[mrbobbytables]

Follows #1973 (merged); rebased onto main.

What

Each docs/architectures/<id>/index.md now carries its catalog metadata in an architecture: front matter block, and data/architectures/catalog.json is generated from the pages:

• New npm run generate:architectures (scripts/generate-architectures.mjs over scripts/lib/architecture-frontmatter.mjs) writes the catalog from every page's front matter, in the order the importer has always used (organization, then id).
• id is the directory name and assets is the sorted images/ listing; neither is written by hand.
• validate:architectures validates each field on the page it was read from, rejects an unknown key under architecture:, and fails when the committed catalog is behind the pages, naming the generator as the fix. Comparison is of parsed records, so a fix:format refold is not drift.
• data/architectures/records/ is removed. The submission importer writes the page's front matter and regenerates the catalog; architecture-submission.yml runs generate:architectures after the import step.
• All ten pages migrated; the regenerated catalog is semantically identical to the committed one (one architecture's assets are now sorted).
• Docs: CONTRIBUTING data table and rules, submission and doc-authoring skills, copilot instructions, and ADR 0010 recording the decision.

Why

A contributor finds an architecture by its page and edits it; nothing on the page said that three other files described it. The first hand-authored contribution would have shipped a page the catalog did not list, with validator errors naming files the contributor never opened. The page is now the one place to write the metadata.

Remit: a maintainer-requested change to where architecture metadata is authored; no change to what end users see on /architectures.

Verification

• npm run test:unit:coverage:check (src 100% lines and regions)
• npm run check:format, check:spelling, check:markdown, check:duplication, check:lint, check:unused
• npm run test:mutation -- --mutate scripts/lib/architecture-frontmatter.mjs: 95.7%, no survivors
• npm run build:production; architecture detail, interactions, data-fixture and accessibility e2e specs pass
• npm run generate:architectures reports the committed catalog current; validate:architectures and validate:members pass

[netlify]

✅ Deploy Preview for endusers ready!

Name	Link
🔨 Latest commit	b91c501
🔍 Latest deploy log	https://app.netlify.com/projects/endusers/deploys/6ae26080116300db095910a5
😎 Deploy Preview	https://deploy-preview-1975--endusers.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[hivecommons-hive]

b91c501

ℹ️ Sentinel notice — informational; author is trusted (owner), merge is not blocked

Hive flagged this PR (author @mrbobbytables, head b91c5010cd54) because it matches behaviors that can override security controls, escalate privileges or damage the codebase. This is a heuristic, not an accusation — a maintainer should confirm the change is intended before it merges.

• sensitive_path — changes 2 sensitive path(s) (Touches a sensitive path (OWNERS, workflows, policies, hive config, security docs, …))
  • .github/workflows/architecture-submission.yml
  • package.json

Hive did not add the sentinel-alert label because this author is trusted. The finding remains recorded for audit and the dashboard Security tab; set sentinel.trusted_authors_block: true to require the blocking label for trusted authors too.

[hivecommons-hive]

Checked out b91c501 and verified the chain end-to-end; this looks correct to me.

What I verified locally:

• npm run generate:architectures on the PR head reports the committed catalog current (10 records), and validate:architectures passes.
• The regenerated data/architectures/catalog.json is semantically identical to main's except swisscom-cloud-native-telco.assets, which is now sorted (scripts/lib/architecture-frontmatter.mjs:112-116). The only consumer of assets order is src/components/ReferenceArchitectures/index.js:16, which finds the logo by regex, not position — so nothing end users see changes, matching the stated remit.
• The importer (scripts/import-architecture-issue.mjs) now writes the record into the page's front matter via yaml.stringify and regenerates the whole catalog through the same collectArchitectureRecords/serializeCatalog path as the generator, so issue-imported records can't diverge in shape or order. uniqueId now disambiguates against the directory (existsSync(join(docsDir, base))) instead of the catalog, which is consistent with the page being the source of truth.
• node --test on the five touched test files: 149 pass, 0 fail. The last reference to data/architectures/records is the test asserting the directory is no longer created (tests/import-architecture-issue.test.mjs:152).
• The .github/workflows/architecture-submission.yml change is a single additive run: npm run generate:architectures step; no permissions change, and it only runs a script other steps in the same job already exercise transitively.

No findings. Approval itself is a human's call, but I found nothing blocking.

— hive: agent=reviewer backend=copilot model=claude-fable-5 copilot=1.0.88

[hivecommons-hive]

Independently reproduced this branch's verification claims at b91c501 (clean clone of cncf/endusers, npm ci):

• node scripts/generate-architectures.mjs → catalog.json is current (10 records) with a clean git status, so the committed catalog is byte-for-byte what the pages generate.
• node scripts/validate-architectures.mjs → Validated 10 architecture records.
• npm run test:unit:coverage:check → src files 100.00 lines / 100.00 regions, harness files 100.00 / 99.78; gate passes.
• npx eslint over the four changed scripts: clean, no stranded imports after recordsDir was removed.
• npm run validate:all on main for comparison: all validators green, so nothing here masks a pre-existing failure.

Two things I checked specifically because they are the only places this refactor could reach an end user, both fine:

1. The one catalog diff is inert. swisscom-cloud-native-telco's assets are now sorted, moving logo.png from last to first. ArchitectureCard picks its avatar with assets.find((a) => /logo|wordmark/i.test(a)) (src/components/ReferenceArchitectures/index.js:16), and logo.png is the only member of that list matching the pattern either way — so the rendered avatar is unchanged, as the description claims.
2. Catalog ordering is preserved. compareRecords keeps the importer's organization ordering and only adds id as a tie-break, so two architectures from one organization now have a deterministic order instead of an insertion-dependent one.

One observation, not a request for a change: the importer now regenerates the whole catalog, so a pre-existing page with unreadable front matter would fail a future submission import rather than only its own validation. validate:architectures is required on every PR to main, so no such page can land — the coupling is gated, and the thrown message names the offending page.

No defects found. LGTM from the testing side.

---

🐝 Hive Agent: quality | Instance: hosted-available-lke648397-260827-5n31 | SHA: b91c501

— hive: agent=quality backend=copilot model=claude-opus-5 copilot=1.0.88