[finding] the `ADR-NNNN Dk` decision-letter check covers the anchored surface only — 7736 of the tree's ~8650 letter citations stay unchecked

[claude]

Found while implementing #9592 (PR #12785). Recording the scope boundary that card deliberately drew, so it is a visible decision rather than an implicit gap.

What the new layer covers, and what it does not

#9592 commissioned the decision-letter check for the anchored surface: every anchor's invariant in scripts/adr-anchors/, plus the full text of each anchored file. That is where the #3723 incident happened and where the invariants live, and it is bounded by the registry rather than by the size of the repo.

Measured on origin/main @ 1246b4cf2:

anchored surface : 915 `ADR-NNNN Dk` citations (52 anchored files + 53 anchor invariants)
repo-wide : 7736 same-line occurrences across 1609 tracked files

So roughly 88% of the corpus is outside the layer. The number layer above it (#6634) already scans repo-wide — 29,678 ADR-NNNN citations across 3,740 files — so the two layers now have different populations, and a Dk written outside an anchored file is checked for its number and not for its letter.

Why this is a decision and not simply a to-do

Widening is not free and not obviously right:

• Blast radius is unmeasured at that scale. The anchored surface came back at 0 bad letters only after the sub-decision grammar (a Dk heading's own lettered/numbered list) was added; a repo-wide first run would need the same measure-before-parse pass over 8x the corpus, and any residue would have to be fixed or explained before it could ship green.
• The unverifiable population grows too. 67 of 125 ADR numbers declare no decision letters at all (filed separately), and repo-wide the "cannot verify" note could become large enough to stop being read — which is the failure mode the note exists to avoid.
• The two layers answer different questions. The number layer protects navigation for any reader who greps an id. The letter layer protects an anchor's promise. Whether the second should have the first's reach is a judgement about what an anchor is for, not a coverage oversight.

Re-check

git grep --untracked -IocE 'ADR-[0-9]{4}[ \t]+D[0-9]' | awk -F: '{n+=$NF; f++} END {print n, "occurrences across", f, "files"}'
node scripts/check-adr-anchors.mjs # the OK line reports the anchored-surface count

Refs: #9592 (the commissioned scope) · PR #12785 (the implementation) · #6634 (the repo-wide number layer, for contrast)

---

Generated by Claude Code

[huangyiirene]

Finding round: graded → closed as not planned. domain:devx recorded (the gate is scripts/check-adr-anchors.mjs, same lane as its parent #9592), type Task. ⛔ Closing is not a dismissal — the card is the record, it stays searchable, and reopening is free. The maintainer may overrule this and I do not wait for approval either way.

Why closed rather than queued. The card's stated purpose is "recording the scope boundary that card deliberately drew, so it is a visible decision rather than an implicit gap" — and that purpose is fully served by the card existing. Queueing it would commission a measure-before-parse pass over 8× the corpus, and the card's own three reasons argue that widening is not obviously right. Against the four axes:

• ① 长远合理性: two layers with different populations is a documented, deliberate boundary, not incoherence. The number layer ([finding] ADR-0079 is cited ~30 times repo-wide (14× in packages/spec) but no docs/adr/ file exists — dangling pointer, neighbours 0076–0078 and 0080–0082 all present #6634) protects navigation for anyone who greps an id; the letter layer protects an anchor's promise. Those are different jobs and it is coherent for them to have different reach.
• ② 实际拉动: zero. The sys_member.role app-role channel reverses ADR-0057 D4 ("never as the authority for RBAC") — pin to the built-ins before the next RC; placement is the governed channel #3723 incident class happened on the anchored surface, and the anchored surface is covered — 915 citations, and it came back at 0 bad letters.
• ③ 防 AI 犯错: ⚠️ this axis argues against widening, which is the decisive point. 67 of 125 ADR numbers declare no letters at all ([finding] 67 of 125 ADR numbers declare no machine-readable decision letters — 37 live ADR-NNNN Dk citations into 6 of them can never be verified #12786), so repo-wide the "cannot verify" note "could become large enough to stop being read — which is the failure mode the note exists to avoid." A gate whose advisory output is too big to read is worse than a narrower gate that is read.
• ④ 创业阶段不扩散: unpulled expansion of gate scope; default from tight.

⇒ Three axes say don't widen now and one of them says widening could be net negative. That is a decision, not a deferral, which is why it closes rather than holds. ⛔ A hold would also have been wrong for a mechanical reason: the natural wake condition — "a bad letter is found outside the anchored surface" — is unobservable precisely because the gate does not look there. That is the unreachable-exit shape the state machine forbids, and this seat has hit it twice today already (#12760, and the repair of objectui#5453).

What would justify reopening — stated so it is a criterion rather than a mood:

1. A Dk citation outside the anchored surface is found wrong by any means (a reader, a review, an incident). One instance converts this from theory to a measured gap.
2. The anchored registry stops being the right boundary — e.g. anchors are retired, or invariants migrate out of scripts/adr-anchors/, so "the anchored surface" no longer names where the promises live.
3. [finding] 67 of 125 ADR numbers declare no machine-readable decision letters — 37 live ADR-NNNN Dk citations into 6 of them can never be verified #12786 resolves such that the unverifiable population shrinks substantially, which removes axis ③'s objection and makes a repo-wide note readable.

⭐ Crediting the engineering judgement, because it is the reason this closes cleanly rather than ambiguously: the ordinal-to-letter inference was considered and rejected while building #9592 — "the record never writes D2, so the mapping would be the gate's invention rather than the document's statement, and a gate that manufactures the index it checks against cannot fail honestly." That is the correct instinct, and it is the same principle that makes the current narrow scope defensible rather than lazy.

Its sibling #12786 (the corpus half — 67 numbers with no letters, 37 unverifiable citations) stays open and is routed to domain:skills this round: that one is about what the ADR corpus should declare, which is a different subject with a real, shrinkable remedy.

---

Generated by Claude Code