shapeup-sdlc 3.4.0 → 3.5.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "shapeup-sdlc-plugin",
   "displayName": "ShapeUp SDLC Plugin",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "description": "Shape Up SDLC harness for Claude Code: shaping, intake, orient, scope-mapping, building (T0-verified, sandboxed, scope-contracted), evaluation and QA skills orchestrated by a tech-lead.",
   "author": {
     "name": "Liberty Nguyen",

package/AGENTS.md

@@ -28,9 +28,10 @@ Betting Table: PO decides; rejected pitches loop back to raw idea.
 |------|------|--------|
 | Kick-off | ⏸ **L0** — Intake & Config (L0.8 model/budget matrix) + worker roster ✧ | `/translator` if non-English |
 | Orient (Scout) | ⏸ **L1a** — Orient Review | `/orient` |
-| Analyze | — (reviewed at L1b) | `/ba-pitch-analyzer` (`analyze`): spec tree + board (UC + Invariants + Test Surface ★); before Wire (needs its use cases) |
+| Requirements | — (reviewed at L1b) | `/ba-pitch-analyzer` (`coverage`): the pitch's clauses → committed `requirements.md`, one atomic clause per `REQ-<n>` row naming the pitch clause it came from, ids assigned once and frozen; dispatched once, ahead of Analyze because the acceptance criteria are what cite its ids. A registry already on disk is not re-dispatched |
+| Analyze | — (reviewed at L1b) | `/ba-pitch-analyzer` (`analyze`): spec tree + board (UC + Invariants + Test Surface ★); before Wire (needs its use cases). An acceptance criterion that grades a requirement carries `(covers: REQ-…)` — that clause is the edge the verdict travels back along |
 | Wire | ⏸ **L1a.5** — Wiring Review ✚ | `/solution-architect` (`wire`): sole writer of committed `wiring-map.md` — per-UC engine → seam → entry-point call site → affordance, per `project-profile.md` |
-| Map Scopes | ⏸ **L1b** — Board Review (+ substrate disjointness lint) | `/scope-architect` (scope contracts ✦ — sole writer); traceability oracle advisory ✚ |
+| Map Scopes | ⏸ **L1b** — Board Review (+ substrate disjointness lint) | `/scope-architect` (scope contracts ✦ — sole writer); traceability oracle advisory ✚. A registered requirement that no acceptance criterion grades and no scope claims is **red** here, and L1b prints the `REQ → AC` table: the two ways out are an AC carrying `(covers: REQ-…)` or the PO marking the clause `CUT (PO-approved)`. Red only where the plan is still cheap to change — after L1b nobody re-reads the pitch |
 | Build Vertically | ⏸ **L2** — Board 100% ✅ + T0-green ✦ | per dispatch: compile order → `/task-executor` (--order) → ingest result; T0-verified per attempt (fixtures + DB probe + seesaw ✦), substrate-sandboxed ✦. Scopes build **concurrently** ✦ — `--parallel-scopes N` caps it (default 4), a scope is released the moment its own dependencies are green, and a scope green in this round is skipped rather than rebuilt. Then the **round build gate** ⚙: the ledger's run command, then the profile's `build_probe` and `launch_probe`, run once per round before EVAL — a red gate ends the round with no verdict and its failing step is compiled into the next round's orders as bugs; a `mobile` profile with no `launch_probe` is warned about every round, so the install/launch risk has an owner |
 | EVAL (once per round) | ⏸ **L3** — Verdict | `/spec-evaluator` (--order), only over a round whose build gate ⚙ is not red: spec- + test-surface-conformance ★, T0 citation ✦; refuted boxes/verdict applied by ingest |
 | FAIL → round r+1 | — | regression rule ★: bugs + full Test Surface of touched UC |
@@ -58,6 +59,7 @@ Everything discovered funnels into `.shapeup/<slug>/discovery/ledger.md` (Orient
 - **Ledger = single source of truth** — every discovery flow writes only its own section.
 - **QA is a level-up, not a gate** — `--no-qa` skips it; circuit breaker outranks the Hunter.
 - **Role separation** — Evaluator grades, task-executor fixes, QA discovers.
+- **The requirements matrix is a projection, never a verdict** — `REQ → AC → criterion → verdict` is derived from files for one named run (the registry, the board's `covers:` clauses, the run's verdict rows, the T0 citations), never narrated and never passed in. `covers:` is the authoritative join: a criterion anchored to a requirement no AC covers is printed for reconciliation and counted as nothing. L4 reads one line off it, GATE H's census takes the clauses with no evidence, `REPORT.md` freezes the table — and none of that blocks a ship. A clause with no PASS evidence is a fact the baseline comparison weighs, not a veto.
 - **Hill phase is mechanical ✦** — derived only from T0/T1/seesaw artifacts, never self-reported, and a T0-green from a round whose build gate ⚙ is red moves no dot (a green fixture in a round the feature did not build is evidence about the fixture); the evaluator cites a T0 artifact it re-hashes itself, from the list its order carries. A scoped verdict citing none is refused: its round stays open and is evaluated again, never advanced.
 - **Envelope port (v1.0)** — every dispatch is WorkOrder in / WorkResult out; shared state has exactly one writer (the ingest step); malformed envelopes are hook-denied. Workers: stateless, craft-only, pipeline-blind.
 

package/README.md

@@ -221,8 +221,12 @@ the layer that carries it, and the three layers here fail differently:
 - `PreToolUse` (`Edit|Write|MultiEdit`) — **`hooks/sandbox-guard.mjs` blocks a write that no LIVE
   order's substrate permits.** It reads every order that is compiled and not yet answered — a result
   at least as new as the order itself — rather than a pointer to one, so scopes building
-  concurrently are each held to their own contract and a finished run fences nothing; `frozen`
-  outranks everything, across all of them.
+  concurrently are each held to their own contract and a finished run fences nothing. A phase
+  dispatch the run has already moved past stops fencing too: once a later phase compiles its order,
+  an evaluation or a QA leg that never returned a result no longer holds the board. `frozen` is
+  checked first and outranks everything, across every live contract — including the carve-out that
+  otherwise keeps the active feature's own run trace writable, so a path a live order froze stays
+  frozen wherever it lives.
 - `PreToolUse` (`Bash|Read|Write|Edit|MultiEdit`) — **`hooks/safety-spine.mjs` denies destructive
   commands** (`rm -rf` on unrecoverable targets, force-push/push-to-main, `git reset --hard`,
   `DROP TABLE`) and secret-file reads. A machine guard, not a pipeline guard; the escape hatch is

package/SECURITY.md

@@ -72,7 +72,7 @@ sitting, and reading them is the recommended review.
 | [`safety-spine.mjs`](hooks/safety-spine.mjs) | PreToolUse (`Bash\|Read\|Write\|Edit\|MultiEdit`) | The proposed command/path; `.shapeup/safety-overrides.json` | Yes — provably destructive ops only: `rm -rf` on unrecoverable targets, `git push --force` / push to main, `git reset --hard`, `git clean -fdx`, `DROP TABLE`/`TRUNCATE`, reads of `.env`/keys/cloud credentials, and any write to its own overrides file | Never blocks an unmatched command; `--force-with-lease` stays allowed |
 | [`gate-intake.mjs`](hooks/gate-intake.mjs) | PreToolUse (`Skill`) | The `tech-lead` dispatch's own arguments | Yes — an orchestrator dispatch carrying no resolvable intake (no pitch, spec, resume or requirement text) | Fails open on `--order` and on any ambiguous arg shape |
 | [`harness verify envelope`](kernel/verify/envelope.mjs) | PreToolUse (`Skill\|Agent`) | The `--order` file named in the dispatch; the JSON schemas | Yes — a worker dispatch whose order file is missing or schema-invalid | Never gates a dispatch that carries no `--order` (standalone skill use stays free) |
-| [`sandbox-guard.mjs`](hooks/sandbox-guard.mjs) | PreToolUse (`Edit\|Write\|MultiEdit`) | The target path; the `substrate` block of every LIVE order — compiled, with no result at least as new as the order's own `compiled_at` | Yes — any write no live order permits: outside every `allowed`/`shared`, inside any `frozen`, or a `Write` to an `append_only` path | No-op unless an order is live, which a finished run no longer is: the pointer names the run, never a dispatch. The active feature's own `.shapeup/<slug>/` run-trace is always writable. Appends denials to the local pathology log |
+| [`sandbox-guard.mjs`](hooks/sandbox-guard.mjs) | PreToolUse (`Edit\|Write\|MultiEdit`) | The target path; the `substrate` block of every LIVE order — compiled, with no result at least as new as the order's own `compiled_at`, and, for a run-level phase dispatch, not yet superseded by a later phase's order | Yes — any write no live order permits: inside any `frozen`, outside every `allowed`/`shared`, or a `Write` to an `append_only` path. `frozen` is checked FIRST, so it also outranks the run-trace carve-out | No-op unless an order is live, which a finished run no longer is: the pointer names the run, never a dispatch. The active feature's own `.shapeup/<slug>/` run trace is writable EXCEPT where a live order freezes a path inside it. Appends denials to the local pathology log |
 | [`dispatch-receipt.mjs`](hooks/dispatch-receipt.mjs) | PostToolUse (`Skill\|Agent`) | The `--order` file named in the dispatch; the tool result's own report of which skill ran | **No — it has no deny path at all.** It records that the shipped skill ran, so `harness reduce ingest` can refuse a result no dispatch produced | Never writes an attestation for a result that does not name a resolved skill; never fails the call it observes (every write is inside `try`/`catch`) |
 | [`gate-zerowork.mjs`](hooks/gate-zerowork.mjs) | Stop | Run receipts on disk; the session transcript; the decision ledger | **Yes — the one blocking hook.** Returns `decision:"block"` when the session dispatched the orchestrator and produced no run receipt | Defers the moment any receipt exists; `stop_hook_active` caps it at one block per stop chain |
 

package/hooks/sandbox-guard.mjs

@@ -42,6 +42,21 @@
 // the order's own `compiled_at`, the stamp the compiler writes INTO the order, which a copy or a
 // touch cannot perturb. An order carrying no stamp falls back to presence, which is all it ever had.
 //
+// A RUN-LEVEL ORDER RETIRES AT ITS PHASE BOUNDARY, which is the other half of that same question.
+// Liveness is "compiled, no result yet", so a PHASE dispatch whose worker never returned — a killed
+// evaluation, a QA leg that escalated without a result, a failed scope mapping — would stay live for
+// the rest of the run, and everything its `frozen` list names (the board, the spec tree) would be
+// fenced from then on. The board is the one that bites: the next round's doer cannot tick its own
+// acceptance criteria, and the run wedges with no dispatch actually in flight. The orchestrator has
+// long since moved on by the time that matters, and the move itself is the signal: the next phase
+// compiles its own order. So an order for a RUN-LEVEL operation stops being live once an order for a
+// DIFFERENT operation has been compiled after it — the window the committed tier already has, a
+// phase boundary rather than the middle of somebody else's dispatch. Build legs are exempt: they run
+// concurrently, finish out of order, and an abandoned one is resolved by ``harness init run --force``
+// rather than by a sibling's compile stamp. Two concurrent legs of the SAME operation never retire
+// each other, for that same reason. An order carrying no operation or no `compiled_at` keeps
+// fencing — an unreadable claim is not a retired one.
+//
 // That is the same question as "the writer's own contract" because scope substrates are disjoint by
 // construction — `harness verify spec`'s DISJOINT rule fails a spec where two scopes claim the same
 // path, and it runs at GATE L1b before any build starts. `frozen` is checked across all of them, so
@@ -133,7 +148,37 @@ function answered(resultPath, order) {
 }
 
 /**
- * Every order for this run that has been compiled and not yet answered.
+ * Operations whose order is a BUILD leg — one scope, one attempt, dispatched alongside its siblings.
+ *
+ * Everything else the compiler emits is a RUN-LEVEL phase dispatch, and only those retire at a phase
+ * boundary (see the banner). The distinction is by operation rather than by "does it carry a scope",
+ * because the single-task lane compiles an `execute` order with no scope contract on it and that leg
+ * is still a build.
+ */
+const BUILD_OPERATIONS = new Set(["execute", "fix", "spike"]);
+
+/**
+ * Has the run moved past this order's phase — i.e. did a LATER order for a different operation get
+ * compiled while this one was still unanswered?
+ *
+ * Conservative in both directions it cannot read: an order with no `operation`, a build leg, or an
+ * order with no parseable `compiled_at` keeps fencing.
+ *
+ * @param {object} order - The parsed, unanswered order.
+ * @param {Array<{operation:(string|undefined), at:number}>} stamps - Every compiled order's
+ *   operation and parsed `compiled_at`, unparseable stamps excluded.
+ * @returns {boolean} True when this order's phase is over and it should stop being enforced.
+ */
+function pastItsPhase(order, stamps) {
+  const op = order?.operation;
+  if (!op || BUILD_OPERATIONS.has(op)) return false;
+  const at = Date.parse(order?.compiled_at ?? "");
+  if (Number.isNaN(at)) return false;
+  return stamps.some((s) => s.at > at && s.operation !== op);
+}
+
+/**
+ * Every order for this run that has been compiled, not yet answered, and whose phase is still open.
  *
  * @param {string} cwd - Project root.
  * @param {string} slug - The run named by the pointer.
@@ -143,14 +188,17 @@ function liveOrders(cwd, slug) {
   const dir = ordersDir(cwd, slug);
   if (!existsSync(dir)) return [];
   const rDir = resultsDir(cwd, slug);
-  const live = [];
+  const unanswered = [];
+  const stamps = [];
   for (const f of readdirSync(dir)) {
     if (!f.endsWith(".json")) continue;
     const order = readJSON(join(dir, f));
     if (!order) continue;
-    if (!answered(join(rDir, f), order)) live.push(order);
+    const at = Date.parse(order.compiled_at ?? "");
+    if (!Number.isNaN(at)) stamps.push({ operation: order.operation, at });
+    if (!answered(join(rDir, f), order)) unanswered.push(order);
   }
-  return live;
+  return unanswered.filter((o) => !pastItsPhase(o, stamps));
 }
 
 function extractPaths(toolInput) {
@@ -231,22 +279,33 @@ async function main() {
   const runTracePrefix = join(LOCAL, active.slug) + sep;
   const violations = [];
   const blockReasons = [];
+  let frozenHits = 0;
 
   for (const raw of targetPaths) {
     const abs = resolve(cwd, raw);
     const rel = relative(root, abs);
-    if (rel.startsWith(runTracePrefix)) continue;
 
     // Frozen takes absolute precedence, and it is checked across EVERY live contract: a path one
     // scope froze stays frozen while another scope is in flight, which is the whole point of
     // declaring it.
+    //
+    // IT IS CHECKED BEFORE THE RUN-TRACE CARVE-OUT, and that order is load-bearing. The carve-out
+    // below exists so the doer can keep its own bookkeeping current; it was never a licence to
+    // overwrite a file a live contract declared read-only. Checked after it, every `frozen` glob
+    // naming a path inside the run trace was inert — the board an evaluation froze, the staged pitch
+    // a planner is graded against — so the compiler emitted a declaration with no enforcer, which is
+    // the exact state this hook exists to end. A path a live contract freezes is a violation
+    // wherever it lives.
     const freezer = contracts.find((c) => matchesAny(rel, c.frozen));
     if (freezer) {
       violations.push(rel);
+      frozenHits++;
       blockReasons.push(`${rel} is frozen by ${freezer.order_id}`);
       continue;
     }
 
+    if (rel.startsWith(runTracePrefix)) continue;
+
     if (contracts.some((c) => matchesAny(rel, c.allowed))) continue;      // inside a live contract
 
     if (contracts.some((c) => matchesAny(rel, c.appendOnly))) {
@@ -291,7 +350,11 @@ async function main() {
 
   return {
     verdict: "deny", event: "PreToolUse", tool: p.tool_name, subject: active.order_path, cwd: root,
-    rule: "outside-substrate",
+    // THE LEDGER NAMES THE CAUSE, not just the verdict. A write refused because a live contract
+    // FROZE the path and a write refused because no contract covers it are different facts with
+    // different remedies, and a single rule string cannot tell the reader which one happened —
+    // which is how a frozen declaration can stop being enforced without a single row moving.
+    rule: frozenHits === violations.length ? "frozen" : "outside-substrate",
     reason: `${violations.length} write(s) rejected by substrate boundaries: ${blockReasons.join("; ")}`,
     payload: {
       hookSpecificOutput: {

package/kernel/compile.mjs

@@ -207,6 +207,15 @@ export function substrateFor(operation, { slug, specDir, scope } = {}) {
   // `feedback.md`, `api-feasibility.md` and `integration.md` are analysis, not contract.
   const working = `${local}/working`;
   const FROZEN_SPEC_CORE = [`${spec}/domain-model.md`, `${spec}/usecases/*.md#Steps`, `${spec}/contracts/**`, `${spec}/ux-behavior.md`];
+  // THE STAGED PITCH IS THE RUN'S OWN INPUT TRUTH, and it is a separate constant from the spec core
+  // on purpose: the spec core is what a planner PRODUCES and a judge grades against, while these two
+  // are what the run was asked for. `init run` stages them beside the receipt that digests them, and
+  // every planning and evaluating operation reads them — so a worker that can rewrite either can
+  // rewrite the question it is about to be measured on, and the receipt's digest stops describing
+  // the file next to it. Frozen, not merely unlisted: `analyze` already carries the whole run trace
+  // in its `allowed` globs, so only a `frozen` entry denies the write. `translate` is the one
+  // operation that legitimately rewrites a pitch, and it writes the COMMITTED copy, not this one.
+  const FROZEN_INTAKE = [`${local}/intake.md`, `${local}/breadboard.md`];
   switch (operation) {
     case "execute": case "fix": case "spike":
       return {
@@ -214,7 +223,7 @@ export function substrateFor(operation, { slug, specDir, scope } = {}) {
         shared: scope?.shared_substrate || [],
       };
     case "analyze":
-      return { allowed: [`${spec}/**`, `${local}/**`], frozen: [] };
+      return { allowed: [`${spec}/**`, `${local}/**`], frozen: [...FROZEN_INTAKE] };
 
     case "reconcile":
       return {
@@ -229,24 +238,24 @@ export function substrateFor(operation, { slug, specDir, scope } = {}) {
       // The covers-closure input truth. Writes ONLY the derived registry: the REQ source it
       // extracts from is frozen alongside the spec core, because a planner that may edit the
       // requirements it is being measured against is not measuring anything.
-      return { allowed: [globShared(slug, "requirements.md")], frozen: FROZEN_SPEC_CORE };
+      return { allowed: [globShared(slug, "requirements.md")], frozen: [...FROZEN_SPEC_CORE, ...FROZEN_INTAKE] };
 
     case "map-scopes":
       return {
         allowed: [`${scopesDir}/*.md`, globShared(slug, "scope-board.md")],
-        frozen: [...FROZEN_SPEC_CORE, `${local}/tasks/**`],
+        frozen: [...FROZEN_SPEC_CORE, ...FROZEN_INTAKE, `${local}/tasks/**`],
       };
     case "wire":
       // solution-architect writes the SHARED wiring map DIRECTLY (precedent: scope-architect
       // writes scopes/*.md). The spec core, the scopes, and the profile stay frozen.
       return {
         allowed: [globShared(slug, "wiring-map.md")],
-        frozen: [...FROZEN_SPEC_CORE, `${scopesDir}/**`, globShared(slug, "project-profile.md")],
+        frozen: [...FROZEN_SPEC_CORE, ...FROZEN_INTAKE, `${scopesDir}/**`, globShared(slug, "project-profile.md")],
       };
     case "evaluate":
-      return { allowed: [`${local}/evaluation/**`], frozen: [`${spec}/**`, `${local}/tasks/**`] };
+      return { allowed: [`${local}/evaluation/**`], frozen: [`${spec}/**`, ...FROZEN_INTAKE, `${local}/tasks/**`] };
     case "hunt":
-      return { allowed: [`${local}/qa/**`], frozen: [`${spec}/**`, `${local}/tasks/**`] };
+      return { allowed: [`${local}/qa/**`], frozen: [`${spec}/**`, ...FROZEN_INTAKE, `${local}/tasks/**`] };
     case "orient":
       return { allowed: [`${local}/orient/**`], frozen: [`${spec}/**`] };
     case "translate":

package/kernel/harness.mjs

@@ -31,7 +31,8 @@
 //            ship · board · verdict · graph
 //   gate                                      An answer file with a source, not a vibe.
 //   probe    resume · t0 · stats · digest ·   Read-only queries over run state. `concurrency`
-//            concurrency · leg · eval · owner  answers how many legs ran at once and what the
+//            concurrency · leg · eval ·        answers how many legs ran at once and what the
+//            owner · requirements
 //                                              fan-out bought, and refuses a figure the record set
 //                                              cannot support rather than printing a plausible one.
 //                                              `leg` answers whether a scope's work reached the
@@ -45,7 +46,10 @@
 //                                              own end-of-turn summary of its own verdict. `owner`
 //                                              answers which scope may write a path, elected from
 //                                              the contracts — so a census cites it instead of
-//                                              asserting ownership from memory.
+//                                              asserting ownership from memory. `requirements`
+//                                              answers which pitch clause a verdict reached, joined
+//                                              through the plan's own covers: edge — the L4 line and
+//                                              GATE H's census cite it for the same reason.
 //   init     run · fit                        Opens a run, or refuses it (exit 3).
 //   report   export                           Projects the run's records as fact tables.
 //   compile                                   The WorkOrder: schema-valid or nothing is dispatched.
@@ -81,6 +85,7 @@ export const ROUTES = {
     resume: "./probe/resume.mjs", t0: "./probe/t0.mjs", stats: "./probe/stats.mjs",
     digest: "./probe/digest.mjs", concurrency: "./probe/concurrency.mjs",
     leg: "./probe/leg.mjs", eval: "./probe/eval.mjs", owner: "./probe/owner.mjs",
+    requirements: "./probe/requirements.mjs",
   },
   init: { run: "./init/run.mjs", fit: "./init/fit.mjs" },
   report: { export: "./report/export.mjs", _default: "export" },

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.
  *