[finding] 10 more dead relative links + 2 stale path references in ARCHITECTURE.md — nothing gates that file's links #6867

Found while implementing #6733 (the dead docs/adr/0001-… link in ARCHITECTURE.md). Out of that card's scope — its dispatch scopes the diff to the ADR-0001 pointer — so filed per Prime Directive #10, unassigned.

Distinct from #6726: that card is about links written inside docs/adr/ pointing at the source tree. This is ARCHITECTURE.md's own outbound links. No overlap, no Blocked-by:.

The fact

Measured at origin/main 659526212, with #6733's fix applied (so the ADR-0001 entry is already gone). A census of every relative Markdown link in ARCHITECTURE.md: 12 links, 1 resolved. After #6733 it is 12 links, 2 resolved — the remaining 10 are dead:

L582  [content/docs/introduction/architecture.mdx](content/docs/introduction/architecture.mdx)
L679  [Metadata Flow Documentation](docs/METADATA_FLOW.md)
L716  [Quick Reference Guide](./QUICK-REFERENCE.md)
L717  [Package Dependency Graph](./PACKAGE-DEPENDENCIES.md)
L719  [Studio Roadmap](./apps/studio/ROADMAP.md)
L720  [MicroKernel Architecture Guide](./content/docs/developers/micro-kernel.mdx)
L721  [Plugin Ecosystem Architecture](./content/docs/developers/plugin-ecosystem.mdx)
L722  [Writing Plugins](./content/docs/developers/writing-plugins.mdx)
L723  [Three-Layer Stack](./content/docs/introduction/architecture.mdx)
L724  [Design Principles](./content/docs/introduction/design-principles.mdx)

The whole ## Related Documentation section (L716–L724) is dead except ./ROADMAP.md.

Triage per link — three dispositions, not one sweep

Moved, repointable but ambiguous:

• content/docs/introduction/architecture.mdx (cited twice, L582 + L723) — no introduction/ dir; two candidates exist, content/docs/concepts/architecture.mdx and content/docs/kernel/architecture.mdx. Which one "Three-Layer Stack" meant is an authoring call.
• content/docs/introduction/design-principles.mdx → content/docs/concepts/design-principles.mdx. Unambiguous single candidate.

Target left the tree entirely (needs a decision, not a repoint):

• content/docs/developers/{micro-kernel,plugin-ecosystem,writing-plugins}.mdx — no file of any of those names anywhere under content/.
• docs/METADATA_FLOW.md, ./QUICK-REFERENCE.md, ./PACKAGE-DEPENDENCIES.md — absent.
• ./apps/studio/ROADMAP.md — apps/ now contains only docs/; Studio lives in a sibling repo, so no relative path from here can reach it (same shape as [finding] 8 dead ADR -> source-tree links in ADR-0004 and ADR-0020 — targets left this repository, and they are what forces #6592's gate to ship with a baseline #6726's apps/studio/** entries).

Bare (unlinked) path references in prose that also no longer resolve:

• ARCHITECTURE.md:406 — packages/spec/src/system/plugin-capability.zod.ts; the file is real but at packages/spec/src/kernel/plugin-capability.zod.ts (system/ → kernel/). A one-word fix.
• ARCHITECTURE.md:271 — packages/plugins/plugin-msw/; nothing named msw exists anywhere in the repo.
• (Not a defect: ARCHITECTURE.md:3 cites .changeset/v5-project-to-environment-rename.md, which is legitimately consumed at release time.)

Why it survived — the gap is real and named

Nothing checks this file:

• .github/workflows/check-links.yml (lychee, advisory lane) runs over exactly content/**/*.md, content/**/*.mdx, README.md. ARCHITECTURE.md is not in the globs.
• scripts/check-adr-links.mjs (docs/adr/ is outside the Check Links scan surface — ADR cross-links are unverified, and the obvious widening goes red on ADR-0046's illustrative links #6592) resolves relative links under docs/adr/ only — verified green on main at 531 destinations while all 11 of these were dead.
• scripts/check-adr-anchors.mjs audits ADR numbers, not link targets, so a cited number can resolve while its link 404s — exactly the ADR-0001 case ARCHITECTURE.md links to docs/adr/0001-metadata-service-architecture.md, deleted 2026-02-11 — the link 404s #6733 fixed.

So ARCHITECTURE.md — the repo's most prominent architecture entry point, and the file PD #13 sends a new agent to first — has had zero link coverage throughout. Adding ARCHITECTURE.md (or root *.md) to the lychee globs would surface all 10 at once, but that lane is advisory-first by design (#6028) and turning it red on day one is the failure mode check-adr-links's header explicitly warns against; whoever picks this up should fix the links first, then extend the glob.

Severity

Observation-class as filed: no user path, no runtime behaviour, no product contract. The cost is agent and contributor navigation — the same cost #6726 records, on the file with the widest readership. Labelled finding, no pm:queue; severity is the PM's to grade.

Provenance

Dev seat session session_01F8q5J1MQyocgtNspb15fSn, while implementing #6733 (branch claude/issue-6733-architecture-dead-adr-link). Duplicate search before filing: ARCHITECTURE.md links over open issues — only #6733 itself and the PM seat issue.