docs(cli): drop the dead tracker number from bin/run.js docblock and keep the sentence

[objectstack-fleet]

Part of #20594
Clause-②: no

What changed

Stage 18 of the domain:cli lane's dead-citation sweep: the last comment site that ships in the tarball and has no deciding commit.

• packages/cli/bin/run.js, the docblock line at :225: — #14874 is removed (the space, the dash, the number). The sentence stays and still ends in a period: "files names only dist, but npm packs a bin target regardless)." That sentence already states the measured fact in words, so nothing is lost.
• .changeset/20594-cli-bin-form-d.md: @objectstack/cli patch. bin/run.js is packed as a bin target regardless of files, so a published byte moves even though behaviour does not.

This is ruling C+D's form D for a shipped line: runtime-facing text carries no tracker number and the lesson is written into the words. Form C (anchor a commit) is not available because no commit decided that number: the history search of stage 17, re-read adversarially in contract review 5920476831, found only commits that restate or apply the packing fact. Routing is the stage 17 ACCEPT 5920504334; the claim is 5920968376.

Not in this PR

The five test sites with no deciding commit keep their numbers, as listed under 5914299201: vitest.config.ts:221, test/init.test.ts:189, and the three #14874 mentions in test/published-entry-stderr-error-listener.test.ts and test/published-subpath-hook-body.pin.test.ts. The 97 dead string sites across the lane belong to #20752.

Evidence (head fdb924cc7d, base 013f97df93)

Comment only, measured two ways.

• Byte level: exactly one line differs (225); bin/run.js is 258 lines before and 258 after; occurrences of 14874 in the file go 1 to 0; the removed suffix is exactly the dash-and-number and putting it back reproduces the base line.
• Token level: the non-comment token stream of bin/run.js, taken with the TypeScript parser with JSDoc nodes dropped, is identical before and after (179 tokens, equal sha256).
• Controls on copies, never on the worktree: mutating a code identifier flips the guard (2 token lines differ); mutating a string literal in an import specifier flips it (2 differ); a comment-only mutation does not (identical). A first version of the guard counted JSDoc blocks as tokens and flagged the real edit as well as the comment-only control; that was an instrument defect, found by the controls and corrected before any reading was taken, and the before-state was re-measured from the byte-identical base blob (git hash-object equal to the base blob).

Smoke (after building the dependency closure): node packages/cli/bin/run.js --help exits 0 with 66 stdout lines and empty stderr; --version exits 0 and prints @objectstack/cli/17.5.0 linux-x64 node-v22.22.2.

Gates. node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands with no path derived 54 commands. All 54 were run one by one with the exit code captured before any pipe, and --ran reconciled them: 54 derived, 54 run, 0 NOT-MEASURED, 0 UNRUN. The derivation line named commit fdb924cc7d, which is the final head. An earlier pass ran before the workspace was fully built and read exit 3 (prerequisite not met, so not a verdict) for check:dual-build-cjs-loads and check:i18n-coverage; after a full turbo run build (72 of 72 tasks) the whole list was re-run from scratch and is what is reported here.

Lint. The full pnpm lint (eslint . --no-inline-config) exits 0 with no findings, run on this head, so no narrowed form is relied on.

cli package.

• pnpm --filter @objectstack/cli typecheck: exit 0.
• Unit tier (vitest run --project unit): 239 files, 3391 tests passed.
• Integration tier, run locally because the diff touches bin/, a spawn entry: 67 files in six --shard=i/6 runs, all exit 0 (12, 11, 11, 11, 11, 11 files; 71, 118, 74, 94, 114, 107 tests passed, 1 skipped). The whole tier in one call exceeded my 540 s bound and exited 124, which is no reading; it was re-run as the six shards.
• The two published-entry pins read bin/run.js through maskComments, so they cannot see a comment edit by construction, and both are inside the integration shards above.

Acceptance notes

• scripts/check-issue-citations.mjs declares its surface as comment prose in packages/**/src/**; bin/run.js is outside it, so its green is not a reading of this line. The reading of this line is the byte and token evidence above.
• Not measured here: CI's own jobs (Test Core shards, Dogfood, Build Core, Temporal Conformance, the type-check lanes), which run after this report.
• Commit trailers are the model-free pair AGENTS.md prescribes, not the harness reminder's model-named form.
• Governed surfaces: none (the two paths are packages/cli/bin/run.js and a .changeset file); 15 changed lines against the 5000-line human-merge threshold.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️ 1 changed file(s) yielded no anchor (packages/cli/bin/run.js), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files. Nothing else in this diff resolved to a documentable surface (no symbol, route or SDK anchor derived from 1 changed package(s)).

What this run could not see

• 1 changed file(s) yielded no anchor (packages/cli/bin/run.js) — pages documenting those are invisible to this run
• 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 — 25 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 212d613ca03d2dd3de7147ebd0eb759667e2ffa9 → packageMentionDocs.

[objectstack-fleet]

Contract review

Served-tier: CONTRACT_REVIEW_TIER
Head-sha: fdb924cc7df2eedae88fc9aebab365fe19be58a1
Local-runs: none

① Derived judgments

(a) The diff is exactly the claimed one — holds. Net diff 013f97df93..fdb924cc7d, read in the clone: 2 files, +14 / −1, one commit, parent 013f97df93, and the API file list agrees. packages/cli/bin/run.js: one line differs (225, hunk @@ -222,7 +222,7 @@); the removed text is — #14874 (space, em dash, space, number) and nothing else; 258 lines before and 258 after; occurrences of 14874 in the file read 1 at the base and 0 at the head. The remaining line, read in context at the head (lines 224–225), is "on the entry point a customer's install actually runs (files names only dist, but npm packs a bin target regardless)." — the parenthesis opened on 224 closes on 225 and the sentence ends in a period, so it is complete. It is true: packages/cli/package.json at the head maps bin objectstack and os to ./bin/run.js while files is dist, README.md, CHANGELOG.md, and the repository's own gate encodes the fact the words state (scripts/check-changeset-no-major.mjs, binTargetsOf docblock: "npm packs a bin target REGARDLESS of files … bin/run.js ships anyway"). The five test sites with no deciding commit are untouched: the diff has no third path. Form: ruling 5749154545 defines D as "runtime strings carry no tracker numbers — the lesson is written into the text" and puts "the two shipped tarball lines" under D first, refusing A because "the two shipped lines keep sending readers to 404"; the #19123 execution applied it to shipped docblock lines (ACCEPT 5855952308: "The two lines that ship now state the lesson in words, with no tracker number (D)"). There, D travelled with a C anchor because a deciding commit existed; here none does — git log -S '#14874' to the head names 95d5cbb316, b3ef687c04 (wrote the line), 8c1515e847, d451409d20 and 7e6337007f (a Version Packages compile of 8c1515e847's changeset), each restating or applying the packing fact, which matches the stage-17 record's adversarial re-read and 5914299201's rule that a commit which only restates or applies a decision is not the anchor. Dropping the number and keeping the sentence that already states the measured fact is D as the ruling wrote it and as #19123 applied it to shipped lines, and is exactly what the stage-17 ACCEPT 5920504334 routed ("drop only the number and keep the sentence") and the claim 5920968376 scoped ("drop #14874 only … ⛔ No commit anchor … ⛔ No other line").

(b) The changeset — owed, patch right, prose accurate. Owed: bin/run.js is a bin target and ships regardless of files (the manifest and gate reading above, the same rule the stage-17 record verified at 5920476831 ①(c)), so a published byte moves and skip-changeset is not available under AGENTS.md's rule; the landed precedents 8c1515e847 (#16971) and #19123's PR #20226 took the same patch shape. .changeset/20594-cli-bin-form-d.md declares '@objectstack/cli': patch. Prose, checked line by line: "The docblock above bin/run.js's process.stderr error listener" — the docblock closes at 238 and the listener is attached at 246, with only the // ⚠️ NAMED comment between; "ended a sentence with a tracker number that no longer resolves on GitHub" — #14874 is in the dead set the stage-14 and stage-17 records carry; "files names only dist, but npm packs a bin target regardless, which is the measured fact the number was pointing at" — the gate's own docblock cites #14874 beside that exact fact; "The file ships because of that same packing rule, which is why this is a release note at all" — correct; "Comment only: no command, flag, exit code, error code, export or runtime behaviour changes" — what the diff shows. It claims no behaviour change, and the body carries no tracker number itself, which is right for text that ships as CHANGELOG.md. Check Changeset on the head: success.

② Semver level

Clause-②: no (line 2 of the PR body) with @objectstack/cli: patch is right under AGENTS.md's rule: yes pairs with at least minor; no — no accept set, export or public face moves, which ①(a) verifies by byte count and ①(b) by the manifest — pairs with patch, and patch rather than none because bin/run.js ships. Not breaking, so no ADR-0087 marker is owed.

③ Boundary flags

Check-runs on fdb924cc7d, collapsed to latest-per-name after convergence (last completion Test Core at 2026-10-01T00:26:48Z): 34 names — 31 success, 3 skipped (Build Docs, Console Pin Gate, Packed-tarball smoke (opt-in)), 0 failure, 0 pending. All seven required contexts success: Lint & Repo Gates, TypeScript Type Check (and its four lanes), Test Core (and its six shards), Dogfood Regression Gate (and its three), Build Core, Temporal Conformance (live PG + MySQL), Governed Surface Queue Guard. Check Changeset, Check PR Size, No other open PR may claim the same single-writer path and No other open PR may claim the same issue: success.

PR form: draft, head repo = base repo, base main, first line Part of #20594, Clause-②: no, no closing keyword (Part-of PR must not also close its card success; The card this PR closes must claim this branch success). Governed surfaces: 0 of 2 paths; 15 changed lines. Commit fdb924cc7d ends with Claude-Session: plus Co-authored-by: Claude and carries no model identifier. The base 013f97df93 is an ancestor of the branch tip 212d613ca0 (13 commits between) and git log over the two changed paths in that range is empty.

Deviations (7), each answered:

1. Model-free trailer pair over the harness reminder — answered: the one commit carries the pair AGENTS.md prescribes and no model identifier (read in the clone).
2. The container restart killed the first workspace build and the partial log is not cited — noted; nothing cited rests on it, and the gate is CI's Build Core, success.
3. A first gate pass before the full build read exit 3 for two gates and only the second pass is reported — noted; CI's Lint & Repo Gates runs them on the head, success.
4. The token-guard instrument was corrected before any reading — noted; the one-line / 258-line / 1→0 reading in ①(a) is this record's own and independent of that guard.
5. The integration tier was sharded after a 540 s timeout and shard 4 was backgrounded — noted; the gate is CI's Test Core, all six shards success.
6. A stray /build.pid at the dev container's filesystem root, left undeleted — outside this diff and outside the repository (the diff carries the two named paths and no scratch artefact); nothing owed by this record, and the dev correctly did not route around the safety refusal.
7. Stage files prefixed s18- in a shared scratchpad — scratch only; outside the diff.

Out-of-scope finding (1), answered: scripts/check-issue-citations.mjs declares its surface as packages/**/src/**/*.ts(x) (read at the head, rows at lines 226 and 234), so packages/cli/bin/** was never in its census and its green is not a reading of line 225; widening it is excluded by the card. Answered by an independent reading: the 1→0 occurrence count at the head in ①(a) is this record's own instrument, not the gate's. Carrier none, correctly: no action is owed here.

One observation of this record's own, non-blocking: scripts/check-changeset-no-major.mjs's binTargetsOf docblock still cites #14874 beside the same packing fact. It is repository tooling, not a shipped line, and outside the claim's surface ("⛔ No other line"), so it is correctly untouched here; stage 14's ACCEPT once named #15809 for "a gate script", which the stage-17 ACCEPT records as closed not_planned, so that site has no named carrier. Routing is the seat's; this record writes no rule for it.

Implemented-by: claude/issue-20594-bin-run-form-d
Reviewed-by: session_01VvcEokUG1tvVxkceYfR5XB

VERDICT: PASS

---

Generated by Claude Code