shapeup-sdlc 3.15.0 → 3.16.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "shapeup-sdlc-plugin",
   "displayName": "ShapeUp SDLC Plugin",
-  "version": "3.15.0",
+  "version": "3.16.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

@@ -36,7 +36,7 @@ Betting Table: PO decides; rejected pitches loop back to raw idea.
 | 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 ✚. 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 ✦), 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. The order names the round's build gate artifact and the profile's `launch_probe`, so a `[ui]` row is graded on the app the gate launched rather than recorded as no evidence — a project with no `launch_probe` still gets no on-device grade |
+| 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. The order names the round's build gate artifact and the profile's `launch_probe`, so a `[ui]` row is graded on the app the gate launched rather than recorded as no evidence — a project with no `launch_probe` still gets no on-device grade. A PASS names every Test Surface row as its own criterion: one that grades the surface as a group is refused, and the judge is sent back once with the reason |
 | FAIL → round r+1 | — | regression rule ★: bugs + full Test Surface of touched UC. Every criterion the verdict graded FAIL reaches the round, whether or not the judge filed a bug for it, addressed to the scope that owns its use case — a round with a FAIL verdict and nothing to fix is how a run stalls. A row whose check the scope rewrote between a failing trial and a passing one is listed for the judge, who reads it against the row before the pass counts |
 
 ✦ = requires scope contracts (`shapeup/<slug>/scopes/*.md`); ✚ = requires the spine artifacts (`requirements.md`, `wiring-map.md`, `project-profile.md`). Traceability stays advisory until `covers:` is populated. Absent artifact ⇒ arm skipped (non-regression).

package/kernel/probe/eval.mjs

@@ -35,7 +35,7 @@ import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
 import { join, resolve, resolve as resolvePath, sep } from "node:path";
 import { createHash } from "node:crypto";
 import { runArgs } from "../lib/argv.mjs";
-import { resultsDir, scopesDir, readRunId, verdictsDir } from "../lib/paths.mjs";
+import { resultsDir, scopesDir, readRunId, verdictsDir, specDir } from "../lib/paths.mjs";
 
 /** Longest `reason` reported. A deviation is prose written by a worker and can run to paragraphs. */
 const REASON_MAX = 400;
@@ -203,6 +203,56 @@ export function verdictProblem(verdict) {
   return null;
 }
 
+/**
+ * The Test Surface row ids the spec declares, in spec order.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @returns {string[]} Every `TS-…` id that opens a table row in a use-case file; [] with no spec tree.
+ */
+export function surfaceRows(cwd, slug) {
+  const dir = join(specDir(cwd, slug), "usecases");
+  let files = [];
+  try { files = readdirSync(dir).filter((f) => /^UC-.*\.md$/.test(f)).sort(); } catch { return []; }
+  const rows = [];
+  for (const f of files) {
+    let text = "";
+    try { text = readFileSync(join(dir, f), "utf8"); } catch { continue; }
+    for (const m of text.matchAll(/^\|\s*(TS-[A-Za-z0-9_-]+)\s*\|/gm)) if (!rows.includes(m[1])) rows.push(m[1]);
+  }
+  return rows;
+}
+
+/**
+ * Whether a PASS grades every Test Surface row by name.
+ *
+ * A PASS that grades the surface as a whole — "device rows", "local rows" — validated like any other
+ * and switched off everything that reads a verdict row by row: the requirements matrix read no
+ * evidence under every covered requirement, a failed row had no criterion to become a bug, and a row
+ * nobody looked at passed with the rest. A row counts as graded when its id appears in a criterion's
+ * text or its `traces_to`. Only a PASS is held to it: a FAIL sends the round back either way.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {object} verdict - The WorkResult's `verdict`.
+ * @returns {(string|null)} A reason naming the rows no criterion graded, or null.
+ */
+export function coverageProblem(cwd, slug, verdict) {
+  if (verdict?.overall !== "PASS") return null;
+  const rows = surfaceRows(cwd, slug);
+  if (!rows.length) return null;
+  const named = new Set();
+  for (const c of Array.isArray(verdict.criteria) ? verdict.criteria : []) {
+    const text = [c?.criterion, ...(Array.isArray(c?.traces_to) ? c.traces_to : [])].map((x) => String(x ?? "")).join(" ");
+    for (const m of text.matchAll(/\bTS-[A-Za-z0-9_]+(?:-[A-Za-z0-9_]+)*/g)) named.add(m[0]);
+  }
+  const missing = rows.filter((r) => !named.has(r));
+  if (!missing.length) return null;
+  const shown = missing.slice(0, 8).join(", ") + (missing.length > 8 ? ` and ${missing.length - 8} more` : "");
+  return `the PASS verdict grades ${rows.length - missing.length} of ${rows.length} Test Surface rows by name — ` +
+    `each row is its own criterion, its id in the criterion or its traces_to; ungraded: ${shown}`;
+}
+
 export function citationProblem(cwd, slug, verdict, { round = null } = {}) {
   if (verdict?.overall !== "PASS" && verdict?.overall !== "FAIL") return null;
   if (!isScoped(cwd, slug)) return null;
@@ -247,7 +297,7 @@ export function evalVerdict(cwd, slug, round) {
       ? `the evaluator returned ${status || "no status"}: ${first}`
       : `status ${status || "unknown"} with no PASS/FAIL verdict`), status);
   }
-  const problem = verdictProblem(v) || citationProblem(cwd, slug, v, { round });
+  const problem = verdictProblem(v) || coverageProblem(cwd, slug, v) || citationProblem(cwd, slug, v, { round });
   if (problem) return unfit(problem, status, overall);
   return {
     found: true,

package/kernel/reduce/ingest.mjs

@@ -37,7 +37,7 @@ import { fileURLToPath } from "node:url";
 import { validate } from "../verify/envelope.mjs";
 import { runArgs } from "../lib/argv.mjs";
 import { tasksDir, localRoot, dispatchReceipts, legLedger, readRunId } from "../lib/paths.mjs";
-import { citationProblem, verdictProblem } from "../probe/eval.mjs";
+import { citationProblem, coverageProblem, verdictProblem } from "../probe/eval.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const RESULT_SCHEMA = JSON.parse(readFileSync(resolve(HERE, "../schemas/work-result.schema.json"), "utf8"));
@@ -692,17 +692,20 @@ export async function cli(rawArgv) {
     process.exit(1);
   }
 
-  // --- T0 citation gate -----------------------------------------------------------------------
-  // A PASS or FAIL on a scoped spec that cites no T0 artifact is not a judgement this run may act
-  // on (see `citationProblem`). `probe eval` refuses it to the round loop; refusing it here as well
-  // keeps the verdict ledger from recording a verdict the loop will never branch on.
+  // --- Verdict gate: structure, row coverage, T0 citation ---------------------------------------
+  // A PASS or FAIL on a scoped spec that cites no T0 artifact, or a PASS that does not grade every
+  // Test Surface row by name, is not a judgement this run may act on (see `citationProblem`,
+  // `coverageProblem`). `probe eval` refuses it to the round loop; refusing it here as well keeps
+  // the verdict ledger from recording a verdict the loop will never branch on.
   if (result.verdict) {
+    const evalSlug = String(result.order_id).split("/")[0];
     const evalRound = Number((String(result.order_id).match(/-r(\d+)$/) || [])[1]) || null;
-    const problem = verdictProblem(result.verdict) || citationProblem(cwd, String(result.order_id).split("/")[0], result.verdict, { round: evalRound });
+    const problem = verdictProblem(result.verdict) || coverageProblem(cwd, evalSlug, result.verdict)
+      || citationProblem(cwd, evalSlug, result.verdict, { round: evalRound });
     if (problem) {
       console.error(`ingest-result: result refused — ${problem}.`);
       console.error(`  The round stays open: re-dispatch the evaluator against its order, which lists`);
-      console.error(`  the T0 artifacts to cite. Nothing was written.`);
+      console.error(`  the T0 artifacts to cite and the spec whose rows it grades. Nothing was written.`);
       process.exit(1);
     }
   }

package/kernel/reduce/ship.mjs

@@ -370,6 +370,21 @@ export function buildReport(facts) {
   return deboard(L.join("\n"), board.anchors);
 }
 
+/**
+ * The QA line the report may print. The run says whether it dispatched the hunt; the hunt's own
+ * report says whether anything was hunted. A hunter that could not reach the app still returns, and
+ * a report opening `charters: 0/…` over a dispatched hunt read as "QA: run" with no findings — which
+ * a reader takes for an app with nothing wrong, not for an app nobody drove.
+ * @param {string|undefined} passed - What the caller recorded (`run`, `skipped`), if anything.
+ * @param {string|null} huntReport - The hunt report's text, or null when there is none.
+ * @returns {string} `skipped`, `not-hunted` (dispatched, zero charters run), or `run`.
+ */
+export function qaStatus(passed, huntReport) {
+  if (passed === "skipped" || (!passed && !huntReport)) return passed || "skipped";
+  if (huntReport && /^charters:\s*0\s*\//m.test(huntReport)) return "not-hunted";
+  return passed || "run";
+}
+
 /**
  * Gather every fact from disk and render the report.
  * @param {{cwd:string, slug:string, verdict?:string, qa?:string}} opts - Inputs.
@@ -394,7 +409,7 @@ export function generate({ cwd, slug, verdict, qa }) {
     at: today(),
     verdict: verdict || run.final_verdict || "not-evaluated",
     census: (() => { try { return JSON.parse(readIf(hammerCensus(cwd, slug)) || "null"); } catch { return null; } })(),
-    qa: qa || (huntReport ? "run" : "skipped"),
+    qa: qaStatus(qa, huntReport),
     rounds: derivedRounds.rounds_used,
     roundsJudged: derivedRounds.rounds_judged,
     intakeSha: receipt.intake_sha256,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shapeup-sdlc",
-  "version": "3.15.0",
+  "version": "3.16.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/qa-edge-hunter/SKILL.md

@@ -70,9 +70,13 @@ Phase Q3  │ Report ───────► qa/hunt-report.md — no score, no
 ## GATE Q0 — Preflight
 
 ```
+FIRST: read `payload.kb_rules_path` for the tool paths it names — a device tool that is not on PATH is
+  named there by its full path, and a bare-name lookup (`which`, a bare call) proves nothing.
 HARD (any miss → STOP, report which):
   ✅ deliverable reachable: one real request at `app_url`, or `launch_cmd` run and exit 0, or one
-     real invocation of the entry point (not a ping, not a guess that a tool is missing)
+     real invocation of the entry point (not a ping, not a guess that a tool is missing). When the
+     order carries `launch_cmd`, run it before concluding anything; the report names the command
+     and its exit. A hunt that reached nothing returns `status: failed`, never `done`.
   ✅ EVAL-FEATURE-<slug>.md exists with verdict: PASS
   ✅ if discovery/ledger.md exists: ledger.feature == <feature> (read-only context check —
      a missing ledger is fine; ingest creates it when your findings land)

package/skills/spec-evaluator/SKILL.md

@@ -175,6 +175,11 @@ round. Write it so someone without your context can answer it in one reply.
 }
 ```
 
+**Every Test Surface row is its own criterion.** Name the row's id (`TS-05-05`) in `criterion`, one
+row per entry — never a range (`TS-01-04/05`) and never a group ("device rows"). Ingest refuses a
+PASS that leaves any row of the spec unnamed, because the requirement matrix, the next round's bugs
+and the rewritten-check list all read the verdict one row at a time.
+
 **`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:`
@@ -200,6 +205,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)
+- [ ] Every Test Surface row is graded as its own criterion, by id
 - [ ] `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

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

@@ -507,8 +507,9 @@ Effect: one feature-level pass over the running app against all AC + Done-when;
         verdicts, refuted boxes, T0 citations). It touches NO task file and NO board.
 ingest-result <results/evaluate-r<r>.json>: appends the .verdicts JSONL ledger, un-ticks the
         refuted AC boxes, sets eval_verdict frontmatter — the judge returns data, ingest writes.
-        A verdict on a scoped spec that cites no T0 artifact is refused and the round stays
-        open: re-dispatch the evaluator, do not advance the round.
+        A verdict on a scoped spec that cites no T0 artifact, or a PASS that does not name
+        every Test Surface row as its own criterion, is refused and the round stays open:
+        re-dispatch the evaluator once with the refusal's reason, do not advance the round.
 Read back: EVAL-FEATURE-<slug>.md → verdict (pass|fail) + the bug list (each bug has
         task ref, severity, file:line, expected vs actual).
 ```

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

@@ -1868,8 +1868,8 @@ while (verdict !== "pass" && round <= maxRounds) {
     // freezes at GATE L4 has to say that as plainly as the gate block already does.
     verdict = "not-evaluated";
   } else {
-    const e = await worker({
-      skill: "spec-evaluator", operation: "evaluate", schema: EVAL, phase: "Eval", label: `eval:r${round}`,
+    const evalOnce = (label, extraNote = "") => worker({
+      skill: "spec-evaluator", operation: "evaluate", schema: EVAL, phase: "Eval", label,
       model: evalModel, round,
       // No `t0_artifacts` here, deliberately: `harness compile` derives them from the round's green
       // T0 verdicts on disk, for every lane — this script could only name paths it was told about.
@@ -1877,12 +1877,22 @@ while (verdict !== "pass" && round <= maxRounds) {
       // artifact and the project profile, so the judge gets the launch evidence without this script
       // having to carry it.
       payload: { dimensions: evalDims, run_cmd: rs.run_cmd, round },
-      extra: "Evaluate the running feature against every acceptance criterion and Done-when. One feature-level pass; cite every artifact the order lists under t0_artifacts, re-hashing each yourself.",
+      extra: "Evaluate the running feature against every acceptance criterion and Done-when. One feature-level pass; cite every artifact the order lists under t0_artifacts, re-hashing each yourself." + extraNote,
     });
+    let e = await evalOnce(`eval:r${round}`);
     if (e.__failed) return await withWarnings(diedAt("L3", e));
     // The pass/fail branch is decided from the WorkResult on disk, not from the dispatching
     // agent's own summary of it (`e.overall`) — see EVAL_VERDICT's comment for why.
-    const ev = await query(`probe eval --slug ${slug} --round ${round}`, EVAL_VERDICT, "Eval", `verdict:r${round}`);
+    let ev = await query(`probe eval --slug ${slug} --round ${round}`, EVAL_VERDICT, "Eval", `verdict:r${round}`);
+    // A verdict the kernel refused — a PASS that grades the surface as a group, a missing citation —
+    // is a correctable answer, not a dead judge: the judge is sent back once with the refusal's own
+    // words, and only a second refusal ends the round.
+    if (ev && !ev.ok && ev.overall && ev.reason) {
+      log(`EVAL r${round} — verdict refused (${ev.reason}); the judge is sent back once`);
+      e = await evalOnce(`eval:r${round}:again`, ` Your previous verdict for this round was refused: ${ev.reason}. Grade again and correct that.`);
+      if (e.__failed) return await withWarnings(diedAt("L3", e));
+      ev = await query(`probe eval --slug ${slug} --round ${round}`, EVAL_VERDICT, "Eval", `verdict:r${round}:again`);
+    }
     if (!ev) return await withWarnings(diedAt("L3", nullFail(`verdict:r${round}`)));
     // A round with no verdict to act on is NOT a dead worker. An evaluator that refused the round
     // wrote a result saying why, and `probe eval` carries it as `reason`; reported as "died after