shapeup-sdlc 3.18.2 → 4.0.0

package/kernel/verify/budget.mjs

@@ -1,153 +0,0 @@
-#!/usr/bin/env node
-// THE THIRD BREAKER — wall clock. Derived, never claimed; checked at every round boundary.
-//
-// WHY THIS EXISTS (and it corrects an earlier diagnosis).
-//
-// A run killed at an external time cap produces nothing scoreable, and the obvious reading is that
-// it stalled at a gate with no human to sign off.
-//
-// Reading the transcript with transcript-level metrics often says otherwise, and not narrowly:
-// steady turns, steady tool calls, steady file writes, gate markers advancing, a low narration
-// ratio and zero stall signals — a run killed mid-loop at GATE L3, Verdict & Loop. It was not
-// waiting. It ran out of clock while genuinely working.
-//
-// That makes the defect specific: **both existing breakers count events, not time.**
-// `round_budget` decrements once per round; `attempt_budget` decrements once per T0 attempt.
-// Neither can observe that round 1 has been running for twenty-nine minutes. A run can burn its
-// entire wall-clock budget without either breaker moving a single tick, and when the harness is
-// killed from outside, it ships nothing — not even the scopes that were already green.
-//
-// So the fix is not more gate automation (there was no stall to automate away). It is a third
-// breaker on the axis nobody was watching:
-//
-//     OUTER    round_budget     — rounds, the six-week-timebox analog
-//     INNER    attempt_budget   — T0 attempts per scope
-//     DEADLINE wall_clock_budget — elapsed seconds, this file
-//
-// Tripping the deadline breaker does NOT kill the run. It routes to GATE H (scope-hammer): the
-// census runs, the cut list is compared against the baseline, and whatever is green ships. That
-// is the entire difference between an external SIGTERM and a circuit breaker — one produces a
-// dash in every column, the other produces a smaller feature that works.
-//
-// Non-regression by construction: with no `wall_clock_budget_s` in the run config this reports
-// `off` and nothing changes. Existing runs behave exactly as before.
-//
-// USAGE
-//   node `harness verify budget` [--slug <slug>] [--cwd <root>] [--at <ISO>]   # status, exit 0
-//   node `harness verify budget` --strict …    # exit 6 when the breaker has tripped
-//
-// Output: { status, elapsed_s, budget_s, remaining_s, used_fraction, action }
-//   status ∈ off | ok | warn | trip
-//   action = the sentence the orchestrator must act on at the round boundary.
-
-import { readFileSync, readdirSync, existsSync } from "node:fs";
-import { join } from "node:path";
-import { runArgs } from "../lib/argv.mjs";
-import { localDir } from "../lib/paths.mjs";
-
-/** Fraction of the budget at which the run should stop STARTING work it cannot finish. */
-export const WARN_AT = 0.75;
-
-/**
- * Decide the breaker state from elapsed time against a budget. Pure, so the structural tests can
- * assert every boundary without waiting for a clock.
- *
- * @param {number} elapsedS - Seconds since the run receipt was written.
- * @param {number|null} budgetS - Configured wall-clock budget, or null/0 when the breaker is off.
- * @returns {{status: string, elapsed_s: number, budget_s: number|null, remaining_s: number|null,
- *            used_fraction: number|null, action: string}}
- */
-export function evaluateBudget(elapsedS, budgetS) {
-  const elapsed = Math.max(0, Math.round(elapsedS));
-  if (!budgetS || budgetS <= 0) {
-    return {
-      status: "off", elapsed_s: elapsed, budget_s: null, remaining_s: null, used_fraction: null,
-      action: "No wall-clock budget configured — the deadline breaker is off. Round and attempt budgets still apply.",
-    };
-  }
-  const remaining = Math.round(budgetS - elapsed);
-  const used = Number((elapsed / budgetS).toFixed(3));
-
-  if (remaining <= 0) {
-    return {
-      status: "trip", elapsed_s: elapsed, budget_s: budgetS, remaining_s: remaining, used_fraction: used,
-      action:
-        "DEADLINE BREAKER TRIPPED. Do not start another build round or another scope. Go straight to " +
-        "GATE H (delegate scope-hammer with --breaker deadline): run the census, compare the shippable " +
-        "subset against the baseline, and ship what is green. A run killed from outside ships nothing; " +
-        "a run that trips its own breaker ships the part that works.",
-    };
-  }
-  if (used >= WARN_AT) {
-    return {
-      status: "warn", elapsed_s: elapsed, budget_s: budgetS, remaining_s: remaining, used_fraction: used,
-      action:
-        `${remaining}s of ${budgetS}s remain (${Math.round(used * 100)}% spent). Finish and T0-verify the ` +
-        "scope in flight; do NOT open a new scope or a new build round. The next boundary is where the " +
-        "breaker trips, and work started now will be cut at GATE H rather than shipped.",
-    };
-  }
-  return {
-    status: "ok", elapsed_s: elapsed, budget_s: budgetS, remaining_s: remaining, used_fraction: used,
-    action: `${remaining}s remain of ${budgetS}s. Proceed.`,
-  };
-}
-
-/** Locate the active run's receipt — the only place `started_at` is recorded. */
-export function findRun(cwd, slug = null) {
-  const root = localDir(cwd);
-  if (!existsSync(root)) return null;
-  if (!slug) {
-    try {
-      const ptr = JSON.parse(readFileSync(join(root, "active-scope"), "utf8"));
-      slug = ptr?.slug || null;
-    } catch { /* no pointer — fall through to a scan */ }
-  }
-  const candidates = slug ? [slug] : (() => { try { return readdirSync(root); } catch { return []; } })();
-  for (const entry of candidates) {
-    const p = join(root, entry, "receipt.json");
-    if (!existsSync(p)) continue;
-    try { return { slug: entry, receipt: JSON.parse(readFileSync(p, "utf8")) }; }
-    catch { /* unreadable receipt is not a run */ }
-  }
-  return null;
-}
-
-/** The typed argv contract (see `./lib/argv.mjs`). */
-export const ARGV_SPEC = {
-  usage: "harness.mjs verify budget [--slug <slug>] [--cwd <dir>] [--at <iso8601>] [--strict]",
-  _: { arity: 0, max: 0, name: "(no positional operands)" },
-  slug: { type: "str" },
-  cwd: { type: "path" },
-  at: { type: "str" },
-  strict: { type: "flag" },
-};
-
-/**
- * Check the wall-clock budget for the open run and report the breaker's verdict.
- *
- * @param {string[]} rawArgv - The subcommand's own arguments (harness.mjs strips the verb words).
- * @returns {(Promise<void>|void)} Settles when the subcommand has written its output; most paths
- *   call `process.exit()` with the subcommand's documented code rather than returning.
- */
-export function cli(rawArgv) {
-  const args = runArgs(ARGV_SPEC, rawArgv);
-  const cwd = args.cwd || process.cwd();
-  const run = findRun(cwd, args.slug ?? null);
-  if (!run) {
-    console.error("no run receipt found — open the run with `harness init run` first (GATE L0.1).");
-    process.exit(2);
-  }
-  const startedAt = Date.parse(run.receipt.started_at || "");
-  if (Number.isNaN(startedAt)) {
-    console.error(`receipt for "${run.slug}" has no parseable started_at — cannot derive elapsed time.`);
-    process.exit(2);
-  }
-  const now = args.at ? Date.parse(args.at) : Date.now();
-  const budget = Number(run.receipt.config?.wall_clock_budget_s || 0) || null;
-  const result = evaluateBudget((now - startedAt) / 1000, budget);
-
-  console.log(JSON.stringify({ slug: run.slug, started_at: run.receipt.started_at, ...result }, null, 2));
-  process.exit(args.strict && result.status === "trip" ? 6 : 0);
-}
-

package/kernel/verify/build.mjs

@@ -1,428 +0,0 @@
-#!/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, readRunId } 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 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.
- * @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(); }
-  // This run's gates only: a prior run's red round over the same slug must not hold this run's dot.
-  const runId = readRunId(cwd, slug);
-  for (const f of files) {
-    const m = f.match(/^r(\d+)-t(\d+)\.json$/);
-    if (!m) continue;
-    if (runId) {
-      try { const g = JSON.parse(readFileSync(join(roundBuildDir(cwd, slug), f), "utf8")); if (g?.run_id && g.run_id !== runId) continue; }
-      catch { 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> | --preflight) [--cwd <dir>]",
-  _: { arity: 0, max: 0, name: "(no positional operands)" },
-  slug: { type: "str", required: true },
-  round: { type: "int", min: 1 },
-  preflight: { type: "flag" },
-  cwd: { type: "path" },
-};
-
-/**
- * Classify a preflight: the declared steps run, nothing is written.
- *
- * WHY A PREFLIGHT, AND WHY IT WRITES NOTHING. Every environment fault a run has died of was
- * discoverable in seconds and discovered after most of an hour: a checkout missing its package
- * install or its local SDK pointer fails the build in about a second, a probe outside the session's
- * grant is refused, a device that is not attached leaves every `[ui]` row ungraded. Each surfaced
- * only at the first round gate, after planning had been paid for. The same commands, run once before
- * anything is dispatched, turn that into one report up front. It is not a round, so it writes no
- * round artifact: a red preflight read back as round 0's gate would reach round 1's orders as bugs,
- * handing a feature worker an environment fault it cannot fix.
- *
- * A step that exits 2 is a probe that COULD NOT RUN — the fixture convention, e.g. no device
- * attached — which is a gap in the environment rather than a red build, and is reported apart.
- *
- * @param {{overall:string, steps:Array<{kind:string, exit?:number, pass?:boolean, skipped?:boolean}>}} gate
- *   What {@link runGate} returned.
- * @returns {{status:("green"|"red"|"cannot-run"), failed_step:(string|null)}} `cannot-run` when the
- *   first failing step exited 2.
- */
-export function classifyPreflight(gate) {
-  const failing = gate.steps.find((s) => !s.skipped && !s.pass);
-  if (!failing) return { status: "green", failed_step: null };
-  return { status: failing.exit === 2 ? "cannot-run" : "red", failed_step: failing.kind };
-}
-
-/**
- * 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;
-  if (Boolean(args.preflight) === (round != null)) {
-    console.error("verify build: pass exactly one of --round <N> (the round gate, writes its artifact) or --preflight (runs the same steps, writes nothing)");
-    process.exit(2);
-  }
-  const { archetype, steps, warnings } = declaredSteps(cwd, slug);
-  for (const w of warnings) console.error(`build-gate: ${w}`);
-
-  if (args.preflight) {
-    if (steps.length === 0) {
-      console.log(JSON.stringify({ preflight: true, status: "undeclared", steps: [], warnings }, null, 2));
-      process.exit(3);
-    }
-    const gate = runGate(steps, cwd);
-    const { status, failed_step } = classifyPreflight(gate);
-    const failing = gate.steps.find((s) => s.kind === failed_step);
-    console.log(JSON.stringify({
-      preflight: true, status, archetype, warnings,
-      steps: gate.steps.map((s) => (s.skipped ? { kind: s.kind, skipped: true } : { kind: s.kind, exit: s.exit, pass: s.pass })),
-      ...(failing ? { failed_step, stderr_tail: `${failing.stdout_tail || ""}\n${failing.stderr_tail || ""}`.trim().slice(-1200) } : {}),
-    }, null, 2));
-    process.exit(status === "green" ? 0 : status === "cannot-run" ? 4 : 1);
-  }
-
-  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));