@mutagent/helix 0.1.0-alpha.14

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

@@ -0,0 +1,440 @@
+// ---------------------------------------------------------------------------
+// mutagent-optimize — the improve-loop STATE MODEL (the deterministic core the
+// improve-loop-run.ts driver advances). Pure data + pure transitions: no clock,
+// no random, no IO — every time-like input (elapsed budget, iteration) is passed
+// IN, so the same (state, inputs) always yields the same next state + terminator.
+//
+// The loop is a BOUNDED, goal-legal FSM (Build → Verify → Eval → Gate →
+// [Diagnose ↺]). It may only run if it declares an observable goal + hard
+// termination gates (max-iters · wallclock budget · no-improvement) — else it
+// refuses (see assertGoalLegal). An iteration counts as improvement ONLY on a
+// strict, above-noise gain that does not regress variance (the variance-gate).
+// ---------------------------------------------------------------------------
+
+/** The FSM phases — S0..S5 + the terminal state. */
+export const LoopPhase = {
+  Init: "S0-init",
+  Build: "S1-build", // ai-engineer #apply — WRITE (worktree-scoped)
+  Verify: "S2-verify", // ai-architect PROCEED|STEER|ABORT
+  Eval: "S3-eval", // evaluator re-eval swing — JUDGE
+  Gate: "S4-gate", // GATE verdict PASS/FAIL
+  Diagnose: "S5-diagnose", // analyzer RCA on new failures → back to S1
+  Terminal: "terminal",
+} as const;
+export type LoopPhaseValue = (typeof LoopPhase)[keyof typeof LoopPhase];
+
+/** How a bounded loop legally STOPS (goal-legal terminators). */
+export const Terminator = {
+  /** the observable goal was met (eval-pass · criterion · delta) */
+  Converged: "converged",
+  /** the eval delta flat-lined below the noise floor for N turns */
+  NoImprovement: "no-improvement",
+  /** hit the max-iters ceiling */
+  MaxIters: "max-iters",
+  /** hit the wallclock budget */
+  Budget: "budget",
+  /** ai-architect returned ABORT on an applied remedy */
+  Aborted: "aborted",
+} as const;
+export type TerminatorValue = (typeof Terminator)[keyof typeof Terminator];
+
+/** The observable goal a loop must declare to run at all. */
+export type Goal =
+  | { kind: "eval-pass" } // GATE = PASS (0 critical/high fail)
+  | { kind: "criterion"; id: string } // a named criterion flips to pass
+  | { kind: "delta"; min: number } // eval score improves by ≥ min
+  // CODE-TARGET (Wave-2 W2I1). Converged = BOTH a hard deterministic gate (the code
+  // subject's OWN test suite is green, `IterationRecord.testsGreen === true`) AND the
+  // code-quality evaluator verdict passes (`gate === PASS`). NEITHER alone converges:
+  // a green test suite with a failing quality verdict keeps looping, and a passing
+  // quality verdict on a red test suite keeps looping. The session supplies both
+  // signals per round (S1 build → test-green; S3/S4 → the quality gate) — see the
+  // mutagent-optimize SKILL §2·5 code-target conduct branch.
+  | { kind: "code-quality" }
+  // NATURAL-LANGUAGE goal (Wave-2 W2I10; OT-4 widened to a criterion SET). A free-text
+  // goal the operator typed (`*optimize <subject> --goal "<free text>"`). It carries the
+  // raw `text` for provenance/audit, and is ILLEGAL until it is FROZEN — the loop needs an
+  // OBSERVABLE, unchanging yardstick, so a free-text intent is not runnable on its own
+  // (assertGoalLegal rejects `resolved === undefined` / an empty set, exactly as it rejects
+  // an unbounded config). The INTERPRETATION of the text is AGENT reasoning done by the
+  // top-level session at loop entry (interpret → confirm-once → freeze; SKILL §2·5), NOT a
+  // code loop — a real NL intent usually decomposes into a COMPOSITION of binary criteria /
+  // measurable-metric criteria, so the frozen form is a SET `resolved.criterionIds[]` (a
+  // single-criterion intent is just a 1-element set). Once frozen, those ids name the
+  // concrete criteria the loop runs against, and `goalMet` treats it like an AND of
+  // `criterion` goals — met only when ALL listed ids pass (each a strict binary check).
+  // A headless run (no human to confirm-freeze) therefore refuses at the goal-legal
+  // gate — an unfrozen NL goal never runs unbounded.
+  | { kind: "nl"; text: string; resolved?: { criterionIds: string[] } };
+
+/**
+ * The subject a loop is optimizing, by KIND (Wave-2 W2I10). Governs which goals are
+ * even applicable — see `assertGoalAllowedForSubject`:
+ *   - `code`     — actual source: the ONLY kind with a test suite + code to gate, so
+ *                  the `code-quality` BOTH-gate applies here and ONLY here.
+ *   - `agent`    — a markdown / platform agent (Claude Code `.md`, Codex, prompt-defined):
+ *                  evals only; there is no code to test, so `code-quality` NEVER fires.
+ *   - `skill`    — a prompt/markdown-defined skill: evals only (same reason as `agent`).
+ *   - `platform` — a hosted/reconstruct-spec subject (non-code markdown): evals only.
+ * The `code-quality` NAME is retained deliberately (operator-confirmed): it is accurate
+ * precisely because it applies only to real code.
+ *
+ * `SUBJECT_KINDS` is the SINGLE SOURCE OF TRUTH for the legal values — the `SubjectKind`
+ * type is derived from it, and `assertSubjectKind` validates raw CLI input against it (so a
+ * bogus `--subject-kind` fails LOUD instead of casting through silently). This is the
+ * optimize-loop goal-legality vocabulary: the inter-stage handover / config `TargetSubject`
+ * canon is the narrower `agent | skill | code`; `platform` is optimize-only (an evals-only
+ * non-code subject, same goal-class as agent/skill — it just never has a code test suite).
+ */
+export const SUBJECT_KINDS = ["code", "agent", "skill", "platform"] as const;
+export type SubjectKind = (typeof SUBJECT_KINDS)[number];
+
+/** Type-guard: is `v` a recognized SubjectKind? */
+export function isSubjectKind(v: string): v is SubjectKind {
+  return (SUBJECT_KINDS as readonly string[]).includes(v);
+}
+
+/**
+ * Assert `v` is a recognized SubjectKind — throws (fail-closed) on an unrecognized value so a
+ * bogus `--subject-kind` is rejected loudly rather than silently accepted. Used by the CLI
+ * `assert-goal-legal --subject-kind` path.
+ */
+export function assertSubjectKind(v: string): asserts v is SubjectKind {
+  if (!isSubjectKind(v)) {
+    throw new Error(
+      `unknown subject-kind '${v}' — expected one of: ${SUBJECT_KINDS.join(" · ")}`,
+    );
+  }
+}
+
+/** The loop's hard bounds + variance policy (the termination contract). */
+export interface LoopConfig {
+  goal: Goal;
+  maxIters: number;
+  budgetMs: number;
+  /** consecutive non-improving turns before a no-improvement stop. */
+  noImprovementStreak: number;
+  /** the calibrated noise floor a delta must clear to count as improvement. */
+  noiseFloor: number;
+  /**
+   * The subject KIND the loop is optimizing (OPTIONAL). When present, `assertGoalLegal`
+   * additionally enforces the subject-kind → goal legality (e.g. a `code-quality` goal is
+   * illegal on a non-code subject) — so a HEADLESS `runImproveLoop` enforces the same guard
+   * the interactive CLI enforces via its `--subject-kind` flag, without the flag. ADDITIVE:
+   * absent ⇒ the loop skips the subject-kind gate (pre-existing behavior, unchanged).
+   */
+  subjectKind?: SubjectKind;
+}
+
+/** The ai-architect verdict on an applied remedy. */
+export const ArchitectVerdict = {
+  Proceed: "PROCEED",
+  Steer: "STEER",
+  Abort: "ABORT",
+} as const;
+export type ArchitectVerdictValue =
+  (typeof ArchitectVerdict)[keyof typeof ArchitectVerdict];
+
+/** The GATE verdict from the re-eval. */
+export const GateVerdict = { Pass: "PASS", Fail: "FAIL" } as const;
+export type GateVerdictValue = (typeof GateVerdict)[keyof typeof GateVerdict];
+
+/** One iteration's recorded outcome (persisted in loop-state.json). */
+export interface IterationRecord {
+  iteration: number;
+  verify: ArchitectVerdictValue;
+  gate: GateVerdictValue;
+  /** the eval score this turn (higher = better). */
+  score: number;
+  /** delta vs the previous kept score. */
+  delta: number;
+  /** whether this turn counted as an above-noise, variance-safe improvement. */
+  improved: boolean;
+  /**
+   * CODE-TARGET (Wave-2 W2I1) — the hard deterministic test-suite gate result for
+   * a `code` subject this turn: `true` iff the subject's OWN test suite ran green.
+   * OPTIONAL + additive: undefined for non-code targets (they omit it, unchanged).
+   * The `code-quality` goal requires this to be strictly `true` (an undefined /
+   * absent signal never converges — safe default). It is a SEPARATE axis from
+   * `gate` (the quality verdict) so both signals stay first-class + auditable in
+   * loop-state.json; `goalMet` does the AND.
+   */
+  testsGreen?: boolean;
+}
+
+/** The loop-state.json cursor. */
+export interface LoopState {
+  iteration: number;
+  phase: LoopPhaseValue;
+  /** the score of the last KEPT (improving) iteration — the convergence anchor. */
+  bestScore: number;
+  /** running count of consecutive non-improving turns. */
+  noImprovementCount: number;
+  /** cumulative wallclock spent (ms), injected by the driver. */
+  budgetSpentMs: number;
+  history: IterationRecord[];
+  terminator: TerminatorValue | null;
+}
+
+/** A loop is illegal (refuses to start) unless it declares real bounds. */
+export function assertGoalLegal(config: LoopConfig): void {
+  const problems: string[] = [];
+  if (!config.goal) problems.push("no observable goal declared");
+  if (!(config.maxIters > 0)) problems.push("maxIters must be > 0");
+  if (!(config.budgetMs > 0)) problems.push("budgetMs must be > 0");
+  if (!(config.noImprovementStreak > 0)) problems.push("noImprovementStreak must be > 0");
+  if (config.noiseFloor < 0) problems.push("noiseFloor must be >= 0");
+  // NATURAL-LANGUAGE goal (Wave-2 W2I10): an UNRESOLVED NL goal is NOT an observable,
+  // bounded yardstick — it is a free-text intent, not yet a measurable criterion. It is
+  // illegal exactly like an unbounded config, so the loop (interactive OR headless)
+  // refuses to run it. A headless run has no human to confirm-freeze, so this gate is
+  // precisely what makes it fall back / refuse rather than spin on an un-yardsticked goal.
+  if (
+    config.goal &&
+    config.goal.kind === "nl" &&
+    (config.goal.resolved === undefined || config.goal.resolved.criterionIds.length === 0)
+  ) {
+    problems.push(
+      'natural-language goal is unresolved — freeze it to a measurable criterion set first ' +
+        '(interpret → confirm-once → freeze; SKILL §2·5). A free-text goal is not a runnable yardstick.',
+    );
+  }
+  if (problems.length > 0) {
+    throw new Error(`optimize loop is not goal-legal — refusing to run: ${problems.join("; ")}`);
+  }
+  // SUBJECT-KIND gate (Wave-2 follow-up): when the config names the subject kind, enforce
+  // that the goal is applicable to it (a `code-quality` goal is illegal on a non-code
+  // subject). Folding this into assertGoalLegal — the ONE gate both the interactive CLI and
+  // the headless `runImproveLoop` already call — is what lets a HEADLESS run enforce the
+  // guard (no `--subject-kind` flag to pass). Throws with assertGoalAllowedForSubject's own
+  // clear message. Absent subjectKind ⇒ skipped (unchanged).
+  if (config.subjectKind !== undefined) {
+    assertGoalAllowedForSubject(config.goal, config.subjectKind);
+  }
+}
+
+/**
+ * SUBJECT-KIND → GOAL legality (Wave-2 W2I10). The `code-quality` BOTH-gate is only
+ * meaningful for a `code` subject (it ANDs a real test suite with a quality verdict);
+ * a non-code subject (agent · skill · platform) has no code to test, so `code-quality`
+ * NEVER fires there — it must use an eval-based goal (`eval-pass` · `criterion` · `delta`
+ * · a frozen NL criterion). All eval-based goals are valid for ANY subject-kind (code
+ * included), so this gate constrains ONLY `code-quality`. Throws with a clear message.
+ */
+export function assertGoalAllowedForSubject(goal: Goal, subjectKind: SubjectKind): void {
+  if (goal.kind === "code-quality" && subjectKind !== "code") {
+    throw new Error(
+      `goal 'code-quality' is only valid for a 'code' subject — a '${subjectKind}' subject has ` +
+        'no test suite / code to gate; use an eval-based goal (eval-pass · criterion · delta · a frozen NL criterion)',
+    );
+  }
+}
+
+/**
+ * Parse the `--goal` argument (Wave-2 W2I10) into a `Goal`. Recognizes the four
+ * STRUCTURED shapes and treats anything else as a NATURAL-LANGUAGE goal (free text) —
+ * the catch-all is deliberate: an NL goal is illegal until frozen (see assertGoalLegal),
+ * so a typo'd structured goal cannot silently run; it surfaces at the confirm-freeze step.
+ *   eval-pass | code-quality | criterion:<id> | delta:<n> | "<any free text>"
+ * PURE: no IO, no clock. Throws (fail-loud) on a malformed structured shape or empty input.
+ */
+export function parseGoal(raw: string): Goal {
+  const s = raw.trim();
+  if (!s) throw new Error("goal is empty — pass eval-pass · criterion:<id> · delta:<n> · code-quality · a free-text goal");
+  if (s === "eval-pass") return { kind: "eval-pass" };
+  if (s === "code-quality") return { kind: "code-quality" };
+  if (s.startsWith("criterion:")) {
+    const id = s.slice("criterion:".length).trim();
+    if (!id) throw new Error('criterion goal needs an id — "criterion:<id>"');
+    return { kind: "criterion", id };
+  }
+  if (s.startsWith("delta:")) {
+    // Guard the EMPTY payload FIRST: `Number("") === 0` (and `Number.isFinite(0) === true`),
+    // so without this an empty `delta:` would silently parse to `{kind:"delta",min:0}` — a
+    // min of 0 converges on ANY above-noise gain, which is not what an operator who typed a
+    // bare `delta:` meant. Fail loud instead (a missing threshold is a malformed goal).
+    const payload = s.slice("delta:".length).trim();
+    if (!payload) throw new Error('delta goal needs a number — "delta:<n>" (got an empty payload)');
+    const min = Number(payload);
+    if (!Number.isFinite(min)) throw new Error('delta goal needs a finite number — "delta:<n>"');
+    return { kind: "delta", min };
+  }
+  // Everything else is a free-text (natural-language) goal — UNRESOLVED until frozen.
+  return { kind: "nl", text: s };
+}
+
+/**
+ * FREEZE a natural-language goal (Wave-2 W2I10; OT-4 widened to a criterion SET) to a
+ * concrete, measurable criterion COMPOSITION — the step that makes it goal-legal. The
+ * session INTERPRETS the free text into one or more binary / measurable-metric criteria
+ * (agent reasoning at entry) and CONFIRMS once with the operator; this pure transform
+ * records that frozen decision on the goal (keeping the original `text` for audit). After
+ * freezing, `goalMet` runs it as an AND of `criterion` goals — met only when ALL listed
+ * ids pass. Accepts either a single id (a 1-element set — back-compat) or a list, and
+ * splits comma-separated ids so the CLI can pass `--criterion a,b`. Throws if the goal is
+ * not an NL goal, or if no criterion id is supplied.
+ */
+export function freezeNlGoal(goal: Goal, criterionIds: string | string[]): Goal {
+  if (goal.kind !== "nl") {
+    throw new Error(`freezeNlGoal: goal is '${goal.kind}', not a natural-language goal — nothing to freeze`);
+  }
+  const ids = (Array.isArray(criterionIds) ? criterionIds : [criterionIds])
+    .flatMap((c) => c.split(","))
+    .map((s) => s.trim())
+    .filter(Boolean);
+  if (ids.length === 0) throw new Error("freezeNlGoal: a criterion id is required to freeze the NL goal");
+  return { kind: "nl", text: goal.text, resolved: { criterionIds: ids } };
+}
+
+/** The variance-gate: an above-noise gain that does NOT regress variance. */
+export function isImprovement(delta: number, noiseFloor: number, varianceRegressed: boolean): boolean {
+  return delta > noiseFloor && !varianceRegressed;
+}
+
+/** Whether the observable goal is met this turn. */
+export function goalMet(goal: Goal, rec: IterationRecord, criteriaPassed: Set<string>): boolean {
+  switch (goal.kind) {
+    case "eval-pass":
+      return rec.gate === GateVerdict.Pass;
+    case "criterion":
+      return criteriaPassed.has(goal.id);
+    case "delta":
+      return rec.improved && rec.delta >= goal.min;
+    case "code-quality":
+      // BOTH-gate (Wave-2 W2I1): test-green AND quality-verdict PASS. `=== true`
+      // makes an undefined/absent test signal fail-safe (never a false converge).
+      return rec.testsGreen === true && rec.gate === GateVerdict.Pass;
+    case "nl":
+      // NATURAL-LANGUAGE goal (Wave-2 W2I10; OT-4 widened to a criterion SET). Only a
+      // FROZEN NL goal is ever met — an unresolved / empty-set one can't reach here
+      // (assertGoalLegal refuses to run it), and if it somehow does, it is never met
+      // (fail-safe: the empty-set guard stops `[].every` from vacuously converging).
+      // Frozen ⇒ an AND of `criterion` goals: met only when EVERY resolved id is in the
+      // passed set (each id is a strict binary check / measurable-metric criterion).
+      return (
+        goal.resolved !== undefined &&
+        goal.resolved.criterionIds.length > 0 &&
+        goal.resolved.criterionIds.every((id) => criteriaPassed.has(id))
+      );
+    default: {
+      const _never: never = goal;
+      throw new Error(`unknown goal kind ${JSON.stringify(_never)}`);
+    }
+  }
+}
+
+/**
+ * Compute the terminator (or null to continue) AFTER an iteration is recorded.
+ * Ordering is deliberate: an ABORT halts immediately; then goal (success) wins
+ * over the bounded stops so a converging final turn is reported as Converged.
+ */
+export function checkTerminators(
+  state: LoopState,
+  config: LoopConfig,
+  lastVerify: ArchitectVerdictValue,
+  criteriaPassed: Set<string>,
+): TerminatorValue | null {
+  const last = state.history[state.history.length - 1];
+  if (lastVerify === ArchitectVerdict.Abort) return Terminator.Aborted;
+  if (last && goalMet(config.goal, last, criteriaPassed)) return Terminator.Converged;
+  if (state.noImprovementCount >= config.noImprovementStreak) return Terminator.NoImprovement;
+  if (state.iteration >= config.maxIters) return Terminator.MaxIters;
+  if (state.budgetSpentMs >= config.budgetMs) return Terminator.Budget;
+  return null;
+}
+
+/** The next phase from the current one given the two in-loop gate results. */
+export function nextPhase(
+  phase: LoopPhaseValue,
+  verify?: ArchitectVerdictValue,
+  gate?: GateVerdictValue,
+): LoopPhaseValue {
+  switch (phase) {
+    case LoopPhase.Init:
+      return LoopPhase.Build;
+    case LoopPhase.Build:
+      return LoopPhase.Verify;
+    case LoopPhase.Verify:
+      // ABORT ends the turn; STEER re-builds; PROCEED advances to eval.
+      if (verify === ArchitectVerdict.Abort) return LoopPhase.Terminal;
+      if (verify === ArchitectVerdict.Steer) return LoopPhase.Build;
+      return LoopPhase.Eval;
+    case LoopPhase.Eval:
+      return LoopPhase.Gate;
+    case LoopPhase.Gate:
+      // PASS → the turn may converge (driver checks terminators); FAIL → diagnose.
+      return gate === GateVerdict.Pass ? LoopPhase.Terminal : LoopPhase.Diagnose;
+    case LoopPhase.Diagnose:
+      return LoopPhase.Build; // RCA remedy → next Build turn
+    case LoopPhase.Terminal:
+      return LoopPhase.Terminal;
+    default: {
+      const _never: never = phase;
+      throw new Error(`unknown phase ${JSON.stringify(_never)}`);
+    }
+  }
+}
+
+/** A fresh loop-state cursor. */
+export function initLoopState(): LoopState {
+  return {
+    iteration: 0,
+    phase: LoopPhase.Init,
+    bestScore: Number.NEGATIVE_INFINITY,
+    noImprovementCount: 0,
+    budgetSpentMs: 0,
+    history: [],
+    terminator: null,
+  };
+}
+
+/**
+ * Record one completed iteration into the cursor (pure — returns a new state).
+ * Applies the variance-gate to decide improvement + advance/reset the streak.
+ */
+export function recordIteration(
+  state: LoopState,
+  config: LoopConfig,
+  input: {
+    verify: ArchitectVerdictValue;
+    gate: GateVerdictValue;
+    score: number;
+    varianceRegressed: boolean;
+    budgetSpentMs: number;
+    /**
+     * CODE-TARGET (Wave-2 W2I1) — the deterministic test-suite gate for a `code`
+     * subject this turn. OPTIONAL: omit for non-code targets (recorded as
+     * undefined, no behavior change). Threaded verbatim into the record so the
+     * `code-quality` goal's BOTH-gate can AND it with the quality verdict.
+     */
+    testsGreen?: boolean;
+  },
+): LoopState {
+  const iteration = state.iteration + 1;
+  const prevBest = state.bestScore;
+  const delta = prevBest === Number.NEGATIVE_INFINITY ? input.score : input.score - prevBest;
+  const improved =
+    prevBest === Number.NEGATIVE_INFINITY
+      ? input.score > config.noiseFloor // first turn: any real signal
+      : isImprovement(delta, config.noiseFloor, input.varianceRegressed);
+  const rec: IterationRecord = {
+    iteration,
+    verify: input.verify,
+    gate: input.gate,
+    score: input.score,
+    delta,
+    improved,
+    // Only stamp the field when the session supplied it — a non-code turn keeps the
+    // record shape identical to pre-W2I1 (no `testsGreen` key ⇒ byte-identical).
+    ...(input.testsGreen === undefined ? {} : { testsGreen: input.testsGreen }),
+  };
+  return {
+    iteration,
+    phase: LoopPhase.Gate,
+    bestScore: improved ? input.score : prevBest,
+    noImprovementCount: improved ? 0 : state.noImprovementCount + 1,
+    budgetSpentMs: input.budgetSpentMs,
+    history: [...state.history, rec],
+    terminator: null,
+  };
+}

package/mutagent-optimize/CLAUDE.md

@@ -0,0 +1,49 @@
+# mutagent-optimize/ — skill navigation map
+
+> Lean map of THIS skill's internals. Repo-wide conventions live in `../CLAUDE.md`.
+> **DESIGN / scaffolded** — the loop-state FSM + the shared apply transport landed; the
+> improve-loop driver + crew wiring are the remaining build. Not yet tagged `optimize-v*`.
+
+**What it is:** the ADL ⑤ IMPROVE stage — the closed, bounded eval-driven optimize loop.
+A sub-orchestration skill: the parent owns the loop FSM + gates and dispatches a borrowed
+crew (ai-engineer · ai-architect · evaluator · diagnostics-analyzer). Writes nothing itself.
+
+## Layout
+
+```
+.claude/skills/mutagent-optimize/
+  SKILL.md                     the stage contract — ONE command *optimize; §2·5 = the runtime conduct procedure
+  .meta/
+    design-principles.md       OP-PR-001..004 (the constitution)
+    prd.yaml                   goals · key_problems · design_choices · verification · REQ registry
+  scripts/
+    loop-state.ts              the PURE FSM decision model (bounded · goal-legal · variance-aware)
+    loop-state-cli.ts          one-shot CLI over loop-state.ts — the conducting SESSION shells this between Task dispatches
+    improve-loop-run.ts        the unit-test harness + future HEADLESS verification driver (NOT the interactive runtime)
+  tests/
+    loop-state.test.ts         the FSM unit suite
+    loop-state-cli.test.ts     the decision-CLI suite
+    improve-loop-run.test.ts   the harness suite
+```
+
+## Two runtimes — do NOT conflate (the load-bearing distinction)
+
+The same FSM (`loop-state.ts`) is driven two ways:
+
+- **Model B · INTERACTIVE `*optimize` (the operator runtime).** The TOP-LEVEL SESSION conducts
+  the loop (only the session can Task-dispatch sub-agents — a sub-agent can't; a TS `while`
+  awaiting dispatches is the wrong shape). The session follows **SKILL.md §2·5**: confirm once →
+  per round Task-dispatch ai-engineer → ai-architect → evaluator, then shell `loop-state-cli.ts`
+  to record + decide (terminator / next-phase), and on a terminator raise the single apply-gate.
+  There is deliberately **no** production `CrewBindings` object — the "crew binding" IS the §2·5
+  procedure. This mirrors diagnostics running its `orchestrator-protocol` inline in the parent.
+- **Model A · HEADLESS verification (`improve-loop-run.ts`).** A deterministic child-spawn driver
+  for unit tests + future SimuLatte/CI regression — NOT a live operator loop. The injected
+  `CrewBindings` seam is a TEST/verification abstraction only.
+
+## Boundaries
+
+- **Apply is a call OUT** to the shared `mutagent-cli apply` (`@mutagent/tools`) — NOT a
+  subcommand. optimize gates the human decision at the skill layer, then shells the transport.
+- **Delegation** — WRITE → ② builder (ai-engineer) · JUDGE → ③ evaluator · RCA → ④ diagnostics.
+- **Sealed-sibling** — the borrowed crew arrives via a Helix HandoverBundle; no source imports.

package/mutagent-optimize/README.md

@@ -0,0 +1,26 @@
+# @mutagent/optimize
+
+The **ADL ⑤ IMPROVE** stage — the closed, bounded, eval-driven optimize loop
+(`Build → Eval → Diagnose → Improve ↻`).
+
+One command, `*optimize`: confirm once at entry → run the bounded auto-loop →
+one human apply-gate at convergence. It is a sub-orchestration skill — the parent
+session owns the loop FSM + gates and dispatches a **borrowed** crew (ai-engineer
+WRITE · ai-architect VERIFY · evaluator JUDGE · diagnostics-analyzer RCA). It writes
+nothing itself: the WRITE delegates to ② builder, the JUDGE to ③ evaluator, the RCA
+to ④ diagnostics, and the TRANSPORT to the shared `mutagent-cli apply` service.
+
+```
+*optimize <subject> [--goal eval-pass|criterion:<id>|delta:<n>] [--max-iters N] [--budget 30m] [--dry-run] [--html]
+```
+
+- **Bounded + goal-legal** — the loop refuses to run without an observable goal + hard
+  gates (max-iters · budget · no-improvement). Variance-gate: only an above-noise,
+  variance-safe gain counts as improvement.
+- **Apply is a call OUT** — at the promotion gate optimize collects the human approval,
+  then shells `mutagent-cli apply --dry-run` → `--commit` (the CLI holds no approval
+  logic; every commit emits an apply-audit). Non-destructive + revertible.
+- **One owner** — `*improve` resolves here; it replaces the prior three surfaces
+  (builder route · diagnostics apply-worker · evaluator EDD mode).
+
+See `.claude/skills/mutagent-optimize/SKILL.md` for the full contract.

package/mutagent-orchestrator/CLAUDE.md

@@ -0,0 +1,102 @@
+# mutagent-orchestrator/
+
+> **Status: IN CONSTRUCTION** (`feat/adl-system-v1`). This directory frames the
+> orchestrator's role and contract, and now carries its executable logic: the
+> build package + the `*sync` topology indexer + the HandoverBundle contract +
+> the config schema/onboarding-check + the **dispatch + execution-gate engine**.
+> The only remaining declare-only piece is the live cross-skill RUNTIME invocation
+> (step 3 of `execution-flow` in orchestrator.md).
+
+## What this is
+
+`mutagent-orchestrator` is the **composition layer** for the three standalone skills in
+`mutagent-system/`. It drives a skill (or agent) through the **Agentic Development
+Lifecycle (ADL)** — taking it from *idea → built → evaluated → diagnosed → improved* —
+by composing the existing skills as ADL stages. It owns no domain logic of its own; each
+stage is delegated to the skill that already does that job.
+
+## The ADL stages (skill composition)
+
+| ADL stage | Skill | Role |
+|---|---|---|
+| **SPEC** | `mutagent-agentspec` | Author + validate `agentspec.yaml`; `*sync-spec` reconciles the spec against a target (delegating the code-read to builder's `ai-architect #sync-spec`). |
+| **BUILD** | `mutagent-builder` | Implement a validated `agentspec.yaml` into the target; `ai-architect` runs `#sync-spec` build-internally when code drifts ahead mid-build. |
+| **AUDIT / verify** | `mutagent-evaluator` | Evaluate the built skill against declared success criteria; emit a verdict. |
+| **DIAGNOSE** | `mutagent-diagnostics` | Pull evidence from traces, root-cause failures, surface ranked remedies. |
+| **IMPROVE** | (loop back to BUILD) | Feed approved agentspec-backed remedies back into `mutagent-builder` for the next iteration. |
+
+```
+        idea
+          │
+        BUILD ───────────────┐  (mutagent-builder)
+          │                  │
+          ▼                  │
+        AUDIT/verify         │  (mutagent-evaluator)
+          │                  │
+          ▼                  │
+        DIAGNOSE             │  (mutagent-diagnostics)
+          │                  │
+          ▼                  │
+        IMPROVE ─────────────┘  (loop back to BUILD until goal met)
+```
+
+## Design stance (skeleton)
+
+- **Composes, never re-implements.** Each stage is a thin dispatch into an already-shipping
+  skill. The orchestrator owns sequencing, gate adjudication, and state hand-off between
+  stages — not the work inside any stage.
+- **Standalone + symbiosis preserved.** Skills do not reference each other in source
+  (see `../CLAUDE.md` → Standalone + Symbiosis principle). The orchestrator is the *only*
+  place that knows about all three; it talks to each via its public skill contract.
+- **Goal-driven loop with a termination contract.** Like the skills it composes, the ADL
+  loop must declare an observable terminator (goal met / verdict PASS) — never open-ended.
+
+## Present now
+
+- `package.json` + `tsconfig*.json` + `bunfig.toml` + `eslint.config.js` — the build package.
+- `scripts/sync-index.ts` — the `*sync` deterministic topology indexer (+ `tests/`). Also scans
+  `assets/agents/*.md` and indexes each as a `system_agent` subject (kind `skill | agent |
+  system_agent`; `system_agent` folds to `SubjectKind.Agent` on the frozen bundle).
+- `assets/agents/` — the orchestrator's first `assets/`: cross-stage **system-agent** defs (minimal
+  frontmatter + a body ```yaml``` operating block, per the agent-def conformance check). Today:
+  `discovery.md` (`class: system_agent`) — the trace-Discovery cell dispatched by `*discover`
+  (route_target "discovery"; `*collect-traces` alias), INTENT-BRANCHED on `TraceQuery.operationIntent`
+  (`fetch` generic collect/list/monitor · `evals`/`dataset` purposed fetch→select→classify curate).
+- `scripts/handover-contract.ts` — the TypeBox HandoverBundle contract blueprint
+  (schema + `validateHandoverBundle` + `makeHandoverBundle`, frozen v0.1.0) (+ `tests/`).
+- `scripts/config-schema.ts` — the TypeBox `MutagentConfigSchema` for `.mutagent/config.yaml`
+  (closed object, frozen `config_version` **0.2.0** — `global` (providers·workspace·models{default,`judge_model`}·brand·`context[]`·**`sources[]`**·**`targets[]`**, each source/target carries an optional `default` selector + `credential_ref: string|{env,path}`) + `lifecycle.{agentspec,builder,evaluator,diagnostics}` (per-skill, opaque-passthrough) + per-stage `triggers` (ship DISABLED) · `validateConfig` · `loadConfig` over an injected YAML path with legacy (pre-0.2.0) detection → `migration-required`) (+ `tests/` + `tests/fixtures/config/`).
+- `scripts/onboarding-check.ts` — the pure stage-aware `checkOnboardingComplete(config, activeStages, runCtx)`
+  completion-check: a scoped **global base floor** + **source/target/provider** floors only for the invoked stage, with source/target bound **by role** from the `global` catalog — `resolveSourceByRole`/`resolveTargetByRole`: one ⇒ resolved · one `default:true` among many ⇒ resolved · many + no default ⇒ `needs-selection` (non-blocking; operator picks at run time) · `>1 default` ⇒ `multiple-defaults` (config-error) (+ `tests/`).
+- `scripts/dispatch.ts` — the O6 dispatch engine: pure `resolveDispatch(command, ctx)` →
+  a DispatchDescriptor (dispatch | local | unknown). Resolves the target subject from the
+  injected `*sync` topology, maps the *command → a ROUTING AdlStage (the two-enum split),
+  and BUILDS the HandoverBundle via `makeHandoverBundle`. `lookupRoute` exports the shared
+  route table (+ `tests/`).
+- `scripts/gate.ts` — the O8 execution gate: pure `gateExecution(command, config, ctx)` →
+  `{ allowed, blockers }`. Two floors — onboarding (calls `checkOnboardingComplete` for
+  source stages; never tightens the schema) + approval (gated commands need
+  `approval_granted`) (+ `tests/`).
+- `scripts/eval-routing.ts` — the reusable LLM-DRIVEN routing eval (`*eval-routing`):
+  the DI harness `runRoutingEval(dataset, routerFn, ctx)` (pure, stub-router in the gate;
+  categorical exact-match grader + per-command + in-dist + held-out cohorts) + the pure
+  `buildRoutingPrompt`/`parseRoutedCommand`/`loadDataset`/`loadRoutingContext` + the REAL
+  on-demand `routeViaLLM` (mirrors the repo's `@langchain/google-genai` call, temp 0;
+  model intent sacred — no silent swap). Closes pred3 the operator's way. (+ `tests/` +
+  `tests/fixtures/routing-eval/dataset.yaml` — labeled in-dist + held-out + out-of-domain).
+- `orchestrator.md` + `routing.yaml` — the agent definition (incl. the `execution-flow`
+  resolve→gate→emit contract, step 3 declare-only · the `routing-eval` `*eval-routing`
+  capability) + NL-intent routing map.
+
+## Not yet present (follow-up)
+
+- `SKILL.md` — this orchestrator FOLDER has none by design; it is the dev-internal composition
+  layer. The orchestrator's PUBLISHED surface is **`@mutagent/helix`** (the ADL bundle, rooted at
+  `mutagent-system/`): it wraps `orchestrator.md` + `routing.yaml` as the conductor skill at
+  `mutagent-system/.claude/skills/mutagent-helix/SKILL.md` and ships the lifecycle skills alongside.
+  See `mutagent-system/RELEASING.md`.
+- The live cross-skill RUNTIME invocation (step 3 of `execution-flow`) — handing the gated
+  HandoverBundle to a real sibling skill (Skill-tool / sub-agent spawn). The deterministic
+  engine (resolve → gate → emit-descriptor) has landed; the live sibling call is declare-only.
+- The session state model + termination-gate machinery (the ADL loop's durable state + the
+  goal-met / verdict-PASS terminator) land in a follow-up.

package/mutagent-orchestrator/README.md

@@ -0,0 +1,20 @@
+# mutagent-orchestrator
+
+> **Scaffold.** Construction lands in a follow-up.
+
+`mutagent-orchestrator` composes the `mutagent-system` lifecycle skills into the **Agentic
+Development Lifecycle (ADL)** — driving a skill or agent from idea to a built, evaluated,
+diagnosed, and continuously-improved unit. It owns sequencing and stage hand-off only;
+each stage's work is delegated to the skill that already does that job.
+
+## ADL stage map
+
+| Stage | Skill | Does |
+|---|---|---|
+| **SPEC** | `mutagent-agentspec` | Guided interview → portable, validated `agentspec.yaml` (the Definition). |
+| **BUILD** | `mutagent-builder` | Implement a validated `agentspec.yaml` into the chosen target/harness. |
+| **AUDIT / verify** | `mutagent-evaluator` | Evaluate against success criteria → verdict. |
+| **DIAGNOSE** | `mutagent-diagnostics` | Trace-grounded root-cause + ranked remedies. |
+| **IMPROVE** | `mutagent-optimize` | Session-conducted, bounded eval-driven optimize loop (Build → Eval → Diagnose → Improve ↻); ONE gated apply at convergence via the shared `mutagent-cli apply`. |
+
+See `CLAUDE.md` in this directory for the full framing.