[finding] nothing holds `content/docs/deployment/cli.mdx`'s two enumerations equal to their source declarations — three measured under-inclusive drifts, all repaired by hand

[claude]

Filed by the domain:cli execution PM seat (#6024, session session_01TSf4DV7ziu4V5j73e46b7c), round R73, 2026-09-11T20:03Z, as the carrier for the mechanism question #16892 raised and could not answer inside its own fence. ⛔ Left unlabelled beyond finding — triage owns domain:*, type and priority. ⛔ Not a defect in what #16892 landed (PR #17722): that PR documents all eleven flags, all three scripts and the --manifest-id condition correctly. This card exists because the next drift has nothing to stop it.

The problem, stated as a record rather than a worry

content/docs/deployment/cli.mdx states two enumerations whose sources live in code, and nothing holds either equal to its source. Measured drift, three times:

• docs(deployment): the CLI reference has no entry for os package publish or os package install — the two commands that move an app onto a platform #8965 — an earlier under-inclusive drift on this same page.
• docs(deployment/cli): two under-documented enumerations — the scaffolded-scripts mapping names two of three, and os lint documents 4 of its 11 declared flags #16892 item ① — the scaffolded-scripts sentence said "these" (three commands) and named two scripts. Under-inclusive since scaffold: create-objectstack creates .github/ but ships no workflow, so every scaffolded app starts with zero CI — the gates exist as npm scripts nothing ever runs #16330, and for all four scaffolders since scaffold: os create writes no lint script, so the two scaffolders now disagree on the generated script set #16350 / PR fix(cli): os init writes a lint script into all three scaffold templates, and a pin holds the two scaffolders equal #16888.
• docs(deployment/cli): two under-documented enumerations — the scaffolded-scripts mapping names two of three, and os lint documents 4 of its 11 declared flags #16892 item ② — os lint declares 11 flags and the page documented 4. Seven undocumented, including --include-platform, which the command names in its own hint, so a reader following that hint arrived at a page that did not mention it.

⇒ three drifts, all in the same direction (under-inclusive), all repaired by hand. ⛔ Hand repair is what produces 4 of 11 in the first place.

The routes, and the seat's recommended direction

A — GENERATE the flag table from the declaration, so the hand-typed form stops being a spelling anyone can get wrong; gate only what generation cannot reach.
B — A NEW GATE in the exact shape of scripts/check-docs-spec-enumerations.mjs (#17388), keyed on Object.keys(Command.flags) per documented command section, refusing if the declaration moves rather than deriving an empty set.
C — leave it hand-maintained.

⭐ Recommended direction: A, then B for the residue. The standing repair order is 「失效修法按序取:先删容许出错的构造,再让正确形态成唯一拼写,最后才加检查」 — a check is the last step. Option A is the "make the correct form the only spelling" step, and it has not happened here. ⛔ C is rejected on the measured record above.

⚠️ The dispatching seat deliberately did NOT charter this. A new mechanism is a new validation surface and sat outside #16892's fence; the choice between A and B belongs to the receiving lane or the maintainer, not to the seat that noticed.

⚠️ Three constraints the dispatched dev measured, which any route must respect

1. ⛔ The obvious cheaper route cannot work. scripts/check-cli-examples-parity.mjs already holds one fence on this very page — measured green here: "5 os package publish invocation(s) in publish.ts (examples) == 5 in the block at content/docs/deployment/cli.mdx:1759". But os lint declares no examples, and an example set and a flag set are different populations: a flag need not appear in any example, so that gate is structurally blind to a missing flag. ⇒ extending it is not the cheap win it looks like.
2. ⛔ No enumeration route covers item ③. A condition is not an enumeration, and the precedent gate says so in its own non-coverage list — verified at source by this seat, scripts/check-docs-spec-enumerations.mjs:92-:93: "mentions a namespace, explains one, or links to one is not an enumeration and is held to nothing." ⇒ whatever is built covers ① and ② only; ③ stays prose and stays unheld.
3. ⭐ Item ①'s SOURCE side is already held by packages/cli/test/scaffold-ci-script-parity.test.ts. What nothing holds is the doc sentence that names them. ⇒ the gap is one-sided, which narrows the work considerably.

⭐ The precedent, and it landed

#15373 (closed, domain:devx, priority:p2) — "no gate reads the CLI transcripts embedded in content/docs — a number quoted from a live registry drifts silently, and four published pages carried a stale one." It produced scripts/check-docs-transcript-drift.mjs, which PR #17722 measured green on this very page ("4 declared transcript value(s) across 402 page(s) … equal what the registry derives today").

⇒ a docs figure held to its source by a gate is already an accepted shape in this repo, on this page, for a different figure family. This card asks for the same treatment of the two enumeration families beside it. ⭐ That precedent is why this is a proposal with a known cost rather than a new idea.

Dedupe

Repo-scoped semantic search returned 7 results; the channel fired rather than going silent, so the absence of a duplicate is a reading.

• docs(deployment/cli): two under-documented enumerations — the scaffolded-scripts mapping names two of three, and os lint documents 4 of its 11 declared flags #16892 (open, closing on PR docs(deployment/cli): derive the two under-documented enumerations from source, and state the manifest-id fallback condition #17722) — the card that raised the question. Its three items are fixed; this card is only the mechanism. ⛔ Not a duplicate.
• no gate reads the CLI transcripts embedded in content/docs — a number quoted from a live registry drifts silently, and four published pages carried a stale one #15373 (closed, landed) — the precedent above, a different figure family (live-registry transcript values, not declared enumerations). ⛔ Adjacent, not this.
• [finding] docs/qa/platform-checklist pins source LINE NUMBERS that no gate resolves — cli.json's manifest.zod.ts citations rotted silently when #13479 shifted the file #13482 (closed) — source line numbers no gate resolves. Same disease, different artefact.
• [finding] cli-build-prerequisite exports CLI and CLI_PKG as CWD-relative constants, so its probe defers on every off-root run of either gate that uses it #11394, [finding] cli checklist: build-own-contract clause 4 vs flag-command-error-ux disagree on exit code 2 — narrow clause 4 to the #4873 duration-leak #7648, [finding] driver-sql hardcodes the os migrate multi-value-columns CLI command id in an operator warning, and nothing fails if the command is renamed #12016, platform-checklist quotes the old --seed-admin contract sentence verbatim, and #14157 changes it #14350 — CLI-gate and checklist findings, all unrelated subjects.

⛔ No open card proposes a generator or gate for CLI docs enumerations.

⚠️ What this card is NOT

• ⛔ Not a reproducible defect, a violated declared contract, or an AI-metadata trap — it is prevention. The dispatched dev noted exactly that and correctly left the filing decision to the seat. It is filed under the 换班报告 mechanizable channel (「可机械化项 → 门禁/脚本卡,⛔ 不是散文」) rather than as one of the three defect classes, and it should be graded on that footing.
• ⛔ Not a claim that docs(deployment/cli): derive the two under-documented enumerations from source, and state the manifest-id fallback condition #17722's page is wrong today. It is correct today; the question is what keeps it correct.

Refs: #16892 (PR #17722) · #15373 · #17388 · #8965 · #16330 · #16350 (PR #16888)

---

Generated by Claude Code