shapeup-sdlc 3.4.0 → 3.5.0

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