shapeup-sdlc 3.4.0 → 3.5.0

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));

package/kernel/probe/resume.mjs

@@ -63,7 +63,7 @@ import { splitFrontmatter } from "../lib/contract.mjs";
 import { globToRegExp } from "../verify/spec.mjs";
 import {
   intake, harnessRun, wiringMap, projectProfile, scopesDir, resultsDir, ordersDir,
-  orientDir, activeOrder, usecasesDir, breadboard, receipt, readReceipt,
+  orientDir, activeOrder, usecasesDir, breadboard, receipt, readReceipt, requirements,
 } from "../lib/paths.mjs";
 import { evalVerdict } from "./eval.mjs";
 
@@ -394,6 +394,12 @@ export function deriveResumeState(cwd, slug) {
     orient_dir: `.shapeup/${slug}/orient/`,
     has_orient_artifacts: hasOrientArtifacts(cwd, slug),
     has_spec_tree: hasSpecTree(cwd, slug, hr.spec_folder || null),
+    // A PLAIN FACT, DELIBERATELY NOT A PHASE. The requirements registry is dispatched once, before
+    // ANALYZE, and the orchestrator guards that one dispatch on this boolean. It is NOT an entry in
+    // PHASE_ARTIFACT, and adding it there would be a migration hazard rather than a tidier shape:
+    // that map is also `nextPhase()`'s ordered list, so every run recorded before the registry
+    // existed would fast-forward to the registry instead of to `build` on its next relaunch.
+    has_requirements: existsSync(requirements(cwd, slug)),
     has_wiring_map: existsSync(wiringMap(cwd, slug)),
     project_profile_path: projectProfile(cwd, slug),
     has_project_profile: existsSync(projectProfile(cwd, slug)),

package/kernel/reduce/graph.mjs

@@ -32,7 +32,7 @@ import {
   localRoot, receipt as receiptPath, ordersDir, resultsDir, verdictsDir, trials as trialsPath,
   gates as gatesPath, scopesDir, usecasesDir, requirements as requirementsPath, wiringMap as wiringMapPath,
 } from "../lib/paths.mjs";
-import { readAllContracts, readContract, ucId, SCOPE_CONTRACT, WIRING_MAP } from "../lib/contract.mjs";
+import { readAllContracts, readContract, ucId, reqId, SCOPE_CONTRACT, WIRING_MAP } from "../lib/contract.mjs";
 import { runIdFromReceipt } from "../lib/paths.mjs";
 
 /** The graph's home — one file per feature, beside the run trace it projects. */
@@ -263,7 +263,10 @@ export function project(cwd, slug) {
       // UseCase nodes it was built from and `--trace` stopped there instead of reaching the
       // objective. The contract now names both, so both are projectable.
       for (const uc of contract.use_cases || []) edge(id, "IMPLEMENTS", `uc:${slug}:${ucId(uc)}`);
-      for (const req of contract.covers || []) edge(id, "COVERS", `req:${slug}:${req}`);
+      // Normalised to the registry's key space on the way in, the same mapping spec-lint applies:
+      // a contract citing the pitch's `R<n>` and a Requirement node keyed `REQ-<n>` are one node,
+      // and an edge drawn to the other spelling is an edge to a node the graph does not hold.
+      for (const req of contract.covers || []) edge(id, "COVERS", `req:${slug}:${reqId(req)}`);
       for (const dep of contract.depends_on || []) edge(id, "DEPENDS_ON", `scope:${slug}:${dep}`);
     }
   }

package/kernel/reduce/ingest.mjs

@@ -8,7 +8,9 @@
 //   task_results[]      → tick AC boxes, flip task frontmatter status, append Execution Log,
 //                         update tasks/_index.md row, propagate unblocks (old P3.1–P3.6)
 //   discoveries[]       → append to .shapeup/<slug>/discovery/ledger.md (old P3.7 / QA H.3)
-//   verdict.criteria[]  → append evaluation/.verdicts-<target>.jsonl (old evaluator B.0)
+//   verdict.criteria[]  → append evaluation/.verdicts-<target>.jsonl (old evaluator B.0), every
+//                         row keyed by run_id and carrying the judge's traces_to[] anchor back to
+//                         the requirement — see step 4 for why neither may be dropped here
 //   verdict.refuted[]   → un-tick refuted AC boxes + set eval_verdict frontmatter (old B.2/B.2b)
 //   (the leg itself)    → append one leg-completion row to .shapeup/<slug>/legs.jsonl
 //
@@ -286,21 +288,32 @@ function applyResultLocked(result, { cwd, slug }) {
   }
 
   // 4. Verdict bookkeeping (old evaluator B.0/B.2/B.2b) — judge returns data, ingest writes.
+  //
+  // THE PROJECTION KEEPS THE TWO KEYS A LATER READER CANNOT RE-DERIVE. Measured on the first real
+  // verdict of a spined run: 85 of 97 criteria carried `traces_to` in the WorkResult and 0 of 97
+  // survived into this file, so the anchor from a criterion back to the requirement it grades was
+  // written by the judge and discarded one step later. And the row carried only the monotonic `run`
+  // counter, which restarts per ledger file and repeats across runs of one slug — `run_id` is the
+  // only key that separates them, so a projection over this file silently mixed two runs without
+  // it. A WorkResult carries no run key; it is read off the run's own receipt, the same derivation
+  // every other writer here uses.
   if (result.verdict) {
     const evalDir = join(local, "evaluation");
     mkdirSync(evalDir, { recursive: true });
     if (result.verdict.criteria?.length) {
       const target = result.order_id.split("/")[1] || "run";
       const ledger = join(evalDir, `.verdicts-${target}.jsonl`);
+      const runId = readRunId(cwd, slug);
       let run = 1;
       if (existsSync(ledger)) {
         const prior = readFileSync(ledger, "utf8").trim().split(/\n/).filter(Boolean).map((l) => { try { return JSON.parse(l); } catch { return null; } }).filter(Boolean);
         run = prior.reduce((mx, r) => Math.max(mx, r.run || 0), 0) + 1;
       }
       const lines = result.verdict.criteria.map((c) => JSON.stringify({
-        run, dimension: c.dimension || "spec-conformance", criterion: c.criterion,
+        run, run_id: runId, dimension: c.dimension || "spec-conformance", criterion: c.criterion,
         verdict: c.verdict, confidence: c.confidence, reprobed: !!c.reprobed,
-        evidence: c.evidence || "", at: new Date().toISOString(),
+        evidence: c.evidence || "", traces_to: Array.isArray(c.traces_to) ? c.traces_to : [],
+        at: new Date().toISOString(),
       })).join("\n");
       appendFileSync(ledger, lines + "\n");
       summary.verdict_lines = result.verdict.criteria.length;

package/kernel/reduce/ship.mjs

@@ -36,6 +36,7 @@ import {
 } from "../lib/paths.mjs";
 import { readTrials } from "../verify/t0.mjs";
 import { ratchetReport } from "../probe/stats.mjs";
+import { projectRequirements, summaryLine } from "../probe/requirements.mjs";
 import { collectDiff, scanDiff, summarize } from "./leftovers.mjs";
 
 /** @returns {string} Today as `YYYY-MM-DD` (UTC). */
@@ -167,7 +168,7 @@ export function section(md, heading) {
 export function buildReport(facts) {
   const {
     slug, at, verdict, qa, rounds, board, t0, artifacts, ratchet,
-    evalCriteria, evalBugs, qaFindings, decisions, discovered, intakeSha, leftovers,
+    evalCriteria, evalBugs, qaFindings, decisions, discovered, intakeSha, leftovers, requirements,
   } = facts;
 
   const L = [];
@@ -214,6 +215,40 @@ export function buildReport(facts) {
     L.push("");
   }
 
+  // The requirement matrix — the way back from a verdict to the clause the pitch asked for, frozen
+  // at the one moment the run's local evidence still exists. Omitted entirely when the run has no
+  // registry: a table of nothing reads as "no requirements", which is a different claim from "this
+  // run predates the registry". Derived like every other figure here, by the same probe the L4 line
+  // and GATE H's census read, so the three cannot disagree.
+  if (requirements?.registry && requirements.rows.length) {
+    L.push("## Requirements", "");
+    L.push("One row per registered clause. A requirement has evidence when an acceptance criterion",
+      "covers it AND a criterion grading it passed — `covers:` is the join, the judge's anchor is the",
+      "path back. This is a projection, never a verdict: it never blocked this ship.", "");
+    L.push(`**${summaryLine(requirements)}** · run \`${requirements.run_id ?? "unknown"}\``, "");
+    // A clause, an AC and a criterion are all free prose, and a literal pipe in any of them breaks
+    // the row into columns nobody wrote — a frozen report that misrenders its own evidence.
+    /**
+     * Escape a free-prose value for a Markdown table cell.
+     * @param {string} s - The value.
+     * @returns {string} The value with every literal pipe escaped.
+     */
+    const cell = (s) => String(s).replace(/\|/g, "\\|");
+    L.push("| REQ | source | evidence | covering AC | criterion | T0 |", "|---|---|---|---|---|---|");
+    for (const r of requirements.rows) {
+      const ac = r.covering_acs.length ? `${r.covering_acs[0].task_id}: ${r.covering_acs[0].ac}${r.covering_acs.length > 1 ? ` (+${r.covering_acs.length - 1})` : ""}` : "—";
+      const crit = r.criteria.length ? `${r.criteria[0].criterion}${r.criteria.length > 1 ? ` (+${r.criteria.length - 1})` : ""} → ${r.criteria.map((c) => c.verdict).join(",")}` : "—";
+      const t0h = r.t0.length ? r.t0.map((h) => String(h).slice(0, 12)).join(", ") : "—";
+      L.push(`| ${r.id} | ${cell(r.source || "—")} | ${r.evidence} | ${cell(ac)} | ${cell(crit)} | ${t0h} |`);
+    }
+    L.push("");
+    if (requirements.inconsistencies.length) {
+      L.push("Anchored to a requirement no acceptance criterion covers — reconcile, do not count as evidence:", "");
+      for (const i of requirements.inconsistencies) L.push(`- ${i.requirement} ← "${i.criterion}" (${i.verdict})`);
+      L.push("");
+    }
+  }
+
   // The ratchet aggregate is derived, ~10 scalars that do not grow with the run, which is why it
   // can live in the committed tier while `metrics/` correctly stays gitignored (ADR-0001: a
   // committed shard keyed on $HOSTNAME only grows). Without this the instrument existed and was
@@ -306,6 +341,7 @@ export function generate({ cwd, slug, verdict, qa }) {
     board: boardCensus(cwd, slug),
     t0: t0Summary(cwd, slug),
     ratchet: ratchetReport(readTrials(trials(cwd, slug))),
+    requirements: projectRequirements({ cwd, slug }),
     artifacts: verdictArtifactCount(cwd, slug),
     evalCriteria: section(evalReport, /^#+\s.*criteria/i) || section(evalReport, /^#+\s*spec-conformance/i),
     evalBugs: section(evalReport, /^#+\s*Bugs?\b/i),

package/kernel/verify/spec.mjs

@@ -34,6 +34,11 @@
 //   SCOPE-COVERS  a contract's covers entry that is not a REQ-id (warn), or names a REQ that
 //             is not in requirements.md (red, when a registry exists) — shape alone let a scope
 //             claim coverage of a requirement that does not exist
+//   REQ-UNCOVERED  the other direction of the same edge: a registered requirement still marked
+//             covered that NO acceptance criterion grades and NO scope claims. SCOPE-COVERS asks
+//             whether a link resolves; this asks whether a requirement has one at all. Red here
+//             and only advisory in trace-lint, because a requirement nothing reaches is a plan
+//             defect the PO can still answer at L1b — cover it, or cut it on the record
 //   SCOPE-PARTITION  a task claimed by more than one scope. The UC anchor is a SPEC link, not an
 //             assignment: one use case is routinely implemented by several scopes, so on a
 //             four-scope/one-UC cut every scope claimed every task and would build all of them.
@@ -65,9 +70,18 @@ import { parseBoard, deriveUnlocks } from "../reduce/board.mjs";
 import { runArgs } from "../lib/argv.mjs";
 import { LOCAL } from "../lib/paths.mjs";
 import { specDir, scopesDir, tasksDir, intake, sharedRoot, requirements } from "../lib/paths.mjs";
-import { readAllContracts, unreadableReason, ucId, scopePartitionConflicts, SCOPE_CONTRACT } from "../lib/contract.mjs";
+import { readAllContracts, unreadableReason, ucId, reqId, scopePartitionConflicts, SCOPE_CONTRACT } from "../lib/contract.mjs";
+import { UNREADABLE, LEGACY_LAYOUT } from "../lib/contract.mjs";
+import { validate as validateAgainstSchema, SCHEMAS_DIR } from "./envelope.mjs";
 import { breadboard as stagedBreadboard } from "../lib/paths.mjs";
 import { parseBreadboard, hasBreadboardTables, idCounts } from "../lib/breadboard.mjs";
+// ONE implementation of covers-closure, two reporters: trace-lint narrates it, spec-lint gates it.
+// Re-deriving either here is how the advisory report and the gate start disagreeing about which
+// requirement is covered. This closes the import ring spec → trace → compile → probe/resume → spec,
+// which holds only while no module in it dereferences an imported binding at module-evaluation
+// time — do NOT add a top-level `const x = someImportedFn()` to any of the four.
+import { parseRequirements, coveredReqIds } from "./trace.mjs";
+import { readBoard } from "../compile.mjs";
 
 // Inlined from hooks/sandbox-guard.mjs so this skill ships self-contained (a skill's scripts
 // must not reach outside its own folder — channels that copy only skills/ would dangle).
@@ -347,7 +361,11 @@ export function lintScopeAnchors({ scopes, specDir: specRoot, reqIds = null, tas
       else if (id && !ids.has(id)) findings.push({ rule: "SCOPE-DEPS", level: "red", scope: where, detail: `depends_on "${id}" is not a scope in this run — the scheduler drops the edge, so this scope may build before its dependency` });
     }
     for (const r of s.covers || []) {
-      const req = String(r).trim();
+      // ONE KEY SPACE. A pitch numbers its requirements `R<n>` and the registry keys off
+      // `REQ-<n>`; `reqId` maps the first onto the second BEFORE the pattern below, so a link the
+      // planner actually wrote resolves instead of reading as a shape warning nobody can act on.
+      // A reference neither space recognises comes back verbatim and still fails the pattern.
+      const req = reqId(r);
       if (!/^REQ-[A-Z0-9-]+$/i.test(req)) {
         findings.push({ rule: "SCOPE-COVERS", level: "warn", scope: where, detail: `covers "${r}" is not a REQ-id — the requirement edge will not resolve` });
         continue;
@@ -372,6 +390,55 @@ export function lintScopeAnchors({ scopes, specDir: specRoot, reqIds = null, tas
   return findings;
 }
 
+/**
+ * REQ-UNCOVERED — a live requirement that nothing in the plan reaches.
+ *
+ * THE OTHER DIRECTION OF THE COVERS EDGE. `SCOPE-COVERS` walks the links that exist and asks
+ * whether each one resolves; a requirement with no link at all satisfies it perfectly. Measured on
+ * a full run of one pitch: twenty-one requirements, every one of them with an acceptance criterion
+ * somewhere, and only eleven reaching a criterion the judge grades — the board is the last place a
+ * requirement can be dropped without anything going red, because after L1b nobody re-reads the
+ * pitch.
+ *
+ * WHY THE BOARD HERE IS `readBoard`, NOT `lint()`'s `tasks`. `parseBoard` (`kernel/reduce/board.mjs`)
+ * builds the scheduling view and its records carry no `acceptance_criteria` field at all, while
+ * `coveredReqIds` reads exactly that field — feed it the wrong board and the covered set is empty
+ * and EVERY requirement reds on EVERY run. `readBoard` (`kernel/compile.mjs`) is the parser that
+ * carries the criteria, and it is the only other one there may be: a second parser of the task file
+ * is explicitly ruled out where the first one lives.
+ *
+ * A SCOPE'S CLAIM COUNTS. The arm is about requirements nothing reaches, not about which layer
+ * reaches them: a clause claimed by a contract's `covers:` has an owner who answers for it at L1b,
+ * even before the criterion that grades it is written. `CUT (PO-approved)` is likewise an answer
+ * already given, not a defect — which is why `status` is read rather than assumed.
+ *
+ * @param {{clauses:Array<{id:string, clause:string, source:string, status:string}>,
+ *   board:Array<object>, scopes:Array<{covers?:string[]}>}} input - The registry clauses
+ *   (`parseRequirements`), the board `readBoard` parsed, and the scope contracts. An empty
+ *   `clauses` (no registry on disk) yields no findings — absent artifact ⇒ arm skipped.
+ * @returns {Array<{rule:string, level:("red"|"warn"), scope:string, detail:string}>} One red per
+ *   uncovered live requirement; [] when every one is graded, claimed or cut.
+ */
+export function lintRequirementCoverage({ clauses = [], board = [], scopes = [] }) {
+  const findings = [];
+  const graded = coveredReqIds(board);
+  // The contracts speak the pitch's numbering as readily as the registry's; `reqId` lands both in
+  // the one key space before the comparison, exactly as SCOPE-COVERS does above.
+  const claimed = new Set();
+  for (const s of scopes) for (const r of s.covers || []) claimed.add(reqId(r).toUpperCase());
+  for (const c of clauses) {
+    if (c.status !== "covered") continue; // CUT (PO-approved) — an answer on the record, not a gap
+    const id = c.id.toUpperCase();
+    if (graded.has(c.id) || claimed.has(id)) continue;
+    const from = c.source ? ` ← ${c.source}` : "";
+    findings.push({ rule: "REQ-UNCOVERED", level: "red", scope: c.id, detail:
+      `${c.id}${from} is graded by no acceptance criterion and claimed by no scope — "${(c.clause || "").slice(0, 60)}" ` +
+      "would ship unverified and nothing downstream would say so. Cover it with an AC carrying " +
+      `(covers: ${c.id}), or mark it CUT (PO-approved) in requirements.md.` });
+  }
+  return findings;
+}
+
 /**
  * Every dependency cycle among the scopes, each reported once from its lowest-sorting member.
  * @param {Array<{scope_id:string, depends_on?:string[]}>} scopes - The contracts.
@@ -663,6 +730,51 @@ export function runBreadboard(cwd, slug, intakeContent) {
   return hasBreadboardTables(intakeContent) ? intakeContent : null;
 }
 
+/**
+ * Every scope contract whose PARSED shape fails `$defs/ScopeContract`.
+ *
+ * `kernel/lib/contract.mjs`'s own banner promised this check — "spec-lint re-validates every parsed
+ * contract against domain.schema.json, so a hand-edit that breaks the shape fails loudly instead of
+ * silently widening a sandbox" — and it did not exist. `compile` validated, spec-lint did not, so a
+ * contract could pass GATE L1b green and then be refused at dispatch by the one reader that checked.
+ *
+ * Measured 2026-09-19 on a real run: a planner wrote every `required_states` table cell bare
+ * (`loading, error, ready`) where the dialect wants `[loading, error, ready]`, so all 32 manifest
+ * rows across the six UI scopes parsed as strings. `verify spec` reported `red=0`; `compile` then
+ * refused all six with `expected array, got string`, and those scopes were never dispatched — no
+ * order, no leg, no T0 trial. The round reached EVAL with six of eighteen scopes missing and the
+ * evaluator escalated rather than grading. This arm turns that into a red at the gate, naming the
+ * scope and the field, with the message the compiler would otherwise produce an hour later.
+ *
+ * The validator is the one `compile` already uses; there is no second implementation here.
+ *
+ * @param {Array<{contract:object, path:string}>} contracts - Parsed contracts with their paths.
+ * @param {object} domainSchema - The parsed `domain.schema.json`.
+ * @returns {Array<{rule:string, level:string, scope:string, detail:string}>} One red per invalid
+ *   contract; [] when the schema cannot be read (absent artifact ⇒ arm skipped).
+ */
+export function lintContractSchema(contracts, domainSchema) {
+  const def = domainSchema?.$defs?.ScopeContract;
+  if (!def) return [];
+  const schema = { ...def, $defs: domainSchema.$defs };
+  const out = [];
+  for (const { contract, path } of contracts) {
+    const c = { ...contract };
+    delete c[UNREADABLE];
+    delete c[LEGACY_LAYOUT];
+    let res;
+    try { res = validateAgainstSchema(c, schema); } catch { continue; }  // fail open, never closed
+    if (res?.valid) continue;
+    out.push({
+      rule: "CONTRACT-SCHEMA", level: "red", scope: contract.scope_id || path,
+      detail: `the contract parses, but not into the shape a WorkOrder carries — ${(res.errors || [])[0] || "schema validation failed"}. ` +
+        `compile refuses an order that fails its own schema, so as written this scope would be silently undispatched. ` +
+        `A list in a table cell is written [a, b], brackets and all.`,
+    });
+  }
+  return out;
+}
+
 /**
  * Run the full spec lint (scopes + structure) for a slug.
  * @param {{cwd:string, slug:string}} opts - Working root and feature slug.
@@ -679,10 +791,21 @@ export function lint({ cwd, slug }) {
   const intakeContent = existsSync(intakePath) ? readFileSync(intakePath, "utf8") : "";
   // The REQ registry, when the tree has one — absent means covers-closure simply cannot apply.
   const reqFile = requirements(cwd, slug);
-  const reqIds = existsSync(reqFile)
-    ? new Set([...readFileSync(reqFile, "utf8").matchAll(/\bREQ-[A-Z0-9-]+/gi)].map((m) => m[0].toUpperCase()))
+  const reqText = existsSync(reqFile) ? readFileSync(reqFile, "utf8") : null;
+  const reqIds = reqText !== null
+    ? new Set([...reqText.matchAll(/\bREQ-[A-Z0-9-]+/gi)].map((m) => m[0].toUpperCase()))
     : null;
+  // Table rows only, and with the status/source cells REQ-UNCOVERED reports from — the id set
+  // above is deliberately looser (it also sees ids named in the registry's prose) and stays that
+  // way, because the two arms ask different questions of the same file.
+  const reqClauses = reqText !== null ? parseRequirements(reqText) : [];
   const repoFiles = walkFiles(cwd);
+  // Loaded HERE, not at module scope. `spec → trace → compile → probe/resume → spec` is a live
+  // import ring, and a top-level dereference of an imported binding is what would break it.
+  // Unreadable schema ⇒ the arm skips itself, like every other absent-artifact arm.
+  let domainSchema = null;
+  try { domainSchema = JSON.parse(readFileSync(join(SCHEMAS_DIR, "domain.schema.json"), "utf8")); } catch { /* arm skipped */ }
+
   const findings = [
     // A contract whose table this parser cannot see reads as a contract that declared no
     // table, and every rule below then passes for the part it could not read. Loud, not empty.
@@ -690,8 +813,11 @@ export function lint({ cwd, slug }) {
       .map(({ contract, path }) => ({ reason: unreadableReason(contract), scope: contract.scope_id || path }))
       .filter((x) => x.reason)
       .map((x) => ({ rule: "CONTRACT-UNREADABLE", level: "red", scope: x.scope, detail: `${x.reason} — the rules below could not check what they could not read` })),
+    ...lintContractSchema(contracts, domainSchema),
     ...lintScopes(scopes, repoFiles),
     ...lintScopeAnchors({ scopes, specDir: specRoot, reqIds, tasks }),
+    // `readBoard`, not the `tasks` above: only the compile-order parser carries acceptance_criteria.
+    ...lintRequirementCoverage({ clauses: reqClauses, board: readBoard(cwd, slug), scopes }),
     ...lintCommittedTier({ cwd, slug }),
     ...lintStructure({ specDir: specRoot, tasks, intakeContent }),
     ...(() => {