@sublang/playbook 15.0.0 → 16.0.0

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

@@ -1,20 +1,19 @@
 // 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';
-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>.',
-];
+import { validatePlaybookCallResult } from '@sublang/playbook/xstate-runtime';
+/** One role-id array per parallel group; CODE declares no parallel group. */
+export const concurrentRoleSets = [];
+/** The literal nested-call target shared by both call states and guards. */
+const REVIEW_PLAYBOOK_ID = 'review';
+// ---------------------------------------------------------------------------
+// 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.',
     '',
@@ -30,320 +29,424 @@ 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 NEEDS_BOSS_REPLY_RESULT = "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 = {
-    directCommit: 'Coder completed and committed the direct implementation phase. 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.',
-    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.',
-    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,
+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_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_RESULT = {
+    directCommit: "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 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, 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, 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,
 };
-const IR_TASK_RESULTS = {
-    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.",
-    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,
+const IR_TASK_PHASE_RESULT = {
+    moreTasks: "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 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,
 };
 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.",
 };
-function playbookMeta(stateId, role) {
-    return {
-        playbook: {
-            stateId,
-            description: STATE_DESCRIPTIONS[stateId],
-            ...(role === undefined ? {} : { role }),
-        },
-    };
-}
-// 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, terminal) {
-    return {
-        playbook: {
-            stateId,
-            description: STATE_DESCRIPTIONS[stateId],
-            terminal,
-        },
-    };
-}
-function isRecord(value) {
-    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
-        return false;
-    }
-    const prototype = Object.getPrototypeOf(value);
-    return prototype === Object.prototype || prototype === null;
-}
-function isNonEmptyString(value) {
-    return typeof value === 'string' && value.trim().length > 0;
-}
-function playerOutput(event) {
-    if (!isRecord(event))
+const RESUME_METADATA = {
+    firstPhase: { sourceItem: 'CODE-1' },
+    irTaskPhase: { sourceItem: 'CODE-3' },
+};
+const REVIEW_NOT_PASSED = {
+    name: 'ReviewNotPassed',
+    message: 'review returned a terminal result that does not establish that the supplied scope was evaluated with no unsettled findings.',
+};
+// ---------------------------------------------------------------------------
+// Structural helpers
+// ---------------------------------------------------------------------------
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isNonEmptyString = (value) => typeof value === 'string' && value.trim().length > 0;
+const doneOutputOf = (event) => isRecord(event) ? event.output : undefined;
+const actorErrorOf = (event) => isRecord(event) ? event.error : undefined;
+/** Narrows a player done event to the declared player output contract. */
+function playerOutputOf(event) {
+    const output = doneOutputOf(event);
+    if (!isRecord(output))
         return undefined;
-    return isRecord(event.output) ? event.output : undefined;
-}
-function outputGuard(event, guard) {
-    return playerOutput(event)?.guard === guard;
-}
-function outputString(event, field) {
-    const value = playerOutput(event)?.[field];
-    return isNonEmptyString(value) ? value : undefined;
-}
-function hasCommittedOutput(event) {
-    return (outputString(event, 'coderOutput') !== undefined &&
-        outputString(event, 'latestCommit') !== undefined);
-}
-function hasIrTaskOutput(event) {
-    return (hasCommittedOutput(event) &&
-        outputString(event, 'irNumber') !== undefined &&
-        outputString(event, 'irTask') !== undefined);
-}
-function isDirectCommit({ event }) {
-    return (outputGuard(event, 'directCommit') &&
-        hasCommittedOutput(event));
-}
-function isIrCommit({ event }) {
-    return (outputGuard(event, 'irCommit') &&
-        hasCommittedOutput(event) &&
-        outputString(event, 'irNumber') !== undefined);
-}
-function isMoreTasks({ event }) {
-    return (outputGuard(event, 'moreTasks') &&
-        hasIrTaskOutput(event));
-}
-function isFinalTask({ event }) {
-    return (outputGuard(event, 'finalTask') &&
-        hasIrTaskOutput(event));
-}
-function needsBossReply({ event }) {
-    return (outputGuard(event, 'needsBossReply') &&
-        outputString(event, 'question') !== undefined);
-}
-function reviewOutput(event) {
-    return isRecord(event) ? event.output : undefined;
-}
-function isReviewApprovedValue(value) {
-    if (!isRecord(value))
-        return false;
-    if (Reflect.ownKeys(value).some((key) => typeof key !== 'string' ||
-        (key !== 'noUnsettledFindings' && key !== 'evaluatedRevision'))) {
-        return false;
+    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) {
-    return ({ context, event }) => context.phase === phase && isReviewApprovedValue(reviewOutput(event));
 }
-function isStateValue(value, ancestors = new Set()) {
-    if (typeof value === 'string')
+/**
+ * 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, path = new Set()) {
+    if (value === null)
         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) {
-    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) {
-    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;
+    switch (typeof value) {
+        case 'boolean':
+        case 'string':
+            return true;
+        case 'number':
+            return Number.isFinite(value);
+        case 'object':
+            break;
+        default:
+            return false;
     }
-    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) {
-    if (!(error instanceof Error))
-        return undefined;
-    const result = error.result;
-    return isRecord(result) ? result : undefined;
-}
-function isFailureTerminalRecord(value) {
-    if (!isRecord(value))
+    const container = value;
+    if (path.has(container))
         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'));
-}
-function normalizedReviewFailure(error) {
-    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)) {
-        return undefined;
-    }
-    if (result.status === 'ok') {
-        if (!Object.prototype.hasOwnProperty.call(result, 'terminal') ||
-            !isFailureTerminalRecord(result.terminal) ||
-            !isNonEmptyString(result.childSessionId)) {
-            return undefined;
+    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;
         }
-        return {
-            status: 'ok',
-            ...(result.output === undefined
-                ? {}
-                : { output: result.output }),
-        };
-    }
-    let normalizedError;
-    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;
+        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;
+            }
         }
-        normalizedError = {
-            name: result.error.name,
-            message: result.error.message,
-        };
+        return true;
     }
-    else if (result.status === 'error') {
-        return undefined;
+    finally {
+        path.delete(container);
     }
-    return {
-        status: result.status,
-        ...(normalizedError === undefined ? {} : { error: normalizedError }),
-    };
-}
-function authoredReviewFailure({ event }) {
-    const error = isRecord(event) ? event.error : undefined;
-    return normalizedReviewFailure(error) !== undefined;
 }
-function compactError(value) {
+/** Normalizes any thrown or malformed value to a JSON-safe error record. */
+function errorRecord(value) {
     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) };
 }
-function authoredReviewError(event) {
-    const outer = isRecord(event) ? event.error : undefined;
-    const failure = normalizedReviewFailure(outer);
-    if (failure !== undefined && failure.status !== 'ok' && failure.error) {
-        return failure.error;
+// ---------------------------------------------------------------------------
+// Nested `review` results
+// ---------------------------------------------------------------------------
+/**
+ * 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) {
+    const output = doneOutputOf(event);
+    if (!isRecord(output))
+        return undefined;
+    return output.noUnsettledFindings === true &&
+        isNonEmptyString(output.evaluatedRevision)
+        ? { noUnsettledFindings: true, evaluatedRevision: output.evaluatedRevision }
+        : undefined;
+}
+/**
+ * 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, expectedPlaybookId) {
+    if (!(error instanceof Error))
+        return undefined;
+    try {
+        const result = validatePlaybookCallResult(error.result, expectedPlaybookId);
+        return result.status !== 'ok' || result.terminal?.kind === 'failure'
+            ? result
+            : undefined;
     }
-    if (failure?.status === 'aborted') {
-        return { name: 'AbortError', message: 'REVIEW was aborted.' };
+    catch {
+        return undefined;
     }
-    return compactError(outer);
 }
-function quoteRelay(label, value) {
-    const lines = value.split('\n');
-    return [`> ${label}: ${lines[0] ?? ''}`, ...lines.slice(1).map((line) => `> ${line}`)].join('\n');
+/** Compact evidence and reported error for an authored review failure. */
+function authoredReviewFailureOf(event) {
+    const result = authoredChildResult(actorErrorOf(event), REVIEW_PLAYBOOK_ID);
+    if (result === undefined)
+        return undefined;
+    if (result.status === 'ok') {
+        const description = result.terminal?.description;
+        return {
+            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.',
+            },
+        };
+    }
+    const error = result.error !== undefined
+        ? { name: result.error.name, message: result.error.message }
+        : { name: 'AbortError', message: 'The review call was aborted.' };
+    return {
+        evidence: { playbookId: REVIEW_PLAYBOOK_ID, status: result.status, error },
+        error,
+    };
 }
-function reviewScopeLine(context) {
-    return (`> Review scope: the commit ${context.latestCommit ?? ''} ` +
-        'from this coding phase and its resulting repository state.');
+// ---------------------------------------------------------------------------
+// Nested call text composition (quoted relays)
+// ---------------------------------------------------------------------------
+const REVIEW_PLACEHOLDER = /<caller-input>|<code-commit>|<coder-output>|<ir-task>/g;
+/**
+ * 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, values) {
+    const lines = [];
+    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) => {
+            const value = values[token];
+            if (value === undefined)
+                return token;
+            return quoted ? value.split('\n').join('\n> ') : value;
+        }));
+    }
+    while (lines.length > 0 && lines[lines.length - 1] === '')
+        lines.pop();
+    return lines.join('\n');
 }
-function newIntentReviewText(context) {
-    return [
-        quoteRelay('Original intent', context.callerInput ?? ''),
-        reviewScopeLine(context),
-        quoteRelay('Coder output', context.coderOutput ?? ''),
-    ].join('\n');
+const acceptsOutcome = (outcome) => ({ event }) => playerOutputOf(event)?.guard === outcome;
+const needsBossReplyWithQuestion = ({ event }) => 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) => ({ context, event }) => context.phaseOutcome === outcome &&
+    isNonEmptyString(context.codeCommit) &&
+    reviewPassOf(event) !== undefined;
+const authoredReviewFailure = ({ event }) => authoredReviewFailureOf(event) !== undefined;
+const validStartCode = ({ event }) => event.type === 'START_CODE' &&
+    isNonEmptyString(event.callerInput) &&
+    (event.runResults === undefined || typeof event.runResults === 'string');
+const repliesToPendingQuestion = ({ context, event }) => event.type === 'BOSS_REPLY' &&
+    context.pendingBossQuestion !== undefined &&
+    (event.questionId === undefined ||
+        event.questionId === context.pendingBossQuestion.questionId);
+const emptyBossReply = (args) => repliesToPendingQuestion(args) &&
+    args.event.type === 'BOSS_REPLY' &&
+    !isNonEmptyString(args.event.answer);
+const INTERRUPT_PRECONDITIONS = {
+    firstPhase: (context) => isNonEmptyString(context.callerInput),
+    irTaskPhase: (context) => isNonEmptyString(context.callerInput) &&
+        isNonEmptyString(context.irNumber),
+};
+// ---------------------------------------------------------------------------
+// Transition helpers
+// ---------------------------------------------------------------------------
+/** One guarded root transition per jumpable state. */
+function bossInterrupts(ids) {
+    return ids.map((id) => ({
+        guard: ({ context, event }) => event.type === 'BOSS_INTERRUPT' &&
+            event.targetId === id &&
+            INTERRUPT_PRECONDITIONS[id](context),
+        target: `#${id}`,
+        reenter: true,
+        actions: 'resetForInterrupt',
+    }));
 }
-function irTaskReviewText(context) {
-    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(ids) {
+    return ids.map((id) => ({
+        guard: (args) => repliesToPendingQuestion(args) &&
+            args.event.type === 'BOSS_REPLY' &&
+            isNonEmptyString(args.event.answer) &&
+            args.context.pendingBossQuestion?.resumeStateId === id,
+        target: `#${id}`,
+        reenter: true,
+        actions: 'rememberBossReply',
+    }));
 }
-const machineSetup = setup({
-    types: {},
+const bossReplyFields = (context) => ({
+    ...(context.pendingBossQuestion !== undefined
+        ? { pendingBossQuestion: context.pendingBossQuestion }
+        : {}),
+    ...(context.bossReply !== undefined ? { bossReply: context.bossReply } : {}),
+});
+const acceptedOutcome = (source, target, outcome) => ({
+    type: 'playbook.acceptedOutcome',
+    params: { source, target, acceptedOutcome: outcome },
+});
+const acceptPhaseArm = (source, outcome, guard, target) => ({
+    guard,
+    target: `#${target}`,
+    actions: [
+        acceptedOutcome(source, target, outcome),
+        'rememberPhaseCommit',
+        'clearBossReplyContext',
+    ],
+});
+const suspendArm = (source) => ({
+    guard: 'needsBossReplyWithQuestion',
+    target: '#awaitBossReply',
+    actions: [
+        acceptedOutcome(source, 'awaitBossReply', 'needsBossReply'),
+        { type: 'setPendingBossQuestion', params: { resumeStateId: source } },
+    ],
+});
+const malformedPlayerOutputArm = {
+    target: '#failed',
+    actions: ['rememberMalformedPlayerOutput', 'clearBossReplyContext'],
+};
+const playerOnError = {
+    target: '#failed',
+    actions: ['rememberActorError', 'clearBossReplyContext'],
+};
+const reviewOnError = [
+    {
+        guard: 'authoredReviewFailure',
+        target: '#reviewFailed',
+        actions: 'rememberAuthoredReviewFailure',
+    },
+    { target: '#failed', actions: 'rememberActorError' },
+];
+const meta = (stateId, role) => ({
+    playbook: {
+        stateId,
+        description: STATE_DESCRIPTIONS[stateId],
+        ...(role === undefined ? {} : { role }),
+    },
+});
+const finalMeta = (stateId, terminal) => ({
+    playbook: {
+        stateId,
+        description: STATE_DESCRIPTIONS[stateId],
+        terminal,
+    },
+});
+// ---------------------------------------------------------------------------
+// Machine
+// ---------------------------------------------------------------------------
+export const codeMachine = setup({
+    types: {
+        context: {},
+        events: {},
+        input: {},
+        output: {},
+    },
     actors: {
         player: fromPromise(async () => {
             throw new Error('player actor must be provided by the runner');
@@ -352,488 +455,345 @@ const machineSetup = setup({
             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, _params) => undefined,
-        startCoding: assign(({ context, event }) => {
-            if (event.type !== 'START_CODE')
-                return {};
-            return {
-                runResults: context.runResults,
+        startCode: assign(({ context, event }) => event.type === 'START_CODE'
+            ? {
                 callerInput: event.callerInput,
+                runResults: event.runResults ?? context.runResults,
+                codeCommit: undefined,
                 coderOutput: undefined,
-                latestCommit: undefined,
                 irNumber: undefined,
                 irTask: undefined,
+                phaseOutcome: undefined,
                 evaluatedRevision: undefined,
-                phase: undefined,
-                completion: undefined,
                 reviewError: undefined,
+                reviewEvidence: undefined,
                 lastError: undefined,
                 pendingBossQuestion: undefined,
                 bossReply: undefined,
-            };
-        }),
-        rememberDirectCommit: assign(({ event }) => ({
-            coderOutput: outputString(event, 'coderOutput'),
-            latestCommit: outputString(event, 'latestCommit'),
-            phase: 'direct',
-            pendingBossQuestion: undefined,
-            bossReply: undefined,
-        })),
-        rememberIrCommit: assign(({ event }) => ({
-            coderOutput: outputString(event, 'coderOutput'),
-            latestCommit: outputString(event, 'latestCommit'),
-            irNumber: outputString(event, 'irNumber'),
-            irTask: undefined,
-            phase: 'ir-created',
-            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',
-            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',
+            }
+            : {}),
+        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) => {
+            const output = playerOutputOf(event);
+            if (output?.guard !== 'needsBossReply')
+                return {};
+            const 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',
-                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 = {
+                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',
-            reviewError: authoredReviewError(event),
-        })),
-        completeWithInvalidReviewOutput: assign(({ event }) => ({
-            completion: 'review-failed',
-            reviewError: {
-                name: 'ReviewContractError',
-                message: `REVIEW returned an invalid approval result: ` +
-                    JSON.stringify(reviewOutput(event)),
-            },
-        })),
         rememberActorError: assign(({ event }) => ({
-            lastError: event.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 : '',
+        runResults: typeof input?.runResults === 'string' ? input.runResults : '',
     }),
     output: ({ context }) => {
-        const lastCodeCommit = context.latestCommit;
-        if (!isNonEmptyString(lastCodeCommit)) {
-            throw new Error('CODE reached a final state without a commit identity');
+        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']),
+    },
     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 }) => ({
-                    stateId: 'runFirstPhase',
+                    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 }) => ({
-                    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',
+                        actions: 'rememberReviewPass',
                     },
                     {
-                        guard: 'reviewApprovedIrCreated',
-                        target: 'runIrTask',
+                        guard: 'reviewPassedNewIr',
+                        target: 'irTaskPhase',
+                        actions: 'rememberReviewPass',
                     },
-                    {
-                        target: 'reportedReviewFailure',
-                        actions: 'completeWithInvalidReviewOutput',
-                    },
-                ],
-                onError: [
-                    {
-                        guard: 'authoredReviewFailure',
-                        target: 'reportedReviewFailure',
-                        actions: 'completeWithReviewFailure',
-                    },
-                    { 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 }) => ({
-                    stateId: 'runIrTask',
+                    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 }) => ({
-                    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',
+                        actions: 'rememberReviewPass',
                     },
-                    {
-                        target: 'reportedReviewFailure',
-                        actions: 'completeWithInvalidReviewOutput',
-                    },
-                ],
-                onError: [
-                    {
-                        guard: 'authoredReviewFailure',
-                        target: 'reportedReviewFailure',
-                        actions: 'completeWithReviewFailure',
-                    },
-                    { 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']),
                 ],
-                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;