@sublang/playbook 15.1.0 → 16.0.0

package/reference/sdlc/code.playbook/code.fsm.ts

@@ -1,9 +1,17 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 //
-// Generated by slc/gears2fsm.md from ./code.gears.md.
+// FSM object artifact compiled from ./code.gears.md by gears2fsm.
+// It declares only the machine, its actor contracts, and typed inputs; the
+// linked runtime supplies the `player` and `playbook` actor implementations.
 
 import { assign, fromPromise, setup } from 'xstate';
+import { validatePlaybookCallResult } from '@sublang/playbook/xstate-runtime';
+import type { PlaybookCallResult } from '@sublang/playbook/runtime';
+
+// ---------------------------------------------------------------------------
+// Shared JSON value type (exact readonly variance of the shared boundary)
+// ---------------------------------------------------------------------------
 
 export type JsonValue =
   | null
@@ -13,40 +21,83 @@ export type JsonValue =
   | readonly JsonValue[]
   | { readonly [key: string]: JsonValue };
 
-export type CodeStateId =
-  | 'runFirstPhase'
-  | 'reviewFirstCommit'
-  | 'runIrTask'
-  | 'reviewIrTask';
+// ---------------------------------------------------------------------------
+// Identities
+// ---------------------------------------------------------------------------
+
+/** Canonical lowercase local id of the source role Coder. */
+export type CodeRole = 'coder';
+
+/** One role-id array per parallel group; CODE declares no parallel group. */
+export const concurrentRoleSets: readonly (readonly CodeRole[])[] = [];
+
+/** Delegated-player working leaves (CODE-1, CODE-3). */
+export type WorkingStateId = 'firstPhase' | 'irTaskPhase';
+
+/** Working leaves that may suspend for, and resume from, a Boss reply. */
+export type ResumableStateId = WorkingStateId;
+
+/** Root `BOSS_INTERRUPT` targets. */
+export type JumpableStateId = WorkingStateId;
+
+/** Nested `review` call states (CODE-2, CODE-4). */
+export type ReviewStateId = 'reviewNewIntentPhase' | 'reviewIrTaskPhase';
 
 export type CodeSourceItem = 'CODE-1' | 'CODE-2' | 'CODE-3' | 'CODE-4';
 
-export type CodePhase =
-  | 'direct'
-  | 'ir-created'
-  | 'ir-task-more'
-  | 'ir-task-final';
+/** The accepted phase outcome whose `review` call decides the next step. */
+export type PhaseOutcome =
+  | 'directCommit'
+  | 'irCommit'
+  | 'moreTasks'
+  | 'finalTask';
+
+/** The literal nested-call target shared by both call states and guards. */
+const REVIEW_PLAYBOOK_ID = 'review';
 
-export type PendingBossQuestion = {
-  readonly questionId: 'runFirstPhase' | 'runIrTask';
-  readonly resumeStateId: 'runFirstPhase' | 'runIrTask';
+// ---------------------------------------------------------------------------
+// Boss-reply suspension (scalar form: one active player task at a time)
+// ---------------------------------------------------------------------------
+
+export interface PendingBossQuestion {
+  readonly questionId: ResumableStateId;
+  readonly resumeStateId: ResumableStateId;
   readonly sourceItem: 'CODE-1' | 'CODE-3';
-  readonly asker: { readonly kind: 'role'; readonly roleId: 'coder' };
+  readonly asker: { readonly kind: 'role'; readonly roleId: CodeRole };
   readonly question: string;
-};
+}
 
-export type PlayerInput = {
-  readonly stateId: 'runFirstPhase' | 'runIrTask';
-  readonly role: 'coder';
-  readonly sourceItem: 'CODE-1' | 'CODE-3';
+// ---------------------------------------------------------------------------
+// Delegated player actor contract
+// ---------------------------------------------------------------------------
+
+interface PlayerInputBase {
+  readonly role: CodeRole;
+  /** The source item's full final prompt, verbatim. */
   readonly prompt: string;
+  /** This state's local result contract: guard name → description. */
   readonly result: Readonly<Record<string, string>>;
-  readonly callerInput: string;
+  /** `<caller-input>`: the caller's complete coding request. */
+  readonly callerInput?: string;
+  /** `<run-results>`: relevant run results; empty when none were supplied. */
   readonly runResults: string;
-  readonly irNumber?: string;
   readonly pendingBossQuestion?: PendingBossQuestion;
   readonly bossReply?: string;
-};
+}
+
+export interface FirstPhasePlayerInput extends PlayerInputBase {
+  readonly stateId: 'firstPhase';
+  readonly sourceItem: 'CODE-1';
+}
+
+export interface IrTaskPhasePlayerInput extends PlayerInputBase {
+  readonly stateId: 'irTaskPhase';
+  readonly sourceItem: 'CODE-3';
+  /** `<ir-number>`: the IR whose next unfinished task this phase implements. */
+  readonly irNumber?: string;
+}
+
+export type PlayerInput = FirstPhasePlayerInput | IrTaskPhasePlayerInput;
 
 export type PlayerOutput =
   | {
@@ -74,91 +125,119 @@ export type PlayerOutput =
       readonly irNumber: string;
       readonly irTask: string;
     }
-  | {
-      readonly guard: 'needsBossReply';
-      readonly question: string;
-    };
+  | { readonly guard: 'needsBossReply'; readonly question: string };
 
-export type PlaybookInput = {
-  readonly stateId: 'reviewFirstCommit' | 'reviewIrTask';
+// ---------------------------------------------------------------------------
+// Nested playbook actor contract
+// ---------------------------------------------------------------------------
+
+export interface PlaybookInput {
+  readonly stateId: ReviewStateId;
   readonly sourceItem: 'CODE-2' | 'CODE-4';
-  readonly playbookId: 'review';
+  readonly playbookId: typeof REVIEW_PLAYBOOK_ID;
   readonly text: string;
-};
+}
 
-export type ReviewOutput = {
+/** A successful call yields the child's own JSON-safe machine output. */
+export type PlaybookOutput = JsonValue | undefined;
+
+/** Public output interface of the packaged builtin `review`. */
+export interface ReviewPassOutput {
   readonly noUnsettledFindings: true;
-  /**
-   * Exact repository revision at which the review scope was evaluated:
-   * the last review-fix commit when one landed, otherwise the clean
-   * round's receipt-observed HEAD (DR-045). Always present.
-   */
   readonly evaluatedRevision: string;
-};
+}
 
-export type CompactError = {
+export interface CompactError {
   readonly name: string;
   readonly message: string;
-};
+}
+
+export interface ErrorRecord {
+  readonly name: string;
+  readonly message: string;
+  readonly stack?: string;
+}
 
-export type CodePlaybookOutput =
+/** Sanitized completed-result evidence of the `review` call that ended CODE. */
+export type CompletedReviewResult =
+  | {
+      readonly playbookId: typeof REVIEW_PLAYBOOK_ID;
+      readonly status: 'ok';
+      readonly output?: JsonValue;
+    }
+  | {
+      readonly playbookId: typeof REVIEW_PLAYBOOK_ID;
+      readonly status: 'aborted' | 'error';
+      readonly error: CompactError;
+    };
+
+// ---------------------------------------------------------------------------
+// Machine input, context, events, and output
+// ---------------------------------------------------------------------------
+
+/** Public output interface of the packaged builtin `code`. */
+export type CodeOutput =
   | {
       readonly status: 'complete';
-      /** Exact identity of the last CODE-owned commit. */
       readonly lastCodeCommit: string;
-      /** Exact repository revision the final passing review evaluated. */
       readonly finalEvaluatedRevision: string;
-      /** Every phase's review passed with no unsettled findings. */
       readonly allReviewsPassed: true;
     }
   | {
       readonly status: 'review-failed';
-      /** Exact identity of the last CODE-owned commit. */
       readonly lastCodeCommit: string;
       readonly error: CompactError;
     };
 
-export type CodingInput = {
+export interface CodeInput {
+  /** Optional seed for `<run-results>`; `START_CODE` may supply its own. */
   readonly runResults?: string;
-};
+}
 
-export type CodingContext = {
+export interface CodeContext {
+  /** `<run-results>`: relevant run results relayed to every phase. */
   readonly runResults: string;
+  /** `<caller-input>`: the caller's coding request and relevant context. */
   readonly callerInput?: string;
+  /** `<code-commit>`: the accepted `latestCommit` of the latest phase. */
+  readonly codeCommit?: string;
+  /** `<coder-output>`: Coder's verbatim final text for the latest phase. */
   readonly coderOutput?: string;
-  readonly latestCommit?: string;
+  /** `<ir-number>`: the created or continued IR. */
   readonly irNumber?: string;
+  /** `<ir-task>`: the IR task the latest IR-task phase implemented. */
   readonly irTask?: string;
+  /** The accepted outcome of the phase under review. */
+  readonly phaseOutcome?: PhaseOutcome;
+  /** Revision evaluated by the latest passing review. */
   readonly evaluatedRevision?: string;
-  readonly phase?: CodePhase;
-  readonly completion?: 'complete' | 'review-failed';
+  /** Compact failure CODE reports when review did not pass a phase. */
   readonly reviewError?: CompactError;
-  readonly lastError?: unknown;
+  /** Sanitized evidence of the review result that ended CODE. */
+  readonly reviewEvidence?: CompletedReviewResult;
+  readonly lastError?: ErrorRecord;
   readonly pendingBossQuestion?: PendingBossQuestion;
   readonly bossReply?: string;
-};
+}
 
-export type CodingEvent =
-  | { readonly type: 'START_CODE'; readonly callerInput: string }
+export type CodeEvent =
+  | {
+      readonly type: 'START_CODE';
+      readonly callerInput: string;
+      readonly runResults?: string;
+    }
+  | { readonly type: 'BOSS_INTERRUPT'; readonly targetId: JumpableStateId }
   | {
       readonly type: 'BOSS_REPLY';
       readonly answer: string;
-      readonly questionId?: 'runFirstPhase' | 'runIrTask';
+      readonly questionId?: ResumableStateId;
     };
 
-const APPENDED_PHASE_PROMPT = [
-  'Keep to the original intent and follow what it asks.',
-  'Do not re-run tests or builds whose inputs have not changed since any previous reported run.',
-  "Make the phase's minimal changes and then one new commit, following @specs/packages/git.md; never amend an existing commit.",
-  'Make the commit message explain concisely what changed and why, including relevant verification.',
-  'Identify every new commit you make.',
-  'Credit every AI that contributed to this commit: Coder <coder-llm>.',
-];
+// ---------------------------------------------------------------------------
+// Prompts and result contracts (verbatim from code.gears.md)
+// ---------------------------------------------------------------------------
 
 const FIRST_PHASE_PROMPT = [
-  '> Original request: <caller-input>',
-  '> Run results: <run-results>',
-  '',
   'First determine whether the coding request starts a new coding intent or continues an existing IR with unfinished work.',
   'If the request may continue an existing IR but does not identify it unambiguously, ask Boss before changing files.',
   '',
@@ -174,473 +253,556 @@ const FIRST_PHASE_PROMPT = [
   '',
   'Consult @specs/map.md for relevant context and @specs/meta.md for spec requirements, if needed.',
   '',
-  ...APPENDED_PHASE_PROMPT,
-].join('\n');
-
-const IR_TASK_PROMPT = [
+  'Keep to the original intent and follow what it asks.',
+  'Do not re-run tests or builds whose inputs have not changed since any previous reported run.',
+  "Make the phase's minimal changes and then one new commit, following @specs/packages/git.md; never amend an existing commit.",
+  'Make the commit message explain concisely what changed and why, including relevant verification.',
+  'Identify every new commit you make.',
+  'Credit every AI that contributed to this commit: Coder <coder-llm>.',
+  '',
   '> Original request: <caller-input>',
-  '> IR number: <ir-number>',
   '> Run results: <run-results>',
-  '',
+].join('\n');
+
+const IR_TASK_PHASE_PROMPT = [
   'Read the identified IR and implement exactly its next unfinished task, including corresponding tests or specs if any.',
   'Do not implement a later task in this phase.',
   "Mark the IR's progress and deliverables when relevant.",
   'If the IR will be finished after this phase, double-check that all acceptance criteria are met.',
   '',
-  ...APPENDED_PHASE_PROMPT,
+  'Keep to the original intent and follow what it asks.',
+  'Do not re-run tests or builds whose inputs have not changed since any previous reported run.',
+  "Make the phase's minimal changes and then one new commit, following @specs/packages/git.md; never amend an existing commit.",
+  'Make the commit message explain concisely what changed and why, including relevant verification.',
+  'Identify every new commit you make.',
+  'Credit every AI that contributed to this commit: Coder <coder-llm>.',
+  '',
+  '> Original request: <caller-input>',
+  '> IR number: <ir-number>',
+  '> Run results: <run-results>',
+].join('\n');
+
+const REVIEW_NEW_INTENT_PHASE_TEMPLATE = [
+  '> Original intent: <caller-input>',
+  '> Review scope: the commit <code-commit> from this coding phase and its resulting repository state.',
+  '> Coder output: <coder-output>',
+].join('\n');
+
+const REVIEW_IR_TASK_PHASE_TEMPLATE = [
+  '> Original intent: <caller-input>',
+  '> Review scope: the commit <code-commit> from this coding phase and its resulting repository state.',
+  '> Coder output: <coder-output>',
+  '',
+  '> Current IR task: <ir-task>',
 ].join('\n');
 
-const NEEDS_BOSS_REPLY_RESULT =
+const NEEDS_BOSS_REPLY_DESCRIPTION =
   "The acting agent's prose surfaces a clarifying question for Boss that the agent cannot answer alone. Output shall include `question: <verbatim question text from the acting agent's prose>`.";
 
-const FIRST_PHASE_RESULTS = {
+const FIRST_PHASE_RESULT = {
   directCommit:
-    'Coder completed and committed the direct implementation phase. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.',
+    "Coder completed the new coding intent as one direct implementation phase and made its one new commit; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.",
   irCommit:
-    'Coder created and committed a new IR without implementing an IR task. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, and `irNumber` identifying the created IR.',
+    "Coder decomposed the new coding intent into a new IR, implemented no IR task, and made its one new commit; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, and `irNumber` identifying the created IR.",
   moreTasks:
-    'Coder continued an existing IR, completed and committed exactly its next unfinished task, and at least one task remains. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, `irNumber` identifying the continued IR, and `irTask` naming the implemented task.',
+    "Coder continued an existing IR, implemented exactly its next unfinished task, made its one new commit, and at least one IR task remains unfinished; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, `irNumber` identifying the continued IR, and `irTask` naming the implemented task.",
   finalTask:
-    'Coder continued an existing IR and completed and committed its final task. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, `irNumber` identifying the continued IR, and `irTask` naming the implemented task.',
-  needsBossReply: NEEDS_BOSS_REPLY_RESULT,
+    "Coder continued an existing IR, implemented its final unfinished task, and made its one new commit; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, `irNumber` identifying the continued IR, and `irTask` naming the implemented task.",
+  needsBossReply: NEEDS_BOSS_REPLY_DESCRIPTION,
 } as const;
 
-const IR_TASK_RESULTS = {
+const IR_TASK_PHASE_RESULT = {
   moreTasks:
-    "Coder completed and committed exactly the IR's next unfinished task and at least one task remains. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, `irNumber` identifying the continued IR, and `irTask` naming the implemented task.",
+    "Coder implemented exactly the IR's next unfinished task, made its one new commit, and at least one IR task remains unfinished; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, `irNumber` identifying the IR, and `irTask` naming the implemented task.",
   finalTask:
-    "Coder completed and committed the IR's final task. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, `irNumber` identifying the continued IR, and `irTask` naming the implemented task.",
-  needsBossReply: NEEDS_BOSS_REPLY_RESULT,
+    "Coder implemented the IR's final unfinished task and made its one new commit; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, `irNumber` identifying the IR, and `irTask` naming the implemented task.",
+  needsBossReply: NEEDS_BOSS_REPLY_DESCRIPTION,
 } as const;
 
 const STATE_DESCRIPTIONS = {
-  ready: 'Waiting for a coding intent.',
-  runFirstPhase:
-    'Coder is running the first coding phase: a direct implementation, a new intent record, or an existing intent-record task.',
-  reviewFirstCommit:
-    'The REVIEW playbook is checking the direct or new-IR phase commit.',
-  runIrTask: 'Coder is implementing exactly one unfinished intent-record task.',
-  reviewIrTask: 'The REVIEW playbook is checking the latest task commit.',
-  awaitBossReply: 'Waiting for Boss to answer Coder.',
-  failed: 'The coding workflow failed and is waiting for a new coding intent.',
-  reportedReviewFailure:
-    'The coding workflow reported a REVIEW failure and the last code-owned commit.',
-  done: "The coding workflow completed after every phase's REVIEW passed with no unsettled findings.",
+  ready: 'Waiting for a coding request.',
+  firstPhase:
+    'Coder runs the first coding phase: a direct implementation, a new IR, or the next task of an existing IR.',
+  reviewNewIntentPhase:
+    'REVIEW examines the commit of the direct implementation or new-IR phase.',
+  irTaskPhase: "Coder implements the identified IR's next unfinished task.",
+  reviewIrTaskPhase: 'REVIEW examines the commit of the IR-task phase.',
+  awaitBossReply: "Waiting for Boss to answer the acting agent's question.",
+  failed:
+    'CODE parked after a control-plane failure and waits for Boss to restart or resume it.',
+  reviewFailed:
+    'CODE stopped because review did not pass a phase and reports the failure with its last code-owned commit.',
+  done: "CODE completed: every phase's review passed with no unsettled findings.",
 } as const;
 
-function playbookMeta<StateId extends keyof typeof STATE_DESCRIPTIONS>(
-  stateId: StateId,
-  role?: 'coder',
-) {
-  return {
-    playbook: {
-      stateId,
-      description: STATE_DESCRIPTIONS[stateId],
-      ...(role === undefined ? {} : { role }),
-    },
-  };
-}
+type StateKey = keyof typeof STATE_DESCRIPTIONS;
 
-// DR-048: a final state additionally declares whether its outcome means the
-// workflow succeeded or failed, so a caller learns that from the machine
-// rather than from CODE's output fields.
-function terminalMeta<StateId extends keyof typeof STATE_DESCRIPTIONS>(
-  stateId: StateId,
-  terminal: 'success' | 'failure',
-) {
-  return {
-    playbook: {
-      stateId,
-      description: STATE_DESCRIPTIONS[stateId],
-      terminal,
-    },
-  };
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
-    return false;
-  }
-  const prototype = Object.getPrototypeOf(value);
-  return prototype === Object.prototype || prototype === null;
-}
+const RESUME_METADATA = {
+  firstPhase: { sourceItem: 'CODE-1' },
+  irTaskPhase: { sourceItem: 'CODE-3' },
+} as const satisfies Record<
+  ResumableStateId,
+  { readonly sourceItem: PendingBossQuestion['sourceItem'] }
+>;
 
-function isNonEmptyString(value: unknown): value is string {
-  return typeof value === 'string' && value.trim().length > 0;
-}
-
-function playerOutput(event: unknown): Record<string, unknown> | undefined {
-  if (!isRecord(event)) return undefined;
-  return isRecord(event.output) ? event.output : undefined;
-}
-
-function outputGuard(event: unknown, guard: PlayerOutput['guard']): boolean {
-  return playerOutput(event)?.guard === guard;
-}
-
-function outputString(event: unknown, field: string): string | undefined {
-  const value = playerOutput(event)?.[field];
-  return isNonEmptyString(value) ? value : undefined;
-}
-
-function hasCommittedOutput(event: unknown): boolean {
-  return (
-    outputString(event, 'coderOutput') !== undefined &&
-    outputString(event, 'latestCommit') !== undefined
-  );
-}
-
-function hasIrTaskOutput(event: unknown): boolean {
-  return (
-    hasCommittedOutput(event) &&
-    outputString(event, 'irNumber') !== undefined &&
-    outputString(event, 'irTask') !== undefined
-  );
-}
-
-function isDirectCommit({ event }: { event: unknown }): boolean {
-  return (
-    outputGuard(event, 'directCommit') &&
-    hasCommittedOutput(event)
-  );
-}
+const REVIEW_NOT_PASSED: CompactError = {
+  name: 'ReviewNotPassed',
+  message:
+    'review returned a terminal result that does not establish that the supplied scope was evaluated with no unsettled findings.',
+};
 
-function isIrCommit({ event }: { event: unknown }): boolean {
-  return (
-    outputGuard(event, 'irCommit') &&
-    hasCommittedOutput(event) &&
-    outputString(event, 'irNumber') !== undefined
-  );
-}
+// ---------------------------------------------------------------------------
+// Structural helpers
+// ---------------------------------------------------------------------------
 
-function isMoreTasks({ event }: { event: unknown }): boolean {
-  return (
-    outputGuard(event, 'moreTasks') &&
-    hasIrTaskOutput(event)
-  );
-}
+const isRecord = (
+  value: unknown,
+): value is Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
 
-function isFinalTask({ event }: { event: unknown }): boolean {
-  return (
-    outputGuard(event, 'finalTask') &&
-    hasIrTaskOutput(event)
-  );
-}
+const isNonEmptyString = (value: unknown): value is string =>
+  typeof value === 'string' && value.trim().length > 0;
 
-function needsBossReply({ event }: { event: unknown }): boolean {
-  return (
-    outputGuard(event, 'needsBossReply') &&
-    outputString(event, 'question') !== undefined
-  );
-}
+const doneOutputOf = (event: unknown): unknown =>
+  isRecord(event) ? event.output : undefined;
 
-function reviewOutput(event: unknown): unknown {
-  return isRecord(event) ? event.output : undefined;
-}
+const actorErrorOf = (event: unknown): unknown =>
+  isRecord(event) ? event.error : undefined;
 
-function isReviewApprovedValue(value: unknown): value is ReviewOutput {
-  if (!isRecord(value)) return false;
-  if (
-    Reflect.ownKeys(value).some(
-      (key) =>
-        typeof key !== 'string' ||
-        (key !== 'noUnsettledFindings' && key !== 'evaluatedRevision'),
-    )
-  ) {
-    return false;
+/** Narrows a player done event to the declared player output contract. */
+function playerOutputOf(event: unknown): PlayerOutput | undefined {
+  const output = doneOutputOf(event);
+  if (!isRecord(output)) return undefined;
+  switch (output.guard) {
+    case 'directCommit':
+      return isNonEmptyString(output.coderOutput) &&
+        isNonEmptyString(output.latestCommit)
+        ? {
+            guard: 'directCommit',
+            coderOutput: output.coderOutput,
+            latestCommit: output.latestCommit,
+          }
+        : undefined;
+    case 'irCommit':
+      return isNonEmptyString(output.coderOutput) &&
+        isNonEmptyString(output.latestCommit) &&
+        isNonEmptyString(output.irNumber)
+        ? {
+            guard: 'irCommit',
+            coderOutput: output.coderOutput,
+            latestCommit: output.latestCommit,
+            irNumber: output.irNumber,
+          }
+        : undefined;
+    case 'moreTasks':
+    case 'finalTask':
+      return isNonEmptyString(output.coderOutput) &&
+        isNonEmptyString(output.latestCommit) &&
+        isNonEmptyString(output.irNumber) &&
+        isNonEmptyString(output.irTask)
+        ? {
+            guard: output.guard,
+            coderOutput: output.coderOutput,
+            latestCommit: output.latestCommit,
+            irNumber: output.irNumber,
+            irTask: output.irTask,
+          }
+        : undefined;
+    case 'needsBossReply':
+      return isNonEmptyString(output.question)
+        ? { guard: 'needsBossReply', question: output.question }
+        : undefined;
+    default:
+      return undefined;
   }
-  return (
-    value.noUnsettledFindings === true &&
-    isNonEmptyString(value.evaluatedRevision)
-  );
-}
-
-function reviewApprovedFor(
-  phase: CodePhase,
-): (args: { context: CodingContext; event: unknown }) => boolean {
-  return ({ context, event }) =>
-    context.phase === phase && isReviewApprovedValue(reviewOutput(event));
-}
-
-function isStateValue(value: unknown, ancestors = new Set<object>()): boolean {
-  if (typeof value === 'string') return true;
-  if (!isRecord(value) || ancestors.has(value)) return false;
-  const next = new Set(ancestors).add(value);
-  return Reflect.ownKeys(value).every(
-    (key) =>
-      typeof key === 'string' &&
-      Object.prototype.propertyIsEnumerable.call(value, key) &&
-      isStateValue(value[key], next),
-  );
 }
 
-function isStringArray(value: unknown): value is readonly string[] {
-  return (
-    Array.isArray(value) &&
-    Reflect.ownKeys(value).length === value.length + 1 &&
-    Reflect.ownKeys(value).every((key) => {
-      if (key === 'length') return true;
-      return (
-        typeof key === 'string' &&
-        /^(0|[1-9][0-9]*)$/.test(key) &&
-        Number(key) < value.length
-      );
-    }) &&
-    value.every((entry) => isNonEmptyString(entry)) &&
-    new Set(value).size === value.length
-  );
-}
-
-function isPlaybookState(value: unknown): boolean {
-  if (!isRecord(value)) return false;
-  const allowed = new Set([
-    'value',
-    'activeStateIds',
-    'tags',
-    'status',
-    'quiescent',
-    'stateId',
-  ]);
-  if (
-    Reflect.ownKeys(value).some(
-      (key) => typeof key !== 'string' || !allowed.has(key),
-    ) ||
-    !Object.prototype.hasOwnProperty.call(value, 'value') ||
-    !Object.prototype.hasOwnProperty.call(value, 'activeStateIds') ||
-    !Object.prototype.hasOwnProperty.call(value, 'tags') ||
-    !Object.prototype.hasOwnProperty.call(value, 'status') ||
-    !Object.prototype.hasOwnProperty.call(value, 'quiescent')
-  ) {
-    return false;
+/**
+ * Strict JSON validation: null, booleans, finite numbers, strings, exact
+ * arrays, and plain records of enumerable own data properties. Cycle
+ * detection tracks only the active recursion path.
+ */
+function isJsonValue(value: unknown, path: Set<object> = new Set()): value is JsonValue {
+  if (value === null) return true;
+  switch (typeof value) {
+    case 'boolean':
+    case 'string':
+      return true;
+    case 'number':
+      return Number.isFinite(value);
+    case 'object':
+      break;
+    default:
+      return false;
+  }
+  const container = value as object;
+  if (path.has(container)) return false;
+  path.add(container);
+  try {
+    if (Array.isArray(container)) {
+      if (Object.getPrototypeOf(container) !== Array.prototype) return false;
+      const keys = Reflect.ownKeys(container);
+      if (keys.length !== container.length + 1) return false;
+      const lengthDescriptor = Object.getOwnPropertyDescriptor(container, 'length');
+      if (
+        lengthDescriptor === undefined ||
+        lengthDescriptor.configurable !== false ||
+        lengthDescriptor.enumerable !== false ||
+        lengthDescriptor.value !== container.length
+      ) {
+        return false;
+      }
+      for (let index = 0; index < container.length; index += 1) {
+        const descriptor = Object.getOwnPropertyDescriptor(container, String(index));
+        if (
+          descriptor === undefined ||
+          !descriptor.enumerable ||
+          !('value' in descriptor) ||
+          !isJsonValue(descriptor.value, path)
+        ) {
+          return false;
+        }
+      }
+      return true;
+    }
+    const prototype = Object.getPrototypeOf(container);
+    if (prototype !== Object.prototype && prototype !== null) return false;
+    for (const key of Reflect.ownKeys(container)) {
+      if (typeof key !== 'string') return false;
+      const descriptor = Object.getOwnPropertyDescriptor(container, key);
+      if (
+        descriptor === undefined ||
+        !descriptor.enumerable ||
+        !('value' in descriptor) ||
+        !isJsonValue(descriptor.value, path)
+      ) {
+        return false;
+      }
+    }
+    return true;
+  } finally {
+    path.delete(container);
   }
-  return (
-    isStateValue(value.value) &&
-    isStringArray(value.activeStateIds) &&
-    isStringArray(value.tags) &&
-    (value.status === 'active' ||
-      value.status === 'done' ||
-      value.status === 'error' ||
-      value.status === 'stopped') &&
-    typeof value.quiescent === 'boolean' &&
-    (!Object.prototype.hasOwnProperty.call(value, 'stateId') ||
-      (isNonEmptyString(value.stateId) &&
-        value.activeStateIds.length === 1 &&
-        value.activeStateIds[0] === value.stateId))
-  );
 }
 
-function nestedResultFromError(error: unknown): Record<string, unknown> | undefined {
-  if (!(error instanceof Error)) return undefined;
-  const result = (error as Error & { readonly result?: unknown }).result;
-  return isRecord(result) ? result : undefined;
+/** Normalizes any thrown or malformed value to a JSON-safe error record. */
+function errorRecord(value: unknown): ErrorRecord {
+  if (value instanceof Error) {
+    return {
+      name: value.name || 'Error',
+      message: value.message,
+      ...(typeof value.stack === 'string' ? { stack: value.stack } : {}),
+    };
+  }
+  if (isRecord(value) && typeof value.message === 'string') {
+    return {
+      name: isNonEmptyString(value.name) ? value.name : 'Error',
+      message: value.message,
+    };
+  }
+  return { name: 'Error', message: String(value) };
 }
 
-type AuthoredReviewFailure =
-  | {
-      readonly status: 'aborted' | 'error';
-      readonly error?: CompactError;
-    }
-  // DR-048: a child that completed at an authored failure terminal. The
-  // bridge rejects it through the same error path, so CODE recognizes the
-  // failure from REVIEW's own machine and never from its output fields.
-  | {
-      readonly status: 'ok';
-      readonly output?: JsonValue;
-    };
+// ---------------------------------------------------------------------------
+// Nested `review` results
+// ---------------------------------------------------------------------------
 
-function isFailureTerminalRecord(value: unknown): boolean {
-  if (!isRecord(value)) return false;
-  const allowed = new Set(['stateId', 'kind', 'description']);
-  return (
-    Reflect.ownKeys(value).every(
-      (key) => typeof key === 'string' && allowed.has(key),
-    ) &&
-    isNonEmptyString(value.stateId) &&
-    value.kind === 'failure' &&
-    (!Object.prototype.hasOwnProperty.call(value, 'description') ||
-      typeof value.description === 'string')
-  );
+/**
+ * Source-authored acceptance on `review`'s declared public output: the
+ * result returns the exact evaluated repository revision and affirmatively
+ * establishes that no unsettled findings remain. The shared bridge correlates
+ * the result with the supplied review scope.
+ */
+function reviewPassOf(event: unknown): ReviewPassOutput | undefined {
+  const output = doneOutputOf(event);
+  if (!isRecord(output)) return undefined;
+  return output.noUnsettledFindings === true &&
+    isNonEmptyString(output.evaluatedRevision)
+    ? { noUnsettledFindings: true, evaluatedRevision: output.evaluatedRevision }
+    : undefined;
 }
 
-function normalizedReviewFailure(
+/**
+ * Recognizes an authored rejected child result: an aborted or error call, or
+ * a child that completed at its own authored failure terminal.
+ */
+export function authoredChildResult(
   error: unknown,
-): AuthoredReviewFailure | undefined {
-  const result = nestedResultFromError(error);
-  if (result === undefined) return undefined;
-  const allowed = new Set([
-    'status',
-    'playbookId',
-    'childSessionId',
-    'state',
-    ...(result.status === 'ok' ? ['output', 'terminal'] : ['error']),
-  ]);
-  if (
-    Reflect.ownKeys(result).some(
-      (key) => typeof key !== 'string' || !allowed.has(key),
-    ) ||
-    (result.status !== 'aborted' &&
-      result.status !== 'error' &&
-      result.status !== 'ok') ||
-    result.playbookId !== 'review'
-  ) {
-    return undefined;
-  }
-  if (
-    Object.prototype.hasOwnProperty.call(result, 'childSessionId') &&
-    !isNonEmptyString(result.childSessionId)
-  ) {
-    return undefined;
-  }
-  if (
-    Object.prototype.hasOwnProperty.call(result, 'state') &&
-    !isPlaybookState(result.state)
-  ) {
+  expectedPlaybookId: string,
+): PlaybookCallResult | undefined {
+  if (!(error instanceof Error)) return undefined;
+  try {
+    const result = validatePlaybookCallResult(
+      (error as Error & { result?: unknown }).result,
+      expectedPlaybookId,
+    );
+    return result.status !== 'ok' || result.terminal?.kind === 'failure'
+      ? result
+      : undefined;
+  } catch {
     return undefined;
   }
+}
+
+/** Compact evidence and reported error for an authored review failure. */
+function authoredReviewFailureOf(
+  event: unknown,
+):
+  | { readonly evidence: CompletedReviewResult; readonly error: CompactError }
+  | undefined {
+  const result = authoredChildResult(actorErrorOf(event), REVIEW_PLAYBOOK_ID);
+  if (result === undefined) return undefined;
   if (result.status === 'ok') {
-    if (
-      !Object.prototype.hasOwnProperty.call(result, 'terminal') ||
-      !isFailureTerminalRecord(result.terminal) ||
-      !isNonEmptyString(result.childSessionId)
-    ) {
-      return undefined;
-    }
+    const description = result.terminal?.description;
     return {
-      status: 'ok',
-      ...(result.output === undefined
-        ? {}
-        : { output: result.output as JsonValue }),
-    };
-  }
-  let normalizedError: CompactError | undefined;
-  if (Object.prototype.hasOwnProperty.call(result, 'error')) {
-    if (!isRecord(result.error)) return undefined;
-    const errorKeys = Reflect.ownKeys(result.error);
-    if (
-      errorKeys.some(
-        (key) =>
-          typeof key !== 'string' ||
-          (key !== 'name' && key !== 'message' && key !== 'stack'),
-      ) ||
-      !Object.prototype.hasOwnProperty.call(result.error, 'name') ||
-      !Object.prototype.hasOwnProperty.call(result.error, 'message') ||
-      !isNonEmptyString(result.error.name) ||
-      typeof result.error.message !== 'string' ||
-      (Object.prototype.hasOwnProperty.call(result.error, 'stack') &&
-        typeof result.error.stack !== 'string')
-    ) {
-      return undefined;
-    }
-    normalizedError = {
-      name: result.error.name,
-      message: result.error.message,
+      evidence: {
+        playbookId: REVIEW_PLAYBOOK_ID,
+        status: 'ok',
+        ...(result.output === undefined ? {} : { output: result.output }),
+      },
+      error: {
+        name: 'ReviewFailed',
+        message: isNonEmptyString(description)
+          ? `review ended at its authored failure terminal: ${description}`
+          : 'review ended at its authored failure terminal.',
+      },
     };
-  } else if (result.status === 'error') {
-    return undefined;
   }
+  const error: CompactError =
+    result.error !== undefined
+      ? { name: result.error.name, message: result.error.message }
+      : { name: 'AbortError', message: 'The review call was aborted.' };
   return {
-    status: result.status,
-    ...(normalizedError === undefined ? {} : { error: normalizedError }),
+    evidence: { playbookId: REVIEW_PLAYBOOK_ID, status: result.status, error },
+    error,
   };
 }
 
-function authoredReviewFailure({ event }: { event: unknown }): boolean {
-  const error = isRecord(event) ? event.error : undefined;
-  return normalizedReviewFailure(error) !== undefined;
-}
+// ---------------------------------------------------------------------------
+// Nested call text composition (quoted relays)
+// ---------------------------------------------------------------------------
 
-function compactError(value: unknown): CompactError {
-  if (value instanceof Error) {
-    return {
-      name: value.name || 'Error',
-      message: value.message,
-    };
-  }
-  return { name: 'Error', message: String(value) };
-}
+const REVIEW_PLACEHOLDER =
+  /<caller-input>|<code-commit>|<coder-output>|<ir-task>/g;
 
-function authoredReviewError(event: unknown): CompactError {
-  const outer = isRecord(event) ? event.error : undefined;
-  const failure = normalizedReviewFailure(outer);
-  if (failure !== undefined && failure.status !== 'ok' && failure.error) {
-    return failure.error;
-  }
-  if (failure?.status === 'aborted') {
-    return { name: 'AbortError', message: 'REVIEW was aborted.' };
+/**
+ * Composes review call text in one callback pass per template line: a quoted
+ * relay line whose value is empty contributes no line, a multi-line value is
+ * quoted line by line, and an absent value keeps its placeholder literal.
+ */
+function composeReviewText(
+  template: string,
+  values: Readonly<Record<string, string | undefined>>,
+): string {
+  const lines: string[] = [];
+  for (const line of template.split('\n')) {
+    const quoted = line.startsWith('> ');
+    const tokens = line.match(REVIEW_PLACEHOLDER) ?? [];
+    if (quoted && tokens.some((token) => values[token] === '')) continue;
+    lines.push(
+      line.replace(REVIEW_PLACEHOLDER, (token: string) => {
+        const value = values[token];
+        if (value === undefined) return token;
+        return quoted ? value.split('\n').join('\n> ') : value;
+      }),
+    );
   }
-  return compactError(outer);
+  while (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
+  return lines.join('\n');
 }
 
-function quoteRelay(label: string, value: string): string {
-  const lines = value.split('\n');
-  return [`> ${label}: ${lines[0] ?? ''}`, ...lines.slice(1).map((line) => `> ${line}`)].join(
-    '\n',
-  );
-}
+// ---------------------------------------------------------------------------
+// Guards
+// ---------------------------------------------------------------------------
 
-function reviewScopeLine(context: CodingContext): string {
-  return (
-    `> Review scope: the commit ${context.latestCommit ?? ''} ` +
-    'from this coding phase and its resulting repository state.'
-  );
-}
+type EventArgs = { readonly event: unknown };
+type ContextEventArgs = {
+  readonly context: CodeContext;
+  readonly event: unknown;
+};
+type MachineArgs = {
+  readonly context: CodeContext;
+  readonly event: CodeEvent;
+};
+
+const acceptsOutcome =
+  (outcome: PhaseOutcome) =>
+  ({ event }: EventArgs): boolean =>
+    playerOutputOf(event)?.guard === outcome;
+
+const needsBossReplyWithQuestion = ({ event }: EventArgs): boolean =>
+  playerOutputOf(event)?.guard === 'needsBossReply';
+
+// A review state is entered only through an accepting phase arm, which records
+// the phase outcome and its non-empty code-owned commit.
+const reviewPassedAfter =
+  (outcome: PhaseOutcome) =>
+  ({ context, event }: ContextEventArgs): boolean =>
+    context.phaseOutcome === outcome &&
+    isNonEmptyString(context.codeCommit) &&
+    reviewPassOf(event) !== undefined;
+
+const authoredReviewFailure = ({ event }: EventArgs): boolean =>
+  authoredReviewFailureOf(event) !== undefined;
+
+const validStartCode = ({ event }: MachineArgs): boolean =>
+  event.type === 'START_CODE' &&
+  isNonEmptyString(event.callerInput) &&
+  (event.runResults === undefined || typeof event.runResults === 'string');
+
+const repliesToPendingQuestion = ({ context, event }: MachineArgs): boolean =>
+  event.type === 'BOSS_REPLY' &&
+  context.pendingBossQuestion !== undefined &&
+  (event.questionId === undefined ||
+    event.questionId === context.pendingBossQuestion.questionId);
+
+const emptyBossReply = (args: MachineArgs): boolean =>
+  repliesToPendingQuestion(args) &&
+  args.event.type === 'BOSS_REPLY' &&
+  !isNonEmptyString(args.event.answer);
 
-function newIntentReviewText(context: CodingContext): string {
-  return [
-    quoteRelay('Original intent', context.callerInput ?? ''),
-    reviewScopeLine(context),
-    quoteRelay('Coder output', context.coderOutput ?? ''),
-  ].join('\n');
+const INTERRUPT_PRECONDITIONS = {
+  firstPhase: (context: CodeContext) => isNonEmptyString(context.callerInput),
+  irTaskPhase: (context: CodeContext) =>
+    isNonEmptyString(context.callerInput) &&
+    isNonEmptyString(context.irNumber),
+} as const satisfies Record<JumpableStateId, (context: CodeContext) => boolean>;
+
+// ---------------------------------------------------------------------------
+// Transition helpers
+// ---------------------------------------------------------------------------
+
+/** One guarded root transition per jumpable state. */
+function bossInterrupts<const Ids extends readonly JumpableStateId[]>(
+  ids: Ids,
+) {
+  return ids.map((id) => ({
+    guard: ({ context, event }: MachineArgs) =>
+      event.type === 'BOSS_INTERRUPT' &&
+      event.targetId === id &&
+      INTERRUPT_PRECONDITIONS[id](context),
+    target: `#${id}` as const,
+    reenter: true,
+    actions: 'resetForInterrupt' as const,
+  }));
 }
 
-function irTaskReviewText(context: CodingContext): string {
-  return [
-    quoteRelay('Original intent', context.callerInput ?? ''),
-    reviewScopeLine(context),
-    quoteRelay('Coder output', context.coderOutput ?? ''),
-    quoteRelay('Current IR task', context.irTask ?? ''),
-  ].join('\n');
+/** One guarded `BOSS_REPLY` resume transition per suspended working leaf. */
+function resumableStates<const Ids extends readonly ResumableStateId[]>(
+  ids: Ids,
+) {
+  return ids.map((id) => ({
+    guard: (args: MachineArgs) =>
+      repliesToPendingQuestion(args) &&
+      args.event.type === 'BOSS_REPLY' &&
+      isNonEmptyString(args.event.answer) &&
+      args.context.pendingBossQuestion?.resumeStateId === id,
+    target: `#${id}` as const,
+    reenter: true,
+    actions: 'rememberBossReply' as const,
+  }));
 }
 
-const machineSetup = setup({
-  types: {} as {
-    context: CodingContext;
-    events: CodingEvent;
-    input: CodingInput;
-    output: CodePlaybookOutput;
+const bossReplyFields = (context: CodeContext) => ({
+  ...(context.pendingBossQuestion !== undefined
+    ? { pendingBossQuestion: context.pendingBossQuestion }
+    : {}),
+  ...(context.bossReply !== undefined ? { bossReply: context.bossReply } : {}),
+});
+
+const acceptedOutcome = (
+  source: WorkingStateId,
+  target: string,
+  outcome: PhaseOutcome | 'needsBossReply',
+) =>
+  ({
+    type: 'playbook.acceptedOutcome',
+    params: { source, target, acceptedOutcome: outcome },
+  }) as const;
+
+const acceptPhaseArm = (
+  source: WorkingStateId,
+  outcome: PhaseOutcome,
+  guard: 'acceptDirectCommit' | 'acceptIrCommit' | 'acceptMoreTasks' | 'acceptFinalTask',
+  target: ReviewStateId,
+) =>
+  ({
+    guard,
+    target: `#${target}`,
+    actions: [
+      acceptedOutcome(source, target, outcome),
+      'rememberPhaseCommit',
+      'clearBossReplyContext',
+    ],
+  }) as const;
+
+const suspendArm = (source: WorkingStateId) =>
+  ({
+    guard: 'needsBossReplyWithQuestion',
+    target: '#awaitBossReply',
+    actions: [
+      acceptedOutcome(source, 'awaitBossReply', 'needsBossReply'),
+      { type: 'setPendingBossQuestion', params: { resumeStateId: source } },
+    ],
+  }) as const;
+
+const malformedPlayerOutputArm = {
+  target: '#failed',
+  actions: ['rememberMalformedPlayerOutput', 'clearBossReplyContext'],
+} as const;
+
+const playerOnError = {
+  target: '#failed',
+  actions: ['rememberActorError', 'clearBossReplyContext'],
+} as const;
+
+const reviewOnError = [
+  {
+    guard: 'authoredReviewFailure',
+    target: '#reviewFailed',
+    actions: 'rememberAuthoredReviewFailure',
+  },
+  { target: '#failed', actions: 'rememberActorError' },
+] as const;
+
+const meta = (stateId: StateKey, role?: CodeRole) => ({
+  playbook: {
+    stateId,
+    description: STATE_DESCRIPTIONS[stateId],
+    ...(role === undefined ? {} : { role }),
+  },
+});
+
+const finalMeta = (
+  stateId: 'reviewFailed' | 'done',
+  terminal: 'success' | 'failure',
+) => ({
+  playbook: {
+    stateId,
+    description: STATE_DESCRIPTIONS[stateId],
+    terminal,
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Machine
+// ---------------------------------------------------------------------------
+
+export const codeMachine = setup({
+  types: {
+    context: {} as CodeContext,
+    events: {} as CodeEvent,
+    input: {} as CodeInput,
+    output: {} as CodeOutput,
   },
   actors: {
     player: fromPromise<PlayerOutput, PlayerInput>(async () => {
       throw new Error('player actor must be provided by the runner');
     }),
-    playbook: fromPromise<JsonValue | undefined, PlaybookInput>(async () => {
+    playbook: fromPromise<PlaybookOutput, PlaybookInput>(async () => {
       throw new Error('playbook actor must be provided by the runner');
     }),
   },
-  guards: {
-    isDirectCommit,
-    isIrCommit,
-    isMoreTasks,
-    isFinalTask,
-    needsBossReply,
-    reviewApprovedDirect: reviewApprovedFor('direct'),
-    reviewApprovedIrCreated: reviewApprovedFor('ir-created'),
-    reviewApprovedMoreTasks: reviewApprovedFor('ir-task-more'),
-    reviewApprovedFinalTask: reviewApprovedFor('ir-task-final'),
-    authoredReviewFailure,
-    emptyBossReply: ({ event }) =>
-      event.type === 'BOSS_REPLY' && event.answer.trim().length === 0,
-    resumesFirstPhase: ({ context, event }) =>
-      event.type === 'BOSS_REPLY' &&
-      event.answer.trim().length > 0 &&
-      context.pendingBossQuestion?.resumeStateId === 'runFirstPhase' &&
-      (event.questionId === undefined || event.questionId === 'runFirstPhase'),
-    resumesIrTask: ({ context, event }) =>
-      event.type === 'BOSS_REPLY' &&
-      event.answer.trim().length > 0 &&
-      context.pendingBossQuestion?.resumeStateId === 'runIrTask' &&
-      (event.questionId === undefined || event.questionId === 'runIrTask'),
-  },
   actions: {
     'playbook.acceptedOutcome': (
       _args,
@@ -650,475 +812,382 @@ const machineSetup = setup({
         readonly acceptedOutcome: string;
       },
     ) => undefined,
-    startCoding: assign(({ context, event }) => {
-      if (event.type !== 'START_CODE') return {};
-      return {
-        runResults: context.runResults,
-        callerInput: event.callerInput,
-        coderOutput: undefined,
-        latestCommit: undefined,
-        irNumber: undefined,
-        irTask: undefined,
-        evaluatedRevision: undefined,
-        phase: undefined,
-        completion: undefined,
-        reviewError: undefined,
-        lastError: undefined,
-        pendingBossQuestion: undefined,
-        bossReply: undefined,
-      };
-    }),
-    rememberDirectCommit: assign(({ event }) => ({
-      coderOutput: outputString(event, 'coderOutput'),
-      latestCommit: outputString(event, 'latestCommit'),
-      phase: 'direct' as const,
-      pendingBossQuestion: undefined,
-      bossReply: undefined,
-    })),
-    rememberIrCommit: assign(({ event }) => ({
-      coderOutput: outputString(event, 'coderOutput'),
-      latestCommit: outputString(event, 'latestCommit'),
-      irNumber: outputString(event, 'irNumber'),
-      irTask: undefined,
-      phase: 'ir-created' as const,
-      pendingBossQuestion: undefined,
-      bossReply: undefined,
-    })),
-    rememberMoreTasks: assign(({ event }) => ({
-      coderOutput: outputString(event, 'coderOutput'),
-      latestCommit: outputString(event, 'latestCommit'),
-      irNumber: outputString(event, 'irNumber'),
-      irTask: outputString(event, 'irTask'),
-      phase: 'ir-task-more' as const,
-      pendingBossQuestion: undefined,
-      bossReply: undefined,
-    })),
-    rememberFinalTask: assign(({ event }) => ({
-      coderOutput: outputString(event, 'coderOutput'),
-      latestCommit: outputString(event, 'latestCommit'),
-      irNumber: outputString(event, 'irNumber'),
-      irTask: outputString(event, 'irTask'),
-      phase: 'ir-task-final' as const,
+    startCode: assign(({ context, event }) =>
+      event.type === 'START_CODE'
+        ? {
+            callerInput: event.callerInput,
+            runResults: event.runResults ?? context.runResults,
+            codeCommit: undefined,
+            coderOutput: undefined,
+            irNumber: undefined,
+            irTask: undefined,
+            phaseOutcome: undefined,
+            evaluatedRevision: undefined,
+            reviewError: undefined,
+            reviewEvidence: undefined,
+            lastError: undefined,
+            pendingBossQuestion: undefined,
+            bossReply: undefined,
+          }
+        : {},
+    ),
+    resetForInterrupt: assign({
+      phaseOutcome: undefined,
+      evaluatedRevision: undefined,
+      reviewError: undefined,
+      reviewEvidence: undefined,
+      lastError: undefined,
       pendingBossQuestion: undefined,
       bossReply: undefined,
-    })),
-    rememberPendingQuestion: assign(({ context, event }) => {
-      const question = outputString(event, 'question');
-      const output = playerOutput(event);
-      const stateId =
-        context.irNumber === undefined ? 'runFirstPhase' : 'runIrTask';
-      if (question === undefined || output?.guard !== 'needsBossReply') {
-        return { lastError: new Error('Coder question output was malformed') };
-      }
+    }),
+    rememberPhaseCommit: assign(({ event }) => {
+      const output = playerOutputOf(event);
+      if (output === undefined || output.guard === 'needsBossReply') return {};
       return {
-        pendingBossQuestion: {
-          questionId: stateId,
-          resumeStateId: stateId,
-          sourceItem: stateId === 'runFirstPhase' ? 'CODE-1' : 'CODE-3',
-          asker: { kind: 'role', roleId: 'coder' },
-          question,
-        },
-        bossReply: undefined,
+        codeCommit: output.latestCommit,
+        coderOutput: output.coderOutput,
+        phaseOutcome: output.guard,
+        irNumber: output.guard === 'directCommit' ? undefined : output.irNumber,
+        irTask:
+          output.guard === 'moreTasks' || output.guard === 'finalTask'
+            ? output.irTask
+            : undefined,
+        lastError: undefined,
       };
     }),
+    setPendingBossQuestion: assign(
+      ({ event }, params: { readonly resumeStateId: ResumableStateId }) => {
+        const output = playerOutputOf(event);
+        if (output?.guard !== 'needsBossReply') return {};
+        const pendingBossQuestion: PendingBossQuestion = {
+          questionId: params.resumeStateId,
+          resumeStateId: params.resumeStateId,
+          sourceItem: RESUME_METADATA[params.resumeStateId].sourceItem,
+          asker: { kind: 'role', roleId: 'coder' },
+          question: output.question,
+        };
+        return { pendingBossQuestion, bossReply: undefined, lastError: undefined };
+      },
+    ),
     rememberBossReply: assign(({ event }) =>
       event.type === 'BOSS_REPLY' ? { bossReply: event.answer } : {},
     ),
-    rememberEmptyBossReplyError: assign({
-      lastError: () => new Error('BOSS_REPLY received an empty answer'),
+    clearBossReplyContext: assign({
       pendingBossQuestion: undefined,
       bossReply: undefined,
     }),
-    completeSuccessfully: assign(({ event }) => {
-      const output = reviewOutput(event);
-      const approved = isReviewApprovedValue(output) ? output : undefined;
-      return {
-        completion: 'complete' as const,
-        evaluatedRevision: approved?.evaluatedRevision,
-        reviewError: undefined,
+    rememberReviewPass: assign(({ event }) => {
+      const pass = reviewPassOf(event);
+      return pass === undefined
+        ? {}
+        : { evaluatedRevision: pass.evaluatedRevision, lastError: undefined };
+    }),
+    rememberReviewNotPassed: assign(({ event }) => {
+      const output = doneOutputOf(event);
+      const reviewEvidence: CompletedReviewResult = {
+        playbookId: REVIEW_PLAYBOOK_ID,
+        status: 'ok',
+        ...(isJsonValue(output) ? { output } : {}),
       };
+      return { reviewEvidence, reviewError: REVIEW_NOT_PASSED, lastError: undefined };
+    }),
+    rememberAuthoredReviewFailure: assign(({ event }) => {
+      const failure = authoredReviewFailureOf(event);
+      return failure === undefined
+        ? {}
+        : {
+            reviewEvidence: failure.evidence,
+            reviewError: failure.error,
+            lastError: undefined,
+          };
     }),
-    completeWithReviewFailure: assign(({ event }) => ({
-      completion: 'review-failed' as const,
-      reviewError: authoredReviewError(event),
-    })),
-    completeWithInvalidReviewOutput: assign(({ event }) => ({
-      completion: 'review-failed' as const,
-      reviewError: {
-        name: 'ReviewContractError',
-        message:
-          `REVIEW returned an invalid approval result: ` +
-          JSON.stringify(reviewOutput(event)),
-      },
-    })),
     rememberActorError: assign(({ event }) => ({
-      lastError: (event as unknown as { readonly error?: unknown }).error,
-    })),
-    rememberMalformedPlayerOutput: assign(({ context }) => ({
-      lastError: new Error(
-        `Coder result for ${context.irNumber === undefined ? 'CODE-1' : 'CODE-3'} ` +
-          'did not match a declared outcome.',
-      ),
+      lastError: errorRecord(actorErrorOf(event)),
     })),
+    rememberMalformedPlayerOutput: assign(({ event }) => {
+      const output = doneOutputOf(event);
+      return {
+        lastError: {
+          name: 'MalformedPlayerOutput',
+          message:
+            isRecord(output) && output.guard === 'needsBossReply'
+              ? 'Coder output declared needsBossReply without a question.'
+              : 'Coder output did not match an outcome declared for the working state.',
+        },
+      };
+    }),
+    rememberMalformedBossReply: assign({
+      lastError: {
+        name: 'MalformedBossReply',
+        message: 'BOSS_REPLY carried an empty answer.',
+      },
+    }),
   },
-});
-
-export const codingMachine = machineSetup.createMachine({
+  guards: {
+    needsBossReplyWithQuestion,
+    acceptDirectCommit: acceptsOutcome('directCommit'),
+    acceptIrCommit: acceptsOutcome('irCommit'),
+    acceptMoreTasks: acceptsOutcome('moreTasks'),
+    acceptFinalTask: acceptsOutcome('finalTask'),
+    reviewPassedDirect: reviewPassedAfter('directCommit'),
+    reviewPassedNewIr: reviewPassedAfter('irCommit'),
+    reviewPassedNonfinalTask: reviewPassedAfter('moreTasks'),
+    reviewPassedFinalTask: reviewPassedAfter('finalTask'),
+    authoredReviewFailure,
+    validStartCode,
+    emptyBossReply,
+  },
+}).createMachine({
   id: 'code',
   initial: 'ready',
-  context: ({ input }) => ({
-    runResults: typeof input.runResults === 'string' ? input.runResults : '',
+  context: ({ input }): CodeContext => ({
+    runResults: typeof input?.runResults === 'string' ? input.runResults : '',
   }),
-  output: ({ context }): CodePlaybookOutput => {
-    const lastCodeCommit = context.latestCommit;
-    if (!isNonEmptyString(lastCodeCommit)) {
-      throw new Error('CODE reached a final state without a commit identity');
+  output: ({ context }): CodeOutput => {
+    if (!isNonEmptyString(context.codeCommit)) {
+      throw new Error(
+        'CODE reached a final state without its last code-owned commit',
+      );
     }
-    if (context.completion === 'review-failed') {
+    if (context.reviewError !== undefined) {
       return {
         status: 'review-failed',
-        lastCodeCommit,
-        error:
-          context.reviewError ?? {
-            name: 'Error',
-            message: 'REVIEW failed without error detail.',
-          },
+        lastCodeCommit: context.codeCommit,
+        error: context.reviewError,
       };
     }
-    const finalEvaluatedRevision = context.evaluatedRevision;
-    if (!isNonEmptyString(finalEvaluatedRevision)) {
-      throw new Error(
-        'CODE completed without an evaluated repository revision',
-      );
+    if (!isNonEmptyString(context.evaluatedRevision)) {
+      throw new Error('CODE completed without the final evaluated revision');
     }
     return {
       status: 'complete',
-      lastCodeCommit,
-      finalEvaluatedRevision,
+      lastCodeCommit: context.codeCommit,
+      finalEvaluatedRevision: context.evaluatedRevision,
       allReviewsPassed: true,
     };
   },
+  on: {
+    BOSS_INTERRUPT: bossInterrupts(['firstPhase', 'irTaskPhase'] as const),
+  },
   states: {
     ready: {
       id: 'ready',
+      tags: 'playbook.parked',
       description: STATE_DESCRIPTIONS.ready,
-      meta: playbookMeta('ready'),
-      tags: ['playbook.parked'],
+      meta: meta('ready'),
       on: {
-        START_CODE: { target: 'runFirstPhase', actions: 'startCoding' },
+        START_CODE: {
+          guard: 'validStartCode',
+          target: 'firstPhase',
+          actions: 'startCode',
+        },
       },
     },
-    runFirstPhase: {
-      id: 'runFirstPhase',
-      description: STATE_DESCRIPTIONS.runFirstPhase,
-      meta: playbookMeta('runFirstPhase', 'coder'),
-      tags: ['playbook.busy'],
+    firstPhase: {
+      id: 'firstPhase',
+      tags: 'playbook.busy',
+      description: STATE_DESCRIPTIONS.firstPhase,
+      meta: meta('firstPhase', 'coder'),
       invoke: {
         src: 'player',
-        input: ({ context }): PlayerInput => ({
-          stateId: 'runFirstPhase',
+        input: ({ context }): FirstPhasePlayerInput => ({
+          stateId: 'firstPhase',
           role: 'coder',
           sourceItem: 'CODE-1',
           prompt: FIRST_PHASE_PROMPT,
-          result: FIRST_PHASE_RESULTS,
-          callerInput: context.callerInput ?? '',
+          result: FIRST_PHASE_RESULT,
+          ...(context.callerInput !== undefined
+            ? { callerInput: context.callerInput }
+            : {}),
           runResults: context.runResults,
-          ...(context.pendingBossQuestion === undefined
-            ? {}
-            : { pendingBossQuestion: context.pendingBossQuestion }),
-          ...(context.bossReply === undefined
-            ? {}
-            : { bossReply: context.bossReply }),
+          ...bossReplyFields(context),
         }),
         onDone: [
-          {
-            guard: 'isDirectCommit',
-            target: 'reviewFirstCommit',
-            actions: [
-              {
-                type: 'playbook.acceptedOutcome',
-                params: {
-                  source: 'runFirstPhase',
-                  target: 'reviewFirstCommit',
-                  acceptedOutcome: 'directCommit',
-                },
-              },
-              'rememberDirectCommit',
-            ],
-          },
-          {
-            guard: 'isIrCommit',
-            target: 'reviewFirstCommit',
-            actions: [
-              {
-                type: 'playbook.acceptedOutcome',
-                params: {
-                  source: 'runFirstPhase',
-                  target: 'reviewFirstCommit',
-                  acceptedOutcome: 'irCommit',
-                },
-              },
-              'rememberIrCommit',
-            ],
-          },
-          {
-            guard: 'isMoreTasks',
-            target: 'reviewIrTask',
-            actions: [
-              {
-                type: 'playbook.acceptedOutcome',
-                params: {
-                  source: 'runFirstPhase',
-                  target: 'reviewIrTask',
-                  acceptedOutcome: 'moreTasks',
-                },
-              },
-              'rememberMoreTasks',
-            ],
-          },
-          {
-            guard: 'isFinalTask',
-            target: 'reviewIrTask',
-            actions: [
-              {
-                type: 'playbook.acceptedOutcome',
-                params: {
-                  source: 'runFirstPhase',
-                  target: 'reviewIrTask',
-                  acceptedOutcome: 'finalTask',
-                },
-              },
-              'rememberFinalTask',
-            ],
-          },
-          {
-            guard: 'needsBossReply',
-            target: 'awaitBossReply',
-            actions: [
-              {
-                type: 'playbook.acceptedOutcome',
-                params: {
-                  source: 'runFirstPhase',
-                  target: 'awaitBossReply',
-                  acceptedOutcome: 'needsBossReply',
-                },
-              },
-              'rememberPendingQuestion',
-            ],
-          },
-          {
-            target: 'failed',
-            actions: 'rememberMalformedPlayerOutput',
-          },
+          suspendArm('firstPhase'),
+          acceptPhaseArm(
+            'firstPhase',
+            'directCommit',
+            'acceptDirectCommit',
+            'reviewNewIntentPhase',
+          ),
+          acceptPhaseArm(
+            'firstPhase',
+            'irCommit',
+            'acceptIrCommit',
+            'reviewNewIntentPhase',
+          ),
+          acceptPhaseArm(
+            'firstPhase',
+            'moreTasks',
+            'acceptMoreTasks',
+            'reviewIrTaskPhase',
+          ),
+          acceptPhaseArm(
+            'firstPhase',
+            'finalTask',
+            'acceptFinalTask',
+            'reviewIrTaskPhase',
+          ),
+          malformedPlayerOutputArm,
         ],
-        onError: { target: 'failed', actions: 'rememberActorError' },
+        onError: playerOnError,
       },
     },
-    reviewFirstCommit: {
-      id: 'reviewFirstCommit',
-      description: STATE_DESCRIPTIONS.reviewFirstCommit,
-      meta: playbookMeta('reviewFirstCommit'),
-      tags: ['playbook.suspended'],
+    reviewNewIntentPhase: {
+      id: 'reviewNewIntentPhase',
+      tags: 'playbook.suspended',
+      description: STATE_DESCRIPTIONS.reviewNewIntentPhase,
+      meta: meta('reviewNewIntentPhase'),
       invoke: {
         src: 'playbook',
         input: ({ context }): PlaybookInput => ({
-          stateId: 'reviewFirstCommit',
+          stateId: 'reviewNewIntentPhase',
           sourceItem: 'CODE-2',
-          playbookId: 'review',
-          text: newIntentReviewText(context),
+          playbookId: REVIEW_PLAYBOOK_ID,
+          text: composeReviewText(REVIEW_NEW_INTENT_PHASE_TEMPLATE, {
+            '<caller-input>': context.callerInput,
+            '<code-commit>': context.codeCommit,
+            '<coder-output>': context.coderOutput,
+          }),
         }),
         onDone: [
           {
-            guard: 'reviewApprovedDirect',
+            guard: 'reviewPassedDirect',
             target: 'done',
-            actions: 'completeSuccessfully',
-          },
-          {
-            guard: 'reviewApprovedIrCreated',
-            target: 'runIrTask',
-          },
-          {
-            target: 'reportedReviewFailure',
-            actions: 'completeWithInvalidReviewOutput',
+            actions: 'rememberReviewPass',
           },
-        ],
-        onError: [
           {
-            guard: 'authoredReviewFailure',
-            target: 'reportedReviewFailure',
-            actions: 'completeWithReviewFailure',
+            guard: 'reviewPassedNewIr',
+            target: 'irTaskPhase',
+            actions: 'rememberReviewPass',
           },
-          { target: 'failed', actions: 'rememberActorError' },
+          { target: 'reviewFailed', actions: 'rememberReviewNotPassed' },
         ],
+        onError: reviewOnError,
       },
     },
-    runIrTask: {
-      id: 'runIrTask',
-      description: STATE_DESCRIPTIONS.runIrTask,
-      meta: playbookMeta('runIrTask', 'coder'),
-      tags: ['playbook.busy'],
+    irTaskPhase: {
+      id: 'irTaskPhase',
+      tags: 'playbook.busy',
+      description: STATE_DESCRIPTIONS.irTaskPhase,
+      meta: meta('irTaskPhase', 'coder'),
       invoke: {
         src: 'player',
-        input: ({ context }): PlayerInput => ({
-          stateId: 'runIrTask',
+        input: ({ context }): IrTaskPhasePlayerInput => ({
+          stateId: 'irTaskPhase',
           role: 'coder',
           sourceItem: 'CODE-3',
-          prompt: IR_TASK_PROMPT,
-          result: IR_TASK_RESULTS,
-          callerInput: context.callerInput ?? '',
+          prompt: IR_TASK_PHASE_PROMPT,
+          result: IR_TASK_PHASE_RESULT,
+          ...(context.callerInput !== undefined
+            ? { callerInput: context.callerInput }
+            : {}),
+          ...(context.irNumber !== undefined
+            ? { irNumber: context.irNumber }
+            : {}),
           runResults: context.runResults,
-          ...(context.irNumber === undefined
-            ? {}
-            : { irNumber: context.irNumber }),
-          ...(context.pendingBossQuestion === undefined
-            ? {}
-            : { pendingBossQuestion: context.pendingBossQuestion }),
-          ...(context.bossReply === undefined
-            ? {}
-            : { bossReply: context.bossReply }),
+          ...bossReplyFields(context),
         }),
         onDone: [
-          {
-            guard: 'isMoreTasks',
-            target: 'reviewIrTask',
-            actions: [
-              {
-                type: 'playbook.acceptedOutcome',
-                params: {
-                  source: 'runIrTask',
-                  target: 'reviewIrTask',
-                  acceptedOutcome: 'moreTasks',
-                },
-              },
-              'rememberMoreTasks',
-            ],
-          },
-          {
-            guard: 'isFinalTask',
-            target: 'reviewIrTask',
-            actions: [
-              {
-                type: 'playbook.acceptedOutcome',
-                params: {
-                  source: 'runIrTask',
-                  target: 'reviewIrTask',
-                  acceptedOutcome: 'finalTask',
-                },
-              },
-              'rememberFinalTask',
-            ],
-          },
-          {
-            guard: 'needsBossReply',
-            target: 'awaitBossReply',
-            actions: [
-              {
-                type: 'playbook.acceptedOutcome',
-                params: {
-                  source: 'runIrTask',
-                  target: 'awaitBossReply',
-                  acceptedOutcome: 'needsBossReply',
-                },
-              },
-              'rememberPendingQuestion',
-            ],
-          },
-          {
-            target: 'failed',
-            actions: 'rememberMalformedPlayerOutput',
-          },
+          suspendArm('irTaskPhase'),
+          acceptPhaseArm(
+            'irTaskPhase',
+            'moreTasks',
+            'acceptMoreTasks',
+            'reviewIrTaskPhase',
+          ),
+          acceptPhaseArm(
+            'irTaskPhase',
+            'finalTask',
+            'acceptFinalTask',
+            'reviewIrTaskPhase',
+          ),
+          malformedPlayerOutputArm,
         ],
-        onError: { target: 'failed', actions: 'rememberActorError' },
+        onError: playerOnError,
       },
     },
-    reviewIrTask: {
-      id: 'reviewIrTask',
-      description: STATE_DESCRIPTIONS.reviewIrTask,
-      meta: playbookMeta('reviewIrTask'),
-      tags: ['playbook.suspended'],
+    reviewIrTaskPhase: {
+      id: 'reviewIrTaskPhase',
+      tags: 'playbook.suspended',
+      description: STATE_DESCRIPTIONS.reviewIrTaskPhase,
+      meta: meta('reviewIrTaskPhase'),
       invoke: {
         src: 'playbook',
         input: ({ context }): PlaybookInput => ({
-          stateId: 'reviewIrTask',
+          stateId: 'reviewIrTaskPhase',
           sourceItem: 'CODE-4',
-          playbookId: 'review',
-          text: irTaskReviewText(context),
+          playbookId: REVIEW_PLAYBOOK_ID,
+          text: composeReviewText(REVIEW_IR_TASK_PHASE_TEMPLATE, {
+            '<caller-input>': context.callerInput,
+            '<code-commit>': context.codeCommit,
+            '<coder-output>': context.coderOutput,
+            '<ir-task>': context.irTask,
+          }),
         }),
         onDone: [
           {
-            guard: 'reviewApprovedMoreTasks',
-            target: 'runIrTask',
+            guard: 'reviewPassedNonfinalTask',
+            target: 'irTaskPhase',
+            actions: 'rememberReviewPass',
           },
           {
-            guard: 'reviewApprovedFinalTask',
+            guard: 'reviewPassedFinalTask',
             target: 'done',
-            actions: 'completeSuccessfully',
-          },
-          {
-            target: 'reportedReviewFailure',
-            actions: 'completeWithInvalidReviewOutput',
-          },
-        ],
-        onError: [
-          {
-            guard: 'authoredReviewFailure',
-            target: 'reportedReviewFailure',
-            actions: 'completeWithReviewFailure',
+            actions: 'rememberReviewPass',
           },
-          { target: 'failed', actions: 'rememberActorError' },
+          { target: 'reviewFailed', actions: 'rememberReviewNotPassed' },
         ],
+        onError: reviewOnError,
       },
     },
     awaitBossReply: {
       id: 'awaitBossReply',
+      tags: 'playbook.parked',
       description: STATE_DESCRIPTIONS.awaitBossReply,
-      meta: playbookMeta('awaitBossReply'),
-      tags: ['playbook.parked'],
+      meta: meta('awaitBossReply'),
       on: {
         BOSS_REPLY: [
           {
             guard: 'emptyBossReply',
-            target: '#failed',
-            actions: 'rememberEmptyBossReplyError',
-          },
-          {
-            guard: 'resumesFirstPhase',
-            target: '#runFirstPhase',
-            reenter: true,
-            actions: 'rememberBossReply',
-          },
-          {
-            guard: 'resumesIrTask',
-            target: '#runIrTask',
-            reenter: true,
-            actions: 'rememberBossReply',
+            target: 'failed',
+            actions: ['rememberMalformedBossReply', 'clearBossReplyContext'],
           },
+          ...resumableStates(['firstPhase', 'irTaskPhase'] as const),
         ],
-        START_CODE: { target: 'runFirstPhase', actions: 'startCoding' },
+        START_CODE: {
+          guard: 'validStartCode',
+          target: 'firstPhase',
+          actions: 'startCode',
+        },
       },
     },
     failed: {
       id: 'failed',
+      tags: 'playbook.parked',
       description: STATE_DESCRIPTIONS.failed,
-      meta: playbookMeta('failed'),
-      tags: ['playbook.parked'],
+      meta: meta('failed'),
       on: {
-        START_CODE: { target: 'runFirstPhase', actions: 'startCoding' },
+        START_CODE: {
+          guard: 'validStartCode',
+          target: 'firstPhase',
+          actions: 'startCode',
+        },
       },
     },
-    reportedReviewFailure: {
-      id: 'reportedReviewFailure',
-      description: STATE_DESCRIPTIONS.reportedReviewFailure,
-      meta: terminalMeta('reportedReviewFailure', 'failure'),
+    reviewFailed: {
+      id: 'reviewFailed',
       type: 'final',
+      description: STATE_DESCRIPTIONS.reviewFailed,
+      meta: finalMeta('reviewFailed', 'failure'),
     },
     done: {
       id: 'done',
-      description: STATE_DESCRIPTIONS.done,
-      meta: terminalMeta('done', 'success'),
       type: 'final',
+      description: STATE_DESCRIPTIONS.done,
+      meta: finalMeta('done', 'success'),
     },
   },
 });
 
-export default codingMachine;
+export default codeMachine;