docs(spec): the agent.tools rejection now says why ADR-0064 binds, so its Proposed status does not read as not-yet-in-force

[os-bill]

Part of #16927

What this is

The author-facing tombstone for the retired agent.tools key rests the rule on ADR-0064. An author who follows that citation lands on a record whose own header reads **Status**: Proposed (2026-06-22) and carries a 🔶 Cloud-owned — superseded in part by cloud ADR-0025 (2026-06-25) callout. Nothing on the record tells them the rule still binds — the metadata invites the weaker reading.

⛔ Nothing here re-opens the retirement. agent.tools stays retired, the rejection stays correct, the accept set is untouched.

• Clause-②: no

The card's route 1 is falsified — the citation is NOT retargeted

The card offered "retarget the author-facing citations to ADR-0109". Reading all three records on origin/main@88a933088e says no:

ADR	status line, verbatim	verdict
ADR-0064	**Status**: Proposed (2026-06-22) — cloud-owned (2026-07-16 audit): the only framework dependency (\skill.surface`) exists; 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.`	stays the cited authority
ADR-0109	**Status**: **Accepted — implemented (Phase 1)** (2026-07-28; revised same day before acceptance — see Revision note).	⛔ not a replacement
ADR-0106	**Status**: Accepted (2026-07-27; implemented 2026-08-08 — #3682)	unrelated, as the card said

The deciding measurement: ADR-0109 names agent.tools zero times (grep -c 'agent\.tools' docs/adr/0109-… → 0; lit control: the same grep over docs/adr/0064-… → 1). ADR-0109's own **Builds on** line attributes the invariant back to ADR-0064 — "(an agent's tools are its skills' tools)" — and ADR-0064's title is that invariant, with Decision §1 stating tools(agent) = ⋃ { skill.tools | skill ∈ agent.skills ∧ skill.surface ∈ {agent.surface, 'both'} }.

⇒ Retargeting would send an author to a record that does not contain the rule they broke. This matches the triage ruling on the card, which reached the same conclusion independently.

What actually changed

One clarifying clause in the tombstone, splitting the two halves the status line conflates: the Proposed / cloud-owned marking scopes the runtime half (tool resolution, which lives in cloud service-ai), while the authoring half is in force in this repo, and ADR-0109 (Accepted — implemented) is the in-repo record carrying it.

The standardised os migrate meta --from 16 sentence remains the closing sentence of the prescription, per the maintainer ruling in shared/retired-key.ts.

content/docs/references/ai/agent.mdx is AUTO-GENERATED from that same source and was regenerated with pnpm --filter @objectstack/spec gen:docs; check:generated and check:docs are green.

Scope held

⛔ No behaviour, no schema, no guidance mechanism, no accept set. ⛔ content/docs/releases/ untouched (measured: the message text appears there 0 times; lit control agent.tools → 6 hits). ⛔ No repeater/row-schema file touched.

ADR-0064's own record was deliberately NOT edited. A clarifying note on the record itself would reach all 32 citing files at once, but docs/adr/** is a governed surface (PD #14) and the record is cloud-owned. Triage placed the landing face in packages/spec; the maintainer may prefer the record-side note instead, and that option is left open rather than taken.

Census — citations of ADR-0064

Tracked files only (git grep, no built dist/ in tree — verified git ls-files | grep -cE '(^|/)dist/' → 0):

• 74 occurrences across 32 files (git grep -oIE 'ADR-0064|0064-tool-scoping-to-agent').
• The card's "12 files" reading is stale: it was taken at 9a89a0040d and scoped to three directories only.
• Author-facing sites (strings an author receives): the tombstone (this PR), the migration summary in conversions/registry.ts, and three os explain catalog rows in packages/cli. Only the tombstone is changed here; the other two are noted, not filed.
• Also drifted since the card: the release page it cites as content/docs/releases/v17.mdx:719 is now content/docs/releases/v17/17-0.mdx.

Verification

• pnpm --filter @objectstack/spec test → VERDICT command-exit 0, 473 files / 13432 tests passed.

• pnpm --filter @objectstack/spec typecheck → VERDICT command-exit 0.

• pnpm --filter @objectstack/spec build → VERDICT command-exit 0.

• Gate families derived mechanically (node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack, not a hand-written list) and reconciled with --ran carrying each recorded exit code, all at 1a55b9dc0b:

  100 derived famil(ies) accounted for — 98 run, 2 NOT-MEASURED (2 DERIVED from a recorded exit 3), 0 UNRUN

  Four families first refused their prerequisite and were converted to real readings after building the @objectstack/lint, @objectstack/formula and @objectstack/client-react closures (check:doc-formula-expressions, check:doc-security-posture, check:docs-transcript-drift, check:skill-examples — all then exit 0). The remaining two, check:dual-build-cjs-loads and check:lean-entry-closure, need a repo-wide build of 79+ packages and stay NOT MEASURED — a self-declared PREREQUISITE NOT MET, neither a pass nor a finding. CI runs them.
  Notably green and directly load-bearing here: check:generated, check:docs (the regenerated page is in sync) and check:authorable-surface (the accept set did not move).

• Dependency closure (①) is empty: @objectstack/spec declares no workspace: dependencies.

Changeset

skip-changeset would be wrong here, measured rather than assumed. @objectstack/spec is published and its files[] ships both dist and src/**/*.zod.ts — the edited file itself. After pnpm --filter @objectstack/spec build, the new clause was found in 18 dist files, 6 json-schema files and the shipped src/ai/agent.zod.ts (positive control, a pre-existing sentence from the same message: 38 / 130 / 1). Published bytes move, so the change is graded patch in .changeset/16927-agent-tools-retirement-citation.md.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 1 documentable anchor(s).

2 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/ai/agents.mdx (via AgentSchema (symbol, a top-level const))
• content/docs/getting-started/quick-reference.mdx (via AgentSchema (symbol, a top-level const))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v13.mdx (via AgentSchema (symbol, a top-level const))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• the SDK route bridge reached 60 of 215 client-bound route-ledger rows — the other 155 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 155: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 100 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 135 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 88a933088e93067b4df4b20380ab9a1ceed2ed17 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 89e151c1f7465c5ffaf2d25c1d9658d58572e0a6 — the merge of head 1a55b9dc0bc17f2392c9127dcfc110c21b1b6677 into base 88a933088e93067b4df4b20380ab9a1ceed2ed17, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 89e151c1f7465c5ffaf2d25c1d9658d58572e0a6 && git checkout 89e151c1f7465c5ffaf2d25c1d9658d58572e0a6
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 88a933088e93067b4df4b20380ab9a1ceed2ed17 1a55b9dc0bc17f2392c9127dcfc110c21b1b6677 && git checkout -B drift-repro 88a933088e93067b4df4b20380ab9a1ceed2ed17 && git merge --no-ff 1a55b9dc0bc17f2392c9127dcfc110c21b1b6677

node scripts/docs-audit/affected-docs.mjs --json 88a933088e93067b4df4b20380ab9a1ceed2ed17

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 88a933088e93067b4df4b20380ab9a1ceed2ed17 → pass the list as
args.docs, on the commit named under Which tree this was computed on.