@bongos/core 1.19.1036 → 1.19.1037

package/modules/grading/grader.js

@@ -75,23 +75,28 @@
 //   module (which receives it via dependency injection to avoid a circular
 //   require).
 //
-// ## Legacy v1 (still exported)
+// ## Retired (task 1002842)
 //
-//   gradeDeterministic(...) — v1 deterministic path, kept for
-//   scripts/gds/audit-ships.js (retroactive audit). NOT invoked at ship time.
+//   The v1 deterministic process-audit grader (gradeDeterministic and its nine
+//   per-criterion scorers) and its one caller, scripts/gds/audit-ships.js, are
+//   deleted: the live panel grades every ship at ship time, so a retroactive
+//   heuristic audit has nothing left to cover. aggregateShots / runOneShot moved
+//   to grader-no-artifact.js, the species that depends on them; they are still
+//   re-exported here, and the trivial-diff fast path below still runs one shot.
 
 const path = require('node:path');
 const fs = require('node:fs');
 const { spawn } = require('node:child_process');
 
-const { ASSUMED_BUILDER_MODEL, DEFAULT_GRADER_MODEL, DEFAULT_SHOTS, FALLTHROUGH_CONFIDENCE, RUBRIC, THRESHOLD, V1, V3, VERSION, generatedProvenance, permissionPathPrePass, routeRankPrePass, workers } = require('./grader-config.js');
+const { ASSUMED_BUILDER_MODEL, DEFAULT_GRADER_MODEL, FALLTHROUGH_CONFIDENCE, RUBRIC, THRESHOLD, VERSION, generatedProvenance, permissionPathPrePass, routeRankPrePass, workers } = require('./grader-config.js');
 const { clamp, isTrivialDiff, median, r1, selectGraderModel, workerModelFor } = require('./grader-model.js');
 const { buildPrompt, extractJson } = require('./grader-prompt.js');
 // task 1004011: the second grade species — a grade over the CLAIM on an
 // --allow-empty ship, where there is no diff for the panel above to read.
-const { GRADER_KIND: NO_ARTIFACT_GRADER_KIND, buildNoArtifactPrompt, gradeNoArtifact } = require('./grader-no-artifact.js');
-const { aggregateShots, changeMagnitude, hasPanelEvidence, isSubstantiveIssue, serverSideGuards, validateAndScore } = require('./grader-score.js');
-const { buildContextBundle, diffAddedLinesByFile, extractAssistantResult, extractCostUsd, runOneShot, runSubagent, runSubagentCached } = require('./grader-subagent.js');
+// task 1002842: the generalist-shot plumbing now lives there too.
+const { GRADER_KIND: NO_ARTIFACT_GRADER_KIND, aggregateShots, buildNoArtifactPrompt, gradeNoArtifact, runOneShot } = require('./grader-no-artifact.js');
+const { changeMagnitude, hasPanelEvidence, isSubstantiveIssue, serverSideGuards, validateAndScore } = require('./grader-score.js');
+const { buildContextBundle, diffAddedLinesByFile, extractAssistantResult, extractCostUsd, runSubagent, runSubagentCached } = require('./grader-subagent.js');
 // task 1002903: the severity gate's unbacked low scores, named once for the record.
 const { unbackedLowScores } = require('./grader-workers/worker-verdict.js');
 // task 1002839: the central engine the code panel below registers into (ADR 0089 §1).
@@ -478,8 +483,8 @@ function aggregatePanel(workerResults, meta = {}) {
     grader_version: VERSION,
     // #486: the panel's own API spend (USD), for cost_log (source=grader).
     panel_cost_usd: panelCostUsd,
-    // rubric_scores keep the v3 keys so the trend dashboard + audit-ships
-    // legacy v1 entry-points continue to read them. Phase 2.1 added
+    // rubric_scores keep the v3 keys so the trend dashboard and the server's
+    // validateAndScore re-validation continue to read them. Phase 2.1 added
     // security_score; Phase 2.2 adds efficiency_score. Both additive —
     // consumers that don't know about them just ignore the fields.
     rubric_scores: {
@@ -651,12 +656,17 @@ async function gradeSubagent({ task, valueSummary, diff, changedFiles, diffStats
   });
 }
 
-// ---------- v3 multi-shot path (kept exported for explicit diagnostics) ----------
+// ---------- the trivial-diff fast path (#513) ----------
 //
-// Same shape as the original v3 gradeSubagent; renamed so the public name
-// (gradeSubagent) points at the v4 panel. Useful for re-running a single
-// generalist prompt N times for diagnostic comparison against the panel.
-async function gradeSubagentV3MultiShot({ task, valueSummary, diff, changedFiles, diffStats, shots = DEFAULT_SHOTS, builderModel, runOpts = {} }) {
+// A small copy/docs-only diff gets ONE generalist shot instead of the four-worker
+// panel — "lighter, not skipped" (ADR 0089 §7 keeps it). The name is historical:
+// the v3 multi-shot GENERATION is retired (task 1002842 removed its 3-shot default
+// and rubric block), and this is what is left of it — the working fast path.
+// Moving it onto a v4 panel needs a reviewer type that reports both
+// functional_fidelity and code_quality, which no v4 worker does; that is a cost
+// and behaviour decision, not a cleanup. `runShot` is a test seam defaulted to
+// the real spawner (the same pattern as gradeNoArtifact); production passes none.
+async function gradeSubagentV3MultiShot({ task, valueSummary, diff, changedFiles, diffStats, shots = 1, builderModel, runOpts = {}, runShot = runOneShot }) {
   const prompt = buildPrompt({ task, valueSummary, diff, changedFiles, diffStats, generatedProvenance: await generatedProvenance.verifyGeneratedProvenanceAsync({ changedFiles, cwd: runOpts.cwd }) }); // task 1002795
   const graderModel = selectGraderModel({ builderModel });
   const N = Math.max(1, Math.trunc(shots));
@@ -664,7 +674,7 @@ async function gradeSubagentV3MultiShot({ task, valueSummary, diff, changedFiles
   const startedAt = Date.now();
   const shotPromises = [];
   for (let i = 0; i < N; i++) {
-    shotPromises.push(runOneShot({ prompt, model: graderModel, shotIndex: i, runOpts }));
+    shotPromises.push(runShot({ prompt, model: graderModel, shotIndex: i, runOpts }));
   }
   const shotResults = await Promise.all(shotPromises);
   const totalMs = Date.now() - startedAt;
@@ -676,189 +686,6 @@ async function gradeSubagentV3MultiShot({ task, valueSummary, diff, changedFiles
   });
 }
 
-// =========================================================================
-// Legacy v1 (deterministic) — kept for scripts/gds/audit-ships.js only.
-// =========================================================================
-
-function scoreEstActualBand(actualMinutes, estMinutes) {
-  if (!Number.isFinite(actualMinutes) || actualMinutes <= 0) return 5;
-  if (!Number.isFinite(estMinutes) || estMinutes <= 0) return 6;
-  const ratio = actualMinutes / estMinutes;
-  if (ratio >= 0.5 && ratio <= 2.0) return 10;
-  if (ratio < 0.5) {
-    if (ratio <= 0.1) return 0;
-    return r1(10 * ((ratio - 0.1) / 0.4));
-  }
-  if (ratio > 2.0) {
-    if (ratio >= 10) return 0;
-    return r1(10 * (1 - (ratio - 2.0) / 8.0));
-  }
-  return 5;
-}
-
-function scoreValueSummary(valueSummary) {
-  const s = (valueSummary || '').trim();
-  if (s.length === 0) return 0;
-  if (s.length < 40) return 5;
-  if (s.length < 120) return 8;
-  return /\b(add|fix|update|remove|refactor|wire|land|migrate|enable|disable|introduce|deprecate|ship|deploy|prevent|capture|gate|allocate|carry|expose|surface)\b/i.test(s)
-    ? 10
-    : 8;
-}
-
-function scoreDiffHygiene(diffStats) {
-  if (!diffStats) return 5;
-  const files = Number(diffStats.files_changed) || 0;
-  const added = Number(diffStats.lines_added) || 0;
-  const removed = Number(diffStats.lines_removed) || 0;
-  if (files === 0 || added + removed === 0) return 0;
-  if (files > 50) return 5;
-  return 10;
-}
-
-function scoreScannerSmoke(verification) {
-  if (!verification) return 5;
-  return verification.scanner_clean && verification.smoke_clean ? 10 : 5;
-}
-
-function scoreScopingSignal(scopingConfidence) {
-  if (scopingConfidence == null) return 6;
-  const c = Number(scopingConfidence);
-  if (c <= 0) return 2;
-  if (c === 1) return 4;
-  if (c === 2) return 6;
-  if (c === 3) return 7;
-  if (c === 4) return 8;
-  return 10;
-}
-
-function scoreLocNetNegative(diffStats) {
-  if (!diffStats) return 5;
-  const added = Number(diffStats.lines_added) || 0;
-  const removed = Number(diffStats.lines_removed) || 0;
-  if (removed > added) return 10;
-  if (removed === added) return 5;
-  return 0;
-}
-
-function scoreLearningRow(learningRow) {
-  if (!learningRow) return 0;
-  const body = (learningRow.body_md || '').trim();
-  if (body.length > 100) return 10;
-  if (body.length > 0) return 5;
-  return 0;
-}
-
-function scoreArtRubricAvg(value) {
-  if (!Number.isFinite(value)) return null;
-  return clamp(r1(value), 0, 10);
-}
-
-function blendWeightsForKind(kind) {
-  const blended = {};
-  for (const [name, def] of Object.entries(V1.weights.common)) {
-    blended[name] = def.weight;
-  }
-  const kindBonus = V1.weights.kind_specific[kind];
-  if (kindBonus) {
-    for (const [name, def] of Object.entries(kindBonus)) {
-      if (name === 'loc_net_negative' && 'diff_hygiene' in blended) delete blended.diff_hygiene;
-      if (name === 'learning_row' && 'diff_hygiene' in blended) delete blended.diff_hygiene;
-      blended[name] = def.weight;
-    }
-  }
-  const total = Object.values(blended).reduce((a, b) => a + b, 0);
-  for (const k of Object.keys(blended)) blended[k] = blended[k] / total;
-  return blended;
-}
-
-// Legacy v1 entry. Renamed from `grade()` in V3.R18 (#209). Now ONLY
-// called from scripts/gds/audit-ships.js (retroactive #204 audit). The
-// runtime ship path uses gradeSubagent (v3 multi-shot).
-function gradeDeterministic({ task, verification, actualMinutes, valueSummary, learningRow }) {
-  const kind = task?.kind || 'unclassified';
-  const weights = blendWeightsForKind(kind);
-  const rubricScores = {};
-  const signals = {
-    kind,
-    est_minutes: task?.est_minutes ?? null,
-    actual_minutes: actualMinutes ?? null,
-    scoping_confidence: task?.scoping_confidence ?? null,
-    scanner_clean: verification?.scanner_clean ?? null,
-    smoke_clean: verification?.smoke_clean ?? null,
-    diff_stats: verification?.diff_stats ?? null,
-    art_rubric_avg: verification?.art_rubric_avg ?? null,
-    value_summary_chars: (valueSummary || '').trim().length,
-  };
-
-  if ('est_actual_band' in weights) {
-    rubricScores.est_actual_band = scoreEstActualBand(actualMinutes, task?.est_minutes);
-  }
-  if ('value_summary' in weights) {
-    rubricScores.value_summary = scoreValueSummary(valueSummary);
-  }
-  if ('diff_hygiene' in weights) {
-    rubricScores.diff_hygiene = scoreDiffHygiene(verification?.diff_stats);
-  }
-  if ('scanner_smoke' in weights) {
-    rubricScores.scanner_smoke = scoreScannerSmoke(verification);
-  }
-  if ('scoping_signal' in weights) {
-    rubricScores.scoping_signal = scoreScopingSignal(task?.scoping_confidence);
-  }
-  if ('loc_net_negative' in weights) {
-    rubricScores.loc_net_negative = scoreLocNetNegative(verification?.diff_stats);
-  }
-  if ('learning_row' in weights) {
-    rubricScores.learning_row = scoreLearningRow(learningRow);
-  }
-  if ('art_rubric_avg' in weights) {
-    const s = scoreArtRubricAvg(verification?.art_rubric_avg);
-    if (s == null) {
-      const w = weights.art_rubric_avg;
-      delete weights.art_rubric_avg;
-      const remaining = Object.values(weights).reduce((a, b) => a + b, 0);
-      if (remaining > 0) {
-        for (const k of Object.keys(weights)) weights[k] = weights[k] / remaining;
-      }
-    } else {
-      rubricScores.art_rubric_avg = s;
-    }
-  }
-
-  let score = 0;
-  for (const [name, w] of Object.entries(weights)) {
-    if (rubricScores[name] != null) score += rubricScores[name] * w;
-  }
-  score = r1(clamp(score, 0, 10));
-
-  const threshold = V1.threshold;
-  const passed = score >= threshold;
-
-  const lines = [];
-  lines.push(`Auto-grader ${V1.version} (deprecated) — task_kind=${kind}.`);
-  lines.push(`Score ${score}/10 vs threshold ${threshold} → ${passed ? 'PASS' : 'FAIL'}.`);
-  lines.push('');
-  lines.push('Per-criterion:');
-  for (const [name, w] of Object.entries(weights)) {
-    const s = rubricScores[name];
-    if (s == null) continue;
-    const contrib = r1(s * w);
-    lines.push(`  - ${name.padEnd(20)} ${String(s).padStart(4)}/10  × ${w.toFixed(2)} = ${contrib}`);
-  }
-
-  return {
-    score,
-    passed,
-    threshold,
-    grader_kind: 'auto',
-    grader_version: V1.version,
-    rubric_scores: rubricScores,
-    signals,
-    notes_md: lines.join('\n'),
-  };
-}
-
 module.exports = {
   // v4 surface (active panel-based gate)
   aggregatePanel,
@@ -888,25 +715,13 @@ module.exports = {
   runSubagent,
   runSubagentCached,              // System 5 (task 1359): opt-in content-addressed cached path
   runOneShot,
-  gradeSubagentV3MultiShot,       // explicit v3 multi-shot diagnostic path
+  gradeSubagentV3MultiShot,       // the trivial-diff fast path (#513) — one generalist shot
   extractJson,
   extractAssistantResult,
   extractCostUsd,                 // #486: parse total_cost_usd from the envelope
   THRESHOLD,
   VERSION,
   DEFAULT_GRADER_MODEL,
-  DEFAULT_SHOTS,
   ASSUMED_BUILDER_MODEL,
-  // legacy v1 (audit-ships.js only)
-  gradeDeterministic,
-  scoreEstActualBand,
-  scoreValueSummary,
-  scoreDiffHygiene,
-  scoreScannerSmoke,
-  scoreScopingSignal,
-  scoreLocNetNegative,
-  scoreLearningRow,
-  scoreArtRubricAvg,
-  blendWeightsForKind,
   RUBRIC,
 };

package/modules/lifecycle/db-ship.js

@@ -277,9 +277,9 @@ async function resolveClaim({ claimId, builderId, outcome, notesMd, valueSummary
     // The ordering below is NOT for the grader, whatever this comment used to
     // say. V3.R18 (#209) moved the grader out of resolveClaim — see the block
     // after this one — and the live panel never receives actual_minutes at all
-    // (modules/grading/grader-prompt.js buildPrompt prints est_minutes only;
-    // scoreEstActualBand lives in gradeDeterministic, whose one non-test caller
-    // is the retroactive audit in scripts/gds/audit-ships.js). The seal must
+    // (modules/grading/grader-prompt.js buildPrompt prints est_minutes only; the
+    // one scorer that read actual_minutes was retired with the v1 grader in task
+    // 1002842). The seal must
     // still precede the recompute, because the recompute SUMs the row it writes.
     // tests/regrade_actual_minutes.mjs pins the panel half of that.
     await sealSessionLog(client, {

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1036",
+  "version": "1.19.1037",
   "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/release-notes.json

@@ -7497,5 +7497,15 @@
       "id": "1004174",
       "text": "The owner of a hosted project can now upgrade it themselves: the \"you're behind\" banner on their project links to the Deploy page on the hub, which lets a project's owner move their own project, and only their own."
     }
+  ],
+  "1.19.1037": [
+    {
+      "id": "1002842",
+      "text": "The grader's retired first generation and an unused one-off audit script are removed, and the pieces a newer reviewer still depends on now live with it — nothing about how work is graded changes."
+    },
+    {
+      "id": "1004280",
+      "text": "The project's own notes no longer claim a past decision banned all new checks; each one now gives its real reason, and a test stops the wrong claim coming back."
+    }
   ]
 }

package/scripts/gds/claim.js

@@ -739,7 +739,8 @@ async function main() {
     // last thing the builder reads before deciding how to work — task 1267.
     printDisciplineMode(task);
     // task 1004202: a task that changes a page is told to use /design and get its
-    // human's OK on the before/after. A nudge, never a gate (ADR 0162).
+    // human's OK on the before/after. A nudge, never a gate: gating on that OK would
+    // put a person's approval in the land path, which ADR 0162 retired.
     try {
       const nudge = visualReviewNudge(task);
       if (nudge) console.log(`\n${nudge.join('\n')}`);

package/scripts/gds/grade-smoke.js

@@ -2,7 +2,7 @@
 // Subagent grader smoke test — GDS-V3 task V3.R18 (#209) → MAS Phase 1 #395.
 //
 // Runs two synthetic ship scenarios end-to-end through the v3 multi-shot
-// subagent grader (DEFAULT_SHOTS × cross-family model, unanimous-PASS gate).
+// subagent grader (the worker panel, cross-family model, unanimous-PASS gate).
 // Asserts:
 //
 //   - Known-GOOD ship: a tiny, complete change → grade passes (unanimous
@@ -148,8 +148,8 @@ function summarize(result, label) {
 // -------- Main --------
 
 (async () => {
-  console.log(`Running subagent grader smoke (v${grader.VERSION}, model=${grader.DEFAULT_GRADER_MODEL}, ${grader.DEFAULT_SHOTS}× shots, threshold=${grader.THRESHOLD})`);
-  console.log('Two scenarios will run sequentially. Each spawns 3 parallel shots.');
+  console.log(`Running subagent grader smoke (v${grader.VERSION}, model=${grader.DEFAULT_GRADER_MODEL}, ${grader.WORKERS.DEFAULT_PANEL.length}-worker panel, threshold=${grader.THRESHOLD})`);
+  console.log(`Two scenarios will run sequentially. Each runs the ${grader.WORKERS.DEFAULT_PANEL.length}-worker panel.`);
 
   let assertFailures = 0;
 

package/scripts/gds/render-check.js

@@ -7,7 +7,7 @@
 // count that still ran past its card (task 1003480) and a second grid child landing on the first (task 1003078)
 // both shipped looking correct in code and were found only by opening a browser.
 //
-// A SIGNAL, never a gate (ADR 0162): /ship-check shows it as an advisory row; ship.js and the grader never
+// A SIGNAL, never a gate (ADR 0329, decisions 3-4): /ship-check shows it as an advisory row; ship.js and the grader never
 // read it. The measurement is the kit's `text-fit` + `sibling-overlap` floors (modules/ui-design/kit/lib.js);
 // this file only picks the pages, runs the kit's renderer at 1280 + 390, and keeps those two floors.
 //

package/scripts/gds/ship-check.js

@@ -25,7 +25,7 @@ const REPO_ROOT = path.resolve(__dirname, '..', '..');
 
 // Each step: a label, the argv to run (node scripts run with THIS node), the command that heals it,
 // and how to read a non-zero exit. `optional` steps are skipped when their script is absent. An `advisory`
-// step is a signal, never a gate (ADR 0162): a non-zero exit reads `warn` (3 = no browser reads `skipped`).
+// step is a signal, never a gate (ADR 0329, decision 3): a non-zero exit reads `warn` (3 = no browser reads `skipped`).
 // `onlyWith` names the flag that adds a step; `skipWith` the flag that leaves one out.
 const STEPS = [
   { key: 'fitness', label: 'fitness.js (architecture + budgets + freshness gate)', argv: ['scripts/gds/fitness.js'], fix: 'read the ✗ lines above; each names its fix' },

package/scripts/gds/ship-flow.js

@@ -496,7 +496,7 @@ async function shipMain() {
       passed,
       // touches[] cleanup [4/8] (task 879): the drift scanner is gone; with no
       // scanner there is nothing to drift, so this audit-trail signal
-      // (grader.scoreScannerSmoke) is vacuously clean.
+      // (read by the retired v1 grader, task 1002842) is vacuously clean.
       scanner_clean: true,
       smoke_clean: smoke.clean,
     },

package/scripts/gds/ship-grade-steps.js

@@ -314,7 +314,7 @@ function formatOutageDiagnostic(g, cliFinding) {
 
 // cliFinding: the preflight `claude CLI` row, injected by printGradeOutcome so a
 // dark panel can say "your CLI is logged out" instead of leaving the builder to
-// guess. Report-only — it never changes the outcome (ADR 0162: no new gates).
+// guess. Report-only — it never changes the outcome: it explains an outage, it does not decide one.
 function formatGradeOutcome(g, taskId, cliFinding = null) {
   const out = [];
   // #943: a TOTAL grader outage (every gating worker failed to spawn / the
@@ -466,7 +466,7 @@ function printGradeOutcome(g, taskId) {
   // task 1003313: on a TOTAL outage only, ask the existing preflight whether the
   // local `claude` CLI is launchable and logged in — the two faults that produce
   // this exact all-workers-dead signature. Report-only and outage-only, so the
-  // happy path pays nothing and no ship is newly gated (ADR 0162).
+  // happy path pays nothing and no ship's outcome depends on the probe.
   let cliFinding = null;
   if (g?.signals?.panel_outcome === 'unavailable') {
     try {

package/scripts/gds/visual-review-nudge.js

@@ -5,7 +5,8 @@
 // real browser, and get the human's OK on the before/after before shipping — the
 // project default for every builder since the owner's 2026-09-23 decision.
 //
-// A NUDGE, never a gate (ADR 0162). "Is this UI work" is the ONE predicate the
+// A NUDGE, never a gate: as a gate, the human's OK would be a person's approval in
+// the land path, which ADR 0162 retired. "Is this UI work" is the ONE predicate the
 // artist review and the grader's copy lens already use (lifecycle/cascade.js), so
 // the three cannot disagree. Nothing has changed yet at claim time, so it is fed
 // the paths the task NAMES: its touches[] and any modules/*/public/ path written

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.1036'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.1037'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/adr_0162_gate_citation.mjs

@@ -0,0 +1,167 @@
+// tests/adr_0162_gate_citation.mjs — "no new gates" is not what ADR 0162 decided; no surface
+// may cite 0162 as the reason something is a signal and not a gate (task 1004280).
+//
+// WHAT WENT WRONG. Task 1003573 corrected one slogan cited to ADR 0162 ("verdicts are advisory,
+// never self-executing" — ADR 0158 §2's rule; tests/adr_0162_citation.mjs pins that). A sibling
+// slogan rode along: "no new gates (ADR 0162)", "a signal, never a gate (ADR 0162)", "NOT A
+// PIPELINE GATE (ADR 0162)". It is broader than the ADR. 0162 retired REVIEW gates — a gate that
+// needs a particular person's approval before work can land — and its own table keeps four
+// automatic controls, three of which fail CLOSED (the grader among them). ADR 0241 ("What ADR 0162
+// actually forbids") states the test 0162 leaves behind: an automatic, state-read, rank-consistent
+// gate with a named escape hatch is admissible. So "this is not a gate because 0162" cites a rule
+// 0162 does not make, and it hides the surface's real reason for staying advisory.
+//
+// The surfaces keep their choice (most were right to stay advisory); only the reason changed:
+// 0162 for "no human approval in the land path", and the surface's own reason otherwise.
+//
+// WHAT THIS PINS. (1) The premise, read from the ADRs: 0162 keeps fail-closed automatic controls
+// and never says "no new gates"; 0241 says what 0162 forbids. (2) No tracked surface cites 0162
+// with the gate shorthand, in any of the shapes the 2026-09-25 sweep found.
+//
+// Run:  node --test tests/adr_0162_gate_citation.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const read = (rel) => readFileSync(path.join(ROOT, rel), 'utf8');
+
+const ADR_0162 = 'docs/adr/0162-review-gates-retired-rank-consistent-ci-only.md';
+const ADR_0241 = 'docs/adr/0241-the-artist-gate-is-a-per-project-deploy-gate-that-reads-a-state.md';
+
+// A match is a line that gives 0162 as the reason something is not (or must not be) a gate.
+const GATE_SHORTHANDS = [
+  // The advisory claim, then 0162 as its source: "no new gates (ADR 0162)", "A SIGNAL, never a
+  // gate (ADR 0162)", "NOT A PIPELINE GATE (ADR 0162)", "no ship is newly gated (ADR 0162)",
+  // "WITHOUT adding a gate (ADR 0162)", "It gates NOTHING (ADR 0162 / ADR 0241)", "a new gate on
+  // the ship path (ADR 0162)", "It had to stay a signal (ADR 0162)", "never flips its exit (ADR 0162)".
+  /\b(?:no new gates?|never a gate|not a (?:pipeline )?gate|newly gated|adding a gate|gates nothing|new gate on the ship path|stay a signal|never flips its exit)\b[^\n()]{0,40}\(ADR 0162\b/i,
+  // 0162, then the shorthand as its gloss: "ADR 0162 — no new gates", "(ADR 0162: no new gates)",
+  // "[ADR 0162](…) (no new gates)".
+  /\b0162\b[\])]?\s*(?:\(|—|–|:)\s*no new gates?\b/i,
+  // A describe-only posture cited to 0162: "(describe, never confirm/flip — ADR 0162)". That is
+  // 0158 §2's rule — the sibling test's subject, in a shape it does not match.
+  /\bnever confirm\/flip\s*[—–-]\s*ADR 0162\b/i,
+];
+
+// Deliberately NOT corrected, each with its reason. Shrink-only: when one is fixed, delete its
+// row — the last test fails until you do, so a stale exemption cannot outlive what it excused.
+const KNOWN_DEFERRED = new Map([
+  // HARD-FLOOR surfaces (scripts/gds/gate-review.js HARD_FLOOR_GLOBS lists `.claude/hooks/`):
+  // even a comment-only edit escalates to the owner, which a citation fix does not justify on
+  // its own. Correct them with the next real edit (the redteam-patrol.yml precedent, task 1003573).
+  ['.claude/hooks/allow-rule-guard.js', 'hard-floor gate surface'],
+  ['.claude/hooks/git-guard.js', 'hard-floor gate surface'],
+  // A hall PAGE script: any edit under modules/*/public/ is UI work, so its ship files an artist
+  // review that holds the deploy (ADR 0241). A comment fix does not justify that; correct it
+  // with the next real edit to the page.
+  ['modules/hall-ui/public/studio.js', 'page script — an edit files an artist review'],
+]);
+
+const HISTORICAL = /^docs\/session-logs\//;
+// This file and its sibling quote the shapes they hunt, as examples.
+const SELF = new Set(['tests/adr_0162_gate_citation.mjs', 'tests/adr_0162_citation.mjs']);
+const TEXT = /\.(?:md|js|mjs|cjs|json|ya?ml|sql|sh|html|txt)$/;
+// A line that NAMES the slogan as its subject is discussing it, not citing by it.
+const DISCUSSES_SLOGAN = /paraphrase|shorthand/i;
+// Markdown link targets carry the ADR's filename, which would sit between a citation and its gloss.
+const stripLinkTargets = (s) => s.replace(/\]\([^)\s]*\)/g, ']');
+const continuation = (s) => (s || '').replace(/^\s*(?:\/\/+|#+|--|\*|>|-)?\s*/, '');
+
+function offendersIn(rel, text) {
+  const lines = stripLinkTargets(text).split('\n');
+  const hits = [];
+  for (let i = 0; i < lines.length; i++) {
+    const here = lines[i];
+    if (DISCUSSES_SLOGAN.test(here)) continue;
+    // Join the next line so a citation wrapped mid-phrase still reads as one; only a match
+    // that STARTS on this line is this line's.
+    const window = `${here} ${continuation(lines[i + 1])}`;
+    if (!/0162/.test(window)) continue;
+    for (const re of GATE_SHORTHANDS) {
+      const m = re.exec(window);
+      if (m && m.index < here.length) { hits.push(`${rel}:${i + 1}: ${here.trim().slice(0, 140)}`); break; }
+    }
+  }
+  return hits;
+}
+
+function trackedTextFiles() {
+  const r = spawnSync('git', ['ls-files', '-z'], { cwd: ROOT, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  if (r.status !== 0) return null; // a packaged core is not a git checkout
+  return r.stdout.split('\0').filter((f) => f && TEXT.test(f));
+}
+
+test('the premise: ADR 0162 keeps automatic gates that fail closed, and never says "no new gates"', () => {
+  const adr0162 = read(ADR_0162);
+  assert.match(adr0162, /Review requirements on `main` are \*\*retired permanently\*\*/, 'what 0162 retired');
+  const failsClosed = adr0162.split('\n').filter((l) => /^\|.*\|\s*closed\s*\|\s*$/.test(l));
+  assert.ok(failsClosed.length >= 3,
+    `0162's compensating-controls table should keep >=3 controls that fail CLOSED (found ${failsClosed.length}) — `
+    + 'if the ADR changed, re-ask whether "no new gates" became its rule before re-pointing these citations');
+  assert.doesNotMatch(adr0162, /no new gates?/i, 'ADR 0162 never says "no new gates"');
+  assert.match(read(ADR_0241), /^## What ADR 0162 actually forbids$/m, 'ADR 0241 is where the narrower rule is written');
+});
+
+test('the detector recognises every shape the sweep corrected, and passes the true citations', () => {
+  const flag = (line) => offendersIn('probe.md', line).length > 0;
+  for (const bad of [
+    '- **ADR 0162 — no new gates.** This skill describes and recovers; it never inserts a human-approval step',
+    '// A SIGNAL, never a gate (ADR 0162): /ship-check shows it as an advisory row; ship.js and the grader never',
+    '// step is a signal, never a gate (ADR 0162): a non-zero exit reads `warn` (3 = no browser reads `skipped`).',
+    '// A NUDGE, never a gate (ADR 0162). "Is this UI work" is the ONE predicate the',
+    '    // human\'s OK on the before/after. A nudge, never a gate (ADR 0162).',
+    '// guess. Report-only — it never changes the outcome (ADR 0162: no new gates).',
+    '  // happy path pays nothing and no ship is newly gated (ADR 0162).',
+    '- **Relates to:** [ADR 0162](0162-review-gates-retired-rank-consistent-ci-only.md) (no new gates), [ADR 0197](0197-the-ui-design-module.md) (the kit)',
+    'or both. It had to stay a signal (ADR 0162).',
+    '- **Block the fourth attempt.** That is a new gate on the ship path (ADR 0162), and a wrong',
+    'shows them as an ADVISORY row that never flips its exit (ADR 0162). Not a grader worker',
+    '// NOT A PIPELINE GATE (ADR 0162): it gates no merge, no CI check, no ship.',
+    '// It gates NOTHING (ADR 0162 / ADR 0241): nothing here holds a ship or a deploy.',
+    '// pass and WITHOUT adding a gate (ADR 0162). Every case below that has a low',
+    '// read-only (describe, never confirm/flip — ADR 0162).',
+  ]) assert.ok(flag(bad), `should flag: ${bad}`);
+
+  for (const good of [
+    '- **Related:** ADR 0162 (no new human gates on the ship path)',
+    'No review requirement — gates are CI checks, not human approvals (ADR 0162).',
+    '- **Relates to:** [ADR 0162](0162-review-gates-retired-rank-consistent-ci-only.md) (review gates retired: no human approval in the land path)',
+    'no confirms, no status flips, and no new approval step on anyone\'s ship (ADR 0162). The remediation lines',
+    '// A NUDGE, never a gate: as a gate, the human\'s OK would be a person\'s approval in\n// the land path, which ADR 0162 retired.',
+    '// A SIGNAL, never a gate (ADR 0329, decisions 3-4): /ship-check shows it as an advisory row',
+    'It never holds a builder\'s ship, which is what keeps it compatible with ADR 0162.',
+    'This matters, because the shorthand "no new gates (ADR 0162)" is broader than the ADR',
+  ]) assert.ok(!flag(good), `should pass: ${good}`);
+});
+
+test('no tracked surface cites ADR 0162 as the reason something is not a gate', (t) => {
+  const files = trackedTextFiles();
+  if (!files) return t.skip('not a git checkout — nothing tracked to scan');
+  const offenders = [];
+  for (const rel of files) {
+    if (SELF.has(rel) || HISTORICAL.test(rel) || KNOWN_DEFERRED.has(rel)) continue;
+    let text;
+    try { text = readFileSync(path.join(ROOT, rel), 'utf8'); } catch { continue; }
+    if (!text.includes('0162')) continue;
+    offenders.push(...offendersIn(rel, text));
+  }
+  assert.deepEqual(offenders, [],
+    'these cite ADR 0162 for "no new gates" / "a signal, never a gate". 0162 retired gates that need a '
+    + 'particular person\'s approval in the land path, and keeps automatic gates that fail closed (ADR 0241). '
+    + 'Cite 0162 for "no human approval in the land path", and name the surface\'s own reason for staying advisory.');
+});
+
+test('every deferred exemption still has something to excuse (shrink-only)', (t) => {
+  if (!trackedTextFiles()) return t.skip('not a git checkout');
+  for (const [rel, why] of KNOWN_DEFERRED) {
+    let text = '';
+    try { text = read(rel); } catch { /* deleted: the exemption is stale too */ }
+    assert.ok(offendersIn(rel, text).length > 0,
+      `${rel} (${why}) no longer cites 0162 for the gate shorthand — delete its KNOWN_DEFERRED row`);
+  }
+});