docs(spec): strip the internal issue-ids projected into the published skill catalog, and drop the gate exemption that hid them

[os-litant]

Fixes#11930

Fourteen internal #NNNN references survived the 2026-08-23 strip of the published skill corpus. None of them was authored in skills/**: they are projected there from .describe() / TSDoc text in packages/spec/src/** by gen:skill-refs and gen:react-blocks, so the corpus-side cleanup could not reach them and a regeneration would have put them straight back. This is the source-layer half of that ruling, and the gate change that stops the round trip.

Premise, re-verified on origin/main

Measured at f7b25c5 before any edit: exactly 14 hits for #[0-9]{3,5} not followed by a word character, matching the filing's per-file counts exactly. Three further hits of a naive #[0-9]{3,5} scan are the CSS hex colours #6366f1, #4169E1 and #3498db — the same false-positive family the id rule's lookahead was written to exclude.

The filing's guess at which source files these came from was partly wrong, and the artifacts were used as the acceptance set instead. The real sources, reverse-looked-up from each of the 14 sites:

generated site	real source
objectstack-{data,platform}/references/_index.md — #4410 ×4	data/driver/common.zod.ts, data/driver/config-registry.zod.ts
objectstack-{data,platform}/references/_index.md — #6345 ×2	data/driver/turso.zod.ts
objectstack-automation/references/_index.md — #4661	shared/retry-policy.zod.ts
objectstack-i18n/references/_index.md — #4001	system/translation.zod.ts
objectstack-ui/references/react-blocks.md + contracts/react-blocks.contract.json — #11284 ×4, #4413 ×2	ui/react-blocks.ts (the ListView.objectName / ListView.viewType deprecation notes and the Block tag summary)

The _index.md summary is the first line of a file's first JSDoc block (extractDescription in build-skill-references.ts), which is why stripping one id from shared/retry-policy.zod.ts meant rewriting its opening sentence rather than deleting three characters: the citation ran across the line break and left a dangling ) behind.

What changed

Six source sites rewritten to say the same thing without the citation, keeping the teaching per the standing ruling of 2026-08-12, verbatim and untranslated: 「处理 issue 时犯的错应该总结成经验,保留 issue id没有意义」. Then gen:skill-refs, gen:react-blocks and gen:docs regenerated. Result: 0 internal issue-id references anywhere under skills/**.

Deeper TSDoc in the same files still carries internal ids — those lines project nowhere customer-facing, and widening to them is a different decision than the one this card inherits.

The gate exemption is removed, not narrowed

GENERATED_SKILL_ARTIFACTS in scripts/check-doc-authoring.mjs exempted references/_index.md and references/react-blocks.md by path, for a stated reason that no longer holds: it existed because those files still carried projected ids, and reding a file whose own header says "do not edit" pointed the remedy at the wrong repo layer. With the sources clean the exemption guarded a clean surface — and that is precisely where the next regeneration would smuggle one back in, past the gate that exists to stop it.

So the exemption is deleted rather than narrowed, and the "wrong repo layer" objection is answered where it actually bites — in the failure text, which now tells an author who hits a red on an auto-generated file to strip the id at the spec source and regenerate, never to hand-edit the artifact.

Its self-test is rewritten rather than patched: the two cases that pinned "the generated artifact is exempt" asserted the behaviour being removed, so they now pin the artifacts as in scope, and a new case plants an id in a generated _index.md and asserts the scan reds on it and names that file. Listing a file only proves collection; the plant proves it is read.

This aligns with the gate PR #11931 landed. No second gate was added, and the spec-source-side ban the filing floats as step 3 is deliberately not implemented here — it would be a second gate over a different population, which is a decision this card does not carry.

Line budgets (governed surface)

skills/** is loaded whole into customer context windows, so both readings are reported. Lines are the budget; tokens are ceil(utf8 bytes / 4), the sibling ratchet's unit.

Every changed artifact, whole file:

file	lines before → after	tokens before → after
objectstack-automation/references/_index.md	44 → 44	763 → 761
objectstack-data/references/_index.md	65 → 65	1286 → 1280
objectstack-i18n/references/_index.md	35 → 35	493 → 491
objectstack-platform/references/_index.md	62 → 62	1233 → 1227
objectstack-ui/contracts/react-blocks.contract.json	559 → 559	5356 → 5350
objectstack-ui/references/react-blocks.md	117 → 117	3157 → 3150

Whole package — every SKILL.md in the published catalog: 10505 → 10505 lines (net 0), 117716 → 117716 tokens (net 0); no SKILL.md is touched. Whole skills/ tree, every file: 17849 → 17849 lines (net 0), 187951 → 187922 tokens (net −29).

Against the dispatched budgets: skills/** net 0 lines (budget ≤ +0) · packages/spec/src net +1 (budget ≤ +30) · scripts/ net +10 (budget ≤ +10). The scripts/ figure needed a deliberate trim — the first draft of the comment and self-test came to +16, and it was compressed to fit rather than the budget being raised.

Declared deviation — two source files outside the dispatched surface

The dispatched file surface named packages/spec/src/{conversions,data,ui,automation,ai,api}. Two of the six real sources are not in those directories:

• packages/spec/src/shared/retry-policy.zod.ts
• packages/spec/src/system/translation.zod.ts

The directory list was derived from the filing's source attribution, which the reverse look-up above disproves. The acceptance set is the 14 artifact sites, and leaving 2 of the 14 standing because a guess named the wrong directory would deliver a card that does not close. Both edits are the same defect class, the same mechanical rewrite, the same gate families, and no other in-flight claim holds either file (checked against the open-PR list). Recorded here rather than taken silently.

content/docs/references/data/driver-common.mdx and driver-turso.mdx also change — that is the same source edit reaching the docs site through build-docs.ts, and the full regen set was called for at dispatch.

One consequence left deliberately untouched

scripts/check-ratchet-remedy-authority.mjs carries a why string for check-doc-authoring.mjs that names GENERATED_SKILL_ARTIFACTS among that file's declarations. This PR removes that constant. The gate stays green — it was run, and its verdict rests on the other declarations named there — but the prose will name a symbol that no longer exists once this lands. PR #12061 is in flight on exactly that file and is marked blocked pending a recorded verdict, so racing a one-clause edit into it here would be worse than leaving it. Tracked separately; the repair should ride whichever of the two PRs lands second.

Verification

Full gate list re-derived from the real change set with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (the script reads its own merge-base diff), which returned 44 families once the changeset existed — more than the 14 the dispatch named. All 44 run green at d1a56ba, together with the regeneration-freshness set (check:skill-refs, check:react-blocks, check:docs, check:generated, check:skill-docs, check:authorable-surface, check:api-surface), check-doc-authoring --self-test, check-ratchet-remedy-authority, check-skills-token-ratchet, check:nul-bytes, and @objectstack/spectypecheck.

packages/spec's own suite: pnpm --filter @objectstack/spec exec vitest run --maxWorkers=2 → Test Files 425 passed (425) / Tests 11321 passed (11321).

Two gates first refused with PREREQUISITE NOT MET — the workspace package is not built and were re-run green after pnpm --filter '@objectstack/lint...' build; their own text says "Nothing was measured", so the first result was not a finding.

check:react-declaration-parity refuses with MANIFEST is not set — it needs an objectui manifest dump and a browser, is not in the derived family list for this card, and exits before reading the diff. check-dev-prereqs.mjs reports 66 of 67 workspace packages unbuilt: it measures the container's build state, and this diff adds no package, edits no package.json and produces no build output, so it cannot move that verdict either way.

Repo-wide pnpm lint was not run; CI owns that farm run.

Filed out of scope

• build-skill-references.ts still picks the first JSDoc block anywhere in the file — the defect build-docs.ts fixed, publishing a private constant's comment to customers #12094 — build-skill-references.ts still selects the first JSDoc block anywhere in the file as a file's published description, the ordering defect build-docs.ts already fixed by moving to findModuleDocBlock(). Live victim: system/translation.zod.ts, whose skill-reference entry describes a private TRANSLATION_HISTORY constant rather than the Translation protocol. Found here because that entry is one of the 14 sites; stripping its id does not make the sentence correct, only id-free.
• check-ratchet-remedy-authority's entry for check-doc-authoring.mjs names GENERATED_SKILL_ARTIFACTS, a constant that is being removed #12095 — the stale GENERATED_SKILL_ARTIFACTS mention described above.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

⚠️5 changed file(s) yielded no anchor (packages/spec/src/data/driver/common.zod.ts, packages/spec/src/data/driver/config-registry.zod.ts, packages/spec/src/data/driver/turso.zod.ts, …), 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

• 5 changed file(s) yielded no anchor (packages/spec/src/data/driver/common.zod.ts, packages/spec/src/data/driver/config-registry.zod.ts, packages/spec/src/data/driver/turso.zod.ts, …) — pages documenting those are invisible to this run
• 2 name(s) were too generic to anchor anything (single lowercase words)
• 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 0e0bf8049dfcef2ac29c43cfa15f9963c3b921a0 → packageMentionDocs.

[os-zhuang]

Merging on the maintainer's explicit instruction, 2026-08-25: 「你帮我合并」 (covering the reviewed governed-draft group: #11829, #11934, this PR). The maintainer reviewed the per-PR verdict summary before instructing; this merge is the acceptance act executed on their behalf.

---

Generated by Claude Code