@sublang/playbook 5.0.0 → 7.0.0

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

@@ -1,1445 +1,685 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
-// XState v5's generics do not flow through helpers declared outside the
-// machine (e.g., shared guard/action factories, the `readyEvents` block),
-// so strict checking emits structural-mismatch noise without surfacing real
-// bugs. The runner overrides `player` via `.provide({ actors: { ... } })`
-// and re-asserts the public surface (`CodingContext`, `CodingEvent`,
-// `PlayerInput`, `PlayerOutput`) at the boundary.
-// @ts-nocheck
+//
+// Generated by slc/gears2fsm.md from ./code.gears.md.
 import { assign, fromPromise, setup } from 'xstate';
-const jumpableStateIds = [
-    'ready',
-    'planAndImplement',
-    'respondToReview',
-    'continueIr',
-    'summarizeSpecs',
-    'reviewBossCommitSpecs',
-    'reviewBossCommitCode',
-    'reviewBossCommitMixed',
-    'reviewIrTaskCommitSpecs',
-    'reviewIrTaskCommitCode',
-    'reviewIrTaskCommitMixed',
-    'reviewChangesSpecs',
-    'reviewChangesCode',
-    'reviewChangesMixed',
-    'reviewChangesAndChallengesSpecs',
-    'reviewChangesAndChallengesCode',
-    'reviewChangesAndChallengesMixed',
-    'adjudicateChallenges',
-    'commitCoderInitial',
-    'commitJoint',
-    'failed',
-];
-const resumableStateIds = [
-    'planAndImplement',
-    'respondToReview',
-    'continueIr',
-    'summarizeSpecs',
-    'reviewBossCommitSpecs',
-    'reviewBossCommitCode',
-    'reviewBossCommitMixed',
-    'reviewIrTaskCommitSpecs',
-    'reviewIrTaskCommitCode',
-    'reviewIrTaskCommitMixed',
-    'reviewChangesSpecs',
-    'reviewChangesCode',
-    'reviewChangesMixed',
-    'reviewChangesAndChallengesSpecs',
-    'reviewChangesAndChallengesCode',
-    'reviewChangesAndChallengesMixed',
-    'adjudicateChallenges',
-    'commitCoderInitial',
-    'commitJoint',
-];
-const stateDescriptions = {
-    ready: 'Idle hub: waits for Boss to start or resume a coding sub-procedure.',
-    awaitBossReply: 'Waiting for Boss to answer a player question.',
-    planAndImplement: 'CODE-1: Coder assesses a Boss intent and either implements a single-commit change or drafts an IR.',
-    respondToReview: 'CODE-2: Coder addresses or challenges Reviewer findings.',
-    continueIr: 'CODE-3: Coder continues an IR after the previous task or IR draft passed review.',
-    summarizeSpecs: 'CODE-4: Coder summarizes a completed IR into minimal spec items.',
-    reviewBossCommitSpecs: 'CODE-5: Reviewer reviews a Boss-intent commit whose changes are only in spec item files.',
-    reviewBossCommitCode: 'CODE-6: Reviewer reviews a Boss-intent commit whose changes are only outside spec item files.',
-    reviewBossCommitMixed: 'CODE-7: Reviewer reviews a Boss-intent commit whose changes span both spec item files and other files.',
-    reviewIrTaskCommitSpecs: 'CODE-8: Reviewer reviews an IR-task commit whose changes are only in spec item files.',
-    reviewIrTaskCommitCode: 'CODE-9: Reviewer reviews an IR-task commit whose changes are only outside spec item files.',
-    reviewIrTaskCommitMixed: 'CODE-10: Reviewer reviews an IR-task commit whose changes span both spec item files and other files.',
-    reviewChangesSpecs: 'CODE-11: Reviewer reviews uncommitted Coder changes that touch only spec item files with no accompanying rebuttals.',
-    reviewChangesCode: 'CODE-12: Reviewer reviews uncommitted Coder changes that touch only files outside spec item files with no accompanying rebuttals.',
-    reviewChangesMixed: 'CODE-13: Reviewer reviews uncommitted Coder changes that touch both spec item files and other files with no accompanying rebuttals.',
-    reviewChangesAndChallengesSpecs: 'CODE-15: Reviewer reviews uncommitted Coder changes that touch only spec item files and adjudicates accompanying rebuttals in one round.',
-    reviewChangesAndChallengesCode: 'CODE-16: Reviewer reviews uncommitted Coder changes that touch only files outside spec item files and adjudicates accompanying rebuttals in one round.',
-    reviewChangesAndChallengesMixed: 'CODE-17: Reviewer reviews uncommitted Coder changes that touch both spec item files and other files and adjudicates accompanying rebuttals in one round.',
-    adjudicateChallenges: 'CODE-14: Reviewer adjudicates Coder rebuttals against the prior review when Coder produced no code edits this round.',
-    commitCoderInitial: 'CODE-18: Committer commits Coder Initial Changes when Reviewer has not played since the last commit.',
-    commitJoint: 'CODE-19: Committer commits changes when both Coder and Reviewer have played since the last commit.',
-    failed: 'Captures the last Captain error so the runner can report it. Boss may resume from here.',
-    done: 'The selected coding workflow has completed.',
+const FIRST_PHASE_PROMPT = [
+    '> <caller-input>',
+    '> <run-results>',
+    '',
+    'Assess whether the coding intent can be completed well in one commit.',
+    'If yes, implement and test it, update the affected specs, and ensure @specs/map.md remains accurate.',
+    'Otherwise, decompose it into tasks sized to exactly one commit each, add a new IR under @specs/intents, and do not implement any IR task in this phase.',
+    'Plan affected spec updates before, with, or after their corresponding code changes, either as standalone IR tasks or as explicit work within related tasks.',
+    '',
+    'Consult @specs/map.md for relevant context and @specs/meta.md for spec requirements, if needed.',
+    '',
+    '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.',
+    'Report it as exactly one final-response line beginning `Commit: `, followed only by the exact commit identity.',
+    'Coder is <coder-llm>; format the model token in conventional human form.',
+].join('\n');
+const IR_TASK_PROMPT = [
+    '> <ir-task>',
+    '> <run-results>',
+    '',
+    'Read IR-<#> and implement exactly the 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.',
+    '',
+    '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.',
+    'Report it as exactly one final-response line beginning `Commit: `, followed only by the exact commit identity.',
+    'Coder is <coder-llm>; format the model token in conventional human form.',
+].join('\n');
+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>`, `irNumber`, and `irTask` naming the exact next unfinished task.',
+    needsBossReply: "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 playbookMeta = (stateId) => ({
-    playbook: {
-        stateId,
-        description: stateDescriptions[stateId],
-    },
-});
-const outputOf = (event) => event.output;
-const guardIs = (guard) => ({ event }) => outputOf(event)?.guard === guard;
-const guardAndOrigin = (guard, origin) => ({ context, event }) => outputOf(event)?.guard === guard && context.changeOrigin === origin;
-const acceptedAfter = (subject) => ({ context, event }) => outputOf(event)?.guard === 'accepted' && context.reviewSubject === subject;
-const noFindingsAfter = (afterReview) => ({ context, event }) => outputOf(event)?.guard === 'noFindings' &&
-    context.afterReview === afterReview;
-const rememberCaptainOutput = assign({
-    lastResult: ({ event }) => outputOf(event),
-    lastError: () => undefined,
-    irNumber: ({ context, event }) => outputOf(event)?.irNumber ?? context.irNumber,
-    taskDescription: ({ context, event, }) => outputOf(event)?.taskDescription ?? context.taskDescription,
-    reviews: ({ context, event }) => outputOf(event)?.reviews ?? context.reviews,
-    challenges: ({ context, event, }) => outputOf(event)?.challenges ?? context.challenges,
-});
-const rememberCaptainError = assign({
-    lastError: ({ event }) => event.error,
-});
-const rememberEmptyBossReplyError = assign({
-    lastError: () => new Error('BOSS_REPLY received empty answer'),
-});
-const rememberBossInput = assign({
-    intent: ({ context, event }) => event.intent ?? context.intent,
-    irNumber: ({ context, event }) => event.irNumber ?? context.irNumber,
-});
-const needsBossReplyDescription = "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 bossReplyInputFields = (context) => ({
-    pendingBossQuestion: context.pendingBossQuestion,
-    bossReply: context.bossReply,
-});
-const withNeedsBossReply = (result) => ({
-    ...result,
-    needsBossReply: needsBossReplyDescription,
-});
-const captainStateMetadata = {
-    planAndImplement: { sourceItem: 'CODE-1', player: 'Coder' },
-    respondToReview: { sourceItem: 'CODE-2', player: 'Coder' },
-    continueIr: { sourceItem: 'CODE-3', player: 'Coder' },
-    summarizeSpecs: { sourceItem: 'CODE-4', player: 'Coder' },
-    reviewBossCommitSpecs: { sourceItem: 'CODE-5', player: 'Reviewer' },
-    reviewBossCommitCode: { sourceItem: 'CODE-6', player: 'Reviewer' },
-    reviewBossCommitMixed: { sourceItem: 'CODE-7', player: 'Reviewer' },
-    reviewIrTaskCommitSpecs: { sourceItem: 'CODE-8', player: 'Reviewer' },
-    reviewIrTaskCommitCode: { sourceItem: 'CODE-9', player: 'Reviewer' },
-    reviewIrTaskCommitMixed: { sourceItem: 'CODE-10', player: 'Reviewer' },
-    reviewChangesSpecs: { sourceItem: 'CODE-11', player: 'Reviewer' },
-    reviewChangesCode: { sourceItem: 'CODE-12', player: 'Reviewer' },
-    reviewChangesMixed: { sourceItem: 'CODE-13', player: 'Reviewer' },
-    reviewChangesAndChallengesSpecs: {
-        sourceItem: 'CODE-15',
-        player: 'Reviewer',
-    },
-    reviewChangesAndChallengesCode: { sourceItem: 'CODE-16', player: 'Reviewer' },
-    reviewChangesAndChallengesMixed: {
-        sourceItem: 'CODE-17',
-        player: 'Reviewer',
-    },
-    adjudicateChallenges: { sourceItem: 'CODE-14', player: 'Reviewer' },
-    commitCoderInitial: { sourceItem: 'CODE-18', player: 'Committer' },
-    commitJoint: { sourceItem: 'CODE-19', player: 'Committer' },
+const IR_TASK_RESULTS = {
+    moreTasks: 'Coder completed and committed the current IR task and at least one task remains. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, and `irTask` naming the exact next unfinished task.',
+    finalTask: 'Coder completed and committed the final IR task. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.',
+    needsBossReply: "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 planAndImplementInput = (context) => ({
-    stateId: 'planAndImplement',
-    player: 'Coder',
-    sourceItem: 'CODE-1',
-    intent: context.intent,
-    ...bossReplyInputFields(context),
-    prompt: [
-        'Assess whether this can be completed in a single commit, following best practices.',
-        'If yes, implement and test, updating both code and specs; otherwise, decompose into tasks as a new IR under @specs/intents (or @specs/iterations in older scaffolds) and stop without implementing any IR task.',
-        'For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.',
-        'Ensure @specs/map.md reflects the changes.',
-        'Do not commit.',
-    ].join('\n'),
-    result: withNeedsBossReply({
-        singleCommitReady: 'Coder produced uncommitted single-commit changes (Initial Changes).',
-        irDrafted: 'Coder decomposed the intent into a new IR and drafted it uncommitted (Initial Changes).',
-    }),
-});
-const continueIrInput = (context) => ({
-    stateId: 'continueIr',
-    player: 'Coder',
-    sourceItem: 'CODE-3',
-    irNumber: context.irNumber,
-    ...bossReplyInputFields(context),
-    prompt: [
-        'Continue to implement IR-<#> if not all deliverables and tasks are done.',
-        'Implement one task at a time (including corresponding tests if any).',
-        'Stop after each task for review — do not commit yet.',
-        'If relevant, mark progress in the IR.',
-    ].join('\n'),
-    result: withNeedsBossReply({
-        taskReady: 'Coder produced uncommitted changes for the next IR task (Initial Changes). Output shall include `taskDescription: <one-line description of the task just implemented>`.',
-        iterationDone: 'All IR deliverables and tasks are done.',
-    }),
-});
-const summarizeSpecsInput = (context) => ({
-    stateId: 'summarizeSpecs',
-    player: 'Coder',
-    sourceItem: 'CODE-4',
-    irNumber: context.irNumber,
-    ...bossReplyInputFields(context),
-    prompt: [
-        'Read IR-<#> and corresponding commits.',
-        'According to @specs/meta.md, add or update spec items to fully capture:',
-        '',
-        '- the external behavior users rely on,',
-        '- the internal system behavior, and',
-        '- the integration/system test cases.',
-        '',
-        'The spec items should be the *minimal* set needed to reimplement code without the IR.',
-        'The set should be complete and coherent.',
-        'Avoid implementation specifics.',
-        'Avoid redundant spec items.',
-        'Ensure @specs/map.md reflects the changes.',
-    ].join('\n'),
-    result: withNeedsBossReply({
-        specsReady: 'Coder produced uncommitted spec updates (Initial Changes).',
-        noSpecChanges: 'Existing specs already capture the realized intent.',
-    }),
-});
-const setPendingBossQuestion = (resumeStateId) => assign({
-    pendingBossQuestion: ({ context, event, }) => {
-        const input = captainStateMetadata[resumeStateId];
+const STATE_DESCRIPTIONS = {
+    ready: 'Waiting for a coding intent.',
+    runFirstPhase: 'Coder is implementing one direct phase or committing a new intent record.',
+    reviewFirstCommit: 'The REVIEW playbook is checking the first 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.',
+    done: 'The coding workflow completed after REVIEW found no unsettled findings.',
+};
+function playbookMeta(stateId, player) {
+    return {
+        playbook: {
+            stateId,
+            description: STATE_DESCRIPTIONS[stateId],
+            ...(player === undefined ? {} : { player }),
+        },
+    };
+}
+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))
+        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 commitOutput(event) {
+    const coderOutput = outputString(event, 'coderOutput');
+    const latestCommit = outputString(event, 'latestCommit');
+    const commitLines = coderOutput
+        ?.split('\n')
+        .filter((line) => line.startsWith('Commit: '));
+    if (coderOutput === undefined ||
+        latestCommit === undefined ||
+        commitLines?.length !== 1 ||
+        commitLines[0] !== `Commit: ${latestCommit}`) {
+        return undefined;
+    }
+    return { coderOutput, latestCommit };
+}
+function isDirectCommit({ event }) {
+    return (outputGuard(event, 'directCommit') &&
+        commitOutput(event) !== undefined);
+}
+function isIrCommit({ event }) {
+    return (outputGuard(event, 'irCommit') &&
+        commitOutput(event) !== undefined &&
+        outputString(event, 'irNumber') !== undefined &&
+        outputString(event, 'irTask') !== undefined);
+}
+function isMoreTasks({ event }) {
+    return (outputGuard(event, 'moreTasks') &&
+        commitOutput(event) !== undefined &&
+        outputString(event, 'irTask') !== undefined);
+}
+function isFinalTask({ event }) {
+    return (outputGuard(event, 'finalTask') &&
+        commitOutput(event) !== undefined);
+}
+function needsBossReply({ event }) {
+    return (outputGuard(event, 'needsBossReply') &&
+        outputString(event, 'question') !== undefined);
+}
+function reviewOutput(event) {
+    return isRecord(event) ? event.output : undefined;
+}
+function isReviewApprovedValue(value) {
+    return (isRecord(value) &&
+        Object.keys(value).sort().join('\0') ===
+            ['approvedCommit', 'noUnsettledFindings'].sort().join('\0') &&
+        value.approvedCommit === 'latest' &&
+        value.noUnsettledFindings === true);
+}
+function reviewApprovedFor(phase) {
+    return ({ context, event }) => context.phase === phase && isReviewApprovedValue(reviewOutput(event));
+}
+function isStateValue(value, ancestors = new Set()) {
+    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) {
+    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;
+    }
+    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 normalizedReviewFailure(error) {
+    const result = nestedResultFromError(error);
+    if (result === undefined)
+        return undefined;
+    const allowed = new Set([
+        'status',
+        'playbookId',
+        'childSessionId',
+        'state',
+        'error',
+    ]);
+    if (Reflect.ownKeys(result).some((key) => typeof key !== 'string' || !allowed.has(key)) ||
+        (result.status !== 'aborted' && result.status !== 'error') ||
+        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;
+    }
+    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;
+        }
+        normalizedError = {
+            name: result.error.name,
+            message: result.error.message,
+        };
+    }
+    else if (result.status === 'error') {
+        return undefined;
+    }
+    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) {
+    if (value instanceof Error) {
         return {
-            questionId: resumeStateId,
-            resumeStateId,
-            sourceItem: input.sourceItem,
-            player: input.player,
-            question: outputOf(event)?.question ?? '',
+            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?.error !== undefined)
+        return failure.error;
+    if (failure?.status === 'aborted') {
+        return { name: 'AbortError', message: 'REVIEW was aborted.' };
+    }
+    return compactError(outer);
+}
+function quoteRelay(label, value) {
+    const lines = value.split('\n');
+    return [`> ${label}: ${lines[0] ?? ''}`, ...lines.slice(1).map((line) => `> ${line}`)].join('\n');
+}
+function initialReviewText(context) {
+    return [
+        quoteRelay('Initial intent', context.callerInput ?? ''),
+        quoteRelay('Coder output', context.coderOutput ?? ''),
+    ].join('\n');
+}
+function irTaskReviewText(context) {
+    return [
+        quoteRelay('IR task', context.irTask ?? ''),
+        quoteRelay('Coder output', context.coderOutput ?? ''),
+    ].join('\n');
+}
+const machineSetup = setup({
+    types: {},
+    actors: {
+        player: fromPromise(async () => {
+            throw new Error('player actor must be provided by the runner');
+        }),
+        playbook: fromPromise(async () => {
+            throw new Error('playbook actor must be provided by the runner');
+        }),
     },
-    bossReply: () => undefined,
-});
-const rememberBossReply = assign({
-    bossReply: ({ event }) => event.answer ?? '',
-});
-const clearBossReplyContext = assign({
-    pendingBossQuestion: () => undefined,
-    bossReply: () => undefined,
-});
-const actionsArray = (actions) => actions === undefined ? [] : Array.isArray(actions) ? actions : [actions];
-const withClearBossReplyContext = (transition) => ({
-    ...transition,
-    actions: [clearBossReplyContext, ...actionsArray(transition.actions)],
-});
-const bossInterrupts = (ids, extraActions = []) => ids.map((id) => ({
-    target: `#${id}`,
-    guard: ({ event }) => event.type === 'BOSS_INTERRUPT' && event.targetId === id,
-    reenter: true,
-    actions: [...extraActions, rememberBossInput],
-}));
-const resumableStates = (ids) => ids.map((id) => ({
-    target: `#${id}`,
-    guard: ({ context, event, }) => event.type === 'BOSS_REPLY' &&
-        context.pendingBossQuestion?.resumeStateId === id &&
-        (event.questionId === undefined ||
-            event.questionId === context.pendingBossQuestion.questionId),
-    reenter: true,
-    actions: rememberBossReply,
-}));
-const bossReplyIsEmpty = ({ event }) => event.type === 'BOSS_REPLY' && event.answer.trim() === '';
-const withNeedsBossReplyTransition = (resumeStateId, transitions) => [
-    ...transitions.map((transition) => withClearBossReplyContext(transition)),
-    {
-        guard: guardIs('needsBossReply'),
-        target: '#awaitBossReply',
-        actions: [rememberCaptainOutput, setPendingBossQuestion(resumeStateId)],
-    },
-];
-const captainError = {
-    target: '#failed',
-    actions: rememberCaptainError,
-};
-const readyEvents = {
-    START_CODING: {
-        target: '#planAndImplement',
-        actions: [
-            rememberBossInput,
-            assign({
-                workflow: () => 'singleCommit',
-                changeOrigin: () => 'bossIntent',
-                afterReview: () => 'done',
-            }),
-        ],
-    },
-    CONTINUE_IR: {
-        target: '#continueIr',
-        actions: [
-            rememberBossInput,
-            assign({
-                workflow: () => 'iteration',
-                changeOrigin: () => 'irTask',
-                afterReview: () => 'continueIr',
-            }),
-        ],
+    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'),
     },
-    SUMMARIZE_IR: {
-        target: '#summarizeSpecs',
-        actions: [
-            rememberBossInput,
-            assign({
-                workflow: () => 'specSummary',
-                changeOrigin: () => 'irTask',
-                afterReview: () => 'done',
-            }),
-        ],
+    actions: {
+        startCoding: assign(({ context, event }) => {
+            if (event.type !== 'START_CODE')
+                return {};
+            return {
+                coderPlayer: context.coderPlayer,
+                runResults: context.runResults,
+                callerInput: event.callerInput,
+                coderOutput: undefined,
+                latestCommit: undefined,
+                irNumber: undefined,
+                irTask: undefined,
+                nextIrTask: 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',
+            pendingBossQuestion: undefined,
+            bossReply: undefined,
+        })),
+        rememberIrCommit: assign(({ event }) => ({
+            coderOutput: outputString(event, 'coderOutput'),
+            latestCommit: outputString(event, 'latestCommit'),
+            irNumber: outputString(event, 'irNumber'),
+            irTask: outputString(event, 'irTask'),
+            nextIrTask: undefined,
+            phase: 'ir-created',
+            pendingBossQuestion: undefined,
+            bossReply: undefined,
+        })),
+        rememberMoreTasks: assign(({ event }) => ({
+            coderOutput: outputString(event, 'coderOutput'),
+            latestCommit: outputString(event, 'latestCommit'),
+            nextIrTask: outputString(event, 'irTask'),
+            phase: 'ir-task-more',
+            pendingBossQuestion: undefined,
+            bossReply: undefined,
+        })),
+        rememberFinalTask: assign(({ event }) => ({
+            coderOutput: outputString(event, 'coderOutput'),
+            latestCommit: outputString(event, 'latestCommit'),
+            nextIrTask: undefined,
+            phase: 'ir-task-final',
+            pendingBossQuestion: undefined,
+            bossReply: undefined,
+        })),
+        advanceToNextIrTask: assign(({ context }) => ({
+            irTask: context.nextIrTask,
+            nextIrTask: 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') };
+            }
+            return {
+                pendingBossQuestion: {
+                    questionId: stateId,
+                    resumeStateId: stateId,
+                    sourceItem: stateId === 'runFirstPhase' ? 'CODE-1' : 'CODE-3',
+                    player: 'Coder',
+                    question,
+                },
+                bossReply: undefined,
+            };
+        }),
+        rememberBossReply: assign(({ event }) => event.type === 'BOSS_REPLY' ? { bossReply: event.answer } : {}),
+        rememberEmptyBossReplyError: assign({
+            lastError: () => new Error('BOSS_REPLY received an empty answer'),
+            pendingBossQuestion: undefined,
+            bossReply: undefined,
+        }),
+        completeSuccessfully: assign({
+            completion: 'complete',
+            reviewError: 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.'),
+        })),
     },
-};
-const awaitBossReplyEvents = {
-    START_CODING: withClearBossReplyContext(readyEvents.START_CODING),
-    CONTINUE_IR: withClearBossReplyContext(readyEvents.CONTINUE_IR),
-    SUMMARIZE_IR: withClearBossReplyContext(readyEvents.SUMMARIZE_IR),
-    BOSS_INTERRUPT: bossInterrupts(jumpableStateIds, [clearBossReplyContext]),
-    BOSS_REPLY: [
-        {
-            guard: bossReplyIsEmpty,
-            target: '#failed',
-            actions: [clearBossReplyContext, rememberEmptyBossReplyError],
-        },
-        ...resumableStates(resumableStateIds),
-    ],
-};
-const playerPlaceholder = fromPromise(async () => {
-    throw new Error('player actor must be provided by the runner');
 });
-export const codingMachine = setup({
-    types: {},
-    actors: {
-        player: playerPlaceholder,
-    },
-}).createMachine({
-    id: 'coding',
+export const codingMachine = machineSetup.createMachine({
+    id: 'code',
+    initial: 'ready',
     context: ({ input }) => ({
-        intent: input?.intent,
-        irNumber: input?.irNumber,
-        coderPlayer: input?.coderPlayer,
-        reviewerPlayer: input?.reviewerPlayer,
-        committerPlayer: input?.committerPlayer,
+        coderPlayer: isNonEmptyString(input.coderPlayer) ? input.coderPlayer : 'Coder',
+        runResults: typeof input.runResults === 'string' ? input.runResults : '',
     }),
-    initial: 'ready',
-    on: {
-        BOSS_INTERRUPT: bossInterrupts(jumpableStateIds),
+    output: ({ context }) => {
+        const lastCodeCommit = context.latestCommit;
+        if (!isNonEmptyString(lastCodeCommit)) {
+            throw new Error('CODE reached a final state without a commit identity');
+        }
+        const lastCodeOutput = context.coderOutput ?? '';
+        if (context.completion === 'review-failed') {
+            return {
+                status: 'review-failed',
+                lastCodeCommit,
+                lastCodeOutput,
+                error: context.reviewError ?? {
+                    name: 'Error',
+                    message: 'REVIEW failed without error detail.',
+                },
+            };
+        }
+        return { status: 'complete', lastCodeCommit, lastCodeOutput };
     },
     states: {
         ready: {
             id: 'ready',
-            description: stateDescriptions.ready,
+            description: STATE_DESCRIPTIONS.ready,
             meta: playbookMeta('ready'),
             tags: ['playbook.parked'],
-            on: readyEvents,
-        },
-        awaitBossReply: {
-            id: 'awaitBossReply',
-            description: stateDescriptions.awaitBossReply,
-            meta: playbookMeta('awaitBossReply'),
-            tags: ['playbook.parked'],
-            on: awaitBossReplyEvents,
-        },
-        planAndImplement: {
-            id: 'planAndImplement',
-            description: stateDescriptions.planAndImplement,
-            meta: playbookMeta('planAndImplement'),
-            tags: ['playbook.busy'],
-            invoke: {
-                src: 'player',
-                input: ({ context }) => planAndImplementInput(context),
-                onDone: withNeedsBossReplyTransition('planAndImplement', [
-                    {
-                        guard: guardIs('singleCommitReady'),
-                        target: '#commitCoderInitial',
-                        actions: [
-                            rememberCaptainOutput,
-                            assign({
-                                workflow: () => 'singleCommit',
-                                changeOrigin: () => 'bossIntent',
-                                afterReview: () => 'done',
-                            }),
-                        ],
-                    },
-                    {
-                        guard: guardIs('irDrafted'),
-                        target: '#commitCoderInitial',
-                        actions: [
-                            rememberCaptainOutput,
-                            assign({
-                                workflow: () => 'iteration',
-                                changeOrigin: () => 'bossIntent',
-                                afterReview: () => 'continueIr',
-                            }),
-                        ],
-                    },
-                ]),
-                onError: captainError,
+            on: {
+                START_CODE: { target: 'runFirstPhase', actions: 'startCoding' },
             },
         },
-        respondToReview: {
-            id: 'respondToReview',
-            description: stateDescriptions.respondToReview,
-            meta: playbookMeta('respondToReview'),
+        runFirstPhase: {
+            id: 'runFirstPhase',
+            description: STATE_DESCRIPTIONS.runFirstPhase,
+            meta: playbookMeta('runFirstPhase', 'Coder'),
             tags: ['playbook.busy'],
             invoke: {
                 src: 'player',
                 input: ({ context }) => ({
-                    stateId: 'respondToReview',
+                    stateId: 'runFirstPhase',
                     player: 'Coder',
-                    sourceItem: 'CODE-2',
-                    ...bossReplyInputFields(context),
-                    reviews: context.reviews,
-                    prompt: [
-                        'For each review item below for the above changes, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.',
-                        'Stage all current changes that belong in the repo before making any edits, and leave your edits unstaged/untracked.',
-                    ].join('\n'),
-                    result: {
-                        changesMadeSpecs: 'Coder accepted items and produced unstaged/untracked edits only in spec item files (@specs/packages/, @specs/compositions/, or legacy @specs/{user,dev,test}/), without raising any rebuttals.',
-                        changesMadeCode: 'Coder accepted items and produced unstaged/untracked edits only outside spec item files (any other files, including @specs/ decision, intent, or legacy iteration records, @specs/map.md, and @specs/meta.md), without raising any rebuttals.',
-                        changesMadeMixed: 'Coder accepted items and produced unstaged/untracked edits spanning both spec item files and other files, without raising any rebuttals.',
-                        changesMadeSpecsAndChallenged: 'Coder produced unstaged/untracked edits only in spec item files (@specs/packages/, @specs/compositions/, or legacy @specs/{user,dev,test}/) AND challenged one or more review items. Output shall include `challenges: <numbered rebuttals, one per challenged item>`.',
-                        changesMadeCodeAndChallenged: 'Coder produced unstaged/untracked edits only outside spec item files AND challenged one or more review items. Output shall include `challenges: <numbered rebuttals, one per challenged item>`.',
-                        changesMadeMixedAndChallenged: 'Coder produced unstaged/untracked edits spanning both spec item files and other files AND challenged one or more review items. Output shall include `challenges: <numbered rebuttals, one per challenged item>`.',
-                        challengesRaised: 'Coder challenged one or more review items without producing any code edits. Output shall include `challenges: <numbered rebuttals, one per challenged item>`.',
-                        accepted: 'Coder accepted the review outcome without further edits.',
-                        needsBossReply: needsBossReplyDescription,
-                    },
-                }),
-                onDone: withNeedsBossReplyTransition('respondToReview', [
-                    {
-                        guard: guardIs('changesMadeSpecs'),
-                        target: '#reviewChangesSpecs',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: guardIs('changesMadeCode'),
-                        target: '#reviewChangesCode',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: guardIs('changesMadeMixed'),
-                        target: '#reviewChangesMixed',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: guardIs('changesMadeSpecsAndChallenged'),
-                        target: '#reviewChangesAndChallengesSpecs',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: guardIs('changesMadeCodeAndChallenged'),
-                        target: '#reviewChangesAndChallengesCode',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: guardIs('changesMadeMixedAndChallenged'),
-                        target: '#reviewChangesAndChallengesMixed',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: guardIs('challengesRaised'),
-                        target: '#adjudicateChallenges',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: acceptedAfter('changes'),
-                        target: '#commitJoint',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: ({ context, event }) => outputOf(event)?.guard === 'accepted' &&
-                            context.reviewSubject === 'commit' &&
-                            context.afterReview === 'continueIr',
-                        target: '#continueIr',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: ({ context, event }) => outputOf(event)?.guard === 'accepted' &&
-                            context.reviewSubject === 'commit' &&
-                            context.afterReview === 'summarizeSpecs',
-                        target: '#summarizeSpecs',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: ({ context, event }) => outputOf(event)?.guard === 'accepted' &&
-                            context.reviewSubject === 'commit' &&
-                            context.afterReview === 'done',
-                        target: '#done',
-                        actions: rememberCaptainOutput,
-                    },
-                ]),
-                onError: captainError,
-            },
-        },
-        continueIr: {
-            id: 'continueIr',
-            description: stateDescriptions.continueIr,
-            meta: playbookMeta('continueIr'),
-            tags: ['playbook.busy'],
-            invoke: {
-                src: 'player',
-                input: ({ context }) => continueIrInput(context),
-                onDone: withNeedsBossReplyTransition('continueIr', [
-                    {
-                        guard: guardIs('taskReady'),
-                        target: '#commitCoderInitial',
-                        actions: [
-                            rememberCaptainOutput,
-                            assign({
-                                workflow: () => 'iteration',
-                                changeOrigin: () => 'irTask',
-                                afterReview: () => 'continueIr',
-                            }),
-                        ],
-                    },
-                    {
-                        guard: guardIs('iterationDone'),
-                        target: '#summarizeSpecs',
-                        actions: [
-                            rememberCaptainOutput,
-                            assign({
-                                workflow: () => 'specSummary',
-                                afterReview: () => 'done',
-                            }),
-                        ],
-                    },
-                ]),
-                onError: captainError,
-            },
-        },
-        summarizeSpecs: {
-            id: 'summarizeSpecs',
-            description: stateDescriptions.summarizeSpecs,
-            meta: playbookMeta('summarizeSpecs'),
-            tags: ['playbook.busy'],
-            invoke: {
-                src: 'player',
-                input: ({ context }) => summarizeSpecsInput(context),
-                onDone: withNeedsBossReplyTransition('summarizeSpecs', [
-                    {
-                        guard: guardIs('specsReady'),
-                        target: '#commitCoderInitial',
-                        actions: [
-                            rememberCaptainOutput,
-                            assign({
-                                workflow: () => 'specSummary',
-                                changeOrigin: () => 'irTask',
-                                afterReview: () => 'done',
-                            }),
-                        ],
-                    },
-                    {
-                        guard: guardIs('noSpecChanges'),
-                        target: '#done',
-                        actions: rememberCaptainOutput,
-                    },
-                ]),
-                onError: captainError,
-            },
-        },
-        reviewBossCommitSpecs: {
-            id: 'reviewBossCommitSpecs',
-            description: stateDescriptions.reviewBossCommitSpecs,
-            meta: playbookMeta('reviewBossCommitSpecs'),
-            tags: ['playbook.busy'],
-            invoke: {
-                src: 'player',
-                input: ({ context }) => ({
-                    stateId: 'reviewBossCommitSpecs',
-                    player: 'Reviewer',
-                    sourceItem: 'CODE-5',
-                    ...bossReplyInputFields(context),
-                    intent: context.intent,
-                    prompt: [
-                        'Review the latest commit.',
-                        'Refer to the commit message.',
-                        'Verify any affected spec items are:',
-                        '',
-                        '- Complete & coherent: sufficient for you to reimplement code.',
-                        '- Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.',
-                        '- Minimal: essential and concise; every item earns its place; also check with other items.',
-                        '- Well organized: spec packages are finely scoped, with high cohesion and low coupling.',
-                        '',
-                        'Flag anything missing, redundant, over-specified, or under-specified.',
-                        'For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.',
-                        'Verify @specs/map.md reflects the changes.',
-                        "If the change is ready to commit or push, don't raise nitpicks.",
-                        'Do not edit files or commit; report findings only.',
-                    ].join('\n'),
-                    result: {
-                        noFindings: 'The spec-only commit has no review findings.',
-                        hasFindings: 'The review produced findings for Coder. Output shall include `reviews: <numbered list of findings, no duplication>`.',
-                        needsBossReply: needsBossReplyDescription,
-                    },
-                }),
-                onDone: withNeedsBossReplyTransition('reviewBossCommitSpecs', [
-                    {
-                        guard: noFindingsAfter('continueIr'),
-                        target: '#continueIr',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: noFindingsAfter('summarizeSpecs'),
-                        target: '#summarizeSpecs',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: noFindingsAfter('done'),
-                        target: '#done',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: guardIs('hasFindings'),
-                        target: '#respondToReview',
-                        actions: [
-                            rememberCaptainOutput,
-                            assign({ reviewSubject: () => 'commit' }),
-                        ],
-                    },
-                ]),
-                onError: captainError,
-            },
-        },
-        reviewBossCommitCode: {
-            id: 'reviewBossCommitCode',
-            description: stateDescriptions.reviewBossCommitCode,
-            meta: playbookMeta('reviewBossCommitCode'),
-            tags: ['playbook.busy'],
-            invoke: {
-                src: 'player',
-                input: ({ context }) => ({
-                    stateId: 'reviewBossCommitCode',
-                    player: 'Reviewer',
-                    sourceItem: 'CODE-6',
-                    ...bossReplyInputFields(context),
-                    intent: context.intent,
-                    prompt: [
-                        'Review the latest commit.',
-                        'Refer to the commit message.',
-                        'Flag any issues or improvements (numbered; no duplication).',
-                        "Think thoroughly — don't just approve or reject.",
-                        'For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.',
-                        'Verify @specs/map.md reflects the changes.',
-                        "If the change is ready to commit or push, don't raise nitpicks.",
-                        'Do not edit files or commit; report findings only.',
-                    ].join('\n'),
-                    result: {
-                        noFindings: 'The code-only commit has no review findings.',
-                        hasFindings: 'The review produced findings for Coder. Output shall include `reviews: <numbered list of findings, no duplication>`.',
-                        needsBossReply: needsBossReplyDescription,
-                    },
-                }),
-                onDone: withNeedsBossReplyTransition('reviewBossCommitCode', [
-                    {
-                        guard: noFindingsAfter('continueIr'),
-                        target: '#continueIr',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: noFindingsAfter('summarizeSpecs'),
-                        target: '#summarizeSpecs',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: noFindingsAfter('done'),
-                        target: '#done',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: guardIs('hasFindings'),
-                        target: '#respondToReview',
-                        actions: [
-                            rememberCaptainOutput,
-                            assign({ reviewSubject: () => 'commit' }),
-                        ],
-                    },
-                ]),
-                onError: captainError,
-            },
-        },
-        reviewBossCommitMixed: {
-            id: 'reviewBossCommitMixed',
-            description: stateDescriptions.reviewBossCommitMixed,
-            meta: playbookMeta('reviewBossCommitMixed'),
-            tags: ['playbook.busy'],
-            invoke: {
-                src: 'player',
-                input: ({ context }) => ({
-                    stateId: 'reviewBossCommitMixed',
-                    player: 'Reviewer',
-                    sourceItem: 'CODE-7',
-                    ...bossReplyInputFields(context),
-                    intent: context.intent,
-                    prompt: [
-                        'Review the latest commit.',
-                        'Refer to the commit message.',
-                        'Flag any issues or improvements (numbered; no duplication).',
-                        "Think thoroughly — don't just approve or reject.",
-                        'Verify any affected spec items are:',
-                        '',
-                        '- Complete & coherent: sufficient for you to reimplement code.',
-                        '- Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.',
-                        '- Minimal: essential and concise; every item earns its place; also check with other items.',
-                        '- Well organized: spec packages are finely scoped, with high cohesion and low coupling.',
-                        '',
-                        'Flag anything missing, redundant, over-specified, or under-specified.',
-                        'For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.',
-                        'Verify @specs/map.md reflects the changes.',
-                        "If the change is ready to commit or push, don't raise nitpicks.",
-                        'Do not edit files or commit; report findings only.',
-                    ].join('\n'),
-                    result: {
-                        noFindings: 'The mixed commit has no review findings.',
-                        hasFindings: 'The review produced findings for Coder. Output shall include `reviews: <numbered list of findings, no duplication>`.',
-                        needsBossReply: needsBossReplyDescription,
-                    },
-                }),
-                onDone: withNeedsBossReplyTransition('reviewBossCommitMixed', [
-                    {
-                        guard: noFindingsAfter('continueIr'),
-                        target: '#continueIr',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: noFindingsAfter('summarizeSpecs'),
-                        target: '#summarizeSpecs',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: noFindingsAfter('done'),
-                        target: '#done',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: guardIs('hasFindings'),
-                        target: '#respondToReview',
-                        actions: [
-                            rememberCaptainOutput,
-                            assign({ reviewSubject: () => 'commit' }),
-                        ],
-                    },
-                ]),
-                onError: captainError,
-            },
-        },
-        reviewIrTaskCommitSpecs: {
-            id: 'reviewIrTaskCommitSpecs',
-            description: stateDescriptions.reviewIrTaskCommitSpecs,
-            meta: playbookMeta('reviewIrTaskCommitSpecs'),
-            tags: ['playbook.busy'],
-            invoke: {
-                src: 'player',
-                input: ({ context }) => ({
-                    stateId: 'reviewIrTaskCommitSpecs',
-                    player: 'Reviewer',
-                    sourceItem: 'CODE-8',
-                    ...bossReplyInputFields(context),
-                    irNumber: context.irNumber,
-                    taskDescription: context.taskDescription,
-                    prompt: [
-                        'Review the latest commit.',
-                        'Refer to the commit message.',
-                        'Verify any affected spec items are:',
-                        '',
-                        '- Complete & coherent: sufficient for you to reimplement code.',
-                        '- Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.',
-                        '- Minimal: essential and concise; every item earns its place; also check with other items.',
-                        '- Well organized: spec packages are finely scoped, with high cohesion and low coupling.',
-                        '',
-                        'Flag anything missing, redundant, over-specified, or under-specified.',
-                        'For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.',
-                        'Verify @specs/map.md reflects the changes.',
-                        "If the change is ready to commit or push, don't raise nitpicks.",
-                        'Do not edit files or commit; report findings only.',
-                    ].join('\n'),
-                    result: {
-                        noFindings: 'The IR-task spec-only commit has no review findings.',
-                        hasFindings: 'The review produced findings for Coder. Output shall include `reviews: <numbered list of findings, no duplication>`.',
-                        needsBossReply: needsBossReplyDescription,
-                    },
-                }),
-                onDone: withNeedsBossReplyTransition('reviewIrTaskCommitSpecs', [
-                    {
-                        guard: noFindingsAfter('continueIr'),
-                        target: '#continueIr',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: noFindingsAfter('summarizeSpecs'),
-                        target: '#summarizeSpecs',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: noFindingsAfter('done'),
-                        target: '#done',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: guardIs('hasFindings'),
-                        target: '#respondToReview',
-                        actions: [
-                            rememberCaptainOutput,
-                            assign({ reviewSubject: () => 'commit' }),
-                        ],
-                    },
-                ]),
-                onError: captainError,
-            },
-        },
-        reviewIrTaskCommitCode: {
-            id: 'reviewIrTaskCommitCode',
-            description: stateDescriptions.reviewIrTaskCommitCode,
-            meta: playbookMeta('reviewIrTaskCommitCode'),
-            tags: ['playbook.busy'],
-            invoke: {
-                src: 'player',
-                input: ({ context }) => ({
-                    stateId: 'reviewIrTaskCommitCode',
-                    player: 'Reviewer',
-                    sourceItem: 'CODE-9',
-                    ...bossReplyInputFields(context),
-                    irNumber: context.irNumber,
-                    taskDescription: context.taskDescription,
-                    prompt: [
-                        'Review the latest commit.',
-                        'Refer to the commit message.',
-                        'Flag any issues or improvements (numbered; no duplication).',
-                        "Think thoroughly — don't just approve or reject.",
-                        'For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.',
-                        'Verify @specs/map.md reflects the changes.',
-                        "If the change is ready to commit or push, don't raise nitpicks.",
-                        'Do not edit files or commit; report findings only.',
-                    ].join('\n'),
-                    result: {
-                        noFindings: 'The IR-task code-only commit has no review findings.',
-                        hasFindings: 'The review produced findings for Coder. Output shall include `reviews: <numbered list of findings, no duplication>`.',
-                        needsBossReply: needsBossReplyDescription,
-                    },
-                }),
-                onDone: withNeedsBossReplyTransition('reviewIrTaskCommitCode', [
-                    {
-                        guard: noFindingsAfter('continueIr'),
-                        target: '#continueIr',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: noFindingsAfter('summarizeSpecs'),
-                        target: '#summarizeSpecs',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: noFindingsAfter('done'),
-                        target: '#done',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: guardIs('hasFindings'),
-                        target: '#respondToReview',
-                        actions: [
-                            rememberCaptainOutput,
-                            assign({ reviewSubject: () => 'commit' }),
-                        ],
-                    },
-                ]),
-                onError: captainError,
-            },
-        },
-        reviewIrTaskCommitMixed: {
-            id: 'reviewIrTaskCommitMixed',
-            description: stateDescriptions.reviewIrTaskCommitMixed,
-            meta: playbookMeta('reviewIrTaskCommitMixed'),
-            tags: ['playbook.busy'],
-            invoke: {
-                src: 'player',
-                input: ({ context }) => ({
-                    stateId: 'reviewIrTaskCommitMixed',
-                    player: 'Reviewer',
-                    sourceItem: 'CODE-10',
-                    ...bossReplyInputFields(context),
-                    irNumber: context.irNumber,
-                    taskDescription: context.taskDescription,
-                    prompt: [
-                        'Review the latest commit.',
-                        'Refer to the commit message.',
-                        'Flag any issues or improvements (numbered; no duplication).',
-                        "Think thoroughly — don't just approve or reject.",
-                        'Verify any affected spec items are:',
-                        '',
-                        '- Complete & coherent: sufficient for you to reimplement code.',
-                        '- Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.',
-                        '- Minimal: essential and concise; every item earns its place; also check with other items.',
-                        '- Well organized: spec packages are finely scoped, with high cohesion and low coupling.',
-                        '',
-                        'Flag anything missing, redundant, over-specified, or under-specified.',
-                        'For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.',
-                        'Verify @specs/map.md reflects the changes.',
-                        "If the change is ready to commit or push, don't raise nitpicks.",
-                        'Do not edit files or commit; report findings only.',
-                    ].join('\n'),
-                    result: {
-                        noFindings: 'The IR-task mixed commit has no review findings.',
-                        hasFindings: 'The review produced findings for Coder. Output shall include `reviews: <numbered list of findings, no duplication>`.',
-                        needsBossReply: needsBossReplyDescription,
-                    },
-                }),
-                onDone: withNeedsBossReplyTransition('reviewIrTaskCommitMixed', [
-                    {
-                        guard: noFindingsAfter('continueIr'),
-                        target: '#continueIr',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: noFindingsAfter('summarizeSpecs'),
-                        target: '#summarizeSpecs',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: noFindingsAfter('done'),
-                        target: '#done',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: guardIs('hasFindings'),
-                        target: '#respondToReview',
-                        actions: [
-                            rememberCaptainOutput,
-                            assign({ reviewSubject: () => 'commit' }),
-                        ],
-                    },
-                ]),
-                onError: captainError,
-            },
-        },
-        reviewChangesSpecs: {
-            id: 'reviewChangesSpecs',
-            description: stateDescriptions.reviewChangesSpecs,
-            meta: playbookMeta('reviewChangesSpecs'),
-            tags: ['playbook.busy'],
-            invoke: {
-                src: 'player',
-                input: ({ context }) => ({
-                    stateId: 'reviewChangesSpecs',
-                    player: 'Reviewer',
-                    sourceItem: 'CODE-11',
-                    ...bossReplyInputFields(context),
-                    prompt: [
-                        'Review the unstaged and untracked changes in the context of the staged changes.',
-                        'Understand the intent.',
-                        'Verify any affected spec items are:',
-                        '',
-                        '- Complete & coherent: sufficient for you to reimplement code.',
-                        '- Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.',
-                        '- Minimal: essential and concise; every item earns its place; also check with other items.',
-                        '- Well organized: spec packages are finely scoped, with high cohesion and low coupling.',
-                        '',
-                        'Flag anything missing, redundant, over-specified, or under-specified.',
-                        'For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.',
-                        'Verify @specs/map.md reflects the changes.',
-                        "If the change is ready to commit or push, don't raise nitpicks.",
-                        'Do not edit files or commit; report findings only.',
-                    ].join('\n'),
-                    result: {
-                        noFindings: 'The uncommitted spec-only changes are ready to commit.',
-                        hasFindings: 'The review produced findings for Coder. Output shall include `reviews: <numbered list of findings, no duplication>`.',
-                        needsBossReply: needsBossReplyDescription,
-                    },
-                }),
-                onDone: withNeedsBossReplyTransition('reviewChangesSpecs', [
-                    {
-                        guard: guardIs('noFindings'),
-                        target: '#commitJoint',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: guardIs('hasFindings'),
-                        target: '#respondToReview',
-                        actions: [
-                            rememberCaptainOutput,
-                            assign({ reviewSubject: () => 'changes' }),
-                        ],
-                    },
-                ]),
-                onError: captainError,
-            },
-        },
-        reviewChangesCode: {
-            id: 'reviewChangesCode',
-            description: stateDescriptions.reviewChangesCode,
-            meta: playbookMeta('reviewChangesCode'),
-            tags: ['playbook.busy'],
-            invoke: {
-                src: 'player',
-                input: ({ context }) => ({
-                    stateId: 'reviewChangesCode',
-                    player: 'Reviewer',
-                    sourceItem: 'CODE-12',
-                    ...bossReplyInputFields(context),
-                    prompt: [
-                        'Review the unstaged and untracked changes in the context of the staged changes.',
-                        'Understand the intent.',
-                        'Flag any issues or improvements (numbered; no duplication).',
-                        "Think thoroughly — don't just approve or reject.",
-                        'For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.',
-                        'Verify @specs/map.md reflects the changes.',
-                        "If the change is ready to commit or push, don't raise nitpicks.",
-                        'Do not edit files or commit; report findings only.',
-                    ].join('\n'),
-                    result: {
-                        noFindings: 'The uncommitted code-only changes are ready to commit.',
-                        hasFindings: 'The review produced findings for Coder. Output shall include `reviews: <numbered list of findings, no duplication>`.',
-                        needsBossReply: needsBossReplyDescription,
-                    },
-                }),
-                onDone: withNeedsBossReplyTransition('reviewChangesCode', [
-                    {
-                        guard: guardIs('noFindings'),
-                        target: '#commitJoint',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: guardIs('hasFindings'),
-                        target: '#respondToReview',
-                        actions: [
-                            rememberCaptainOutput,
-                            assign({ reviewSubject: () => 'changes' }),
-                        ],
-                    },
-                ]),
-                onError: captainError,
-            },
-        },
-        reviewChangesMixed: {
-            id: 'reviewChangesMixed',
-            description: stateDescriptions.reviewChangesMixed,
-            meta: playbookMeta('reviewChangesMixed'),
-            tags: ['playbook.busy'],
-            invoke: {
-                src: 'player',
-                input: ({ context }) => ({
-                    stateId: 'reviewChangesMixed',
-                    player: 'Reviewer',
-                    sourceItem: 'CODE-13',
-                    ...bossReplyInputFields(context),
-                    prompt: [
-                        'Review the unstaged and untracked changes in the context of the staged changes.',
-                        'Understand the intent.',
-                        'Flag any issues or improvements (numbered; no duplication).',
-                        "Think thoroughly — don't just approve or reject.",
-                        'Verify any affected spec items are:',
-                        '',
-                        '- Complete & coherent: sufficient for you to reimplement code.',
-                        '- Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.',
-                        '- Minimal: essential and concise; every item earns its place; also check with other items.',
-                        '- Well organized: spec packages are finely scoped, with high cohesion and low coupling.',
-                        '',
-                        'Flag anything missing, redundant, over-specified, or under-specified.',
-                        'For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.',
-                        'Verify @specs/map.md reflects the changes.',
-                        "If the change is ready to commit or push, don't raise nitpicks.",
-                        'Do not edit files or commit; report findings only.',
-                    ].join('\n'),
-                    result: {
-                        noFindings: 'The uncommitted mixed changes are ready to commit.',
-                        hasFindings: 'The review produced findings for Coder. Output shall include `reviews: <numbered list of findings, no duplication>`.',
-                        needsBossReply: needsBossReplyDescription,
-                    },
+                    sourceItem: 'CODE-1',
+                    prompt: FIRST_PHASE_PROMPT,
+                    result: FIRST_PHASE_RESULTS,
+                    callerInput: context.callerInput ?? '',
+                    runResults: context.runResults,
+                    coderPlayer: context.coderPlayer,
+                    ...(context.pendingBossQuestion === undefined
+                        ? {}
+                        : { pendingBossQuestion: context.pendingBossQuestion }),
+                    ...(context.bossReply === undefined
+                        ? {}
+                        : { bossReply: context.bossReply }),
                 }),
-                onDone: withNeedsBossReplyTransition('reviewChangesMixed', [
+                onDone: [
                     {
-                        guard: guardIs('noFindings'),
-                        target: '#commitJoint',
-                        actions: rememberCaptainOutput,
+                        guard: 'isDirectCommit',
+                        target: 'reviewFirstCommit',
+                        actions: 'rememberDirectCommit',
                     },
                     {
-                        guard: guardIs('hasFindings'),
-                        target: '#respondToReview',
-                        actions: [
-                            rememberCaptainOutput,
-                            assign({ reviewSubject: () => 'changes' }),
-                        ],
-                    },
-                ]),
-                onError: captainError,
-            },
-        },
-        reviewChangesAndChallengesSpecs: {
-            id: 'reviewChangesAndChallengesSpecs',
-            description: stateDescriptions.reviewChangesAndChallengesSpecs,
-            meta: playbookMeta('reviewChangesAndChallengesSpecs'),
-            tags: ['playbook.busy'],
-            invoke: {
-                src: 'player',
-                input: ({ context }) => ({
-                    stateId: 'reviewChangesAndChallengesSpecs',
-                    player: 'Reviewer',
-                    sourceItem: 'CODE-15',
-                    ...bossReplyInputFields(context),
-                    reviews: context.reviews,
-                    challenges: context.challenges,
-                    prompt: [
-                        'Review the unstaged and untracked changes in the context of the staged changes.',
-                        'Understand the intent.',
-                        'Verify any affected spec items are:',
-                        '',
-                        '- Complete & coherent: sufficient for you to reimplement code.',
-                        '- Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.',
-                        '- Minimal: essential and concise; every item earns its place; also check with other items.',
-                        '- Well organized: spec packages are finely scoped, with high cohesion and low coupling.',
-                        '',
-                        'Flag anything missing, redundant, over-specified, or under-specified.',
-                        'For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.',
-                        'Verify @specs/map.md reflects the changes.',
-                        "If the change is ready to commit or push, don't raise nitpicks.",
-                        'Do not edit files or commit; report findings only.',
-                        'For each rebuttal below, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.',
-                    ].join('\n'),
-                    result: {
-                        approved: 'The new spec-only changes are ready to commit and every rebuttal was accepted (or no items remained open).',
-                        needsRevision: 'The combined round needs more work: the review produced findings, one or more rebuttals were rejected, or both. Output shall include `reviews: <numbered list of any new findings or rejected rebuttals to address>`.',
-                        needsBossReply: needsBossReplyDescription,
+                        guard: 'isIrCommit',
+                        target: 'reviewFirstCommit',
+                        actions: 'rememberIrCommit',
                     },
-                }),
-                onDone: withNeedsBossReplyTransition('reviewChangesAndChallengesSpecs', [
                     {
-                        guard: guardIs('approved'),
-                        target: '#commitJoint',
-                        actions: rememberCaptainOutput,
+                        guard: 'needsBossReply',
+                        target: 'awaitBossReply',
+                        actions: 'rememberPendingQuestion',
                     },
                     {
-                        guard: guardIs('needsRevision'),
-                        target: '#respondToReview',
-                        actions: [
-                            rememberCaptainOutput,
-                            assign({ reviewSubject: () => 'changes' }),
-                        ],
+                        target: 'failed',
+                        actions: 'rememberMalformedPlayerOutput',
                     },
-                ]),
-                onError: captainError,
+                ],
+                onError: { target: 'failed', actions: 'rememberActorError' },
             },
         },
-        reviewChangesAndChallengesCode: {
-            id: 'reviewChangesAndChallengesCode',
-            description: stateDescriptions.reviewChangesAndChallengesCode,
-            meta: playbookMeta('reviewChangesAndChallengesCode'),
-            tags: ['playbook.busy'],
+        reviewFirstCommit: {
+            id: 'reviewFirstCommit',
+            description: STATE_DESCRIPTIONS.reviewFirstCommit,
+            meta: playbookMeta('reviewFirstCommit'),
+            tags: ['playbook.suspended'],
             invoke: {
-                src: 'player',
+                src: 'playbook',
                 input: ({ context }) => ({
-                    stateId: 'reviewChangesAndChallengesCode',
-                    player: 'Reviewer',
-                    sourceItem: 'CODE-16',
-                    ...bossReplyInputFields(context),
-                    reviews: context.reviews,
-                    challenges: context.challenges,
-                    prompt: [
-                        'Review the unstaged and untracked changes in the context of the staged changes.',
-                        'Understand the intent.',
-                        'Flag any issues or improvements (numbered; no duplication).',
-                        "Think thoroughly — don't just approve or reject.",
-                        'For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.',
-                        'Verify @specs/map.md reflects the changes.',
-                        "If the change is ready to commit or push, don't raise nitpicks.",
-                        'Do not edit files or commit; report findings only.',
-                        'For each rebuttal below, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.',
-                    ].join('\n'),
-                    result: {
-                        approved: 'The new code-only changes are ready to commit and every rebuttal was accepted (or no items remained open).',
-                        needsRevision: 'The combined round needs more work: the review produced findings, one or more rebuttals were rejected, or both. Output shall include `reviews: <numbered list of any new findings or rejected rebuttals to address>`.',
-                        needsBossReply: needsBossReplyDescription,
-                    },
+                    stateId: 'reviewFirstCommit',
+                    sourceItem: 'CODE-2',
+                    playbookId: 'review',
+                    text: initialReviewText(context),
                 }),
-                onDone: withNeedsBossReplyTransition('reviewChangesAndChallengesCode', [
+                onDone: [
                     {
-                        guard: guardIs('approved'),
-                        target: '#commitJoint',
-                        actions: rememberCaptainOutput,
+                        guard: 'reviewApprovedDirect',
+                        target: 'done',
+                        actions: 'completeSuccessfully',
                     },
                     {
-                        guard: guardIs('needsRevision'),
-                        target: '#respondToReview',
-                        actions: [
-                            rememberCaptainOutput,
-                            assign({ reviewSubject: () => 'changes' }),
-                        ],
-                    },
-                ]),
-                onError: captainError,
-            },
-        },
-        reviewChangesAndChallengesMixed: {
-            id: 'reviewChangesAndChallengesMixed',
-            description: stateDescriptions.reviewChangesAndChallengesMixed,
-            meta: playbookMeta('reviewChangesAndChallengesMixed'),
-            tags: ['playbook.busy'],
-            invoke: {
-                src: 'player',
-                input: ({ context }) => ({
-                    stateId: 'reviewChangesAndChallengesMixed',
-                    player: 'Reviewer',
-                    sourceItem: 'CODE-17',
-                    ...bossReplyInputFields(context),
-                    reviews: context.reviews,
-                    challenges: context.challenges,
-                    prompt: [
-                        'Review the unstaged and untracked changes in the context of the staged changes.',
-                        'Understand the intent.',
-                        'Flag any issues or improvements (numbered; no duplication).',
-                        "Think thoroughly — don't just approve or reject.",
-                        'Verify any affected spec items are:',
-                        '',
-                        '- Complete & coherent: sufficient for you to reimplement code.',
-                        '- Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.',
-                        '- Minimal: essential and concise; every item earns its place; also check with other items.',
-                        '- Well organized: spec packages are finely scoped, with high cohesion and low coupling.',
-                        '',
-                        'Flag anything missing, redundant, over-specified, or under-specified.',
-                        'For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.',
-                        'Verify @specs/map.md reflects the changes.',
-                        "If the change is ready to commit or push, don't raise nitpicks.",
-                        'Do not edit files or commit; report findings only.',
-                        'For each rebuttal below, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.',
-                    ].join('\n'),
-                    result: {
-                        approved: 'The new mixed changes are ready to commit and every rebuttal was accepted (or no items remained open).',
-                        needsRevision: 'The combined round needs more work: the review produced findings, one or more rebuttals were rejected, or both. Output shall include `reviews: <numbered list of any new findings or rejected rebuttals to address>`.',
-                        needsBossReply: needsBossReplyDescription,
+                        guard: 'reviewApprovedIrCreated',
+                        target: 'runIrTask',
                     },
-                }),
-                onDone: withNeedsBossReplyTransition('reviewChangesAndChallengesMixed', [
                     {
-                        guard: guardIs('approved'),
-                        target: '#commitJoint',
-                        actions: rememberCaptainOutput,
+                        target: 'done',
+                        actions: 'completeWithInvalidReviewOutput',
                     },
+                ],
+                onError: [
                     {
-                        guard: guardIs('needsRevision'),
-                        target: '#respondToReview',
-                        actions: [
-                            rememberCaptainOutput,
-                            assign({ reviewSubject: () => 'changes' }),
-                        ],
+                        guard: 'authoredReviewFailure',
+                        target: 'done',
+                        actions: 'completeWithReviewFailure',
                     },
-                ]),
-                onError: captainError,
+                    { target: 'failed', actions: 'rememberActorError' },
+                ],
             },
         },
-        adjudicateChallenges: {
-            id: 'adjudicateChallenges',
-            description: stateDescriptions.adjudicateChallenges,
-            meta: playbookMeta('adjudicateChallenges'),
+        runIrTask: {
+            id: 'runIrTask',
+            description: STATE_DESCRIPTIONS.runIrTask,
+            meta: playbookMeta('runIrTask', 'Coder'),
             tags: ['playbook.busy'],
             invoke: {
                 src: 'player',
                 input: ({ context }) => ({
-                    stateId: 'adjudicateChallenges',
-                    player: 'Reviewer',
-                    sourceItem: 'CODE-14',
-                    ...bossReplyInputFields(context),
-                    reviews: context.reviews,
-                    challenges: context.challenges,
-                    prompt: [
-                        'For each rebuttal below, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.',
-                        'Do not edit files or commit; report findings only.',
-                    ].join('\n'),
-                    result: {
-                        challengeAccepted: 'Reviewer accepted the rebuttal — no further review edits are required.',
-                        challengeRejected: 'Reviewer rejected the rebuttal — Coder must respond again.',
-                        noOpenItems: 'No review items remain open.',
-                        needsBossReply: needsBossReplyDescription,
-                    },
+                    stateId: 'runIrTask',
+                    player: 'Coder',
+                    sourceItem: 'CODE-3',
+                    prompt: IR_TASK_PROMPT,
+                    result: IR_TASK_RESULTS,
+                    callerInput: context.callerInput ?? '',
+                    runResults: context.runResults,
+                    coderPlayer: context.coderPlayer,
+                    ...(context.irNumber === undefined
+                        ? {}
+                        : { irNumber: context.irNumber }),
+                    ...(context.irTask === undefined ? {} : { irTask: context.irTask }),
+                    ...(context.pendingBossQuestion === undefined
+                        ? {}
+                        : { pendingBossQuestion: context.pendingBossQuestion }),
+                    ...(context.bossReply === undefined
+                        ? {}
+                        : { bossReply: context.bossReply }),
                 }),
-                onDone: withNeedsBossReplyTransition('adjudicateChallenges', [
+                onDone: [
                     {
-                        guard: ({ context, event }) => (outputOf(event)?.guard === 'challengeAccepted' ||
-                            outputOf(event)?.guard === 'noOpenItems') &&
-                            context.reviewSubject === 'changes',
-                        target: '#commitJoint',
-                        actions: rememberCaptainOutput,
+                        guard: 'isMoreTasks',
+                        target: 'reviewIrTask',
+                        actions: 'rememberMoreTasks',
                     },
                     {
-                        guard: ({ context, event }) => (outputOf(event)?.guard === 'challengeAccepted' ||
-                            outputOf(event)?.guard === 'noOpenItems') &&
-                            context.reviewSubject === 'commit' &&
-                            context.afterReview === 'continueIr',
-                        target: '#continueIr',
-                        actions: rememberCaptainOutput,
+                        guard: 'isFinalTask',
+                        target: 'reviewIrTask',
+                        actions: 'rememberFinalTask',
                     },
                     {
-                        guard: ({ context, event }) => (outputOf(event)?.guard === 'challengeAccepted' ||
-                            outputOf(event)?.guard === 'noOpenItems') &&
-                            context.reviewSubject === 'commit' &&
-                            context.afterReview === 'summarizeSpecs',
-                        target: '#summarizeSpecs',
-                        actions: rememberCaptainOutput,
+                        guard: 'needsBossReply',
+                        target: 'awaitBossReply',
+                        actions: 'rememberPendingQuestion',
                     },
                     {
-                        guard: ({ context, event }) => (outputOf(event)?.guard === 'challengeAccepted' ||
-                            outputOf(event)?.guard === 'noOpenItems') &&
-                            context.reviewSubject === 'commit' &&
-                            context.afterReview === 'done',
-                        target: '#done',
-                        actions: rememberCaptainOutput,
+                        target: 'failed',
+                        actions: 'rememberMalformedPlayerOutput',
                     },
-                    {
-                        guard: guardIs('challengeRejected'),
-                        target: '#respondToReview',
-                        actions: rememberCaptainOutput,
-                    },
-                ]),
-                onError: captainError,
+                ],
+                onError: { target: 'failed', actions: 'rememberActorError' },
             },
         },
-        commitCoderInitial: {
-            id: 'commitCoderInitial',
-            description: stateDescriptions.commitCoderInitial,
-            meta: playbookMeta('commitCoderInitial'),
-            tags: ['playbook.busy'],
+        reviewIrTask: {
+            id: 'reviewIrTask',
+            description: STATE_DESCRIPTIONS.reviewIrTask,
+            meta: playbookMeta('reviewIrTask'),
+            tags: ['playbook.suspended'],
             invoke: {
-                src: 'player',
+                src: 'playbook',
                 input: ({ context }) => ({
-                    stateId: 'commitCoderInitial',
-                    player: 'Committer',
-                    sourceItem: 'CODE-18',
-                    ...bossReplyInputFields(context),
-                    coderPlayer: context.coderPlayer,
-                    committerPlayer: context.committerPlayer,
-                    prompt: [
-                        'Make a commit of the changes that belong in the repo, following @specs/packages/git.md (reread if necessary).',
-                        "If that spec is absent, follow the legacy @specs/dev/git.md; if neither exists, follow the repository's existing commit conventions and do not search elsewhere.",
-                        'Write the commit message concisely.',
-                        'Coder is <coder-llm>.',
-                        'Format the `Co-authored-by` `<model>` token as the conventional human form of the substituted id (e.g., `claude-opus-4-7` → `Claude-Opus-4.7`, `gpt-5.5` → `GPT-5.5`).',
-                    ].join('\n'),
-                    result: {
-                        committedSpecs: 'Committed changes that touch only spec item files (@specs/packages/, @specs/compositions/, or legacy @specs/{user,dev,test}/).',
-                        committedCode: 'Committed changes that touch only files that are not spec item files (any other files, including @specs/ decision, intent, or legacy iteration records, @specs/map.md, and @specs/meta.md).',
-                        committedMixed: 'Committed changes that span both spec item files and other files.',
-                        noRelevantChanges: 'There are no relevant changes to commit.',
-                        needsBossInput: 'Committing requires additional Boss input.',
-                        needsBossReply: needsBossReplyDescription,
-                    },
+                    stateId: 'reviewIrTask',
+                    sourceItem: 'CODE-4',
+                    playbookId: 'review',
+                    text: irTaskReviewText(context),
                 }),
-                onDone: withNeedsBossReplyTransition('commitCoderInitial', [
-                    {
-                        guard: guardAndOrigin('committedSpecs', 'bossIntent'),
-                        target: '#reviewBossCommitSpecs',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: guardAndOrigin('committedCode', 'bossIntent'),
-                        target: '#reviewBossCommitCode',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: guardAndOrigin('committedMixed', 'bossIntent'),
-                        target: '#reviewBossCommitMixed',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: guardAndOrigin('committedSpecs', 'irTask'),
-                        target: '#reviewIrTaskCommitSpecs',
-                        actions: rememberCaptainOutput,
-                    },
+                onDone: [
                     {
-                        guard: guardAndOrigin('committedCode', 'irTask'),
-                        target: '#reviewIrTaskCommitCode',
-                        actions: rememberCaptainOutput,
+                        guard: 'reviewApprovedMoreTasks',
+                        target: 'runIrTask',
+                        actions: 'advanceToNextIrTask',
                     },
                     {
-                        guard: guardAndOrigin('committedMixed', 'irTask'),
-                        target: '#reviewIrTaskCommitMixed',
-                        actions: rememberCaptainOutput,
+                        guard: 'reviewApprovedFinalTask',
+                        target: 'done',
+                        actions: 'completeSuccessfully',
                     },
                     {
-                        guard: guardIs('noRelevantChanges'),
-                        target: '#ready',
-                        actions: rememberCaptainOutput,
+                        target: 'done',
+                        actions: 'completeWithInvalidReviewOutput',
                     },
+                ],
+                onError: [
                     {
-                        guard: guardIs('needsBossInput'),
-                        target: '#ready',
-                        actions: rememberCaptainOutput,
+                        guard: 'authoredReviewFailure',
+                        target: 'done',
+                        actions: 'completeWithReviewFailure',
                     },
-                ]),
-                onError: captainError,
+                    { target: 'failed', actions: 'rememberActorError' },
+                ],
             },
         },
-        commitJoint: {
-            id: 'commitJoint',
-            description: stateDescriptions.commitJoint,
-            meta: playbookMeta('commitJoint'),
-            tags: ['playbook.busy'],
-            invoke: {
-                src: 'player',
-                input: ({ context }) => ({
-                    stateId: 'commitJoint',
-                    player: 'Committer',
-                    sourceItem: 'CODE-19',
-                    ...bossReplyInputFields(context),
-                    coderPlayer: context.coderPlayer,
-                    reviewerPlayer: context.reviewerPlayer,
-                    committerPlayer: context.committerPlayer,
-                    prompt: [
-                        'Make a commit of the changes that belong in the repo, following @specs/packages/git.md (reread if necessary).',
-                        "If that spec is absent, follow the legacy @specs/dev/git.md; if neither exists, follow the repository's existing commit conventions and do not search elsewhere.",
-                        'Write the commit message concisely.',
-                        'Coder is <coder-llm>; Reviewer is <reviewer-llm>.',
-                        'Format the `Co-authored-by` `<model>` token as the conventional human form of the substituted id (e.g., `claude-opus-4-7` → `Claude-Opus-4.7`, `gpt-5.5` → `GPT-5.5`).',
-                    ].join('\n'),
-                    result: {
-                        committed: 'Relevant changes were committed.',
-                        noRelevantChanges: 'There are no relevant changes to commit.',
-                        needsBossInput: 'Committing requires additional Boss input.',
-                        needsBossReply: needsBossReplyDescription,
-                    },
-                }),
-                onDone: withNeedsBossReplyTransition('commitJoint', [
-                    {
-                        guard: ({ context, event }) => outputOf(event)?.guard === 'committed' &&
-                            context.afterReview === 'continueIr',
-                        target: '#continueIr',
-                        actions: rememberCaptainOutput,
-                    },
-                    {
-                        guard: ({ context, event }) => outputOf(event)?.guard === 'committed' &&
-                            context.afterReview === 'summarizeSpecs',
-                        target: '#summarizeSpecs',
-                        actions: rememberCaptainOutput,
-                    },
+        awaitBossReply: {
+            id: 'awaitBossReply',
+            description: STATE_DESCRIPTIONS.awaitBossReply,
+            meta: playbookMeta('awaitBossReply'),
+            tags: ['playbook.parked'],
+            on: {
+                BOSS_REPLY: [
                     {
-                        guard: ({ context, event }) => outputOf(event)?.guard === 'committed' &&
-                            context.afterReview === 'done',
-                        target: '#done',
-                        actions: rememberCaptainOutput,
+                        guard: 'emptyBossReply',
+                        target: '#failed',
+                        actions: 'rememberEmptyBossReplyError',
                     },
                     {
-                        guard: guardIs('noRelevantChanges'),
-                        target: '#done',
-                        actions: rememberCaptainOutput,
+                        guard: 'resumesFirstPhase',
+                        target: '#runFirstPhase',
+                        reenter: true,
+                        actions: 'rememberBossReply',
                     },
                     {
-                        guard: guardIs('needsBossInput'),
-                        target: '#ready',
-                        actions: rememberCaptainOutput,
+                        guard: 'resumesIrTask',
+                        target: '#runIrTask',
+                        reenter: true,
+                        actions: 'rememberBossReply',
                     },
-                ]),
-                onError: captainError,
+                ],
+                START_CODE: { target: 'runFirstPhase', actions: 'startCoding' },
             },
         },
         failed: {
             id: 'failed',
-            description: stateDescriptions.failed,
+            description: STATE_DESCRIPTIONS.failed,
             meta: playbookMeta('failed'),
             tags: ['playbook.parked'],
-            on: readyEvents,
+            on: {
+                START_CODE: { target: 'runFirstPhase', actions: 'startCoding' },
+            },
         },
         done: {
             id: 'done',
-            description: stateDescriptions.done,
+            description: STATE_DESCRIPTIONS.done,
             meta: playbookMeta('done'),
             type: 'final',
         },
     },
 });
+export default codingMachine;