session-orchestrator 3.21.0 → 3.22.0

package/scripts/lib/resource-probe.mjs

@@ -18,6 +18,7 @@
  *     cpu_load_5m: 1.8,
  *     cpu_load_5m_pct: 45 | null,   // 5m load-average as pct-of-cores; null on Windows/zero-load (#943)
  *     claude_processes_count: 3 | null,
+ *     peer_sessions_count: 2 | null,   // live peer SESSIONS from the registry, self excluded (#1089)
  *     codex_processes_count: 0 | null,
  *     other_node_processes: 12 | null,
  *     zombie_processes_count: 1 | null,
@@ -40,13 +41,14 @@
  */
 
 import os from 'node:os';
-import { ramSnapshot, cpuSnapshot, processCounts, swapUsedMb, memoryPressurePctFree, ramAvailableGb } from './resource-probe/probe-platform.mjs';
+import { ramSnapshot, cpuSnapshot, processCounts, swapUsedMb, memoryPressurePctFree, ramAvailableGb, peerSessionsCount } from './resource-probe/probe-platform.mjs';
 
 // ---------------------------------------------------------------------------
 // Re-exports — preserve public API for all existing callers
 // ---------------------------------------------------------------------------
 
-export { evaluate } from './resource-probe/evaluate.mjs';
+export { evaluate, PROCESSES_PER_SESSION, PRESSURE_HARD_PCT, PRESSURE_SOFT_PCT, PRESSURE_HEALTHY_PCT, DEFAULT_RESOURCE_THRESHOLDS } from './resource-probe/evaluate.mjs';
+export { peerSessionsCount } from './resource-probe/probe-platform.mjs';
 export { parseEtimeToMinutes, countZombieProcesses, countProcessMatches, parseSwapUsageOutput, parseMemoryPressureOutput, parseVmStatAvailableGb } from './resource-probe/parsers.mjs';
 
 // ---------------------------------------------------------------------------
@@ -60,6 +62,9 @@ export { parseEtimeToMinutes, countZombieProcesses, countProcessMatches, parseSw
  * @param {boolean} [opts.skipExtendedSignals] — skip swap + memory_pressure calls (faster in tests)
  * @param {number|null} [opts.zombieThresholdMin] — when non-null, detect zombie Claude/Node
  *   processes older than this many minutes with low CPU. Default null (feature disabled).
+ * @param {string|null} [opts.sessionId] — own session id, excluded from `peer_sessions_count`
+ *   (#1089). Omit and the count simply includes every live registry entry, which
+ *   over-counts by exactly one — pass it whenever the caller knows its own id.
  * @returns {Promise<object>}
  */
 export async function probe(opts = {}) {
@@ -85,6 +90,13 @@ export async function probe(opts = {}) {
     ? { claude_processes_count: null, codex_processes_count: null, other_node_processes: null, zombie_processes_count: null }
     : await processCounts(zombieThresholdMin);
 
+  // #1089: the registry-denominated concurrency signal. Gated on the same
+  // skipProcessCounts flag as the `ps` pass — both answer "who else is on this
+  // host", and tests that skip one always mean to skip the other.
+  const peer_sessions_count = opts.skipProcessCounts
+    ? null
+    : await peerSessionsCount({ sessionId: opts.sessionId ?? null });
+
   let swap_used_mb = null;
   let memory_pressure_pct_free = null;
   let ram_available_gb = null;
@@ -104,6 +116,10 @@ export async function probe(opts = {}) {
     cpu_load_5m,
     cpu_load_5m_pct,
     ...procs,
+    // Live peer SESSIONS (registry, self excluded) — the unit
+    // `concurrent-sessions-warn` is named for. null = registry unreadable, in
+    // which case evaluate() falls back to the rescaled process count (#1089).
+    peer_sessions_count,
     swap_used_mb,
     memory_pressure_pct_free,
     // macOS-only numeric available-RAM (free + reclaimable) from vm_stat; null

package/scripts/lib/spiral-carryover.mjs

@@ -35,8 +35,14 @@
  */
 
 import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
 import { digestSha256Short } from './crypto-digest-utils.mjs';
-import { chargeIssueBudget, formatBlockReason } from './issue-budget.mjs';
+import {
+  chargeIssueBudget,
+  formatBlockReason,
+  resolveIssueBudgetSessionId,
+} from './issue-budget.mjs';
 import { resolveRepoSpec } from './vcs-repo-spec.mjs';
 
 /**
@@ -99,10 +105,25 @@ function runCli(cmd, args) {
   if (isIssueCreateArgv(cmd, args)) {
     try {
       const repoRoot = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+      // The harness exports CLAUDE_CODE_SESSION_ID (measured 2026-08-21: it is
+      // present in the Bash tool environment this module runs in). There is no
+      // CLAUDE_SESSION_ID — reading that name made this whole block dead code
+      // and left the cap permanently off on the programmatic path.
+      const nativeRawId = process.env.CLAUDE_CODE_SESSION_ID ?? null;
+      let currentSession = null;
+      if (typeof nativeRawId === 'string' && nativeRawId.length > 0) {
+        try {
+          currentSession = JSON.parse(
+            readFileSync(path.join(repoRoot, '.orchestrator', 'current-session.json'), 'utf8'),
+          );
+        } catch {
+          // Missing or malformed records conservatively retain the native env key.
+        }
+      }
       const titleIdx = args.indexOf('--title');
       const verdict = chargeIssueBudget({
         repoRoot,
-        sessionId: process.env.CLAUDE_SESSION_ID || null,
+        sessionId: resolveIssueBudgetSessionId(nativeRawId, currentSession),
         command: [cmd, ...args].join(' '),
         title: titleIdx >= 0 ? (args[titleIdx + 1] ?? null) : null,
       });

package/scripts/lib/state-md/mission-status.mjs

@@ -16,6 +16,40 @@
 import { parseStateMd, serializeStateMd } from './yaml-parser.mjs';
 import { updateFrontmatterFields, writeStateMd } from './frontmatter-mutators.mjs';
 
+const MISSION_STATUS_HEADING_RE = /^##\s+Mission Status\s*$/;
+const WRITER_TIMESTAMP_SOURCE = '\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z';
+const WRITER_TIMESTAMP_RE = new RegExp(`^${WRITER_TIMESTAMP_SOURCE}$`);
+const CANONICAL_MISSION_STATUS_ENTRY_RE = new RegExp(
+  `^- ([a-z][a-z0-9]*(?:-[a-z0-9]+)*-\\d+): (.*) \\(updated (${WRITER_TIMESTAMP_SOURCE})\\)$`
+);
+
+/**
+ * Finds the first exact `## Mission Status` section and its closing heading.
+ *
+ * @param {string[]} lines
+ * @returns {{ headingIdx: number, sectionEnd: number }|null}
+ */
+function findMissionStatusSection(lines) {
+  if (!Array.isArray(lines)) return null;
+  const headingIdx = lines.findIndex((line) => MISSION_STATUS_HEADING_RE.test(line));
+  if (headingIdx === -1) return null;
+
+  let sectionEnd = lines.length;
+  for (let i = headingIdx + 1; i < lines.length; i++) {
+    if (/^##\s+/.test(lines[i])) {
+      sectionEnd = i;
+      break;
+    }
+  }
+  return { headingIdx, sectionEnd };
+}
+
+function isWriterTimestamp(timestamp) {
+  if (!WRITER_TIMESTAMP_RE.test(timestamp)) return false;
+  const parsed = new Date(timestamp);
+  return !Number.isNaN(parsed.getTime()) && parsed.toISOString() === timestamp;
+}
+
 /**
  * Parses the optional `mission-status:` block from a STATE.md frontmatter object
  * (as returned by `parseStateMd(...).frontmatter`).
@@ -83,13 +117,17 @@ export function writeMissionStatus(contents, missionStatusArray) {
  * entry level — the input is never mutated, which keeps `parseMissionStatus`'s
  * shallow-copy contract intact for anything else holding the same nested entries).
  *
- * UPDATE-ONLY by design: when the key is absent, is not an array, or holds no entry
- * with a matching `id`, the frontmatter is returned unchanged. It is deliberately
- * neither created nor an error, because `setMissionStatus(contents, taskId, status)`
- * knows only `id` and `status` — it lacks the `task` and `wave` fields a full entry
- * carries, so a synthesised entry would be shape-invalid yet look authoritative to
- * frontmatter consumers such as `vault-status/narrative-mirror.mjs`. Throwing is
- * likewise excluded by the never-throw contract of `setMissionStatus`.
+ * UPDATE-ONLY by design: when the key is absent, is not an array, or holds no
+ * matching entry in a populated array, the frontmatter is returned unchanged. It is
+ * deliberately neither created nor an error, because `setMissionStatus(contents,
+ * taskId, status)` knows only `id` and `status` — it lacks the `task` and `wave`
+ * fields a full entry carries, so a synthesised entry would be shape-invalid yet look
+ * authoritative to frontmatter consumers such as `vault-status/narrative-mirror.mjs`.
+ * Throwing is likewise excluded by the never-throw contract of `setMissionStatus`.
+ *
+ * An empty array is recovered from the final body by
+ * `recoverFrontmatterMissionStatus`, which persists only the truthful `id` and
+ * `status` values available there. It does not fabricate absent metadata.
  *
  * `status` is mirrored verbatim without an enum check on purpose: gating it would
  * reintroduce the exact divergence (body says X, frontmatter says Y) this sync exists
@@ -125,6 +163,80 @@ function syncFrontmatterMissionStatus(frontmatter, taskId, status) {
   return { ...frontmatter, 'mission-status': entries };
 }
 
+/**
+ * Mirrors body-only task IDs into the frontmatter `mission-status` registry as
+ * partial `{ id, status }` entries. This is a SUPERSET merge: existing entries are
+ * never rewritten or reordered, so their full metadata (`task`, `wave`) survives —
+ * only IDs absent from the registry are appended.
+ *
+ * It must not be gated on an EMPTY registry. Recovering only from empty froze the
+ * registry after its first recovery: the sync path (`syncFrontmatterMissionStatus`)
+ * is update-only, so every subsequently added task ID was never mirrored again, and
+ * Phase 1.9/1.10 read a plausible undercount instead of the obvious zero. That is
+ * #1084 one write later — measured m-1/m-2/m-3 in the body against `[m-1]` in the
+ * frontmatter.
+ *
+ * The section parse stays strict and all-or-nothing: any nonblank line that is not a
+ * unique canonical writer bullet (unsafe ID, pipe, malformed timestamp, duplicate,
+ * prose) aborts the whole merge rather than fabricating entries from an ambiguous
+ * body. Known limitation: one foreign-but-writer-accepted ID (e.g. `Docs_2`) or a
+ * hand-written legacy bullet without a timestamp therefore suppresses the merge for
+ * the whole file, silently.
+ *
+ * @param {object} frontmatter
+ * @param {string} body
+ * @returns {object}
+ */
+function recoverFrontmatterMissionStatus(frontmatter, body) {
+  if (frontmatter === null || typeof frontmatter !== 'object' || Array.isArray(frontmatter)) {
+    return frontmatter;
+  }
+  const raw = frontmatter['mission-status'];
+  if (!Array.isArray(raw) || typeof body !== 'string') return frontmatter;
+
+  const lines = body.split('\n');
+  const section = findMissionStatusSection(lines);
+  if (section === null) return frontmatter;
+
+  const entries = [];
+  const ids = new Set();
+  for (let i = section.headingIdx + 1; i < section.sectionEnd; i++) {
+    const line = lines[i];
+    if (line.trim() === '') continue;
+
+    const match = CANONICAL_MISSION_STATUS_ENTRY_RE.exec(line);
+    if (match === null) return frontmatter;
+    const [, id, status, timestamp] = match;
+    if (
+      status.length === 0 ||
+      status.includes('|') ||
+      status.includes('\n') ||
+      !isWriterTimestamp(timestamp) ||
+      ids.has(id)
+    ) {
+      return frontmatter;
+    }
+    ids.add(id);
+    entries.push({ id, status });
+  }
+
+  const known = new Set(
+    raw
+      .filter((e) => e !== null && typeof e === 'object' && !Array.isArray(e))
+      .map((e) => e.id)
+  );
+  const added = entries.filter((e) => !known.has(e.id));
+  if (added.length === 0) return frontmatter;
+  return { ...frontmatter, 'mission-status': [...raw, ...added] };
+}
+
+function serializeMissionStatusUpdate(frontmatter, body) {
+  return serializeStateMd({
+    frontmatter: recoverFrontmatterMissionStatus(frontmatter, body),
+    body,
+  });
+}
+
 /**
  * Sets (or updates) the mission status for a single task in the `## Mission Status` body
  * section of STATE.md. Creates the section if it does not exist.
@@ -137,7 +249,10 @@ function syncFrontmatterMissionStatus(frontmatter, taskId, status) {
  * during a wave; the frontmatter array is what `parseMissionStatus` consumers read
  * (`vault-status/narrative-mirror.mjs`, session-end Phase 1.9/1.10). Before this sync the
  * live writer and the reader sat on different surfaces and drifted apart in both
- * directions. Frontmatter mirroring is UPDATE-ONLY — see `syncFrontmatterMissionStatus`.
+ * directions. A legacy empty registry is recovered from canonical body bullets as
+ * partial `{ id, status }` entries, which lets frontmatter readers classify the work
+ * without fabricated metadata. Ambiguous legacy bodies remain empty; other unmatched
+ * populated entries remain update-only. See `syncFrontmatterMissionStatus`.
  *
  * Pure function — no I/O. Returns original `contents` unchanged on bad input.
  *
@@ -160,31 +275,16 @@ export function setMissionStatus(contents, taskId, status) {
   const bullet = `- ${taskId}: ${status} (updated ${timestamp})`;
   const lines = parsed.body.split('\n');
 
-  // Find existing ## Mission Status section
-  let headingIdx = -1;
-  for (let i = 0; i < lines.length; i++) {
-    if (/^##\s+Mission Status\b/.test(lines[i])) {
-      headingIdx = i;
-      break;
-    }
-  }
-
-  if (headingIdx === -1) {
+  const section = findMissionStatusSection(lines);
+  if (section === null) {
     // Section does not exist — append it at the end
     let bodyOut = parsed.body;
     if (!bodyOut.endsWith('\n')) bodyOut += '\n';
     bodyOut += `\n## Mission Status\n\n${bullet}\n`;
-    return serializeStateMd({ frontmatter, body: bodyOut });
+    return serializeMissionStatusUpdate(frontmatter, bodyOut);
   }
 
-  // Find end of section: next ## heading or end of lines
-  let sectionEnd = lines.length;
-  for (let i = headingIdx + 1; i < lines.length; i++) {
-    if (/^##\s+/.test(lines[i])) {
-      sectionEnd = i;
-      break;
-    }
-  }
+  const { headingIdx, sectionEnd } = section;
 
   // Look for an existing entry with this taskId within the section
   const entryRe = new RegExp(`^-\\s+${taskId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}:`);
@@ -214,18 +314,20 @@ export function setMissionStatus(contents, taskId, status) {
       const before = lines.slice(0, headingIdx + 1);
       const after = lines.slice(insertAt);
       const rebuilt = [...before, '', bullet, ...after];
-      return serializeStateMd({ frontmatter, body: rebuilt.join('\n') });
+      return serializeMissionStatusUpdate(frontmatter, rebuilt.join('\n'));
     }
   }
 
-  return serializeStateMd({ frontmatter, body: lines.join('\n') });
+  return serializeMissionStatusUpdate(frontmatter, lines.join('\n'));
 }
 
 /**
  * Reads the current mission status for a single task from the `## Mission Status` body
  * section of STATE.md.
  *
- * Returns the status string (e.g. `'in-dev'`) or `null` if the task is not found or the
+ * Returns the full status string before a current-writer timestamp (e.g. `'in-dev'`
+ * or `'needs manual testing'`). For legacy body lines that lack that exact form, falls
+ * back to the first status token. Returns `null` if the task is not found or the
  * section does not exist. Never throws — returns `null` on any bad input.
  *
  * @param {string} contents - Current STATE.md file contents (string)
@@ -239,29 +341,24 @@ export function readMissionStatus(contents, taskId) {
   if (parsed === null) return null;
 
   const lines = parsed.body.split('\n');
-  let headingIdx = -1;
-  for (let i = 0; i < lines.length; i++) {
-    if (/^##\s+Mission Status\b/.test(lines[i])) {
-      headingIdx = i;
-      break;
-    }
-  }
-  if (headingIdx === -1) return null;
+  const section = findMissionStatusSection(lines);
+  if (section === null) return null;
 
-  let sectionEnd = lines.length;
-  for (let i = headingIdx + 1; i < lines.length; i++) {
-    if (/^##\s+/.test(lines[i])) {
-      sectionEnd = i;
-      break;
-    }
+  // Prefer the full current-writer status, including internal spaces.
+  const escapedId = taskId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const writerEntryRe = new RegExp(
+    `^- ${escapedId}: (.*) \\(updated ${WRITER_TIMESTAMP_SOURCE}\\)$`
+  );
+  for (let i = section.headingIdx + 1; i < section.sectionEnd; i++) {
+    const match = writerEntryRe.exec(lines[i]);
+    if (match) return match[1];
   }
 
-  // Match: - <taskId>: <status> (updated ...)
-  const escapedId = taskId.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-  const entryRe = new RegExp(`^-\\s+${escapedId}:\\s+(\\S+)`);
-  for (let i = headingIdx + 1; i < sectionEnd; i++) {
-    const m = entryRe.exec(lines[i]);
-    if (m) return m[1];
+  // Reader-only legacy compatibility. Recovery remains canonical and all-or-nothing.
+  const legacyEntryRe = new RegExp(`^-\\s+${escapedId}:\\s+(\\S+)`);
+  for (let i = section.headingIdx + 1; i < section.sectionEnd; i++) {
+    const match = legacyEntryRe.exec(lines[i]);
+    if (match) return match[1];
   }
   return null;
 }

package/scripts/lib/validate/check-auq-clarity.mjs

@@ -0,0 +1,274 @@
+#!/usr/bin/env node
+// check-auq-clarity.mjs — Ratchet guard for the AUQ question corpus (#1107).
+//
+// ## Why this file exists
+//
+// Wave 2 of #1107 built a deterministic measurer for the operator-facing
+// AskUserQuestion corpus (`scripts/lib/auq/` + `scripts/auq-audit.mjs`); wave 3
+// used it to bring the corpus from 21/72 to 72/72 clean. The measurer had zero
+// callers — no npm script, no gate, no skill phase invoked it. That is this
+// repo's documented systemic failure class ("built, documented, tested, never
+// switched on"), and without a caller the corpus silently rots back.
+//
+// This validator is that caller. It is a RATCHET, not a cleanup order: the
+// corpus stands at 0 broken hurdles today, so the check is green today and goes
+// red exactly when someone lands a NEW question that breaks a hard limit.
+//
+// ## What it gates on — and, deliberately, what it does not
+//
+// It gates on the two HARD LIMITS only (`HURDLES` in scripts/lib/auq/schema.mjs):
+//
+//   H1  header at most 12 Unicode CODE POINTS (the tool truncates past that —
+//       the operator never sees the rest)
+//   H2  2-4 options PER QUESTION (never per block), and a `(Recommended)`
+//       marker only on index 0
+//
+// It does NOT gate on the eight weighted criteria K1-K8 or on the resulting
+// score. Their measured false-positive rates run 14%-25% (module head of
+// scripts/lib/auq/clarity.mjs); a gate built on them would object to roughly
+// every fourth CORRECT question, and a validator that cries wolf gets switched
+// off — taking every true finding with it. H1 and H2 are the only two with a
+// measured false-positive rate of 0%. That asymmetry is the whole design:
+// a narrow gate that survives beats a broad gate that gets disabled.
+//
+// Score, grades and the K1-K8 findings remain available on demand via
+// `node scripts/auq-audit.mjs .` — reported, never enforced.
+//
+// ## It measures nothing itself
+//
+// Every judgement comes from the existing modules: `parseRepo()` finds the
+// templates (across ALL six populations, including `.cursor/rules/*.mdc`, which
+// is the only surface a Cursor operator ever sees), `scoreBlocks()` scores them,
+// and `HURDLES` names the limits. A second implementation of the criteria here
+// would be the start of divergence — the two copies would disagree the first
+// time a threshold moves, and the disagreement would be silent.
+//
+// Direct import rather than spawning `scripts/auq-audit.mjs --json`: the audit
+// CLI emits a >1 MB envelope that would have to be re-parsed, and its exit code
+// speaks a different dialect (3 = hard limit broken under `--strict`) than the
+// 0/1/2 this validator family uses. Importing skips both translations.
+//
+// ## Language
+//
+// Comments and structural output are English, matching the 35 sibling
+// validators in this directory. Quoted finding text is German because it comes
+// verbatim from clarity.mjs, where it is written for the operator on purpose —
+// re-wording it here would be exactly the second copy this file avoids.
+//
+// Usage: check-auq-clarity.mjs <plugin-root> [--file <repo-relative-path>]...
+//
+// `--file` restricts the corpus to the named files and bypasses `git ls-files`.
+// Its purpose is testability: the default enumeration is git-backed, so inside a
+// throwaway fixture directory (no git) the corpus would otherwise be empty. The
+// orchestrator never passes it.
+//
+// Outputs lines of the form "  PASS: ..." / "  FAIL: ..." / "  WARN: ..." plus a
+// "Results: N passed, M failed" line so the validate-plugin orchestrator's
+// PASS:/FAIL: tally counts it.
+//
+// Exit codes:
+//   0 — clean (no question breaks a hard limit)
+//   1 — at least one question breaks a hard limit, or the corpus is empty
+//   2 — tool error (missing arg / unreadable root)
+
+import { parseRepo } from '../auq/parse.mjs';
+import { scoreBlocks } from '../auq/clarity.mjs';
+import { HURDLES, HURDLE_IDS, POPULATIONS } from '../auq/schema.mjs';
+
+// ---------------------------------------------------------------------------
+// Argument parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * Splits argv into the plugin root and the optional `--file` restriction list.
+ *
+ * Deliberately NOT exported: this module's body runs the check on import, so an
+ * importing test would trigger a `process.exit()` instead of getting a function.
+ * Argument handling is covered through the subprocess, like the sibling checks.
+ *
+ * @param {string[]} argv - arguments after `node <script>`
+ * @returns {{root: string|null, files: string[], error: string|null}}
+ */
+function parseCheckArgs(argv) {
+  let root = null;
+  const files = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--file') {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith('--')) {
+        return { root, files, error: '--file needs a repo-relative path' };
+      }
+      files.push(value);
+      i++;
+      continue;
+    }
+    if (arg.startsWith('--')) return { root, files, error: `unknown flag: ${arg}` };
+    if (root === null) root = arg;
+  }
+  return { root, files, error: null };
+}
+
+const parsed = parseCheckArgs(process.argv.slice(2));
+
+if (parsed.error) {
+  console.error(`Usage: check-auq-clarity.mjs <plugin-root> [--file <path>]... (${parsed.error})`);
+  process.exit(2);
+}
+if (!parsed.root) {
+  console.error('Usage: check-auq-clarity.mjs <plugin-root> [--file <path>]...');
+  process.exit(2);
+}
+
+let passed = 0;
+let failed = 0;
+let warned = 0;
+
+function pass(msg) {
+  console.log(`  PASS: ${msg}`);
+  passed++;
+}
+
+function fail(msg) {
+  console.log(`  FAIL: ${msg}`);
+  failed++;
+}
+
+function warn(msg) {
+  console.log(`  WARN: ${msg}`);
+  warned++;
+}
+
+// ============================================================================
+// Check: AUQ hard limits (H1/H2) across the whole question corpus
+// ============================================================================
+console.log('--- Check: AUQ question corpus hard limits (H1 header, H2 options) ---');
+
+let repo;
+try {
+  repo = parseRepo({
+    repoRoot: parsed.root,
+    ...(parsed.files.length > 0 ? { files: parsed.files } : {}),
+  });
+} catch (err) {
+  console.error(`  tool-error: cannot parse the AUQ corpus: ${err?.message ?? String(err)}`);
+  process.exit(2);
+}
+
+// Read warnings are surfaced, never swallowed: each one is a template that
+// silently left the corpus, and a shrinking corpus is how this guard would fade
+// to a decoy without anyone noticing. WARN (not FAIL) matches the sibling
+// convention and never touches the exit code.
+for (const w of repo.warnings) warn(`AUQ corpus: ${w}`);
+
+const scores = scoreBlocks(repo.blocks);
+
+// --- Anti-decoy guard -------------------------------------------------------
+// A validator that is wired up but measures nothing is indistinguishable from a
+// green one, and that is precisely the failure this file was written to end. An
+// empty corpus therefore FAILS rather than passing vacuously: it means the
+// enumeration broke (git unavailable, corpus prefixes moved, `--file` pointed
+// outside the corpus), never that the repo is clean.
+if (scores.length === 0) {
+  fail(
+    'the AUQ corpus is empty — 0 questions found, so this check measured nothing. ' +
+      'Either the file enumeration broke (git ls-files unavailable, or scripts/lib/auq/parse.mjs ' +
+      'corpus prefixes no longer match the tree) or a --file argument pointed outside the corpus. ' +
+      'A silently empty corpus is a decoy gate, not a clean repo.',
+  );
+  console.log('');
+  console.log(`Results: ${passed} passed, ${failed} failed, ${warned} warned`);
+  process.exit(1);
+}
+
+// --- The two hard limits ----------------------------------------------------
+// Note what is NOT consulted here: `score.points`, `score.grade`, and
+// `score.findings[].severity === 'warn'`. Only `hurdlesBroken` drives the exit
+// code. This is also what makes the `optionCountUnknown` case correct by
+// construction: three-plus templates in the corpus end in an ellipsis rather
+// than a full option list, so their true option count is UNKNOWN. clarity.mjs
+// records that as a warn-level note and deliberately breaks NO hurdle for it
+// ("not checkable" is not "violated"). Keying on `hurdlesBroken` inherits that
+// judgement; keying on findings would invent violations that do not exist.
+const brokenByHurdle = new Map(HURDLE_IDS.map((id) => [id, []]));
+
+for (const score of scores) {
+  for (const id of score.hurdlesBroken) {
+    if (!brokenByHurdle.has(id)) brokenByHurdle.set(id, []);
+    brokenByHurdle.get(id).push(score);
+  }
+}
+
+/**
+ * The operator-facing reason a question broke a hurdle, taken verbatim from the
+ * finding clarity.mjs already produced.
+ *
+ * Filtered on the finding's OWN `hurdle` tag, not on the hurdle's criterion.
+ * The criterion filter this used to carry over-reached: K6 produces four
+ * finding classes (description length, label length, payload size, option
+ * count) and only the last one breaks H2, so a FAIL line here could name a
+ * description that is 186 characters long — a finding that breaks nothing —
+ * while the real option-count break sat behind it. The same over-reach was
+ * measured in `hooks/pre-auq-clarity.mjs` and is fixed there too; both
+ * consumers had reconstructed a mapping that `clarity.mjs` already knew.
+ *
+ * The criterion path stays as a fallback so an older scorer that emits
+ * untagged findings degrades to the previous behaviour instead of producing a
+ * silent empty reason. Found by this session's architecture review (W4-Q7).
+ *
+ * @param {import('../auq/schema.mjs').AuqScore} score
+ * @param {string} hurdleId
+ * @returns {string}
+ */
+function reasonFor(score, hurdleId) {
+  const criterion = HURDLES[hurdleId]?.criterion;
+  const tagged = score.findings.filter((f) => f.hurdle === hurdleId && f.severity === 'fail');
+  const pool = tagged.length > 0
+    ? tagged
+    : score.findings.filter((f) => f.criterion === criterion && f.severity === 'fail');
+  const messages = pool.map((f) => f.message);
+  return messages.length > 0 ? messages.join(' ') : '(no message recorded)';
+}
+
+for (const id of HURDLE_IDS) {
+  const offenders = brokenByHurdle.get(id) ?? [];
+  const hurdle = HURDLES[id];
+
+  if (offenders.length === 0) {
+    // Deliberately reports the DENOMINATOR too. A "0 violations" line is equally
+    // true of a corpus of zero questions, which is the state the anti-decoy
+    // guard above exists to catch — printing what was actually measured keeps
+    // the two distinguishable at a glance.
+    pass(
+      `${id} (${hurdle.title}) — 0 of ${scores.length} questions break this limit ` +
+        `[${hurdle.rule}]`,
+    );
+    continue;
+  }
+
+  for (const score of offenders) {
+    fail(
+      `${score.file}:${score.line} (question ${score.questionIndex + 1}) breaks hard limit ${id} ` +
+        `— ${hurdle.title}. ${reasonFor(score, id)} See .claude/rules/ask-via-tool.md (AUQ-003) ` +
+        'and run `node scripts/auq-audit.mjs .` for the full report.',
+    );
+  }
+}
+
+// --- Corpus census (informational) ------------------------------------------
+// Deliberately NOT routed through pass(): this is bookkeeping, not an audited
+// invariant, and must not inflate the passed count the orchestrator tallies.
+//
+// It is printed because the most plausible way this guard degrades is by
+// quietly narrowing to `.md`. The six populations include `.cursor/rules/*.mdc`
+// — the only surface a Cursor operator ever sees — and runtime questions inside
+// `.mjs`. A checker that read markdown only would hand those a clean bill of
+// health while never opening them; a per-population line makes that visible
+// instead of invisible.
+const census = POPULATIONS.map((p) => `${p}:${repo.corpus[p] ?? 0}`).join(' ');
+console.log(`  (corpus: ${scores.length} questions in ${repo.blocks.length} blocks — ${census})`);
+
+console.log('');
+console.log(`Results: ${passed} passed, ${failed} failed, ${warned} warned`);
+
+process.exit(failed > 0 ? 1 : 0);