@bongos/core 1.19.305 → 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.305",
-  "core_contract": "1.19.305",
-  "source_commit": "6dc5a84be60b26f11d572eeccf10b8092c7352ae",
+  "core_version": "1.19.306",
+  "core_contract": "1.19.306",
+  "source_commit": "bfb69ddea49ebcce6d1d0608dd8e1fc50cc755e2",
   "source_ref": "HEAD",
-  "built_at": "2026-08-23T19:20:49.275Z",
+  "built_at": "2026-08-23T19:41:29.546Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 322,
     "agent_docs_stubbed": 22,
-    "functional_verbatim": 1414,
+    "functional_verbatim": 1416,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1758,
-  "tree_sha256": "3a7cd2627a967fe3dbe7edf3dc916b4d728170b826669b64ae457d5e92ac10d1",
+  "file_count": 1760,
+  "tree_sha256": "a2c3f65e69e891c0076d0b10268d3549cfddf8d76d1f320274e86fd833d56013",
   "files": [
     {
       "path": ".claude/skills/blocker-review/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": "4678a5bfd751ffe8ac5c3283eb25af2e011ccb14d32032bf373c7c77bcb61a3d"
+      "sha256": "ab53e6d02f437a24895dd3d04b3e8ef39ddf4257b8c4b2e784a84dd10820adc4"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "5ff86f97c1df0bf8d224512adc339aac2859db0a65e40e7783032b0128f7cbbd"
+      "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": "a59a54dc09613fc6d95a2efa1262b6d8099fabfb1ef90289462b81accd9c7fea"
+      "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",

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.305",
+  "version": "1.19.306",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.305",
+      "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.305",
+  "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

@@ -1037,8 +1037,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         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.305'; // 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');
+});