refactor(spec)!: strip internal tracker ids from the three customer-facing text populations, and widen check-doc-authoring Rule 3 to hold them

[os-trump]

Fixes#12522

Strips internal issue-tracker ids from the three adjacent customer-facing text
populations in packages/spec, and widens check:doc-authoring Rule 3 so they
stay stripped.

This is ruling-inheritance, not a new ruling. The founding rationale is "the
ban follows the audience, not the file type", and re-checking it against each
bucket answers the card without a new maintainer decision: strictObject
guidance and retiredKey() prescriptions are printed verbatim at the refusing
author — same audience, same moment as a refusal message — and .describe()
prose projects into content/docs/references/** and the generated skill
artifacts, where a customer cannot resolve a bare id either.

What was stripped, and what was deliberately kept

bucket	strings	example FROM	example TO
strictObject guidance / history / aliases	262	Until #4001 closed this shape these were dropped silently	Until this shape was closed these were dropped silently
retiredKey() + *_RETIRED_KEY_GUIDANCE	130	removed in @objectstack/spec 17 (#3894) — use `skills`.	removed in @objectstack/spec 17 — use `skills`.
.describe() docs prose	187	Parsed but no runtime consumer yet (liveness #1878/#1893).	Parsed but no runtime consumer yet.
zod message: — the hoisted spelling	5	a pair that cannot work as written (#9041).	a pair that cannot work as written.
total	584

KEPT throughout: ADR ids, protocol and package versions, error codes, and the
os migrate meta --from PROTOCOL migration commands. AGENTS.md positively
requires a tombstone prescription to carry a durable reference; those are the
forms a customer can actually resolve, so an issue id riding beside an ADR id was
the strippable half — never the ADR id itself.

No accept/reject behaviour changes anywhere: no schema takes or refuses anything
it did not before, and no key, default or error code moved. Message wording and
generated docs only.

The rule widening — with its before/after evidence

Rule 3 recognised two positions (message:, positional validator messages). It
now recognises five, and there is still no exemption mechanism — widening
means widening the recognised positions, exactly as the rule's own header
prescribed.

BEFORE the widening (unmodified tree)
doc authoring guard: 535 refusal-message string(s) across 670 spec sources
clean — no internal issue-id references. exit 0
AFTER the widening, BEFORE the strip
Internal issue-id reference(s) in CUSTOMER-FACING spec text:
584 string(s): strictObject 262 · describe 187 · tombstone 130 · message 5
exit 1
AFTER the strip (this PR)
doc authoring guard: 13306 customer-facing string(s) across 672 spec
sources clean — no internal issue-id references
(message 778 · strictObject 3282 · tombstone 751 · describe 8495) exit 0

The green line is a census, not a silence: all four buckets are populated, so
the per-bucket seen floor is satisfied rather than merely unbreached.

The hoisted-const spelling — why positions alone were not enough

A position-only matcher stops at the first VariableDeclaration it climbs into,
and this tree overwhelmingly hoists its guidance maps (const TOOL_RETIRED_KEY_GUIDANCE = {…}, referenced as guidance: …) and some of its
refusal messages (message: CREDENTIALS_REF_MONGO_URL_NO_USER_REFUSED). So
collectTextSinkConsts() runs a per-file sink-alias pass to a fixed point.

That is not a hypothetical about the new buckets: the hoisted spelling was hiding
five ids from the message: rule itself, which had reported that population
clean since the day it landed. Those five are the message row above.

The seen floor also moved from the total to per bucket — .describe()
alone would hold a total positive forever while the guidance matcher rotted
unseen, which is the same argument the per-ROOT floor already rests on.

Fork condition — one member

Charter item 4: a tombstone the strip would leave with no durable reference at
all is reported, never stripped silently and never given an invented reference.
All 132 changed tombstone prescriptions were audited against the three accepted
forms — 96 carry an ADR id, 83 the migration command, 59 a FROM to TO mapping,
128 a version anchor.

One member has none of them:

packages/spec/src/api/batch.zod.ts — options.validateOnly
FROM: …was removed from BatchOptions in @objectstack/spec (#4052).
TO: …was removed from BatchOptions in @objectstack/spec.

Its only reference was the issue id: no ADR, no os migrate command, and —
unlike every other member — no version anchor either. The prescription is
still complete and actionable ("drop the key", plus what to do instead), so this
is a missing citation, not a missing instruction. No replacement has been
invented; the removal version is a fact for the maintainer to supply, and it is
reported on the card for that decision.

Verification beyond the gate

Bracket balance. An id excised from mid-parenthetical can take the closing
bracket with it — the result still compiles and still reads almost right, and no
gate sees it. Every concatenated string expression in all 88 touched sources was
compared against the branch base: 11,065 expressions, balance unchanged on
every one. That check caught one real defect (a dropped bracket in
protocol.zod.ts).

Sentence quality. The transform was rule-based over ranges the gate itself
listed, so nothing outside the ruled population was edited; 479 sites were taken
mechanically and 105 were read and repaired by hand, because deleting the
clause would have left sentences that no longer said anything. Repairs state in
words what the id pointed at ("the gap this key exists to close", "the console
release that restores this flag"). A dangling-connective guard drops a
parenthetical rather than stranding it — (#8778, widened by cloud#1395) becomes
nothing, never (widened by).

Pin tests moved with the strings (charter item 3), iterated against the suite
rather than against a pattern: 92 to 46 to 13 to 4 to 0 failures. Each pin now
asserts the new sentence instead of being deleted, and where a pin existed only
to hold a tracker id it is replaced by the negative pin the gate's own failure
text prescribes (a not.toMatch on the id shape), so the assertion stays
load-bearing.

Two corrections along the way are worth a reviewer's attention, because both
produced states that read as progress while being wrong:

• Ten pins were repointed that were never stale and are now restored. Their
  ids are still in the sources — in populations outside the four ruled buckets
  (conversion registries, migration entries, TSDoc, and refusal prose built
  inside error callbacks). The rule the reverts encode: a pin may only lose an
  id this branch removed from that message, which is narrower than "an id
  this branch removed somewhere".
• A regex repair ate a literal escape while tidying emptied groups, in
  driver.test.ts. That failure was briefly diagnosed as pre-existing on main —
  the phrase really was absent from every revision, because the mangled regex was
  what was being compared. git diff against the branch base is what settled it.

Test titles and comments keep their ids on purpose: the gate excludes test
bodies because that reader has the tracker, and the ban follows the audience. An
earlier line-based attempt would have stripped 482 literals across 134 files,
most of them titles — it was discarded for an AST pass scoped to assertion
arguments.

Gates

Re-derived from the real changeset with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack rather than from the dispatch brief.

The union below was run on the FINAL commit, dd7c13d57 — after the second
merge of main and its regeneration, so it is a verdict on the tree this PR
actually proposes:

pnpm --filter @objectstack/spec exec vitest run
Test Files 440 passed (440)
Tests 11675 passed (11675)
pnpm --filter @objectstack/spec typecheck OK (test layer included,
via tsconfig.test.json)
pnpm --filter @objectstack/spec check:generated all 14 artifacts up to date
check:doc-authoring · check:parse-guard · check:watch-hint-literal ·
check:nul-bytes · check:error-code-casing · check:empty-changeset ·
check:changeset-gate-self-tests · check:cross-package-test-inputs ·
check:test-source-alias · check:merge-driver · check:published-files ·
check:agent-test-spelling all PASS

check:i18n is NOT MEASURED here, not green: it refuses with PREREQUISITE NOT MET — the workspace CLI is not built and says so explicitly rather than
reporting a clean scan. Nothing in this diff touches a translation bundle; CI
builds the workspace and runs it there. origin/main was merged via
scripts/pm/os-regen-merge.sh and the generated chain regenerated on the
committed merge — 64 files under content/docs/references/, 772 insertions /
772 deletions, no added line carrying a tracker id, content/docs/releases/
untouched.

Out-of-scope finding

#13002 — a fourth customer-facing refusal population, built inside error
callbacks (28 literals / 32 ids across 8 files), is structurally unreachable by
Rule 3 even widened. Same audience as everything stripped here, but the census on
this card counted it in other and the charter named three buckets, so stripping
it would widen a ruling rather than apply one. Filed, not fixed.

Cross-wave note

Declared at claim time and repeated here: this PR's edits are prose-only and
disjoint from the semantic regions of the gated drafts on ui/view.zod.ts,
contracts/* and data/aggregation-conformance.ts. data/field.zod.ts is a
trigger file of an on-hold card — re-pricing input only, no rider work. The
second merge of main conflicted once, in ui/view.zod.ts: resolved by taking
main's newer visibleWhen prose whole and applying this branch's strip to it.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

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

62 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json df1c75c4b027e6b7be2c911108cdb8ca8f745e61.

⛔ 6 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• 2 changed file(s) yielded no anchor (packages/spec/src/api/realtime.zod.ts, packages/spec/src/system/notification.zod.ts) — pages documenting those are invisible to this run
• 1 anchor(s) matched too much of the corpus to be a work list: sys_user (literal, 29 pages)
• 28 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 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 — 126 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 df1c75c4b027e6b7be2c911108cdb8ca8f745e61 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 3d17803a99afe1fa6e42ee1009ed00f8a738f029 — the merge of head 5ebfe8ba0581ff2506fbc75b3510ef4c46f53eb8 into base df1c75c4b027e6b7be2c911108cdb8ca8f745e61, 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 3d17803a99afe1fa6e42ee1009ed00f8a738f029 && git checkout 3d17803a99afe1fa6e42ee1009ed00f8a738f029
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin df1c75c4b027e6b7be2c911108cdb8ca8f745e61 5ebfe8ba0581ff2506fbc75b3510ef4c46f53eb8 && git checkout -B drift-repro df1c75c4b027e6b7be2c911108cdb8ca8f745e61 && git merge --no-ff 5ebfe8ba0581ff2506fbc75b3510ef4c46f53eb8
node scripts/docs-audit/affected-docs.mjs --json df1c75c4b027e6b7be2c911108cdb8ca8f745e61

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