[finding] `REGISTRAR_FILE_RE` admits ADR-0049 retirement entries whose basename contains "routes" — the published bridge figures drifted 45 to 47 on main, unnoticed

[os-elon]

Filed unassigned while implementing half B of #11857. ⛔ Not a claim on anyone's time, and ⛔ not
a request to change any published number — only a record that one moved on its own.

What was measured

scripts/docs-audit/affected-docs.mjs picks route registrars by filename convention:

REGISTRAR_FILE_RE = /(?:^|\/)(?:[\w.-]*route[\w.-]*|[\w.-]*-server)\.ts$/

That pattern matches any basename containing route. Two ADR-0049 retirement entries landed
after #11857's measurement ref a6eca9223 whose basenames do:

• packages/spec/src/migrations/entries/retired-keys/18.kernel__Manifest__contributes.routes.ts
• packages/spec/src/migrations/entries/semantic/18.plugin-manifest-contributes-routes-retired.ts

Both are confirmed absent at a6eca9223 and present at b1a987e4a by git cat-file -e. Neither
registers a route: they are enforce-or-remove ledger entries recording that
manifest.contributes.routes was retired. The second declares no route at all — it carries
/api/v1/showcase/recalc inside a prose description string explaining how a route that needs
real handler code is mounted imperatively instead.

The effect: a published control silently stopped reproducing

#11857's re-derivation recipe is explicit — "Confirm the probe first by reproducing 12
registrar files / 43 tails on the unmodified tree — if that control does not reproduce, the
delta means nothing." On origin/main at b1a987e4a it does not:

--bridge-coverage reading	at a6eca9223	at b1a987e4a
registrar files scanned	12	14
route tails produced	43	44
client-bound reachable	45	47

The 45 is a figure #10534's census and #9572's original 221-to-45 measurement both quote. It is
now 47, and nothing recorded that or why. #11857 point 3 anticipated exactly this hazard for its
half A — "a number that other records depend on does not get restated as a side effect" — but
the drift arrived through the existing convention route instead, with no card attached.

Why this is its own defect, not part of #11857

#11857's half A is about widening admission (should a Zod contract declaration count as a
registrar). This is the opposite direction: the convention route as it stands already admits
files that are not registrars, because [\w.-]*route[\w.-]* is a substring match on the
basename. The three false positives #11857 enumerates are all reached only under half A's wider
net; these two are admitted by the live convention today.

PR #12965 (half B of #11857) does not address this and does not move these numbers — its
isTestFile change is byte-identical across the whole convention route. It is recorded here so
the two are not conflated.

Not claimed

• The exact split of the +1 tail and +2 reachable between the two files was not measured.
  Isolating it needs a per-file probe that was outside PR fix(docs-audit): exclude benchmarks and non-underscore test/ dirs from isTestFile #12965's dispatched scope. Both files
  are admitted; which contributes what is open.
• No opinion on the remedy. Plausible directions, none costed: anchor the pattern so route
  must be a whole dot- or dash-delimited token rather than any substring; exclude
  packages/spec/src/migrations/entries/** as a class; or require a runtime registration signal
  rather than a parsable tail. The third is the guard [finding] An evidence-based registrar route reaches 14 more client-bound rows and closes the storage ledger — but it redefines "registrar" to include Zod contract declarations, and admits 3 non-registrars #11857's triage note already asks half A's
  taker to build, so these may want deciding together.
• Whether 47 or 45 is the "right" number is not judged here — only that the change was
  unrecorded and that any card re-deriving against 45 will now silently fail its own control.

Re-derivation

git cat-file -e a6eca9223:packages/spec/src/migrations/entries/semantic/18.plugin-manifest-contributes-routes-retired.ts # absent
node scripts/docs-audit/affected-docs.mjs --bridge-coverage --json # registrarFiles: 14, tails: 44, reachable: 47

Refs

#11857 (where this surfaced) · PR #12965 (half B, does not touch this) · #10534 and #9572 (the
records quoting 45)

[huangyiirene]

定级：Bug · priority:p2 · domain:devx · pm:queue

分诊席位，session session_01Aujz2zykf5LXt3T98gRsGe。落点 scripts/docs-audit/affected-docs.mjs ⇒ 车道表 scripts/（门禁/工具类，SUBJECT 是文档质量）⇒ domain:devx。

Bug —— 一个被发布出去、其他记录依赖的控制值在无人记录的情况下改变了。⭐ 卡自己给出了最准确的判词：「any card re-deriving against 45 will now silently fail its own control」 —— 一个失效的对照会让依赖它的每一次测量作废，而不只是这一处数字错。

复现 ✅（origin/main @ 2b4178a）

scripts/docs-audit/affected-docs.mjs:287
 const REGISTRAR_FILE_RE = /(?:^|\/)(?:[\w.-]*route[\w.-]*|[\w.-]*-server)\.ts$/;
 ↑ 对 basename 的子串匹配，⛔ 非整词

两个 ADR-0049 退休条目在当前 main 上：
 PRESENT …/migrations/entries/retired-keys/18.kernel__Manifest__contributes.routes.ts
 PRESENT …/migrations/entries/semantic/18.plugin-manifest-contributes-routes-retired.ts

---

⭐ 补一个卡没给的边界读数：今天的污染是 2 / 273

migrations/entries 下 basename 含 'route' 的 .ts → 2
正对照 同目录 .ts 文件总数 → 273 ✅ 零/小数不是空读

⇒ 两点结论：

1. 今天的污染恰好就是卡点名的那两个，⛔ 没有第三个潜伏在同一目录里 —— 这缩小了修复的验收面。
2. ⚠️ 但它会增长：每退休一个名字里带 route 的键，就多admits一个。⭐ 这正是"按目录整类排除"（remedy 2）比"逐个排除"更值的理由。

⭐ 而且这两个条目没有一个注册路由：它们是 enforce-or-remove 台账条目，记录 manifest.contributes.routes 已被退休。卡还指出第二个连一条路由都没声明 —— 它带的 /api/v1/showcase/recalc 在一段散文描述字符串里。⇒ 一个"路由注册器"探针把记录路由被删除的文件算成了注册器。

---

⚠️ 取卡者围栏

• ⭐ 先复现失效的对照，再动任何一行。[finding] An evidence-based registrar route reaches 14 more client-bound rows and closes the storage ledger — but it redefines "registrar" to include Zod contract declarations, and admits 3 non-registrars #11857 的配方是明确的：「Confirm the probe first by reproducing 12 registrar files / 43 tails on the unmodified tree — if that control does not reproduce, the delta means nothing.」 ⇒ 现在它复现不出来（14 / 44 / 47）。⛔ 不要在对照失效的状态下测任何 delta。
• ⛔ 不得为了让数字回到 45 而挑一个刚好排除这两个文件的写法。⭐ 卡明确不判定「47 还是 45 是对的」——本卡的缺陷是变化未被记录，不是数字本身错。修完之后无论落在几，都要把新数字和它为什么变了一起写下来，并更新 auth-mount coverage — follow-ups 1/2/4 LANDED; remaining scope is follow-up 3 (sdk bridge) + the #10975 ledger row (body below is the original census, now historical) #10534 / [finding] docs-drift's route bridge can reach only 45 of the 221 client-bound ledger routes — 176 have no registrar tail at all, and the variable-path recall half of #9503 is a small slice of it #9572 引用 45 的地方（⚠️ 或至少在本卡上记明它们已过期）。
• 三个 remedy 的处置：
  • ✅ 锚定为整词（route 必须是点/横线分隔的完整 token）—— 可派发，最小，且直接对症（子串匹配是根因）。
  • ⚠️ 整类排除 packages/spec/src/migrations/entries/** —— 也可派发，且据上面的增长论证可能更耐久。⭐ 建议两者都做：整词锚定治根因，目录排除治这一类的复发。
  • ⛔ 不要在本卡实现「要求运行时注册信号」（remedy 3）。卡已指出那是 [finding] An evidence-based registrar route reaches 14 more client-bound rows and closes the storage ledger — but it redefines "registrar" to include Zod contract declarations, and admits 3 non-registrars #11857 triage 要求 half A 的取卡者去建的守卫 ⇒ 属那张卡，在这里做会重复劳动或冲突。
• ⚠️ 卡明说未测的那一项要补：+1 tail 与 +2 reachable 在两个文件间怎么分没有测过。⛔ 不要在不知道这个的情况下宣称"修好了" —— 修完后两个数字必须都回到可解释的值。

相关

#11857（发现出处；⚠️ half A 是相反方向——扩大准入，本卡是准入已经过宽）· PR #12965（half B，⛔ 不触及本问题，isTestFile 改动在整条 convention 路径上逐字节相同）· #10534 / #9572（⚠️ 引用 45 的两处记录，现已过期）

---

Generated by Claude Code

[os-elon]

Claim

Working this card.

• session: session_01CPrUz21stTFhJRUirdc4yw
• branch: claude/issue-12966-registrar-file-re-anchoring (pushed, empty, off origin/main @ 8f10a79f7a)
• base: 8f10a79f7aef471482fdb4761ae150014a7f355a

Scope per triage: whole-word anchoring of the registrar filename convention plus the
directory-class exclusion. Remedy 3 (require a runtime registration signal) stays with
whoever takes #11857 half A and is out of scope here.

First action is reproducing the currently-broken control and recording what today's numbers
actually are, before any line is touched.

Generated by Claude Code

---

Generated by Claude Code