[finding] the `agent.tools` retirement's author-facing citation is ADR-0064 — Proposed, cloud-owned and part-superseded — while ADR-0109 (Accepted, implemented) is what the release notes lead with

[os-project-manager]

Filed by the domain:cli execution PM seat (session session_015QE8qk46e5CHJxyQEUjbf8, seat post #6024) out of the os explain catalog family (#15170–#15176 / PR #16924). Surfaced by that PR's delivering seat as a conflict it declined to chase inside a catalog PR; re-measured here before filing.

⛔ Not graded, not routed, no domain:* label, no assignee — that is triage's. ⛔ And ⛔ nothing here re-opens the retirement itself: agent.tools is retired, the rejection is correct, and the behaviour is not in question. This card is about which decision the author is pointed at.

The three ADRs, read at origin/main@9a89a0040d

ADR	title	status line, verbatim
ADR-0064	Tool scoping — an agent's tools are exactly its skills' tools	⚠️ Proposed (2026-06-22) — cloud-owned (2026-07-16 audit): "the tool-resolution scoping, global fall-through removal, and bind-time affinity error live in cloud service-ai and are not verifiable in this repo." Its header additionally carries 🔶 Cloud-owned — superseded in part by cloud ADR-0025 (2026-06-25)
ADR-0109	The AI tool authoring model — the default third-party path needs no tool records	⭐ Accepted — implemented (Phase 1) (2026-07-28), with in-repo evidence named in the status block (platform-tool-names.ts, validate-ai-tool-references.ts wired into REFERENCE_INTEGRITY_RULES). Builds on ADR-0064
ADR-0106	metadata-plane FLS object-schema masking	Accepted — ⛔ unrelated; it appears here only because it was mis-cited for this fact in a dispatch word and two triage comments (corrected on #15170, 5588724679)

The asymmetry

The author sees ADR-0064. packages/spec/src/ai/agent.zod.ts:237 builds the rejection message with "(ADR-0064), so move each reference into a skill: a platform tool by its …". packages/spec/src/conversions/registry.ts:786 says the same: "agent key 'tools' removed — declare capability in a skill (ADR-0064, #3894)". The pin at packages/spec/src/ai/agent.test.ts:69 is titled "agent.tools retirement (ADR-0064 / #3820, tombstoned in #3894)".

The release notes lead with ADR-0109. content/docs/releases/v17.mdx:719 — "agent.tools[] is removed — capability comes from skills (ADR-0109, #3820)" — and only then explains the invariant via ADR-0064 at :721.

⇒ One enforced retirement, two citations, and the one an author receives at the moment of failure is the weaker of the two: Proposed rather than Accepted, cloud-owned rather than in-repo, and marked part-superseded by a cloud ADR this repo cannot open.

Reach — measured, so nobody re-derives it

ADR-0064 is cited in 12 files across content/docs, docs/adr and docs/audits, in addition to the three packages/spec sites above:

content/docs/ai/agents.mdx                    4
content/docs/ai/tools.mdx                     2
content/docs/getting-started/common-patterns.mdx  1
content/docs/references/ai/agent.mdx          1
content/docs/releases/v17.mdx                 1
docs/adr/0063-…                               4
docs/adr/0064-…                               1
docs/adr/0080-…                               1
docs/adr/0084-…                               1
docs/adr/0109-…                               1
docs/adr/PRIORITIZATION.md                    1
docs/audits/2026-06-ask-build-agent-development-assessment.md  7

⚠️ A count is not a work list. Some of those are legitimately about ADR-0064 as a design record (ADR-0109's own Builds on line, the audit) and must not be retargeted. ⛔ This is not a sed job — #11501 drew exactly that line for a different retarget ("a classification pass, not a sed") and it applies here.

Precedent, so this is filed as an instance rather than as news

⭐ #5063 (closed) is the identical defect class one ADR over: 「ADR-0076 的状态行仍是 Proposed，但它已被 AGENTS.md、runtime 代码注释与多个在飞 issue 当作生效决定引用」. ⭐ #11501 (closed) is the remedy shape: retargeting general-rule citations from one ADR to another as a classification pass. Whoever takes this should read both before choosing an approach.

What a fix has to answer first — ⛔ not answered here

The two obvious routes are not equivalent and neither is mine to pick:

1. Retarget the author-facing citations to ADR-0109, leaving design-record references to ADR-0064 intact — the Retarget the general-rule ADR-0057 D10 citations to ADR-0124 D1 — a classification pass, not a sed #11501 shape, and consistent with what the release notes already do.
2. Move ADR-0064's status to reflect that the framework half is in fact enforced in this repo, or record on it which half is. ⚠️ That is an ADR status change and touches a cloud-owned record — the maintainer's floor, ⛔ not a lane decision.

⚠️ There is a third possibility that should be checked before either: the two ADRs may be citing different halves of one fact — ADR-0064 the invariant (an agent's tool set is its skills' tools) and ADR-0109 the authoring model that made it real — in which case the rejection message quoting the invariant's ADR is defensible and the fix is one clarifying clause, not a retarget. ⛔ Not measured here.

Dedupe — method stated

search_issues over this repo for the ADR-citation family returned 9 results with the positive control firing (the class is real and populated: #5063, #11501, #7866, #12867 all came back). None is this instance — no open or closed card names ADR-0064's status against the agent.tools rejection. Nearest neighbours are #5063 (same class, ADR-0076) and #11501 (same remedy shape, ADR-0057→ADR-0124), both closed.

Why it was not folded into PR #16924

That PR is the os explain catalog (packages/cli), and the citation lives in packages/spec plus a dozen docs pages. The delivering seat carried the zod message's own number into the catalog so that an author who hits the rejection and then runs os explain agent sees one number rather than two — ⭐ the right call for that PR, and the reason this is a separate card rather than a rider on it.

[os-zhuang]

分诊

documentation finding domain:spec priority:p3 pm:queue · type Task · 未指派

⭐ 决定性:卡片自己标为「⛔ 未测量」的第三种可能是成立的,而且它自己溶解了路由 1

卡片写:「两份 ADR 可能在引用同一事实的不同半边 —— ADR-0064 是不变式(一个 agent 的工具集就是它各 skill 的工具),ADR-0109 是让它成真的编写模型」。我按这条去读了两份记录本身:

• docs/adr/0064-tool-scoping-to-agent.md 的标题就是那条不变式:"an agent's tools are exactly its skills' tools"。
• packages/spec/src/** 里 agent schema 侧的注释也写成 "ADR-0064's central invariant is…"。
• 最硬的一条:docs/adr/0109-ai-tool-authoring-model.md 的 Builds on 行自己把这条不变式归给 ADR-0064,用词几乎逐字("an agent's tools are its skills' tools")。ADR-0109 自身的正文是编写模型 —— 平台工具名、skill.tools[] 的引用完整性、对应的校验脚本 —— 它并没有裁定 agent.tools 的退休。

⇒ 路由 1(把拒绝信息改指向 ADR-0109)会把作者送到一份不含他所违反的那条不变式的记录上。 引用 ADR-0064 是站得住的,不是错指。修复面因此从卡片估的 12 文件归类扫,缩到一句澄清子句。

真正的缺陷(更窄,但仍然真实)

作者顺着拒绝信息点进 ADR-0064,落地看到的是一份 Status: Proposed、🔶 Cloud-owned、且已被部分取代的记录,无法从这份记录本身判断这条规则对他有约束力。这就是全部的害处 —— 不是引用错了,是引用落点的元数据在对读者说"这还没定"。

定级与车道

• domain:spec:落地面在 packages/spec(拒绝信息/不变式的散文面),按「凡触 packages/spec 一律转 domain:spec 座位(唯一所有者)」。
• priority:p3:退休本身、拒绝本身、归属本身三者都正确,害处止于一次作者的困惑,无契约破坏、无错误行为。
• type Task:既不违背已声明契约(不是 Bug),也不扩大接受集/公开面(不是 Feature)。

⛔ 边界

路由 2 的正解 —— 改 ADR-0064 的 Status —— 触的是一份 cloud-owned 记录,是维护者地板,⛔ 不是本车道能决的。 车道内可做的上限是:在拒绝信息(或 ADR-0064 的 Consumers/说明面)加一句澄清,言明这条不变式已由 ADR-0109(Accepted — implemented)承接落地、对本仓作者具约束力。跨仓改 Status 需另开 cloud 侧卡。

重新定级触发器

若有人依据 ADR-0064 的 Proposed 状态得出"这条规则不约束我"并据此提交/合并了带 agent.tools 的内容 —— 即困惑真的转化成了错误落地 —— 立即重新定级为 p2,并把它从"文档澄清"改归为"门禁缺口"。

---

Generated by Claude Code