@bongos/core 1.19.305 → 1.19.307

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/scripts/gds/ship-honesty.js

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+// scripts/gds/ship-honesty.js — a ship must not lose the builder's prose, and
+// must not lie about how far it got (task 1003168 / G04, goal 1000077;
+// criterion guards-ship-cannot-lie).
+//
+// TWO fixes live here because they are one incident. A ship was invoked with
+// handoff notes containing backticks; bash command-substituted them before node
+// ran, truncating the argument list. The task resolved with EMPTY notes, landed
+// at 'completed', and the process died before grading with a bare
+// `fatal: <stack>`. Two failures compounded: the prose was lost (nothing in the
+// ledger about a session that happened), and the status could not say which leg
+// died — 'completed' is ALSO what a grade-failed task looks like.
+//
+// Split out of ship.js, which is ~4600 lines and far over the size ratchet, so
+// adding this there would have regressed excess_lines_total.
+
+'use strict';
+
+const { argText } = require('./cli-lib.js');
+
+// resolveProse(args, specs) — resolve every prose argument for one invocation
+// through cli-lib.argText, refusing the combinations that would silently lose
+// text. Returns a { [bareName]: string } map, or exits 2 having explained why.
+//
+// The extra rule argText cannot enforce alone: stdin can only be consumed ONCE,
+// so two `-file -` arguments in the same command would hand the first reader
+// everything and the second an empty string. Refuse instead — a ship whose notes
+// silently came back empty is the exact incident this whole task is about
+// (learning 1000197).
+function resolveProse(args, specs) {
+  const out = {};
+  const stdinUsers = [];
+  for (const name of specs) {
+    const r = argText(`--${name}`, args);
+    if (r.error) {
+      console.error(r.error);
+      process.exit(2);
+    }
+    if (r.source === 'stdin') stdinUsers.push(`--${name}-file`);
+    out[name] = r.value;
+  }
+  if (stdinUsers.length > 1) {
+    console.error(`${stdinUsers.join(' and ')} both read stdin, which can only be consumed once — `
+      + 'the second would silently come back empty. Put at least one in a real file.');
+    process.exit(2);
+  }
+  return out;
+}
+
+// ---------- The ship must not lie about how far it got (G04, task 1003168) ----
+//
+// THE INCIDENT. A ship died after the claim resolved and before the grade
+// recorded. resolveClaim had already landed the task at 'completed', so the
+// process printed `fatal: <stack>` and exited — and 'completed' is exactly what
+// a task ALSO looks like when its grade ran and failed. The status could not
+// distinguish "the pipeline stopped here" from "the pipeline got further and the
+// grade said no", and the work went unrecovered because nobody could tell.
+//
+// The cure is not more status values: it is that the process which knows where it
+// died must SAY so on the way out. shipProgress records the last leg that
+// completed; fatalRecoveryLines turns it into an instruction.
+let shipProgress = { stage: 'preflight', taskId: null };
+
+// The one writer. Called by ship.js as each leg completes.
+function markShipProgress(stage, taskId) {
+  shipProgress = { stage, taskId };
+}
+
+// Pure so the wording is pinned by a DB-free test (the smokeGateMessages
+// precedent) — a recovery message that drifts out of date is worse than none.
+//
+// WHY EVERY STAGE POINTS AT A PLAIN RE-RUN, never --regrade: shipMain on a task
+// with no active claim routes by the task's CURRENT status (evaluateResumeAction)
+// — 'completed' resumes the grade, 'confirmed' resumes the merge. --regrade only
+// accepts 'completed' and REFUSES a 'confirmed' task with "its grade passed;
+// nothing to re-grade". A builder reading a crash does not know which leg died,
+// which is the entire problem, so the advice must be the command that works from
+// either — and a plain re-run of a 'completed' task calls regradeMain() anyway.
+function fatalRecoveryLines(progress = shipProgress) {
+  const id = progress.taskId;
+  const rerun = id ? `node scripts/gds/ship.js ${id}` : 'node scripts/gds/ship.js <task-id>';
+  const head = 'The ship did NOT finish. Where it stopped, and what recovers it:';
+  switch (progress.stage) {
+    case 'resolved':
+      return [
+        head,
+        `  Task #${id} is at 'completed' — the claim resolved, the grade did NOT record.`,
+        '  No credits awarded. Your commits are safe; nothing was lost but the grade.',
+        `  Resume:  ${rerun}`,
+        "  (A plain re-run resumes the stalled leg. Do NOT reach for --regrade: it only",
+        "   accepts 'completed', so it refuses outright if the ship actually got further.)",
+      ];
+    case 'graded':
+      return [
+        head,
+        `  Task #${id} is at 'confirmed' — it graded and PASSED; the merge/deploy did not finish.`,
+        '  Credits land on the merge, so they have not been awarded yet.',
+        `  Resume:  ${rerun}`,
+        '  (--regrade would refuse this one — its grade already passed.)',
+      ];
+    case 'landed':
+      return [
+        'The ship LANDED; the failure above is in the after-work:',
+        `  Task #${id} reached 'shipped' — the merge landed and credits were awarded.`,
+        '  Broadcast / card / cleanup did not complete, which does not undo the ship.',
+        `  Safe to re-run if you want the after-work retried:  ${rerun}`,
+      ];
+    case 'preflight':
+    default:
+      return [
+        head,
+        '  The claim was NOT resolved — it is still active and the task is unchanged.',
+        `  Fix the error above and re-run:  ${rerun}`,
+      ];
+  }
+}
+
+// task 1002605 (G-18): the pre-resolve smoke gate's two message sets, pure so the
+// wording is pinned by a DB-free unit test (tests/ship_smoke_gate.mjs). A smoke
+// FAIL used to fall silently through into the claim resolve — claim consumed,
+// grading skipped with no message, task parked at 'completed', exit 0 — the
+// choke-point map's likeliest "my task vanished" shape. `abort` is the default
+// (printed BEFORE the resolve; the claim stays active); `parked` is the
+// --allow-smoke-fail continuation (printed where the grader would have run, so
+// the builder knows exactly where the task stopped and how to resume).
+function smokeGateMessages(taskId) {
+  return {
+    abort: [
+      'Ship ABORTED: the production smoke test FAILED — see the FAIL line(s) above.',
+      'No claim resolved, no credits awarded — your claim is still active and nothing changed.',
+      'The smoke suite hits LIVE endpoints (your change is not deployed yet), so this usually means production is briefly degraded — not that your change broke it.',
+      `  - Re-run once it recovers:     node scripts/gds/ship.js ${taskId}`,
+      `  - Ship anyway (deliberate):    node scripts/gds/ship.js ${taskId} --allow-smoke-fail`,
+      `    (parks the task at 'completed' ungraded; a plain re-run resumes it)`,
+    ],
+    parked: [
+      '--allow-smoke-fail: smoke FAILED and the ship deliberately stops here.',
+      `Task #${taskId} is parked at 'completed' — ungraded, unconfirmed, no credits awarded.`,
+      `Resume when production is healthy:  node scripts/gds/ship.js ${taskId}`,
+      '  (A plain re-run routes to whichever leg stalled. --regrade only accepts a task at',
+      "   'completed', so it refuses if the ship got further — task 1003168.)",
+    ],
+  };
+}
+
+module.exports = {
+  resolveProse, markShipProgress, fatalRecoveryLines, smokeGateMessages,
+  _resetForTest: () => { shipProgress = { stage: 'preflight', taskId: null }; },
+  _peekForTest: () => shipProgress,
+};

package/scripts/gds/ship.js

@@ -12,6 +12,7 @@
 // the task stays at 'confirmed' for /merge-mode to land later.
 //
 // Usage:
+//   node scripts/gds/ship.js <task-id> --notes-file notes.md --summary-file summary.txt
 //   node scripts/gds/ship.js <task-id> --notes "handoff markdown" --summary "value-summary line"
 //   node scripts/gds/ship.js <task-id> --no-merge      # stop after confirm; skip auto-merge
 //   node scripts/gds/ship.js <task-id> --db-only       # deliberate zero-commit / direct-SQL ship (task 391):
@@ -62,6 +63,8 @@ const os = require('node:os');
 const path = require('node:path');
 const readline = require('node:readline');
 const { cliClient, requireSession, loadSession, loadSessionSync, printOnboardingNudge, arg, rewardPolicy } = require('./cli-lib');
+// task 1003168 (G04): how a ship reports prose + an unfinished run — see that file.
+const { resolveProse, markShipProgress, fatalRecoveryLines, smokeGateMessages } = require('./ship-honesty.js');
 
 // The instance's reward policy, as reported by the server on GET /me (ADR 0146 /
 // task 1002469). Cached module-level because the credits print + the completion
@@ -2235,32 +2238,6 @@ function runSmokeAsync() {
   });
 }
 
-// task 1002605 (G-18): the pre-resolve smoke gate's two message sets, pure so the
-// wording is pinned by a DB-free unit test (tests/ship_smoke_gate.mjs). A smoke
-// FAIL used to fall silently through into the claim resolve — claim consumed,
-// grading skipped with no message, task parked at 'completed', exit 0 — the
-// choke-point map's likeliest "my task vanished" shape. `abort` is the default
-// (printed BEFORE the resolve; the claim stays active); `parked` is the
-// --allow-smoke-fail continuation (printed where the grader would have run, so
-// the builder knows exactly where the task stopped and how to resume).
-function smokeGateMessages(taskId) {
-  return {
-    abort: [
-      'Ship ABORTED: the production smoke test FAILED — see the FAIL line(s) above.',
-      'No claim resolved, no credits awarded — your claim is still active and nothing changed.',
-      'The smoke suite hits LIVE endpoints (your change is not deployed yet), so this usually means production is briefly degraded — not that your change broke it.',
-      `  - Re-run once it recovers:     node scripts/gds/ship.js ${taskId}`,
-      `  - Ship anyway (deliberate):    node scripts/gds/ship.js ${taskId} --allow-smoke-fail`,
-      `    (parks the task at 'completed' ungraded; resume later with --regrade)`,
-    ],
-    parked: [
-      '--allow-smoke-fail: smoke FAILED and the ship deliberately stops here.',
-      `Task #${taskId} is parked at 'completed' — ungraded, unconfirmed, no credits awarded.`,
-      `Resume when production is healthy:  node scripts/gds/ship.js ${taskId} --regrade`,
-    ],
-  };
-}
-
 // ---------- Step 3: merge + deploy chain ----------
 
 function currentBranch() {
@@ -3696,11 +3673,14 @@ async function shipMain() {
   const args = process.argv.slice(2);
   const taskId = Number(args[0]);
   if (!Number.isFinite(taskId)) {
-    console.error('usage: node scripts/gds/ship.js <task-id> --notes "..." --summary "..." [--surprise "text" | --surprise none | --no-surprise] [--no-merge] [--db-only] [--verified] [--allow-empty] [--allow-smoke-fail] [--base <ref>]');
+    console.error('usage: node scripts/gds/ship.js <task-id> (--notes-file <path|-> | --notes "...") (--summary-file <path|-> | --summary "...") [--surprise "text" | --surprise none | --no-surprise] [--no-merge] [--db-only] [--verified] [--allow-empty] [--allow-smoke-fail] [--base <ref>]');
+    console.error('  prefer the -file forms for prose: a shell command-substitutes backticks in an inline value before node sees it (learning 1000197).');
     process.exit(2);
   }
-  const notes = arg('--notes', args) || '';
-  const summary = arg('--summary', args) || '';
+  // G04: prose from a FILE or inline, never shell-mangled in silence.
+  const prose = resolveProse(args, ['notes', 'summary']);
+  const notes = prose.notes;
+  const summary = prose.summary;
   const skipMerge = args.includes('--no-merge');
   const force = args.includes('--force');
   // task 391 (idea #37): a deliberate zero-commit / direct-SQL ship. Without it,
@@ -4114,6 +4094,8 @@ async function shipMain() {
 
   const taskStatus = r.data.taskStatus || 'shipped (legacy response)';
   console.log(`Task #${r.data.taskId} is now: ${taskStatus}`);
+  // Claim CONSUMED, task at 'completed' — a crash from here needs fatalRecoveryLines.
+  markShipProgress('resolved', taskId);
 
   // ---- Step 2: subagent quality grader ----
   // Runs when local verification passed AND resolveClaim landed at completed.
@@ -4241,6 +4223,10 @@ async function shipMain() {
   // ---- Step 3: confirmed→shipped tail (merge + deploy → memory/session sync →
   // Done → onboarding nudge → completion card), shared with regradeMain via
   // finishShip (#1093/C9). ----
+  // Graded. If it passed, only the merge remains — a different crash story.
+  if (postGradeStatus === 'confirmed' || postGradeStatus === 'shipped') {
+    markShipProgress(postGradeStatus === 'shipped' ? 'landed' : 'graded', taskId);
+  }
   await finishShip({
     taskId, summary, advanceToMerge, skipMerge, postGradeStatus, doneLine: 'Done.', dbOnly,
     // task 1270: data for the deterministic completion card.
@@ -4283,14 +4269,15 @@ async function regradeMain() {
   const args = process.argv.slice(2);
   const taskId = Number(args[0]);
   if (!Number.isFinite(taskId)) {
-    console.error('usage: node scripts/gds/ship.js <task-id> --regrade [--summary "..."] [--response "..."] [--no-merge] [--force] [--verified] [--base <ref>]');
+    console.error('usage: node scripts/gds/ship.js <task-id> --regrade [--summary-file <path|-> | --summary "..."] [--response-file <path|-> | --response "..."] [--no-merge] [--force] [--verified] [--base <ref>]');
     process.exit(2);
   }
-  const summaryArg = arg('--summary', args) || '';
+  const regradeProse = resolveProse(args, ['summary', 'response']);
+  const summaryArg = regradeProse.summary;
   // task 1002662: the builder's response to the prior round's findings — how
   // each was fixed, tracked (a task ref), or why it's out of scope. Rides to
   // the panel fenced, under the delta re-grade policy.
-  const responseArg = arg('--response', args) || '';
+  const responseArg = regradeProse.response;
   const skipMerge = args.includes('--no-merge');
   const force = args.includes('--force');
   // task 1002422: honor --base on regrade/resume too, so `--regrade --base <ref>`
@@ -4609,6 +4596,7 @@ module.exports = {
   // / non-ci → false) is unit-tested with no gh/network (env-driven via
   // OTB_DEPLOY_MODE + OTB_PUSH_VIA_SERVER).
   broadcastHandledByServer,
+  fatalRecoveryLines, // G04 re-export (definition in ship-honesty.js)
 };
 
 if (require.main === module) {
@@ -4617,6 +4605,9 @@ if (require.main === module) {
   const main = process.argv.slice(2).includes('--regrade') ? regradeMain : shipMain;
   main().catch((err) => {
     console.error('fatal:', err);
+    // G04: never exit on a stack trace alone — say which leg died.
+    console.error('');
+    for (const line of fatalRecoveryLines()) console.error(line);
     process.exit(1);
   });
 }

package/src/module-api.js

@@ -1037,8 +1037,12 @@ 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)
+//   1.19.307 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.306 with no explicit bump. run 32663876767. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.305'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.307'; // 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/route_rank_check.mjs

@@ -427,19 +427,127 @@ test('LIVE: checkRouteRanks() on src/bongos/routes/ has zero unknowns', () => {
   assert.equal(res.hardFail, false);
 });
 
-// The census invariant (BV1.R109b). Asserting that the 10 known multi-line paths parse
-// would prove nothing about the ELEVENTH — the next route someone declares in a form
-// this scanner doesn't handle. So count instead: every `router.<method>(` line in every
-// discovered route file must yield exactly one classified route.
+// The census invariant (BV1.R109b, re-derived in task 1002671). Asserting that the 10
+// known multi-line paths parse would prove nothing about the ELEVENTH — the next route
+// someone declares in a form this scanner doesn't handle. So count instead: every
+// `router.<method>(` call in every discovered route file must yield exactly one
+// classified route.
 //
-// The census regex below is HAND-WRITTEN here on purpose and NOT imported from the
-// module. Importing ROUTE_DECL_RE would move both sides of the comparison together and
-// prove nothing (the oracle trap tests/route_permission_check.mjs documents).
-const CENSUS_DECL_RE = /^\s*router\.(?:get|post|patch|put|delete)\s*\(/;
+// ORACLE INDEPENDENCE (the 2026-07-30 review's HIGH finding, confirmed): the first cut
+// of this census was a verbatim copy of the scanner's own ROUTE_DECL_RE — hand-written,
+// but shape-identical, so any widening of the scanner would be pasted into the census
+// and both sides would move together. The census below is derived on a structurally
+// different axis instead:
+//   • token-level, not line-level — comments and string/template/regex literals are
+//     stripped first by a tiny tokenizer, then calls are counted in the whole text;
+//   • not line-anchored — an inline/chained/mid-line declaration counts here even
+//     though the scanner's `^\s*` form cannot see it;
+//   • whitespace-tolerant across the member access (`router . get (` counts).
+// A unilateral change to the scanner's recognizer now shows up as a census mismatch
+// and forces a DELIBERATE census-side decision, instead of going green by paste.
+//
+// The tokenizer is deliberately small and fail-closed: if it ever misreads a future
+// route file, the equality below goes red and a human looks — that is the correct
+// failure mode for an audit oracle (never silently green).
+function stripNonCode(src) {
+  let out = '';
+  const n = src.length;
+  const tplBraceDepth = []; // one entry per open template-literal interpolation
+  let i = 0;
+  const KEYWORDS_BEFORE_REGEX = new Set(['return', 'typeof', 'case', 'in', 'of', 'instanceof', 'new', 'delete', 'void', 'do', 'else', 'yield', 'await']);
+  const regexCanFollow = () => {
+    const t = out.trimEnd();
+    if (t === '') return true;
+    const last = t[t.length - 1];
+    if ('(,=:[!&|?{};+-*%~^<>'.includes(last)) return true;
+    const word = /[A-Za-z_$][\w$]*$/.exec(t);
+    return !!(word && KEYWORDS_BEFORE_REGEX.has(word[0]));
+  };
+  // Consume string/template BODY starting at src[i] (opening quote already emitted
+  // and consumed). For templates, stops early at `${` and pushes an interpolation
+  // frame — the main loop then lexes the interpolation as code until its `}`.
+  const skipStringBody = (quote) => {
+    while (i < n && src[i] !== quote) {
+      if (src[i] === '\\') { out += '..'; i += 2; continue; }
+      if (quote === '`' && src[i] === '$' && src[i + 1] === '{') { out += '${'; i += 2; tplBraceDepth.push(0); return 'interp'; }
+      out += (src[i] === '\n' ? '\n' : '.'); i++;
+    }
+    out += quote; i++; // closing quote (or EOF)
+    return 'closed';
+  };
+  const skipString = (quote) => {
+    out += quote; i++;
+    return skipStringBody(quote);
+  };
+  while (i < n) {
+    const c = src[i], d = src[i + 1];
+    if (c === '/' && d === '/') { while (i < n && src[i] !== '\n') i++; continue; }
+    if (c === '/' && d === '*') { i += 2; while (i < n && !(src[i] === '*' && src[i + 1] === '/')) { if (src[i] === '\n') out += '\n'; i++; } i += 2; out += ' '; continue; }
+    if (c === '/' && regexCanFollow()) { // regex literal (handles quotes inside, e.g. /[&<>"']/)
+      out += '/'; i++;
+      let inClass = false;
+      while (i < n && (inClass || src[i] !== '/')) {
+        if (src[i] === '\\') { out += '..'; i += 2; continue; }
+        if (src[i] === '[') inClass = true;
+        else if (src[i] === ']') inClass = false;
+        out += '.'; i++;
+      }
+      out += '/'; i++;
+      while (i < n && /[a-z]/i.test(src[i])) { out += src[i]; i++; } // flags
+      continue;
+    }
+    if (c === '\'' || c === '"' || c === '`') { skipString(c); continue; }
+    if (tplBraceDepth.length) { // inside a template interpolation: brace-track back to the template
+      if (c === '{') tplBraceDepth[tplBraceDepth.length - 1]++;
+      if (c === '}') {
+        if (tplBraceDepth[tplBraceDepth.length - 1] === 0) {
+          tplBraceDepth.pop(); out += '}'; i++;
+          skipStringBody('`'); // resume the enclosing template's body (may re-enter an interpolation)
+          continue;
+        }
+        tplBraceDepth[tplBraceDepth.length - 1]--;
+      }
+    }
+    out += c; i++;
+  }
+  return out;
+}
+
+// HAND-WRITTEN on purpose and NOT imported from the module (the oracle trap
+// tests/route_permission_check.mjs documents) — and, unlike the pre-1002671 census,
+// deliberately NOT shape-identical to the scanner's ROUTE_DECL_RE either.
+const CENSUS_CALL_RE = /\brouter\s*\.\s*(?:get|post|patch|put|delete)\s*\(/g;
+// A computed member declaration (`router[method](…)`) is invisible to every static
+// recognizer on both sides. Fail loud instead of silently under-counting.
+const CENSUS_DYNAMIC_RE = /\brouter\s*\[/;
 // A floor, so a change that silently guts BOTH sides (e.g. discoverRouteFiles stops
 // finding module routes) reds instead of trivially "matching" at a smaller number.
 const ROUTE_CENSUS_FLOOR = 258;
 
+function censusCount(text) {
+  const code = stripNonCode(String(text));
+  assert.ok(!CENSUS_DYNAMIC_RE.test(code),
+    'route file uses a computed router[method](…) declaration — invisible to the rank auditor; declare it statically');
+  return (code.match(CENSUS_CALL_RE) || []).length;
+}
+
+test('census tokenizer: strips comments, strings, and quote-bearing regex literals', () => {
+  assert.equal(censusCount(`// router.get('/a', h)\nrouter.post('/b', h);`), 1);
+  assert.equal(censusCount(`const s = "router.get('/a'"; router.get('/b', h);`), 1);
+  assert.equal(censusCount(`s.replace(/[&<>"']/g, esc); router.get('/x', h);`), 1);
+  assert.equal(censusCount('const t = `x ${router.get(\'/live\', h)} y`;'), 1);
+});
+
+test('census independence: counts declarations the line-anchored scanner cannot see', () => {
+  // Inline (mid-line) declaration: census sees it, scanDeclarations does not. If the
+  // scanner ever learns this form, this fixture forces the census comparison to be
+  // revisited deliberately rather than drifting in lockstep.
+  const text = `if (flag) router.get('/inline', h);`;
+  assert.equal(censusCount(text), 1);
+  assert.equal(rrc.classifyText(text).length, 0,
+    'fixture stale: the scanner now classifies inline declarations — update the census comment');
+});
+
 test('LIVE census: every router.<method>( declaration classifies to exactly one route [BV1.R109b]', () => {
   const fs = require('node:fs');
   let declared = 0;
@@ -447,7 +555,7 @@ test('LIVE census: every router.<method>( declaration classifies to exactly one
   const shortfall = [];
   for (const { abs, rel } of rrc.discoverRouteFiles()) {
     const text = fs.readFileSync(abs, 'utf8');
-    const d = text.split('\n').filter((l) => CENSUS_DECL_RE.test(l)).length;
+    const d = censusCount(text);
     const c = rrc.classifyText(text).length;
     declared += d;
     classified += c;