@bongos/core 1.19.305 → 1.19.307

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.305",
-  "core_contract": "1.19.305",
-  "source_commit": "6dc5a84be60b26f11d572eeccf10b8092c7352ae",
+  "core_version": "1.19.307",
+  "core_contract": "1.19.307",
+  "source_commit": "b8d2ed227fd6cb0b948128e23f0daf0070b50bcc",
   "source_ref": "HEAD",
-  "built_at": "2026-08-23T19:20:49.275Z",
+  "built_at": "2026-08-23T20:16:34.186Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 322,
     "agent_docs_stubbed": 22,
-    "functional_verbatim": 1414,
+    "functional_verbatim": 1418,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1758,
-  "tree_sha256": "3a7cd2627a967fe3dbe7edf3dc916b4d728170b826669b64ae457d5e92ac10d1",
+  "file_count": 1762,
+  "tree_sha256": "2ce3db5cb1a893df39826469894f19d4acdee021e5729859eaa8d429933be04d",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -97,7 +97,7 @@
     {
       "path": ".claude/skills/builder-ship/SKILL.md",
       "mode": "0000644",
-      "sha256": "bb9075e768b4cbc6142e2b4b24a57f92e9a4ae75d76f6849566082e0c5495d13"
+      "sha256": "78fcb68ce3ff4b1028904acb9d4d0a37dadd8377108fefef248feef010e4c8b1"
     },
     {
       "path": ".claude/skills/builder-stage/SKILL.md",
@@ -142,7 +142,7 @@
     {
       "path": ".claude/skills/fix-task/SKILL.md",
       "mode": "0000644",
-      "sha256": "2ccc2a59ce44ba21c18db999c86768252b2fa6c8be6fa81f2b00a71eb727e664"
+      "sha256": "59b29fcdf54fe51e85191d1a66be237ef35432b76b26a10ec67e46bf08b4d1d3"
     },
     {
       "path": ".claude/skills/goal-create/SKILL.md",
@@ -212,12 +212,12 @@
     {
       "path": ".claude/skills/otb-tile-generate/SKILL.md",
       "mode": "0000644",
-      "sha256": "cab6aee8bce317982447625d021d862e79c8363a1259d60d109de13331afa1bd"
+      "sha256": "53bfcf6c531c0aeefc1696b470ba6a746f4490501ab092766f42c501f06d453d"
     },
     {
       "path": ".claude/skills/paint/SKILL.md",
       "mode": "0000644",
-      "sha256": "a0ef068b967e8560ead467c790543f707353bee740ce0a7fa0f01c67445119dd"
+      "sha256": "54af43e9417eaa369d9f166e0bbc8567c4540e064504e67ef32186fe31b2f766"
     },
     {
       "path": ".claude/skills/planning-session/SKILL.md",
@@ -1662,7 +1662,7 @@
     {
       "path": "docs/recipes/claude-design-loop.md",
       "mode": "0000644",
-      "sha256": "4f2e7cc445ae05968ba65fcb0c995cb358f144344dcb498047ec753a5a229a39"
+      "sha256": "389dbbbfb7c941315731d533e300b5d43f40a8aac866c5a1c74c32d5be212a22"
     },
     {
       "path": "docs/recipes/core-release-pipeline.md",
@@ -1687,7 +1687,7 @@
     {
       "path": "docs/recipes/figma-design-loop.md",
       "mode": "0000644",
-      "sha256": "0c2c462d59634b9ec0e777d713cbc0bdc5af06408aa8b3717d2afac09c0070f0"
+      "sha256": "6bfee82bddc07a5743316e310dda1e6cb7266fa7805fc1eed67bc8cc17980b46"
     },
     {
       "path": "docs/recipes/gds-db-backup.md",
@@ -4577,12 +4577,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "4678a5bfd751ffe8ac5c3283eb25af2e011ccb14d32032bf373c7c77bcb61a3d"
+      "sha256": "4815e8ce78e80ac2fff7dad9f77bef508e2f0090459c67e59722b65af3e27294"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "5ff86f97c1df0bf8d224512adc339aac2859db0a65e40e7783032b0128f7cbbd"
+      "sha256": "bdeee91142d9d7f3930c99134be76d03f28329222adcf293deaa8f8354ab2cd8"
     },
     {
       "path": "public-docs/index.html",
@@ -5082,7 +5082,7 @@
     {
       "path": "scripts/gds/cli-lib.js",
       "mode": "0000644",
-      "sha256": "95574e210b1fd215b10c7664da109b0698b18aa7724daa736bade6d752318f63"
+      "sha256": "5aa658b099b2acda06cdb3aecfe905da7de79f2b12c844faca091ff061454017"
     },
     {
       "path": "scripts/gds/code.js",
@@ -5189,6 +5189,11 @@
       "mode": "0000644",
       "sha256": "7e279cd4cb8fb0458b8b3be7b0d694e7afcc96eec926abf68b8ccd6afb65429f"
     },
+    {
+      "path": "scripts/gds/doc-cli-guard.js",
+      "mode": "0000644",
+      "sha256": "e7feb497a7b568273d1a2c16c2a65036c60017d163d792d05d3c43addcfd7d8f"
+    },
     {
       "path": "scripts/gds/docs-entropy.js",
       "mode": "0000644",
@@ -5227,7 +5232,7 @@
     {
       "path": "scripts/gds/fitness.js",
       "mode": "0000644",
-      "sha256": "e4399cd9d5283ff23b8c5baf9e7b22a4663cab3f6e0e477b138f279cda50bd72"
+      "sha256": "71f7b70fb6b7b2251c5a335b90faf0b63b51c614829a247679b6f25209549264"
     },
     {
       "path": "scripts/gds/gate-review.js",
@@ -5779,10 +5784,15 @@
       "mode": "0000644",
       "sha256": "087def1396283b19cb8a6deea4cc7f362d7a2f164d496a587220f0a48568aae6"
     },
+    {
+      "path": "scripts/gds/ship-honesty.js",
+      "mode": "0000644",
+      "sha256": "32827178a46cc01c36c422e1adef433be99492e8444a8affbe51e5e8c1e8ce9f"
+    },
     {
       "path": "scripts/gds/ship.js",
       "mode": "0000644",
-      "sha256": "73c2e91340171d6a9112e869552be17e0f82aeb80a5c680205ac452d34c3ddc4"
+      "sha256": "f3005175abc0ba20e958381df6aee02402267e9956da466386656dd4e86ad8cf"
     },
     {
       "path": "scripts/gds/smoke-batch-claim.sh",
@@ -6237,7 +6247,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "a59a54dc09613fc6d95a2efa1262b6d8099fabfb1ef90289462b81accd9c7fea"
+      "sha256": "90436d6db6e32424c48549f61ad48a3a77f5c7cac1ae16d5559b7db76fee7b4a"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -7019,6 +7029,11 @@
       "mode": "0000644",
       "sha256": "d9fd04cc3f2fcb3b4a9945c1e743c44445a216a10648fa619f74716b381468f3"
     },
+    {
+      "path": "tests/doc_cli_guard.mjs",
+      "mode": "0000644",
+      "sha256": "4e68c67489daa51167b8d738a36f7c0187016b342e8a57731d14241563262878"
+    },
     {
       "path": "tests/docs_entropy.mjs",
       "mode": "0000644",
@@ -8272,7 +8287,7 @@
     {
       "path": "tests/route_rank_check.mjs",
       "mode": "0000644",
-      "sha256": "1cb0af04d3f0f837ab19c5c821e91ca7a183f2744608d7ee3b79b4886fbbd4ed"
+      "sha256": "bdc58224050392ece492ae8e8f12f62a8934d86e3993e0df5b8cb0aac80602e8"
     },
     {
       "path": "tests/route_validation.mjs",
@@ -8494,6 +8509,11 @@
       "mode": "0000644",
       "sha256": "afdb09a3ee072fea82390a187c12c42d8249fce0ce84644a4b8dff6a643dd009"
     },
+    {
+      "path": "tests/ship_cannot_lie.mjs",
+      "mode": "0000644",
+      "sha256": "82f6f951cc50c34860545be0f309e18a796ebb5baa712ccb341e1fd0dd72a233"
+    },
     {
       "path": "tests/ship_card.mjs",
       "mode": "0000644",
@@ -8542,7 +8562,7 @@
     {
       "path": "tests/ship_smoke_gate.mjs",
       "mode": "0000644",
-      "sha256": "43e2f109ce85e99e71daa4573a6ec4fc591b167fe81ee02f2f73ea1ce84d465c"
+      "sha256": "6ce7bd5d2a8910e201a9869c8a3f22ef210fd4400fbd14777d8d15d13252a97e"
     },
     {
       "path": "tests/ship_upload_skip.mjs",

package/.claude/skills/builder-ship/SKILL.md

@@ -7,7 +7,7 @@ You are shipping a task on behalf of the current builder. Shipping is the moment
 
 ## What this skill does
 
-Runs `node scripts/gds/ship.js <task-id> --notes "..." --summary "..."`.
+Runs `node scripts/gds/ship.js <task-id> --notes-file notes.md --summary-file summary.txt`.
 
 The CLI drives a **three-state lifecycle** with a subagent grader between states (Phase 5, 2026-05-10):
 
@@ -34,7 +34,7 @@ The CLI drives a **three-state lifecycle** with a subagent grader between states
 
    **When you see that block, position the sandbox link prominently for the builder.** `ship.js` also emits the deterministic lifecycle card for the `review` stage (an `[otb-card-html] <path>` marker) — if an in-feed visualization tool is available, render that card (its primary action is **Open in sandbox ↗**, the URL); it's the cleanest way to make the link impossible to miss. Either way, surface the URL as its own standalone, clickable line in chat — a clear callout, NOT buried inside a paragraph of command output — and say in one line what to look at. This is the moment the change is ready to review; the link must be impossible to miss. Let the builder open it, review, and suggest changes; iterate if needed. **Only once the builder explicitly approves, re-run with `node scripts/gds/ship.js <id> --approved`** — that records their sign-off as a durable `sandbox_review` fact on the task (who, when, and the content stamp of exactly what was reviewed). Never pass `--approved` yourself without a real human go; the pause + sign-off IS the feature. `--skip-stage` is the escape hatch (use sparingly — the gate exists so unreviewed game changes don't ride straight to prod). Laptop sessions and non-game diffs are unaffected.
 
-2. **Compose the handoff notes (`--notes`)** following the structure in `docs/handoff-template.md`:
+2. **Compose the handoff notes (`--notes-file`)** following the structure in `docs/handoff-template.md`:
    - What shipped (with confidence tags: verified-prod | verified-smoke | implemented-not-verified)
    - What's broken or unverified
    - Manual checks the next session should run first
@@ -52,16 +52,28 @@ The CLI drives a **three-state lifecycle** with a subagent grader between states
    - "Sessions can claim work atomically; merge conflicts can't happen across worktrees."
    No jargon, no file paths, no commit hashes.
 
-4. **Run**:
+4. **Run** — write the prose to files and pass the file (task 1003168):
    ```bash
-   node scripts/gds/ship.js <task-id> \
-     --notes "$(cat <<'EOF'
-   ...handoff markdown...
-   EOF
-   )" \
-     --summary "the one-liner"
+   # write notes.md and summary.txt with your editor/Write tool first
+   node scripts/gds/ship.js <task-id> --notes-file notes.md --summary-file summary.txt
    ```
 
+   **Use the `-file` forms.** Handoff notes are technical prose, so they contain
+   backticks — and a backtick in an inline `--notes "..."` is command-substituted
+   by the shell *before* node runs: the span executes, its output replaces it, and
+   the rest of the argument list is truncated. That is not hypothetical; it shipped
+   a task with **empty notes and no summary**, so the ledger held nothing about a
+   session that had happened (learning 1000197). A file argument is the one form
+   the shell cannot rewrite. `-` reads stdin if you'd rather pipe.
+
+   Inline `--notes "..."` / `--summary "..."` still work for short prose with no
+   backticks, `$`, or newlines. The older documented form —
+   `--notes "$(cat <<'EOF' … EOF)"` — is *also* shell-safe, because the quoted
+   heredoc delimiter suppresses expansion; it is simply easy to get subtly wrong,
+   and when you do the failure is silent. Passing both `--notes` and
+   `--notes-file` is refused rather than resolved by precedence, so nothing you
+   wrote is dropped without a word.
+
    **Never merge a task branch to main before running `ship.js`.** `ship.js` diffs the claim branch against `main`; an already-merged branch yields an empty diff, and the only exits are `--allow-empty` (dead-ends the task at `completed`, requiring an Archon-only confirm) or reverting the merge. Ship from the branch, then let `ship.js` land it. (This trap was hit on tasks 1002417 and 1002419, producing blockers 1000081/1000082 and an ~8.5-hour stall.)
 
 5. **Render the completion card — it IS the summary; do NOT write a prose recap (task 1270).**

package/.claude/skills/fix-task/SKILL.md

@@ -39,7 +39,7 @@ Runs the recurring "claim, fix, and ship task NNNN" macro end to end. Its own va
 
 6. **Ship from the claim branch** — see `/builder-ship` for handoff notes, the value summary, and the completion-card rendering contract. In short:
    ```
-   node scripts/gds/ship.js <id> --notes "..." --summary "..."
+   node scripts/gds/ship.js <id> --notes-file notes.md --summary-file summary.txt
    ```
    **Never merge the claim branch into `main` before running `ship.js`.** `ship.js` diffs the branch against `main`; a pre-merged branch yields an empty diff, and the only way out is `--allow-empty` (dead-ends the task at `completed`, needing an Archon-only confirm) or reverting the merge. Ship from the branch and let `ship.js` land it — the same trap `/builder-ship` calls out.
 

package/.claude/skills/otb-tile-generate/SKILL.md

@@ -30,7 +30,7 @@ Runs `modules/art-pipeline/pipeline/orchestrator.py` for the requested tiles. Th
 
    **View it on your sandbox without placing it in-game** (#1262): every tile you've generated — native + zoomed, with its score and critique — is served at **`https://sandbox-<login>.example.com/art`** (locally: `http://localhost:<port>/art`). This is the generated-art *gallery* (`modules/art-pipeline/generated/preview.html`), so you can show the builder what they made even when the tile isn't placed in the world yet. The atlas-rebuild in-game step below is only needed once you actually want it *in the playable world*.
 
-6. **See it in-game on your sandbox** (#1067): run `node scripts/gds/art-stage.js` — it rebuilds the atlas the client loads, surfaces it on your sandbox live preview (`sandbox-<login>.example.com`, ADR 0044), and prints the URL + affected tiles. With the auto-reload (task 1065) an already-open tab refreshes itself. (The family/refresh runs also accept `--stage` to do this automatically: `family_orchestrator.py <id> --publish --stage`, `refresh_all.py --stage`.) Only a genuinely NEW base-tile *type* still needs a `public/game/world/tilePalette.js` mapping edit; an updated existing tile just needs the atlas rebuild above.
+6. **See it in-game on your sandbox** (#1067): run `node scripts/gds/art-stage.js` (**ships with the `art-pipeline` host module, not the portable core** — absent from a core-only checkout, where this step doesn't apply) — it rebuilds the atlas the client loads, surfaces it on your sandbox live preview (`sandbox-<login>.example.com`, ADR 0044), and prints the URL + affected tiles. With the auto-reload (task 1065) an already-open tab refreshes itself. (The family/refresh runs also accept `--stage` to do this automatically: `family_orchestrator.py <id> --publish --stage`, `refresh_all.py --stage`.) Only a genuinely NEW base-tile *type* still needs a `public/game/world/tilePalette.js` mapping edit; an updated existing tile just needs the atlas rebuild above.
 
 ## Constraints
 

package/.claude/skills/paint/SKILL.md

@@ -40,7 +40,7 @@ Ground every asset in the locked theme so nothing drifts:
 1. **Establish the visual target first, not in prose.** Confirm the subject (an existing vocab id, or a new in-world prop/plant/animal/accessory) and, if helpful, show the reference cluster it should sit beside. One or two lines, then move to making.
 2. **Generate via the pipeline — never freelance.** Drive `/otb-tile-generate` (which runs `modules/art-pipeline/pipeline/orchestrator.py`: generate → post-process to 32×32 → score against rubric → retry up to 5 tiers → save to `modules/art-pipeline/generated/tiles/<id>.png`, logging cost). Check the budget first (`python3 modules/art-pipeline/pipeline/cost_ledger.py status`; hard stop at $80) — but report it as one line.
 3. **SHOW the result.** Display the final accepted PNG and its rubric score. The gallery serves every tile (native + zoomed, with score + critique) at `sandbox-<login>.example.com/art` — point them there and/or render the image inline. **Default visibility: show the final accepted asset and any failures. Show the intermediate retry attempts only if the artist asks ("show me the attempts").**
-4. **See it in the world.** When they want it placed, run `node scripts/gds/art-stage.js` — it rebuilds the atlas and surfaces the asset live in the game on their sandbox (auto-reloads an open tab). Screenshot/point at the in-world view. (A genuinely new base-tile *type* also needs a `public/game/world/tilePalette.js` mapping edit; an updated existing tile just needs the rebuild.)
+4. **See it in the world.** When they want it placed, run `node scripts/gds/art-stage.js` (**ships with the `art-pipeline` host module, not the portable core** — on a core-only checkout the file is absent and this step doesn't apply) — it rebuilds the atlas and surfaces the asset live in the game on their sandbox (auto-reloads an open tab). Screenshot/point at the in-world view. (A genuinely new base-tile *type* also needs a `public/game/world/tilePalette.js` mapping edit; an updated existing tile just needs the rebuild.)
 5. **Feedback is visual → a durable rule.** When the artist reacts ("too saturated", "trees too modern", "weather the marble"), don't just tweak once — run `/otb-feedback-capture` to write the note into `modules/art-pipeline/template/style_guide.md` as a dated rule, then regenerate and **show the new result**. The loop is see → react → see again, and the style guide gets smarter each pass.
 6. **Use `/otb-design-review`** when you want a rubric-grounded second opinion on whether an asset truly hits the bar — surface its numbers, not a paragraph.
 

package/docs/recipes/claude-design-loop.md

@@ -113,7 +113,7 @@ The adapter writes files to `src/ui/<surfaceId>/` and updates `config/design-sou
 ```bash
 git add src/ui/hall-ui/ config/design-sources.json
 git commit -m "ui(hall-ui): Claude Design export (task 1234)"
-node scripts/gds/ship.js 1234 --notes "..." --summary "..."
+node scripts/gds/ship.js 1234 --notes-file notes.md --summary-file summary.txt
 ```
 
 ---

package/docs/recipes/figma-design-loop.md

@@ -98,7 +98,7 @@ The adapter translates frames/text/solid-fill rectangles into `.js` + `.css` fil
 ```bash
 git add src/ui/hall-ui/ config/design-sources.json
 git commit -m "ui(hall-ui): Figma export (task 1234)"
-node scripts/gds/ship.js 1234 --notes "..." --summary "..."
+node scripts/gds/ship.js 1234 --notes-file notes.md --summary-file summary.txt
 ```
 
 ---

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.305",
+  "version": "1.19.307",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.305",
+      "version": "1.19.307",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.305",
+  "version": "1.19.307",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/cli-lib.js

@@ -266,6 +266,58 @@ function stripBom(s) {
   return s.charCodeAt(0) === 0xfeff ? s.slice(1) : s;
 }
 
+// argText(name, args, io) — resolve prose passed EITHER inline (`--notes "..."`)
+// or from a file (`--notes-file path`, or `-` for stdin). Returns
+// { value, source, error }: `value` is a string ('' when neither flag is
+// present), `source` is 'inline' | 'file' | 'stdin' | 'none', and `error` is a
+// caller-printable string when the request was refused or unreadable.
+//
+// WHY THIS EXISTS (learning 1000197). Prose handed to a CLI inline goes through
+// the SHELL first. A handoff note containing backticks — which technical prose
+// constantly does — is command-substituted by bash before node ever runs: the
+// backticked span executes, its output replaces it, and the rest of the argument
+// list is truncated. That is not a theoretical hazard; it silently shipped a task
+// with EMPTY notes and no summary, so the ledger recorded nothing about a session
+// that had happened. A file argument is the only form the shell cannot rewrite.
+//
+// BOTH-GIVEN IS AN ERROR, never a silent precedence. Picking one would mean the
+// caller's other input vanished without a word — the same class of quiet loss
+// this helper exists to end (the capture.js --spark/--full refusal precedent).
+function argText(name, args = process.argv.slice(2), io = {}) {
+  const readFile = io.readFile || ((f) => require('fs').readFileSync(f, 'utf8'));
+  const readStdin = io.readStdin || (() => require('fs').readFileSync(0, 'utf8'));
+  const fileFlag = `${name}-file`;
+  const inline = arg(name, args);
+  // arg() returns undefined (not null) for a flag present as the LAST token, so
+  // presence must be tested separately — otherwise `--notes-file` with no path
+  // slips past the null check and resolves to an empty string, which is the very
+  // silent-empty outcome this helper exists to prevent.
+  const filePresent = args.includes(fileFlag) || args.some((a) => a.startsWith(`${fileFlag}=`));
+  const file = filePresent ? arg(fileFlag, args) : null;
+
+  if (inline != null && filePresent) {
+    return {
+      value: '', source: 'none',
+      error: `${name} and ${fileFlag} were both given. Pass one — ${fileFlag} is the safe form for prose `
+        + '(a shell rewrites backticks in an inline value before node sees it). Refusing rather than '
+        + 'silently picking one, so nothing you wrote is dropped without a word.',
+    };
+  }
+  if (filePresent) {
+    if (file == null || file === '' || file.startsWith('--')) {
+      return { value: '', source: 'none', error: `${fileFlag} needs a path (or - for stdin).` };
+    }
+    try {
+      const raw = file === '-' ? readStdin() : readFile(file);
+      return { value: stripBom(String(raw)), source: file === '-' ? 'stdin' : 'file', error: null };
+    } catch (err) {
+      return { value: '', source: 'none', error: `could not read ${fileFlag} ${file}: ${err.message}` };
+    }
+  }
+  if (inline != null) return { value: inline, source: 'inline', error: null };
+  return { value: '', source: 'none', error: null };
+}
+
 // resolveQuiet(args, env) — true when api.js's stderr status banner should be
 // suppressed: the --quiet flag or the GDS_QUIET env var. Both default to the
 // live process, matching hasFlag()'s own default-args contract. Default OFF —
@@ -853,6 +905,7 @@ module.exports = {
   loadSessionSync,
   saveSession,
   arg,
+  argText,
   hasFlag,
   stripBom,
   repairMsysMangledPath,

package/scripts/gds/doc-cli-guard.js

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+// scripts/gds/doc-cli-guard.js — a doc that NAMES a CLI invocation must match the
+// real CLI (task 1003165 / G01, goal 1000077; criterion guards-doc-names-a-command).
+//
+// WHY. Task 1002931 shipped a skill instructing `capture.js --full --fields-file`
+// while those flags lived on an unlanded branch. Its test passed, because the test
+// pinned the skill's PROSE — it asserted the file said the words, never that the
+// words worked. So the skill confidently told agents to run a command that
+// silently ignored both flags and filed the wrong thing. That is the whole class:
+// AN UNRECOGNISED FLAG IS NOT AN ERROR. `arg('--x')`/`hasFlag('--x')` return null
+// and the command proceeds, so a doc can name a flag that does nothing and every
+// test stays green (learning 1000198). It happened TWICE in one session: the
+// second time /workspace ran an older capture.js and the same documented flags
+// were dropped on the floor again.
+//
+// WHAT IT CHECKS, deliberately narrow: for every `node scripts/gds/<x>.js` in a
+// tracked .md, (a) the script exists, and (b) each `--flag` written next to it
+// appears in that script's source. Nothing else — this is not a prose linter.
+//
+// STATIC ONLY, NEVER EXECUTED. The reason matters: running every documented CLI
+// would be slow, would need a session, and a command that blocks on a prompt
+// would hang CI forever — the exact failure R151's TTY gate exists to prevent.
+//
+// It lives in its OWN FILE rather than in fitness.js because fitness.js is already
+// over the size ratchet (config/fitness-baselines.json) — the control-manifest.js
+// precedent. fitness.js requires it in CHECKS.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('node:child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+// ---------------------------------------------------------------------------
+// Check 22 — a doc that NAMES a CLI invocation must match the real CLI
+// (task 1003165 / G01, goal 1000077).
+//
+// WHY. Task 1002931 shipped a skill instructing `capture.js --full --fields-file`
+// while those flags lived on an unlanded branch. Its test passed, because the test
+// pinned the skill's PROSE — it asserted the file said the words, never that the
+// words worked. So the skill confidently told agents to run a command that
+// silently ignored both flags and filed the wrong thing. That is the whole class:
+// AN UNRECOGNISED FLAG IS NOT AN ERROR. `arg('--x')`/`hasFlag('--x')` just return
+// null and the command proceeds, so a doc can name a flag that does nothing and
+// every test stays green (learning 1000198).
+//
+// It happened TWICE in one session: the second time, /workspace ran an older
+// capture.js and the same documented flags were dropped on the floor again.
+//
+// WHAT IT CHECKS, deliberately narrow: for every `node scripts/gds/<x>.js` in a
+// tracked .md, (a) the script exists, and (b) each `--flag` written next to it is
+// parsed by that script. Nothing else — this is not a linter for prose.
+//
+// STATIC ONLY, NEVER EXECUTED. The task says so and the reason matters: running
+// every documented CLI from a fitness check would be slow, would need a session,
+// and a command that blocks on a prompt would hang CI forever — the exact failure
+// R151's TTY gate exists to prevent.
+// Key is `<doc path>::<token>`, where token is either the script path (the whole
+// invocation is tolerated) or `--flag` (just that flag). Every entry carries its
+// reason on the same line: an unexplained entry is a silent hole, and the point of
+// this check is that a doc's claims are checkable.
+const DOC_CLI_ALLOW = new Map([
+  ['.claude/skills/paint/SKILL.md::scripts/gds/art-stage.js',
+    'art-stage.js ships with the art-pipeline HOST module, which publish-manifest.js excludes from core — absent from a core-only checkout by design; the skill says so inline.'],
+  ['.claude/skills/otb-tile-generate/SKILL.md::scripts/gds/art-stage.js',
+    'same as paint/SKILL.md — the art staging CLI travels with the excluded art-pipeline module, not the portable core.'],
+]);
+
+// `node scripts/gds/foo.js` … up to the end of the line/segment, so the flags that
+// follow travel with the script that owns them.
+const DOC_CLI_RE = /node\s+(scripts\/gds\/[A-Za-z0-9._-]+\.js)([^\n`]*)/g;
+// A long flag only. Short flags and bare words are ignored: too many false
+// positives from prose, and the failure this guards is long-flag drift.
+const DOC_FLAG_RE = /(?<![\w-])--([A-Za-z][A-Za-z0-9-]*)/g;
+
+// Flags every CLI inherits from shared arg plumbing rather than naming itself.
+const UNIVERSAL_FLAGS = new Set(['quiet', 'help', 'dry-run', 'json']);
+
+// Does `script` know about `--flag` AT ALL?
+//
+// This deliberately asks the WEAK question — does the literal appear anywhere in
+// the source — and not the strong one ("is it wired into arg parsing"). The first
+// draft of this check asked the strong question, matching `arg('--x')` and
+// `hasFlag('--x')`, and produced FIVE false positives out of nine hits on its
+// first real run: triage.js parses via `argv.indexOf('--development')`,
+// provision.js via `hasFlag(args, '--apply')`, oauth-secret.js via
+// `argVal(args, '--client-id')`, status.js via `a === '--widget'`, and
+// validate-design.js via `ARGS.has('--strict')`. Every one of those is correct
+// code that the strong check called broken.
+//
+// The set of ways to read an argv in JavaScript is open-ended, so a check that
+// enumerates them will keep growing false positives forever — and a fitness check
+// that cries wolf gets muted, which costs more than the drift it was catching.
+// The weak question is ONE-DIRECTIONAL and therefore sound: a script whose source
+// never contains the string `--full` cannot possibly honour `--full`, whatever
+// idiom it uses. That is exactly the failure this exists for (learning 1000198:
+// /workspace ran a capture.js from before those flags existed, and both were
+// silently dropped). A stale usage comment naming a removed flag slips through —
+// accepted, deliberately: guessing which mentions are "real" is how the strong
+// version went wrong.
+function scriptMentionsFlag(src, flag) {
+  const f = flag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  // Trailing guard so `--client` does not match `--client-id`.
+  return new RegExp(`--${f}(?![\\w-])`).test(src);
+}
+
+// The scan CORE. IO is injected — `readDoc(path)` and `readScript(path)` both
+// return source or null — so a test can exercise a DRIFTED doc without writing
+// a broken file into the tree (the control-manifest.js `evaluate` precedent).
+// A check that cannot be shown to fail is not evidence of anything, which is
+// precisely how task 1002931's prose-pinning test let the bad skill through.
+function scanDocs(docs, { readDoc, readScript, allow = DOC_CLI_ALLOW } = {}) {
+  const violations = [];
+  const warnings = [];
+  let invocations = 0;
+  const srcCache = new Map();
+  const script = (rel) => {
+    if (!srcCache.has(rel)) srcCache.set(rel, readScript(rel));
+    return srcCache.get(rel);
+  };
+
+  for (const doc of docs) {
+    const text = readDoc(doc);
+    if (text === null) continue;
+    DOC_CLI_RE.lastIndex = 0;
+    let m;
+    while ((m = DOC_CLI_RE.exec(text))) {
+      const scriptRel = m[1];
+      const tail = m[2] || '';
+      invocations += 1;
+      const src = script(scriptRel);
+      if (src === null) {
+        if (!allow.has(`${doc}::${scriptRel}`)) {
+          violations.push(
+            `${doc} → \`node ${scriptRel}\` names a script that does not exist. `
+            + 'An agent following this doc gets MODULE_NOT_FOUND. Fix the path, or allowlist it in DOC_CLI_ALLOW with a reason.'
+          );
+        }
+        continue;
+      }
+      // A whole-invocation allowlist covers its flags too — the script isn't here to check them against.
+      if (allow.has(`${doc}::${scriptRel}`)) continue;
+      DOC_FLAG_RE.lastIndex = 0;
+      let f;
+      while ((f = DOC_FLAG_RE.exec(tail))) {
+        const flag = f[1];
+        if (UNIVERSAL_FLAGS.has(flag)) continue;
+        if (allow.has(`${doc}::--${flag}`)) continue;
+        if (scriptMentionsFlag(src, flag)) {
+          // The criterion asks that the flag be PARSED, not merely present. The
+          // hard check can only prove presence (see scriptMentionsFlag), so the
+          // residual gap — a flag surviving in a usage comment after the code that
+          // read it was deleted — is reported as a WARNING, not a failure. Warning
+          // rather than failing is the deliberate choice: a usage banner is the
+          // ONLY place some scripts name a flag they genuinely handle via a helper,
+          // so failing here would resurrect the false positives that sank draft 1.
+          if (!scriptMentionsFlag(stripLineComments(src), flag)) {
+            warnings.push(
+              `${doc} → \`node ${scriptRel} --${flag}\`: ${scriptRel} names \`--${flag}\` only in comments/usage text, `
+              + 'never in code — it may be a flag whose implementation was deleted. Verify it is still handled.'
+            );
+          }
+        } else {
+          violations.push(
+            `${doc} → \`node ${scriptRel} --${flag}\`: ${scriptRel} never mentions \`--${flag}\` anywhere in its source, so it cannot honour it. `
+            + 'An unrecognised flag is silently IGNORED, not an error — so the documented command does the wrong thing while every test stays green. '
+            + 'Add the flag, fix the doc, or allowlist it in DOC_CLI_ALLOW with a reason.'
+          );
+        }
+      }
+    }
+  }
+  return { violations, warnings, invocations };
+}
+
+// Drop `//` line comments and `/* */` blocks — enough to tell "named in code" from
+// "named only in a usage banner". Not a JS parser, and it does not need to be: a
+// false split here downgrades a warning, never a failure.
+function stripLineComments(src) {
+  return String(src)
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .split('\n')
+    .map((l) => l.replace(/(^|\s)\/\/.*$/, '$1'))
+    .join('\n');
+}
+
+// Tracked markdown, via an argv ARRAY and never a shell string: `git ls-files
+// '*.md'` as a string goes through cmd.exe on Windows, where the quotes are
+// literal, git matches nothing, and the scan silently reports on zero files
+// (task 1002526).
+function trackedMarkdown() {
+  const out = execFileSync('git', ['ls-files', '*.md'], {
+    cwd: REPO_ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return String(out || '').split('\n').map((f) => f.trim()).filter(Boolean);
+}
+
+const readFileOrNull = (rel) => {
+  try { return fs.readFileSync(path.join(REPO_ROOT, rel), 'utf8'); } catch { return null; }
+};
+
+const NAME = 'a doc that names a CLI matches the real CLI (G01)';
+
+function checkDocNamesRealCli({ files = null } = {}) {
+  const docs = files || trackedMarkdown();
+  // A lint that reports on nothing is worse than one that fails (the
+  // docs-entropy precedent) — this repo tracks hundreds of .md files, so an
+  // empty enumeration is a broken scan, not a clean result.
+  if (!docs.length) {
+    return {
+      name: NAME, ok: false, hardFail: true,
+      violations: ['scan defect — enumerated 0 tracked markdown files; a broken enumeration, not a clean result.'],
+      warnings: [], note: 'static scan of documented `node scripts/gds/*.js` invocations.',
+    };
+  }
+
+  const { violations, warnings, invocations } = scanDocs(docs, {
+    readDoc: readFileOrNull, readScript: readFileOrNull,
+  });
+
+  return {
+    name: NAME,
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings,
+    note: `${invocations} documented \`node scripts/gds/*.js\` invocation(s) across ${docs.length} tracked .md file(s): the script exists and every long flag it is written with appears in that script's source. Static — never executes a CLI (a documented command that blocks on a prompt would hang CI). ${DOC_CLI_ALLOW.size} allowlisted.`,
+  };
+}
+
+function main() {
+  const r = checkDocNamesRealCli();
+  for (const v of r.violations) console.error(`\u2717 ${v}`);
+  console.log(`${r.hardFail ? 'FAIL' : 'PASS'}  ${r.note}`);
+  process.exit(r.hardFail ? 1 : 0);
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  checkDocNamesRealCli, scanDocs, trackedMarkdown, scriptMentionsFlag, stripLineComments,
+  DOC_CLI_ALLOW, DOC_CLI_RE, DOC_FLAG_RE, UNIVERSAL_FLAGS,
+};