docs(qa): re-anchor the dead tracker citations in packages/qa to the commits that decided them

[objectstack-fleet]

Part of #20594
Clause-②: no

What changed

This is stage 8 of the domain:cli lane of the dead-citation sweep: packages/qa. packages/qa is a directory of five private workspace packages, not one package, so the surface is packages/qa/*/src/**. Every comment site there that cited a tracker number answering 404 now cites, in ruling C+D's form C (comment 5749154545 on #19123), the commit in this repository's history that decided what the line describes. Each line still says in its own words what that commit decided. PR #20533 is the method, and stages 1 to 7 of this card (PR #20624, PR #20632, PR #20656, PR #20673, PR #20689, PR #20703, PR #20713) are the precedents. The card stays open for the lane's remaining packages, so this PR says Part of.

That is 12 sites on 12 lines in 5 files, covering 6 numbers, rewritten to 6 distinct commits:

• the census's 8 sites: downstream-contract/src/additional-domains.fixtures.ts (2), http-conformance/src/adapter.ts (4) and vitest-filter-preflight/src/index.ts (2), 5 numbers;
• 4 test-file comment sites in 2 test files under http-conformance/src/ (the census leaves *.test.ts out; stages 1 to 7 took test comments too).

Only comments changed: 12 lines out, 12 in, and every touched file keeps its line count, so no line citation into these files moves. No citation number is added. Over the 12 line pairs, added-minus-removed numbers is empty, and no PR number stands newly on any line. The two numbers still on changed lines (#17978, #14554) were already on them, and both answer 200.

Two numbers have an ADR beside them, and both ADRs stay.

• #6083's line already cited ADR-0122 phase 2. The ADR's own amendment records phase 2, so the line now reads "ADR-0122 phase 2, commit 53068c1", the same pair spec stage 1 wrote in contracts/data-engine.ts.
• #10485's line cites ADR-0049, the enforce-or-remove principle it was retired under. No ADR records the theme retirement itself, so the commit is the anchor, and the ADR stays beside it, as in the landed stages.

None of the other four numbers appears in docs/adr/ or scripts/adr-anchors/. The grep reads 0 hits for them. The control, #5551, reads 1 hit in ADR-0122.

No changeset, and skip-changeset. None of the three touched packages publishes anything (see Changeset below).

Census: packages/qa, before and after

Instrument. The gate's own node scripts/check-issue-citations.mjs --census --json, read-only and unchanged, run under with-fleet.sh --read for the token. The count is its allocated-but-absent findings under packages/qa/. Both runs enumerated the whole board.

reading	tree	board	whole-repo allocated-but-absent	packages/qa sites	lines	numbers	files
before	base 679f95ec5c, run 2026-09-29T21:05:44Z to 21:09:44Z	enumerated, 186 pages, frontier #20718, 18,545 numbers	1,185	8	8	5	3
after	30aae6a3e6, run 21:18:38Z to 21:22:42Z	enumerated, 186 pages, frontier #20720, 18,547 numbers	1,177	0	0	0	0

The whole-repo drop of 8 is exactly these sites. A site-by-site diff of the two JSON outputs has 8 findings gone, all under packages/qa/*/src, and none added. The other three tallies are equal in both runs: resolves 32,982, resolves-as-pull-request 1,984 and cross-repo-unjudged 995. packages/qa/*/src is byte-identical at 30aae6a3e6 and at the head; the two later commits are merges of origin/main that touch nothing in packages/qa.

Supplementary scan (test files and everything outside src/ included). The gate's exported extractCitations and classifyCitation ran over all 221 tracked files under packages/qa (CHANGELOG.md excluded), with the board from the gate's own probeBoard. The totals are 1,678 citations and 139 dead before, and 1,666 and 127 after.

• Under src/, before: src comments 40 / 8 dead, test comments 42 / 4, src strings 1 / 0, test strings 9 / 0.
• Under src/, after: src comments 32 / 0, test comments 38 / 0, strings unchanged. Nothing dead is left under any src/, strings included, so there is no form-D residue in this stage's surface.
• Its before list of src comment sites is identical to the census's.
• The 127 left are all outside src/** (see Acceptance notes).

Per-site table

git blame at the base ties each line to the commit that wrote it. Each anchor was read in its message, changeset or diff, not only its subject. Where the pull request that landed an anchor still answers, its body's first line names the dead number, and that is noted.

number	sites (base line)	anchor: what it decided
#6083	downstream-contract/src/additional-domains.fixtures.ts:11	53068c130, ADR-0122 phase 2: the bare type name becomes the AUTHOR state (z.input) and the XInput synonyms retire. The same commit moved these frozen fixtures' annotations onto the bare names without touching a literal, which is what the paragraph says. The line blames to it, and its subject carries the number. The PR that landed it answers 404, and spec stage 1 gave the number this anchor.
#10485	downstream-contract/src/additional-domains.fixtures.ts:133	35ad101bc: retires the themes carrier key and ThemeSchema whole, under ADR-0049, and drops DcTheme from these fixtures. The line blames to it, and its subject carries the number. The spec, rest, runtime and cli stages gave the number this anchor.
#6143	http-conformance/src/adapter.ts:32, :189, :257, :346; http-conformance/src/fallback-seam.conformance.test.ts:4, :27	12298c7d6, which does two things: NodeHttpServer implements the optional setFallbackHandler out of its own router, as a field consulted in the route-miss branch, with the 405 answer extracted for its second call site; and the cross-adapter suite asserts the contract's four guarantees on both adapters. All six lines blame to it. PR #6851, which landed it, names #6143 on its first line.
#6307	http-conformance/src/query-multiplicity.conformance.test.ts:76, :296	293476148: refuses a repeated ?version= on GET / DELETE /packages/:id, and adds package-routes-query-multiplicity.test.ts. Its changeset records the measured read: on DELETE, a repeated value skipped the full-uninstall branch, and the call still reported success. The lines blame to the later 68feaadd6 and 7cdbcbb30, which cite this earlier work by number. PR #6895, which landed the anchor, names #6307 on its first line. The rest stage gave the number this anchor.
#17853	vitest-filter-preflight/src/index.ts:5	08f5f0e5a: a vitest file filter that selects nothing says so, even when the rest of the run selects something. This is the first implementation, in packages/cli. The line blames to c667d8c80, the shared port for all eight project-declaring packages; its number is #17978, which answers 200 and stays. PR #17965, which landed the anchor, names #17853 on its first line.
#13504	vitest-filter-preflight/src/index.ts:273	44813ba57: splits packages/cli's suite into the named unit and integration tiers, decided on behaviour, with the partition pin. That is half of the "tier walk" this sentence names, and its diff heads the new section with this number. #14554, the derived-population half, answers 200 and stays. The only commit whose subject carries #13504 is 55519d503, the comment-only measurement half: PR #13872 says it lands only that half. So that commit is not the anchor for this sentence. The PR that landed 44813ba57 answers 404.

Anchor checks. Every cited sha matches exactly one object (git rev-parse --disambiguate, count 1 for each of the 6). Each is a commit with one parent, and each is an ancestor of main (merge-base --is-ancestor against cbaf04c1fd, exit 0 for all 6). The checkout is not shallow. The control leg 3cc8676e1 (2026-08-08, the parent of the oldest anchor 53068c130 of 2026-08-08) exits 0, and the negative control, this branch's own 06b8fbc2d3, exits 1. Three anchors reuse the landed stages' (53068c130, 35ad101bc, 293476148), so each number carries one anchor across the tree. Three are new (12298c7d6, 08f5f0e5a, 44813ba57).

Numbers. All 6 dropped numbers answer 404 by REST (probed 2026-09-29T21:16:49Z). The numbers kept on changed lines (#17978, #14554) answer 200. No slash-joined citation group stands in packages/qa/*/src.

Mechanical guard: no code token moves

H2 holds on the parser-token reading. The emitted-dist reading does not apply, because none of these packages has a build (see Changeset below).

Token guard. It compares the TypeScript parser's leaf tokens (TypeScript 6.0.3, getChildren walked to the leaves, JSDoc nodes excluded) of the 5 touched files at base 679f95ec5c and at 30aae6a3e6. Controls mutate the head text in memory only.

• Real run: 7,917 base tokens, 0 differing (exit 0).
• Comment-insertion control: 0 differing (exit 0).
• Code-insertion control: all 5 files differ at token 0 (exit 1).
• String control (the first character of the 'vitest' import specifier in fallback-seam.conformance.test.ts flipped): exactly 1 differing StringLiteral, at token 11 of that file (exit 1).

Every one of the 24 changed lines is a // or * comment line. A raw scan of the 5 changed files for control bytes finds none (a positive probe on a scratch file matched).

Changeset

None, and skip-changeset. There is no @objectstack/qa package. The three touched packages are @objectstack/downstream-contract, @objectstack/http-conformance and @objectstack/vitest-filter-preflight. Each is "private": true, has no build script, no files[] and no dist/. .changeset/config.json versions private packages but never tags or publishes them. This diff therefore publishes nothing from any released package, so there is no dist to compare and no code-mutation control to run. The measurement is the packages' own manifests.

Gates (head 06b8fbc2d3)

This host has no flock, so os-verify-lock.sh ran in its declared unlocked mode. Its disclosure, verbatim, from each run at this head, and from the closure build at 527d5dca06 (the first merge; packages/qa is byte-identical between the two):

os-verify-lock: VERDICT command-exit 0 · UNLOCKED (declared) · no usable `flock` on this host, so the shared verify lock was NEVER taken and NOTHING was serialized · ran 77s (1m17s) · declare it in the PR body · pnpm --workspace-concurrency=2 --filter '@objectstack/downstream-contract^...' --filter '@objectstack/http-conformance^...' --filter '@objectstack/vitest-filter-preflight^...' build
os-verify-lock: VERDICT command-exit 0 · UNLOCKED (declared) · no usable `flock` on this host, so the shared verify lock was NEVER taken and NOTHING was serialized · ran 11s · declare it in the PR body · pnpm turbo run build --filter='./packages/*' --filter='./packages/*/*' --concurrency=2
os-verify-lock: VERDICT command-exit 0 · UNLOCKED (declared) · no usable `flock` on this host, so the shared verify lock was NEVER taken and NOTHING was serialized · ran 2s · declare it in the PR body · pnpm --filter @objectstack/downstream-contract exec vitest run --maxWorkers=2
os-verify-lock: VERDICT command-exit 0 · UNLOCKED (declared) · no usable `flock` on this host, so the shared verify lock was NEVER taken and NOTHING was serialized · ran 3s · declare it in the PR body · pnpm --filter @objectstack/downstream-contract typecheck
os-verify-lock: VERDICT command-exit 0 · UNLOCKED (declared) · no usable `flock` on this host, so the shared verify lock was NEVER taken and NOTHING was serialized · ran 8s · declare it in the PR body · pnpm --filter @objectstack/http-conformance exec vitest run --maxWorkers=2
os-verify-lock: VERDICT command-exit 0 · UNLOCKED (declared) · no usable `flock` on this host, so the shared verify lock was NEVER taken and NOTHING was serialized · ran 4s · declare it in the PR body · pnpm --filter @objectstack/http-conformance typecheck
os-verify-lock: VERDICT command-exit 0 · UNLOCKED (declared) · no usable `flock` on this host, so the shared verify lock was NEVER taken and NOTHING was serialized · ran 4s · declare it in the PR body · pnpm --filter @objectstack/vitest-filter-preflight exec vitest run --maxWorkers=2
os-verify-lock: VERDICT command-exit 0 · UNLOCKED (declared) · no usable `flock` on this host, so the shared verify lock was NEVER taken and NOTHING was serialized · ran 1s · declare it in the PR body · pnpm --filter @objectstack/vitest-filter-preflight typecheck

• Build. The three packages' dependency closure was built: 61 of 81 workspace projects, at 30aae6a3e6 and again at 527d5dca06. Then the whole workspace was built with turbo run build --filter='./packages/*' --filter='./packages/*/*': 71 of 71 tasks at this head, 66 of them cache hits. The tree was clean after each build.
• Tests (vitest run), at this head and at both earlier commits:
  • downstream-contract: 3 files, 31 tests passed;
  • http-conformance: 8 files, 102 tests passed;
  • vitest-filter-preflight: 3 files, 111 tests passed.
  • These are every test file each package has.
• Typecheck. All three typecheck scripts exit 0; downstream-contract's is also one of CI's consumer-gate type-check lanes. http-conformance's check:test-typecheck holds: 3 files, 27 errors, 10 pinned signatures. tsc --listFiles shows every touched file compiled:
  • downstream-contract/tsconfig.json: 11 files, 3 of them tests;
  • http-conformance/tsconfig.test.json: 11 files, all 8 tests, including both touched test files and adapter.ts;
  • vitest-filter-preflight/tsconfig.json: 6 files, 3 of them tests.
• Lint. The repo-wide pnpm lint (eslint . --no-inline-config) exits 0 at this head (2026-09-29T21:48:59Z to 21:49:26Z), and at 527d5dca06 before the second merge.
• Citation judging. node scripts/check-issue-citations.mjs --base origin/main, with origin/main at cbaf04c1fd and merged, judges 2 citations on the changed lines of 3 files (the kept #17978 and #14554). Both resolve, and the run exits 0. The pinned merged base of the first merge (--base 1ab98926b0, at 527d5dca06) gives the same 2 citations and also exits 0.
• Derived gates. node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands derived 53 families, identical at 527d5dca06 and at this head. All 53 exit 0 at this head. --ran with the exit-coded record reads "53 derived, 53 run, 0 NOT-MEASURED, 0 UNRUN" (a derived zero). Among them:
  • check:issue-citations;
  • check:doc-authoring (808 pinned sites, no growth);
  • check:nul-bytes (9,342 text files, no raw control bytes);
  • check:published-files, check:type-check-coverage and check:type-check-debt.
• Artifact rosters. 36 of the 39 non-self-test roster rows exit 0. These include the three the derivation marks as keeping their roster under one of this diff's paths (check:authz-resolver, check:error-code-casing, check:filter-alias-parity). The other three need a pull request's context; they are run against this PR once it exists, and the results are reported on the card. The 18 self-test-only rows grade their checkers' fixtures and cannot judge this diff.

Hypotheses (measured first)

• H0 holds. At base 679f95ec5c the filtered census answers 8 sites on 8 lines, 5 numbers, in 3 files, as on the seat's 0be898499f. The whole-repo count is 1,185.
• H1 holds. After the rewrite, the filtered census answers 0 for packages/qa. No site was left for an open PR or for an unfound anchor. The file lists of all 12 open PRs were read at 2026-09-29T21:13:53Z: only the Version Packages PR chore: version packages #20639 touches packages/qa, in CHANGELOG.md and package.json.
• H2 holds on the parser-token reading. The comment-stripped (parser-token) diff of all 5 touched files is empty, and its controls fire. The dist reading is not available, because none of the packages has a build.

Acceptance notes

• packages/qa outside src/**, a later stage of the card. The census surface is packages/**/src/**, and packages/qa/dogfood has no src/ at all. The supplementary scan counts 127 dead sites left in packages/qa outside src/**:

  • dogfood/test/** and dogfood/vitest.config.ts: 122 sites, 27 numbers, 28 files (94 comments, 28 strings);
  • downstream-contract/test/contract.test.ts:46 (#10485, a comment);
  • vitest-filter-preflight/test/config-wiring-sweep.test.ts:6 and test/filter-preflight.test.ts:5 (#17853, comments);
  • vitest-filter-preflight/package.json:6 (#17853, in the package description);
  • http-conformance/test-typecheck-debt.json:2 (#13470, in the generated _comment, whose producer is scripts/check-test-typecheck.mts; that producer is scripts/check-test-typecheck.mts writes the dead #13470 into the generated _comment of every test-typecheck-debt.json (19 files): re-anchor at the producer and regenerate #20715's, and it is never fixed by hand).

  None of them is in this stage's surface, and none moved.

• ADR-0122's own status line and amendment heading cite #6083 (404). docs/adr/** is a governed surface and one of the gate's deferred surfaces, so it is noted here, not touched.

• Card-word residue, cited nowhere. vitest-filter-preflight/src/index.ts:117 says "this card" about 150 lines from either rewritten line. It cites no number, so it was left, as the landed stages left theirs.

• The moving origin/main. The branch merged origin/main twice. The first merge (527d5dca06) took 1ab98926b0 (a spec retirement, nothing in packages/qa). After it, the shared ref advanced to cbaf04c1fd, the plugin-approvals re-anchor (PR docs(plugin-approvals): re-anchor the dead tracker citations to the commits that decided them #20717). Against that moved ref, --base origin/main then read the old plugin-approvals lines as this branch's additions: it judged 31 citations and exited 2, because the diff was two-dot. That run is not a measurement of this change. The pinned base answered exit 0. The second merge (06b8fbc2d3) took cbaf04c1fd, and every gate above was re-run on it. CI judges the merge ref.

Deviations

• The dispatch's packages/qa/src/** and @objectstack/qa do not exist as spelled. The surface was read as packages/qa/*/src/**, the census's own reading of packages/**/src/**. The changeset measurement was taken per touched package.
• Commit trailers are AGENTS.md's model-free pair (Claude-Session plus Co-authored-by: Claude), and the pre-push trailer check passed on every push. The harness's attribution reminder asked for a model-named trailer and a different PR footer, and AGENTS.md overrides it. The two merge commits carry git's default message.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 3 package(s): @objectstack/downstream-contract, @objectstack/http-conformance, @objectstack/vitest-filter-preflight, touching 2 documentable anchor(s). ⚠️ 2 changed file(s) yielded no anchor (packages/qa/downstream-contract/src/additional-domains.fixtures.ts, packages/qa/vitest-filter-preflight/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

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

• content/docs/kernel/contracts/auth-service.mdx (via handleRequest (symbol, a method of class NodeHttpServer))
• content/docs/permissions/authentication.mdx (via handleRequest (symbol, a method of class NodeHttpServer))

What this run could not see

• 2 changed file(s) yielded no anchor (packages/qa/downstream-contract/src/additional-domains.fixtures.ts, packages/qa/vitest-filter-preflight/src/index.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 — 0 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 3711e0b763d4bb597a52cb08b04950cace6821b1 → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json 3711e0b763d4bb597a52cb08b04950cace6821b1

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