shapeup-sdlc 3.3.0 → 3.5.0

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 }),
     ...(() => {

package/kernel/verify/trace.mjs

@@ -211,8 +211,16 @@ export function traceLint(slug, { cwd, gate = false }) {
   const findings = [];
 
   // 1. Covers-closure.
+  //
+  // THE WHOLE ARM IS GATED ON THE REGISTRY EXISTING — both halves of it, and the second half is the
+  // one that was missing. With no `requirements.md` there are no clauses, so `REQ-UNCOVERED` cannot
+  // fire; but `dangling` is derived from the BOARD, which needs no registry to carry a `covers:`
+  // clause, so a tree with no registry reported "covers-closure not applicable" in the same breath
+  // as a red finding for every `covers:` on the board. An arm that reports itself skipped and emits
+  // findings anyway is not skipped, and the report says the opposite of what the findings do.
   const reqPath = join(shared, "requirements.md");
-  const clauses = existsSync(reqPath) ? parseRequirements(readFileSync(reqPath, "utf8")) : [];
+  const closureChecked = existsSync(reqPath);
+  const clauses = closureChecked ? parseRequirements(readFileSync(reqPath, "utf8")) : [];
   const board = readBoard(cwd, slug);
   const covered = coveredReqIds(board);
   const knownIds = new Set(clauses.map((c) => c.id));
@@ -227,12 +235,13 @@ export function traceLint(slug, { cwd, gate = false }) {
     findings.push({ severity: "red", code: "REQ-UNCOVERED", req: id,
       message: `${id} (status: covered) is named by no AC's covers: — the clause "${(c?.clause || "").slice(0, 60)}" would silently vanish. Cover it with an AC, or mark it CUT (PO-approved).` });
   }
-  for (const id of dangling) {
-    findings.push({ severity: "red", code: "COVERS-DANGLING", req: id,
-      message: `an AC declares (covers: ${id}) but ${id} is not in requirements.md — a covers: link must resolve to a registered REQ.` });
+  if (closureChecked) {
+    for (const id of dangling) {
+      findings.push({ severity: "red", code: "COVERS-DANGLING", req: id,
+        message: `an AC declares (covers: ${id}) but ${id} is not in requirements.md — a covers: link must resolve to a registered REQ.` });
+    }
   }
 
-  const closureChecked = existsSync(reqPath);
   const coversClosure = {
     checked: closureChecked,
     requirements_total: clauses.length,
@@ -240,8 +249,8 @@ export function traceLint(slug, { cwd, gate = false }) {
     cut_status: cut.length,
     covered_by_ac: [...covered].filter((id) => knownIds.has(id)).length,
     uncovered,
-    dangling_covers: dangling,
-    pass: uncovered.length === 0 && dangling.length === 0,
+    dangling_covers: closureChecked ? dangling : [],
+    pass: uncovered.length === 0 && (!closureChecked || dangling.length === 0),
     skipped_reason: closureChecked ? null : "no requirements.md registry — covers-closure not applicable (non-regression on pre-spine specs).",
   };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shapeup-sdlc",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "description": "Shape Up for coding agents \u2014 with gates the agent can't talk its way past. Harness for Claude Code.",
   "bin": {
     "shapeup-sdlc": "bin/init.mjs"

package/skills/ba-pitch-analyzer/SKILL.md

@@ -98,6 +98,21 @@ its phase; templates live in `assets/templates/`.
 (red). An invariant-backed regression task still anchors to its owning UC — there is no
 second path to green.
 
+**The requirement edge is written on the AC line, or it does not exist.** An acceptance
+criterion that grades a registry requirement ends with `(covers: REQ-…)` — the trailing clause,
+in the checkbox text, not a mention in prose. Measured on two runs of one pitch: every
+requirement had an acceptance criterion somewhere on the board and only half reached a criterion
+the judge grades, because a board AC reaches the judge through the refuted list alone — it can
+yield a FAIL and can never yield a PASS. An AC nothing cites by id produces no evidence for the
+requirement it was written for.
+
+**A requirement with no natural use-case home still becomes a task.** Contrast, localisation, a
+performance ceiling, a test surface — a non-functional clause has no actor+action and so no UC of
+its own, and the habit is to record it in the risk register, where nothing grades it. Give it a
+task whose AC reaches the committed spec (the invariant, the contract field or the Test Surface
+row that states it) and carries its `(covers: REQ-…)`. A line in the risk table is a note; a
+covered AC is a requirement the run can be measured against.
+
 ---
 
 ## The other three operations — same craft, different payload + whitelist
@@ -106,7 +121,7 @@ second path to green.
 |---|---|---|
 | `reconcile` | Verify `ledger.feature == payload.feature` (mismatch → STOP). Map each `[+]` Keep item → its owning UC; new task continues numbering (never renumber); `~`/Cut → synthesis "Hammered Out" row, no file. A Keep item asserting a new invariant → APPEND `[INV-NN]` + TS-INV row to that UC (append-only sections in your substrate). A new actor/action with no UC → `status: "escalated"` + a `deviations[]` spec-ambiguity entry: spawning a UC mid-cycle is silent re-shaping, the PO decides. Finish with board-derive (appetite overflow → report) + spec-lint | re-run phases 1–5; edit UC Steps; resolve the appetite HAMMER yourself |
 | `retrofit-surface` | Append `## Test Surface` (derived rows only, after Error Cases) to each UC of a pre-surface spec; an all-sources-empty UC gets the explicit empty-sources line | touch anything else — append-only substrate |
-| `coverage` | Extract **atomic** customer requirement clauses from `payload.requirements` (default: the pitch) and write the SHARED `shapeup/<slug>/requirements.md` registry: one `\| REQ-id \| clause (verbatim) \| source \| status \| note \|` row per clause. Split compound sentences into one testable clause each — a clause lost *inside* a bigger sentence is a requirement nothing can be traced to. **Assign REQ-ids ONCE and freeze them** (they behave like scope_id, never TASK-NNN — every `covers:` link rots otherwise): re-running, append new clauses with fresh ids, mark a removed clause `CUT (PO-approved)`, never renumber or delete. Status starts `covered` (a live requirement); only the PO sets `CUT`. The REQ source itself is frozen — the registry is a separate derived file | edit the REQ source; renumber existing REQ-ids; delete a dropped clause instead of marking it CUT; invent a requirement not in the source |
+| `coverage` | Extract **atomic** customer requirement clauses from `payload.requirements` (default: the pitch) and write the SHARED `shapeup/<slug>/requirements.md` registry: one `\| REQ-id \| clause (verbatim) \| source \| status \| note \|` row per clause. Split compound sentences into one testable clause each — a clause lost *inside* a bigger sentence is a requirement nothing can be traced to. **Assign REQ-ids ONCE and freeze them** (they behave like scope_id, never TASK-NNN — every `covers:` link rots otherwise): re-running, append new clauses with fresh ids, mark a removed clause `CUT (PO-approved)`, never renumber or delete. Status starts `covered` (a live requirement); only the PO sets `CUT`. The REQ source itself is frozen — the registry is a separate derived file. **Numbering.** A source clause already carrying an `R<n>` keeps its number — `R12` → `REQ-12` — and its `source` cell records where it came from verbatim (`shaping.md R12`), because that cell is the only thing that survives a re-run. A clause with no R-id takes the next free number ABOVE the highest `R<n>` in the source, so it can never collide with one added later. Splitting a compound clause keeps `REQ-12` for the first atomic part and records `shaping.md R12 (split 2/3)` for the rest — a requirement graded in parts is why splitting matters at all. On a re-run, match an existing id by its frozen `source` cell and clause text, **never** by re-deriving the number from the source's current order | edit the REQ source; renumber existing REQ-ids; delete a dropped clause instead of marking it CUT; invent a requirement not in the source; re-point an existing REQ-id because the source's R-numbers shifted |
 ---
 
 ## Anti-rationalization table

package/skills/scope-architect/SKILL.md

@@ -41,6 +41,16 @@ the ship report's census table.
            scalars and [a, b] lists, a `## Affordances` table for affordance_manifest, and a
            short `## Why this slice` paragraph. A reviewer must be able to read the substrate
            in a PR; regeneration preserves prose under headings you do not own.
+           ► affordance_manifest lives in the TABLE and NOWHERE ELSE. Do not also write it in
+             the frontmatter: nothing reads it there, so the copy is discarded — and a run has
+             been lost to exactly that. The frontmatter copy said required_states: [idle], the
+             table cell said a bare idle, the table won, the value was a string where an array
+             was required, and four scopes were never dispatched — the board green, the contract
+             lint-clean, each leg reporting done with no error, every round, until EVAL refused
+             to grade a round whose scopes had never run. A contract declaring no affordances
+             writes `affordance_manifest: []` in frontmatter and no table.
+           ► A LIST INSIDE A TABLE CELL IS WRITTEN `[a, b]`, brackets and all — `[idle]`, never
+             `idle`. A bare word in that cell is a string, and required_states is an array.
              scope_id, topology_type                         — the stable join key is the scope
              use_cases[]                                     — the UC ids this scope implements.
                                                                THE ONLY LINK YOU WRITE TO THE
@@ -53,7 +63,12 @@ the ship report's census table.
                                                                the board's own use_case_refs
              covers[]                                        — optional REQ-ids from
                                                                requirements.md this scope answers
-                                                               for; stable, never renumbered
+                                                               for; stable, never renumbered.
+                                                               WRITE THE REGISTRY'S OWN KEY:
+                                                               `REQ-12`, not the pitch's `R12`.
+                                                               Both resolve — readers normalise —
+                                                               but one spelling in the committed
+                                                               contract is one thing to read
              depends_on[]                                    — scope_ids this scope builds AFTER.
                                                                This is the build ORDER — declare
                                                                it whenever one scope consumes

package/skills/scope-hammer/SKILL.md

@@ -72,6 +72,14 @@ H0.1  Unresolved scopes (breaker cases only):
 H0.2  QA findings (qa-edge-hunter's hunt-report.md, when present) — all `~` by default.
 H0.3  Discovered-task ledger entries still open (discovery/ledger.md, `[+]`/`~` unresolved).
 H0.4  Attempt-budget hammer proposals (scopes that exhausted their T0 attempts during BUILD).
+H0.4b Requirements with no PASS evidence — the pitch clauses the run never showed working. Run
+        node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" probe requirements --slug <slug> --format table
+      and take its `no evidence` rows; cite the row, the same way H0.0 cites ownership. Each is a
+      census item carrying its source clause (`REQ-12 ← shaping.md R12`). A `cut` row is an answer
+      the PO already gave — not an item. An inconsistency row (a criterion anchored to a
+      requirement no acceptance criterion covers) is reported to the PO as a reconciliation, never
+      counted as evidence and never promoted as a finding. No registry on disk → this input is
+      empty and the census is unchanged (absent artifact ⇒ arm skipped).
 H0.5  Classify every item: MUST-HAVE (the pitch's core problem is unsolved without it) vs
       NICE-TO-HAVE (`~`, improves but doesn't block the core promise). Default to NICE-TO-HAVE
       unless the item traces directly to a pitch boundary or a scope's business_goal — a
@@ -81,7 +89,8 @@ H0.5  Classify every item: MUST-HAVE (the pitch's core problem is unsolved witho
 **GATE H0 Output:**
 ```
 ⏸ GATE H0 — Census
-Must-have (unresolved)  : [N] — [list, each with source: scope | QA | discovered | advisor-overflow]
+Must-have (unresolved)  : [N] — [list, each with source: scope | QA | discovered | requirement |
+                                 advisor-overflow]
 Nice-to-have (~)        : [M]
 Carry candidates        : [scopes still uphill/downhill, or exhausted attempt budget]
 ```

package/skills/spec-evaluator/SKILL.md

@@ -152,13 +152,23 @@ round. Write it so someone without your context can answer it in one reply.
     "t0_citations": [ { "scope_id": "cart", "path": "…/t0/verdicts/r2-a3.json", "sha256": "…" } ],
     "criteria": [ { "criterion": "UC-01 step 3", "dimension": "spec-conformance",
                     "verdict": "FAIL", "confidence": "high", "reprobed": true,
-                    "evidence": "Pay click throws — apps/web/checkout/Pay.tsx:84" } ],
+                    "evidence": "Pay click throws — apps/web/checkout/Pay.tsx:84",
+                    "traces_to": ["REQ-4"] } ],
     "refuted": [ { "task_id": "TASK-007", "ac": "<the checkbox text your evidence disproves>" } ],
     "bugs": [ /* report-schema bug entries */ ]
   }
 }
 ```
 
+**`traces_to` is copied, not invented.** Fill it from the `(covers: REQ-…)` clause of the
+acceptance criteria your criterion grades: the AC already carries the link, written when the plan
+was reviewed, and you record which requirement your criterion maps back to. An AC with no `covers:`
+clause yields no anchor — leave the array empty rather than guessing, and never read the pitch to
+supply one. This changes nothing you grade: the anchor is a navigation path, never a grading input,
+and a criterion passes or fails on its evidence exactly as before. It matters downstream because
+the requirement matrix at GATE L4 and the census at GATE H are projected from these anchors; a
+verdict that drops them grades the build and says nothing about what the pitch asked for.
+
 **Every FAIL criterion's `evidence` MUST carry a `file:line` locator** — schema-enforced, not
 advice: the envelope is validated against `work-result.schema.json` at ingest and a locatorless
 FAIL is rejected before any write. A PASS may cite plain output. (Observed, not theorized: a
@@ -175,6 +185,7 @@ separation is the whole point of the architecture.
 ## Verification checklist
 
 - [ ] Every criterion traces to committed spec text (UC/domain-model/contract/Done-when/Non-Go)
+- [ ] `traces_to` copied from the graded ACs' `covers:` clauses — empty where they carry none
 - [ ] Every PASS cites a confirming probe; every FAIL cites evidence or "NO EVIDENCE"
 - [ ] Every FAIL was re-probed once; confidence assigned per the ledger rule
 - [ ] Scoped spec → T0 citations present with recomputed sha256 (else the run returned `failed`)

package/skills/tech-lead/references/gates.md

@@ -297,6 +297,12 @@ Scope contracts present:
     - scope-summary "Done when" headline statements
     - the Deferred Places from ux-behavior.md (breadboard Places this shape will not build) —
       each one needs the PO's yes; a rejected deferral goes back to the planner as a screen
+    - the REQ → AC table from requirements.md, one row per registered requirement: REQ-id, the
+      source clause it came from (`REQ-12 ← shaping.md R12`), and the acceptance criterion that
+      grades it — or the scope that claims it, or CUT (PO-approved). Omitted entirely when the run
+      has no registry. A requirement with none of the three is already a red below; this table is
+      what the PO reads to answer it — cover it, or cut it on the record. Printed, never asked:
+      the table decides nothing at this gate
 No scope contracts (pre-v0.3.0, unchanged from v0.2.6):
   Read tasks/_index.md (LOCAL root). Print:
     - task count by package/variant (.shared / .be / .web / .mobile / .e2e)
@@ -312,7 +318,15 @@ this is the orchestrator's own re-confirmation before committing to a build sequ
     waiting to happen), PA1 (directory-aligned scope), PA2 (size cap), SCOPE-ANCHOR (a scope
     naming no committed use case, or one that does not resolve), TIER-DIRECTION (a committed
     contract naming LOCAL task ids), SCOPE-DEPS (a build-order id naming a scope that is not
-    in this run), BREADBOARD-PLACE (a breadboard Place with UI affordances has no
+    in this run), REQ-UNCOVERED (a requirement in requirements.md that no acceptance criterion
+    grades and no scope claims — the PO's two ways out are an AC carrying `(covers: REQ-…)` or
+    `CUT (PO-approved)` in the registry; silent on a run with no registry),
+    CONTRACT-SCHEMA (a scope contract that parses but not into the shape a WorkOrder carries —
+    most often a list written bare in a table cell where the dialect wants `[a, b]`; without
+    this the compiler refuses the order later and the scope is never dispatched at all, with
+    the board green and the leg reporting done), CONTRACT-UNREADABLE (a table the parser could
+    not see, or a table field also declared in frontmatter where nothing reads it),
+    BREADBOARD-PLACE (a breadboard Place with UI affordances has no
     `## Screen: … (P#)` in ux-behavior.md and is not deferred), BREADBOARD-UI (a U# not
     specified on a screen of its own Place). Any red → HARD STOP, past a 🔴 at the
     architect's own checkpoint. The breadboard reds are the planner's to fix — add the screen
@@ -513,8 +527,15 @@ Feature   : [slug] — [SHIPPED (deployed) | BUILT & VERIFIED — deploy pending
 Rounds    : [r] (build+eval cycles)
 Verdict   : PASS (dims: [spec-conformance]; not evaluated: [security, performance])
 QA        : [hunt done — N findings, M promoted+fixed, rest ~ | skipped (--no-qa) | n/a (pre-QA spec)]
+Requirements: [15/17 PASS · 1 CUT (PO) · 1 no evidence (REQ-12 ← R12) | n/a (no registry)]
 Ledger    : harness-run.md
 ```
+The Requirements line is TRANSCRIBED, never composed — run
+`node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" probe requirements --slug <slug> --format table`
+and copy its `Requirements:` summary. It joins each registered clause to the acceptance criterion
+that covers it and to the criterion the judge graded, over the run named in its own output. It
+decides nothing here: a requirement with no PASS evidence is a fact GATE H's census and the
+baseline comparison weigh, not a ship blocker.
 Question (max 1): "Anything to record before I close the run? (y/n) or provide feedback for the next sprint."
 On confirm:
 - If the PO provides substantive feedback (not just 'y' or empty) → automatically delegate via Agent (model: exec — see references/protocol.md "Invocation mechanism"): Skill(shapeup-sdlc-plugin:coach) with the provided feedback for RLHF. The coach runs its own GATE COACH-1 to have the PO categorize each rule, then files it under the responsible skill in `shapeup/knowledge-base/<skill>.md` (committed → team-shared). Coachable: `task-executor`, `ba-pitch-analyzer`, `qa-edge-hunter`, `orient`, `scope-architect`, `solution-architect` (each reads its own file at the top of its next run) and `tech-lead` (workflow guidance, read at the next GATE L0). Guidance never decides a gate: a filed rule may add a question or a check to a gate block, never an answer. The tech lead does not categorize the feedback itself — that is the coach's gate, by design (no assumptions).

package/skills/tech-lead/schemas/domain.schema.json

@@ -341,6 +341,7 @@
       "spec_folder",
       "feature",
       "discovered_ledger",
+      "requirements",
       "kb_rules_path"
     ],
     "scope-architect": [
@@ -2611,6 +2612,10 @@
           "type": "boolean",
           "description": "ANALYZE finished: the spec folder's usecases/ carries at least one use case that is not _index.md. WIRE reads these — one wiring-map entry per use case — which is why ANALYZE precedes WIRE in the phase chain: dispatched against an empty spec folder, WIRE escalates on every launch."
         },
+        "has_requirements": {
+          "type": "boolean",
+          "description": "The requirements registry is on disk: shapeup/<slug>/requirements.md exists. A PLAIN FACT, not a phase — the orchestrator guards its single `coverage` dispatch on this boolean, and it is deliberately absent from kernel/probe/resume.mjs's PHASE_ARTIFACT map, which doubles as nextPhase()'s ordered list: an entry there would fast-forward every run recorded before the registry existed to the registry instead of to build."
+        },
         "has_wiring_map": {
           "type": "boolean",
           "description": "WIRE finished: shapeup/<slug>/wiring-map.md exists."

package/skills/tech-lead/workflows/shapeup-run.js

@@ -407,6 +407,9 @@ const RESUME = {
     eval_dimensions: { type: "array", items: { type: "string" } },
     has_orient_artifacts: { type: "boolean" },
     has_spec_tree: { type: "boolean" },
+    // The requirements registry — a fact, not a phase. See the COVERAGE block below for why it is
+    // guarded on this bare boolean and never asked about through `probe resume --require`.
+    has_requirements: { type: "boolean" },
     has_wiring_map: { type: "boolean" },
     has_project_profile: { type: "boolean" },
     // THE SHAPE THE KERNEL WRITES, not a convenient one. `probe resume` emits `{scope_id, path}` per
@@ -488,7 +491,7 @@ const ORIENT = {
   required: ["ok", "artifact_written", "spiked_area", "spike_result"],
 };
 
-/** analyze / wire — "did the artifact land?" is all a gate needs from them. */
+/** coverage / analyze / wire — "did the artifact land?" is all a gate needs from them. */
 const PHASE_OK = {
   type: "object",
   properties: { ok: { type: "boolean" }, artifact_written: { type: "boolean" }, detail: { type: "string" } },
@@ -1006,8 +1009,47 @@ if (!rs.has_orient_artifacts) {
   if (g.stop) return withWarnings(g.stop);
 }
 
-// ---- ANALYZE (spec tree + board) — ahead of WIRE, which reads its use cases -------------------
+// ---- COVERAGE (the requirements registry) — ahead of ANALYZE, whose ACs cite its ids ----------
+//
+// WHY IT RUNS AT ALL, and why here. The pitch's own requirement list is the one statement of what
+// the run was asked for, and until it is extracted into `shapeup/<slug>/requirements.md` there is
+// no stable key an acceptance criterion, a scope contract or a verdict can point back to. Measured
+// on a full run: the planner produced the requirement edge on the board and the judge never saw
+// it, because nothing on either side shared a key space. So the registry is written BEFORE the
+// board, not beside it — ANALYZE's acceptance criteria cite `REQ-<n>` ids, which have to exist
+// before they can be cited.
+//
+// IT IS NOT A PHASE, AND THAT IS THE WHOLE DESIGN OF THIS BLOCK.
+//   · No `phase("Coverage")`: the dispatch belongs to the planning stretch the Analyze group
+//     already covers (`setRunStatus("mapping")` spans it), so it never renders as an empty group
+//     on a relaunch — the failure a per-phase progress box would otherwise have to pay a leg to
+//     avoid, and there is no leg to spend here (see the next point).
+//   · No `requirePhase()` / no `fastForward()`: both route to `probe resume --require`, whose
+//     `--require` is an ENUM over `PHASE_ARTIFACT`'s keys. `coverage` is not one, so the call exits
+//     2, and this file reads any exit other than 6 as "the predicate was never asked" — a dispatch
+//     that worked would abort the run. The skip is therefore narrated, and guarded on the bare
+//     `has_requirements` boolean the resume state carries.
+//   · Not in `PHASE_ARTIFACT` either: that map is also `nextPhase()`'s ordered list, so adding it
+//     would fast-forward every pre-registry run to the registry instead of to `build`.
 phase("Analyze");
+if (!rs.has_requirements) {
+  log(`COVERAGE — dispatching (slug ${slug})`);
+  await setRunStatus("mapping", "Analyze");
+  const c = await worker({
+    skill: "ba-pitch-analyzer", operation: "coverage", schema: PHASE_OK, phase: "Analyze", label: "coverage",
+    payload: { requirements: rs.intake_path, feature: slug },
+    extra:
+      "Extract the pitch's requirement clauses into the SHARED requirements registry, one atomic " +
+      "clause per row. A clause carrying an R-id keeps its number as REQ-<n> and records the R-id " +
+      "verbatim in its source cell; ids are assigned once and never renumbered.",
+  });
+  if (c.__failed) return diedAt("COVERAGE", c);
+  await advisory(`reduce graph --slug ${slug}`, "Analyze", "graph:coverage");
+} else {
+  log(`COVERAGE — a requirements registry is already on disk; not re-dispatching it`);
+}
+
+// ---- ANALYZE (spec tree + board) — ahead of WIRE, which reads its use cases -------------------
 if (!rs.has_spec_tree) {
   log(`ANALYZE — dispatching (slug ${slug})`);
   // "mapping", not "analyzing": the kernel's RUN_STATUSES enum is deliberately COARSER than this
@@ -1193,6 +1235,17 @@ await advisory(`reduce hill --slug ${slug}`, "MapScopes", "hill-derive");
 const lastEval = rs.eval_rounds_done?.length ? Math.max(...rs.eval_rounds_done) : 0;
 let round = lastEval + 1;
 let verdict = null;
+// DERIVED FROM DISK AT EVERY LAUNCH, never accumulated only in memory. These two lists ARE GATE H's
+// census: `scope-hammer` is dispatched with `hammer_proposals`, and AGENTS.md makes a scope that
+// exhausted its attempt budget a queued GATE H proposal. As bare `const []` they were emptied by the
+// one event that most needs them intact — a gate PAUSE is a `return`, so the PO's answer is followed
+// by a FRESH LAUNCH whose accumulators start empty and whose round loop is then fast-forwarded past
+// the rounds that filled them. The PO was handed an empty cut list for a run that had genuinely
+// exhausted scopes. Unattended (`ci`) runs never pause, which is why no archived trace shows it.
+//
+// This file has now paid for the same class three times — `findings` in the temporal dead zone and
+// `payload.bugs` "lived in a variable, which a relaunch between two rounds resets to empty" are the
+// other two. The cure is the same each time and it is not a bigger variable: re-derive the fact.
 const allGreen = [];
 const allHammer = [];
 // OUTSIDE the loop, because its whole purpose is to cross a round boundary: round r's verdict is
@@ -1248,6 +1301,16 @@ while (verdict !== "pass" && round <= maxRounds) {
   const alreadyGreen = new Set(g?.green_scopes_by_round?.[String(round)] || []);
   if (alreadyGreen.size) log(`BUILD r${round} — ${alreadyGreen.size} scope(s) already green in the graph, skipping them`);
 
+  // REBUILD THE CENSUS FROM THE GRAPH THIS QUERY JUST RETURNED. Everything a prior launch learned is
+  // already on disk: a scope green in ANY round is green work, and a scope the run has touched but
+  // never got green is what GATE H has to be shown. One query, already made, re-read — so a relaunch
+  // after a paused gate carries the same census the launch that paused it would have.
+  const greenEver = new Set(Object.values(g?.green_scopes_by_round || {}).flat());
+  for (const sid of greenEver) if (!allGreen.includes(sid)) allGreen.push(sid);
+  for (const sid of (g?.scopes || [])) {
+    if (!greenEver.has(sid) && !allHammer.includes(sid) && scopes.some((x) => x.scope_id === sid)) allHammer.push(sid);
+  }
+
   // SCOPES FAN OUT. A scope contract is the definition of an independent subtask — disjoint
   // substrate, own fixtures, own ratchet — so the loop that ran them one at a time was leaving the
   // whole point of the contract on the floor. `pipeline()` has NO barrier between its stages: a
@@ -1281,13 +1344,25 @@ while (verdict !== "pass" && round <= maxRounds) {
       async (pre, s) => (pre?.pending ? buildScope(s, round) : pre),
       async (res, s) => {
         if (!res || res.__failed) return res;
-        if (res.resumed || !res.green) return res;
-        const confirmed = await query(`probe t0 --slug ${slug} --scope ${s.scope_id} --round ${round}`,
-          T0CHECK, "Build", `t0confirm:${s.scope_id}-r${round}`);
-        if (!confirmed?.green) {
-          log(`BUILD r${round} — ${s.scope_id} reported green but no T0 verdict is on disk for this ` +
-              `round; treating it as not green (the evaluator cites that artifact, and it is not there).`);
-          return { ...res, green: false, reason: "reported green with no T0 verdict artifact on disk" };
+        if (!res.green) return res;
+        // THE T0 RE-READ IS SKIPPED FOR A RESUMED SCOPE; THE LEG CHECK BELOW IS NOT.
+        //
+        // `resumed` means the graph already reported this scope green for this round, so re-reading
+        // its T0 artifact would only confirm what the resume derivation just read. But these two
+        // stages answer DIFFERENT questions, and the second one is precisely the question a resumed
+        // scope is most likely to fail: a relaunch happens because the previous launch DIED, and a
+        // leg that died between writing its result and running `reduce ingest` leaves exactly this
+        // state — green T0 on disk, result never applied, board still `pending`. The short-circuit
+        // used to cover both stages, so the one scope class known to be at risk was the one class
+        // nobody asked, and the late-ingest repair nine lines below could never fire for it.
+        if (!res.resumed) {
+          const confirmed = await query(`probe t0 --slug ${slug} --scope ${s.scope_id} --round ${round}`,
+            T0CHECK, "Build", `t0confirm:${s.scope_id}-r${round}`);
+          if (!confirmed?.green) {
+            log(`BUILD r${round} — ${s.scope_id} reported green but no T0 verdict is on disk for this ` +
+                `round; treating it as not green (the evaluator cites that artifact, and it is not there).`);
+            return { ...res, green: false, reason: "reported green with no T0 verdict artifact on disk" };
+          }
         }
         // AND ITS RESULT HAS TO HAVE REACHED THE BOARD. A green T0 says the worker's fixtures ran and
         // passed; it says nothing about whether the WorkResult was applied, and this stage used to ask
@@ -1341,8 +1416,10 @@ while (verdict !== "pass" && round <= maxRounds) {
     }
   }
 
-  allGreen.push(...roundGreen);
-  allHammer.push(...roundHammer);
+  for (const sid of roundGreen) if (!allGreen.includes(sid)) allGreen.push(sid);
+  // A scope that went green this round is no longer a cut candidate, however it was queued earlier.
+  for (const sid of roundGreen) { const i = allHammer.indexOf(sid); if (i !== -1) allHammer.splice(i, 1); }
+  for (const sid of roundHammer) if (!allHammer.includes(sid) && !allGreen.includes(sid)) allHammer.push(sid);
 
   // INNER breaker: nothing green and something queued → GATE H. The census is scope-hammer's job.
   if (roundGreen.length === 0 && roundHammer.length > 0) {