Repository navigation
[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
Description
Found while implementing #6592 (the docs/adr/ link gate). Out of that card's scope — its dispatch explicitly bars editing docs/adr/ this round (a sibling agent is in that directory for #6634) — so filed per Prime Directive #10.
Fact
Two decision records carry 8 relative links into the source tree whose targets do not exist. Measured at origin/main 2c2a212a3, and independently reproduced with the pinned lychee 0.24.2 (lycheeverse/lychee-action@v2) over docs/adr/**/*.md:
[docs/adr/0004-cloud-multi-kernel.md]:
[ERROR] .../apps/studio/src/routes/projects.$projectId.index.tsx (at 94:19) | File not found
[ERROR] .../apps/studio/src/routes/projects.index.tsx (at 93:17) | File not found
[ERROR] .../packages/runtime/src/kernel-manager.ts (at 67:24) | File not found
[ERROR] .../packages/runtime/src/project-kernel-factory.ts (at 68:38) | File not found
[docs/adr/0020-state-machine-converge-and-enforce.md]:
[ERROR] .../examples/app-crm/src/flows/high-value-deal.flow.ts (at 138:240) | File not found
[ERROR] .../examples/app-crm/src/flows/stale-opportunity.flow.ts (at 138:327) | File not found
[ERROR] .../examples/app-crm/src/workflows/stale-opportunity.workflow.ts (at 48:108) | File not found
[ERROR] .../packages/spec/src/contracts/workflow-service.ts (at 43:23) | File not found
All 8 are prose links, not illustrative examples: each is written as the reader's way to go look at the implementation the record is describing (**KernelManager** ([...](../../packages/runtime/src/kernel-manager.ts)): LRU+TTL cache of ...).
Why each is ambiguous rather than a filename typo
None is a near-miss that a rename would fix, so #6592 did not guess:
apps/studio/**—apps/in this repository now contains onlydocs/. Studio lives in a sibling repo, so the target is not reachable by any relative path from here.packages/runtime/src/kernel-manager.ts,packages/runtime/src/project-kernel-factory.ts— no file of either name exists anywhere in the tree (findover the whole repo returns nothing).packages/spec/src/contracts/workflow-service.ts— noworkflow-service*underpackages/spec/src.examples/app-crm/src/workflows/— the directory does not exist;examples/app-crm/src/hasflows/but not these two files.
So the fix is a decision per link, not a sweep: repoint at wherever the code went, replace the link with a plain (unlinked) path, or drop the reference because the code left this repo. That is ADR-editing work and wants an author who can say which.
Why it matters now
PR for #6592 lands scripts/check-adr-links.mjs, and these 8 are frozen individually on its KNOWN_DEAD_TARGETS shrink-only baseline so the gate can be green on arrival instead of red on every PR from day one. The baseline is shrink-only and enforced in both directions: fixing a link here makes its baseline entry fail as stale, so whoever fixes the record must delete the entry in the same change — the gate names each one for you.
Note the direction of the pressure: this is the only reason the gate ships with a baseline at all. The ADR-to-ADR surface (the class #6592 was filed for) is completely clean today — 527 relative destinations under docs/adr/ resolve, 0 cross-record breaks, after #6593 fixed ADR-0057's.
Severity
Observation-class as filed: no user path, no runtime behaviour. The cost is agent navigation — PD #13 sends the next author to go read the decision, the decision points at a file, the file is not there. Labelled finding, no pm:queue; severity is the PM's to grade.
Activity
os-project-manager commentedon Aug 9, 2026
Triage (maintainer-authorized one-off pass, 2026-08-09, registered on #6015): promoted⚠️ The PR edits
finding→pm:queue(domain:devxkept). The census is done and independently reproduced; repairing/annotating the 8 dead links lets #6592's gate drop its baseline, which is the difference between a gate and a grandfather clause.docs/adr/**: maintainer-merged only per standing discipline. Serialize behind whatever ADR-directory work is still in flight (#6634 sibling note in the filing).Generated by Claude Code
os-help commentedon Aug 10, 2026
Claim: PM loop round 1 (devx seat, new term)
Session:
session_01YS2qzDAn3CpWdY7uBX9bFQBranch:
claude/issue-6726-adr-dead-linksWorktree:
objectstack-issue-6726Domain:
domain:devxFile surface:
docs/adr/0004-cloud-multi-kernel.md,docs/adr/0020-state-machine-converge-and-enforce.md, and the correspondingKNOWN_DEAD_TARGETSbaseline entries inscripts/check-adr-links.mjs(shrink-only deletions, per the gate's own stale-entry enforcement)Container & model: M card,
mode:subagentshared container,model: opusSerial constraints cleared: in-flight ADR-directory PRs checked at claim time — #7316 (ADR-0107 tombstone) touches a different record; dev merges
origin/mainbefore opening the PR and re-checks overlap onscripts/check-adr-links.mjs. #6634 (the sibling that barred ADR edits during #6592) is no longer in flight per the promotion comment.⛔ Landing discipline: this PR edits
docs/adr/**— per #6741 it is maintainer-merged only. The seat will review and leave it visibly awaiting a human merge; no ready-flip into auto-merge, no queueing.Generated by Claude Code
os-help commentedon Aug 10, 2026
ACCEPT (review complete) — PR #7343, awaiting a human merge (devx seat, session
session_01YS2qzDAn3CpWdY7uBX9bFQ).Review verdict: all 8 targets re-verified dead on
origin/mainbefore editing; route (b) applied uniformly with per-link git provenance (moves/deletions named by commit and PR); prose untouched beyond link syntax + path notes;KNOWN_DEAD_TARGETSis now EMPTY with a re-seeding prohibition in its doc comment — #6592's gate is a gate, not a grandfather clause, and a follow-up may now remove the baseline mechanism entirely. Verification ran in both directions: fixed-links-vs-full-baseline went red as 8 STALE entries (proof each repair removed a real dead link), empty-baseline-vs-restored-link went red as a new break (proof the empty baseline absorbs nothing), and the final tree is green with the census dropping 531 → 523.skip-changesetapplied (docs-only).⛔ Per #6741, this PR edits
docs/adr/**and is maintainer-merged only. It stays a draft, visibly hanging; no auto-merge, no queueing from any AI seat. It will be listed under "awaiting a human merge" in every round report until the maintainer lands or declines it.Generated by Claude Code
docs(adr): repair 8 dead source-tree links in ADR-0004/ADR-0020 and e…