@mutagent/helix 0.1.0-alpha.14

package/mutagent-optimize/.claude/skills/mutagent-optimize/scripts/improve-loop-run.ts

@@ -0,0 +1,304 @@
+/**
+ * scripts/improve-loop-run.ts — the deterministic improve-loop FSM harness.
+ * ---------------------------------------------------------------------------
+ * ⚠️ THIS IS NOT THE INTERACTIVE RUNTIME. The interactive `*optimize` loop is
+ * conducted by the TOP-LEVEL SESSION (Model B) — the session is the only thing
+ * that can Task-dispatch sub-agents, so the SESSION conducts the loop per the
+ * SKILL.md "runtime conduct" procedure, calling the pure decisions one-shot via
+ * `scripts/loop-state-cli.ts` between dispatches. There is deliberately NO
+ * production `CrewBindings` implementation that `await`s Task dispatches (a
+ * sub-agent cannot spawn sub-agents; a TS `while` awaiting dispatches is the wrong
+ * shape for the interactive runtime). See CLAUDE.md "Two runtimes".
+ *
+ * What this file IS — two legitimate NON-interactive uses of the SAME FSM:
+ *   (a) the UNIT-TEST HARNESS — tests drive the ring with a scripted fake crew to
+ *       prove the loop-state decisions end-to-end (tests/improve-loop-run.test.ts).
+ *   (b) a future HEADLESS VERIFICATION driver (Model A / SimuLatte sim-run) — a
+ *       deterministic child-spawn run for CI/regression, NOT a live operator loop.
+ *
+ * INVARIANT (for both uses): the driver is deterministic TypeScript, NEVER an LLM.
+ * LLM work happens only inside the crew, reached through the INJECTED `CrewBindings`
+ * seam. Every time-like input (`now`, `monotonic`) + the crew + the fs writer are
+ * injected, so the same (config, crew, clock) always yields the same trajectory +
+ * terminator. The crew seam is a TEST/verification abstraction — the interactive
+ * "crew binding" is the SKILL.md procedure (an agent action), not a TS object.
+ */
+
+import {
+  ArchitectVerdict,
+  GateVerdict,
+  LoopPhase,
+  Terminator,
+  assertGoalLegal,
+  checkTerminators,
+  initLoopState,
+  recordIteration,
+} from "./loop-state.ts";
+import type {
+  ArchitectVerdictValue,
+  GateVerdictValue,
+  LoopConfig,
+  LoopState,
+  TerminatorValue,
+} from "./loop-state.ts";
+import type { AmendRequest } from "./contracts/amend-request.ts";
+
+/** What one crew phase needs. */
+export interface TurnContext {
+  iteration: number;
+  /** the best (kept) score so far — the crew may use it for the amend brief. */
+  bestScore: number;
+  /** the prior diagnose remedy fed into this Build turn (empty on the first). */
+  remedy: string;
+  /**
+   * Wave-2 W2I2 (unify amend formats) — the OPTIONAL structured amend request that
+   * fed this Build turn, normalized to the unified `AmendRequest` superset. Both the
+   * evaluator (EddChangeRequest) and diagnostics (Remedy) dialects map INTO this one
+   * shape via scripts/contracts/amend-request.ts, so the S1 build handover reads a
+   * single contract regardless of emitter. ADDITIVE: absent on legacy string-only
+   * turns (`remedy` is the collapsed NL brief via `amendToBuildRemedy`), so the FSM
+   * + existing harness tests are unchanged.
+   */
+  amend?: AmendRequest;
+}
+
+/** The evaluator's re-eval outcome for one turn. */
+export interface EvalOutcome {
+  score: number;
+  gate: GateVerdictValue;
+  criteriaPassed: string[];
+  varianceRegressed: boolean;
+  /**
+   * CODE-TARGET (Wave-2 W2I1) — the deterministic test-suite gate for a `code`
+   * subject: `true` iff the subject's OWN test suite ran green this turn. OPTIONAL:
+   * a non-code target omits it (undefined). Under a `code-quality` goal the
+   * BOTH-gate requires this strictly `true` AND `gate === PASS` to converge. In the
+   * interactive runtime this signal originates in S1 (ai-engineer's code-target TDD
+   * inner loop); the crew seam surfaces it here for the non-interactive harness.
+   */
+  testsGreen?: boolean;
+}
+
+/**
+ * The crew seam for the NON-interactive uses only (unit test · future headless
+ * verification). The interactive runtime has NO such TS binding — the session
+ * conducts and Task-dispatches the real sub-agents per SKILL.md. Kept abstract so
+ * the FSM is driveable by a scripted fake crew (no LLM, no sub-agents) in tests,
+ * or by a headless child-spawn binding (Model A / sim-run) for CI regression.
+ */
+export interface CrewBindings {
+  /** S1 — ai-engineer #apply (worktree-scoped WRITE). Returns the applied diff summary. */
+  build(ctx: TurnContext): Promise<{ appliedDiff: string }>;
+  /** S2 — ai-architect PROCEED|STEER|ABORT on the applied change. */
+  verify(ctx: TurnContext): Promise<ArchitectVerdictValue>;
+  /** S3+S4 — evaluator re-eval swing → score + GATE verdict. */
+  evaluate(ctx: TurnContext): Promise<EvalOutcome>;
+  /** S5 — analyzer RCA on the new failures (feeds the next Build). Only on a FAIL gate. */
+  diagnose(ctx: TurnContext): Promise<{ remedy: string }>;
+}
+
+/** Everything injected → determinism (mirrors sim-run.ts RunOptions). */
+export interface RunOptions {
+  runId: string;
+  crew: CrewBindings;
+  /** injected ISO clock (audit stamps). */
+  now: () => string;
+  /** injected monotonic ms (budget accounting) — NOT wall-clock. */
+  monotonic: () => number;
+  /** where loop-state.json + the report are written. */
+  projectRoot: string;
+  /** fs writer seam (tests capture without touching disk). */
+  writeFile: (path: string, contents: string) => void;
+  mkdirp: (path: string) => void;
+  /** wirecard sink (default: console.info via the CLI). */
+  out: (line: string) => void;
+  /** emit the living HTML report. */
+  html?: boolean;
+}
+
+export interface RunResult {
+  state: LoopState;
+  terminator: TerminatorValue;
+  /** the final wirecard (also emitted via opts.out during the run). */
+  wirecard: string;
+  /** the report HTML (present when opts.html). */
+  reportHtml?: string;
+}
+
+const runDir = (projectRoot: string, runId: string): string =>
+  `${projectRoot}/.mutagent/optimize/runs/${runId}`;
+
+/**
+ * Run the bounded improve loop. Deterministic given (config, crew, clock).
+ * Throws (goal-legality) if the config is not bounded.
+ */
+export async function runImproveLoop(config: LoopConfig, opts: RunOptions): Promise<RunResult> {
+  // Refuses an un-yardsticked loop: unbounded config OR an unresolved natural-language
+  // goal (Wave-2 W2I10). A headless run has NO human to confirm-freeze an NL goal, so an
+  // unfrozen NL goal throws here — the driver never runs a free-text goal unbounded (it
+  // must be a structured goal or a pre-frozen NL criterion). See assertGoalLegal.
+  assertGoalLegal(config);
+  const dir = runDir(opts.projectRoot, opts.runId);
+  opts.mkdirp(dir);
+
+  const start = opts.monotonic();
+  let state = initLoopState();
+  let remedy = "";
+  let terminator: TerminatorValue | null = null;
+  let lastVerify: ArchitectVerdictValue = ArchitectVerdict.Proceed;
+
+  // hard iteration ceiling belt-and-suspenders (checkTerminators also enforces it)
+  while (terminator === null && state.iteration < config.maxIters + 1) {
+    const iteration = state.iteration + 1;
+    const ctx: TurnContext = { iteration, bestScore: state.bestScore, remedy };
+
+    // S1 BUILD (ai-engineer #apply, worktree-scoped)
+    await opts.crew.build(ctx);
+
+    // S2 VERIFY (ai-architect)
+    lastVerify = await opts.crew.verify(ctx);
+
+    let evalOut: EvalOutcome;
+    if (lastVerify === ArchitectVerdict.Abort) {
+      // ABORT ends the turn with no eval — record a non-improving turn at the best score.
+      evalOut = { score: state.bestScore === Number.NEGATIVE_INFINITY ? 0 : state.bestScore, gate: GateVerdict.Fail, criteriaPassed: [], varianceRegressed: false };
+    } else if (lastVerify === ArchitectVerdict.Steer) {
+      // STEER — the change needs rework; count a non-improving turn, re-build next iteration.
+      evalOut = { score: state.bestScore === Number.NEGATIVE_INFINITY ? 0 : state.bestScore, gate: GateVerdict.Fail, criteriaPassed: [], varianceRegressed: false };
+    } else {
+      // S3+S4 EVAL + GATE (evaluator re-eval swing)
+      evalOut = await opts.crew.evaluate(ctx);
+    }
+
+    const budgetSpentMs = opts.monotonic() - start;
+    state = recordIteration(state, config, {
+      verify: lastVerify,
+      gate: evalOut.gate,
+      score: evalOut.score,
+      varianceRegressed: evalOut.varianceRegressed,
+      budgetSpentMs,
+      // CODE-TARGET (Wave-2 W2I1) — threaded verbatim (undefined for non-code turns
+      // + for ABORT/STEER turns that never reached eval). The BOTH-gate lives in
+      // loop-state's goalMet(code-quality); the driver only carries the signal.
+      testsGreen: evalOut.testsGreen,
+    });
+
+    // persist the cursor + emit the wirecard every iteration
+    opts.writeFile(`${dir}/loop-state.json`, JSON.stringify(state, null, 2) + "\n");
+    opts.out(renderWirecard(state, config, lastVerify, false));
+
+    terminator = checkTerminators(state, config, lastVerify, new Set(evalOut.criteriaPassed));
+    if (terminator !== null) break;
+
+    // S5 DIAGNOSE — a FAIL gate that is still continuing gets RCA to feed the next Build.
+    if (evalOut.gate === GateVerdict.Fail && lastVerify === ArchitectVerdict.Proceed) {
+      remedy = (await opts.crew.diagnose(ctx)).remedy;
+    } else {
+      remedy = "";
+    }
+  }
+
+  // by construction the loop only exits via a terminator; default to MaxIters.
+  const finalTerminator = terminator ?? Terminator.MaxIters;
+  state = { ...state, terminator: finalTerminator, phase: LoopPhase.Terminal };
+  opts.writeFile(`${runDir(opts.projectRoot, opts.runId)}/loop-state.json`, JSON.stringify(state, null, 2) + "\n");
+
+  const wirecard = renderWirecard(state, config, lastVerify, true);
+  opts.out(wirecard);
+
+  let reportHtml: string | undefined;
+  if (opts.html) {
+    reportHtml = renderReportHtml(state, config, opts.runId, opts.now());
+    opts.writeFile(`${runDir(opts.projectRoot, opts.runId)}/optimize-report.html`, reportHtml);
+  }
+
+  return { state, terminator: finalTerminator, wirecard, reportHtml };
+}
+
+/** The periodic terminal dashboard — iteration · phase · per-gate · Δ · terminator. */
+export function renderWirecard(
+  state: LoopState,
+  config: LoopConfig,
+  lastVerify: ArchitectVerdictValue,
+  terminal: boolean,
+): string {
+  const last = state.history[state.history.length - 1];
+  const lines: string[] = [];
+  lines.push(
+    `┌─ optimize ${terminal ? "· TERMINAL" : ""} ─ iter ${state.iteration}/${config.maxIters} · phase ${state.phase}`,
+  );
+  if (last) {
+    // CODE-TARGET (Wave-2 W2I1) — surface the deterministic test-suite gate ONLY when
+    // it was recorded (a `code` subject turn). Absent ⇒ the line is byte-identical to
+    // pre-W2I1 for every non-code target.
+    const testsCell =
+      last.testsGreen === undefined ? "" : `  ·  tests ${last.testsGreen ? "GREEN" : "red"}`;
+    lines.push(
+      `│  verify ${lastVerify}  ·  gate ${last.gate}${testsCell}  ·  score ${last.score.toFixed(3)}  ·  Δ ${last.delta >= 0 ? "+" : ""}${last.delta.toFixed(3)}  ·  ${last.improved ? "IMPROVED" : "flat"}`,
+    );
+  }
+  lines.push(
+    `│  best ${state.bestScore === Number.NEGATIVE_INFINITY ? "—" : state.bestScore.toFixed(3)}  ·  no-improve ${state.noImprovementCount}/${config.noImprovementStreak}  ·  budget ${Math.round(state.budgetSpentMs)}ms/${config.budgetMs}ms`,
+  );
+  if (terminal && state.terminator) {
+    lines.push(`└─ TERMINATED: ${state.terminator}  (goal: ${goalLabel(config)})`);
+  } else {
+    lines.push(`└─ goal: ${goalLabel(config)}`);
+  }
+  return lines.join("\n");
+}
+
+function goalLabel(config: LoopConfig): string {
+  switch (config.goal.kind) {
+    case "eval-pass":
+      return "eval-pass (GATE PASS)";
+    case "criterion":
+      return `criterion:${config.goal.id}`;
+    case "delta":
+      return `delta:${config.goal.min}`;
+    case "code-quality":
+      return "code-quality (tests-green + quality verdict)";
+    case "nl":
+      // NATURAL-LANGUAGE goal (Wave-2 W2I10). A headless run can only reach here with a
+      // FROZEN NL goal — an unfrozen one is rejected by assertGoalLegal above (no human
+      // to confirm-freeze headless), so the driver refuses rather than run unbounded.
+      return config.goal.resolved
+        ? `nl→criterion:${config.goal.resolved.criterionIds.join(",")} ("${config.goal.text}")`
+        : `nl (UNRESOLVED: "${config.goal.text}")`;
+    default: {
+      const _never: never = config.goal;
+      throw new Error(`unknown goal ${JSON.stringify(_never)}`);
+    }
+  }
+}
+
+/** The living HTML report — per-iteration score trajectory + terminator + Δ. */
+export function renderReportHtml(state: LoopState, config: LoopConfig, runId: string, at: string): string {
+  const rows = state.history
+    .map(
+      (r) =>
+        `<tr><td>${r.iteration}</td><td>${r.verify}</td><td>${r.gate}</td><td>${r.score.toFixed(3)}</td><td>${r.delta >= 0 ? "+" : ""}${r.delta.toFixed(3)}</td><td>${r.improved ? "✓" : "·"}</td></tr>`,
+    )
+    .join("\n");
+  const best = state.bestScore === Number.NEGATIVE_INFINITY ? "—" : state.bestScore.toFixed(3);
+  return `<!doctype html>
+<meta charset="utf-8">
+<title>optimize · ${runId}</title>
+<style>
+  body{font-family:ui-monospace,Menlo,monospace;background:#0b0a12;color:#e9e6f4;margin:0;padding:24px}
+  h1{font-size:18px;color:#a78bfa} .meta{color:#918bab;font-size:12px}
+  table{border-collapse:collapse;margin-top:16px;font-size:13px}
+  th,td{border:1px solid #2b2640;padding:6px 12px;text-align:right}
+  th{background:#15121d;color:#a78bfa} .term{margin-top:14px;color:#4ade80}
+</style>
+<h1>mutagent-optimize · ⑤ IMPROVE loop</h1>
+<div class="meta">run ${runId} · rendered ${at} · goal ${goalLabel(config)} · best ${best}</div>
+<table>
+  <thead><tr><th>iter</th><th>verify</th><th>gate</th><th>score</th><th>Δ</th><th>improved</th></tr></thead>
+  <tbody>
+${rows}
+  </tbody>
+</table>
+<div class="term">TERMINATED: ${state.terminator ?? "—"} · ${state.iteration} iteration(s) · best ${best}</div>
+`;
+}

package/mutagent-optimize/.claude/skills/mutagent-optimize/scripts/loop-state-cli.ts

@@ -0,0 +1,300 @@
+/**
+ * scripts/loop-state-cli.ts — the ONE-SHOT decision CLI for the improve loop.
+ * ---------------------------------------------------------------------------
+ * WHY: the interactive `*optimize` loop is conducted by the TOP-LEVEL SESSION
+ * (only the session can Task-dispatch sub-agents; a sub-agent cannot). The session
+ * is an AGENT, not a TS program — it cannot `import` the pure decision functions
+ * in `loop-state.ts`. This CLI EXPOSES those functions one-shot so the conducting
+ * session can call them BETWEEN Task dispatches (write loop-state.json → shell this
+ * CLI to decide terminator / next phase / improvement → act on the printed result).
+ *
+ * It is PURE: reads state/config from JSON files + flags, prints a machine-readable
+ * result, no clock / no network. `budget-ms` (elapsed wall time) is INJECTED by the
+ * conductor. Mirrors the diagnostics `orchestrator-protocol` inline model: the
+ * session conducts; deterministic decisions are shelled to a script.
+ *
+ *   bun run scripts/loop-state-cli.ts <command> [args]
+ *     init
+ *     assert-goal-legal   <config.json> [--subject-kind <code|agent|skill|platform>]
+ *     parse-goal          <raw>                                   # "<free text>" | eval-pass | criterion:<id> | delta:<n> | code-quality → Goal JSON
+ *     freeze-goal         <config.json> --criterion <id> [--criterion <id> …]   # freeze a natural-language goal → a criterion SET (repeat --criterion, or a comma list "a,b") → updated config JSON
+ *     record-iteration    <state.json> <config.json> --verify <PROCEED|STEER|ABORT> --gate <PASS|FAIL> --score <n> --variance-regressed <true|false> --budget-ms <n> [--tests-green <true|false>]
+ *     check-terminators   <state.json> <config.json> --last-verify <PROCEED|STEER|ABORT> [--criteria a,b]
+ *     next-phase          <phase> [--verify <..>] [--gate <..>]
+ *     is-improvement      --delta <n> --noise-floor <n> --variance-regressed <true|false>
+ *     goal-met            <config.json> <record.json> [--criteria a,b]
+ *     accept-amend        <input.json> --dialect <eval|diagnostics|amend> [--subject <s>] [--brief]
+ */
+
+import { readFileSync } from "node:fs";
+
+import {
+  assertGoalAllowedForSubject,
+  assertGoalLegal,
+  assertSubjectKind,
+  checkTerminators,
+  freezeNlGoal,
+  goalMet,
+  initLoopState,
+  isImprovement,
+  nextPhase,
+  parseGoal,
+  recordIteration,
+} from "./loop-state.ts";
+import type {
+  ArchitectVerdictValue,
+  GateVerdictValue,
+  IterationRecord,
+  LoopConfig,
+  LoopPhaseValue,
+  LoopState,
+} from "./loop-state.ts";
+import {
+  amendToBuildRemedy,
+  eddChangeRequestToAmend,
+  remedyToAmend,
+  validateAmendRequest,
+} from "./contracts/amend-request.ts";
+import type { AmendRequest, EddChangeRequestLike, RemedyLike } from "./contracts/amend-request.ts";
+
+export interface CliResult {
+  out: string;
+  code: number;
+}
+
+interface ParsedArgs {
+  positionals: string[];
+  flags: Record<string, string>;
+  /**
+   * All occurrences of each flag, in order — so a REPEATED flag (e.g. `--criterion a
+   * --criterion b`) is not lost to last-wins. `flags` keeps its last-wins string for the
+   * single-value callers; `lists` is the additive multi-value view (used by freeze-goal).
+   */
+  lists: Record<string, string[]>;
+}
+
+function parseArgs(argv: string[]): ParsedArgs {
+  const positionals: string[] = [];
+  const flags: Record<string, string> = {};
+  const lists: Record<string, string[]> = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i]!;
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      let value: string;
+      if (next === undefined || next.startsWith("--")) {
+        value = "true";
+      } else {
+        value = next;
+        i++;
+      }
+      flags[key] = value;
+      (lists[key] ??= []).push(value);
+    } else {
+      positionals.push(a);
+    }
+  }
+  return { positionals, flags, lists };
+}
+
+function readJson<T>(path: string): T {
+  return JSON.parse(readFileSync(path, "utf-8")) as T;
+}
+
+/**
+ * Revive a LoopState read from JSON. `bestScore`'s "no kept iteration yet" sentinel
+ * is `Number.NEGATIVE_INFINITY`, which `JSON.stringify` writes as `null`; restore it
+ * so recordIteration's first-turn detection holds across the JSON round-trip. Pure
+ * boundary fix — loop-state.ts is unchanged.
+ */
+function readState(path: string): LoopState {
+  const raw = readJson<LoopState & { bestScore: number | null }>(path);
+  return { ...raw, bestScore: raw.bestScore === null ? Number.NEGATIVE_INFINITY : raw.bestScore };
+}
+
+function requireFlag(flags: Record<string, string>, key: string): string {
+  const v = flags[key];
+  if (v === undefined) throw new Error(`missing required flag --${key}`);
+  return v;
+}
+
+function requirePositional(pos: string[], i: number, name: string): string {
+  const v = pos[i];
+  if (v === undefined) throw new Error(`missing required argument <${name}>`);
+  return v;
+}
+
+function parseCriteria(flags: Record<string, string>): Set<string> {
+  const raw = flags["criteria"];
+  return new Set(raw ? raw.split(",").map((s) => s.trim()).filter(Boolean) : []);
+}
+
+const USAGE = [
+  "loop-state-cli — one-shot decisions for the improve loop (the conducting session shells this)",
+  "commands: init · assert-goal-legal · parse-goal · freeze-goal · record-iteration · check-terminators · next-phase · is-improvement · goal-met · accept-amend",
+  "see the file header for exact args.",
+].join("\n");
+
+/**
+ * Run one CLI invocation. PURE w.r.t. the process: returns { out, code } instead
+ * of writing/exiting, so tests call it directly. The import.meta.main shell prints
+ * + exits with the result.
+ */
+export function runLoopStateCli(argv: string[]): CliResult {
+  const [command, ...rest] = argv;
+  const { positionals, flags, lists } = parseArgs(rest);
+
+  try {
+    switch (command) {
+      case undefined:
+      case "--help":
+      case "-h":
+      case "help":
+        return { out: USAGE, code: command === undefined ? 1 : 0 };
+
+      case "init":
+        return { out: JSON.stringify(initLoopState()), code: 0 };
+
+      case "assert-goal-legal": {
+        const config = readJson<LoopConfig>(requirePositional(positionals, 0, "config.json"));
+        try {
+          assertGoalLegal(config);
+          // OPTIONAL subject-kind gate (Wave-2 W2I10): when the caller names the subject
+          // kind, additionally enforce that the goal is applicable to it (e.g. a
+          // `code-quality` goal is illegal on a non-code subject). Folds the subject-kind
+          // → goal disambiguation into the SAME entry gate the session already calls.
+          // VALIDATE the raw flag FIRST (Wave-2 follow-up): a bogus value used to cast
+          // through silently (`as SubjectKind`) and — unless the goal was code-quality —
+          // pass with exit 0. assertSubjectKind rejects an unrecognized value LOUD
+          // (fail-closed) so an invalid `--subject-kind` never slips past.
+          const subjectKind = flags["subject-kind"];
+          if (subjectKind !== undefined) {
+            assertSubjectKind(subjectKind);
+            assertGoalAllowedForSubject(config.goal, subjectKind);
+          }
+          return { out: "ok — goal-legal (observable goal + hard terminators + scope)", code: 0 };
+        } catch (e) {
+          return { out: `ILLEGAL: ${e instanceof Error ? e.message : String(e)}`, code: 1 };
+        }
+      }
+
+      case "parse-goal": {
+        // Parse the `--goal` arg into a Goal (Wave-2 W2I10). Free text → an UNRESOLVED
+        // natural-language goal (illegal until frozen); structured shapes → their kind.
+        const raw = requirePositional(positionals, 0, "raw-goal");
+        return { out: JSON.stringify(parseGoal(raw)), code: 0 };
+      }
+
+      case "freeze-goal": {
+        // Freeze a natural-language goal to a concrete criterion SET (Wave-2 W2I10; OT-4) —
+        // the session INTERPRETS + CONFIRMS the free text (agent reasoning at entry), then
+        // shells this pure transform to record the frozen decision on the config, making it
+        // goal-legal. A real NL goal usually decomposes into MULTIPLE binary criteria, so
+        // this accepts repeated `--criterion` flags AND a comma list ("a,b"); freezeNlGoal
+        // splits + trims. Prints the UPDATED config JSON (overwrite config.json with it).
+        const config = readJson<LoopConfig>(requirePositional(positionals, 0, "config.json"));
+        const criterionIds = lists["criterion"];
+        if (criterionIds === undefined) throw new Error("missing required flag --criterion");
+        const frozen = freezeNlGoal(config.goal, criterionIds);
+        return { out: JSON.stringify({ ...config, goal: frozen }), code: 0 };
+      }
+
+      case "record-iteration": {
+        const state = readState(requirePositional(positionals, 0, "state.json"));
+        const config = readJson<LoopConfig>(requirePositional(positionals, 1, "config.json"));
+        const next = recordIteration(state, config, {
+          verify: requireFlag(flags, "verify") as ArchitectVerdictValue,
+          gate: requireFlag(flags, "gate") as GateVerdictValue,
+          score: Number(requireFlag(flags, "score")),
+          varianceRegressed: requireFlag(flags, "variance-regressed") === "true",
+          budgetSpentMs: Number(requireFlag(flags, "budget-ms")),
+          // CODE-TARGET (Wave-2 W2I1) — OPTIONAL. Present only when the session
+          // conducts a `code` subject round: it records the deterministic
+          // test-suite gate so the `code-quality` goal's BOTH-gate can AND it with
+          // the quality verdict. Absent ⇒ undefined (non-code turn, unchanged).
+          ...(flags["tests-green"] === undefined
+            ? {}
+            : { testsGreen: flags["tests-green"] === "true" }),
+        });
+        return { out: JSON.stringify(next), code: 0 };
+      }
+
+      case "check-terminators": {
+        const state = readState(requirePositional(positionals, 0, "state.json"));
+        const config = readJson<LoopConfig>(requirePositional(positionals, 1, "config.json"));
+        const term = checkTerminators(
+          state,
+          config,
+          requireFlag(flags, "last-verify") as ArchitectVerdictValue,
+          parseCriteria(flags),
+        );
+        // A stop-reason exits NON-ZERO so a shell `if` can branch; "continue" is exit 0.
+        return term === null ? { out: "continue", code: 0 } : { out: term, code: 3 };
+      }
+
+      case "next-phase": {
+        const phase = requirePositional(positionals, 0, "phase") as LoopPhaseValue;
+        const next = nextPhase(
+          phase,
+          flags["verify"] as ArchitectVerdictValue | undefined,
+          flags["gate"] as GateVerdictValue | undefined,
+        );
+        return { out: next, code: 0 };
+      }
+
+      case "is-improvement": {
+        const ok = isImprovement(
+          Number(requireFlag(flags, "delta")),
+          Number(requireFlag(flags, "noise-floor")),
+          requireFlag(flags, "variance-regressed") === "true",
+        );
+        return { out: ok ? "true" : "false", code: ok ? 0 : 1 };
+      }
+
+      case "goal-met": {
+        const config = readJson<LoopConfig>(requirePositional(positionals, 0, "config.json"));
+        const rec = readJson<IterationRecord>(requirePositional(positionals, 1, "record.json"));
+        const ok = goalMet(config.goal, rec, parseCriteria(flags));
+        return { out: ok ? "true" : "false", code: ok ? 0 : 1 };
+      }
+
+      case "accept-amend": {
+        // Wave-2 W2I2 (unify amend formats): the CONSUMER accept-gate. Reads either amend
+        // dialect (or an already-unified amend) and normalizes to the ONE `AmendRequest`
+        // superset the ⑤ IMPROVE S1 build handover reads. --brief prints the collapsed NL
+        // build brief instead of the JSON (what the existing string seam consumes).
+        const inputPath = requirePositional(positionals, 0, "input.json");
+        const dialect = requireFlag(flags, "dialect");
+        let amend: AmendRequest;
+        if (dialect === "eval") {
+          amend = eddChangeRequestToAmend(readJson<EddChangeRequestLike>(inputPath));
+        } else if (dialect === "diagnostics") {
+          const subject = requireFlag(flags, "subject");
+          amend = remedyToAmend(readJson<RemedyLike>(inputPath), subject);
+        } else if (dialect === "amend") {
+          amend = validateAmendRequest(readJson<unknown>(inputPath));
+        } else {
+          return { out: `accept-amend: --dialect must be eval|diagnostics|amend (got "${dialect}")`, code: 2 };
+        }
+        // Belt-and-braces: the normalized amend must itself satisfy the accept-gate.
+        validateAmendRequest(amend);
+        if (flags["brief"] === "true") return { out: amendToBuildRemedy(amend), code: 0 };
+        return { out: JSON.stringify(amend), code: 0 };
+      }
+
+      default:
+        return { out: `unknown command '${command}'\n${USAGE}`, code: 2 };
+    }
+  } catch (e) {
+    return { out: `ERROR: ${e instanceof Error ? e.message : String(e)}`, code: 2 };
+  }
+}
+
+// ── CLI shell (the only impure edge) ──────────────────────────────────────────
+if (import.meta.main) {
+  const result = runLoopStateCli(process.argv.slice(2));
+  if (result.code === 0 || result.code === 3) console.info(result.out);
+  else console.error(result.out);
+  process.exit(result.code);
+}