@bongos/core 1.19.304 → 1.19.306

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.304",
-  "core_contract": "1.19.304",
-  "source_commit": "8c22da0cc4ab95a1684933ef98112abb201bc850",
+  "core_version": "1.19.306",
+  "core_contract": "1.19.306",
+  "source_commit": "bfb69ddea49ebcce6d1d0608dd8e1fc50cc755e2",
   "source_ref": "HEAD",
-  "built_at": "2026-08-23T19:13:32.623Z",
+  "built_at": "2026-08-23T19:41:29.546Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 322,
     "agent_docs_stubbed": 22,
-    "functional_verbatim": 1413,
+    "functional_verbatim": 1416,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1757,
-  "tree_sha256": "644acfeea1c7e902934e366c56379f0191e6de8e08e6338567155722b916b2fd",
+  "file_count": 1760,
+  "tree_sha256": "a2c3f65e69e891c0076d0b10268d3549cfddf8d76d1f320274e86fd833d56013",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -177,7 +177,7 @@
     {
       "path": ".claude/skills/ideate/SKILL.md",
       "mode": "0000644",
-      "sha256": "8c89cdb688f39e9ca9009cfb0345f8f75fb12ff91de31914d410c5b7f78d18c2"
+      "sha256": "7e2c13e70e3ac208c4754f32685c2453c501f35b3742310ee49a5855bc0c399b"
     },
     {
       "path": ".claude/skills/merge-mode/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",
@@ -4577,12 +4577,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "3f027a59178132ea747301cbcc78f7404c0f0ec820c6651affcf8854b1cf70f3"
+      "sha256": "ab53e6d02f437a24895dd3d04b3e8ef39ddf4257b8c4b2e784a84dd10820adc4"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "79d94ba55244fa52d3f8f35717803666064daecb4d91d5547060baaa2143692d"
+      "sha256": "c98acd264e43f570b82f0c7c72efb952d6e68758794f4c49a78db06cf44a867f"
     },
     {
       "path": "public-docs/index.html",
@@ -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",
@@ -6237,7 +6242,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "b8db1ca313e0156a5891a779be650f8c56069015529e064a18b8e4970e7e312f"
+      "sha256": "31f8e9579aa3e015fc2c1f819d5d84076db27e831bfb3419ca48141cbcd84038"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -7019,6 +7024,11 @@
       "mode": "0000644",
       "sha256": "d9fd04cc3f2fcb3b4a9945c1e743c44445a216a10648fa619f74716b381468f3"
     },
+    {
+      "path": "tests/doc_cli_guard.mjs",
+      "mode": "0000644",
+      "sha256": "4e68c67489daa51167b8d738a36f7c0187016b342e8a57731d14241563262878"
+    },
     {
       "path": "tests/docs_entropy.mjs",
       "mode": "0000644",
@@ -7564,6 +7574,11 @@
       "mode": "0000644",
       "sha256": "1e6d0784ecb37e613561cc8ee45fa23e178ecf112d5a8f218b9795dca0e7d0fc"
     },
+    {
+      "path": "tests/idea_ideate_full.mjs",
+      "mode": "0000644",
+      "sha256": "5000ed6a7b1a24eced0f070e556af354c8fa9c7937f43c7b932a3ca29f8a5f35"
+    },
     {
       "path": "tests/idea_quick_guard.mjs",
       "mode": "0000644",

package/.claude/skills/ideate/SKILL.md

@@ -72,6 +72,76 @@ The body should carry the development, not just a sentence. Use these line-tag c
 - The developed block when you have it: `surfaces:`, `risks:`, `open questions:`.
 - In autonomous mode only: `origin: autonomous`.
 
+## Authoring a FULL IDEA in conversation (task 1002931 / BV1.R155)
+
+A **Full Idea** is the ideator craft's real output: five answered questions that
+are a baseline scope of work someone else can deliver against *without
+re-interviewing the person who had the thought*. Drawing those five answers out
+of a conversation is exactly this skill's dynamic — and it is the path for
+someone who thinks by talking rather than by filling in a form.
+
+**Get the questions from the template, never from memory.** They are declared
+once, as data, and a project can define its own:
+
+```
+node scripts/gds/spark.js --template
+```
+
+That prints each field, its label, and the substance floor the scorer expects.
+Ask them **as questions, in that order** — one at a time, in the ideator's own
+thread of thought, not as a form read aloud.
+
+### The rule that governs this whole section: you write down what they said
+
+You are already "the instrument, not the author". Here that stops being a stance
+and becomes a hard constraint, because **the completeness score is deterministic
+and it feeds credits** (R142 scores substance; ADR 0172 pays on it). If you
+ghost-write a field, the number is fraudulent and the builder is paid for your
+words. So:
+
+- **Never invent field content.** Not a sentence, not a clause.
+- **Never pad a thin answer** to clear the floor. A short answer scores short —
+  that is the scorer working, not a problem to fix.
+- **Never polish an answer into words they did not use.** Tightening *their*
+  phrasing when they ask is help; rewriting it is authorship.
+- **An unanswered question stays empty.** If they do not want to answer "why does
+  it matter", file it without that field and let the score say so. A Full Idea
+  with a gap is honest; a Full Idea you completed for them is not.
+- What you *should* do is what this skill is for: **press on a thin answer.**
+  "That is one line — what is behind it?" is the sounding board doing its job.
+  Their next sentence is theirs. Yours would not be.
+
+Read the answers back before filing and let them correct you. They bless it; you
+file it.
+
+### Filing it
+
+Write their answers to a JSON file keyed by the template's field keys, then:
+
+```
+node scripts/gds/capture.js "<their title>" --full --fields-file <path>
+```
+
+That is the **same route** the hall form uses (`POST /inbox` with `grade='full'`),
+so the record is identical — same validation against the R141 template, same R142
+score, same ideator-credit lane. There is deliberately no separate write path for
+conversational authoring: a second one would drift, and "indistinguishable in the
+database" is this task's done-when.
+
+The command reports what the server **stored**. If it says the idea landed as
+*quick*, say so plainly — capture is fail-open on grading, and telling someone
+they filed a Full Idea when they did not is the one outcome worse than the
+failure itself.
+
+### Developing someone else's spark
+
+The same conversation works on a **Big Idea Spark** — a quick idea whose author
+marked it as needing development. `node scripts/gds/spark.js --list` shows what is
+waiting; develop one with `spark.js --develop <id> --fields-file <path>`. The
+author keeps the credit for having had the thought and the payout splits with
+them (ADR 0185), so the never-invent rule applies with more force, not less:
+those five answers are now going out under two people's names.
+
 ## Trust boundary — filing is open, triage is not
 
 Filing into the inbox is open to **any** authenticated builder (Xenos included) — that path stays open here. **Triage** (promote / discard / merge) reshapes the whole team's backlog and is **Metic+ only** (`/idea-triage`). So in this skill you *file*; you never verdict. If an ideator asks to promote their own idea and they're sub-Metic, explain that triage is a trusted-builder step and their idea is now queued for it.

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/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.304",
+  "version": "1.19.306",
   "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/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,
+};

package/scripts/gds/fitness.js

@@ -1657,7 +1657,6 @@ function checkWriteRoutesValidated() {
 
 // ---- runner ----------------------------------------------------------------
 
-
 // ── Check 19 — the ADR 0174 vocabulary wall (goal 1000068 R07, task 1003008) ──
 //
 // "Role" means ONE thing in this codebase: a craft — Artist, Ideator, or Builder.
@@ -1899,6 +1898,7 @@ const CHECKS = [
   checkGoalMembershipVocabulary, // Check 19b — ADR 0177 / task 1003013: the FOURTH "role" (goal membership)
   checkWriteRoutesValidated, // Check 18 — BV1 R12 / task 1999: every body-reading write route validates (ADR 0118)
   require('./fitness-ratchets.js').checkQualityRatchets, // Check 20 — task 1003129: quality budgets only tighten (mechanics + knip CI step live in fitness-ratchets.js)
+  require('./doc-cli-guard.js').checkDocNamesRealCli, // Check 22 — task 1003165 / G01: a doc that names a CLI invocation must match the real CLI
   require('./control-manifest.js').checkControlsExist, // Check 21 — task 1003131: goal-1000076 controls assert their own existence (the ADR 0022 assurance-of-assurance)
 ];
 

package/src/module-api.js

@@ -1035,8 +1035,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.302 with no explicit bump. run 32605477232. (task 1002620)
 //   1.19.304 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.303 with no explicit bump. run 32660527575. (task 1002620)
+//   1.19.305 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.304 with no explicit bump. run 32660902666. (task 1002620)
+//   1.19.306 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.305 with no explicit bump. run 32662000590. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.304'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.306'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/doc_cli_guard.mjs

@@ -0,0 +1,195 @@
+// tests/doc_cli_guard.mjs — G01, task 1003165, goal 1000077, criterion
+// guards-doc-names-a-command.
+//
+// This test's whole reason for existing is that the LAST test of this kind was
+// useless. Task 1002931 shipped a skill telling agents to run
+// `capture.js --full --fields-file`, and its test passed — because it asserted
+// the skill file CONTAINED those words, never that the words worked. So the
+// suite was green while the documented command silently ignored both flags.
+//
+// Therefore: every case below drives the check to a VERDICT on injected input.
+// The negative cases prove it actually fails; a guard that has never been seen
+// to fail is not evidence of anything.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const g = require(path.join(ROOT, 'scripts', 'gds', 'doc-cli-guard.js'));
+
+// A tiny injected world: doc text and script source, by path.
+const world = (docs, scripts) => ({
+  readDoc: (p) => (p in docs ? docs[p] : null),
+  readScript: (p) => (p in scripts ? scripts[p] : null),
+  allow: new Map(),
+});
+
+test('the live tree passes', () => {
+  const r = g.checkDocNamesRealCli();
+  assert.equal(r.hardFail, false, `unexpected violations:\n  ${r.violations.join('\n  ')}`);
+  assert.equal(r.ok, true);
+});
+
+test('the live scan actually reads the repo — not a vacuous pass', () => {
+  // The failure mode this pins: a scan that enumerates nothing reports "clean".
+  const r = g.checkDocNamesRealCli();
+  assert.match(r.note, /(\d+) documented/);
+  const invocations = Number(r.note.match(/^(\d+) documented/)[1]);
+  assert.ok(invocations > 50, `expected the real repo to yield many invocations, got ${invocations}`);
+});
+
+test('an empty enumeration FAILS rather than passing quietly', () => {
+  const r = g.checkDocNamesRealCli({ files: [] });
+  assert.equal(r.hardFail, true);
+  assert.match(r.violations[0], /scan defect/);
+});
+
+// ---- the regression that motivated the check ------------------------------
+test('THE 1002931 CASE: a doc naming a flag the script does not have is caught', () => {
+  const { violations } = g.scanDocs(['skill.md'], world(
+    { 'skill.md': 'Run `node scripts/gds/capture.js --full --fields-file f.json`.' },
+    // capture.js as it was on the OTHER machine: no --full, no --fields-file.
+    { 'scripts/gds/capture.js': "const text = process.argv.slice(2).join(' ');" },
+  ));
+  assert.equal(violations.length, 2, violations.join('\n'));
+  assert.ok(violations.some((v) => v.includes('--full')));
+  assert.ok(violations.some((v) => v.includes('--fields-file')));
+  assert.match(violations[0], /silently IGNORED/);
+});
+
+test('the same doc PASSES once the script really carries the flags', () => {
+  const { violations } = g.scanDocs(['skill.md'], world(
+    { 'skill.md': 'Run `node scripts/gds/capture.js --full --fields-file f.json`.' },
+    { 'scripts/gds/capture.js': "const full = args.includes('--full'); const ff = arg('--fields-file');" },
+  ));
+  assert.deepEqual(violations, []);
+});
+
+test('a doc naming a script that does not exist is caught', () => {
+  const { violations } = g.scanDocs(['skill.md'], world(
+    { 'skill.md': 'run `node scripts/gds/art-stage.js` to publish' }, {},
+  ));
+  assert.equal(violations.length, 1);
+  assert.match(violations[0], /does not exist/);
+});
+
+// ---- no false positives (the five that killed the first draft) ------------
+test('every real argv idiom in this repo is accepted', () => {
+  // Draft 1 matched only arg()/hasFlag() with the flag as first argument, and
+  // called all five of these broken. They are all correct code.
+  const idioms = {
+    'argv.indexOf': "const i = argv.indexOf('--development');",
+    'hasFlag(args, x)': "const apply = hasFlag(args, '--development');",
+    'argVal(args, x)': "const v = argVal(args, '--development');",
+    'strict equality': "else if (a === '--development') on = true;",
+    'Set.has': "const on = ARGS.has('--development');",
+    'usage text only': '//   node scripts/gds/x.js --development <path>',
+  };
+  for (const [label, src] of Object.entries(idioms)) {
+    const { violations } = g.scanDocs(['d.md'], world(
+      { 'd.md': 'run `node scripts/gds/x.js --development p.json`' },
+      { 'scripts/gds/x.js': src },
+    ));
+    assert.deepEqual(violations, [], `${label} must be accepted`);
+  }
+});
+
+test('a LONGER flag in the source does not satisfy a shorter documented one', () => {
+  // The direction that actually needs the trailing guard: the source contains
+  // only `--client-id`, and a bare substring search for `--client` would find
+  // it INSIDE that and wave the doc through. Written the other way round this
+  // case passes with or without the guard, so it proves nothing — the first
+  // draft of this test had it backwards and a mutation run caught it.
+  const { violations } = g.scanDocs(['d.md'], world(
+    { 'd.md': 'run `node scripts/gds/x.js --client abc`' },
+    { 'scripts/gds/x.js': "const c = argVal(args, '--client-id');" },
+  ));
+  assert.equal(violations.length, 1, 'a longer flag must not satisfy a shorter one');
+  assert.match(violations[0], /--client\b/);
+});
+
+test('and the exact documented flag is still accepted alongside a longer sibling', () => {
+  const { violations } = g.scanDocs(['d.md'], world(
+    { 'd.md': 'run `node scripts/gds/x.js --client abc`' },
+    { 'scripts/gds/x.js': "argVal(args, '--client-id'); argVal(args, '--client');" },
+  ));
+  assert.deepEqual(violations, []);
+});
+
+test('flags do not leak across two invocations in one doc', () => {
+  // b.js carries --beta, a.js does not; only a.js/--alpha may be flagged.
+  const { violations } = g.scanDocs(['d.md'], world(
+    { 'd.md': 'first `node scripts/gds/a.js --alpha`\nthen `node scripts/gds/b.js --beta`' },
+    { 'scripts/gds/a.js': 'nothing here', 'scripts/gds/b.js': "arg('--beta')" },
+  ));
+  assert.equal(violations.length, 1, violations.join('\n'));
+  assert.match(violations[0], /a\.js.*--alpha/);
+});
+
+test('universal plumbing flags are not reported', () => {
+  const { violations } = g.scanDocs(['d.md'], world(
+    { 'd.md': 'run `node scripts/gds/x.js --quiet --json --help --dry-run`' },
+    { 'scripts/gds/x.js': 'no flags at all' },
+  ));
+  assert.deepEqual(violations, []);
+});
+
+// ---- the allowlist -------------------------------------------------------
+test('an allowlisted invocation is tolerated — and covers its own flags', () => {
+  const allow = new Map([['d.md::scripts/gds/gone.js', 'ships with an excluded host module']]);
+  const { violations } = g.scanDocs(['d.md'], {
+    readDoc: () => 'run `node scripts/gds/gone.js --whatever`',
+    readScript: () => null,
+    allow,
+  });
+  assert.deepEqual(violations, []);
+});
+
+test('every live allowlist entry carries a justification', () => {
+  assert.ok(g.DOC_CLI_ALLOW.size > 0, 'the allowlist documents the real exceptions');
+  for (const [key, reason] of g.DOC_CLI_ALLOW) {
+    assert.match(key, /::/, `${key} must be <doc>::<token>`);
+    assert.ok(String(reason).trim().length > 30, `${key} needs a real reason, not a stub`);
+  }
+});
+
+// ---- the residual gap the criterion names: "parsed", not merely present ----
+test('a flag surviving ONLY in a usage comment warns without failing', () => {
+  // The criterion asks that a documented flag be PARSED. Presence is all a static
+  // check can prove, so the leftover case — implementation deleted, usage banner
+  // left behind — is surfaced as a warning. It must NOT be a violation: some
+  // scripts legitimately name a flag only in their banner and handle it via a
+  // helper, and failing on that is what sank the first draft.
+  const { violations, warnings } = g.scanDocs(['d.md'], world(
+    { 'd.md': 'run `node scripts/gds/x.js --gone`' },
+    { 'scripts/gds/x.js': '// usage: x.js --gone <path>\nconst nothing = 1;' },
+  ));
+  assert.deepEqual(violations, [], 'a comment-only mention must not fail the build');
+  assert.equal(warnings.length, 1);
+  assert.match(warnings[0], /only in comments/);
+});
+
+test('a flag present in real code produces NO warning', () => {
+  const { violations, warnings } = g.scanDocs(['d.md'], world(
+    { 'd.md': 'run `node scripts/gds/x.js --live`' },
+    { 'scripts/gds/x.js': "// usage: x.js --live\nconst on = args.includes('--live');" },
+  ));
+  assert.deepEqual(violations, []);
+  assert.deepEqual(warnings, []);
+});
+
+test('stripLineComments keeps code and drops both comment forms', () => {
+  const out = g.stripLineComments("const a = '--keep'; // --dropped\n/* --alsodropped */\n");
+  assert.ok(out.includes('--keep'));
+  assert.ok(!out.includes('--dropped'));
+  assert.ok(!out.includes('--alsodropped'));
+});
+
+test('a URL is not mistaken for a comment', () => {
+  // `//` inside a string must not truncate the line and hide a real flag.
+  const out = g.stripLineComments("const u = 'https://x.test/?f=--real';");
+  assert.ok(out.includes('--real'), 'a protocol slash-slash must not eat the line');
+});

package/tests/idea_ideate_full.mjs

@@ -0,0 +1,170 @@
+// tests/idea_ideate_full.mjs
+//
+// task 1002931 (BV1.R155, goal 1000062) — /ideate authors a Full Idea
+// conversationally.
+//
+// A skill is a prompt, so the thing to pin is the PROMPT'S CONTRACT. Two
+// done-when clauses, and both are checkable:
+//
+//   1. "indistinguishable in the database from one authored in the hall" — so the
+//      skill must file through the SAME route the hall uses, and must not describe
+//      a bespoke write path of its own. A second path is how two surfaces start
+//      producing subtly different rows.
+//   2. "never invents field content on the builder's behalf" — the sharp one. The
+//      completeness score is deterministic and feeds credits (ADR 0172), so a
+//      ghost-written field is a fraudulent number and the builder is paid for the
+//      model's words. The rule must be present WITH that reason: an instruction
+//      whose justification is missing is the first one dropped under pressure.
+//
+// Plus the rule this goal applies to every surface: the five questions live in the
+// R141 declaration, so no consumer restates them.
+//
+// Run:  node tests/idea_ideate_full.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const SKILL = fs.readFileSync(path.join(ROOT, '.claude/skills/ideate/SKILL.md'), 'utf8');
+// Prose assertions run against a WHITESPACE-NORMALISED copy. Markdown is hard-
+// wrapped, so any phrase long enough to be worth asserting will eventually
+// straddle a newline — and a regex that does not allow for that fails on a
+// reflow that changed nothing. Structural assertions (code fences, list markers)
+// still use SKILL itself.
+const NORM = SKILL.replace(/\s+/g, ' ');
+const { BASE_TEMPLATE } = require('../modules/ideas/templates.js');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.error(`  FAIL ${name}\n    ${err.message}`); }
+}
+
+// --- (1) the same record as the hall ------------------------------------
+
+// THE COMMAND THE SKILL NAMES MUST ACTUALLY EXIST — and this assertion is here
+// because a grader caught its absence. A test that pins prompt text and stops
+// there will happily pass while the skill documents a command that does nothing:
+// R155's branch was cut before R151 added these flags, so for a while the skill
+// said `capture.js --full` to a capture.js that had never heard of it. Prompt
+// tests must reach the executable, or they only prove the prose is self-consistent.
+test('capture.js really supports the flags the skill tells you to use', () => {
+  const capture = path.join(ROOT, 'scripts/gds/capture.js');
+  const usage = spawnSync(process.execPath, [capture], { encoding: 'utf8', timeout: 20000 });
+  assert.equal(usage.status, 2, 'the no-args usage path');
+  assert.match(usage.stderr, /--full/, 'usage advertises --full');
+  assert.match(usage.stderr, /--fields-file/, 'usage advertises --fields-file');
+
+  // Stronger than the usage text: --full must be UNDERSTOOD, not merely listed.
+  // An unrecognised flag would be silently ignored and file a quick idea; the
+  // R151 guard proves the flag is wired to real behaviour.
+  const guard = spawnSync(process.execPath, [capture, 'a title', '--full'], { encoding: 'utf8', timeout: 20000 });
+  assert.equal(guard.status, 2);
+  assert.match(guard.stderr, /--full needs --fields-file/, '--full is parsed and validated');
+
+  // And it can actually send a grade — the thing that makes the record match the
+  // hall's. Asserted over the payload assignment, not the file text.
+  const src = fs.readFileSync(capture, 'utf8');
+  const grades = [...src.matchAll(/payload\.grade\s*=\s*'([a-z]+)'/g)].map((m) => m[1]);
+  assert.deepEqual(grades, ['full'], 'capture.js sends grade=full');
+});
+
+test('it files through capture.js --full — the route the hall form uses', () => {
+  assert.match(SKILL, /capture\.js "<their title>" --full --fields-file/);
+  // Named explicitly so the next reader knows WHY it is that command and not a
+  // bespoke one.
+  assert.match(NORM, /same.{0,10}route.{0,40}hall form uses/i);
+});
+
+test('it describes NO second write path', () => {
+  // The failure this guards: a skill that tells an agent to curl the API by hand
+  // ends up sending a different payload than the form does, and the two records
+  // drift while both claim to be Full Ideas.
+  assert.ok(!/curl/i.test(SKILL), 'no hand-rolled HTTP');
+  assert.ok(!/api\.js POST \/api\/gds\/inbox/.test(SKILL), 'no raw POST for filing an idea');
+  const grade = [...SKILL.matchAll(/grade\s*=\s*'([a-z]+)'/g)].map((m) => m[1]);
+  assert.ok(grade.every((g) => g === 'full'), `only the full grade is named: ${JSON.stringify(grade)}`);
+});
+
+test('it says the report comes from the SERVER, not from the request', () => {
+  // Capture is fail-open on grading (R143): an idea can land as quick.
+  assert.match(NORM, /reports what the server \*\*stored\*\*/);
+  assert.match(NORM, /landed as.{0,20}quick/);
+});
+
+// --- (2) it never invents field content ---------------------------------
+
+test('the never-invent rule is stated, in more than one form', () => {
+  assert.match(NORM, /Never invent field content/);
+  assert.match(NORM, /Never pad a thin answer/);
+  assert.match(NORM, /Never polish an answer into words they did not use/);
+});
+
+test('and it carries the REASON — the score feeds credits', () => {
+  // An instruction without its justification is the first one dropped when the
+  // model is trying to be helpful. This is the sentence that makes ghost-writing
+  // legible as fraud rather than as service.
+  assert.match(NORM, /deterministic/);
+  assert.match(NORM, /feeds credits/);
+  assert.match(NORM, /fraudulent/);
+  assert.match(NORM, /paid for your words/i);
+});
+
+test('an unanswered question is allowed to stay empty', () => {
+  // The tempting failure is completing the set "to be helpful", which is exactly
+  // the ghost-writing the rule forbids.
+  assert.match(NORM, /stays empty/);
+  assert.match(NORM, /honest/);
+});
+
+test('it names the thing to do INSTEAD — press on a thin answer', () => {
+  // A rule that only forbids leaves the model with nothing to do; this is the
+  // sounding-board behaviour the whole skill exists for.
+  assert.match(NORM, /press on a thin answer/i);
+  assert.match(NORM, /Their next sentence is theirs/);
+});
+
+test('the builder blesses it; the skill files it', () => {
+  assert.match(NORM, /They bless it; you file it\./);
+});
+
+// --- the five questions are not restated -------------------------------
+
+test('the skill names NO field key and NO field label', () => {
+  // Same rule the hall composer obeys (R152): the questions are declared once, in
+  // the R141 template, and a copy here would silently ignore a per-project one.
+  for (const f of BASE_TEMPLATE.fields) {
+    assert.ok(!SKILL.includes(f.key), `restates the field key "${f.key}"`);
+    assert.ok(!SKILL.includes(f.label), `restates the label "${f.label}"`);
+  }
+});
+
+test('it points at the command that PRINTS the questions', () => {
+  assert.match(SKILL, /spark\.js --template/);
+  assert.match(NORM, /never from memory/i);
+});
+
+// --- the sibling path ---------------------------------------------------
+
+test('it can also develop someone else\'s spark, with the rule reinforced', () => {
+  assert.match(SKILL, /spark\.js --list/);
+  assert.match(SKILL, /spark\.js --develop/);
+  // The never-invent rule matters MORE there: the answers go out under two names.
+  assert.match(NORM, /two people's names/);
+});
+
+test('the section does not contradict the skill\'s founding rule', () => {
+  // "you are the instrument, not the author" is the whole premise; the Full Idea
+  // section has to be an application of it, not an exception to it.
+  assert.match(NORM, /you are the instrument, not the author/);
+  assert.match(NORM, /stops being a stance and becomes a hard constraint/);
+});
+
+console.log(`\nidea_ideate_full: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);