14 internal issue-id references survive in generated `skills/**` artifacts — their source is `packages/spec` TSDoc, so the ruled strip could not reach them

[os-zhuang]

Measured while implementing #11052 (the ruled strip of internal issue ids from the published catalog). Filed unassigned — out of that card's scope, which was the hand-authored corpus.

Sub-issue of #11052: same ruling, same citation kind, one source-layer over. The 2026-08-23 ruling was «strip the internal issue-id references from the published skill corpus»; these 14 sites are in that corpus but are not authored there.

What

After the strip, skills/** still carries 14 #NNNN references, all in generator-owned files:

3  skills/objectstack-data/references/_index.md          #4410 ×2, #6345
3  skills/objectstack-platform/references/_index.md      #4410 ×2, #6345
3  skills/objectstack-ui/contracts/react-blocks.contract.json   #11284 ×2, #4413
3  skills/objectstack-ui/references/react-blocks.md      #11284 ×2, #4413
1  skills/objectstack-automation/references/_index.md    #4661
1  skills/objectstack-i18n/references/_index.md          #4001

Every one of these files says so in its own header — > **Auto-generated** — do not edit for _index.md, {/* GENERATED by packages/spec/scripts/build-react-blocks-contract.ts — do not edit. */} for the react-blocks pair.

Why the cleanup PR did not fix them

The ids are not written in skills/. They are projected from .describe() / TSDoc text in packages/spec/src/** by gen:skill-refs and gen:react-blocks. So the fix is a spec-source edit plus a regeneration, and that has a materially wider blast radius than the card it would have ridden on:

• the same .describe() strings also feed content/docs/references/ (the public docs site) via build-docs.ts, so the edit changes customer-facing text in two places at once;
• it answers to a different gate set (check:docs, check:authorable-surface, check:api-surface, check:react-blocks) than the skills families;
• skills/*/references/_index.md sits inside the skills/** governed-merge fence while being generator-owned — the exact friction [finding] skills/*/references/_index.md is generator-owned (gen:skill-refs) yet sits inside the skills/** governed-merge fence — every spec PR touching an indexed headline is forced to carry a governed-surface file #11705 is about — so a spec PR that moves one of these headlines is forced to carry a governed-surface file.

Doing it inside the cleanup PR would have been an unmeasured widening riding on a measured card, so it was deliberately left and exempted by path in the new gate, with the reason recorded in scripts/check-doc-authoring.mjs next to the exemption rather than left implicit. The exemption is exact: 9 _index.md + 1 react-blocks.md, each verified to carry a generated marker, leaving 38 of the 48 .md files in scope.

What a card here would do

1. Strip the ids from the source .describe() / TSDoc in packages/spec/src/** (keeping the teaching, per the 2026-08-12 ruling: 「处理 issue 时犯的错应该总结成经验,保留 issue id没有意义」), then regenerate.
2. Decide whether the doc-authoring gate's GENERATED_SKILL_ARTIFACTS exemption can then be narrowed or removed — once the source is clean the generated files are clean, and keeping a permanent exemption over a surface that no longer needs one is how the next id gets in unseen.
3. Consider whether the ban belongs on the spec-source side too, where the text is actually authored — that is the only place a regeneration cannot reintroduce it from.

⚠️ skills/** and the generated artifacts under it are a governed surface, so whatever lands here is draft + human merge.

[claude]

Triage: lands in packages/spec/src/** .describe()/TSDoc text plus regeneration (gen:skill-refs, gen:react-blocks); domain:spec (spec prose face). → pm:queue, Task — inherits the 2026-08-23 strip ruling through #11052 (same ruling, one source layer over; sub-issue linkage already in the body). Clause-②: no (prose-only describe edits, accept/reject unchanged) — but the same strings feed customer docs via build-docs.ts, so the PR must carry the full regen set and the gate families the card names. Hard serial: #11052 is in flight (pm:dispatched) on the same generated artifacts — this card dispatches only after its PR lands.

---

Generated by Claude Code

[os-litant]

Claim: PM loop round R6
Session: session_01NDGG54XF5gbTLdQzCtnaVV
Branch: claude/issue-11930-strip-issue-ids-tsdoc
Worktree: objectstack-issue-11930
Domain: domain:spec
File surface: TSDoc/describe lines in packages/spec/src/{conversions,data,ui,automation,ai,api} + regenerated skills/** artifacts (gen:skill-refs, gen:react-blocks) + scripts/check-doc-authoring.mjs exemption tightening + changeset (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus — dispatch-gates 2026-08-25 @0b04839: "no path-derived mandate … The tier stays the PM's per-card judgment call (floor sonnet · default opus · ceiling fable)"; multi-file editorial rewrite + gate-exemption reassessment ⇒ default opus
Clause-②: no
Serial constraints cleared: sources disjoint from batch siblings (action.zod.ts / component.zod.ts / error-code-ledger.zod.ts / contracts/email-service.ts / migrations untouched); skills/** regen sole in batch; scripts/check-doc-authoring.mjs sole writer (in-flight PR #11908 edits a different detector). Net-line budget: skills/** ≤ +0, spec TSDoc ≤ +30, scripts ≤ +10. Governed surface (skills/**) ⇒ PR stays draft for human merge. No pin assertions on sibling behavior.

---

Generated by Claude Code

[os-litant]

Serial-constraint addendum to the R6 claim above (session session_01NDGG54XF5gbTLdQzCtnaVV): the triage comment's hard serial — "#11052 is in flight on the same generated artifacts" — is verified CLEARED before dispatch: #11052 CLOSED (completed) 2026-08-25T03:28Z via PR #11931 MERGED ("Strip internal issue-id references from the published skill catalog, and gate their return"). Consequence folded into the dispatch order: the source-strip here must regenerate against post-#11931 main and align the exemption tightening with the gate that PR added — no second gate.

---

Generated by Claude Code

[os-litant]

File-surface addendum to the R6 claim above (session session_01NDGG54XF5gbTLdQzCtnaVV), filed as the claim is extended rather than after the fact.

The dispatched surface named packages/spec/src/{conversions,data,ui,automation,ai,api}. That directory list was derived from the filing's source attribution, and reverse-looking-up each of the 14 generated sites to its real source line disproves part of it. Two of the six real sources sit outside the named directories:

• packages/spec/src/shared/retry-policy.zod.ts — the #4661 in objectstack-automation/references/_index.md
• packages/spec/src/system/translation.zod.ts — the #4001 in objectstack-i18n/references/_index.md

(The other four are in-surface: data/driver/common.zod.ts, data/driver/config-registry.zod.ts, data/driver/turso.zod.ts, ui/react-blocks.ts.)

Both are taken in place, and the claimed file surface is amended to include them. Same defect class as the card, mechanical rewrite whose correct form is pinned by the 2026-08-23 ruling, same gate families, no new verification surface, and no other in-flight claim holds either file — checked against the open-PR list. Stopping on the two would have delivered a card that closes 12 of its own 14 sites because a guess named the wrong directory.

Also now in the diff, from the same source edit reaching the docs site via build-docs.ts: content/docs/references/data/driver-common.mdx and driver-turso.mdx. The full regen set was called for at dispatch; naming the two files it actually moved.

Not touched, and flagged for routing rather than taken: scripts/check-ratchet-remedy-authority.mjs carries a why string for check-doc-authoring.mjs that names GENERATED_SKILL_ARTIFACTS, the constant this PR removes. The gate itself stays green (its verdict rests on the other declarations, and it was run), but the prose now names a symbol that no longer exists. PR #12061 is in flight on exactly that file and is itself marked blocked on a recorded verdict, so the one-clause repair should ride whichever of the two lands second rather than be raced here.

---

Generated by Claude Code