shapeup-sdlc 3.2.0 → 3.3.0

package/kernel/probe/owner.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+// probe owner — which scope owns a path, derived from the contracts and nothing else.
+//
+// WHY THIS IS A QUERY AND NOT A SENTENCE. GATE H's census stated ownership facts without reading
+// the contracts: a ship report said no scope owned the app's page files, while the composition
+// root's committed substrate listed `pages/**` in plain sight. The real gap was elsewhere (a route
+// table naming files nobody had written), and the report pointed the PO at a scope cut that was
+// not the problem. A census that narrates ownership from memory is a census that can be wrong in
+// exactly the way that looks most authoritative.
+//
+// Ownership already has ONE mechanical definition in this plugin — the substrate the sandbox hook
+// enforces, and the election `harness compile` runs to address a cited bug to the scope that may
+// write the file (`electOwner`). This probe exposes that same answer on the command line, so a
+// worker that needs to say "no scope owns X" can cite the query instead of asserting it.
+//
+// With no `--path`, the input set is what a census would ask about anyway: every engine and
+// entry-point call site the wiring map names, plus the profile's entry point. A row with no
+// writers is an UNOWNED SEAM — the one kind of gap the disjointness lint cannot see, since DISJOINT
+// fails two owners and nothing fails zero.
+//
+// Usage:
+//   node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" probe owner --slug <slug> [--path <p>]... [--format json|table] [--cwd <dir>]
+//
+// Exit code: 0 = answered, 2 = bad argv or no readable scope contracts.
+
+import { existsSync } from "node:fs";
+import { resolve, join } from "node:path";
+import { runArgs, isMain } from "../lib/argv.mjs";
+import { wiringMap, projectProfile } from "../lib/paths.mjs";
+import { readContract, WIRING_MAP, PROJECT_PROFILE } from "../lib/contract.mjs";
+import { scopeSubstrates, electOwner, bugLocations } from "../compile.mjs";
+import { matchesAny } from "../../hooks/sandbox-guard.mjs";
+
+/**
+ * Ownership of one repo-relative path under a set of scope substrates.
+ *
+ * @param {string} path - Repo-relative POSIX path.
+ * @param {Array<{scope_id:string, allowed:string[], shared:string[]}>} scopes - From
+ *   {@link scopeSubstrates}.
+ * @param {string} [cwd] - Project root; when given, `exists` says whether the path is on disk.
+ * @returns {{path:string, owner:(string|null), writers:string[], shared_with:string[], exists:(boolean|null)}}
+ *   `owner` is the elected fixer (exclusive first, lowest id among equals); `writers` every scope
+ *   whose substrate admits the path; `shared_with` the writers that declare it shared. Empty
+ *   `writers` means no scope may write the file — an unowned path. `exists` is the other half a
+ *   census needs: a seam that is owned but not on disk is a route to a file nobody wrote.
+ */
+export function ownership(path, scopes, cwd = null) {
+  const rel = String(path).replace(/^\.\//, "");
+  const writers = (scopes || []).filter((s) => matchesAny(rel, s.allowed)).map((s) => s.scope_id).sort();
+  const shared = (scopes || []).filter((s) => matchesAny(rel, s.shared || [])).map((s) => s.scope_id).sort();
+  return { path: rel, owner: electOwner(rel, scopes), writers, shared_with: shared, exists: cwd ? existsSync(join(cwd, rel)) : null };
+}
+
+/**
+ * The paths a census asks about when none are given: the wiring map's engines and entry call
+ * sites, and the profile's entry point. Only tokens that look like files are kept — an entry call
+ * site is prose around a path (`src/server.ts — POST /checkout route`), and the path is what the
+ * substrate can answer for.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @returns {Array<{path:string, cited_by:string}>} Distinct paths with where each was named.
+ */
+export function seamPaths(cwd, slug) {
+  const out = [];
+  const seen = new Set();
+  const add = (p, by) => { if (p && !seen.has(p)) { seen.add(p); out.push({ path: p, cited_by: by }); } };
+  const wm = wiringMap(cwd, slug);
+  if (existsSync(wm)) {
+    const entries = readContract(wm, WIRING_MAP)?.contract?.entries || [];
+    for (const e of entries) {
+      for (const p of bugLocations({ location: e.engine })) add(p, `${e.use_case || "?"} engine`);
+      for (const p of bugLocations({ location: e.entry_call_site })) add(p, `${e.use_case || "?"} entry_call_site`);
+    }
+  }
+  const pp = projectProfile(cwd, slug);
+  if (existsSync(pp)) {
+    const ep = readContract(pp, PROJECT_PROFILE)?.contract?.entry_point;
+    for (const p of bugLocations({ location: ep })) add(p, "project-profile entry_point");
+  }
+  return out;
+}
+
+/**
+ * Render the report as a fixed-width table for a human reading a gate block.
+ * @param {object} r - The report {@link cli} prints.
+ * @returns {string} One header line and one row per path.
+ */
+export function renderTable(r) {
+  const rows = r.paths.map((p) => [p.path, p.owner || "—", p.writers.join(",") || "UNOWNED", p.exists === null ? "?" : p.exists ? "yes" : "MISSING", p.cited_by || ""]);
+  const head = ["path", "owner", "writers", "on disk", "cited by"];
+  const w = head.map((h, i) => Math.max(h.length, ...rows.map((row) => String(row[i]).length)));
+  const line = (row) => row.map((c, i) => String(c).padEnd(w[i])).join("  ").trimEnd();
+  return [line(head), line(w.map((n) => "-".repeat(n))), ...rows.map(line),
+    "", `${r.scopes} scope(s) read · ${r.unowned.length} unowned path(s)${r.unowned.length ? `: ${r.unowned.join(", ")}` : ""}` +
+    ` · ${r.missing.length} not on disk${r.missing.length ? `: ${r.missing.join(", ")}` : ""}`].join("\n");
+}
+
+export const ARGV_SPEC = {
+  usage: "harness.mjs probe owner --slug <slug> [--path <p>]... [--format json|table] [--cwd <dir>]",
+  _: { arity: 0, max: 0, name: "(no positional operands)" },
+  slug: { type: "str", required: true },
+  path: { type: "str", multiple: true },
+  format: { type: "enum", values: ["json", "table"], default: "json" },
+  cwd: { type: "path" },
+};
+
+/**
+ * Answer "which scope owns this path" from the committed contracts.
+ *
+ * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
+ * @returns {Promise<void>} Exits 0 with the report, 2 when no scope contract can be read.
+ */
+export async function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
+  const cwd = resolve(args.cwd || process.cwd());
+  const scopes = scopeSubstrates(cwd, args.slug);
+  if (!scopes.length) {
+    console.error(`probe owner: no readable scope contract for ${args.slug} — ownership is a property of the contracts, and there are none to read`);
+    process.exit(2);
+  }
+  const asked = (args.path || []).map((p) => ({ path: p, cited_by: "--path" }));
+  const inputs = asked.length ? asked : seamPaths(cwd, args.slug);
+  const paths = inputs.map((i) => ({ ...ownership(i.path, scopes, cwd), cited_by: i.cited_by }));
+  const report = {
+    slug: args.slug,
+    scopes: scopes.length,
+    source: asked.length ? "--path" : "wiring-map + project-profile",
+    paths,
+    unowned: paths.filter((p) => p.writers.length === 0).map((p) => p.path),
+    // Owned but absent: the wiring names a file nobody wrote — the gap a census reads as
+    // "unowned" when it does not check the disk.
+    missing: paths.filter((p) => p.exists === false).map((p) => p.path),
+  };
+  console.log(args.format === "table" ? renderTable(report) : JSON.stringify(report, null, 2));
+  process.exit(0);
+}
+
+if (isMain(import.meta.url)) cli(process.argv.slice(2));

package/kernel/probe/stats.mjs

@@ -20,7 +20,7 @@
 // Usage: node `harness probe stats` [--cwd <dir>] [--metrics-dir <dir>] [--slug <slug>] [--format json|table]
 
 import { readFileSync, readdirSync, existsSync } from "node:fs";
-import { resolve, join } from "node:path";
+import { resolve, join, relative, sep } from "node:path";
 import { validate } from "../verify/envelope.mjs";
 import { runArgs } from "../lib/argv.mjs";
 import { localDir, decisions as decisionsPath, metricsDir as metricsDirPath, SHARED } from "../lib/paths.mjs";
@@ -283,6 +283,49 @@ export function readDecisions(cwd) {
   } catch { return []; }
 }
 
+/**
+ * Decision ledgers that landed OUTSIDE the project root — the trace a hook left when it filed
+ * under the shell's working directory instead of the project's.
+ *
+ * The hooks now resolve the root themselves, so a stray is either history from before that fix or
+ * evidence the resolver missed a layout; either way the rows in it are missing from the ledger
+ * `--hooks` reads, and a count that silently omits them is the inert-layer signature this report
+ * exists to expose. Bounded walk: depth-limited, skipping dependency and VCS directories.
+ *
+ * @param {string} cwd - Project root.
+ * @param {number} [maxDepth=8] - How deep to look.
+ * @returns {Array<{path:string, rows:number}>} Each stray ledger and its row count.
+ */
+export function strayLedgers(cwd, maxDepth = 8) {
+  const SKIP = new Set(["node_modules", ".git", ".hg", ".svn", ".hvigor", ".idea", "dist", "build", "target", ".next", ".cache"]);
+  const out = [];
+  const home = decisionsPath(cwd);
+  /**
+   * Visit one directory level.
+   * @param {string} dir - Directory to scan.
+   * @param {number} depth - Its depth below `cwd`.
+   * @returns {void}
+   */
+  const walk = (dir, depth) => {
+    if (depth > maxDepth) return;
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (!e.isDirectory() || SKIP.has(e.name)) continue;
+      const sub = join(dir, e.name);
+      const candidate = decisionsPath(sub);
+      if (candidate !== home && existsSync(candidate)) {
+        let rows = 0;
+        try { rows = readFileSync(candidate, "utf8").split("\n").filter((l) => l.trim()).length; } catch { /* unreadable */ }
+        out.push({ path: relative(cwd, candidate).split(sep).join("/"), rows });
+      }
+      walk(sub, depth + 1);
+    }
+  };
+  walk(cwd, 1);
+  return out;
+}
+
 /**
  * Render a StatsReport as a human-readable fixed-width table.
  * @param {object} report - A validated StatsReport (see {@link aggregate}).
@@ -382,6 +425,10 @@ function renderHooks(r) {
     lines.push("", "(zero rows: either no hook has run in this checkout, or the enforcement layer is inert —");
     lines.push(" and that distinction is exactly what this ledger exists to make.)");
   }
+  if (Array.isArray(r.stray_ledgers) && r.stray_ledgers.length) {
+    lines.push("", `stray ledgers: ${r.stray_ledgers.length} decisions.jsonl outside the project root — rows not counted above:`);
+    for (const s of r.stray_ledgers) lines.push(`  ${s.path}  (${s.rows} row(s))`);
+  }
   return lines.join("\n");
 }
 
@@ -403,7 +450,7 @@ export async function cli(rawArgv) {
   if (args.ratchet || args.hooks) {
     const out = {};
     if (args.ratchet) out.ratchet = ratchetReport(readAllTrials(cwd, args.slug ?? null));
-    if (args.hooks) out.hooks = hooksReport(readDecisions(cwd));
+    if (args.hooks) out.hooks = { ...hooksReport(readDecisions(cwd)), stray_ledgers: strayLedgers(cwd) };
     if (format === "table") {
       const parts = [];
       if (out.ratchet) parts.push(renderRatchet(out.ratchet));

package/kernel/reduce/hill.mjs

@@ -9,6 +9,7 @@ import { runArgs } from "../lib/argv.mjs";
 import { scopesDir, hillDir, verdictsDir, resultsDir, discoveryLedger } from "../lib/paths.mjs";
 import { readAllContracts, SCOPE_CONTRACT } from "../lib/contract.mjs";
 import { evalVerdict } from "../probe/eval.mjs";
+import { redBuildRounds } from "../verify/build.mjs";
 
 /**
  * Derive and write the hill phase for all scopes mechanically based on T0, T1, and ledger facts.
@@ -16,7 +17,7 @@ import { evalVerdict } from "../probe/eval.mjs";
  * The derived phase follows these progression rules (facts move dots, not authors):
  * - UPHILL_UNKNOWN: open unknowns > 0 in the ledger for this scope
  * - UPHILL_SOLVED: unknowns 0, no T0-green yet
- * - DOWNHILL_EXECUTION: ≥1 T0-green; T1/seesaw pending
+ * - DOWNHILL_EXECUTION: ≥1 T0-green in a round whose build gate is not red; T1/seesaw pending
  * - FINISHED: T1 PASS ∧ seesaw green
  *
  * @param {string} cwd - The project root directory.
@@ -52,6 +53,15 @@ export function deriveHill(cwd, slug) {
   }
 
   // 2. T0 facts per scope: has it achieved a green overall verdict? was seesaw also green?
+  //
+  // MINUS THE ROUNDS WHOSE BUILD GATE IS RED. A T0 verdict is one scope's fixtures inside its own
+  // substrate; the round build gate (`verify build`) is the feature's build and launch. Measured on
+  // a live run, all fourteen committed shards read DOWNHILL_EXECUTION off T0 verdicts from rounds in
+  // which the app never compiled and never launched — the dashboard showed a feature going downhill
+  // that had not started. A green fixture in a round the gate failed is not evidence the scope
+  // works; it is evidence the fixture does not test the build. No gate artifact at all leaves every
+  // verdict counting exactly as before.
+  const redRounds = redBuildRounds(cwd, slug);
   const t0Facts = {};
   if (existsSync(vDir)) {
     for (const f of readdirSync(vDir)) {
@@ -59,7 +69,7 @@ export function deriveHill(cwd, slug) {
       try {
         const b = JSON.parse(readFileSync(join(vDir, f), "utf8"));
         if (!t0Facts[b.scope_id]) t0Facts[b.scope_id] = { hasGreen: false, seesawGreen: false };
-        if (b.overall === "green") {
+        if (b.overall === "green" && !redRounds.has(Number(b.round))) {
           t0Facts[b.scope_id].hasGreen = true;
           // Read the REAL seesaw result off the verdict artifact (`t0.mjs`'s `writeArtifact()`
           // already persists the full `{ran, pass, scopes_checked, failing}` object), rather than

package/kernel/verify/build.mjs

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+// The round build gate — does the FEATURE build and launch, before the judge is asked about it.
+//
+// WHY A GATE ABOVE T0. A T0 verdict is one scope's fixtures, run inside that scope's substrate, and
+// the fixtures are the scope-architect's to write. Nothing in that layer proves the feature as a
+// whole compiles or starts. Measured on a live mobile run: every one of 30 T0 trials went green on
+// its first try — the fixtures were TypeScript stand-ins, structural greps and a test-suite wrapper
+// that never compiled its sources — while the ledger's own `run_cmd` failed, and once the compiler
+// could actually reach the new files it reported 58 errors. Three rounds of EVAL then graded a
+// blank screen: nothing in the loop had ever installed or launched the app. The hill shards, derived
+// from those T0 verdicts, all read DOWNHILL_EXECUTION.
+//
+// Two lessons, and this gate is both:
+//
+//   1. A green exit code from the build is not proof the feature compiled. Some toolchains compile
+//      only what is reachable from an entry point, so a scope's files can sit outside the compiled
+//      set and the build stays green. The exit code is the necessary half; `build_probe` is where a
+//      project asserts the other half (the artifact covers what the run wrote), in whatever way its
+//      toolchain makes possible.
+//   2. Nothing else in the loop launches the app. `launch_probe` is where a project installs, starts
+//      and asserts a first screen. For the mobile archetype its absence is called out every round,
+//      because "on-device install unverified" was an L0 risk with no owner for three rounds.
+//
+// WHAT RUNS, in order, each stopping the rest on failure: the ledger's `run_cmd` (the build),
+// then the profile's `build_probe`, then its `launch_probe`. All three are commands the tech lead
+// pinned at GATE L0 — this script invents none of them, and a run that declares none of them gets
+// exit 3 and no artifact, which every reader treats as "no gate declared" rather than as green.
+//
+// THE RED GATE IS THE NEXT ROUND'S BUG LIST. `harness compile` reads the latest gate artifact for
+// the previous round and addresses each failing step to the scopes whose substrate contains the
+// files the output names (unowned → every scope, marked), exactly as it does for an EVAL verdict.
+// `reduce hill` reads the same artifact: a T0-green verdict from a round whose gate is red moves no
+// scope downhill. Both are the same file, written once here — zero LLM tokens, same as T0.
+//
+// Usage:
+//   node "${CLAUDE_PLUGIN_ROOT}/kernel/harness.mjs" verify build --slug <slug> --round N [--cwd <dir>]
+//
+// Exit code: 0 = green, 1 = red, 2 = bad argv, 3 = nothing declared (no run_cmd, no probes).
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { runArgs, isMain } from "../lib/argv.mjs";
+import { harnessRun, projectProfile, roundBuildDir, localRoot, runIdFromRoot } from "../lib/paths.mjs";
+import { readContract, readAllContracts, PROJECT_PROFILE, SCOPE_CONTRACT, splitFrontmatter } from "../lib/contract.mjs";
+import { scopesDir } from "../lib/paths.mjs";
+import { digest } from "../probe/digest.mjs";
+
+/** The three steps, in the order they run. */
+export const STEPS = ["run_cmd", "build_probe", "launch_probe"];
+
+/** Archetypes whose product cannot be judged without being launched on a device or simulator. */
+export const LAUNCH_REQUIRED_ARCHETYPES = new Set(["mobile"]);
+
+const TAIL_BYTES = 8 * 1024;
+const tail = (s) => (s || "").length > TAIL_BYTES ? (s || "").slice(-TAIL_BYTES) : (s || "");
+
+/**
+ * The commands this gate runs for a feature, read from the artifacts that declare them.
+ *
+ * `run_cmd` comes from the run ledger's frontmatter (`harness-run.md`, written at GATE L0 and
+ * already what every EVAL order carries); the two probes come from the committed project profile.
+ * Nothing is inferred: an absent field is an absent step.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @returns {{archetype:(string|null), steps:Array<{kind:string, cmd:string}>, warnings:string[]}}
+ *   The declared steps in run order, the profile's archetype, and the warnings a reader should
+ *   see — currently one: a launch-required archetype with no `launch_probe`.
+ */
+export function declaredSteps(cwd, slug) {
+  const warnings = [];
+  let runCmd = null;
+  try {
+    const hr = splitFrontmatter(readFileSync(harnessRun(cwd, slug), "utf8")).meta || {};
+    runCmd = typeof hr.run_cmd === "string" && hr.run_cmd.trim() ? hr.run_cmd.trim() : null;
+  } catch { /* no ledger — no run_cmd */ }
+
+  let profile = null;
+  const pp = projectProfile(cwd, slug);
+  if (existsSync(pp)) profile = readContract(pp, PROJECT_PROFILE)?.contract || null;
+  const archetype = typeof profile?.archetype === "string" ? profile.archetype : null;
+  const pick = (k) => (typeof profile?.[k] === "string" && profile[k].trim() ? profile[k].trim() : null);
+
+  const steps = [];
+  if (runCmd) { steps.push({ kind: "run_cmd", cmd: runCmd }); warnings.push(...fixtureCoverageWarnings(cwd, slug, runCmd)); }
+  else warnings.push("the run ledger declares no run_cmd — the build itself is not part of this gate");
+  const buildProbe = pick("build_probe");
+  if (buildProbe) steps.push({ kind: "build_probe", cmd: buildProbe });
+  const launchProbe = pick("launch_probe");
+  if (launchProbe) steps.push({ kind: "launch_probe", cmd: launchProbe });
+  else if (archetype && LAUNCH_REQUIRED_ARCHETYPES.has(archetype)) {
+    warnings.push(`archetype ${archetype} declares no launch_probe in project-profile.md — nothing in the loop ` +
+      `launches the app, so a blank first screen survives every round. Give the install/launch risk an owner: ` +
+      `a command that installs the built artifact, starts it, asserts the first screen and fails on fatal logs.`);
+  }
+  return { archetype, steps, warnings };
+}
+
+/**
+ * The executable a run command actually invokes — its basename, past any `cd …&&`, `env`, or
+ * `VAR=value` prefix. `cd app && DEVECO_SDK_HOME=/x /tools/hvigor/bin/hvigorw assembleHap` → `hvigorw`.
+ * @param {string} runCmd - The ledger's run command.
+ * @returns {(string|null)} The tool's basename, or null when none can be read.
+ */
+export function buildTool(runCmd) {
+  const segments = String(runCmd || "").split(/&&|;|\|\|/).map((s) => s.trim()).filter(Boolean);
+  for (const seg of segments) {
+    const tokens = seg.split(/\s+/).filter((t) => t && !/^[A-Za-z_][A-Za-z0-9_]*=/.test(t) && t !== "env" && t !== "cd");
+    if (seg.startsWith("cd ")) continue;
+    if (!tokens.length) continue;
+    const base = tokens[0].split(/[\\/]/).pop();
+    if (base) return base;
+  }
+  return null;
+}
+
+/**
+ * Scopes whose fixtures never invoke the build tool `run_cmd` names — ADVISORY.
+ *
+ * A T0 layer can be entirely green on a feature that does not compile when every fixture is a
+ * grep or a stand-in compiler (measured: 13 of 15 fixtures on one run). The harness cannot know
+ * what a project's fixtures should run, but it can see when none of a scope's fixture commands
+ * mention the tool the ledger builds with, and say so beside the gate's verdict. A warning, not a
+ * failure: a library scope with no compiled surface is a legitimate reason for the mismatch.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {(string|null)} runCmd - The ledger's run command.
+ * @returns {string[]} One warning per scope whose fixtures name the tool nowhere.
+ */
+export function fixtureCoverageWarnings(cwd, slug, runCmd) {
+  const tool = buildTool(runCmd);
+  if (!tool) return [];
+  const out = [];
+  let contracts = [];
+  try { contracts = readAllContracts(scopesDir(cwd, slug), SCOPE_CONTRACT).map((x) => x.contract); } catch { return []; }
+  for (const c of contracts) {
+    const fixtures = Array.isArray(c.e2e_verification_fixtures) ? c.e2e_verification_fixtures : [];
+    if (!fixtures.length || fixtures.some((f) => String(f).includes(tool))) continue;
+    out.push(`scope ${c.scope_id}: none of its ${fixtures.length} fixture(s) invoke ${tool} (the ledger's build tool) — ` +
+      `its T0 green is not evidence the scope compiles; only this gate's run_cmd is.`);
+  }
+  return out;
+}
+
+/**
+ * Run one gate command and capture its outcome (10-minute timeout), output tails kept for the digest.
+ * @param {{kind:string, cmd:string}} step - The step to run.
+ * @param {string} cwd - Working directory.
+ * @returns {object} `{kind, cmd, exit, pass, stdout_tail, stderr_tail, error?}`.
+ */
+export function runStep(step, cwd) {
+  const r = spawnSync(step.cmd, { shell: true, cwd, encoding: "utf8", timeout: 10 * 60 * 1000 });
+  const error = r.error ? String(r.error.message || r.error) : null;
+  return {
+    kind: step.kind, cmd: step.cmd,
+    exit: r.status ?? 1, pass: r.status === 0,
+    stdout_tail: tail(r.stdout), stderr_tail: tail(r.stderr),
+    ...(error ? { error } : {}),
+  };
+}
+
+/**
+ * Run the declared steps in order, stopping at the first failure — a probe over a build that did
+ * not complete answers nothing, and would only bury the real error under a second one.
+ *
+ * @param {Array<{kind:string, cmd:string}>} steps - From {@link declaredSteps}.
+ * @param {string} cwd - Working directory.
+ * @returns {{overall:("green"|"red"), steps:Array<object>}} Every declared step, the ones not
+ *   reached marked `skipped: true`.
+ */
+export function runGate(steps, cwd) {
+  const out = [];
+  let failed = false;
+  for (const step of steps) {
+    if (failed) { out.push({ kind: step.kind, cmd: step.cmd, skipped: true }); continue; }
+    const r = runStep(step, cwd);
+    out.push(r);
+    if (!r.pass) failed = true;
+  }
+  return { overall: failed ? "red" : "green", steps: out };
+}
+
+/**
+ * Every gate artifact for a round, oldest first.
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {number} round - Round number.
+ * @returns {Array<{path:string, trial:number, body:object}>} Parsed artifacts; unreadable ones skipped.
+ */
+export function roundBuildArtifacts(cwd, slug, round) {
+  const dir = roundBuildDir(cwd, slug);
+  let files;
+  try { files = readdirSync(dir); } catch { return []; }
+  const out = [];
+  for (const f of files) {
+    const m = f.match(/^r(\d+)-t(\d+)\.json$/);
+    if (!m || Number(m[1]) !== Number(round)) continue;
+    try { out.push({ path: join(dir, f), trial: Number(m[2]), body: JSON.parse(readFileSync(join(dir, f), "utf8")) }); }
+    catch { /* skip */ }
+  }
+  return out.sort((a, b) => a.trial - b.trial);
+}
+
+/**
+ * The gate's latest word on a round — the artifact readers branch on.
+ *
+ * Latest, because the gate may run again after a hand fix between launches, and the run must act on
+ * the current state of the build, not the first one recorded. Every earlier artifact stays on disk.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {number} round - Round number.
+ * @returns {(object|null)} The latest artifact body, or null when the gate never ran for this round.
+ */
+export function latestRoundBuild(cwd, slug, round) {
+  const all = roundBuildArtifacts(cwd, slug, round);
+  return all.length ? all[all.length - 1].body : null;
+}
+
+/**
+ * The rounds whose latest gate artifact is red — the set `reduce hill` subtracts from.
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @returns {Set<number>} Round numbers; empty when the gate never ran (non-regression: every
+ *   T0 verdict then counts exactly as it did before the gate existed).
+ */
+export function redBuildRounds(cwd, slug) {
+  const latest = new Map();
+  let files;
+  try { files = readdirSync(roundBuildDir(cwd, slug)); } catch { return new Set(); }
+  for (const f of files) {
+    const m = f.match(/^r(\d+)-t(\d+)\.json$/);
+    if (!m) continue;
+    const round = Number(m[1]), trial = Number(m[2]);
+    if (!latest.has(round) || latest.get(round).trial < trial) latest.set(round, { trial, file: f });
+  }
+  const red = new Set();
+  for (const [round, { file }] of latest) {
+    try {
+      if (JSON.parse(readFileSync(join(roundBuildDir(cwd, slug), file), "utf8")).overall === "red") red.add(round);
+    } catch { /* unreadable → not proven red */ }
+  }
+  return red;
+}
+
+/**
+ * Write the gate artifact immutably (`wx`, next ordinal on collision — the T0 convention).
+ * @param {string} cwd - Project root.
+ * @param {string} slug - Feature slug.
+ * @param {number} round - Round number.
+ * @param {object} body - Artifact fields.
+ * @returns {{path:string, sha256:string, trial:number}} Where it landed and its digest.
+ */
+export function writeRoundBuild(cwd, slug, round, body) {
+  const dir = roundBuildDir(cwd, slug);
+  mkdirSync(dir, { recursive: true });
+  const existing = roundBuildArtifacts(cwd, slug, round);
+  for (let trial = (existing.length ? existing[existing.length - 1].trial : 0) + 1; ; trial++) {
+    const path = join(dir, `r${round}-t${trial}.json`);
+    const text = JSON.stringify({ schema_version: 1, round, trial, at: new Date().toISOString(), ...body }, null, 2);
+    try {
+      writeFileSync(path, text, { flag: "wx" });
+      return { path, sha256: createHash("sha256").update(text).digest("hex"), trial };
+    } catch (e) { if (e.code !== "EEXIST") throw e; }
+  }
+}
+
+export const ARGV_SPEC = {
+  usage: "harness.mjs verify build --slug <slug> --round <N> [--cwd <dir>]",
+  _: { arity: 0, max: 0, name: "(no positional operands)" },
+  slug: { type: "str", required: true },
+  round: { type: "int", min: 1, required: true },
+  cwd: { type: "path" },
+};
+
+/**
+ * Run the round build gate and write its artifact.
+ *
+ * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
+ * @returns {Promise<void>} Exits 0 green, 1 red, 3 nothing declared, 2 bad argv.
+ */
+export async function cli(rawArgv) {
+  const args = runArgs(ARGV_SPEC, rawArgv);
+  const cwd = resolve(args.cwd || process.cwd());
+  const { slug, round } = args;
+  const { archetype, steps, warnings } = declaredSteps(cwd, slug);
+  for (const w of warnings) console.error(`build-gate: ${w}`);
+
+  if (steps.length === 0) {
+    console.log(JSON.stringify({ round, overall: "skipped", steps: [], warnings,
+      reason: "nothing declared — no run_cmd in the run ledger, no build_probe or launch_probe in project-profile.md" }, null, 2));
+    process.exit(3);
+  }
+
+  const gate = runGate(steps, cwd);
+  const failing = gate.steps.filter((s) => !s.skipped && !s.pass);
+  const discovered = failing.flatMap((s) => digest(`${s.stdout_tail}\n${s.stderr_tail}`));
+  const runId = runIdFromRoot(localRoot(cwd, slug));
+  const { path, sha256, trial } = writeRoundBuild(cwd, slug, round, {
+    ...(runId ? { run_id: runId } : {}),
+    archetype,
+    overall: gate.overall,
+    steps: gate.steps,
+    warnings,
+    discovered_tasks: discovered.slice(0, 16),
+  });
+
+  console.log(JSON.stringify({
+    path, sha256, trial, round, overall: gate.overall, warnings,
+    steps: gate.steps.map((s) => (s.skipped ? { kind: s.kind, skipped: true } : { kind: s.kind, exit: s.exit, pass: s.pass })),
+    ...(failing.length ? { failed_step: failing[0].kind, stderr_tail: failing[0].stderr_tail.slice(-1200) } : {}),
+  }, null, 2));
+  process.exit(gate.overall === "green" ? 0 : 1);
+}
+
+if (isMain(import.meta.url)) cli(process.argv.slice(2));

package/package.json

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