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):
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:
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.
Found while implementing #6733 (the dead
docs/adr/0001-…link inARCHITECTURE.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 isARCHITECTURE.md's own outbound links. No overlap, noBlocked-by:.The fact
Measured at
origin/main659526212, with #6733's fix applied (so the ADR-0001 entry is already gone). A census of every relative Markdown link inARCHITECTURE.md: 12 links, 1 resolved. After #6733 it is 12 links, 2 resolved — the remaining 10 are dead:The whole
## Related Documentationsection (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) — nointroduction/dir; two candidates exist,content/docs/concepts/architecture.mdxandcontent/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 undercontent/.docs/METADATA_FLOW.md,./QUICK-REFERENCE.md,./PACKAGE-DEPENDENCIES.md— absent../apps/studio/ROADMAP.md—apps/now contains onlydocs/; 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'sapps/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 atpackages/spec/src/kernel/plugin-capability.zod.ts(system/→kernel/). A one-word fix.ARCHITECTURE.md:271—packages/plugins/plugin-msw/; nothing namedmswexists anywhere in the repo.ARCHITECTURE.md:3cites.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 exactlycontent/**/*.md,content/**/*.mdx,README.md.ARCHITECTURE.mdis not in the globs.scripts/check-adr-links.mjs(docs/adr/is outside theCheck Linksscan surface — ADR cross-links are unverified, and the obvious widening goes red on ADR-0046's illustrative links #6592) resolves relative links underdocs/adr/only — verified green onmainat 531 destinations while all 11 of these were dead.scripts/check-adr-anchors.mjsaudits 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. AddingARCHITECTURE.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 modecheck-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, nopm:queue; severity is the PM's to grade.Provenance
Dev seat session
session_01F8q5J1MQyocgtNspb15fSn, while implementing #6733 (branchclaude/issue-6733-architecture-dead-adr-link). Duplicate search before filing:ARCHITECTURE.md linksover open issues — only #6733 itself and the PM seat issue.