shapeup-sdlc 3.16.1 → 3.17.1

package/.claude-plugin/plugin.json

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

@@ -32,11 +32,11 @@ 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` |
 | 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). The tree is committed and the board is per-machine: a run that finds the tree on disk and no board dispatches `board`, which regenerates the board from the tree without re-deriving it — GATE L2 refuses `proceed` over a board with zero tasks. An acceptance criterion that grades a requirement carries `(covers: REQ-…)` — that clause is the edge the verdict travels back along |
+| Analyze | — (reviewed at L1b) | `/ba-pitch-analyzer` (`analyze`): spec tree + board (UC + Invariants + Test Surface ★); before Wire (needs its use cases). The tree is committed and the board is per-machine: a run that finds the tree on disk and no board dispatches `board`, which regenerates the board from the tree without re-deriving it — GATE L2 refuses `proceed` over a board with zero tasks. An acceptance criterion that grades a requirement carries `(covers: REQ-…)` — that clause is the edge the verdict travels back along. A board with no such clause beside a registry sends its writer back once, and one that still has none continues with a warning |
 | 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. 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 |
+| 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. A scope that did not go green in the round has its rows graded FAIL, and the order names such scopes, so one red scope never makes the whole round ungradeable |
 | 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).
@@ -45,7 +45,7 @@ Betting Table: PO decides; rejected pitches loop back to raw idea.
 
 
 ### QA Edge Hunt (`/qa-edge-hunter`, post-PASS, pre-ship)
-**Q0** Preflight → **Q1** Charter (6 lenses − EVAL-covered) → **Hunt** (repro required, findings `~` → ledger) → report (no verdict, no score). Skip with `--no-qa`.
+**Q0** Preflight → **Q1** Charter (6 lenses − EVAL-covered) → **Hunt** (repro required, findings `~` → ledger) → report (no verdict, no score). Skip with `--no-qa`. A hunt that reached the app and ran no charter is sent back once; if it still ran none, the report and the run's close say `not-hunted`, never that QA ran.
 
 ### Ship & Triage
 - **SHIP S.0 / GATE H** — `/scope-hammer`: census (QA findings + discovered ledger + attempt-budget proposals ✦; every "no scope owns X" cites `probe owner`, which derives ownership from the contracts) → baseline comparison (never the ideal) → cut list; TL/PO promotes selected items only. The census is written as data beside the report, and GATE L4 reads that file — and nothing else — before any answer set may say `ship`. A breaker does not end the run: the run itself dispatches the census, crosses GATE H, writes the ship report with the verdict as it is, crosses L4, and only then closes — `shipped` with the cut list when the census clears it, `escalated` naming the census when it does not.

package/kernel/compile.mjs

@@ -1267,6 +1267,11 @@ export async function cli(rawArgv) {
   if (operation === "evaluate" && payloadExtra.t0_artifacts === undefined) {
     const { artifacts, missing } = t0ArtifactsFor(cwd, slug, round);
     if (artifacts.length) payloadExtra.t0_artifacts = artifacts;
+    // A scope that did not go green leaves its rows ungraded, not the round: the judge refused a whole
+    // round over one such scope and the run aborted at L3, before the next round or GATE H's census
+    // could act on it. With at least one citation the round is gradeable, and the order names the
+    // scopes whose rows are FAILs for want of a green T0.
+    if (artifacts.length && missing.length) payloadExtra.scopes_without_t0 = missing;
     // On stderr, never stdout: stdout is the order path the caller consumes.
     if (missing.length) {
       console.error(`compile-order: warning — no green T0 verdict${round ? ` in round ${round}` : ""} for ` +

package/kernel/harness.mjs

@@ -32,7 +32,8 @@
 //   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 ·        answers how many legs ran at once and what the
-//            owner · requirements · attempts
+//            owner · requirements · attempts ·
+//            hunt
 //                                              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
@@ -92,7 +93,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", attempts: "./probe/attempts.mjs",
+    requirements: "./probe/requirements.mjs", attempts: "./probe/attempts.mjs", hunt: "./probe/hunt.mjs",
   },
   init: { run: "./init/run.mjs", fit: "./init/fit.mjs", "run-args": "./init/run-args.mjs" },
   report: { export: "./report/export.mjs", _default: "export" },

package/kernel/probe/hunt.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+// probe hunt — "did the QA hunt hunt anything?"
+//
+// CONTRACT. A bounded, read-only query over the hunt's WorkResult, its order and its report.
+// Prints `{ok, status, qa, charters_run, findings, reason}` on stdout; exits 0 when the hunt's
+// result is one the run may accept, 1 when it is not, and 2 on a bad argv. Writes nothing.
+//
+// WHY THIS EXISTS. A hunter that reached the app, swept the fault log and then drafted no charter
+// still returned `done`, and a `done` with no findings reads as an app with nothing wrong. The hunt
+// report's charter count says what actually happened. A `done` hunt over an app its order could
+// reach, with no charter run, is refused here and on ingest, and the run sends the hunter back once
+// — the same shape as a verdict that grades nothing by name.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { runArgs } from "../lib/argv.mjs";
+import { resultsDir, ordersDir, qaDir } from "../lib/paths.mjs";
+
+/**
+ * The number of charters a hunt report says it ran.
+ *
+ * @param {(string|null)} text - The hunt report's text.
+ * @returns {(number|null)} The run count from its `charters: <run>/<approved>` line, or null when
+ *   there is no report or no such line.
+ */
+export function chartersRun(text) {
+  const m = String(text ?? "").match(/^charters:\s*(\d+)/m);
+  return m ? Number(m[1]) : null;
+}
+
+/**
+ * Whether a hunt result may be accepted as it stands.
+ *
+ * Held to it only when the result says `done` and the order gave the hunter a way into the app
+ * (`launch_cmd` or `app_url`): a hunt that returns `failed` says it could not hunt, which is honest,
+ * and a hunt with no way in cannot be asked to drive anything.
+ *
+ * @param {object} result - The hunt WorkResult.
+ * @param {object} payload - The hunt order's payload.
+ * @param {(string|null)} report - The hunt report's text, or null.
+ * @returns {(string|null)} A reason phrased for the hunter, or null.
+ */
+export function huntProblem(result, payload, report) {
+  if (result?.status !== "done") return null;
+  if (!payload?.launch_cmd && !payload?.app_url) return null;
+  const n = chartersRun(report);
+  if (n === null) return "the hunt returned done with no hunt report carrying a `charters:` line";
+  if (n > 0) return null;
+  return "the hunt returned done over an app its order could reach, having run 0 charters — " +
+    "draft at least one charter where the EVAL left territory uncovered and hunt it, or return failed saying why the app could not be driven";
+}
+
+/**
+ * Read a JSON file, or null.
+ * @param {string} p - Path.
+ * @returns {(object|null)} The parsed document, or null when absent or unreadable.
+ */
+const readJson = (p) => { try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; } };
+
+/**
+ * What the hunt on disk amounts to.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @returns {{ok:boolean, status:(string|null), qa:string, charters_run:(number|null), findings:number, reason:(string|null)}}
+ *   `qa` is `run` (charters ran), `not-hunted` (the hunt returned, no charter ran), or `missing`.
+ */
+export function huntOutcome(cwd, slug) {
+  const result = readJson(join(resultsDir(cwd, slug), "hunt.json"));
+  if (!result) return { ok: false, status: null, qa: "missing", charters_run: null, findings: 0, reason: "no hunt result on disk" };
+  const payload = readJson(join(ordersDir(cwd, slug), "hunt.json"))?.payload || {};
+  const reportPath = join(qaDir(cwd, slug), "hunt-report.md");
+  const report = existsSync(reportPath) ? readFileSync(reportPath, "utf8") : null;
+  const n = chartersRun(report);
+  const reason = huntProblem(result, payload, report);
+  return {
+    ok: !reason,
+    status: typeof result.status === "string" ? result.status : null,
+    qa: n ? "run" : "not-hunted",
+    charters_run: n,
+    findings: Array.isArray(result.discoveries) ? result.discoveries.length : 0,
+    reason,
+  };
+}
+
+export const ARGV_SPEC = {
+  usage: "harness.mjs probe hunt --slug <slug> [--cwd <dir>]",
+  _: { arity: 0, max: 0, name: "(no positional operands)" },
+  slug: { type: "str", required: true },
+  cwd: { type: "path" },
+};
+
+/**
+ * Report what the hunt on disk amounts to.
+ *
+ * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
+ * @returns {void} Exits 0 when the hunt result may be accepted, 1 when it may not.
+ */
+export function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
+  const out = huntOutcome(resolve(args.cwd || process.cwd()), args.slug);
+  console.log(JSON.stringify(out));
+  process.exit(out.ok ? 0 : 1);
+}

package/kernel/probe/requirements.mjs

@@ -269,12 +269,38 @@ export function renderTable(r) {
   return out.join("\n");
 }
 
+/**
+ * Whether a board that has tasks carries any `covers:` clause while a requirements registry exists.
+ *
+ * Two bars answer "is this requirement planned": L1b is satisfied by a scope contract's own covers
+ * list, while the matrix reads only the acceptance criteria's `(covers: REQ-…)` clauses. A board
+ * regenerated with none crossed every gate, and the matrix then read "no evidence" under every
+ * requirement of a run whose criteria had passed. Measured on two consecutive runs of one pitch:
+ * thirty clauses on one board, zero on the next, the same instruction both times.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @returns {(string|null)} A reason phrased for the board's writer, or null when there is no
+ *   registry, no board yet, or at least one clause.
+ */
+export function boardCoversProblem(cwd, slug) {
+  const clauses = parseRequirements(readIf(requirementsFile(cwd, slug)) || "");
+  if (!clauses.length) return null;
+  const board = readBoard(cwd, slug);
+  if (!Array.isArray(board) || !board.length) return null;
+  if (coveringAcs(board).size) return null;
+  return `the board's ${board.length} tasks carry no \`(covers: REQ-…)\` clause while the registry holds ${clauses.length} ` +
+    "requirements — every acceptance criterion that grades a requirement carries its covers clause, or the requirements " +
+    "matrix reads no evidence for any of them";
+}
+
 export const ARGV_SPEC = {
-  usage: "harness.mjs probe requirements --slug <slug> [--run-id <id>] [--format json|table] [--cwd <dir>]",
+  usage: "harness.mjs probe requirements --slug <slug> [--run-id <id>] [--format json|table] [--board-check] [--cwd <dir>]",
   _: { arity: 0, max: 0, name: "(no positional operands)" },
   slug: { type: "str", required: true },
   "run-id": { type: "str" },
   format: { type: "enum", values: ["json", "table"], default: "json" },
+  "board-check": { type: "flag" },
   cwd: { type: "path" },
 };
 
@@ -288,6 +314,12 @@ export const ARGV_SPEC = {
 export async function cli(rawArgv) {
   const args = runArgs(ARGV_SPEC, rawArgv);
   const cwd = resolve(args.cwd || process.cwd());
+  if (args.boardCheck) {
+    // `--board-check` answers one question for the run's send-back: may this board stand?
+    const reason = boardCoversProblem(cwd, args.slug);
+    console.log(JSON.stringify({ ok: !reason, reason }));
+    process.exit(reason ? 1 : 0);
+  }
   const report = projectRequirements({ cwd, slug: args.slug, runId: args.runId ?? undefined });
   console.log(args.format === "table" ? renderTable(report) : JSON.stringify(report, null, 2));
   process.exit(0);

package/kernel/reduce/ingest.mjs

@@ -36,8 +36,9 @@ import { resolve, join, dirname, basename } from "node:path";
 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 { tasksDir, localRoot, dispatchReceipts, legLedger, readRunId, qaDir } from "../lib/paths.mjs";
 import { citationProblem, coverageProblem, verdictProblem } from "../probe/eval.mjs";
+import { huntProblem } from "../probe/hunt.mjs";
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const RESULT_SCHEMA = JSON.parse(readFileSync(resolve(HERE, "../schemas/work-result.schema.json"), "utf8"));
@@ -710,6 +711,24 @@ export async function cli(rawArgv) {
     }
   }
 
+  // --- Hunt gate: a `done` hunt over a reachable app ran at least one charter ---------------------
+  // A hunter that reached the app and drafted nothing returned `done`, and a `done` with no findings
+  // reads as a clean app. See `huntProblem`; `probe hunt` refuses the same result to the run.
+  if (result.worker === "qa-edge-hunter") {
+    const reportRel = (Array.isArray(result.artifacts) ? result.artifacts : []).find((a) => /hunt-report\.md$/.test(String(a)));
+    const reportAbs = reportRel ? (String(reportRel).startsWith("/") ? reportRel : join(cwd, reportRel)) : null;
+    let report = null;
+    for (const p of [reportAbs, join(qaDir(cwd, String(result.order_id).split("/")[0]), "hunt-report.md")]) {
+      if (!report && p && existsSync(p)) report = readFileSync(p, "utf8");
+    }
+    const problem = huntProblem(result, order.payload || {}, report);
+    if (problem) {
+      console.error(`ingest-result: result refused — ${problem}.`);
+      console.error(`  Re-dispatch the hunter against its order. Nothing was written.`);
+      process.exit(1);
+    }
+  }
+
   // Resolved for EVERY order, not only the gated ones: the attesting receipt is this leg's start,
   // and a standalone or `--no-receipt-check` ingest still deserves a truthful timing row rather
   // than one silently falling back to the order's re-writable `compiled_at`.

package/kernel/reduce/ship.mjs

@@ -39,6 +39,7 @@ import { ratchetReport } from "../probe/stats.mjs";
 import { projectRequirements, summaryLine } from "../probe/requirements.mjs";
 import { deriveRounds } from "../probe/rounds.mjs";
 import { collectDiff, scanDiff, summarize } from "./leftovers.mjs";
+import { chartersRun } from "../probe/hunt.mjs";
 
 /** @returns {string} Today as `YYYY-MM-DD` (UTC). */
 const today = () => new Date().toISOString().slice(0, 10);
@@ -392,7 +393,7 @@ export function buildReport(facts) {
  */
 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";
+  if (huntReport && chartersRun(huntReport) === 0) return "not-hunted";
   return passed || "run";
 }
 

package/kernel/schemas/domain.schema.json

@@ -363,6 +363,7 @@
       "launch_cmd",
       "build_gate",
       "revised_checks",
+      "scopes_without_t0",
       "t0_artifacts",
       "browser",
       "tasks"
@@ -2445,6 +2446,11 @@
           },
           "description": "spec-evaluator: rows that FAILed in one of the round's T0 trials and PASS in a later one whose own check file (named by the row id) changed in between. Derived by harness compile. Each must be read against its row before its PASS counts; absent when none."
         },
+        "scopes_without_t0": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "spec-evaluator: scopes whose contract exists but which hold no green T0 verdict for the round, while at least one other scope does. Derived by harness compile. The round is still gradeable: each row such a scope owns is a FAIL citing the scope contract, never a reason to refuse the round. Absent when every scope is green."
+        },
         "build_gate": {
           "type": "string",
           "description": "spec-evaluator, qa-edge-hunter: this run's newest round build gate artifact (build/r<N>-t<T>.json) — each step's exit code and output tail, the record that the build ran and the app launched. Derived by `harness compile`, absent when the gate never ran. Read it before grading a [ui] row NO EVIDENCE."
@@ -2871,6 +2877,11 @@
         "qa_findings": {
           "type": "integer"
         },
+        "qa": {
+          "type": "string",
+          "enum": ["run", "not-hunted", "skipped"],
+          "description": "What QA amounted to: run (at least one charter ran), not-hunted (the hunt returned and ran no charter), skipped (--no-qa or the QA gate answered skip). qa_findings is 0 in the last two for different reasons."
+        },
         "report": {
           "type": "string",
           "description": "shipped: shapeup/<slug>/REPORT.md path."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shapeup-sdlc",
-  "version": "3.16.1",
+  "version": "3.17.1",
   "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

@@ -76,7 +76,9 @@ 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). 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`.
+     and its exit. A hunt that reached nothing returns `status: failed`, never `done`. A hunt that
+     reached the app runs at least one charter: ingest refuses a `done` whose report says
+     `charters: 0/…` while the order carried `launch_cmd` or `app_url`.
   ✅ 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

@@ -43,6 +43,7 @@ Invoked as `--order <path>`. Fields you may rely on (absent = unknown, never inf
 | `payload.build_gate` | This run's newest round build gate artifact — each step's exit code and output tail. It records that the build ran and whether the app launched, and the launch step's output names what it captured. Read it before grading any `[ui]` row NO EVIDENCE: a launch that succeeded is evidence the app can be probed, and the row is graded on the app, not on its absence. Absent → the gate never ran |
 | `payload.revised_checks[]` | Rows that FAILed in one trial of this round and PASS in a later one whose own check file changed in between — a pass obtained by editing the check. Read each listed file against its row's Expect before you let its PASS count; a check that no longer asserts what the row asks makes that row a FAIL, and the bug names the check. Absent → no check was rewritten |
 | `payload.t0_artifacts[]` | Per-scope T0 verdict paths for this round (scoped specs), compiled from each scope's green verdict. An artifact listed but missing/red on disk, or a scoped spec with none listed → the round is NOT gradeable: return `status: failed` with the reason, naming the scope, as your FIRST deviation — a structural precondition, not a criterion |
+| `payload.scopes_without_t0[]` | Scopes with no green T0 this round while others have one. The round IS gradeable: grade every row such a scope owns as FAIL, evidence "no green T0 for scope <id>" with the scope contract as its locator (`…/scopes/<id>.md:1`). Never refuse the round for them — a refusal ends the run before the next round or GATE H can act. Absent → every scope is green |
 | `payload.browser` | `cli` (default, ~4x cheaper) \| `mcp` \| `none` |
 | `payload.tasks[]` | Traceability only (which UCs a task claims): NEVER a grading source — the committed UC text is the criterion, a paraphrase mismatch is a finding |
 | `substrate.allowed` | Your only write surface: `.shapeup/<slug>/evaluation/**` (the report + evidence) |

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

@@ -38,7 +38,7 @@
 //   maxParallelScopes (default 4).
 //
 // return — RunReturn (domain.schema.json $defs/RunReturn), the full union:
-//   { status: "shipped", verdict, rounds_used, dims_not_evaluated, qa_findings, report }
+//   { status: "shipped", verdict, rounds_used, dims_not_evaluated, qa_findings, qa, report }
 //   { status: "paused",  paused_at, block, valid_decisions, context }
 //   { status: "aborted", aborted_at, reason }
 //   { status: "gate_h",  breaker: "outer"|"attempt_budget"|"none"|"deadline", hammer_proposals, green_scopes,
@@ -632,6 +632,22 @@ const QA_REPORT = {
   required: ["ok", "findings_count"],
 };
 
+const BOARD_CHECK = {
+  type: "object",
+  properties: { ok: { type: "boolean" }, reason: { type: ["string", "null"] } },
+  required: ["ok"],
+};
+
+const HUNT_OUTCOME = {
+  type: "object",
+  properties: {
+    ok: { type: "boolean" }, status: { type: ["string", "null"] },
+    qa: { type: "string", enum: ["run", "not-hunted", "missing"] },
+    charters_run: { type: ["integer", "null"] }, findings: { type: "integer" }, reason: { type: ["string", "null"] },
+  },
+  required: ["ok", "qa"],
+};
+
 const HAMMER = {
   type: "object",
   properties: {
@@ -856,6 +872,58 @@ async function worker({ skill, operation, payload, schema, phase: phaseName, lab
   return (r && typeof r === "object") ? r : nullFail(label);
 }
 
+/**
+ * Dispatch a worker, check its result mechanically, and send it back ONCE with the refusal.
+ *
+ * A worker's result can be well-formed and still not what the run asked for — a verdict that grades
+ * the surface as a group, a hunt that reached the app and ran no charter. The kernel says so; this
+ * turns that into one more dispatch carrying the kernel's own reason, and only a second refusal
+ * stands. Measured: a rule in the skill made the judge grade row by row on its first dispatch, and
+ * the refusal is what holds when the model takes the loose path anyway.
+ *
+ * @param {function(string): Promise<object>} dispatch - Dispatches the worker; takes a note to append.
+ * @param {function(string): Promise<(object|null)>} check - Runs the kernel's check; takes a label suffix.
+ * @param {function(object): boolean} refused - Whether a check's answer is a correctable refusal.
+ * @param {string} what - What is being checked, for the log line.
+ * @returns {Promise<{r: object, v: (object|null)}>} The last dispatch and the last check.
+ */
+async function sendBackOnce(dispatch, check, refused, what) {
+  let r = await dispatch("");
+  if (r.__failed) return { r, v: null };
+  let v = await check("");
+  if (v && refused(v)) {
+    log(`${what} — refused (${v.reason}); sent back once`);
+    r = await dispatch(` Your previous result was refused: ${v.reason}. Correct that and return again.`);
+    if (r.__failed) return { r, v: null };
+    v = await check(":again");
+  }
+  return { r, v };
+}
+
+/**
+ * Dispatch a board writer (analyze, or the board-only regeneration) and send it back once when the
+ * board carries no `covers:` clause while a requirements registry exists.
+ *
+ * Advisory past the second dispatch: the requirements matrix never blocks a ship, so a board that
+ * still carries none continues with a state warning naming what the matrix will read, rather than
+ * aborting a run whose plan is otherwise sound.
+ *
+ * @param {function(string): Promise<object>} dispatch - The board writer's dispatch; takes a note.
+ * @param {string} what - The operation, for the log and the warning.
+ * @returns {Promise<{r: object, v: (object|null)}>} The last dispatch and the last check.
+ */
+async function boardSentBack(dispatch, what) {
+  const out = await sendBackOnce(dispatch,
+    (suffix) => query(`probe requirements --slug ${slug} --board-check`, BOARD_CHECK, "Analyze", `board-covers${suffix}`),
+    (v) => !v.ok && !!v.reason, `ANALYZE ${what}`);
+  if (!out.r.__failed && out.v && !out.v.ok && out.v.reason) {
+    const msg = `ANALYZE ${what}: ${out.v.reason} (after one send-back; the requirements matrix will read no evidence)`;
+    log(msg);
+    stateWarnings.push(msg);
+  }
+  return out;
+}
+
 // ---------------------------------------------------------------------------------------------
 // GATES — the kernel's exit-code convention, unchanged: 0 cross · 4 pause · 5 abort. The resolved
 // decision travels in `decision`, copied verbatim out of the kernel's own JSON.
@@ -1172,7 +1240,7 @@ async function closeIfTerminal(ret) {
       // A result the single writer never applied is named at the close, not folded into "not green".
       + (Array.isArray(ret.unapplied_results) && ret.unapplied_results.length ? ` unapplied_results=${ret.unapplied_results.length}` : "")
       + (ret.census ? ` census=${ret.census}` : "") + (ret.l4 ? ` l4=${ret.l4}` : "") + (ret.ship_report ? ` ship_report=${ret.ship_report}` : "")
-    : `verdict=${ret.verdict ?? "?"} rounds=${ret.rounds_used ?? "?"} qa_findings=${ret.qa_findings ?? "?"}`
+    : `verdict=${ret.verdict ?? "?"} rounds=${ret.rounds_used ?? "?"} qa_findings=${ret.qa_findings ?? "?"}` + (ret.qa ? ` qa=${ret.qa}` : "")
       + (ret.after ? ` after=${ret.after} breaker=${ret.breaker ?? "?"} census=${ret.census ?? "?"} cut_list=${Array.isArray(ret.cut_list) ? ret.cut_list.length : "?"}` : "");
   // `--close-arm` hands the kernel the arm itself (not a status this file decided was terminal) —
   // a non-terminal arm (`paused`, `ok`) still exits 0 with no "decision" key, so the branches below
@@ -1384,11 +1452,11 @@ if (!rs.has_spec_tree) {
   // single run since the cutover. It is advisory, so nothing stopped; the ledger simply stayed on
   // the previous phase and the snapshot under-reported where the run had got to.
   await setRunStatus("mapping", "Analyze");
-  const a = await worker({
-    skill: "ba-pitch-analyzer", operation: "analyze", schema: PHASE_OK, phase: "Analyze", label: "analyze",
+  const { r: a } = await boardSentBack((note) => worker({
+    skill: "ba-pitch-analyzer", operation: "analyze", schema: PHASE_OK, phase: "Analyze", label: note ? "analyze:again" : "analyze",
     payload: { pitch: rs.intake_path, breadboard: rs.breadboard_path, spec_folder: specFolder, feature: slug, lens: rs.lens, orient_dir: rs.orient_dir },
-    extra: "Write the spec tree and the board from the orient artifacts — do not re-scan the code.",
-  });
+    extra: "Write the spec tree and the board from the orient artifacts — do not re-scan the code." + note,
+  }), "analyze");
   if (a.__failed) return await withWarnings(diedAt("ANALYZE", a));
   const post = await requirePhase("ANALYZE", "analyze", "Analyze");
   if (post) return await withWarnings(post);
@@ -1402,13 +1470,13 @@ if (!rs.has_spec_tree) {
   // operation regenerates it from the tree without re-deriving the tree.
   log(`ANALYZE — spec tree on disk, no board: dispatching the board-only operation (slug ${slug})`);
   await setRunStatus("mapping", "Analyze");
-  const b = await worker({
-    skill: "ba-pitch-analyzer", operation: "board", schema: PHASE_OK, phase: "Analyze", label: "board",
+  const { r: b } = await boardSentBack((note) => worker({
+    skill: "ba-pitch-analyzer", operation: "board", schema: PHASE_OK, phase: "Analyze", label: note ? "board:again" : "board",
     payload: { spec_folder: specFolder, feature: slug, lens: rs.lens },
     extra: "The spec tree is committed and FROZEN for this dispatch. Regenerate the per-machine board " +
            "under the run's tasks/ directory from the use cases on disk — every acceptance criterion " +
-           "carrying its `(covers: REQ-…)` clause — and write nothing under the spec folder.",
-  });
+           "carrying its `(covers: REQ-…)` clause — and write nothing under the spec folder." + note,
+  }), "board");
   if (b.__failed) return await withWarnings(diedAt("ANALYZE", b));
   // The board a worker writes carries `depends_on`; its inverse (`unlocks`) and a new task's
   // `status: todo` are mechanical, so the kernel writes them rather than trusting every regeneration
@@ -1872,31 +1940,26 @@ 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 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.
-      // The same goes for `build_gate` and `launch_cmd`: compile reads them off the round's gate
-      // 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." + extraNote,
-    });
-    let e = await evalOnce(`eval:r${round}`);
+    const { r: e, v: ev } = await sendBackOnce(
+      (note) => worker({
+        skill: "spec-evaluator", operation: "evaluate", schema: EVAL, phase: "Eval",
+        label: note ? `eval:r${round}:again` : `eval:r${round}`, 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.
+        // The same goes for `build_gate` and `launch_cmd`: compile reads them off the round's gate
+        // 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." + note,
+      }),
+      // 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.
+      (suffix) => query(`probe eval --slug ${slug} --round ${round}`, EVAL_VERDICT, "Eval", `verdict:r${round}${suffix}`),
+      // A verdict the kernel refused — grouped rows, a missing citation — is correctable, not a dead judge.
+      (v) => !v.ok && !!v.overall && !!v.reason,
+      `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.
-    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
@@ -1953,15 +2016,26 @@ let qaFindings = 0;
 const qaG = await crossGate("QA", "QA", ["run", "skip", "ask"], { round, verdict });
 if (qaG.stop) return await withWarnings(qaG.stop);
 const qaRan = !args.noQa && qaG.decision === "run";
+// What QA amounted to, from the hunt's own record: `run` only when a charter ran. The QA gate's `run`
+// is the decision to dispatch, and a dispatched hunt that drove nothing is `not-hunted`.
+let qaState = "skipped";
 if (qaRan) {
-  const q = await worker({
-    skill: "qa-edge-hunter", operation: "hunt", schema: QA_REPORT, phase: "QA", label: "hunt", model: qaModel,
-    payload: { feature: slug, spec_folder: specFolder, app_url: rs.app_url, round },
-    extra: "Exploratory hunt over the shipped feature. No verdict and no score — findings only, each with a repro.",
-  });
+  const { r: q, v: hv } = await sendBackOnce(
+    (note) => worker({
+      skill: "qa-edge-hunter", operation: "hunt", schema: QA_REPORT, phase: "QA", label: note ? "hunt:again" : "hunt", model: qaModel,
+      payload: { feature: slug, spec_folder: specFolder, app_url: rs.app_url, round },
+      extra: "Exploratory hunt over the shipped feature. No verdict and no score — findings only, each with a repro." + note,
+    }),
+    (suffix) => query(`probe hunt --slug ${slug}`, HUNT_OUTCOME, "QA", `hunt-outcome${suffix}`),
+    (v) => !v.ok && v.status === "done" && !!v.reason,
+    "QA hunt",
+  );
   // QA is a level-up: losing its worker costs the findings, not the run.
   if (q.__failed) log(`QA — the hunt lost its worker: ${q.__failed}. Shipping without QA findings.`);
-  else qaFindings = q.findings_count;
+  else {
+    qaFindings = hv && Number.isInteger(hv.findings) ? hv.findings : q.findings_count;
+    qaState = hv?.qa === "run" ? "run" : "not-hunted";
+  }
 }
 
 // ---- GATE H — delegated to scope-hammer (census, baseline comparison, cut list) ----------------
@@ -1986,7 +2060,7 @@ if (h.verdict === "cannot-ship") {
 // "not-evaluated" as a real verdict (its own usage string, and `generate()`'s no-artifact
 // default). Hardcoding PASS here is exactly the silent upgrade protocol.md's Rules forbid.
 const shipVerdict = verdict === "not-evaluated" ? "not-evaluated" : "PASS";
-const ship = await cmd(`reduce ship --slug ${slug} --verdict ${shipVerdict} --qa ${qaRan ? "run" : "skipped"}`, "Ship", "ship-report");
+const ship = await cmd(`reduce ship --slug ${slug} --verdict ${shipVerdict} --qa ${qaState}`, "Ship", "ship-report");
 // GATE L4 HAS A CALL SITE. It used to be a line of prose in the tech lead's references — "resolve
 // the gate itself before any of the above" — and a run reached its ship decision with no ledger row
 // for it. The resolver narrows `ship` on the census artifact the hammer just wrote.
@@ -2016,6 +2090,7 @@ return await withWarnings({
   rounds_used: round,
   dims_not_evaluated: ALL_DIMS.filter((d) => !evalDims.includes(d)),
   qa_findings: qaFindings,
+  qa: qaState,
   report: REPORT_PATH,
 });