@sublang/playbook 5.0.0 → 6.0.0

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

@@ -1,1769 +1,928 @@
 // 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';
 
-type Player = 'Coder' | 'Reviewer' | 'Committer';
-
-type JumpableStateId =
-  | 'ready'
-  | 'planAndImplement'
-  | 'respondToReview'
-  | 'continueIr'
-  | 'summarizeSpecs'
-  | 'reviewBossCommitSpecs'
-  | 'reviewBossCommitCode'
-  | 'reviewBossCommitMixed'
-  | 'reviewIrTaskCommitSpecs'
-  | 'reviewIrTaskCommitCode'
-  | 'reviewIrTaskCommitMixed'
-  | 'reviewChangesSpecs'
-  | 'reviewChangesCode'
-  | 'reviewChangesMixed'
-  | 'reviewChangesAndChallengesSpecs'
-  | 'reviewChangesAndChallengesCode'
-  | 'reviewChangesAndChallengesMixed'
-  | 'adjudicateChallenges'
-  | 'commitCoderInitial'
-  | 'commitJoint'
-  | 'failed';
-
-type WorkflowKind = 'singleCommit' | 'iteration' | 'specSummary';
-type ChangeOrigin = 'bossIntent' | 'irTask';
-type ReviewSubject = 'commit' | 'changes';
-type AfterReview = 'continueIr' | 'summarizeSpecs' | 'done';
-type ResumableStateId = Exclude<JumpableStateId, 'ready' | 'failed'>;
-
-type PendingBossQuestion = {
-  questionId: ResumableStateId;
-  resumeStateId: ResumableStateId;
-  sourceItem: string;
-  player: Player;
-  question: string;
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | readonly JsonValue[]
+  | { readonly [key: string]: JsonValue };
+
+export type CodeStateId =
+  | 'runFirstPhase'
+  | 'reviewFirstCommit'
+  | 'runIrTask'
+  | 'reviewIrTask';
+
+export type CodeSourceItem = 'CODE-1' | 'CODE-2' | 'CODE-3' | 'CODE-4';
+
+export type CodePhase =
+  | 'direct'
+  | 'ir-created'
+  | 'ir-task-more'
+  | 'ir-task-final';
+
+export type PendingBossQuestion = {
+  readonly questionId: 'runFirstPhase' | 'runIrTask';
+  readonly resumeStateId: 'runFirstPhase' | 'runIrTask';
+  readonly sourceItem: 'CODE-1' | 'CODE-3';
+  readonly player: 'Coder';
+  readonly question: string;
 };
 
-export type CaptainInput = {
-  stateId: ResumableStateId;
-  sourceItem: string;
-  prompt: string;
-  result: Record<string, string>;
-  // Optional structured fields the source item references but does not
-  // expose as <placeholder> tokens in the verbatim prompt. Each state
-  // populates only the fields its source item depends on; the Captain
-  // resolves placeholder tokens (e.g. IR-<#>, <coder-llm>) and grounds
-  // deictic phrasing ("below") from these.
-  intent?: string;
-  irNumber?: string;
-  taskDescription?: string;
-  reviews?: string;
-  challenges?: string;
-  coderPlayer?: string;
-  reviewerPlayer?: string;
-  // Routing-only: the configured Committer-alias player id (`coder` /
-  // `reviewer`) threaded from
-  // `captain.options.playbooks.code.options.committer` (PBRT-8 / PBRT-30).
-  // It selects which host pane runs a `Committer`
-  // commit; it is not a prompt-placeholder source, so it never affects
-  // <coder-llm> / <reviewer-llm> substitution or any labelled block,
-  // and `input.player` stays `Committer` (PLAYBOOK-3).
-  committerPlayer?: string;
-  pendingBossQuestion?: PendingBossQuestion;
-  bossReply?: string;
+export type PlayerInput = {
+  readonly stateId: 'runFirstPhase' | 'runIrTask';
+  readonly player: 'Coder';
+  readonly sourceItem: 'CODE-1' | 'CODE-3';
+  readonly prompt: string;
+  readonly result: Readonly<Record<string, string>>;
+  readonly callerInput: string;
+  readonly runResults: string;
+  readonly coderPlayer: string;
+  readonly irNumber?: string;
+  readonly irTask?: string;
+  readonly pendingBossQuestion?: PendingBossQuestion;
+  readonly bossReply?: string;
 };
 
-export type PlayerInput = CaptainInput & {
-  player: Player;
-};
+export type PlayerOutput =
+  | {
+      readonly guard: 'directCommit';
+      readonly coderOutput: string;
+      readonly latestCommit: string;
+    }
+  | {
+      readonly guard: 'irCommit';
+      readonly coderOutput: string;
+      readonly latestCommit: string;
+      readonly irNumber: string;
+      readonly irTask: string;
+    }
+  | {
+      readonly guard: 'moreTasks';
+      readonly coderOutput: string;
+      readonly latestCommit: string;
+      readonly irTask: string;
+    }
+  | {
+      readonly guard: 'finalTask';
+      readonly coderOutput: string;
+      readonly latestCommit: string;
+    }
+  | {
+      readonly guard: 'needsBossReply';
+      readonly question: string;
+    };
 
-export type CaptainOutput = {
-  guard: string;
-  irNumber?: string;
-  taskDescription?: string;
-  reviews?: string;
-  challenges?: string;
-  summary?: string;
-  question?: string;
-  [k: string]: unknown;
+export type PlaybookInput = {
+  readonly stateId: 'reviewFirstCommit' | 'reviewIrTask';
+  readonly sourceItem: 'CODE-2' | 'CODE-4';
+  readonly playbookId: 'review';
+  readonly text: string;
 };
 
-export type PlayerOutput = CaptainOutput;
-
-export type CodingInput = {
-  intent?: string;
-  irNumber?: string;
-  coderPlayer?: string;
-  reviewerPlayer?: string;
-  committerPlayer?: string;
+export type ReviewOutput = {
+  readonly approvedCommit: 'latest';
+  readonly noUnsettledFindings: true;
 };
 
-export type CodingContext = CodingInput & {
-  workflow?: WorkflowKind;
-  changeOrigin?: ChangeOrigin;
-  reviewSubject?: ReviewSubject;
-  afterReview?: AfterReview;
-  taskDescription?: string;
-  reviews?: string;
-  challenges?: string;
-  lastResult?: CaptainOutput;
-  lastError?: unknown;
-  pendingBossQuestion?: PendingBossQuestion;
-  bossReply?: string;
+export type CompactError = {
+  readonly name: string;
+  readonly message: string;
 };
 
-export type CodingEvent =
-  | { type: 'START_CODING'; intent: string }
-  | { type: 'CONTINUE_IR'; irNumber: string }
-  | { type: 'SUMMARIZE_IR'; irNumber: string }
+export type CodePlaybookOutput =
   | {
-      type: 'BOSS_INTERRUPT';
-      targetId: JumpableStateId;
-      intent?: string;
-      irNumber?: string;
+      readonly status: 'complete';
+      /** Exact identity of the latest CODE-owned commit. */
+      readonly lastCodeCommit: string;
+      /** Exact Coder final text produced after that commit. */
+      readonly lastCodeOutput: string;
     }
   | {
-      type: 'BOSS_REPLY';
-      answer: string;
-      questionId?: ResumableStateId;
+      readonly status: 'review-failed';
+      /** Exact identity of the latest CODE-owned commit. */
+      readonly lastCodeCommit: string;
+      /** Exact Coder final text produced after that commit. */
+      readonly lastCodeOutput: string;
+      readonly error: CompactError;
     };
 
-const jumpableStateIds = [
-  'ready',
-  'planAndImplement',
-  'respondToReview',
-  'continueIr',
-  'summarizeSpecs',
-  'reviewBossCommitSpecs',
-  'reviewBossCommitCode',
-  'reviewBossCommitMixed',
-  'reviewIrTaskCommitSpecs',
-  'reviewIrTaskCommitCode',
-  'reviewIrTaskCommitMixed',
-  'reviewChangesSpecs',
-  'reviewChangesCode',
-  'reviewChangesMixed',
-  'reviewChangesAndChallengesSpecs',
-  'reviewChangesAndChallengesCode',
-  'reviewChangesAndChallengesMixed',
-  'adjudicateChallenges',
-  'commitCoderInitial',
-  'commitJoint',
-  'failed',
-] as const satisfies readonly JumpableStateId[];
-
-const resumableStateIds = [
-  'planAndImplement',
-  'respondToReview',
-  'continueIr',
-  'summarizeSpecs',
-  'reviewBossCommitSpecs',
-  'reviewBossCommitCode',
-  'reviewBossCommitMixed',
-  'reviewIrTaskCommitSpecs',
-  'reviewIrTaskCommitCode',
-  'reviewIrTaskCommitMixed',
-  'reviewChangesSpecs',
-  'reviewChangesCode',
-  'reviewChangesMixed',
-  'reviewChangesAndChallengesSpecs',
-  'reviewChangesAndChallengesCode',
-  'reviewChangesAndChallengesMixed',
-  'adjudicateChallenges',
-  'commitCoderInitial',
-  'commitJoint',
-] as const satisfies readonly ResumableStateId[];
-
-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.',
-} as const satisfies Record<
-  JumpableStateId | 'awaitBossReply' | 'done',
-  string
->;
-
-const playbookMeta = <StateId extends keyof typeof stateDescriptions>(
-  stateId: StateId,
-) => ({
-  playbook: {
-    stateId,
-    description: stateDescriptions[stateId],
-  },
-});
-
-const outputOf = (event: unknown): CaptainOutput | undefined =>
-  (event as { output?: CaptainOutput }).output;
-
-const guardIs =
-  (guard: string) =>
-  ({ event }: { event: unknown }) =>
-    outputOf(event)?.guard === guard;
-
-const guardAndOrigin =
-  (guard: string, origin: ChangeOrigin) =>
-  ({ context, event }: { context: CodingContext; event: unknown }) =>
-    outputOf(event)?.guard === guard && context.changeOrigin === origin;
-
-const acceptedAfter =
-  (subject: ReviewSubject) =>
-  ({ context, event }: { context: CodingContext; event: unknown }) =>
-    outputOf(event)?.guard === 'accepted' && context.reviewSubject === subject;
-
-const noFindingsAfter =
-  (afterReview: AfterReview) =>
-  ({ context, event }: { context: CodingContext; event: unknown }) =>
-    outputOf(event)?.guard === 'noFindings' &&
-    context.afterReview === afterReview;
-
-const rememberCaptainOutput = assign({
-  lastResult: ({ event }: { event: unknown }) => outputOf(event),
-  lastError: () => undefined,
-  irNumber: ({ context, event }: { context: CodingContext; event: unknown }) =>
-    outputOf(event)?.irNumber ?? context.irNumber,
-  taskDescription: ({
-    context,
-    event,
-  }: {
-    context: CodingContext;
-    event: unknown;
-  }) => outputOf(event)?.taskDescription ?? context.taskDescription,
-  reviews: ({ context, event }: { context: CodingContext; event: unknown }) =>
-    outputOf(event)?.reviews ?? context.reviews,
-  challenges: ({
-    context,
-    event,
-  }: {
-    context: CodingContext;
-    event: unknown;
-  }) => outputOf(event)?.challenges ?? context.challenges,
-});
-
-const rememberCaptainError = assign({
-  lastError: ({ event }: { event: unknown }) =>
-    (event as { error?: unknown }).error,
-});
-
-const rememberEmptyBossReplyError = assign({
-  lastError: () => new Error('BOSS_REPLY received empty answer'),
-});
-
-const rememberBossInput = assign({
-  intent: ({ context, event }: { context: CodingContext; event: unknown }) =>
-    (event as { intent?: string }).intent ?? context.intent,
-  irNumber: ({ context, event }: { context: CodingContext; event: unknown }) =>
-    (event as { irNumber?: string }).irNumber ?? context.irNumber,
-});
-
-type PlayerInputFactory = (context: Partial<CodingContext>) => PlayerInput;
-
-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: Partial<CodingContext>) => ({
-  pendingBossQuestion: context.pendingBossQuestion,
-  bossReply: context.bossReply,
-});
-
-const withNeedsBossReply = <T extends Record<string, string>>(result: T) => ({
-  ...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' },
-} as const satisfies Record<
-  ResumableStateId,
-  { sourceItem: string; player: Player }
->;
-
-const planAndImplementInput: PlayerInputFactory = (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: PlayerInputFactory = (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: PlayerInputFactory = (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: ResumableStateId) =>
-  assign({
-    pendingBossQuestion: ({
-      context,
-      event,
-    }: {
-      context: CodingContext;
-      event: unknown;
-    }) => {
-      const input = captainStateMetadata[resumeStateId];
-      return {
-        questionId: resumeStateId,
-        resumeStateId,
-        sourceItem: input.sourceItem,
-        player: input.player,
-        question: outputOf(event)?.question ?? '',
-      };
-    },
-    bossReply: () => undefined,
-  });
-
-const rememberBossReply = assign({
-  bossReply: ({ event }: { event: unknown }) =>
-    (event as { answer?: string }).answer ?? '',
-});
-
-const clearBossReplyContext = assign({
-  pendingBossQuestion: () => undefined,
-  bossReply: () => undefined,
-});
-
-const actionsArray = (actions: unknown) =>
-  actions === undefined ? [] : Array.isArray(actions) ? actions : [actions];
-
-const withClearBossReplyContext = <T extends { actions?: unknown }>(
-  transition: T,
-): T => ({
-  ...transition,
-  actions: [clearBossReplyContext, ...actionsArray(transition.actions)],
-});
-
-const bossInterrupts = (
-  ids: readonly JumpableStateId[],
-  extraActions: readonly unknown[] = [],
-) =>
-  ids.map((id) => ({
-    target: `#${id}` as const,
-    guard: ({ event }: { event: CodingEvent }) =>
-      event.type === 'BOSS_INTERRUPT' && event.targetId === id,
-    reenter: true,
-    actions: [...extraActions, rememberBossInput],
-  }));
-
-const resumableStates = (ids: readonly ResumableStateId[]) =>
-  ids.map((id) => ({
-    target: `#${id}` as const,
-    guard: ({
-      context,
-      event,
-    }: {
-      context: CodingContext;
-      event: CodingEvent;
-    }) =>
-      event.type === 'BOSS_REPLY' &&
-      context.pendingBossQuestion?.resumeStateId === id &&
-      (event.questionId === undefined ||
-        event.questionId === context.pendingBossQuestion.questionId),
-    reenter: true,
-    actions: rememberBossReply,
-  }));
-
-const bossReplyIsEmpty = ({ event }: { event: CodingEvent }) =>
-  event.type === 'BOSS_REPLY' && event.answer.trim() === '';
-
-const withNeedsBossReplyTransition = <
-  T extends readonly { guard?: unknown; target?: unknown; actions?: unknown }[],
->(
-  resumeStateId: ResumableStateId,
-  transitions: T,
-) => [
-  ...transitions.map((transition) => withClearBossReplyContext(transition)),
-  {
-    guard: guardIs('needsBossReply'),
-    target: '#awaitBossReply',
-    actions: [rememberCaptainOutput, setPendingBossQuestion(resumeStateId)],
-  },
-];
-
-const captainError = {
-  target: '#failed',
-  actions: rememberCaptainError,
+export type CodingInput = {
+  readonly coderPlayer?: string;
+  readonly runResults?: string;
 };
 
-const readyEvents = {
-  START_CODING: {
-    target: '#planAndImplement',
-    actions: [
-      rememberBossInput,
-      assign({
-        workflow: () => 'singleCommit' as const,
-        changeOrigin: () => 'bossIntent' as const,
-        afterReview: () => 'done' as const,
-      }),
-    ],
-  },
-  CONTINUE_IR: {
-    target: '#continueIr',
-    actions: [
-      rememberBossInput,
-      assign({
-        workflow: () => 'iteration' as const,
-        changeOrigin: () => 'irTask' as const,
-        afterReview: () => 'continueIr' as const,
-      }),
-    ],
-  },
-  SUMMARIZE_IR: {
-    target: '#summarizeSpecs',
-    actions: [
-      rememberBossInput,
-      assign({
-        workflow: () => 'specSummary' as const,
-        changeOrigin: () => 'irTask' as const,
-        afterReview: () => 'done' as const,
-      }),
-    ],
-  },
+export type CodingContext = {
+  readonly coderPlayer: string;
+  readonly runResults: string;
+  readonly callerInput?: string;
+  readonly coderOutput?: string;
+  readonly latestCommit?: string;
+  readonly irNumber?: string;
+  readonly irTask?: string;
+  readonly nextIrTask?: string;
+  readonly phase?: CodePhase;
+  readonly completion?: 'complete' | 'review-failed';
+  readonly reviewError?: CompactError;
+  readonly lastError?: unknown;
+  readonly pendingBossQuestion?: PendingBossQuestion;
+  readonly bossReply?: string;
 };
 
-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],
+export type CodingEvent =
+  | { readonly type: 'START_CODE'; readonly callerInput: string }
+  | {
+      readonly type: 'BOSS_REPLY';
+      readonly answer: string;
+      readonly questionId?: 'runFirstPhase' | 'runIrTask';
+    };
+
+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>`.",
+} as const;
+
+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>`.",
+} as const;
+
+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.',
+} as const;
+
+function playbookMeta<StateId extends keyof typeof STATE_DESCRIPTIONS>(
+  stateId: StateId,
+  player?: 'Coder',
+) {
+  return {
+    playbook: {
+      stateId,
+      description: STATE_DESCRIPTIONS[stateId],
+      ...(player === undefined ? {} : { player }),
     },
-    ...resumableStates(resumableStateIds),
-  ],
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function playerOutput(event: unknown): Record<string, unknown> | undefined {
+  if (!isRecord(event)) return undefined;
+  return isRecord(event.output) ? event.output : undefined;
+}
+
+function outputGuard(event: unknown, guard: PlayerOutput['guard']): boolean {
+  return playerOutput(event)?.guard === guard;
+}
+
+function outputString(event: unknown, field: string): string | undefined {
+  const value = playerOutput(event)?.[field];
+  return isNonEmptyString(value) ? value : undefined;
+}
+
+function commitOutput(
+  event: unknown,
+): { readonly coderOutput: string; readonly latestCommit: string } | undefined {
+  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 }: { event: unknown }): boolean {
+  return (
+    outputGuard(event, 'directCommit') &&
+    commitOutput(event) !== undefined
+  );
+}
+
+function isIrCommit({ event }: { event: unknown }): boolean {
+  return (
+    outputGuard(event, 'irCommit') &&
+    commitOutput(event) !== undefined &&
+    outputString(event, 'irNumber') !== undefined &&
+    outputString(event, 'irTask') !== undefined
+  );
+}
+
+function isMoreTasks({ event }: { event: unknown }): boolean {
+  return (
+    outputGuard(event, 'moreTasks') &&
+    commitOutput(event) !== undefined &&
+    outputString(event, 'irTask') !== undefined
+  );
+}
+
+function isFinalTask({ event }: { event: unknown }): boolean {
+  return (
+    outputGuard(event, 'finalTask') &&
+    commitOutput(event) !== undefined
+  );
+}
+
+function needsBossReply({ event }: { event: unknown }): boolean {
+  return (
+    outputGuard(event, 'needsBossReply') &&
+    outputString(event, 'question') !== undefined
+  );
+}
+
+function reviewOutput(event: unknown): unknown {
+  return isRecord(event) ? event.output : undefined;
+}
+
+function isReviewApprovedValue(value: unknown): value is ReviewOutput {
+  return (
+    isRecord(value) &&
+    Object.keys(value).sort().join('\0') ===
+      ['approvedCommit', 'noUnsettledFindings'].sort().join('\0') &&
+    value.approvedCommit === 'latest' &&
+    value.noUnsettledFindings === true
+  );
+}
+
+function reviewApprovedFor(
+  phase: CodePhase,
+): (args: { context: CodingContext; event: unknown }) => boolean {
+  return ({ context, event }) =>
+    context.phase === phase && isReviewApprovedValue(reviewOutput(event));
+}
+
+function isStateValue(value: unknown, ancestors = new Set<object>()): boolean {
+  if (typeof value === 'string') return true;
+  if (!isRecord(value) || ancestors.has(value)) return false;
+  const next = new Set(ancestors).add(value);
+  return Reflect.ownKeys(value).every(
+    (key) =>
+      typeof key === 'string' &&
+      Object.prototype.propertyIsEnumerable.call(value, key) &&
+      isStateValue(value[key], next),
+  );
+}
+
+function isStringArray(value: unknown): value is readonly string[] {
+  return (
+    Array.isArray(value) &&
+    Reflect.ownKeys(value).length === value.length + 1 &&
+    Reflect.ownKeys(value).every((key) => {
+      if (key === 'length') return true;
+      return (
+        typeof key === 'string' &&
+        /^(0|[1-9][0-9]*)$/.test(key) &&
+        Number(key) < value.length
+      );
+    }) &&
+    value.every((entry) => isNonEmptyString(entry)) &&
+    new Set(value).size === value.length
+  );
+}
+
+function isPlaybookState(value: unknown): boolean {
+  if (!isRecord(value)) return false;
+  const allowed = new Set([
+    'value',
+    'activeStateIds',
+    'tags',
+    'status',
+    'quiescent',
+    'stateId',
+  ]);
+  if (
+    Reflect.ownKeys(value).some(
+      (key) => typeof key !== 'string' || !allowed.has(key),
+    ) ||
+    !Object.prototype.hasOwnProperty.call(value, 'value') ||
+    !Object.prototype.hasOwnProperty.call(value, 'activeStateIds') ||
+    !Object.prototype.hasOwnProperty.call(value, 'tags') ||
+    !Object.prototype.hasOwnProperty.call(value, 'status') ||
+    !Object.prototype.hasOwnProperty.call(value, 'quiescent')
+  ) {
+    return false;
+  }
+  return (
+    isStateValue(value.value) &&
+    isStringArray(value.activeStateIds) &&
+    isStringArray(value.tags) &&
+    (value.status === 'active' ||
+      value.status === 'done' ||
+      value.status === 'error' ||
+      value.status === 'stopped') &&
+    typeof value.quiescent === 'boolean' &&
+    (!Object.prototype.hasOwnProperty.call(value, 'stateId') ||
+      (isNonEmptyString(value.stateId) &&
+        value.activeStateIds.length === 1 &&
+        value.activeStateIds[0] === value.stateId))
+  );
+}
+
+function nestedResultFromError(error: unknown): Record<string, unknown> | undefined {
+  if (!(error instanceof Error)) return undefined;
+  const result = (error as Error & { readonly result?: unknown }).result;
+  return isRecord(result) ? result : undefined;
+}
+
+type AuthoredReviewFailure = {
+  readonly status: 'aborted' | 'error';
+  readonly error?: CompactError;
 };
 
-const playerPlaceholder = fromPromise<PlayerOutput, PlayerInput>(async () => {
-  throw new Error('player actor must be provided by the runner');
-});
-
-export const codingMachine = setup({
+function normalizedReviewFailure(
+  error: unknown,
+): AuthoredReviewFailure | undefined {
+  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: CompactError | undefined;
+  if (Object.prototype.hasOwnProperty.call(result, 'error')) {
+    if (!isRecord(result.error)) return undefined;
+    const errorKeys = Reflect.ownKeys(result.error);
+    if (
+      errorKeys.some(
+        (key) =>
+          typeof key !== 'string' ||
+          (key !== 'name' && key !== 'message' && key !== 'stack'),
+      ) ||
+      !Object.prototype.hasOwnProperty.call(result.error, 'name') ||
+      !Object.prototype.hasOwnProperty.call(result.error, 'message') ||
+      !isNonEmptyString(result.error.name) ||
+      typeof result.error.message !== 'string' ||
+      (Object.prototype.hasOwnProperty.call(result.error, 'stack') &&
+        typeof result.error.stack !== 'string')
+    ) {
+      return undefined;
+    }
+    normalizedError = {
+      name: result.error.name,
+      message: result.error.message,
+    };
+  } else if (result.status === 'error') {
+    return undefined;
+  }
+  return {
+    status: result.status,
+    ...(normalizedError === undefined ? {} : { error: normalizedError }),
+  };
+}
+
+function authoredReviewFailure({ event }: { event: unknown }): boolean {
+  const error = isRecord(event) ? event.error : undefined;
+  return normalizedReviewFailure(error) !== undefined;
+}
+
+function compactError(value: unknown): CompactError {
+  if (value instanceof Error) {
+    return {
+      name: value.name || 'Error',
+      message: value.message,
+    };
+  }
+  return { name: 'Error', message: String(value) };
+}
+
+function authoredReviewError(event: unknown): CompactError {
+  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: string, value: string): string {
+  const lines = value.split('\n');
+  return [`> ${label}: ${lines[0] ?? ''}`, ...lines.slice(1).map((line) => `> ${line}`)].join(
+    '\n',
+  );
+}
+
+function initialReviewText(context: CodingContext): string {
+  return [
+    quoteRelay('Initial intent', context.callerInput ?? ''),
+    quoteRelay('Coder output', context.coderOutput ?? ''),
+  ].join('\n');
+}
+
+function irTaskReviewText(context: CodingContext): string {
+  return [
+    quoteRelay('IR task', context.irTask ?? ''),
+    quoteRelay('Coder output', context.coderOutput ?? ''),
+  ].join('\n');
+}
+
+const machineSetup = setup({
   types: {} as {
     context: CodingContext;
     events: CodingEvent;
-    input: CodingInput | undefined;
+    input: CodingInput;
+    output: CodePlaybookOutput;
   },
   actors: {
-    player: playerPlaceholder,
+    player: fromPromise<PlayerOutput, PlayerInput>(async () => {
+      throw new Error('player actor must be provided by the runner');
+    }),
+    playbook: fromPromise<JsonValue | undefined, PlaybookInput>(async () => {
+      throw new Error('playbook actor must be provided by the runner');
+    }),
   },
-}).createMachine({
-  id: 'coding',
+  guards: {
+    isDirectCommit,
+    isIrCommit,
+    isMoreTasks,
+    isFinalTask,
+    needsBossReply,
+    reviewApprovedDirect: reviewApprovedFor('direct'),
+    reviewApprovedIrCreated: reviewApprovedFor('ir-created'),
+    reviewApprovedMoreTasks: reviewApprovedFor('ir-task-more'),
+    reviewApprovedFinalTask: reviewApprovedFor('ir-task-final'),
+    authoredReviewFailure,
+    emptyBossReply: ({ event }) =>
+      event.type === 'BOSS_REPLY' && event.answer.trim().length === 0,
+    resumesFirstPhase: ({ context, event }) =>
+      event.type === 'BOSS_REPLY' &&
+      event.answer.trim().length > 0 &&
+      context.pendingBossQuestion?.resumeStateId === 'runFirstPhase' &&
+      (event.questionId === undefined || event.questionId === 'runFirstPhase'),
+    resumesIrTask: ({ context, event }) =>
+      event.type === 'BOSS_REPLY' &&
+      event.answer.trim().length > 0 &&
+      context.pendingBossQuestion?.resumeStateId === 'runIrTask' &&
+      (event.questionId === undefined || event.questionId === 'runIrTask'),
+  },
+  actions: {
+    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' as const,
+      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' as const,
+      pendingBossQuestion: undefined,
+      bossReply: undefined,
+    })),
+    rememberMoreTasks: assign(({ event }) => ({
+      coderOutput: outputString(event, 'coderOutput'),
+      latestCommit: outputString(event, 'latestCommit'),
+      nextIrTask: outputString(event, 'irTask'),
+      phase: 'ir-task-more' as const,
+      pendingBossQuestion: undefined,
+      bossReply: undefined,
+    })),
+    rememberFinalTask: assign(({ event }) => ({
+      coderOutput: outputString(event, 'coderOutput'),
+      latestCommit: outputString(event, 'latestCommit'),
+      nextIrTask: undefined,
+      phase: 'ir-task-final' as const,
+      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' as const,
+      reviewError: authoredReviewError(event),
+    })),
+    completeWithInvalidReviewOutput: assign(({ event }) => ({
+      completion: 'review-failed' as const,
+      reviewError: {
+        name: 'ReviewContractError',
+        message:
+          `REVIEW returned an invalid approval result: ` +
+          JSON.stringify(reviewOutput(event)),
+      },
+    })),
+    rememberActorError: assign(({ event }) => ({
+      lastError: (event as unknown as { readonly error?: unknown }).error,
+    })),
+    rememberMalformedPlayerOutput: assign(({ context }) => ({
+      lastError: new Error(
+        `Coder result for ${context.irNumber === undefined ? 'CODE-1' : 'CODE-3'} ` +
+          'did not match a declared outcome.',
+      ),
+    })),
+  },
+});
+
+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 }): CodePlaybookOutput => {
+    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 }): PlayerInput => planAndImplementInput(context),
-        onDone: withNeedsBossReplyTransition('planAndImplement', [
-          {
-            guard: guardIs('singleCommitReady'),
-            target: '#commitCoderInitial',
-            actions: [
-              rememberCaptainOutput,
-              assign({
-                workflow: () => 'singleCommit' as const,
-                changeOrigin: () => 'bossIntent' as const,
-                afterReview: () => 'done' as const,
-              }),
-            ],
-          },
-          {
-            guard: guardIs('irDrafted'),
-            target: '#commitCoderInitial',
-            actions: [
-              rememberCaptainOutput,
-              assign({
-                workflow: () => 'iteration' as const,
-                changeOrigin: () => 'bossIntent' as const,
-                afterReview: () => 'continueIr' as const,
-              }),
-            ],
-          },
-        ]),
-        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 }): PlayerInput => ({
-          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 }): PlayerInput => continueIrInput(context),
-        onDone: withNeedsBossReplyTransition('continueIr', [
-          {
-            guard: guardIs('taskReady'),
-            target: '#commitCoderInitial',
-            actions: [
-              rememberCaptainOutput,
-              assign({
-                workflow: () => 'iteration' as const,
-                changeOrigin: () => 'irTask' as const,
-                afterReview: () => 'continueIr' as const,
-              }),
-            ],
-          },
-          {
-            guard: guardIs('iterationDone'),
-            target: '#summarizeSpecs',
-            actions: [
-              rememberCaptainOutput,
-              assign({
-                workflow: () => 'specSummary' as const,
-                afterReview: () => 'done' as const,
-              }),
-            ],
-          },
-        ]),
-        onError: captainError,
-      },
-    },
-
-    summarizeSpecs: {
-      id: 'summarizeSpecs',
-      description: stateDescriptions.summarizeSpecs,
-      meta: playbookMeta('summarizeSpecs'),
-      tags: ['playbook.busy'],
-      invoke: {
-        src: 'player',
-        input: ({ context }): PlayerInput => summarizeSpecsInput(context),
-        onDone: withNeedsBossReplyTransition('summarizeSpecs', [
-          {
-            guard: guardIs('specsReady'),
-            target: '#commitCoderInitial',
-            actions: [
-              rememberCaptainOutput,
-              assign({
-                workflow: () => 'specSummary' as const,
-                changeOrigin: () => 'irTask' as const,
-                afterReview: () => 'done' as const,
-              }),
-            ],
-          },
-          {
-            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 }): PlayerInput => ({
-          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' as const }),
-            ],
-          },
-        ]),
-        onError: captainError,
-      },
-    },
-
-    reviewBossCommitCode: {
-      id: 'reviewBossCommitCode',
-      description: stateDescriptions.reviewBossCommitCode,
-      meta: playbookMeta('reviewBossCommitCode'),
-      tags: ['playbook.busy'],
-      invoke: {
-        src: 'player',
-        input: ({ context }): PlayerInput => ({
-          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' as const }),
-            ],
-          },
-        ]),
-        onError: captainError,
-      },
-    },
-
-    reviewBossCommitMixed: {
-      id: 'reviewBossCommitMixed',
-      description: stateDescriptions.reviewBossCommitMixed,
-      meta: playbookMeta('reviewBossCommitMixed'),
-      tags: ['playbook.busy'],
-      invoke: {
-        src: 'player',
-        input: ({ context }): PlayerInput => ({
-          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' as const }),
-            ],
-          },
-        ]),
-        onError: captainError,
-      },
-    },
-
-    reviewIrTaskCommitSpecs: {
-      id: 'reviewIrTaskCommitSpecs',
-      description: stateDescriptions.reviewIrTaskCommitSpecs,
-      meta: playbookMeta('reviewIrTaskCommitSpecs'),
-      tags: ['playbook.busy'],
-      invoke: {
-        src: 'player',
-        input: ({ context }): PlayerInput => ({
-          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' as const }),
-            ],
-          },
-        ]),
-        onError: captainError,
-      },
-    },
-
-    reviewIrTaskCommitCode: {
-      id: 'reviewIrTaskCommitCode',
-      description: stateDescriptions.reviewIrTaskCommitCode,
-      meta: playbookMeta('reviewIrTaskCommitCode'),
-      tags: ['playbook.busy'],
-      invoke: {
-        src: 'player',
-        input: ({ context }): PlayerInput => ({
-          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' as const }),
-            ],
-          },
-        ]),
-        onError: captainError,
-      },
-    },
-
-    reviewIrTaskCommitMixed: {
-      id: 'reviewIrTaskCommitMixed',
-      description: stateDescriptions.reviewIrTaskCommitMixed,
-      meta: playbookMeta('reviewIrTaskCommitMixed'),
-      tags: ['playbook.busy'],
-      invoke: {
-        src: 'player',
-        input: ({ context }): PlayerInput => ({
-          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' as const }),
-            ],
-          },
-        ]),
-        onError: captainError,
-      },
-    },
-
-    reviewChangesSpecs: {
-      id: 'reviewChangesSpecs',
-      description: stateDescriptions.reviewChangesSpecs,
-      meta: playbookMeta('reviewChangesSpecs'),
-      tags: ['playbook.busy'],
-      invoke: {
-        src: 'player',
-        input: ({ context }): PlayerInput => ({
-          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,
-          },
+          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('reviewChangesSpecs', [
+        onDone: [
           {
-            guard: guardIs('noFindings'),
-            target: '#commitJoint',
-            actions: rememberCaptainOutput,
+            guard: 'isDirectCommit',
+            target: 'reviewFirstCommit',
+            actions: 'rememberDirectCommit',
           },
           {
-            guard: guardIs('hasFindings'),
-            target: '#respondToReview',
-            actions: [
-              rememberCaptainOutput,
-              assign({ reviewSubject: () => 'changes' as const }),
-            ],
+            guard: 'isIrCommit',
+            target: 'reviewFirstCommit',
+            actions: 'rememberIrCommit',
           },
-        ]),
-        onError: captainError,
-      },
-    },
-
-    reviewChangesCode: {
-      id: 'reviewChangesCode',
-      description: stateDescriptions.reviewChangesCode,
-      meta: playbookMeta('reviewChangesCode'),
-      tags: ['playbook.busy'],
-      invoke: {
-        src: 'player',
-        input: ({ context }): PlayerInput => ({
-          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: 'needsBossReply',
+            target: 'awaitBossReply',
+            actions: 'rememberPendingQuestion',
           },
           {
-            guard: guardIs('hasFindings'),
-            target: '#respondToReview',
-            actions: [
-              rememberCaptainOutput,
-              assign({ reviewSubject: () => 'changes' as const }),
-            ],
+            target: 'failed',
+            actions: 'rememberMalformedPlayerOutput',
           },
-        ]),
-        onError: captainError,
+        ],
+        onError: { target: 'failed', actions: 'rememberActorError' },
       },
     },
-
-    reviewChangesMixed: {
-      id: 'reviewChangesMixed',
-      description: stateDescriptions.reviewChangesMixed,
-      meta: playbookMeta('reviewChangesMixed'),
-      tags: ['playbook.busy'],
+    reviewFirstCommit: {
+      id: 'reviewFirstCommit',
+      description: STATE_DESCRIPTIONS.reviewFirstCommit,
+      meta: playbookMeta('reviewFirstCommit'),
+      tags: ['playbook.suspended'],
       invoke: {
-        src: 'player',
-        input: ({ context }): PlayerInput => ({
-          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,
-          },
+        src: 'playbook',
+        input: ({ context }): PlaybookInput => ({
+          stateId: 'reviewFirstCommit',
+          sourceItem: 'CODE-2',
+          playbookId: 'review',
+          text: initialReviewText(context),
         }),
-        onDone: withNeedsBossReplyTransition('reviewChangesMixed', [
+        onDone: [
           {
-            guard: guardIs('noFindings'),
-            target: '#commitJoint',
-            actions: rememberCaptainOutput,
+            guard: 'reviewApprovedDirect',
+            target: 'done',
+            actions: 'completeSuccessfully',
           },
           {
-            guard: guardIs('hasFindings'),
-            target: '#respondToReview',
-            actions: [
-              rememberCaptainOutput,
-              assign({ reviewSubject: () => 'changes' as const }),
-            ],
+            guard: 'reviewApprovedIrCreated',
+            target: 'runIrTask',
           },
-        ]),
-        onError: captainError,
-      },
-    },
-
-    reviewChangesAndChallengesSpecs: {
-      id: 'reviewChangesAndChallengesSpecs',
-      description: stateDescriptions.reviewChangesAndChallengesSpecs,
-      meta: playbookMeta('reviewChangesAndChallengesSpecs'),
-      tags: ['playbook.busy'],
-      invoke: {
-        src: 'player',
-        input: ({ context }): PlayerInput => ({
-          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,
-          },
-        }),
-        onDone: withNeedsBossReplyTransition(
-          'reviewChangesAndChallengesSpecs',
-          [
-            {
-              guard: guardIs('approved'),
-              target: '#commitJoint',
-              actions: rememberCaptainOutput,
-            },
-            {
-              guard: guardIs('needsRevision'),
-              target: '#respondToReview',
-              actions: [
-                rememberCaptainOutput,
-                assign({ reviewSubject: () => 'changes' as const }),
-              ],
-            },
-          ],
-        ),
-        onError: captainError,
-      },
-    },
-
-    reviewChangesAndChallengesCode: {
-      id: 'reviewChangesAndChallengesCode',
-      description: stateDescriptions.reviewChangesAndChallengesCode,
-      meta: playbookMeta('reviewChangesAndChallengesCode'),
-      tags: ['playbook.busy'],
-      invoke: {
-        src: 'player',
-        input: ({ context }): PlayerInput => ({
-          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,
-          },
-        }),
-        onDone: withNeedsBossReplyTransition('reviewChangesAndChallengesCode', [
           {
-            guard: guardIs('approved'),
-            target: '#commitJoint',
-            actions: rememberCaptainOutput,
+            target: 'done',
+            actions: 'completeWithInvalidReviewOutput',
           },
+        ],
+        onError: [
           {
-            guard: guardIs('needsRevision'),
-            target: '#respondToReview',
-            actions: [
-              rememberCaptainOutput,
-              assign({ reviewSubject: () => 'changes' as const }),
-            ],
-          },
-        ]),
-        onError: captainError,
-      },
-    },
-
-    reviewChangesAndChallengesMixed: {
-      id: 'reviewChangesAndChallengesMixed',
-      description: stateDescriptions.reviewChangesAndChallengesMixed,
-      meta: playbookMeta('reviewChangesAndChallengesMixed'),
-      tags: ['playbook.busy'],
-      invoke: {
-        src: 'player',
-        input: ({ context }): PlayerInput => ({
-          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: 'authoredReviewFailure',
+            target: 'done',
+            actions: 'completeWithReviewFailure',
           },
-        }),
-        onDone: withNeedsBossReplyTransition(
-          'reviewChangesAndChallengesMixed',
-          [
-            {
-              guard: guardIs('approved'),
-              target: '#commitJoint',
-              actions: rememberCaptainOutput,
-            },
-            {
-              guard: guardIs('needsRevision'),
-              target: '#respondToReview',
-              actions: [
-                rememberCaptainOutput,
-                assign({ reviewSubject: () => 'changes' as const }),
-              ],
-            },
-          ],
-        ),
-        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 }): PlayerInput => ({
-          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',
-        input: ({ context }): PlayerInput => ({
-          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,
-          },
+        src: 'playbook',
+        input: ({ context }): PlaybookInput => ({
+          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,
-          },
+        onDone: [
           {
-            guard: guardAndOrigin('committedSpecs', 'irTask'),
-            target: '#reviewIrTaskCommitSpecs',
-            actions: rememberCaptainOutput,
+            guard: 'reviewApprovedMoreTasks',
+            target: 'runIrTask',
+            actions: 'advanceToNextIrTask',
           },
           {
-            guard: guardAndOrigin('committedCode', 'irTask'),
-            target: '#reviewIrTaskCommitCode',
-            actions: rememberCaptainOutput,
+            guard: 'reviewApprovedFinalTask',
+            target: 'done',
+            actions: 'completeSuccessfully',
           },
           {
-            guard: guardAndOrigin('committedMixed', 'irTask'),
-            target: '#reviewIrTaskCommitMixed',
-            actions: rememberCaptainOutput,
+            target: 'done',
+            actions: 'completeWithInvalidReviewOutput',
           },
+        ],
+        onError: [
           {
-            guard: guardIs('noRelevantChanges'),
-            target: '#ready',
-            actions: rememberCaptainOutput,
+            guard: 'authoredReviewFailure',
+            target: 'done',
+            actions: 'completeWithReviewFailure',
           },
-          {
-            guard: guardIs('needsBossInput'),
-            target: '#ready',
-            actions: rememberCaptainOutput,
-          },
-        ]),
-        onError: captainError,
+          { target: 'failed', actions: 'rememberActorError' },
+        ],
       },
     },
-
-    commitJoint: {
-      id: 'commitJoint',
-      description: stateDescriptions.commitJoint,
-      meta: playbookMeta('commitJoint'),
-      tags: ['playbook.busy'],
-      invoke: {
-        src: 'player',
-        input: ({ context }): PlayerInput => ({
-          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;