shapeup-sdlc 3.9.2 → 3.10.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "shapeup-sdlc-plugin",
   "displayName": "ShapeUp SDLC Plugin",
-  "version": "3.9.2",
+  "version": "3.10.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 |
+| 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 |
 | FAIL → round r+1 | — | regression rule ★: bugs + full Test Surface of touched UC |
 
 ✦ = 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/compile.mjs

@@ -44,7 +44,7 @@ import { writeActiveOrder } from "./probe/resume.mjs";
 import { greenVerdict } from "./probe/t0.mjs";
 import { attemptEvidence, readReceipts } from "./probe/attempts.mjs";
 import { readLegs } from "./probe/leg.mjs";
-import { latestRoundBuild } from "./verify/build.mjs";
+import { latestRoundBuild, latestRoundBuildFile, launchProbeFor } from "./verify/build.mjs";
 // The SAME matcher the sandbox hook enforces with. "Is this cited file inside this scope's
 // substrate" has to mean exactly what the guard means, or a bug is addressed to a scope that is
 // then denied the write that fixes it.
@@ -748,6 +748,42 @@ export function t0ArtifactsFor(cwd, slug, round) {
   return { artifacts, missing };
 }
 
+// --- the launch evidence the judge grades `[ui]` rows against ---------------------------------
+//
+// WHY THE KERNEL DERIVES IT. A `[ui]` criterion is graded on the RUNNING app, and the evaluator's
+// contract for getting one is `payload.run_cmd`; absent, an orchestrated evaluator escalates rather
+// than guess. The ledger's `run_cmd` is what the round build gate runs FIRST, as the build — on a
+// toolchain where building and launching are different acts it is a build, and the ledger carries
+// none at all when nobody pinned one. Meanwhile the gate had already run the project's launch probe
+// (install, start, assert the first screen) moments earlier, recorded its output, and left the
+// app up. None of that reached the order: the gate's artifact was forwarded only when RED, as the
+// next round's bug list, so a green launch was proven and then unavailable to the one reader who
+// needed it. Every `[ui]` row was graded "no evidence on the running app" over a build that launched.
+//
+// Two fields, both derived from disk, both optional, both absent when there is nothing to say —
+// the same non-regression rule as `t0_artifacts`: a project that declares no launch probe compiles
+// exactly the order it always did.
+
+/**
+ * What an evaluate order should carry about launching the app.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {number} [round] - The round being evaluated. Omitted, the newest gate artifact of any
+ *   round — a standalone evaluation has no round.
+ * @returns {{build_gate?: string, launch_cmd?: string}} `build_gate`: repo-relative path of this
+ *   run's newest round build gate artifact (each step's exit and output tail). `launch_cmd`: the
+ *   profile's launch probe. A key is omitted, never null, when its source is absent.
+ */
+export function launchEvidenceFor(cwd, slug, round) {
+  const out = {};
+  const gate = latestRoundBuildFile(cwd, slug, round);
+  if (gate) out.build_gate = relLocal(slug, "build", basename(gate.path));
+  const cmd = launchProbeFor(cwd, slug);
+  if (cmd) out.launch_cmd = cmd;
+  return out;
+}
+
 /**
  * Assemble a WorkOrder envelope. Pure given its inputs — the CLI wrapper does the disk reads.
  * @param {object} opts - The order inputs (destructured):
@@ -1093,6 +1129,13 @@ export async function cli(rawArgv) {
         `${missing.join(", ")}; the evaluator has nothing to cite for ${missing.length === 1 ? "that scope" : "those scopes"}`);
     }
   }
+  // The launch evidence, for every lane (see launchEvidenceFor). Same rule as above: an explicit
+  // `--payload` value outranks the derivation.
+  if (operation === "evaluate") {
+    const ev = launchEvidenceFor(cwd, slug, round);
+    if (ev.build_gate !== undefined && payloadExtra.build_gate === undefined) payloadExtra.build_gate = ev.build_gate;
+    if (ev.launch_cmd !== undefined && payloadExtra.launch_cmd === undefined) payloadExtra.launch_cmd = ev.launch_cmd;
+  }
 
   const order = compileOrder({
     slug, worker, operation, round, attempt, scope, tasks, decisions, digestedErrors, trialHistory, bugs,

package/kernel/probe/t0.mjs

@@ -1,8 +1,16 @@
 // probe t0 — "has this scope already reached T0-green in this round?"
 //
 // CONTRACT. A bounded, read-only query over the verdict artifacts on disk. Prints
-// `{green, path, round, scope_id}` on stdout; exits 0 when green, 1 when not, 2 on a bad argv.
-// Writes nothing.
+// `{green, path, sha256?, round, scope_id}` on stdout; exits 0 when green, 1 when not, 2 on a bad
+// argv. Writes nothing.
+//
+// WHY IT PRINTS A DIGEST. A verdict on a scoped spec must cite a T0 artifact with the sha256 of the
+// file as it is on disk now, and the judge is asked to obtain that itself rather than accept one it
+// was handed. Some sessions have no shell hasher they may run, and a grant that covers this entry
+// point and not `shasum` is the ordinary case, not an oversight. The digest here is computed from
+// the bytes at the moment of the call, with the same reading the ingest step re-checks it against,
+// so a judge that asks for it is asking the file, not a caller. `sha256` is present only when the
+// verdict is green and readable; absent — never null — otherwise.
 //
 // WHY IT IS A SUBCOMMAND AND NOT AN INLINE SNIPPET. The control plane has no filesystem of its
 // own, so the alternative is a `node -e` blob assembled inside the workflow script. Such a blob is
@@ -14,6 +22,7 @@
 // the only durable evidence of that is the verdict artifact the evaluator is required to cite.
 
 import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
 import { join, resolve } from "node:path";
 import { runArgs } from "../lib/argv.mjs";
 import { verdictsDir, readRunId } from "../lib/paths.mjs";
@@ -89,6 +98,18 @@ export function cli(rawArgv) {
   const args = runArgs(ARGV_SPEC, rawArgv);
   const cwd = resolve(args.cwd || process.cwd());
   const { green, path } = greenVerdict(cwd, args.slug, args.scope, args.round);
-  console.log(JSON.stringify({ green, path, scope_id: args.scope, round: args.round }));
+  const sha256 = green ? digestOf(path) : null;
+  console.log(JSON.stringify({ green, path, ...(sha256 ? { sha256 } : {}), scope_id: args.scope, round: args.round }));
   process.exit(green ? 0 : 1);
 }
+
+/**
+ * The sha256 of a verdict artifact, read as `reduce ingest` re-reads it (utf8 text, then hashed) so
+ * the two can never disagree about the same bytes.
+ * @param {string} path - Absolute path of the verdict file.
+ * @returns {(string|null)} Lowercase hex digest, or null when the file cannot be read.
+ */
+function digestOf(path) {
+  try { return createHash("sha256").update(readFileSync(path, "utf8")).digest("hex"); }
+  catch { return null; }
+}

package/kernel/schemas/domain.schema.json

@@ -301,6 +301,13 @@
         "via": "discovered_tasks[]",
         "note": "a red gate's output, digested — surfaces as payload.bugs on the next round's orders"
       },
+      {
+        "from": "WorkOrder",
+        "to": "RoundBuildVerdict",
+        "cardinality": "N:1",
+        "via": "payload.build_gate",
+        "note": "an evaluate order names this run's newest gate artifact for its round, green or red, so the judge knows the build ran and the app launched before grading a [ui] row; payload.launch_cmd carries the profile's launch_probe beside it"
+      },
       {
         "from": "RoundBuildVerdict",
         "to": "HillShard",
@@ -353,6 +360,8 @@
       "feature",
       "dimensions",
       "run_cmd",
+      "launch_cmd",
+      "build_gate",
       "t0_artifacts",
       "browser",
       "tasks"
@@ -2416,6 +2425,14 @@
           "type": "string",
           "description": "spec-evaluator: how to start the running app. Absent orchestrated → ESCALATE, never guess."
         },
+        "launch_cmd": {
+          "type": "string",
+          "description": "spec-evaluator: the project profile's launch probe — installs the built artifact, starts it and asserts the first screen. Derived by `harness compile` from project-profile.md, absent when the profile declares none. Where `run_cmd` is only a build, this is how the app is brought up; a non-zero exit is a finding, not a reason to guess another way."
+        },
+        "build_gate": {
+          "type": "string",
+          "description": "spec-evaluator: 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."
+        },
         "t0_artifacts": {
           "type": "array",
           "items": {

package/kernel/verify/build.mjs

@@ -220,6 +220,62 @@ export function latestRoundBuild(cwd, slug, round) {
   return all.length ? all[all.length - 1].body : null;
 }
 
+/**
+ * The gate artifact an evaluate order should name — the newest one THIS run wrote, with the file it
+ * lives in.
+ *
+ * {@link latestRoundBuild} answers "what did the gate say about round N" and hands back a body; an
+ * order has to point at a file, so the path travels with it here. Scoped to the current run when a
+ * receipt is readable: a prior run over the same slug leaves its own `r1-t1.json` on disk, and the
+ * judge must not be pointed at another run's launch evidence. Scoped to one round when given; with
+ * no round it is the newest of any round — a standalone evaluation has none, the same reading
+ * `t0ArtifactsFor` uses for the T0 verdicts.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {number} [round] - The round being evaluated.
+ * @returns {({path:string, body:object}|null)} null when the gate never ran, or nothing readable
+ *   belongs to this run. Never throws: an order must compile without it.
+ */
+export function latestRoundBuildFile(cwd, slug, round) {
+  let files;
+  const dir = roundBuildDir(cwd, slug);
+  try { files = readdirSync(dir); } catch { return null; }
+  const runId = readRunId(cwd, slug);
+  let best = null;
+  for (const f of files) {
+    const m = f.match(/^r(\d+)-t(\d+)\.json$/);
+    if (!m) continue;
+    const r = Number(m[1]), t = Number(m[2]);
+    if (round != null && r !== Number(round)) continue;
+    let body;
+    try { body = JSON.parse(readFileSync(join(dir, f), "utf8")); } catch { continue; }
+    if (runId && body?.run_id && body.run_id !== runId) continue;
+    if (!best || r > best.r || (r === best.r && t > best.t)) best = { r, t, path: join(dir, f), body };
+  }
+  return best && { path: best.path, body: best.body };
+}
+
+/**
+ * The command the project declared for bringing the built app up — `launch_probe` in the committed
+ * profile: install the artifact, start it, assert the first screen. Read on its own rather than
+ * through {@link declaredSteps}, which also reads the ledger and computes warnings an order has no
+ * use for.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @returns {(string|null)} The command, or null when the profile is absent or declares none.
+ *   Never throws.
+ */
+export function launchProbeFor(cwd, slug) {
+  try {
+    const pp = projectProfile(cwd, slug);
+    if (!existsSync(pp)) return null;
+    const v = readContract(pp, PROJECT_PROFILE)?.contract?.launch_probe;
+    return typeof v === "string" && v.trim() ? v.trim() : null;
+  } catch { return null; }
+}
+
 /**
  * The rounds whose latest gate artifact is red — the set `reduce hill` subtracts from.
  * @param {string} cwd - Project root.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shapeup-sdlc",
-  "version": "3.9.2",
+  "version": "3.10.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/spec-evaluator/SKILL.md

@@ -36,7 +36,9 @@ Invoked as `--order <path>`. Fields you may rely on (absent = unknown, never inf
 | `payload.spec_folder` | The committed grading truth: `usecases/` + `domain-model.md` (+ `contracts/`, `scope-summary.md`, `_index.md`). No `usecases/` → HARD STOP, nothing to grade against |
 | `payload.feature` | Feature slug — scopes the probe and names the report |
 | `payload.dimensions[]` | The active dimension set (the caller resolved precedence). Absent → `[spec-conformance]` + the auto-enable rules below |
-| `payload.run_cmd` | How to start the running app. Absent standalone → ask; absent orchestrated → ESCALATE, do not guess |
+| `payload.run_cmd` | How to start the running app. On a stack where building and launching are different acts it is only the build — prefer `payload.launch_cmd` when the order carries one. Absent standalone → ask; absent orchestrated with no `launch_cmd` either → ESCALATE, do not guess |
+| `payload.launch_cmd` | The project profile's launch probe: installs the built artifact, starts it and asserts the first screen. This is how the app is brought up for `[ui]` probing. A non-zero exit is a finding to cite, not a reason to try another way. Absent → the profile declares none; fall back to `run_cmd` |
+| `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.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.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 |
@@ -94,7 +96,10 @@ Done-when statements; `_index.md` Non-Go list. Which UCs are in scope comes from
   contract triplet + Non-Go). Overall PASS only if ALL active dimensions pass — the halo
   effect is banned; a strong dimension never lifts a failing one.
 - **T0 citation (scoped specs).** Recompute each cited artifact's sha256 from disk — never
-  trust a handed hash. A verdict on a scoped spec without a T0 citation is structurally
+  trust a handed hash. Use any hasher you may run; when none is available to you,
+  `harness probe t0 --slug <slug> --scope <scope_id> --round <r>` prints the digest of that
+  scope's green verdict as the file is at that moment. A digest from any other place — a ledger
+  line, an earlier report, an error message — is a handed hash, however correct it looks. A verdict on a scoped spec without a T0 citation is structurally
   invalid, regardless of how convincing your own probing looked; generator prose ("tests
   pass", "verified locally") is never admissible evidence.
 - **When a criterion names a command, run THAT command.** Not the one that works, not the

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

@@ -490,6 +490,9 @@ compile-order --operation evaluate --slug <slug> --worker spec-evaluator --round
   --payload '{"dimensions": ["spec-conformance"], "run_cmd": "<cmd>"}'
   t0_artifacts is compiled from each scope's green T0 verdict for round <r> — pass it only to
   override. A scope with no green verdict is named on stderr: the judge has nothing to cite for it.
+  build_gate and launch_cmd are compiled too: this run's newest round build gate artifact, and the
+  profile's launch_probe. Neither is passed here — a `[ui]` row is graded on the running app, and
+  these are how the judge finds out the app was launched and how to bring it up again.
 Invoke via Agent (model: eval), ONCE, after GATE L2:
   Skill(shapeup-sdlc-plugin:spec-evaluator) --order <path>
 Effect: one feature-level pass over the running app against all AC + Done-when; writes
@@ -548,7 +551,7 @@ Read back: the proposed cut list + verdict (SHIP now | SHIP after fixing ship-bl
 | `harness-run.md` | **tech lead (sole writer)** | tech lead (round ledger + Hill + run-state), PO (audit) |
 | `scopes/<scope-id>.md` | `scope-architect` (sole writer) | tech lead (substrate/sequence), sandbox hook (write-whitelist), compile-order (inlined into orders) |
 | `t0/verdicts/r<N>-a<M>-t<T>.json` | `harness verify t0` (skill-local, mechanical — not a worker) | spec-evaluator (required citation), tech lead (hill derivation), compile-order (digested errors) |
-| `build/r<N>-t<T>.json` (the round build gate) | `harness verify build` (mechanical — run_cmd + build_probe + launch_probe, once per round before EVAL) | tech lead (GATE L2 block), `harness reduce hill` (a red round moves no dot), compile-order (`payload.bugs` for round N+1) |
+| `build/r<N>-t<T>.json` (the round build gate) | `harness verify build` (mechanical — run_cmd + build_probe + launch_probe, once per round before EVAL) | tech lead (GATE L2 block), `harness reduce hill` (a red round moves no dot), compile-order (`payload.bugs` for round N+1 when red; `payload.build_gate` on the same round's evaluate order) |
 | `t0/trials.jsonl` (the ratchet ledger, append-only, `baseline_trial` as the parent link) | `harness verify t0` (one row per attempt: score, status, delta, tree_ref) | compile-order (`trial_history` into the next order), ship-report (T0 + Ratchet sections), `harness probe stats --ratchet` |
 | `round-ledger.md` | **tech lead (sole writer)** | compile-order (decisions into every order), PO (audit) |
 | `hill/<scope-id>.yml` + `hill-chart.md` | **tech lead (sole writer)** | PO ("status without asking"), scope-hammer (H0 census) |

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

@@ -1837,6 +1837,9 @@ while (verdict !== "pass" && round <= maxRounds) {
       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.",
     });