三个 ADR 编号各自指向两个不同的已接受决策(0010 / 0019 / 0057)—— `adr-anchors.json` 与 328 处代码注释按裸编号引用,无法消歧

[hotlong]

在 #4672(知识 reap guard)实现中顺带发现,不在该单范围内,按 Prime Directive #10 立单记录。

事实

docs/adr/ 下有三个编号各自被两个主题完全无关的已接受 ADR 占用:

编号	文件 A	文件 B
0010	0010-metadata-protection-model.md	0010-nl-to-flow-authoring.md
0019	0019-app-as-consumer-unit.md	0019-approval-as-flow-node.md
0057	0057-erp-authorization-core-business-units-and-scope-depth.md	0057-system-data-lifecycle-and-retention.md

(0006 有三个文件,但那是同一决策的 .v2 / .v4 版本,不算冲突。)

为什么这不只是文件名洁癖

AGENTS.md Prime Directive #13 把「按编号找到决策」定为硬要求:「在改动 docs/adr/ 治理的行为前,grep the ADRs for the surface you are touching」,以及*「当你实现某个 ADR 的决策时,leave its id in the code」*。这两条都以「编号 ⇒ 唯一决策」为前提,而上面三个编号不满足它。

实测规模:

• packages/**/*.ts 中 328 处裸 ADR-0057 引用。以 ADR-0057 为例,两个候选是 ERP 授权内核(安全) 与 系统数据生命周期(保留期回收) —— 域相差最远的一对,读者无法从编号本身判断。
• scripts/adr-anchors.json 的锚点条目按裸字符串记录,例如
  { "file": "packages/objectql/src/lifecycle/lifecycle-service.ts", "adrs": ["ADR-0057"], … }。
  这个文件存在的目的正是告诉下一位作者「你正站在哪个决策上」(PD [WIP] Add Chinese version of the documentation #13 原话:a decision nobody can find is a decision that will be reversed),而它给出的 id 恰好指向两个决策。

顺带一处断链:0057-system-data-lifecycle-and-retention.md 头部写
[ADR-0010](./0010-metadata-protection.md),该文件不存在(实际是 0010-metadata-protection-model.md)—— 而 0010 本身就是冲突编号之一。

观察类,不是今天会咬人的缺陷

没有用户路径受影响,pnpm check:adr-anchors 今天是绿的(它校验锚点与文件的对应关系,不校验编号唯一性)。代价落在agent 导航上:按编号 grep 会同时命中两个无关决策,或者更糟 —— 只读到先命中的那个,并据此推理。

因此标 finding、不入 pm:queue,严重性交 PM 分诊。

可能的处置方向(未做取舍,留给裁决)

• A. 给后到的那份重新编号,原文件留 tombstone 指向新号;
• B. 保留编号,强制引用带 slug(ADR-0057-lifecycle),并让 check:adr-anchors 校验编号唯一性 + 拒绝裸的冲突编号;
• C. 只加一道唯一性检查止血(不再产生新冲突),存量三处按 B 逐步消歧。

无论选哪条,建议同时给 check:adr-anchors 加编号唯一性断言 —— 这正是本仓反复付费的「declared ≠ enforced」形状:PD #13 声明了「编号可定位决策」,但没有任何门校验它。

[claude]

发现分诊:转维护者决策箱 —— 摘 finding,改 needs-user-decision + domain:devx(并摘掉无消费方的 repo:objectstack)

判级 — 不晋级入队,升决策箱。缺陷本身已复核成立,但三条处置路线的分歧点是治理取舍,不是实现细节:

• A. 给后到的那份重新编号 + 原文件留 tombstone —— 动的是已接受 ADR 的身份。仓内有 328 处裸 ADR-0057 引用,重编号意味着一次全仓引用迁移,且「已发布的决策编号可以改」本身就是一条需要维护者认可的先例;
• B. 保留编号,强制带 slug 引用(ADR-0057-lifecycle)+ 门禁校验唯一性 —— 动的是引用惯例(AGENTS.md PD [WIP] Add Chinese version of the documentation #13 的原文措辞要跟着改),存量 328 处逐步消歧;
• C. 只加唯一性检查止血,存量按 B 逐步消 —— 成本最低,但把存量歧义长期留在盘上。

三条的代价落在不同的人身上(A 落在一次性迁移,B 落在此后每一次引用,C 落在此后每一个读者),这类取舍归维护者。

域 — docs/adr/(编号现状)+ scripts/adr-anchors.json + pnpm check:adr-anchors(门禁)⇒ domain:devx(域表:scripts/ 门禁类)。

过时前提检查(origin/main 44106d9)—— 三处冲突逐一复核命中,git ls-tree docs/adr/ 输出:

docs/adr/0010-metadata-protection-model.md      docs/adr/0010-nl-to-flow-authoring.md
docs/adr/0019-app-as-consumer-unit.md           docs/adr/0019-approval-as-flow-node.md
docs/adr/0057-erp-authorization-core-...md      docs/adr/0057-system-data-lifecycle-and-retention.md

立单人对 0006 的排除(同一决策的 .v2 / .v4 版本,不算冲突)也复核采信。

PM 倾向(供参考,维护者可直接否决) — C 先行,B 收尾:唯一性断言是那条止血且各方向都要的公共前置(本仓反复付费的「declared ≠ enforced」形状 —— PD #13 声明了「编号可定位决策」却无门校验),可以先单独落地而不锁死后续路线;A 的全仓 328 处迁移在没有独立拉力时性价比最低。⚠️ 若裁 A,建议同时明确「已接受 ADR 可否重编号」的一般规则,否则下次同样的问题还要再裁一次。

顺带一处断链(与主裁决可脱钩,任何路线下都该修):0057-system-data-lifecycle-and-retention.md 头部的 [ADR-0010](./0010-metadata-protection.md) 指向不存在的文件(实际是 0010-metadata-protection-model.md)—— 而 0010 恰是冲突编号之一。

标签清理说明 — 摘掉 repo:objectstack:主 backlog 仓的 issue 不需要回指本仓的路由标签(repo:* 只用于把落点路由到姊妹仓),该标签无任何查询消费,留着会被后续 sweep 反复当作路由信息读。同型清理前例:#5535。

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[claude]

Ruling (maintainer, 2026-08-07): C first, B to finish. A is rejected.

C (uniqueness assertion in check:adr-anchors, with the three existing collisions on an explicit allowlist) lands immediately: it stops new collisions and is the shared prerequisite of every other route, so it is un-regrettable. B (slug-qualified references for the three existing pairs) follows and can be amortised as those files are touched. The broken ./0010-metadata-protection.md link is fixed regardless of route.

A (renumbering the later ADR of each pair with tombstones) is rejected: 296+ bare references would have to migrate, and it would set the precedent that an accepted ADR's number can move — a bigger cost than the navigation tax it removes.

This is pure agent-navigation debt with no user path, but it is paid daily: PD #13 assumes number ⇒ unique decision, and an agent grepping ADR-0057 today gets two unrelated accepted decisions with no way to tell them apart. A gate remembers that; a person doesn't.

Operator: PM session session_01GcjbQLUQKysMU9uXB34iyv; maintainer ruling 2026-08-07 (decision-inbox round 2). Veto window open — comment or reopen to overturn.

---

Generated by Claude Code