shapeup-sdlc 3.4.0 → 3.6.0

package/kernel/lib/contract.mjs

@@ -94,6 +94,9 @@ export const PROJECT_PROFILE = { tables: {} };
  */
 export const UNREADABLE = "$unreadable_tables";
 
+/** `found_under` marker: a table field that was also declared in the frontmatter, where nothing reads it. */
+export const FRONTMATTER_COPY = "the frontmatter, where it is silently discarded";
+
 /**
  * Marks a contract that parsed only via a MIGRATION reader — readable, but not in the canonical
  * shape. Without it the fallback is permanent by silence: the file works, nothing says it is the
@@ -440,7 +443,34 @@ export function parseContract(md, spec = SCOPE_CONTRACT) {
   const unreadable = [...(meta[UNREADABLE] || [])];
   delete out[UNREADABLE];
   for (const [field, heading] of Object.entries(spec.tables || {})) {
-    if (tables[heading]) { out[field] = tables[heading]; continue; }
+    // A TABLE FIELD DECLARED IN THE FRONTMATTER TOO IS A DISCARDED DECLARATION, and it has to be
+    // loud. `renderContract` writes table fields ONLY as a table — it filters them out of the
+    // frontmatter it emits — so the table is the source by construction and the line below is right
+    // to prefer it. What the old code did not say is that the frontmatter copy was then dropped
+    // without a word, and `splitFrontmatter` cannot even represent this shape: a block sequence of
+    // MAPPINGS flattens to a list of strings, so the copy is usually garbage as well as ignored.
+    //
+    // Measured: a planner wrote `affordance_manifest` in both places, the frontmatter copy carrying
+    // the correct `required_states: [idle]` and the table cell a bare `idle`. The parser took the
+    // table, the value was a string where the schema wants an array, `compile` refused the order,
+    // and the scope was NEVER DISPATCHED — spec-lint passing the contract, the build leg reporting
+    // `state: "done", error: null`, four of nine scopes gone every round, until EVAL refused to
+    // grade a round whose scopes had never run. The contract even captioned its own table "rendered
+    // here for reviewers": the author's model was the exact inverse of the parser's. That
+    // disagreement is the defect; which side wins is not.
+    //
+    // ONLY WHEN A TABLE ACTUALLY WINS. With no rows under the heading the frontmatter value is what
+    // the field becomes, and `affordance_manifest: []` meaning "none" is legal and current — five of
+    // those nine contracts do exactly that and are correct. An earlier cut of this rule fired on all
+    // nine and turned a working run red, which is the opposite of the fix.
+    if (tables[heading]) {
+      if (field in meta) {
+        unreadable.push({ field, expected_heading: heading, found_under: FRONTMATTER_COPY,
+          rows: Array.isArray(meta[field]) ? meta[field].length : 1 });
+      }
+      out[field] = tables[heading];
+      continue;
+    }
     // The field is absent — but is it absent because nobody declared it, or because the
     // author declared it somewhere this parser does not look? Those are opposite facts and the
     // old code returned the same thing for both. A table carrying this field's signature columns,
@@ -534,6 +564,14 @@ export function unreadableReason(contract) {
         return `\`${x.field}\` was written as a \`## ${x.field}\` markdown section, which this dialect reads as prose — ` +
           `it must be a FRONTMATTER key (a \`- \` block list or an inline [a, b] list), so as written the field parsed as ABSENT`;
       }
+      // A table field ALSO declared in the frontmatter. Its own case because the fix is "delete the
+      // frontmatter copy", not "move the table" — and because the copy is not merely redundant: the
+      // parser takes the table, so whatever the copy said was discarded without a word.
+      if (x.found_under === FRONTMATTER_COPY) {
+        return `\`${x.field}\` is a TABLE field and was also declared in the frontmatter, ` +
+          `where it is read by nothing and silently discarded — the \`## ${x.expected_heading}\` table is the only source. ` +
+          `Delete the frontmatter copy, and check the table says what it said: a list cell is written \`[a, b]\``;
+      }
       return `\`${x.field}\` must be a table under a \`## ${x.expected_heading}\` heading; found ${x.rows} matching row(s) under "${x.found_under}" instead, so the field parsed as ABSENT`;
     })
     .join("; ");
@@ -652,6 +690,35 @@ export function ucId(ref) {
   return String(ref ?? "").trim().replace(/^\[\[|\]\]$/g, "").replace(/^usecases\//, "").replace(/\.md$/, "").trim();
 }
 
+/**
+ * Normalise one requirement reference to the registry's key space (`REQ-<n>`).
+ *
+ * TWO KEY SPACES FOR ONE THING, and the measurement is what decided this. A pitch numbers its
+ * requirements `R1…R21`; the registry, every AC's `covers:` clause and every `traces_to[]` key off
+ * `REQ-<n>`. Measured across two runs of one pitch, the scope contracts cited `R<n>` — 20 of 21
+ * requirements had a scope claiming them, and every one of those links resolved to nothing,
+ * reported 23 times a run as a shape warning nobody could act on. So the edge WAS produced; it was
+ * severed by spelling alone.
+ *
+ * Normalising here rather than teaching the planner to emit `REQ-<n>` is deliberate: `covers[]` is
+ * an OPTIONAL contract field, so a fix that depends on a planner choosing to comply converts
+ * whatever links the next run happens to write, while this converts the links on contracts already
+ * committed, with no worker behaviour change. The craft still asks for `REQ-<n>` going forward.
+ *
+ * THIS IS A MAPPING PERFORMED BEFORE THE PATTERN, NOT A LOOSENING OF IT. `^REQ-[0-9]+$` is
+ * unchanged everywhere it appears; a reference this function does not recognise is returned
+ * verbatim, so it still fails that pattern and is still reported.
+ *
+ * @param {string} ref - A requirement reference (`REQ-12`, `R12`, `R-12`, `[[REQ-12]]`, any case).
+ * @returns {string} The canonical `REQ-<n>` id, or the trimmed input unchanged when it is not a
+ *   numbered requirement reference at all.
+ */
+export function reqId(ref) {
+  const s = String(ref ?? "").trim().replace(/^\[\[|\]\]$/g, "").trim();
+  const m = s.match(/^(?:REQ|R)-?([0-9]+)$/i);
+  return m ? `REQ-${m[1]}` : s;
+}
+
 /**
  * The tasks on a LOCAL board that belong to a scope, joined through the COMMITTED spec.
  *

package/kernel/lib/paths.mjs

@@ -140,6 +140,16 @@ export const receipt = (cwd, slug) => join(localRoot(cwd, slug), RECEIPT_FILE);
 export const intake = (cwd, slug) => join(localRoot(cwd, slug), "intake.md");
 /** The breadboard the pitch was shaped with, verbatim, next to its digest in the receipt. */
 export const breadboard = (cwd, slug) => join(localRoot(cwd, slug), "breadboard.md");
+/**
+ * The launch record's filename, as a constant rather than a literal at each call site — the
+ * writer (`harness init run-args`) and every reader (`probe concurrency`'s `dialFrom()`) resolve
+ * the same path through this constant, the same way {@link runIdFromRoot} resolves `RECEIPT_FILE`
+ * against a bare run root rather than through {@link receipt}'s `(cwd, slug)` form: a caller that
+ * already holds the run root (an archived trace, `--run-root <dir>`) has no slug to reconstruct.
+ */
+export const RUN_ARGS_FILE = "run-args.json";
+/** The launch record — the RunArgs object a run was launched with (GATE L0.9b), kernel-written. */
+export const runArgsPath = (cwd, slug) => join(localRoot(cwd, slug), RUN_ARGS_FILE);
 /** The run ledger — rounds, decisions, status frontmatter. */
 export const harnessRun = (cwd, slug) => join(localRoot(cwd, slug), "harness-run.md");
 /** File-derived mid-run digest, frozen by `reduce snapshot --write` as an audit anchor. */

package/kernel/probe/concurrency.mjs

@@ -30,13 +30,16 @@
 //
 // Usage: node kernel/harness.mjs probe concurrency --slug <slug> [--cwd <dir>] [--run-root <dir>]
 //                                                  [--round N] [--gap-s N] [--format json|table]
+//                                                  [--require-run-args]
 // Exit:  0 = a report was produced with at least one usable leg · 1 = ran, and no leg in scope had
 //        a usable interval (the report still prints, and says why) · 2 = malformed argv.
+//        With --require-run-args the report is skipped: 0 = run-args.json exists at this run root ·
+//        6 = it does not (mirrors `probe resume --require`'s "artifact absent" convention).
 
 import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { runArgs } from "../lib/argv.mjs";
-import { localRoot, runIdFromRoot, RECEIPT_FILE } from "../lib/paths.mjs";
+import { localRoot, runIdFromRoot, RECEIPT_FILE, RUN_ARGS_FILE } from "../lib/paths.mjs";
 
 /** The round-addressed order id forms `<scope>-r<N>-a<M>` and `<phase>-r<N>`. */
 const ROUND_SUFFIX = /^(.*?)-r(\d+)(?:-a(\d+))?$/;
@@ -301,16 +304,18 @@ export function summarise(index, legs) {
 /**
  * Which fan-out width the run was launched with — read, never assumed.
  *
- * The dial is written into `run-args.json` by the launcher. It is absent from every run recorded so
- * far, so the honest answer is the effective default WITH the fact that it is a default: reporting
- * `4` unqualified would assert an operator choice nobody made.
+ * The dial is written into `run-args.json` by `harness init run-args` (GATE L0.9b), the kernel
+ * writer tech-lead invokes right before the launch. A run opened before that writer existed, or one
+ * whose launcher never passed `--parallel-scopes`, still has no file or no key — so the honest
+ * answer stays the effective default WITH the fact that it is a default: reporting `4` unqualified
+ * would assert an operator choice nobody made.
  *
  * @param {string} runRoot - The run's LOCAL root.
  * @returns {{max_parallel_scopes:number, source:string}} The value and where it came from.
  */
 export function dialFrom(runRoot) {
   try {
-    const a = JSON.parse(readFileSync(join(runRoot, "run-args.json"), "utf8"));
+    const a = JSON.parse(readFileSync(join(runRoot, RUN_ARGS_FILE), "utf8"));
     const n = Number(a?.maxParallelScopes);
     if (Number.isFinite(n) && n >= 1) return { max_parallel_scopes: n, source: "run-args" };
     return { max_parallel_scopes: DEFAULT_MAX_PARALLEL_SCOPES, source: "default (run-args.json declares none)" };
@@ -474,7 +479,7 @@ export function table(r) {
 /** The typed argv contract (see `./lib/argv.mjs`). */
 export const ARGV_SPEC = {
   usage: "harness.mjs probe concurrency (--slug <slug> | --run-root <dir>) [--cwd <dir>] [--round N] " +
-         "[--gap-s N] [--format json|table]",
+         "[--gap-s N] [--format json|table] [--require-run-args]",
   _: { arity: 0, max: 0, name: "(no positional operands)" },
   slug: { type: "str" },
   // The archived-trace and post-export cases, and the same escape `verify t0 --out` has: a caller
@@ -484,6 +489,10 @@ export const ARGV_SPEC = {
   round: { type: "int", min: 1 },
   "gap-s": { type: "int", min: 1, default: DEFAULT_GAP_S },
   format: { type: "enum", values: ["json", "table"], default: "json" },
+  // The positive enforcer for the launch record (see the banner below). Skips the concurrency
+  // report entirely — this is a presence check, not a measurement, and the two must not be
+  // confused by sharing an exit code.
+  "require-run-args": { type: "flag" },
 };
 
 /**
@@ -492,6 +501,14 @@ export const ARGV_SPEC = {
  * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
  * @returns {void} Exits 0 when at least one leg had a usable interval, 1 when none did — and the
  *   report prints either way, because "nothing was measurable" is the answer, not an error.
+ *
+ *   `--require-run-args` is a different question with its own exit convention, mirroring
+ *   `probe resume --require`'s 0 (satisfied) / 6 (artifact absent): it never reaches the report at
+ *   all. The launch record had exactly one reader (`dialFrom()`, below) and zero enforcers — a
+ *   run missing it proceeded green with a silently substituted default, "indistinguishable from an
+ *   operator choice" (`gates.md` L0.9b). This flag is what `shapeup-run.js` calls at Preflight, before
+ *   ORIENT, so that state stops being invisible: this module already owns run-root resolution and the
+ *   file's path, so the check is a few lines here rather than a new kernel entry point.
  */
 export function cli(rawArgv) {
   const args = runArgs(ARGV_SPEC, rawArgv);
@@ -504,6 +521,14 @@ export function cli(rawArgv) {
     ? resolve(args.runRoot)
     : localRoot(resolve(args.cwd || process.cwd()), args.slug);
 
+  if (args.requireRunArgs) {
+    const path = join(runRoot, RUN_ARGS_FILE);
+    const present = existsSync(path);
+    console.log(JSON.stringify({ ok: present, run_root: runRoot, run_args_path: path,
+      reason: present ? null : "no run-args.json at this run root — GATE L0.9b's launch record was never written before this launch" }));
+    process.exit(present ? 0 : 6);
+  }
+
   const r = report(runRoot, { round: args.round ?? null, gapS: args.gapS });
   console.log(args.format === "table" ? table(r) : JSON.stringify(r));
   process.exit(r.launches.length ? 0 : 1);

package/kernel/probe/digest.mjs

@@ -6,7 +6,9 @@
 // Script-first by design: regex over known log formats is free (no model tokens); an
 // unrecognized line becomes a "raw" triple (file/line unknown) rather than being silently
 // dropped, so a Sonnet fallback (or a human) still has something to look at — this module never
-// invents a file:line it didn't find in the text.
+// invents a file:line it didn't find in the text. `file` and `line` are independent: a
+// diagnostic that names a file but no line number (a resource-compiler error, for example)
+// still yields its file — `line` stays null rather than being guessed at.
 //
 // Zero dependencies, zero network — same discipline as oracles/*.
 
@@ -19,6 +21,18 @@ const PATTERNS = [
   { re: /^(?:✗|not ok\b.*?)[^()]*\((.+?):(\d+)\)\s*$/, kind: "test-failure" },
   // ESLint/tsc style: "path/to/file.ts:12:34 - error TS2345: message"
   { re: /^(.+?):(\d+):\d+\s*[-–]\s*(?:error|warning)\b.*$/, kind: "compiler-diagnostic" },
+  // File-level diagnostic with NO line number: "resource.xml: error: message" or
+  // "resource.xml - fatal error: message" (resource compilers and linkers report this way —
+  // the failure is the whole file, so there is no line to cite). The file must look like a
+  // path (ends in a dotted extension, no embedded whitespace/colon) so this stays anchored to
+  // real diagnostics rather than matching arbitrary prose that happens to contain "error:".
+  { re: /^([^\s:]+?\.[A-Za-z0-9]{1,10})\s*[:\-–—]\s*(?:fatal\s+error|error|warning)\b.*$/i, kind: "compiler-diagnostic" },
+  // Bundler style: "ERROR in ./src/components/Foo.tsx" (webpack et al.) — file, no line. The
+  // captured token must look like a path — leads with "./"/"../", or ends in a dotted extension
+  // of 1-10 alnum chars (same anchor the sibling pattern above uses) — so prose after "ERROR in"
+  // ("ERROR in the build pipeline", "ERROR in test suite failed to run") is left unmatched
+  // instead of handing back a fabricated file.
+  { re: /^(?:ERROR|WARNING)\s+in\s+(\.{1,2}\/[^\s:]*|[^\s:]+\.[A-Za-z0-9]{1,10})\b/i, kind: "compiler-diagnostic" },
   // Generic "Error: message" line followed later by a stack — capture the message alone.
   { re: /^\s*(?:Error|TypeError|ReferenceError|AssertionError)\s*:\s*(.+)$/, kind: "error-message" },
 ];

package/kernel/probe/owner.mjs

@@ -46,8 +46,11 @@ import { matchesAny } from "../../hooks/sandbox-guard.mjs";
  */
 export function ownership(path, scopes, cwd = null) {
   const rel = String(path).replace(/^\.\//, "");
-  const writers = (scopes || []).filter((s) => matchesAny(rel, s.allowed)).map((s) => s.scope_id).sort();
   const shared = (scopes || []).filter((s) => matchesAny(rel, s.shared || [])).map((s) => s.scope_id).sort();
+  // `writers` is admits-the-path, the same union the sandbox fence composes (allowed ++ shared) —
+  // a path declared only in a contract's `shared` list is still a scope this path may write, and
+  // must read as owned rather than UNOWNED. `shared_with` (below) stays the narrower subset.
+  const writers = (scopes || []).filter((s) => matchesAny(rel, s.allowed) || matchesAny(rel, s.shared || [])).map((s) => s.scope_id).sort();
   return { path: rel, owner: electOwner(rel, scopes), writers, shared_with: shared, exists: cwd ? existsSync(join(cwd, rel)) : null };
 }
 

package/kernel/probe/requirements.mjs

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+// probe requirements — the way back: a pitch clause, the criterion that graded it, the verdict.
+//
+// WHY THIS IS A QUERY AND NOT A SENTENCE, which is the same reason `probe owner` is one. The
+// requirement matrix is read at GATE L4 and cited by GATE H's census, and both are places where a
+// narrated figure is indistinguishable from a measured one. Measured on the first verdict any run
+// of the spine produced: 85 of 97 criterion rows carried a `traces_to` anchor in the WorkResult and
+// 0 of 97 survived into the projection ingest wrote — so a matrix assembled from memory would have
+// been assembled from an edge that no longer existed on disk. Every figure below is derived from
+// files: the committed registry, the board's `covers:` clauses, the verdict ledger, and the EVAL
+// result's own T0 citations. Nothing is passed in and nothing is written.
+//
+// THE JOIN, and which half is authoritative. A requirement has EVIDENCE when an acceptance
+// criterion covers it (`(covers: REQ-…)` on the AC line — the planning-time edge, reviewed at L1b)
+// AND a criterion that names it passed. `traces_to[]` is the navigation path from the judge's
+// criterion back to the requirement, exactly what the schema already calls it: an anchor, never a
+// grading input. A criterion whose `traces_to` names a REQ that no AC covers is printed as an
+// INCONSISTENCY row and counted as nothing — folding it in would derive one L4 line from two
+// unreconciled sources, which is the failure `probe owner` exists to prevent.
+//
+// IT PROJECTS ONE RUN. `order_id`, round and attempt all repeat across runs of one feature; the
+// run key is the only thing that separates them, so a projection that ignored it would silently mix
+// two runs of one slug. Rows written before the key reached the ledger carry no `run_id`; they are
+// reported as unknown rather than folded into the run being projected.
+//
+// AN EMPTY JOIN READS AS CLEARLY AS A FULL ONE. A tree with no registry, a board with no `covers:`
+// and a run with no verdict are all legitimate states, and each answers "no evidence" rather than
+// failing — that answer is the point of the query, not an error in it.
+//
+// Usage:
+//   node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" probe requirements --slug <slug> [--run-id <id>] [--format json|table] [--cwd <dir>]
+//
+// Exit code: 0 = answered (an empty projection is an answer), 2 = bad argv.
+
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { runArgs, isMain } from "../lib/argv.mjs";
+import { requirements as requirementsFile, evaluationDir, resultsDir, readRunId } from "../lib/paths.mjs";
+import { parseRequirements, coveredReqIds } from "../verify/trace.mjs";
+import { readBoard } from "../compile.mjs";
+import { reqId } from "../lib/contract.mjs";
+
+/**
+ * Read a file, tolerating absence — every input to this projection is optional by design.
+ * @param {string} p - Absolute path.
+ * @returns {(string|null)} The contents, or null when the file is missing or unreadable.
+ */
+function readIf(p) {
+  try { return existsSync(p) ? readFileSync(p, "utf8") : null; } catch { return null; }
+}
+
+/**
+ * The acceptance criteria on the LOCAL board that cover each requirement.
+ *
+ * The planning-time half of the join, and the authoritative one: a `covers:` clause is written when
+ * the plan is still cheap to change and is reviewed at L1b, whereas `traces_to` is written by the
+ * judge after the fact.
+ *
+ * NOT A SECOND COVERS-CLOSURE. Whether a requirement is covered is still decided by
+ * `coveredReqIds` in the oracle — there is one implementation of that question and this is not it.
+ * This walk exists only to keep the AC the closure discards, so the matrix can print WHICH
+ * criterion covers the clause instead of only that one does.
+ *
+ * @param {Array<object>} board - Task entries from `readBoard` (the only parser that carries
+ *   `acceptance_criteria`; the scheduling view does not).
+ * @returns {Map<string, Array<{task_id:string, ac:string}>>} REQ-id → the ACs naming it, in board
+ *   order. A requirement no AC covers is simply absent.
+ */
+export function coveringAcs(board) {
+  const out = new Map();
+  for (const task of board || []) {
+    for (const ac of task.acceptance_criteria || []) {
+      if (typeof ac !== "object" || !Array.isArray(ac.covers)) continue;
+      for (const raw of ac.covers) {
+        const id = reqId(raw).toUpperCase();
+        if (!out.has(id)) out.set(id, []);
+        out.get(id).push({ task_id: task.id, ac: ac.text });
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Every criterion row ingest projected, tagged with the EVAL target its ledger belongs to.
+ *
+ * The target is read off the FILE NAME rather than the row: `.verdicts-<target>.jsonl` is written
+ * per order, so the file is what says which dispatch produced the rows, and the same file is what
+ * locates the WorkResult carrying that dispatch's T0 citations.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @returns {Array<object>} One entry per ledger line, each the stored row plus `target`. Malformed
+ *   lines are skipped; a missing evaluation directory yields [].
+ */
+export function readVerdictRows(cwd, slug) {
+  const dir = evaluationDir(cwd, slug);
+  let files = [];
+  try { files = readdirSync(dir).filter((f) => /^\.verdicts-.+\.jsonl$/.test(f)).sort(); } catch { return []; }
+  const rows = [];
+  for (const f of files) {
+    const target = f.replace(/^\.verdicts-/, "").replace(/\.jsonl$/, "");
+    for (const line of (readIf(join(dir, f)) || "").split(/\r?\n/)) {
+      if (!line.trim()) continue;
+      try { rows.push({ ...JSON.parse(line), target }); } catch { /* a truncated line is not a verdict */ }
+    }
+  }
+  return rows;
+}
+
+/**
+ * The T0 artifacts an EVAL dispatch re-hashed, read from the WorkResult it wrote.
+ *
+ * The verdict ledger records criteria, not citations, so the machine fact a generator cannot
+ * fabricate lives one file over — in `results/<target>.json`. Read here rather than recomputed: the
+ * evaluator's own citation is what the round was accepted on.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {string} target - The EVAL order suffix (`evaluate-r1`), from the ledger's file name.
+ * @returns {Array<{scope_id:(string|null), path:(string|null), sha256:(string|null)}>} The cited
+ *   artifacts; [] when the result is absent, unreadable or cites none.
+ */
+export function t0Citations(cwd, slug, target) {
+  const body = readIf(join(resultsDir(cwd, slug), `${target}.json`));
+  if (!body) return [];
+  try {
+    const cites = JSON.parse(body)?.verdict?.t0_citations;
+    if (!Array.isArray(cites)) return [];
+    return cites.map((c) => ({ scope_id: c?.scope_id ?? null, path: c?.path ?? null, sha256: c?.sha256 ?? null }));
+  } catch { return []; }
+}
+
+/**
+ * Project one run's requirement matrix from the artifacts on disk.
+ *
+ * @param {{cwd:string, slug:string, runId?:(string|null)}} opts - Project root, feature slug, and
+ *   the run to project; omitted, it is resolved from the run's own receipt.
+ * @returns {{slug:string, run_id:(string|null), registry:boolean, totals:object,
+ *   rows:Array<object>, inconsistencies:Array<object>, ledger:object}} `rows` is one entry per
+ *   registered clause — its source, status, covering ACs, the criteria that named it and their
+ *   verdicts, and each criterion's T0 citations — with `evidence` one of `PASS`, `no evidence` or
+ *   `cut`. `inconsistencies` holds criteria tracing to a REQ no AC covers. `ledger` says how many
+ *   rows were read, projected, skipped as another run's, and left unkeyed. No registry ⇒ `rows` is
+ *   empty and `registry` is false: an empty projection, not an error.
+ */
+export function projectRequirements({ cwd, slug, runId = undefined }) {
+  const regText = readIf(requirementsFile(cwd, slug));
+  const clauses = regText === null ? [] : parseRequirements(regText);
+  const board = readBoard(cwd, slug);
+  // `covered` decides; `acs` only says which criterion did the covering.
+  const covered = coveredReqIds(board);
+  const acs = coveringAcs(board);
+  const run = runId === undefined ? readRunId(cwd, slug) : runId;
+
+  const all = readVerdictRows(cwd, slug);
+  const ledger = { rows_read: all.length, rows_projected: 0, rows_other_run: 0, rows_unknown_run: 0 };
+  const mine = [];
+  for (const r of all) {
+    if (r.run_id === undefined || r.run_id === null || r.run_id === "") { ledger.rows_unknown_run++; continue; }
+    if (run !== null && r.run_id === run) { ledger.rows_projected++; mine.push(r); continue; }
+    ledger.rows_other_run++;
+  }
+
+  // The criteria that name each requirement, and the T0 artifacts the round that graded them cited.
+  const t0Cache = new Map();
+  /**
+   * The cited T0 artifacts for one EVAL target, read once per target.
+   * @param {string} target - The EVAL order suffix.
+   * @returns {Array<object>} The citation rows.
+   */
+  const t0For = (target) => {
+    if (!t0Cache.has(target)) t0Cache.set(target, t0Citations(cwd, slug, target));
+    return t0Cache.get(target);
+  };
+
+  const byReq = new Map();
+  const inconsistencies = [];
+  for (const r of mine) {
+    const anchors = Array.isArray(r.traces_to) ? r.traces_to : [];
+    for (const raw of anchors) {
+      const id = reqId(raw).toUpperCase();
+      const entry = {
+        criterion: r.criterion ?? "", dimension: r.dimension ?? "", verdict: r.verdict ?? "",
+        confidence: r.confidence ?? null, evidence: r.evidence ?? "", target: r.target,
+        run: r.run ?? null, run_id: r.run_id ?? null, t0: t0For(r.target),
+      };
+      // THE AUTHORITATIVE HALF DECIDES. An anchor pointing at a requirement no acceptance criterion
+      // covers is a claim the plan never made; it is printed so somebody can reconcile it, and
+      // counted as nothing.
+      if (!covered.has(id)) { inconsistencies.push({ requirement: id, ...entry, why: "no acceptance criterion covers this requirement — the anchor resolves to nothing the plan claimed" }); continue; }
+      if (!byReq.has(id)) byReq.set(id, []);
+      byReq.get(id).push(entry);
+    }
+  }
+
+  const rows = clauses.map((c) => {
+    const id = c.id.toUpperCase();
+    const covering = acs.get(id) || [];
+    const criteria = byReq.get(id) || [];
+    const cut = c.status !== "covered";
+    const passed = criteria.some((x) => String(x.verdict).toUpperCase() === "PASS");
+    return {
+      id: c.id,
+      source: c.source || "",
+      clause: c.clause || "",
+      status: c.status,
+      covering_acs: covering,
+      criteria,
+      t0: [...new Set(criteria.flatMap((x) => x.t0.map((t) => t.sha256).filter(Boolean)))],
+      evidence: cut ? "cut" : passed ? "PASS" : "no evidence",
+    };
+  });
+
+  const totals = {
+    total: rows.length,
+    pass: rows.filter((r) => r.evidence === "PASS").length,
+    cut: rows.filter((r) => r.evidence === "cut").length,
+    no_evidence: rows.filter((r) => r.evidence === "no evidence").length,
+    inconsistencies: inconsistencies.length,
+  };
+  return { slug, run_id: run, registry: regText !== null, totals, rows, inconsistencies, ledger };
+}
+
+/**
+ * The one-line summary GATE L4 prints and GATE H's census cites.
+ *
+ * @param {object} r - A report from {@link projectRequirements}.
+ * @returns {string} `15/17 PASS · 1 CUT (PO) · 1 no evidence (REQ-12 ← R12)`, or the empty-run
+ *   phrasing when there is no registry to project.
+ */
+export function summaryLine(r) {
+  if (!r.registry) return "n/a (no registry)";
+  if (!r.totals.total) return "0 requirements registered";
+  const gaps = r.rows.filter((x) => x.evidence === "no evidence");
+  const named = gaps.slice(0, 3).map((x) => (x.source ? `${x.id} ← ${x.source}` : x.id)).join(", ");
+  const parts = [`${r.totals.pass}/${r.totals.total} PASS`];
+  if (r.totals.cut) parts.push(`${r.totals.cut} CUT (PO)`);
+  if (r.totals.no_evidence) parts.push(`${r.totals.no_evidence} no evidence (${named}${gaps.length > 3 ? ", …" : ""})`);
+  if (r.totals.inconsistencies) parts.push(`${r.totals.inconsistencies} inconsistency ${r.totals.inconsistencies === 1 ? "row" : "rows"}`);
+  return parts.join(" · ");
+}
+
+/**
+ * Render the matrix as a fixed-width table for a human reading a gate block.
+ * @param {object} r - A report from {@link projectRequirements}.
+ * @returns {string} The header, one row per requirement, the summary line and any inconsistencies.
+ */
+export function renderTable(r) {
+  const out = [];
+  const head = ["REQ", "source", "status", "covering AC", "criterion", "verdict", "T0"];
+  const rows = r.rows.map((x) => [
+    x.id, x.source || "—", x.evidence,
+    x.covering_acs.length ? `${x.covering_acs[0].task_id}: ${x.covering_acs[0].ac.slice(0, 40)}${x.covering_acs.length > 1 ? ` (+${x.covering_acs.length - 1})` : ""}` : "—",
+    x.criteria.length ? `${x.criteria[0].criterion.slice(0, 40)}${x.criteria.length > 1 ? ` (+${x.criteria.length - 1})` : ""}` : "—",
+    x.criteria.length ? x.criteria.map((c) => c.verdict).join(",") : "—",
+    x.t0.length ? x.t0.map((h) => String(h).slice(0, 12)).join(",") : "—",
+  ]);
+  if (rows.length) {
+    const w = head.map((h, i) => Math.max(h.length, ...rows.map((row) => String(row[i]).length)));
+    const line = (row) => row.map((c, i) => String(c).padEnd(w[i])).join("  ").trimEnd();
+    out.push(line(head), line(w.map((n) => "-".repeat(n))), ...rows.map(line), "");
+  }
+  out.push(`Requirements: ${summaryLine(r)}`);
+  out.push(`run_id: ${r.run_id ?? "unknown"} · ledger rows read ${r.ledger.rows_read}, projected ${r.ledger.rows_projected}, other run ${r.ledger.rows_other_run}, unkeyed (run_id: unknown) ${r.ledger.rows_unknown_run}`);
+  for (const i of r.inconsistencies) {
+    out.push(`  ⚠ ${i.requirement}: "${String(i.criterion).slice(0, 60)}" ${i.verdict} — ${i.why}`);
+  }
+  return out.join("\n");
+}
+
+export const ARGV_SPEC = {
+  usage: "harness.mjs probe requirements --slug <slug> [--run-id <id>] [--format json|table] [--cwd <dir>]",
+  _: { arity: 0, max: 0, name: "(no positional operands)" },
+  slug: { type: "str", required: true },
+  "run-id": { type: "str" },
+  format: { type: "enum", values: ["json", "table"], default: "json" },
+  cwd: { type: "path" },
+};
+
+/**
+ * Answer "which requirement has evidence, and from which criterion" from the artifacts on disk.
+ *
+ * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
+ * @returns {Promise<void>} Exits 0 with the projection — an absent run, an absent registry and an
+ *   absent verdict are all answers, never errors.
+ */
+export async function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
+  const cwd = resolve(args.cwd || process.cwd());
+  const report = projectRequirements({ cwd, slug: args.slug, runId: args.runId ?? undefined });
+  console.log(args.format === "table" ? renderTable(report) : JSON.stringify(report, null, 2));
+  process.exit(0);
+}
+
+if (isMain(import.meta.url)) cli(process.argv.slice(2));