docs(spec): re-anchor the last six dead tracker citations in packages/spec/src to the commits that decided them

[objectstack-fleet]

Part of #20234

Clause-②: no

The next stage of the dead-citation sweep under ruling C+D (record 5749154545 on #19123): the six comment sites the census pointer 5923089344 names, claimed in 5973700515. Each cited a tracker number that answers 404. Each now cites, in form C, the commit on main that decided the rule, and in every case that is the anchor an earlier stage of this card already landed for the same number in a sibling site. Comment text only: no string literal, .describe() text, schema, type, export or test changes.

The rule applied

Form C, as triage's first grade (5856637615) states it and stages 1 to 11 applied it: "the ADR or ruling record, else the commit sha, with a PR number allowed only beside it as a link", and "Each rewritten line says what the cited object decided … Where nothing answers, keep the sentence's reason in words and drop the citation." Stage 10's ACCEPT (5902947213) adds: "Where the number alone carried the meaning, the decision is also said in words." Live numbers stay (stage 9's ACCEPT 5899135835: "its claims forbid removing a lit citation"). A slash group keeps its live numbers and takes the commit beside them, as stage 5 did for #9881/#9972 in component.test.ts (now the #9881 / commit 60e0f900a records).

What changes (line numbers at base 5b5e83f446)

site	dead number	now reads	the same anchor already on main
data/datasource.zod.ts:701	#9040 in #8082/#8336/#9040	#8082/#8336, or the refusal of a credential in mongo's options passthrough (commit 24206416a)	data/datasource-credential-redaction.ts, data/driver/common.zod.ts (stage 3)
data/filter.zod.ts:1067	@see URL of #17590	@see commit e04a0aff2 (the membership reading, landed with the SQL family)	data/filter.zod.ts:979 (stage 3)
data/value-roundtrip-conformance.ts:100	@see URL of #12380	@see commit 4045b954d (the measured boundary set)	the same file's family table and v_json paragraph (stage 3)
ui/component.zod.ts:675	#6276 in #5611/#5775/#6276	#5611 / #5775 / commit 78f0be872	ui/component.zod.ts:71, :207, :682 (stage 5)
ui/component.zod.ts:751	#6276 in #5611/#5775/#6276	#5611 / #5775 / commit 78f0be872	as above
ui/component.zod.ts:4555	#9972 in #9881/#9972	#9881 / commit 60e0f900a	ui/component.zod.ts:2609, ui/component.test.ts:407 (stage 5)

The datasource line is the one site whose sentence did not say what the dead number decided, so it now says it in words, from the code: the mongo options passthrough refusal is part of the config gate (credentialFreeMongoOptions on MongoConfigSchema.options). That comment reflows from two lines to three. Every other edit is one line for one line, and each of those sentences already stated its decision in words.

Evidence

The six are dead, measured with the gate's own instrument. node scripts/check-issue-citations.mjs --census --json (read-only, board enumerated, 195 pages) at base 5b5e83f446 lists exactly these six plus the two literal-read sites stage 6 kept on purpose (data/api-derivation.ts:163 [#6259], identity/identity.zod.ts:230 #8715). Lines match the claim. No seventh dead number in packages/spec/src. REST issues/N, redirects not followed: #9040, #17590, #12380, #6276, #9972 answer 404; the lit controls #8082, #8336, #5611, #5775, #9881, #5286, #12624 answer 200.

After, at head dbacec5f91: the same census reads allocated-but-absent 119 → 113 repo-wide and 8 → 2 in packages/spec/src. Gone: exactly the six. New: none.

Each anchor is on main and names its number. REST compare/SHA...5b5e83f446 answers ahead, behind_by: 0 for all five shas (controls: 5b5e83f446~1 answers ahead, behind_by: 0; the off-main branch commit 25fb56f1b7 answers diverged, behind_by: 3). The local merge-base --is-ancestor exits 1 for all five on this shallow checkout, which is the shallow false negative, so the REST reading is the one cited. Each commit's own text names the number it replaces: 24206416a (subject: refuse a credential in the mongo options passthrough at publish, #9040); e04a0aff2 (its body names #17590 as the card it delivers, and its diff wrote the very @see line rewritten here); 4045b954d ("Part of #12380", with the live 17-value measurement across three dialects); 78f0be872 (subject names #6276); 60e0f900a (subject names #9972).

Comment-only, proved two ways.

• A parser-driven token comparison (TypeScript parser, leaf tokens off the syntax tree, JSDoc nodes skipped): base and head token streams are identical in all four files (2,231 / 6,169 / 1,098 / 16,019 tokens), with 0 parse diagnostics on either side. Controls, 7 of 7 behave: an identifier edit, a .describe() string edit, a template-literal edit and a regex-literal edit each report DIFFERS; a line-comment edit, a JSDoc edit and an @see-line edit each report IDENTICAL.
• Every added or removed line in the source diff is a comment line: 15 of 15 (+8 / −7).

Generated artifacts. After a spec build, check:generated reports 15 of 15 up to date. No reference page renders any of the six comments (content/docs/references/ holds neither the old nor the new text). Nothing was regenerated.

Changeset: @objectstack/spec patch. Measured after the build: datasource.zod.ts, filter.zod.ts and component.zod.ts ship verbatim through the package's files entry src/**/*.zod.ts; in dist, the three component.zod.ts comments are in 14 .js / .mjs bundles and the value-roundtrip-conformance.ts @see is in dist/data/index.d.ts and .d.mts. The datasource and filter comments reach no dist file. Positive control: the maxVisible .describe() text is in 14 dist files. So the change publishes text, and skip-changeset does not apply.

Tests and gates, at head dbacec5f91.

• pnpm --filter @objectstack/spec build: exit 0. Spec local vitest: 609 files, 18,057 passed, 1 todo. pnpm --filter @objectstack/spec typecheck: exit 0.
• node scripts/pm/dispatch-gates.mjs --commands --repo objectstack-ai/objectstack derived 79 families; --ran reconciles 78 run, all exit 0, and 1 NOT MEASURED, 0 unrun.
• NOT MEASURED: check:dual-build-cjs-loads, reason: it refuses (exit 3) until every publishable package is built, and a full monorepo build was not run locally. Narrowed and declared: the diff is comment-only in packages/spec, and of the gate's 106 require entries (its own --list), spec's 19 all load at head. CI runs the full gate.
• Two gates first refused for unbuilt prerequisites (@objectstack/lint check:doc-formula-expressions, check:lean-entry-closure). After building formula, lint and objectql (14 of 14 turbo tasks), both exit 0.

Overlap. Open PR #21632 and PR #21625 touch ui/component.zod.ts in other regions. Neither had landed at origin/main 36e4647520, re-fetched before this PR opened, so no merge was taken. A merge-tree of this head onto that tip exits 0, and none of the five changed paths is routed to the regeneration merge driver, so the local answer is GitHub's.

Acceptance notes

• docs/audits/2026-07-unknown-key-strictness-ledger.md:676 still names the #5611/#5775/#6276 rule. It is outside this stage's file surface and outside the census surface. Carrier: none.
• For #17590 the commit rung was taken, although e04a0aff2's message names a director-seat ruling record. That matches stage 3's anchor for the same number at filter.zod.ts:979, reviewed PASS.
• Not governed: no path under docs/adr/, .claude/, skills/, AGENTS.md or CLAUDE.md. 29 changed lines.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/spec, touching 4 documentable anchor(s). ⚠️ 2 changed file(s) yielded no anchor (packages/spec/src/data/filter.zod.ts, packages/spec/src/data/value-roundtrip-conformance.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

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

• content/docs/releases/v15.mdx (via PageTabsProps (symbol, a top-level const object))
• content/docs/releases/v17/17-0.mdx (via DatasourceSchema (symbol, a top-level const))
• content/docs/releases/v17/17-6.mdx (via DatasourceSchema (symbol, a top-level const), PageHeaderProps (symbol, a top-level const object))

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

• 2 changed file(s) yielded no anchor (packages/spec/src/data/filter.zod.ts, packages/spec/src/data/value-roundtrip-conformance.ts) — pages documenting those are invisible to this run
• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 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; 97 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.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 138 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 36e4647520b1e292c75cc4ded2c7a3bcb916ba91 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from d87dcbd25a12951e82ba3fc6046aa759aeded25b — the merge of head dbacec5f91e9de02df5b513a9b8a1b38ad12f905 into base 36e4647520b1e292c75cc4ded2c7a3bcb916ba91, 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 d87dcbd25a12951e82ba3fc6046aa759aeded25b && git checkout d87dcbd25a12951e82ba3fc6046aa759aeded25b
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 36e4647520b1e292c75cc4ded2c7a3bcb916ba91 dbacec5f91e9de02df5b513a9b8a1b38ad12f905 && git checkout -B drift-repro 36e4647520b1e292c75cc4ded2c7a3bcb916ba91 && git merge --no-ff dbacec5f91e9de02df5b513a9b8a1b38ad12f905

node scripts/docs-audit/affected-docs.mjs --json 36e4647520b1e292c75cc4ded2c7a3bcb916ba91

⚠️ 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 36e4647520b1e292c75cc4ded2c7a3bcb916ba91 → pass the list as
args.docs, on the commit named under Which tree this was computed on.