@sublang/playbook 15.0.0 → 16.0.0

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

@@ -1,95 +1,190 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
-
-// FSM object artifact compiled from review.gears.md.
-// The linked runtime supplies the delegated-player actor.
+//
+// FSM object artifact compiled from ./review.gears.md by gears2fsm.
+// It declares only the machine, its actor contracts, and typed inputs; the
+// linked runtime supplies the `player` actor implementation.
 
 import { assign, fromPromise, setup } from 'xstate';
 
-type Role = 'coder' | 'reviewer';
+// ---------------------------------------------------------------------------
+// Identities
+// ---------------------------------------------------------------------------
+
+/** Canonical lowercase local ids of the source roles Coder and Reviewer. */
+export type ReviewRole = 'coder' | 'reviewer';
+
+/** One role-id array per parallel group; REVIEW declares no parallel group. */
+export const concurrentRoleSets: readonly (readonly ReviewRole[])[] = [];
+
+/** Delegated-player working leaves (REVIEW-1 through REVIEW-4). */
+export type WorkingStateId =
+  | 'firstReview'
+  | 'fixFindings'
+  | 'reviewAfterFix'
+  | 'reviewAfterRejection';
+
+/** Working leaves that may suspend for, and resume from, a Boss reply. */
+export type ResumableStateId = WorkingStateId;
+
+/** Root `BOSS_INTERRUPT` targets. */
+export type JumpableStateId = WorkingStateId;
 
-type JumpableStateId = 'reviewInitial';
+export type ReviewSourceItem = 'REVIEW-1' | 'REVIEW-2' | 'REVIEW-3' | 'REVIEW-4';
 
-export type ResumableStateId =
-  | 'reviewInitial'
-  | 'addressFindings'
-  | 'reviewAfterCommit'
-  | 'reviewAfterRebuttal';
+/** Coder's accepted disposition of the latest findings. */
+export type CoderOutcome = 'committed' | 'rejectedAll';
+
+// ---------------------------------------------------------------------------
+// Boss-reply suspension (scalar form: one active player task at a time)
+// ---------------------------------------------------------------------------
 
 export interface PendingBossQuestion {
-  questionId: ResumableStateId;
-  resumeStateId: ResumableStateId;
-  sourceItem: `REVIEW-${1 | 2 | 3 | 4}`;
-  asker: { readonly kind: 'role'; readonly roleId: Role };
-  question: string;
+  readonly questionId: ResumableStateId;
+  readonly resumeStateId: ResumableStateId;
+  readonly sourceItem: ReviewSourceItem;
+  readonly asker: { readonly kind: 'role'; readonly roleId: ReviewRole };
+  readonly question: string;
 }
 
-export interface ReviewOutput {
-  noUnsettledFindings: true;
-  /**
-   * Exact receipt-derived repository revision at which the review scope was
-   * evaluated: the closing clean round's `unchanged` receipt observes it as
-   * HEAD — the last review-fix commit when one landed, or the caller-supplied
-   * scope revision when none did (DR-045).
-   */
-  evaluatedRevision: string;
+// ---------------------------------------------------------------------------
+// Delegated player actor contract
+// ---------------------------------------------------------------------------
+
+interface PlayerInputBase {
+  /** The source item's full final prompt, verbatim. */
+  readonly prompt: string;
+  /** This state's local result contract: guard name → description. */
+  readonly result: Readonly<Record<string, string>>;
+  /** `<caller-input>`: the caller's complete review request. */
+  readonly callerInput?: string;
+  readonly pendingBossQuestion?: PendingBossQuestion;
+  readonly bossReply?: string;
 }
 
-export type ReviewInput = Readonly<Record<string, never>>;
+export interface FirstReviewPlayerInput extends PlayerInputBase {
+  readonly stateId: 'firstReview';
+  readonly role: 'reviewer';
+  readonly sourceItem: 'REVIEW-1';
+}
 
-export interface ReviewContext {
-  callerInput?: string;
-  reviewerOutput?: string;
-  coderOutput?: string;
-  /** Receipt-derived OID of the latest review-fix commit (never player prose). */
-  latestCommit?: string;
-  /** Observed HEAD of the closing clean round's unchanged receipt (DR-045). */
-  evaluatedRevision?: string;
-  lastError?: unknown;
-  pendingBossQuestion?: PendingBossQuestion;
-  bossReply?: string;
+export interface FixFindingsPlayerInput extends PlayerInputBase {
+  readonly stateId: 'fixFindings';
+  readonly role: 'coder';
+  readonly sourceItem: 'REVIEW-2';
+  /** `<reviewer-output>`: Reviewer's verbatim final text of the latest round. */
+  readonly reviewerOutput?: string;
 }
 
-export type ReviewEvent =
-  | { type: 'START_REVIEW'; callerInput: string }
+export interface ReviewAfterFixPlayerInput extends PlayerInputBase {
+  readonly stateId: 'reviewAfterFix';
+  readonly role: 'reviewer';
+  readonly sourceItem: 'REVIEW-3';
+  /** `<latest-commit>`: the receipt-owned latest review-fix commit. */
+  readonly latestCommit?: string;
+  /** `<coder-output>`: Coder's verbatim final text of the latest fix round. */
+  readonly coderOutput?: string;
+}
+
+export interface ReviewAfterRejectionPlayerInput extends PlayerInputBase {
+  readonly stateId: 'reviewAfterRejection';
+  readonly role: 'reviewer';
+  readonly sourceItem: 'REVIEW-4';
+  /** `<coder-output>`: Coder's verbatim final text of the latest fix round. */
+  readonly coderOutput?: string;
+}
+
+export type PlayerInput =
+  | FirstReviewPlayerInput
+  | FixFindingsPlayerInput
+  | ReviewAfterFixPlayerInput
+  | ReviewAfterRejectionPlayerInput;
+
+export type NeedsBossReplyOutput = {
+  readonly guard: 'needsBossReply';
+  readonly question: string;
+};
+
+/** Reviewer outcomes (REVIEW-1, REVIEW-3, REVIEW-4). */
+export type ReviewerOutput =
+  | { readonly guard: 'hasFindings'; readonly reviewerOutput: string }
   | {
-      type: 'BOSS_INTERRUPT';
-      targetId: JumpableStateId;
-      bossIntent: string;
+      readonly guard: 'noFindings';
+      /** Effect-owned: the exact revision taken from repository authority. */
+      readonly evaluatedRevision: string;
     }
+  | NeedsBossReplyOutput;
+
+/** Coder outcomes (REVIEW-2). */
+export type CoderOutput =
   | {
-      type: 'BOSS_REPLY';
-      questionId?: ResumableStateId;
-      answer: string;
-    };
+      readonly guard: 'committed';
+      readonly coderOutput: string;
+      /** Effect-owned: the runtime fills it from the repository receipt. */
+      readonly latestCommit: string;
+    }
+  | { readonly guard: 'rejectedAll'; readonly coderOutput: string }
+  | NeedsBossReplyOutput;
 
-export interface PlayerInput {
-  stateId: ResumableStateId;
-  sourceItem: `REVIEW-${1 | 2 | 3 | 4}`;
-  role: Role;
-  prompt: string;
-  result: Readonly<Record<string, string>>;
-  callerInput?: string;
-  reviewerOutput?: string;
-  coderOutput?: string;
-  latestCommit?: string;
-  pendingBossQuestion?: PendingBossQuestion;
-  bossReply?: string;
+export type PlayerOutput = ReviewerOutput | CoderOutput;
+
+type PlayerGuard = PlayerOutput['guard'];
+
+export interface ErrorRecord {
+  readonly name: string;
+  readonly message: string;
+  readonly stack?: string;
 }
 
-export type PlayerOutput =
-  | { guard: 'hasFindings'; reviewerOutput: string }
-  | { guard: 'noFindings'; evaluatedRevision: string }
-  | { guard: 'committed'; coderOutput: string; latestCommit: string }
-  | { guard: 'rejectedAll'; coderOutput: string }
-  | { guard: 'needsBossReply'; question: string };
+// ---------------------------------------------------------------------------
+// Machine input, context, events, and output
+// ---------------------------------------------------------------------------
 
-type PlayerDoneEvent = { type: string; output: PlayerOutput };
+/** Public output interface of the packaged builtin `review`. */
+export interface ReviewOutput {
+  readonly noUnsettledFindings: true;
+  readonly evaluatedRevision: string;
+}
 
-const NEEDS_BOSS_REPLY_DESCRIPTION =
-  "The acting agent's prose surfaces a clarifying question for Boss that the agent cannot answer alone. Output shall include `question: <verbatim question text from the acting agent's prose>`.";
+/** The machine reads no input: the caller input arrives on `START_REVIEW`. */
+export type ReviewInput = Readonly<Record<never, never>>;
+
+export interface ReviewContext {
+  /** `<caller-input>`: the caller's intent, review scope, and context. */
+  readonly callerInput?: string;
+  /** `<reviewer-output>`: Reviewer's verbatim final text with findings. */
+  readonly reviewerOutput?: string;
+  /** `<coder-output>`: Coder's verbatim final text of the latest fix round. */
+  readonly coderOutput?: string;
+  /** `<latest-commit>`: the accepted, receipt-owned latest review-fix commit. */
+  readonly latestCommit?: string;
+  /** Coder's accepted disposition of the latest findings. */
+  readonly coderOutcome?: CoderOutcome;
+  /** Revision evaluated by the clean review round that ended REVIEW. */
+  readonly evaluatedRevision?: string;
+  readonly lastError?: ErrorRecord;
+  readonly pendingBossQuestion?: PendingBossQuestion;
+  readonly bossReply?: string;
+}
+
+export type ReviewEvent =
+  | { readonly type: 'START_REVIEW'; readonly callerInput: string }
+  | { readonly type: 'BOSS_INTERRUPT'; readonly targetId: JumpableStateId }
+  | {
+      readonly type: 'BOSS_REPLY';
+      readonly answer: string;
+      readonly questionId?: ResumableStateId;
+    };
 
-const SHARED_REVIEW_INSTRUCTION = [
+// ---------------------------------------------------------------------------
+// Prompts and result contracts (verbatim from review.gears.md)
+// ---------------------------------------------------------------------------
+
+const FIRST_REVIEW_PROMPT = [
+  'A new review begins for the review scope.',
+  'Keep to the original intent and follow what it asks.',
+  'When the scope names commits, read each commit message for its context and rationale; otherwise use repository history and commit messages wherever they help establish that context.',
+  '',
   'Understand the full picture and think systematically about the underlying design.',
   'Continue to identify issues or improvements, if any, without duplication.',
   'Number the findings consistently across rounds.',
@@ -106,160 +201,387 @@ const SHARED_REVIEW_INSTRUCTION = [
   '',
   'Consult @specs/map.md for context if needed; verify it remains accurate.',
   'Consult @specs/meta.md for spec requirements if needed; verify affected specs follow it.',
+  '',
+  '> Original request: <caller-input>',
 ].join('\n');
 
-const INITIAL_REVIEW_PROMPT = [
-  'A new review begins for the review scope.',
+const FIX_FINDINGS_PROMPT = [
+  'For each review item, accept or reject it.',
+  'Before deciding, understand the full picture and think systematically about the underlying design.',
   'Keep to the original intent and follow what it asks.',
-  'When the scope names commits, read each commit message for its context and rationale; otherwise use repository history and commit messages wherever they help establish that context.',
+  'Reject anything that is not essential or is not worth fixing now.',
+  'If you accept an item, fix its root cause, including any fundamental design flaw — do not patch around it; if it represents a class of defect, find every instance within the review scope worth fixing rather than addressing one or two per round, which drags out the review.',
+  'If you reject an item, give the reasoning and cite code or test output that supports it.',
+  'Do not re-run tests or builds whose inputs have not changed since any previous reported run.',
   '',
-  '> Original request: <caller-input>',
+  'If you accept any item, make minimal changes and add one new review-fix commit; never rewrite any existing commit.',
+  'Follow @specs/packages/git.md.',
+  'Make the commit message explain concisely what changed and why, including relevant verification.',
+  'Identify every new commit you make.',
+  'Credit every AI that contributed to this commit: Coder <coder-llm> and Reviewer <reviewer-llm>, whose findings it answers.',
+  '',
+  'If you reject every item, change nothing and make no commit.',
+  'Report every disposition, all relevant run results, and every rebuttal.',
   '',
-  SHARED_REVIEW_INSTRUCTION,
+  '> Original request: <caller-input>',
+  '> Reviewer findings: <reviewer-output>',
 ].join('\n');
 
-const POST_COMMIT_REVIEW_PROMPT = [
+const REVIEW_AFTER_FIX_PROMPT = [
   'A new review round begins for the review scope in the cumulative committed state, with particular attention to the latest review-fix commit.',
   'Keep to the original intent and follow what it asks.',
   "Read the latest review-fix commit's message and see Coder's feedback below.",
   '',
+  'Understand the full picture and think systematically about the underlying design.',
+  'Continue to identify issues or improvements, if any, without duplication.',
+  'Number the findings consistently across rounds.',
+  'Flag only what materially affects correctness, behavior, or spec quality — not style, equally valid alternatives, or theoretical threats.',
+  'For specs, flag stale, missing, over-specified, or under-specified ones, if any.',
+  'Avoid unnecessary complexity in code or tests, but flag any fundamental design flaw when leaving it would cost more in later patches than fixing it now.',
+  '',
+  'If an issue represents a class of defect, find every instance within the review scope worth fixing rather than surfacing one or two per round, which drags out the review.',
+  'For any rebuttal, accept or challenge it.',
+  'Treat as settled, and do not raise again, any finding in this review rejected twice with reasoning.',
+  '',
+  'Do not re-run tests or builds whose inputs have not changed since any previous reported run.',
+  'Do not edit files or commit; report findings only.',
+  '',
+  'Consult @specs/map.md for context if needed; verify it remains accurate.',
+  'Consult @specs/meta.md for spec requirements if needed; verify affected specs follow it.',
+  '',
   '> Original request: <caller-input>',
   '> Latest commit: <latest-commit>',
   '> Coder output: <coder-output>',
-  '',
-  SHARED_REVIEW_INSTRUCTION,
 ].join('\n');
 
-const REBUTTAL_REVIEW_PROMPT = [
+const REVIEW_AFTER_REJECTION_PROMPT = [
   'No new commit was made because Coder rejected every finding.',
   "See Coder's feedback below.",
   '',
-  '> Original request: <caller-input>',
-  '> Coder output: <coder-output>',
+  'Understand the full picture and think systematically about the underlying design.',
+  'Continue to identify issues or improvements, if any, without duplication.',
+  'Number the findings consistently across rounds.',
+  'Flag only what materially affects correctness, behavior, or spec quality — not style, equally valid alternatives, or theoretical threats.',
+  'For specs, flag stale, missing, over-specified, or under-specified ones, if any.',
+  'Avoid unnecessary complexity in code or tests, but flag any fundamental design flaw when leaving it would cost more in later patches than fixing it now.',
   '',
-  SHARED_REVIEW_INSTRUCTION,
-].join('\n');
-
-const CODER_DISPOSITION_PROMPT = [
-  '> Original request: <caller-input>',
-  '> Reviewer findings: <reviewer-output>',
+  'If an issue represents a class of defect, find every instance within the review scope worth fixing rather than surfacing one or two per round, which drags out the review.',
+  'For any rebuttal, accept or challenge it.',
+  'Treat as settled, and do not raise again, any finding in this review rejected twice with reasoning.',
   '',
-  'For each review item, accept or reject it.',
-  'Before deciding, understand the full picture and think systematically about the underlying design.',
-  'Keep to the original intent and follow what it asks.',
-  'Reject anything that is not essential or is not worth fixing now.',
-  'If you accept an item, fix its root cause, including any fundamental design flaw — do not patch around it; if it represents a class of defect, find every instance within the review scope worth fixing rather than addressing one or two per round, which drags out the review.',
-  'If you reject an item, give the reasoning and cite code or test output that supports it.',
   'Do not re-run tests or builds whose inputs have not changed since any previous reported run.',
+  'Do not edit files or commit; report findings only.',
   '',
-  'If you accept any item, make minimal changes and add one new review-fix commit; never rewrite any existing commit.',
-  'Follow @specs/packages/git.md.',
-  'Make the commit message explain concisely what changed and why, including relevant verification.',
-  'Identify every new commit you make.',
-  'Credit every AI that contributed to this commit: Coder <coder-llm> and Reviewer <reviewer-llm>, whose findings it answers.',
+  'Consult @specs/map.md for context if needed; verify it remains accurate.',
+  'Consult @specs/meta.md for spec requirements if needed; verify affected specs follow it.',
   '',
-  'If you reject every item, change nothing and make no commit.',
-  'Report every disposition, all relevant run results, and every rebuttal.',
+  '> Original request: <caller-input>',
+  '> Coder output: <coder-output>',
 ].join('\n');
 
-const REVIEW_RESULTS = {
+const NEEDS_BOSS_REPLY_DESCRIPTION =
+  "The acting agent's prose surfaces a clarifying question for Boss that the agent cannot answer alone. Output shall include `question: <verbatim question text from the acting agent's prose>`.";
+
+const FIRST_REVIEW_RESULT = {
   hasFindings:
-    'Reviewer raised one or more unsettled findings. Output shall include `reviewerOutput: <verbatim final text>`.',
+    "Reviewer raised one or more unsettled findings; a progress report, status update, or promise of a later result supports no review outcome, and the outcome does not depend on finding numbering or any fixed presentation format of Reviewer's reply. Output shall include `reviewerOutput: <verbatim final text>`.",
   noFindings:
-    'Reviewer affirmatively reported the requested review complete with no unsettled findings remaining; a progress report, status update, or promise of a later result supports no review outcome. Output shall include `evaluatedRevision: <repository revision>`.',
+    "Reviewer affirmatively reported that the requested review is complete and no unsettled findings remain; a progress report, status update, or promise of a later result supports no review outcome, and the outcome does not depend on finding numbering or any fixed presentation format of Reviewer's reply. On this outcome the workflow returns the exact repository revision at which the review scope was evaluated, taken from repository authority and not from either player's prose, as evaluatedRevision, and the fact that no unsettled findings remain within that scope, as noUnsettledFindings true. Output shall include `evaluatedRevision: <repository revision>`.",
+  needsBossReply: NEEDS_BOSS_REPLY_DESCRIPTION,
+} as const;
+
+const FIX_FINDINGS_RESULT = {
+  committed:
+    "Coder made one new review-fix commit; the outcome does not depend on finding numbering or any fixed presentation format of Coder's reply. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.",
+  rejectedAll:
+    "Coder rejected every finding, changed nothing, and made no commit; the outcome does not depend on finding numbering or any fixed presentation format of Coder's reply. Output shall include `coderOutput: <verbatim final text>`.",
   needsBossReply: NEEDS_BOSS_REPLY_DESCRIPTION,
 } as const;
 
-const REBUTTAL_RESULTS = {
+const LATER_REVIEW_RESULT = {
   hasFindings:
-    'Reviewer kept one or more unsettled findings. Output shall include `reviewerOutput: <verbatim final text>`.',
+    "Reviewer raised or kept one or more unsettled findings; a progress report, status update, or promise of a later result supports no review outcome, and the outcome does not depend on finding numbering or any fixed presentation format of Reviewer's reply. Output shall include `reviewerOutput: <verbatim final text>`.",
   noFindings:
-    'Reviewer accepted the rebuttals and affirmatively reported the requested review complete with no unsettled findings remaining; a progress report, status update, or promise of a later result supports no review outcome. Output shall include `evaluatedRevision: <repository revision>`.',
+    "Reviewer affirmatively reported that the requested review is complete and no unsettled findings remain; a progress report, status update, or promise of a later result supports no review outcome, and the outcome does not depend on finding numbering or any fixed presentation format of Reviewer's reply. On this outcome the workflow returns the exact repository revision at which the review scope was evaluated, taken from repository authority and not from either player's prose, as evaluatedRevision, and the fact that no unsettled findings remain within that scope, as noUnsettledFindings true. Output shall include `evaluatedRevision: <repository revision>`.",
   needsBossReply: NEEDS_BOSS_REPLY_DESCRIPTION,
 } as const;
 
-const CODER_RESULTS = {
-  committed:
-    'Coder accepted at least one item and added one new review-fix commit. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.',
-  rejectedAll:
-    'Coder rejected every item and made no commit. Output shall include `coderOutput: <verbatim final text>`.',
-  needsBossReply: NEEDS_BOSS_REPLY_DESCRIPTION,
+/** REVIEW-3's authored result contract (identical to REVIEW-4's). */
+const REVIEW_AFTER_FIX_RESULT = LATER_REVIEW_RESULT;
+
+/** REVIEW-4's authored result contract (identical to REVIEW-3's). */
+const REVIEW_AFTER_REJECTION_RESULT = LATER_REVIEW_RESULT;
+
+const STATE_DESCRIPTIONS = {
+  ready: 'Waiting for a caller to start a review.',
+  firstReview: 'Reviewer runs the first review round over the review scope.',
+  fixFindings:
+    "Coder accepts or rejects each of Reviewer's findings and commits any accepted fixes.",
+  reviewAfterFix:
+    'Reviewer runs the next review round over the cumulative committed state after a review-fix commit.',
+  reviewAfterRejection:
+    'Reviewer runs the next review round after Coder rejected every finding without a commit.',
+  awaitBossReply: "Waiting for Boss to answer the acting agent's question.",
+  failed:
+    'REVIEW parked after a failure and waits for Boss to restart or resume it.',
+  done: 'REVIEW completed: the review scope was evaluated at the returned revision and no unsettled findings remain.',
+} as const;
+
+type StateKey = keyof typeof STATE_DESCRIPTIONS;
+
+const RESUME_METADATA = {
+  firstReview: { sourceItem: 'REVIEW-1', role: 'reviewer' },
+  fixFindings: { sourceItem: 'REVIEW-2', role: 'coder' },
+  reviewAfterFix: { sourceItem: 'REVIEW-3', role: 'reviewer' },
+  reviewAfterRejection: { sourceItem: 'REVIEW-4', role: 'reviewer' },
+} as const satisfies Record<
+  ResumableStateId,
+  { readonly sourceItem: ReviewSourceItem; readonly role: ReviewRole }
+>;
+
+// ---------------------------------------------------------------------------
+// Structural helpers
+// ---------------------------------------------------------------------------
+
+const isRecord = (
+  value: unknown,
+): value is Readonly<Record<string, unknown>> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const isNonEmptyString = (value: unknown): value is string =>
+  typeof value === 'string' && value.trim().length > 0;
+
+const doneOutputOf = (event: unknown): unknown =>
+  isRecord(event) ? event.output : undefined;
+
+const actorErrorOf = (event: unknown): unknown =>
+  isRecord(event) ? event.error : undefined;
+
+/** Narrows a player done event to the declared player output contract. */
+function playerOutputOf(event: unknown): PlayerOutput | undefined {
+  const output = doneOutputOf(event);
+  if (!isRecord(output)) return undefined;
+  switch (output.guard) {
+    case 'hasFindings':
+      return isNonEmptyString(output.reviewerOutput)
+        ? { guard: 'hasFindings', reviewerOutput: output.reviewerOutput }
+        : undefined;
+    case 'noFindings':
+      return isNonEmptyString(output.evaluatedRevision)
+        ? { guard: 'noFindings', evaluatedRevision: output.evaluatedRevision }
+        : undefined;
+    case 'committed':
+      return isNonEmptyString(output.coderOutput) &&
+        isNonEmptyString(output.latestCommit)
+        ? {
+            guard: 'committed',
+            coderOutput: output.coderOutput,
+            latestCommit: output.latestCommit,
+          }
+        : undefined;
+    case 'rejectedAll':
+      return isNonEmptyString(output.coderOutput)
+        ? { guard: 'rejectedAll', coderOutput: output.coderOutput }
+        : undefined;
+    case 'needsBossReply':
+      return isNonEmptyString(output.question)
+        ? { guard: 'needsBossReply', question: output.question }
+        : undefined;
+    default:
+      return undefined;
+  }
+}
+
+/** Normalizes any thrown or malformed value to a JSON-safe error record. */
+function errorRecord(value: unknown): ErrorRecord {
+  if (value instanceof Error) {
+    return {
+      name: value.name || 'Error',
+      message: value.message,
+      ...(typeof value.stack === 'string' ? { stack: value.stack } : {}),
+    };
+  }
+  if (isRecord(value) && typeof value.message === 'string') {
+    return {
+      name: isNonEmptyString(value.name) ? value.name : 'Error',
+      message: value.message,
+    };
+  }
+  return { name: 'Error', message: String(value) };
+}
+
+// ---------------------------------------------------------------------------
+// Guards
+// ---------------------------------------------------------------------------
+
+type EventArgs = { readonly event: unknown };
+type MachineArgs = {
+  readonly context: ReviewContext;
+  readonly event: ReviewEvent;
+};
+
+const acceptsOutcome =
+  (outcome: PlayerGuard) =>
+  ({ event }: EventArgs): boolean =>
+    playerOutputOf(event)?.guard === outcome;
+
+// The entry guard validates the text the current event supplies, before the
+// entry action copies it into context.
+const validStartReview = ({ event }: MachineArgs): boolean =>
+  event.type === 'START_REVIEW' && isNonEmptyString(event.callerInput);
+
+const repliesToPendingQuestion = ({ context, event }: MachineArgs): boolean =>
+  event.type === 'BOSS_REPLY' &&
+  context.pendingBossQuestion !== undefined &&
+  (event.questionId === undefined ||
+    event.questionId === context.pendingBossQuestion.questionId);
+
+const emptyBossReply = (args: MachineArgs): boolean =>
+  repliesToPendingQuestion(args) &&
+  args.event.type === 'BOSS_REPLY' &&
+  !isNonEmptyString(args.event.answer);
+
+/** Typed context each jumpable working leaf needs to be entered safely. */
+const INTERRUPT_PRECONDITIONS = {
+  firstReview: (context: ReviewContext) => isNonEmptyString(context.callerInput),
+  fixFindings: (context: ReviewContext) =>
+    isNonEmptyString(context.callerInput) &&
+    isNonEmptyString(context.reviewerOutput),
+  reviewAfterFix: (context: ReviewContext) =>
+    isNonEmptyString(context.callerInput) &&
+    context.coderOutcome === 'committed' &&
+    isNonEmptyString(context.latestCommit) &&
+    isNonEmptyString(context.coderOutput),
+  reviewAfterRejection: (context: ReviewContext) =>
+    isNonEmptyString(context.callerInput) &&
+    context.coderOutcome === 'rejectedAll' &&
+    isNonEmptyString(context.coderOutput),
+} as const satisfies Record<
+  JumpableStateId,
+  (context: ReviewContext) => boolean
+>;
+
+// ---------------------------------------------------------------------------
+// Transition helpers
+// ---------------------------------------------------------------------------
+
+/** One guarded root transition per jumpable state. */
+function bossInterrupts<const Ids extends readonly JumpableStateId[]>(
+  ids: Ids,
+) {
+  return ids.map((id) => ({
+    guard: ({ context, event }: MachineArgs) =>
+      event.type === 'BOSS_INTERRUPT' &&
+      event.targetId === id &&
+      INTERRUPT_PRECONDITIONS[id](context),
+    target: `#${id}` as const,
+    reenter: true,
+    actions: 'resetForInterrupt' as const,
+  }));
+}
+
+/** One guarded `BOSS_REPLY` resume transition per suspended working leaf. */
+function resumableStates<const Ids extends readonly ResumableStateId[]>(
+  ids: Ids,
+) {
+  return ids.map((id) => ({
+    guard: (args: MachineArgs) =>
+      repliesToPendingQuestion(args) &&
+      args.event.type === 'BOSS_REPLY' &&
+      isNonEmptyString(args.event.answer) &&
+      args.context.pendingBossQuestion?.resumeStateId === id,
+    target: `#${id}` as const,
+    reenter: true,
+    actions: 'rememberBossReply' as const,
+  }));
+}
+
+const bossReplyFields = (context: ReviewContext) => ({
+  ...(context.pendingBossQuestion !== undefined
+    ? { pendingBossQuestion: context.pendingBossQuestion }
+    : {}),
+  ...(context.bossReply !== undefined ? { bossReply: context.bossReply } : {}),
+});
+
+const acceptedOutcome = (
+  source: WorkingStateId,
+  target: StateKey,
+  outcome: PlayerGuard,
+) =>
+  ({
+    type: 'playbook.acceptedOutcome',
+    params: { source, target, acceptedOutcome: outcome },
+  }) as const;
+
+/** Reviewer found unsettled findings: Coder answers them next (REVIEW-2). */
+const hasFindingsArm = (source: 'firstReview' | 'reviewAfterFix' | 'reviewAfterRejection') =>
+  ({
+    guard: 'acceptHasFindings',
+    target: '#fixFindings',
+    actions: [
+      acceptedOutcome(source, 'fixFindings', 'hasFindings'),
+      'rememberFindings',
+      'clearBossReplyContext',
+    ],
+  }) as const;
+
+/** Reviewer affirmed a complete review with no unsettled findings. */
+const noFindingsArm = (source: 'firstReview' | 'reviewAfterFix' | 'reviewAfterRejection') =>
+  ({
+    guard: 'acceptNoFindings',
+    target: '#done',
+    actions: [
+      acceptedOutcome(source, 'done', 'noFindings'),
+      'rememberEvaluatedRevision',
+      'clearBossReplyContext',
+    ],
+  }) as const;
+
+const suspendArm = (source: WorkingStateId) =>
+  ({
+    guard: 'acceptNeedsBossReply',
+    target: '#awaitBossReply',
+    actions: [
+      acceptedOutcome(source, 'awaitBossReply', 'needsBossReply'),
+      { type: 'setPendingBossQuestion', params: { resumeStateId: source } },
+    ],
+  }) as const;
+
+const malformedPlayerOutputArm = {
+  target: '#failed',
+  actions: ['rememberMalformedPlayerOutput', 'clearBossReplyContext'],
 } as const;
 
-const stateDescriptions = {
-  ready: 'Waits for a caller to start a scoped committed-work review.',
-  reviewInitial:
-    "REVIEW-1: Reviewer reviews the caller's review scope against the original intent.",
-  addressFindings:
-    'REVIEW-2: Coder accepts or rejects every current review finding.',
-  reviewAfterCommit:
-    'REVIEW-3: Reviewer reviews the cumulative committed state after a review-fix commit.',
-  reviewAfterRebuttal:
-    'REVIEW-4: Reviewer adjudicates an all-rejected Coder disposition.',
-  awaitBossReply: 'Waits for Boss to answer the active player question.',
-  failed: 'Retains a recoverable REVIEW failure for the caller.',
-  done: 'The requested review is complete: no unsettled findings remain within the review scope.',
+const playerOnError = {
+  target: '#failed',
+  actions: ['rememberActorError', 'clearBossReplyContext'],
 } as const;
 
-const playbookMeta = <StateId extends keyof typeof stateDescriptions>(
-  stateId: StateId,
-  role?: Role,
-) => ({
+const startReviewArm = {
+  guard: 'validStartReview',
+  target: '#firstReview',
+  actions: 'startReview',
+} as const;
+
+const meta = (stateId: Exclude<StateKey, 'done'>, role?: ReviewRole) => ({
   playbook: {
     stateId,
-    description: stateDescriptions[stateId],
+    description: STATE_DESCRIPTIONS[stateId],
     ...(role === undefined ? {} : { role }),
   },
 });
 
-// DR-048: a final state additionally declares whether its outcome means the
-// workflow succeeded or failed, so a caller learns that from the machine
-// rather than from REVIEW's output fields.
-const terminalMeta = <StateId extends keyof typeof stateDescriptions>(
-  stateId: StateId,
-  terminal: 'success' | 'failure',
-) => ({
+const finalMeta = (stateId: 'done', terminal: 'success' | 'failure') => ({
   playbook: {
     stateId,
-    description: stateDescriptions[stateId],
+    description: STATE_DESCRIPTIONS[stateId],
     terminal,
   },
 });
 
-const outputOf = (event: unknown): PlayerOutput =>
-  (event as PlayerDoneEvent).output;
-
-const isNonEmptyString = (value: unknown): value is string =>
-  typeof value === 'string' && value.trim().length > 0;
-
-const stateMetadata = {
-  reviewInitial: {
-    sourceItem: 'REVIEW-1',
-    asker: { kind: 'role', roleId: 'reviewer' },
-  },
-  addressFindings: {
-    sourceItem: 'REVIEW-2',
-    asker: { kind: 'role', roleId: 'coder' },
-  },
-  reviewAfterCommit: {
-    sourceItem: 'REVIEW-3',
-    asker: { kind: 'role', roleId: 'reviewer' },
-  },
-  reviewAfterRebuttal: {
-    sourceItem: 'REVIEW-4',
-    asker: { kind: 'role', roleId: 'reviewer' },
-  },
-} as const satisfies Record<
-  ResumableStateId,
-  {
-    sourceItem: `REVIEW-${1 | 2 | 3 | 4}`;
-    asker: { readonly kind: 'role'; readonly roleId: Role };
-  }
->;
-
-const playerPlaceholder = fromPromise<PlayerOutput, PlayerInput>(async () => {
-  throw new Error('player actor must be provided by the runner');
-});
+// ---------------------------------------------------------------------------
+// Machine
+// ---------------------------------------------------------------------------
 
 export const reviewMachine = setup({
   types: {
@@ -269,74 +591,9 @@ export const reviewMachine = setup({
     output: {} as ReviewOutput,
   },
   actors: {
-    player: playerPlaceholder,
-  },
-  guards: {
-    hasFindings: ({ event }) => {
-      const output = outputOf(event);
-      return (
-        output.guard === 'hasFindings' &&
-        isNonEmptyString(output.reviewerOutput)
-      );
-    },
-    noFindings: ({ event }) => {
-      const output = outputOf(event);
-      return (
-        output.guard === 'noFindings' &&
-        isNonEmptyString(output.evaluatedRevision)
-      );
-    },
-    committed: ({ event }) => {
-      const output = outputOf(event);
-      return (
-        output.guard === 'committed' &&
-        isNonEmptyString(output.coderOutput) &&
-        isNonEmptyString(output.latestCommit)
-      );
-    },
-    rejectedAll: ({ event }) => {
-      const output = outputOf(event);
-      return (
-        output.guard === 'rejectedAll' && isNonEmptyString(output.coderOutput)
-      );
-    },
-    needsBossReply: ({ event }) => {
-      const output = outputOf(event);
-      return (
-        output.guard === 'needsBossReply' && isNonEmptyString(output.question)
-      );
-    },
-    emptyBossReply: ({ event }) =>
-      event.type === 'BOSS_REPLY' && event.answer.trim().length === 0,
-    resumeReviewInitial: ({ context, event }) =>
-      event.type === 'BOSS_REPLY' &&
-      event.answer.trim().length > 0 &&
-      context.pendingBossQuestion?.resumeStateId === 'reviewInitial' &&
-      (event.questionId === undefined ||
-        event.questionId === context.pendingBossQuestion.questionId),
-    resumeAddressFindings: ({ context, event }) =>
-      event.type === 'BOSS_REPLY' &&
-      event.answer.trim().length > 0 &&
-      context.pendingBossQuestion?.resumeStateId === 'addressFindings' &&
-      (event.questionId === undefined ||
-        event.questionId === context.pendingBossQuestion.questionId),
-    resumeReviewAfterCommit: ({ context, event }) =>
-      event.type === 'BOSS_REPLY' &&
-      event.answer.trim().length > 0 &&
-      context.pendingBossQuestion?.resumeStateId === 'reviewAfterCommit' &&
-      (event.questionId === undefined ||
-        event.questionId === context.pendingBossQuestion.questionId),
-    resumeReviewAfterRebuttal: ({ context, event }) =>
-      event.type === 'BOSS_REPLY' &&
-      event.answer.trim().length > 0 &&
-      context.pendingBossQuestion?.resumeStateId === 'reviewAfterRebuttal' &&
-      (event.questionId === undefined ||
-        event.questionId === context.pendingBossQuestion.questionId),
-    restartInitialReview: ({ event }) =>
-      event.type === 'BOSS_INTERRUPT' &&
-      event.targetId === 'reviewInitial' &&
-      typeof event.bossIntent === 'string' &&
-      event.bossIntent.trim().length > 0,
+    player: fromPromise<PlayerOutput, PlayerInput>(async () => {
+      throw new Error('player actor must be provided by the runner');
+    }),
   },
   actions: {
     'playbook.acceptedOutcome': (
@@ -347,518 +604,316 @@ export const reviewMachine = setup({
         readonly acceptedOutcome: string;
       },
     ) => undefined,
-    copyStartInput: assign({
-      callerInput: ({ event }) =>
-        event.type === 'START_REVIEW' ? event.callerInput : undefined,
-      reviewerOutput: undefined,
-      coderOutput: undefined,
-      latestCommit: undefined,
+    startReview: assign(({ event }) =>
+      event.type === 'START_REVIEW'
+        ? {
+            callerInput: event.callerInput,
+            reviewerOutput: undefined,
+            coderOutput: undefined,
+            latestCommit: undefined,
+            coderOutcome: undefined,
+            evaluatedRevision: undefined,
+            lastError: undefined,
+            pendingBossQuestion: undefined,
+            bossReply: undefined,
+          }
+        : {},
+    ),
+    resetForInterrupt: assign({
       evaluatedRevision: undefined,
       lastError: undefined,
       pendingBossQuestion: undefined,
       bossReply: undefined,
     }),
-    copyInterruptedInput: assign({
-      callerInput: ({ event }) =>
-        event.type === 'BOSS_INTERRUPT' ? event.bossIntent : undefined,
-      reviewerOutput: undefined,
-      coderOutput: undefined,
-      latestCommit: undefined,
-      evaluatedRevision: undefined,
-      lastError: undefined,
-      pendingBossQuestion: undefined,
-      bossReply: undefined,
+    rememberFindings: assign(({ event }) => {
+      const output = playerOutputOf(event);
+      return output?.guard === 'hasFindings'
+        ? { reviewerOutput: output.reviewerOutput, lastError: undefined }
+        : {};
     }),
-    rememberReviewerOutput: assign({
-      reviewerOutput: ({ event }) => {
-        const output = outputOf(event);
-        return output.guard === 'hasFindings'
-          ? output.reviewerOutput
-          : undefined;
-      },
-      lastError: undefined,
-      pendingBossQuestion: undefined,
-      bossReply: undefined,
-    }),
-    rememberCoderOutput: assign({
-      coderOutput: ({ event }) => {
-        const output = outputOf(event);
-        return output.guard === 'committed' || output.guard === 'rejectedAll'
-          ? output.coderOutput
-          : undefined;
-      },
-      // The receipt-derived review-fix commit identity replaces the prior one
-      // only when Coder committed; an all-rejected round leaves the evaluated
-      // revision unchanged.
-      latestCommit: ({ context, event }) => {
-        const output = outputOf(event);
-        return output.guard === 'committed'
-          ? output.latestCommit
-          : context.latestCommit;
-      },
-      lastError: undefined,
-      pendingBossQuestion: undefined,
-      bossReply: undefined,
-    }),
-    rememberEvaluatedRevision: assign({
-      // DR-045: the closing clean round's unchanged receipt observes the
-      // exact revision the review scope was evaluated at.
-      evaluatedRevision: ({ context, event }) => {
-        const output = outputOf(event);
-        return output.guard === 'noFindings'
-          ? output.evaluatedRevision
-          : context.evaluatedRevision;
-      },
-      lastError: undefined,
-      pendingBossQuestion: undefined,
-      bossReply: undefined,
-    }),
-    rememberBossReply: assign({
-      bossReply: ({ event }) =>
-        event.type === 'BOSS_REPLY' ? event.answer : undefined,
-    }),
-    rememberActorError: assign({
-      lastError: ({ event }) =>
-        (event as { error?: unknown }).error ??
-        new Error('REVIEW player invocation failed'),
-    }),
-    rememberEmptyBossReplyError: assign({
-      lastError: () => new Error('BOSS_REPLY received an empty answer'),
-      pendingBossQuestion: undefined,
-      bossReply: undefined,
-    }),
-    setPendingReviewInitial: assign({
-      pendingBossQuestion: ({ event }) => {
-        const output = outputOf(event);
+    rememberCoderDisposition: assign(({ event }) => {
+      const output = playerOutputOf(event);
+      if (output?.guard === 'committed') {
         return {
-          questionId: 'reviewInitial',
-          resumeStateId: 'reviewInitial',
-          ...stateMetadata.reviewInitial,
-          question: output.guard === 'needsBossReply' ? output.question : '',
+          coderOutput: output.coderOutput,
+          latestCommit: output.latestCommit,
+          coderOutcome: 'committed' as const,
+          lastError: undefined,
         };
-      },
-      bossReply: undefined,
-    }),
-    setPendingAddressFindings: assign({
-      pendingBossQuestion: ({ event }) => {
-        const output = outputOf(event);
+      }
+      if (output?.guard === 'rejectedAll') {
         return {
-          questionId: 'addressFindings',
-          resumeStateId: 'addressFindings',
-          ...stateMetadata.addressFindings,
-          question: output.guard === 'needsBossReply' ? output.question : '',
+          coderOutput: output.coderOutput,
+          coderOutcome: 'rejectedAll' as const,
+          lastError: undefined,
         };
-      },
-      bossReply: undefined,
+      }
+      return {};
     }),
-    setPendingReviewAfterCommit: assign({
-      pendingBossQuestion: ({ event }) => {
-        const output = outputOf(event);
-        return {
-          questionId: 'reviewAfterCommit',
-          resumeStateId: 'reviewAfterCommit',
-          ...stateMetadata.reviewAfterCommit,
-          question: output.guard === 'needsBossReply' ? output.question : '',
+    rememberEvaluatedRevision: assign(({ event }) => {
+      const output = playerOutputOf(event);
+      return output?.guard === 'noFindings'
+        ? { evaluatedRevision: output.evaluatedRevision, lastError: undefined }
+        : {};
+    }),
+    setPendingBossQuestion: assign(
+      ({ event }, params: { readonly resumeStateId: ResumableStateId }) => {
+        const output = playerOutputOf(event);
+        if (output?.guard !== 'needsBossReply') return {};
+        const metadata = RESUME_METADATA[params.resumeStateId];
+        const pendingBossQuestion: PendingBossQuestion = {
+          questionId: params.resumeStateId,
+          resumeStateId: params.resumeStateId,
+          sourceItem: metadata.sourceItem,
+          asker: { kind: 'role', roleId: metadata.role },
+          question: output.question,
         };
+        return { pendingBossQuestion, bossReply: undefined, lastError: undefined };
       },
+    ),
+    rememberBossReply: assign(({ event }) =>
+      event.type === 'BOSS_REPLY' ? { bossReply: event.answer } : {},
+    ),
+    clearBossReplyContext: assign({
+      pendingBossQuestion: undefined,
       bossReply: undefined,
     }),
-    setPendingReviewAfterRebuttal: assign({
-      pendingBossQuestion: ({ event }) => {
-        const output = outputOf(event);
-        return {
-          questionId: 'reviewAfterRebuttal',
-          resumeStateId: 'reviewAfterRebuttal',
-          ...stateMetadata.reviewAfterRebuttal,
-          question: output.guard === 'needsBossReply' ? output.question : '',
-        };
+    rememberActorError: assign(({ event }) => ({
+      lastError: errorRecord(actorErrorOf(event)),
+    })),
+    rememberMalformedPlayerOutput: assign(({ event }) => {
+      const output = doneOutputOf(event);
+      return {
+        lastError: {
+          name: 'MalformedPlayerOutput',
+          message:
+            isRecord(output) && output.guard === 'needsBossReply'
+              ? 'Player output declared needsBossReply without a question.'
+              : 'Player output did not match an outcome declared for the working state.',
+        },
+      };
+    }),
+    rememberMalformedBossReply: assign({
+      lastError: {
+        name: 'MalformedBossReply',
+        message: 'BOSS_REPLY carried an empty answer.',
       },
-      bossReply: undefined,
     }),
   },
+  guards: {
+    acceptHasFindings: acceptsOutcome('hasFindings'),
+    acceptNoFindings: acceptsOutcome('noFindings'),
+    acceptCommitted: acceptsOutcome('committed'),
+    acceptRejectedAll: acceptsOutcome('rejectedAll'),
+    acceptNeedsBossReply: acceptsOutcome('needsBossReply'),
+    validStartReview,
+    emptyBossReply,
+  },
 }).createMachine({
   id: 'review',
-  context: {},
   initial: 'ready',
+  context: {},
+  output: ({ context }): ReviewOutput => {
+    if (!isNonEmptyString(context.evaluatedRevision)) {
+      throw new Error('REVIEW completed without the evaluated repository revision');
+    }
+    return {
+      noUnsettledFindings: true,
+      evaluatedRevision: context.evaluatedRevision,
+    };
+  },
   on: {
-    BOSS_INTERRUPT: {
-      guard: 'restartInitialReview',
-      target: '#reviewInitial',
-      reenter: true,
-      actions: 'copyInterruptedInput',
-    },
+    BOSS_INTERRUPT: bossInterrupts([
+      'firstReview',
+      'fixFindings',
+      'reviewAfterFix',
+      'reviewAfterRejection',
+    ] as const),
   },
   states: {
     ready: {
       id: 'ready',
-      description: stateDescriptions.ready,
-      meta: playbookMeta('ready'),
-      tags: ['playbook.parked'],
+      tags: 'playbook.parked',
+      description: STATE_DESCRIPTIONS.ready,
+      meta: meta('ready'),
       on: {
-        START_REVIEW: {
-          guard: ({ event }) => event.callerInput.trim().length > 0,
-          target: '#reviewInitial',
-          actions: 'copyStartInput',
-        },
+        START_REVIEW: startReviewArm,
       },
     },
-    reviewInitial: {
-      id: 'reviewInitial',
-      description: stateDescriptions.reviewInitial,
-      meta: playbookMeta('reviewInitial', 'reviewer'),
-      tags: ['playbook.busy'],
+    firstReview: {
+      id: 'firstReview',
+      tags: 'playbook.busy',
+      description: STATE_DESCRIPTIONS.firstReview,
+      meta: meta('firstReview', 'reviewer'),
       invoke: {
         src: 'player',
-        input: ({ context }): PlayerInput => ({
-          stateId: 'reviewInitial',
-          sourceItem: 'REVIEW-1',
+        input: ({ context }): FirstReviewPlayerInput => ({
+          stateId: 'firstReview',
           role: 'reviewer',
-          prompt: INITIAL_REVIEW_PROMPT,
-          result: REVIEW_RESULTS,
-          callerInput: context.callerInput,
-          pendingBossQuestion: context.pendingBossQuestion,
-          bossReply: context.bossReply,
+          sourceItem: 'REVIEW-1',
+          prompt: FIRST_REVIEW_PROMPT,
+          result: FIRST_REVIEW_RESULT,
+          ...(context.callerInput !== undefined
+            ? { callerInput: context.callerInput }
+            : {}),
+          ...bossReplyFields(context),
         }),
         onDone: [
-          {
-            guard: 'hasFindings',
-            target: '#addressFindings',
-            actions: [
-              {
-                type: 'playbook.acceptedOutcome',
-                params: {
-                  source: 'reviewInitial',
-                  target: 'addressFindings',
-                  acceptedOutcome: 'hasFindings',
-                },
-              },
-              'rememberReviewerOutput',
-            ],
-          },
-          {
-            guard: 'noFindings',
-            target: '#done',
-            actions: [
-              {
-                type: 'playbook.acceptedOutcome',
-                params: {
-                  source: 'reviewInitial',
-                  target: 'done',
-                  acceptedOutcome: 'noFindings',
-                },
-              },
-              'rememberEvaluatedRevision',
-            ],
-          },
-          {
-            guard: 'needsBossReply',
-            target: '#awaitBossReply',
-            actions: [
-              {
-                type: 'playbook.acceptedOutcome',
-                params: {
-                  source: 'reviewInitial',
-                  target: 'awaitBossReply',
-                  acceptedOutcome: 'needsBossReply',
-                },
-              },
-              'setPendingReviewInitial',
-            ],
-          },
+          hasFindingsArm('firstReview'),
+          noFindingsArm('firstReview'),
+          suspendArm('firstReview'),
+          malformedPlayerOutputArm,
         ],
-        onError: {
-          target: '#failed',
-          actions: 'rememberActorError',
-        },
+        onError: playerOnError,
       },
     },
-    addressFindings: {
-      id: 'addressFindings',
-      description: stateDescriptions.addressFindings,
-      meta: playbookMeta('addressFindings', 'coder'),
-      tags: ['playbook.busy'],
+    fixFindings: {
+      id: 'fixFindings',
+      tags: 'playbook.busy',
+      description: STATE_DESCRIPTIONS.fixFindings,
+      meta: meta('fixFindings', 'coder'),
       invoke: {
         src: 'player',
-        input: ({ context }): PlayerInput => ({
-          stateId: 'addressFindings',
-          sourceItem: 'REVIEW-2',
+        input: ({ context }): FixFindingsPlayerInput => ({
+          stateId: 'fixFindings',
           role: 'coder',
-          prompt: CODER_DISPOSITION_PROMPT,
-          result: CODER_RESULTS,
-          callerInput: context.callerInput,
-          reviewerOutput: context.reviewerOutput,
-          pendingBossQuestion: context.pendingBossQuestion,
-          bossReply: context.bossReply,
+          sourceItem: 'REVIEW-2',
+          prompt: FIX_FINDINGS_PROMPT,
+          result: FIX_FINDINGS_RESULT,
+          ...(context.callerInput !== undefined
+            ? { callerInput: context.callerInput }
+            : {}),
+          ...(context.reviewerOutput !== undefined
+            ? { reviewerOutput: context.reviewerOutput }
+            : {}),
+          ...bossReplyFields(context),
         }),
         onDone: [
           {
-            guard: 'committed',
-            target: '#reviewAfterCommit',
-            actions: [
-              {
-                type: 'playbook.acceptedOutcome',
-                params: {
-                  source: 'addressFindings',
-                  target: 'reviewAfterCommit',
-                  acceptedOutcome: 'committed',
-                },
-              },
-              'rememberCoderOutput',
-            ],
-          },
-          {
-            guard: 'rejectedAll',
-            target: '#reviewAfterRebuttal',
+            guard: 'acceptCommitted',
+            target: '#reviewAfterFix',
             actions: [
-              {
-                type: 'playbook.acceptedOutcome',
-                params: {
-                  source: 'addressFindings',
-                  target: 'reviewAfterRebuttal',
-                  acceptedOutcome: 'rejectedAll',
-                },
-              },
-              'rememberCoderOutput',
+              acceptedOutcome('fixFindings', 'reviewAfterFix', 'committed'),
+              'rememberCoderDisposition',
+              'clearBossReplyContext',
             ],
           },
           {
-            guard: 'needsBossReply',
-            target: '#awaitBossReply',
+            guard: 'acceptRejectedAll',
+            target: '#reviewAfterRejection',
             actions: [
-              {
-                type: 'playbook.acceptedOutcome',
-                params: {
-                  source: 'addressFindings',
-                  target: 'awaitBossReply',
-                  acceptedOutcome: 'needsBossReply',
-                },
-              },
-              'setPendingAddressFindings',
+              acceptedOutcome('fixFindings', 'reviewAfterRejection', 'rejectedAll'),
+              'rememberCoderDisposition',
+              'clearBossReplyContext',
             ],
           },
+          suspendArm('fixFindings'),
+          malformedPlayerOutputArm,
         ],
-        onError: {
-          target: '#failed',
-          actions: 'rememberActorError',
-        },
+        onError: playerOnError,
       },
     },
-    reviewAfterCommit: {
-      id: 'reviewAfterCommit',
-      description: stateDescriptions.reviewAfterCommit,
-      meta: playbookMeta('reviewAfterCommit', 'reviewer'),
-      tags: ['playbook.busy'],
+    reviewAfterFix: {
+      id: 'reviewAfterFix',
+      tags: 'playbook.busy',
+      description: STATE_DESCRIPTIONS.reviewAfterFix,
+      meta: meta('reviewAfterFix', 'reviewer'),
       invoke: {
         src: 'player',
-        input: ({ context }): PlayerInput => ({
-          stateId: 'reviewAfterCommit',
-          sourceItem: 'REVIEW-3',
+        input: ({ context }): ReviewAfterFixPlayerInput => ({
+          stateId: 'reviewAfterFix',
           role: 'reviewer',
-          prompt: POST_COMMIT_REVIEW_PROMPT,
-          result: REVIEW_RESULTS,
-          callerInput: context.callerInput,
-          latestCommit: context.latestCommit,
-          coderOutput: context.coderOutput,
-          pendingBossQuestion: context.pendingBossQuestion,
-          bossReply: context.bossReply,
+          sourceItem: 'REVIEW-3',
+          prompt: REVIEW_AFTER_FIX_PROMPT,
+          result: REVIEW_AFTER_FIX_RESULT,
+          ...(context.callerInput !== undefined
+            ? { callerInput: context.callerInput }
+            : {}),
+          ...(context.latestCommit !== undefined
+            ? { latestCommit: context.latestCommit }
+            : {}),
+          ...(context.coderOutput !== undefined
+            ? { coderOutput: context.coderOutput }
+            : {}),
+          ...bossReplyFields(context),
         }),
         onDone: [
-          {
-            guard: 'hasFindings',
-            target: '#addressFindings',
-            actions: [
-              {
-                type: 'playbook.acceptedOutcome',
-                params: {
-                  source: 'reviewAfterCommit',
-                  target: 'addressFindings',
-                  acceptedOutcome: 'hasFindings',
-                },
-              },
-              'rememberReviewerOutput',
-            ],
-          },
-          {
-            guard: 'noFindings',
-            target: '#done',
-            actions: [
-              {
-                type: 'playbook.acceptedOutcome',
-                params: {
-                  source: 'reviewAfterCommit',
-                  target: 'done',
-                  acceptedOutcome: 'noFindings',
-                },
-              },
-              'rememberEvaluatedRevision',
-            ],
-          },
-          {
-            guard: 'needsBossReply',
-            target: '#awaitBossReply',
-            actions: [
-              {
-                type: 'playbook.acceptedOutcome',
-                params: {
-                  source: 'reviewAfterCommit',
-                  target: 'awaitBossReply',
-                  acceptedOutcome: 'needsBossReply',
-                },
-              },
-              'setPendingReviewAfterCommit',
-            ],
-          },
+          hasFindingsArm('reviewAfterFix'),
+          noFindingsArm('reviewAfterFix'),
+          suspendArm('reviewAfterFix'),
+          malformedPlayerOutputArm,
         ],
-        onError: {
-          target: '#failed',
-          actions: 'rememberActorError',
-        },
+        onError: playerOnError,
       },
     },
-    reviewAfterRebuttal: {
-      id: 'reviewAfterRebuttal',
-      description: stateDescriptions.reviewAfterRebuttal,
-      meta: playbookMeta('reviewAfterRebuttal', 'reviewer'),
-      tags: ['playbook.busy'],
+    reviewAfterRejection: {
+      id: 'reviewAfterRejection',
+      tags: 'playbook.busy',
+      description: STATE_DESCRIPTIONS.reviewAfterRejection,
+      meta: meta('reviewAfterRejection', 'reviewer'),
       invoke: {
         src: 'player',
-        input: ({ context }): PlayerInput => ({
-          stateId: 'reviewAfterRebuttal',
-          sourceItem: 'REVIEW-4',
+        input: ({ context }): ReviewAfterRejectionPlayerInput => ({
+          stateId: 'reviewAfterRejection',
           role: 'reviewer',
-          prompt: REBUTTAL_REVIEW_PROMPT,
-          result: REBUTTAL_RESULTS,
-          callerInput: context.callerInput,
-          coderOutput: context.coderOutput,
-          pendingBossQuestion: context.pendingBossQuestion,
-          bossReply: context.bossReply,
+          sourceItem: 'REVIEW-4',
+          prompt: REVIEW_AFTER_REJECTION_PROMPT,
+          result: REVIEW_AFTER_REJECTION_RESULT,
+          ...(context.callerInput !== undefined
+            ? { callerInput: context.callerInput }
+            : {}),
+          ...(context.coderOutput !== undefined
+            ? { coderOutput: context.coderOutput }
+            : {}),
+          ...bossReplyFields(context),
         }),
         onDone: [
-          {
-            guard: 'hasFindings',
-            target: '#addressFindings',
-            actions: [
-              {
-                type: 'playbook.acceptedOutcome',
-                params: {
-                  source: 'reviewAfterRebuttal',
-                  target: 'addressFindings',
-                  acceptedOutcome: 'hasFindings',
-                },
-              },
-              'rememberReviewerOutput',
-            ],
-          },
-          {
-            guard: 'noFindings',
-            target: '#done',
-            actions: [
-              {
-                type: 'playbook.acceptedOutcome',
-                params: {
-                  source: 'reviewAfterRebuttal',
-                  target: 'done',
-                  acceptedOutcome: 'noFindings',
-                },
-              },
-              'rememberEvaluatedRevision',
-            ],
-          },
-          {
-            guard: 'needsBossReply',
-            target: '#awaitBossReply',
-            actions: [
-              {
-                type: 'playbook.acceptedOutcome',
-                params: {
-                  source: 'reviewAfterRebuttal',
-                  target: 'awaitBossReply',
-                  acceptedOutcome: 'needsBossReply',
-                },
-              },
-              'setPendingReviewAfterRebuttal',
-            ],
-          },
+          hasFindingsArm('reviewAfterRejection'),
+          noFindingsArm('reviewAfterRejection'),
+          suspendArm('reviewAfterRejection'),
+          malformedPlayerOutputArm,
         ],
-        onError: {
-          target: '#failed',
-          actions: 'rememberActorError',
-        },
+        onError: playerOnError,
       },
     },
     awaitBossReply: {
       id: 'awaitBossReply',
-      description: stateDescriptions.awaitBossReply,
-      meta: playbookMeta('awaitBossReply'),
-      tags: ['playbook.parked'],
+      tags: 'playbook.parked',
+      description: STATE_DESCRIPTIONS.awaitBossReply,
+      meta: meta('awaitBossReply'),
       on: {
-        START_REVIEW: {
-          guard: ({ event }) => event.callerInput.trim().length > 0,
-          target: '#reviewInitial',
-          actions: 'copyStartInput',
-        },
         BOSS_REPLY: [
           {
             guard: 'emptyBossReply',
-            target: '#failed',
-            actions: 'rememberEmptyBossReplyError',
-          },
-          {
-            guard: 'resumeReviewInitial',
-            target: '#reviewInitial',
-            reenter: true,
-            actions: 'rememberBossReply',
-          },
-          {
-            guard: 'resumeAddressFindings',
-            target: '#addressFindings',
-            reenter: true,
-            actions: 'rememberBossReply',
-          },
-          {
-            guard: 'resumeReviewAfterCommit',
-            target: '#reviewAfterCommit',
-            reenter: true,
-            actions: 'rememberBossReply',
-          },
-          {
-            guard: 'resumeReviewAfterRebuttal',
-            target: '#reviewAfterRebuttal',
-            reenter: true,
-            actions: 'rememberBossReply',
+            target: 'failed',
+            actions: ['rememberMalformedBossReply', 'clearBossReplyContext'],
           },
+          ...resumableStates([
+            'firstReview',
+            'fixFindings',
+            'reviewAfterFix',
+            'reviewAfterRejection',
+          ] as const),
         ],
+        START_REVIEW: startReviewArm,
       },
     },
     failed: {
       id: 'failed',
-      description: stateDescriptions.failed,
-      meta: playbookMeta('failed'),
-      tags: ['playbook.parked'],
+      tags: 'playbook.parked',
+      description: STATE_DESCRIPTIONS.failed,
+      meta: meta('failed'),
       on: {
-        START_REVIEW: {
-          guard: ({ event }) => event.callerInput.trim().length > 0,
-          target: '#reviewInitial',
-          actions: 'copyStartInput',
-        },
+        START_REVIEW: startReviewArm,
       },
     },
     done: {
       id: 'done',
-      description: stateDescriptions.done,
-      meta: terminalMeta('done', 'success'),
       type: 'final',
+      description: STATE_DESCRIPTIONS.done,
+      meta: finalMeta('done', 'success'),
     },
   },
-  output: ({ context }): ReviewOutput => {
-    if (!isNonEmptyString(context.evaluatedRevision)) {
-      throw new Error(
-        'REVIEW reached done without a receipt-observed evaluated revision',
-      );
-    }
-    return {
-      noUnsettledFindings: true,
-      evaluatedRevision: context.evaluatedRevision,
-    };
-  },
 });
+
+export default reviewMachine;