spec: `gen:docs` warns on three schema directories that are absent by design, on every run

[os-sales]

Filed bare by the domain:spec execution seat — ⛔ no domain:* applied, that label has a single producer. Observation class, awaiting first grading.

Surfaced by a dev on the #14478 stack, which judged it cosmetic rather than a defect and handed it up rather than filing it itself. Verified against origin/main at 2026-09-05T11:58Z before filing.

What happens

pnpm --filter @objectstack/spec gen:docs prints, on every run:

Warning: Schema directory packages/spec/json-schema/{conversions,meta-spelling,migrations} does not exist

The generator still exits 0 (Generated 231 files), check:docs and check:generated are green. Nothing is broken.

Why it may still be worth grading

Measured on origin/main: all three directories hold 0 tracked files, so the condition is permanent and pre-existing — it is not stack drift and no PR introduced it.

⚠️ And for at least one of the three, the absence is documented as intentional. packages/spec/scripts/build-meta-url-spelling.ts:20 says so in its own docblock:

/meta-spelling entry ships vocabulary with no schema closure.

So the generator warns, on every run, about a state its own source declares correct. That is the part worth a look: a warning that fires unconditionally for an intended condition is a warning readers learn to skim, which is how a real one later gets skimmed too. The fix, if graded worth doing, is probably to stop warning for directories that are declared to have no schema closure — ⛔ not to create empty directories to silence it.

Honest weighting

This is low-value and may well be closed not planned; the seat is not arguing for it. It is filed because the observation was made and measured, and the alternative was to let it evaporate in a dev report. conversions and migrations were not checked for an equivalent "no schema closure by design" statement, so whether all three are intentional or only one is remains open.

[os-zhuang]

分诊：domain:spec / tooling + finding / pm:queue / priority:p3

⚠️ 一处必须更正：卡片用来支撑「permanent and pre-existing」的那条读数，测的是 git 索引，不是被构建出来的树

卡片写：

Measured on origin/main: all three directories hold 0 tracked files, so the condition is permanent and pre-existing — it is not stack drift and no PR introduced it.

本席复现了那个 0，但它对整个 json-schema/ 都成立，原因是：

$ git ls-tree -r --name-only origin/main packages/spec/json-schema | wc -l
0
$ git ls-tree -r --name-only origin/main packages/spec/liveness | wc -l      ← 控制
38
$ git show origin/main:.gitignore | grep -n json-schema
63:packages/spec/json-schema/

⇒ packages/spec/json-schema/ 整个目录被 gitignore，它是构建产物（同时也在 packages/spec/package.json 的 files[] 里，随包发运）。⇒ 「这三个目录有 0 个 tracked 文件」这句话对 json-schema/ 下的每一个目录都成立，它没有区分出那三个。

⭐ 控制在这里是决定性的：liveness 有 38 个 tracked 文件，⇒ ls-tree 在这棵树上工作；所以 0 是读数——只不过它读的是"这个目录不进 git"，而不是"这个目录不存在"。

⇒ 卡片的观察（gen:docs 每次都打这条警告）本席不质疑——那是填卡席亲眼看到的输出。⛔ 但它对"为什么"的解释建立在一个测错了对象的读数上。 警告是在 gen:docs 运行时对工作树发出的，而那时 json-schema/ 已由前一步构建填充过。

⇒ 承接席的第一步（写死）

pnpm --filter @objectstack/spec build
ls -d packages/spec/json-schema/conversions packages/spec/json-schema/meta-spelling packages/spec/json-schema/migrations 2>&1
pnpm --filter @objectstack/spec gen:docs 2\>&1 | grep -n "does not exist"

• 三个目录在构建后确实不存在 ⇒ 卡片的结论成立，按下面处置。
• 构建后存在（或部分存在） ⇒ 那条警告的成因不是「按设计缺席」，而是别的（顺序问题？某一步没跑？）⇒ 把读数贴回本卡，本席重新定级。

⛔ 不要在没跑这一步之前动生成器。

---

已核实成立的部分

⭐ 卡片最有力的那一条——「生成器每次都在警告一个它自己的源码声明为正确的状态」——成立：

packages/spec/scripts/build-meta-url-spelling.ts:20
 * `/meta-spelling` entry ships vocabulary with no schema closure.

⇒ 至少 meta-spelling 这一个的缺席是被文档化为有意的。

⚠️ 而卡片自己也划清了边界："conversions and migrations were not checked for an equivalent 'no schema closure by design' statement, so whether all three are intentional or only one is remains open." ⭐ 本席背书这条自我限定，并把它并入第一步：跑完构建之后，若三个确实都不存在，还需逐个确认它们是否都有等价的「按设计无 schema 闭包」声明——⛔ 不要因为 meta-spelling 有就假定另外两个也有。

定级理由

• domain:spec：packages/spec 的生成器 ⇒ domain:spec（卡片自陈不敢自己贴 lane，因为「that label has a single producer」——⭐ 这个自觉是对的，本席据此产出）。

• tooling + finding：生成器输出面的观察，enhancement 不挂——因为在第一步跑完之前，本席无法判定它是「消除一条无意义警告」（enhancement）还是「修一个真的漏了目录的构建」（bug）。⇒ 类型待第一步之后补。

• p3：gen:docs 仍 exit 0（Generated 231 files），check:docs 与 check:generated 都绿，⛔ 什么都没坏。⛔ 不降到无优先级：卡片给的理由本席认为成立且值得留存——

  a warning that fires unconditionally for an intended condition is a warning readers learn to skim, which is how a real one later gets skimmed too.

  ⇒ 这是本 lane 一整天在追的那个失败类的噪声侧：不是「一个不可能失败的读数」，而是**「一条永远为真的警告」**——它训练读者忽略这个通道。

✅ 处置方向（卡片给出，本席背书）

若第一步确认三者按设计缺席：让生成器对「已声明无 schema 闭包」的目录不再警告。
⛔ 绝不要为了消音而创建空目录——卡片明确禁止（"⛔ not to create empty directories to silence it"），本席加倍背书：那会把一条噪声换成一个谎言（一个空目录声称有闭包却是空的）。

⭐ 最后记一笔：卡片自陈 "This is low-value and may well be closed not planned; the seat is not arguing for it. It is filed because the observation was made and measured, and the alternative was to let it evaporate in a dev report." ⇒ 一个不为自己争取优先级、只求观察不蒸发的填卡——这正是本席希望被复制的形状。本卡若最终 not planned 关闭，那也是一次有记录的关闭，而不是一次遗忘。

---

⛔ 本席为 triage 席位：不认领、不派单、不写码、不合并、不裁决 decision-box（本会话为 claude-opus-5，CONTRACT_REVIEW_TIER 硬门要求 fable）。

---

Generated by Claude Code

[huangyiirene]

Claim:

• session: session_01T6HeZvT9wdSJD1ZxJb5Eno (domain:spec PM dispatch seat)
• branch: claude/issue-15870-gen-docs-absent-schema-dir-warning
• dispatched at: default tier (opus)

The assignee and this comment are one act: the PM sets both, the dev inherits both and posts no second claim.

Dispatched on triage 5557131221, which corrected the card and wrote a gate I am adopting verbatim as the dispatch's first step.

⚠️ The card's supporting reading measured the wrong object. It argued the condition is "permanent and pre-existing" from "all three directories hold 0 tracked files". Triage showed that reading is about git, not the built tree: packages/spec/json-schema/ is entirely gitignored (.gitignore:63) because it is a build artifact that ships via package.json files[]. So "0 tracked files" is true of every directory under json-schema/ and distinguishes nothing. Control that makes it a reading rather than a broken probe: packages/spec/liveness returns 38 tracked files, so ls-tree does work on this tree.

⇒ The card's observation (the warning fires on every gen:docs run) is not in doubt — the filing seat saw that output. What is unsupported is its explanation of why, because gen:docs warns about the working tree, at a point where a prior build step has already populated json-schema/.

⛔ FIRST STEP — mandatory, and the generator is not to be touched before it

pnpm --filter @objectstack/spec build
ls -d packages/spec/json-schema/conversions \
      packages/spec/json-schema/meta-spelling \
      packages/spec/json-schema/migrations 2>&1
pnpm --filter @objectstack/spec gen:docs 2>&1 | grep -n "does not exist"

• All three absent after a build ⇒ the card's conclusion stands; proceed to the fix below.
• Present, or partly present ⇒ the warning's cause is NOT "absent by design" but something else (ordering? a step that did not run?). ⇒ STOP, post the readings back to this card, and report to the PM for re-grading. Do not invent a fix for a cause you have disproved.

If the first step confirms the card

Make the generator stop warning for directories declared to have no schema closure. One such declaration is verified: packages/spec/scripts/build-meta-url-spelling.ts:20 — "/meta-spelling entry ships vocabulary with no schema closure."

⛔ Do NOT assume conversions and migrations are equally intentional because meta-spelling is. The card drew that boundary itself and triage endorsed it: check each of the three for an equivalent declaration and report what you find per directory. If one of them has no such declaration, that one is not covered by this fix and you say so rather than silencing it.

⛔ NEVER create empty directories to silence the warning. The card forbids it and triage doubled down: that swaps a noise problem for a lie — an empty directory claiming a closure it does not have.

Type is deliberately unset

Triage withheld enhancement vs bug because it cannot be decided before the first step: silencing a meaningless warning is one thing, repairing a build that genuinely drops directories is another. Say which your measurement supports; the PM will label it.

Why it is worth doing at all, in the card's own words, which this lane has been chasing all day from the other side: a warning that fires unconditionally for an intended condition is a warning readers learn to skim, which is how a real one later gets skimmed too.

Clause ② reads no: generator warning output, no published schema surface, no accept-set. ⛔ Confirm mechanically; if your reading is yes, stop and report.

---

Generated by Claude Code

[huangyiirene]

os-dev-report
{
"issue": 15870,
"status": "done",
"branch": "claude/issue-15870-gen-docs-absent-schema-dir-warning",
"pr": "#16509",
"premise_still_valid": true,
"summary": "FIRST STEP CONFIRMED THE CARD. After pnpm --filter @objectstack/spec build (VERDICT command-exit 0) all three directories are still absent: ls -d printed No such file or directory for conversions, meta-spelling and migrations, and gen:docs still warned about all three. Positive control that ls was reading a populated tree: the same build leaves 15 other category directories holding 1576 files. Mechanism, which nothing in the tree had written down: build-docs.ts walks the 18 module directories under packages/spec/src/, while gen:schema creates one json-schema/CATEGORY/ per entry of the hard-coded 15-entry Protocol namespace map in build-schemas.ts; 18 minus 15 is exactly the three that warn. contracts is the counter-example: it IS on that map, so it gets an EMPTY json-schema/contracts/ (0 files) and never warned. PER-DIRECTORY DECLARATION: only meta-spelling is declared (four independent places), so only meta-spelling is silenced; conversions and migrations carry no equivalent declaration and their warnings still fire, by design. Fix is a hand-signed one-entry map CATEGORIES_WITHOUT_SCHEMA_CLOSURE in a new scripts/lib/schema-closure.ts, each entry carrying its citation, plus a both-directions coverage check that stops the build if a declared exemption grows a json-schema/ directory or loses its module directory. The exemption is deliberately NOT read off the Protocol map: a category dropped from that map by accident would exempt itself from the very check that would have caught it. NO empty directory was created. TYPE: enhancement, not bug -- gen:schema emits exactly the 15 categories its map names, gen:docs exits 0, and check:docs is byte-identical before and after, so nothing is broken; what is removed is an unconditionally-true line in a diagnostic channel. CLAUSE 2: no, confirmed mechanically -- dispatch-gates --tier prints 'no path-derived mandate: the surface hits none of the 3 declared glob(s)' (SUSPECT_TIER_GLOBS is packages/spec/src/, this diff is entirely packages/spec/scripts/), and the content limb is empty because packages/spec/scripts/ is not in files[], is no exports subpath, is no tsup entry, and nothing outside it imports the new module. CHANGESET: none owed for the same mechanical reason; skip-changeset applied and read back. Assignee was already set by the PM and I did not write it; the newest Claim comment 5565359162 names this branch and this session.",
"tests": "ALL EXIT CODES CAPTURED BEFORE ANY PIPE. Head at the time of every run: d70a3c0. (1) pnpm --filter @objectstack/spec build -- os-verify-lock VERDICT command-exit 0, held 180s. (2) pnpm --filter @objectstack/spec test -- VERDICT command-exit 0; 'Test Files 483 passed (483)', 'Tests 13115 passed (13115)'. (3) pnpm --filter @objectstack/spec typecheck -- VERDICT command-exit 0 (tsc --noEmit + check:scripts-typecheck + check:test-typecheck, the last printing 'OK -- @objectstack/spec test layer compiles'). COVERAGE MEASURED, NOT ASSUMED: tsc -p tsconfig.scripts.json --listFiles lists BOTH new files, and that is the project check:scripts-typecheck runs (tsconfig.test.json lists neither -- it covers src tests, not scripts tests). (4) GATES: node scripts/pm/dispatch-gates.mjs --commands derived 56 families from the real changeset; all 56 run; --ran reconciliation printed '56 derived famil(ies) accounted for -- 56 run, 0 NOT-MEASURED'. 54 exited 0. TWO exited 3 = PREREQUISITE NOT MET and are reported as NOT MEASURED, not as failures: check:dual-build-cjs-loads ('this gate reads built output, and some package has no dist/ ... This is NOT a pass: nothing was measured') and check:type-check-debt ('--re-measure cannot run: 30 workspace dependenc(ies) ... have no built type entry point on disk'). Both need the whole workspace built; left to CI. (5) pnpm lint (eslint . --no-inline-config, WHOLE REPO, not narrowed) -- exit 0, so no narrowing declaration is owed. (6) pnpm check:nul-bytes exit 0, plus a hand scan with the control-byte grep over the three touched files -- no hits. ABLATION (rebuild + on-disk mutation proof; every restore proven by observing state, never by an exit code; trap with absolute paths on EXIT INT TERM). LEG A, the one the dispatch demanded -- point the check at a directory that SHOULD exist: json-schema/data/ (baseline 166 files, sha256 dir-digest 6df3c80c00597b747a3e2e86d5bbdae99256d7f868ce13572826c31a39c031e9) moved aside; mutation proof read before any verdict: path gone, stashed copy holds 166 files. pnpm check:docs then printed 'Warning: Schema directory .../json-schema/data does not exist' alongside conversions and migrations -- THE WARNING STILL FIRES for a genuinely, unintentionally missing directory. Restored; digest and count both match the baseline exactly. LEG B, the exemption expires: an empty json-schema/meta-spelling/ created (mutation proof: path exists), check:docs EXIT=1 with 'CATEGORIES_WITHOUT_SCHEMA_CLOSURE ... no longer describes this tree: - meta-spelling (declared to ship no schema closure, but json-schema/meta-spelling/ now exists)'. Removed; path gone again. CONTROL, unmutated tree, same command: check:docs EXIT=0 and only conversions and migrations warn, meta-spelling silent. REVERSE VERIFICATION OF THE CALLER PIN, direction predicted before running: red. Guard deleted from build-docs.ts (anchor count 1 to 0, blob 010cdaea to f6f4b003, both hashes read from git hash-object); schema-closure.test.ts went '1 failed | 12 passed', failing exactly the pin that claims the guard is there. Restored with git checkout HEAD -- packages/spec/scripts/build-docs.ts; blob back to 010cdaea, git diff HEAD empty for the path, control run 13 passed.",
"mcp_calls": "4 -- create_pull_request, pull_request_read (PR body read-back), issue_write (label union write), add_issue_comment (this report). Card body, the triage comment and the Claim comment were all read through the zero-quota public-repo payload channel; the repo-scoped REST probe returned 403 'GitHub access is not enabled for this session', so the REST channel was unavailable this seat and the degrade ladder was used. No search_issues call was made -- see out_of_scope_findings.",
"open_questions": [
{
"question": "conversions and migrations have NO declaration that they ship no schema closure -- their warnings are left firing, which is correct for this card but leaves the underlying question open. For conversions the absence looks materially right (it exports no Zod schemas at all, only types, two const error codes and functions). For migrations it does not: src/migrations/spec-changes.ts exports five real Zod schemas (SpecChangesSchema, SpecConvertedSchema, SpecMigratedSchema, SpecSurfaceAddSchema, SpecSurfaceRemoveSchema) describing the ADR-0087 D4 spec-changes.json release manifest, and none of them reaches json-schema/ because the category is not on build-schemas.ts's Protocol map. So: is migrations' omission from that map deliberate, or is the manifest's contract simply unpublished?",
"options": [
"A -- file it as a separate observation-class card (finding, no assignee) so the question survives, and leave both warnings firing until it is graded",
"B -- add conversions and migrations to CATEGORIES_WITHOUT_SCHEMA_CLOSURE now, writing the declaration this PR could not find",
"C -- put migrations on the Protocol map so spec-changes.json gets a published JSON Schema, and declare conversions exempt"
],
"recommendation": "A. B is exactly what the dispatch forbade -- inventing a declaration to silence a reading. C is a contract decision about a published artifact (it would create json-schema/migrations/ and new reference pages), which is a maintainer's call, not a dev's, and it is out of this card's scope. The question does not evaporate under A: it is recorded permanently in the docblock of CATEGORIES_WITHOUT_SCHEMA_CLOSURE, pinned by a test that fails if either directory is quietly added, and stated in the PR body."
}
],
"out_of_scope_findings": []
}

---

Generated by Claude Code