check:generated 台账缺 `check:variant-docs` 分类——#4177 落地后本地 wrapper 在 main 上直接红

[os-zhuang]

#4177（8c2db68，feat(spec): fail CI when a schema variant is missing from its hand-written doc）往 packages/spec/package.json 加了 check:variant-docs，但没有在 packages/spec/scripts/check-generated.ts 的台账里把它分类进 GATED 或 NO_GENERATOR。台账的双向对账（设计如此）现在在 main 上直接失败：

✗ check:generated ledger is out of sync with package.json:

  `check:variant-docs` exists in package.json but is in neither GATED nor NO_GENERATOR.
    Classify it: does it compare a checked-in artifact against a generator, or audit source?

CI 的两个 job 逐个跑单门，所以 CI 仍绿；红的是 AGENTS.md 让每个改过 spec 的人本地必跑的聚合入口 pnpm --filter @objectstack/spec check:generated——它现在在对账阶段就退出，一个门都不跑。这正是台账存在的意义（「A new check:/gen: script that nobody classified fails the run rather than quietly dropping out of coverage」），只是这次抓到的是 #4177 自己。

修法一行：按 check:variant-docs 的实际性质分类——它审计的是手写文档对 schema variant 的覆盖、没有配套 gen:，应该进 NO_GENERATOR（与 check:liveness 等同类）。若它其实比较 checked-in 产物（packages/spec/variant-docs.json 是 #4177 新增的生成物），则进 GATED 并登记对应 generator。以 #4177 作者的意图为准。

发现于 #4191 的 storage-form 轴工作中（spec 文档改动后按 AGENTS.md 跑 check:generated 时撞上）；与该任务无关，按 Prime Directive #10 单独立项。

[os-zhuang]

已经在 main 上修好了——不过不是单独修的，是 #4194 顺手带上的，所以这个 issue 没有对应 PR。

落地位置：e59786e（fix(spec): five exported symbols resolved to any … (#4194)，2026-07-30 23:44 CST，比本 issue 晚半小时）。#4194 自己要往 package.json 加 check:exported-any，撞上同一堵墙，就把两个都分类了：

// Landed in #4177 while this ledger landed in #4183 — neither PR could see the
// other, so `main` carried an unclassified script and this reconciliation was
// failing on `main` itself. The doc it checks against is hand-written, so there
// is no generator to name.
{ check: 'check:variant-docs', why: 'audits that each schema variant appears in its hand-written doc — no artifact' },

分类结论与本 issue 的推荐一致：NO_GENERATOR，不是 GATED。复核过备选路线——variant-docs.json 虽然是 #4177 新增的 checked-in 文件，但 check-variant-docs.mts 只有 --list，没有写回模式，package.json 里也没有 gen:variant-docs，所以没有 generator 可登记。

验证（在 origin/main e4c2dc8 上跑 check-generated.ts）：对账阶段通过，直接进到

Checking 8 generated artifacts (every gate runs — the first failure does not stop the rest).
…
Not run here (6 source audits with no artifact to regenerate): check:liveness, check:empty-state,
check:react-conformance, check:skill-examples, check:variant-docs, check:exported-any

即 wrapper 不再在对账阶段退出。（这个容器没装依赖，8 个门本身全部因 sh: 1: tsx: not found 而红——环境问题，不是台账问题。）另外手工把双向对账重跑了一遍：packages/spec/package.json 的 15 个 check: 和 10 个 gen: 全部有归属（8 GATED / 6 NO_GENERATOR / 1 SELF；GATED 的 8 个 gen + 2 个 UNGATED_GENERATORS），两个方向都没有落单的。

据此关掉。

---

遗留的复发风险（本 issue 没要求，只记一句，要的话我另开）：让这个 bug 能在 main 上活几个小时的那个结构性缺口还在。ci.yml 的 check-generated job 逐个跑单门，没有任何 job 跑聚合入口 check:generated 本身，所以双向对账从不在 CI 上执行——这次是靠 #4194 恰好撞上才修掉的，不是靠门抓到的。下一个新增 check:/gen: 而没同时改 check-generated.ts 的 PR 会原样复现：CI 全绿，本地 wrapper 红。补法可以很轻，给脚本一个只跑 reconcileLedger 的模式（不跑 8 个门，秒级），在现有 job 里加一步即可。

---

Generated by Claude Code