@sublang/playbook 15.0.0 → 16.0.0

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

@@ -1,11 +1,17 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
-
-// FSM object artifact compiled from decide.gears.md.
-// This module defines only the machine, actor contracts, and typed inputs.
-// The linked runtime supplies the player and nested-playbook actors.
+//
+// FSM object artifact compiled from ./decide.gears.md by gears2fsm.
+// It declares only the machine, its actor contracts, and typed inputs; the
+// linked runtime supplies the `player` and `playbook` actor implementations.
 
 import { assign, fromPromise, setup } from 'xstate';
+import { validatePlaybookCallResult } from '@sublang/playbook/xstate-runtime';
+import type { PlaybookCallResult } from '@sublang/playbook/runtime';
+
+// ---------------------------------------------------------------------------
+// Shared JSON and error shapes (exact readonly variance of the shared boundary)
+// ---------------------------------------------------------------------------
 
 export type JsonValue =
   | null
@@ -15,148 +21,116 @@ export type JsonValue =
   | readonly JsonValue[]
   | { readonly [key: string]: JsonValue };
 
-type Role = 'coder' | 'reviewer';
-
-export const concurrentRoleSets = [['coder', 'reviewer']] as const;
-
-type JumpableStateId = 'independentProposals';
-
-type ResumableStateId =
-  | 'askCoderProposal'
-  | 'askReviewerProposal'
-  | 'commitCoderProposal';
-
-export interface PendingBossQuestion {
-  questionId: ResumableStateId;
-  resumeStateId: ResumableStateId;
-  sourceItem: string;
-  asker: { kind: 'role'; roleId: Role };
-  question: string;
+export interface CompactError {
+  readonly name: string;
+  readonly message: string;
 }
 
-type PendingBossQuestions = Partial<
-  Record<ResumableStateId, PendingBossQuestion>
->;
-
-type BossReplies = Partial<Record<ResumableStateId, string>>;
-
-type PendingBossQuestionParams = Omit<PendingBossQuestion, 'questionId'>;
-
-export interface ReviewSuccessOutput {
-  evaluatedRevision: string;
-  noUnsettledFindings: true;
+export interface ErrorRecord {
+  readonly name: string;
+  readonly message: string;
+  readonly stack?: string;
 }
 
-export interface DecideSuccessOutput {
-  decideCommit: string;
-  evaluatedRevision: string;
-  noUnsettledFindings: true;
-}
+// ---------------------------------------------------------------------------
+// Identities
+// ---------------------------------------------------------------------------
 
-export interface DecideFailureOutput {
-  lastDecideCommit: string;
-  noUnsettledFindings: false;
-  reviewStatus: 'aborted' | 'error';
-  error?: {
-    name: string;
-    message: string;
-  };
-}
+/** Canonical lowercase local ids of the source roles Coder and Reviewer. */
+export type DecideRoleId = 'coder' | 'reviewer';
 
-export type DecideOutput = DecideSuccessOutput | DecideFailureOutput;
+export type DecideSourceItem = 'DECIDE-1' | 'DECIDE-2' | 'DECIDE-3' | 'DECIDE-4';
 
-interface ChildFailure {
-  status: 'aborted' | 'error';
-  playbookId: 'review';
-  error?: {
-    name: string;
-    message: string;
-  };
-}
+/** Delegated-player working leaves; each is its own Boss-reply resume target. */
+export type ResumableStateId =
+  | 'askCoderProposal'
+  | 'askReviewerProposal'
+  | 'synthesizeCommit';
 
-export interface DecideContext {
-  callerTopic?: string;
-  coderProposal?: string;
-  reviewerProposal?: string;
-  latestCommit?: string;
-  coderOutput?: string;
-  reviewResult?: ReviewSuccessOutput;
-  reviewFailure?: ChildFailure;
-  lastResult?: PlayerOutput;
-  lastError?: unknown;
-  pendingBossQuestions?: PendingBossQuestions;
-  bossReplies?: BossReplies;
-  stagedCoderResult?: PlayerOutput;
-  stagedReviewerResult?: PlayerOutput;
-}
+/**
+ * Root `BOSS_INTERRUPT` targets: the parallel proposal pair as one jumpable
+ * unit (DECIDE-1, DECIDE-2), and the synthesis leaf (DECIDE-3). Branch working
+ * leaves and waits are never interrupt targets.
+ */
+export type JumpableStateId = 'independentProposals' | 'synthesizeCommit';
 
-export type DecideEvent =
-  | { type: 'START_DECIDE'; callerTopic: string }
-  | {
-      type: 'BOSS_INTERRUPT';
-      targetId: JumpableStateId;
-      bossIntent: string;
-    }
-  | {
-      type: 'BOSS_REPLY';
-      questionId?: ResumableStateId;
-      answer: string;
-    };
+/**
+ * One role-id array per parallel group, in first-item source order; the inner
+ * array follows the `independent-proposals` item order (DECIDE-1, DECIDE-2).
+ */
+export const concurrentRoleSets: readonly (readonly DecideRoleId[])[] = [
+  ['coder', 'reviewer'],
+] as const;
 
-export type DecideInput = Readonly<Record<string, never>>;
+/** The literal nested-call target of DECIDE-4. */
+const REVIEW_PLAYBOOK_ID = 'review' as const;
+
+// ---------------------------------------------------------------------------
+// Boss-reply suspension (keyed form: the machine has parallel player tasks)
+// ---------------------------------------------------------------------------
 
-export interface PlayerInput {
-  stateId: ResumableStateId;
-  sourceItem: string;
-  prompt: string;
-  result: Record<string, string>;
-  role: Role;
-  callerTopic?: string;
-  reviewerProposal?: string;
-  pendingBossQuestion?: PendingBossQuestion;
-  bossReply?: string;
+export interface PendingBossQuestion {
+  readonly questionId: ResumableStateId;
+  readonly resumeStateId: ResumableStateId;
+  readonly sourceItem: 'DECIDE-1' | 'DECIDE-2' | 'DECIDE-3';
+  readonly asker: { readonly kind: 'role'; readonly roleId: DecideRoleId };
+  readonly question: string;
 }
 
-type AdditionalPlayerFields = {
-  coderProposal?: string;
-  reviewerProposal?: string;
-  coderOutput?: string;
-  latestCommit?: string;
-  question?: string;
-  readonly [key: string]: unknown;
-};
+export type PendingBossQuestions = Partial<
+  Record<ResumableStateId, PendingBossQuestion>
+>;
 
-export type PlayerOutput =
-  | ({ guard: 'proposed'; coderProposal: string } & AdditionalPlayerFields)
-  | ({ guard: 'proposed'; reviewerProposal: string } & AdditionalPlayerFields)
-  | ({ guard: 'committed'; coderOutput: string; latestCommit: string } &
-      AdditionalPlayerFields)
-  | ({ guard: 'needsBossReply'; question: string } & AdditionalPlayerFields);
+export type BossReplies = Partial<Record<ResumableStateId, string>>;
 
-export interface PlaybookInput {
-  stateId: 'reviewCommit';
-  sourceItem: 'DECIDE-4';
-  playbookId: 'review';
-  text: string;
-}
+const RESUMABLE_STATES = {
+  askCoderProposal: { sourceItem: 'DECIDE-1', roleId: 'coder' },
+  askReviewerProposal: { sourceItem: 'DECIDE-2', roleId: 'reviewer' },
+  synthesizeCommit: { sourceItem: 'DECIDE-3', roleId: 'coder' },
+} as const satisfies Record<
+  ResumableStateId,
+  {
+    readonly sourceItem: PendingBossQuestion['sourceItem'];
+    readonly roleId: DecideRoleId;
+  }
+>;
 
-type PlayerDoneEvent = { type: string; output: PlayerOutput };
-type ActorErrorEvent = { type: string; error: unknown };
-type PlaybookDoneEvent = { type: string; output: JsonValue | undefined };
+// ---------------------------------------------------------------------------
+// Prompts (each item's blockquote, verbatim) and local result contracts
+// ---------------------------------------------------------------------------
 
 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 INDEPENDENT_PROPOSAL_PROMPT = [
-  '> Original topic: <caller-topic>',
+/** DECIDE-1 blockquote; `<caller-topic>` is carried as `callerTopic`. */
+const CODER_PROPOSAL_PROMPT = [
+  'Assess whether the topic is better expressed as a few spec items under @specs/packages/ or requires one or more DRs under @specs/decisions/.',
+  'Propose your design.',
+  'Keep your proposal coherent, focused, and concise.',
+  'Consult @specs/map.md for relevant context and @specs/meta.md for spec requirements, if needed.',
+  'Do not change any files.',
   '',
+  '> Original topic: <caller-topic>',
+].join('\n');
+
+/** DECIDE-2 blockquote; `<caller-topic>` is carried as `callerTopic`. */
+const REVIEWER_PROPOSAL_PROMPT = [
   'Assess whether the topic is better expressed as a few spec items under @specs/packages/ or requires one or more DRs under @specs/decisions/.',
   'Propose your design.',
   'Keep your proposal coherent, focused, and concise.',
   'Consult @specs/map.md for relevant context and @specs/meta.md for spec requirements, if needed.',
   'Do not change any files.',
+  '',
+  '> Original topic: <caller-topic>',
 ].join('\n');
 
+/**
+ * DECIDE-3 blockquote. `<caller-topic>` is carried as `callerTopic` and
+ * `<reviewer-proposal>` as `reviewerProposal`. `<coder-llm>` and
+ * `<reviewer-llm>` are local-role prompt identities of Coder and Reviewer: the
+ * linker resolves them through the invocation-scoped `promptIdentity(roleId)`
+ * lookup, so they stay literal here and have no machine or actor-input field.
+ */
 const SYNTHESIZE_COMMIT_PROMPT = [
   "Synthesize your independent proposal with Reviewer's proposal below.",
   'Keep to the original topic below and follow what it asks.',
@@ -174,362 +148,773 @@ const SYNTHESIZE_COMMIT_PROMPT = [
   "> Reviewer's independent proposal: <reviewer-proposal>",
 ].join('\n');
 
-const REVIEW_INPUT_TEMPLATE = [
+const CODER_PROPOSAL_RESULT = {
+  proposed:
+    'Coder affirmatively provided a complete design proposal; a progress report, status update, or promise of a later proposal supports no proposal outcome. Output shall include `coderProposal: <verbatim final text>`.',
+  needsBossReply: NEEDS_BOSS_REPLY_DESCRIPTION,
+} as const;
+
+const REVIEWER_PROPOSAL_RESULT = {
+  proposed:
+    'Reviewer affirmatively provided a complete design proposal; a progress report, status update, or promise of a later proposal supports no proposal outcome. Output shall include `reviewerProposal: <verbatim final text>`.',
+  needsBossReply: NEEDS_BOSS_REPLY_DESCRIPTION,
+} as const;
+
+const SYNTHESIZE_COMMIT_RESULT = {
+  committed:
+    'Coder synthesized the proposals into the necessary DRs and/or spec items and committed the result as one new commit. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.',
+  needsBossReply: NEEDS_BOSS_REPLY_DESCRIPTION,
+} as const;
+
+/** DECIDE-4 blockquote: the `review` call-text template, verbatim. */
+const REVIEW_COMMIT_TEMPLATE = [
   '> Original intent: <caller-topic>',
   '> Review scope: the `decide`-owned commit <decide-commit> and its resulting repository state.',
+  "> Coder's independent proposal: <coder-proposal>",
   '> Coder output: <coder-output>',
 ].join('\n');
 
-function composeReviewInput(
-  callerTopic: string | undefined,
-  decideCommit: string | undefined,
-  coderOutput: string | undefined,
-): string {
-  const fields: Readonly<Record<string, string>> = {
-    '<caller-topic>': callerTopic ?? '',
-    '<decide-commit>': decideCommit ?? '',
-    '<coder-output>': coderOutput ?? '',
-  };
-  return REVIEW_INPUT_TEMPLATE.replace(
-    /<caller-topic>|<decide-commit>|<coder-output>/g,
-    (placeholder, offset: number, source: string) => {
-      const value = fields[placeholder];
-      const lineStart = source.lastIndexOf('\n', offset - 1) + 1;
-      return source.slice(lineStart, offset).startsWith('> ')
-        ? value.replaceAll('\n', '\n> ')
-        : value;
-    },
-  );
+// ---------------------------------------------------------------------------
+// Delegated player actor contract
+// ---------------------------------------------------------------------------
+
+interface PlayerInputBase {
+  readonly pendingBossQuestion?: PendingBossQuestion;
+  readonly bossReply?: string;
 }
 
-const outputOf = (event: unknown): PlayerOutput =>
-  (event as PlayerDoneEvent).output;
+/** DECIDE-1: relays `<caller-topic>` as `callerTopic`. */
+export interface CoderProposalInput extends PlayerInputBase {
+  readonly stateId: 'askCoderProposal';
+  readonly role: 'coder';
+  readonly sourceItem: 'DECIDE-1';
+  readonly prompt: string;
+  readonly result: typeof CODER_PROPOSAL_RESULT;
+  /** `<caller-topic>`: the caller's complete topic. */
+  readonly callerTopic: string;
+}
 
-const playbookOutputOf = (event: unknown): JsonValue | undefined =>
-  (event as PlaybookDoneEvent).output;
+/** DECIDE-2: relays `<caller-topic>` as `callerTopic`. */
+export interface ReviewerProposalInput extends PlayerInputBase {
+  readonly stateId: 'askReviewerProposal';
+  readonly role: 'reviewer';
+  readonly sourceItem: 'DECIDE-2';
+  readonly prompt: string;
+  readonly result: typeof REVIEWER_PROPOSAL_RESULT;
+  /** `<caller-topic>`: the caller's complete topic. */
+  readonly callerTopic: string;
+}
 
-const isNonEmptyString = (value: unknown): value is string =>
-  typeof value === 'string' && value.trim().length > 0;
+/**
+ * DECIDE-3: relays `<caller-topic>` as `callerTopic` and
+ * `<reviewer-proposal>` as `reviewerProposal`.
+ */
+export interface SynthesizeCommitInput extends PlayerInputBase {
+  readonly stateId: 'synthesizeCommit';
+  readonly role: 'coder';
+  readonly sourceItem: 'DECIDE-3';
+  readonly prompt: string;
+  readonly result: typeof SYNTHESIZE_COMMIT_RESULT;
+  /** `<caller-topic>`: the caller's complete topic. */
+  readonly callerTopic: string;
+  /** `<reviewer-proposal>`: Reviewer's complete independent proposal. */
+  readonly reviewerProposal: string;
+}
 
-const coderProposed = ({ event }: { event: unknown }) => {
-  const output = outputOf(event);
-  return output.guard === 'proposed' && isNonEmptyString(output.coderProposal);
-};
+export type PlayerInput =
+  | CoderProposalInput
+  | ReviewerProposalInput
+  | SynthesizeCommitInput;
 
-const reviewerProposed = ({ event }: { event: unknown }) => {
-  const output = outputOf(event);
-  return (
-    output.guard === 'proposed' && isNonEmptyString(output.reviewerProposal)
-  );
-};
+export interface NeedsBossReplyOutput {
+  readonly guard: 'needsBossReply';
+  readonly question: string;
+}
 
-function commitOutput(
-  event: unknown,
-): { readonly coderOutput: string; readonly latestCommit: string } | undefined {
-  const output = outputOf(event);
-  if (
-    output.guard !== 'committed' ||
-    !isNonEmptyString(output.coderOutput) ||
-    !isNonEmptyString(output.latestCommit)
-  ) {
-    return undefined;
-  }
+export type CoderProposalOutput =
+  | { readonly guard: 'proposed'; readonly coderProposal: string }
+  | NeedsBossReplyOutput;
+
+export type ReviewerProposalOutput =
+  | { readonly guard: 'proposed'; readonly reviewerProposal: string }
+  | NeedsBossReplyOutput;
+
+export type SynthesizeCommitOutput =
+  | {
+      readonly guard: 'committed';
+      readonly coderOutput: string;
+      /** Effect-owned: the runtime fills it from the repository receipt. */
+      readonly latestCommit: string;
+    }
+  | NeedsBossReplyOutput;
+
+export type PlayerOutput =
+  | CoderProposalOutput
+  | ReviewerProposalOutput
+  | SynthesizeCommitOutput;
+
+// ---------------------------------------------------------------------------
+// Nested playbook actor contract
+// ---------------------------------------------------------------------------
+
+/** DECIDE-4: literal call of the builtin `review` playbook. */
+export interface PlaybookInput {
+  readonly stateId: 'reviewCommit';
+  readonly sourceItem?: 'DECIDE-4';
+  readonly playbookId: typeof REVIEW_PLAYBOOK_ID;
+  readonly text: string;
+}
+
+/** A successful call yields the child's own JSON-safe machine output. */
+export type PlaybookOutput = JsonValue | undefined;
+
+/** Public output interface of the packaged builtin `review`. */
+export interface ReviewOutput {
+  readonly noUnsettledFindings: true;
+  readonly evaluatedRevision: string;
+}
+
+/** Sanitized completed-result evidence of the `review` call that ended DECIDE. */
+export type CompletedReviewResult =
+  | {
+      readonly playbookId: typeof REVIEW_PLAYBOOK_ID;
+      readonly status: 'ok';
+      readonly output?: JsonValue;
+    }
+  | {
+      readonly playbookId: typeof REVIEW_PLAYBOOK_ID;
+      readonly status: 'aborted' | 'error';
+      readonly error: CompactError;
+    };
+
+// ---------------------------------------------------------------------------
+// Machine input, context, events, and output
+// ---------------------------------------------------------------------------
+
+/** The machine reads no input: the caller's topic arrives on `START_DECIDE`. */
+export type DecideInput = Readonly<Record<string, never>>;
+
+export type ReviewStatus = 'aborted' | 'error';
+
+/**
+ * Typed run context. A text field holds `''` until its producer runs; every
+ * transition that enters a consumer guards the fields it reads as non-empty.
+ */
+export interface DecideContext {
+  /** `<caller-topic>`: set by `START_DECIDE` or a restarting interrupt. */
+  readonly callerTopic: string;
+  /** Branch-staged proposals; the parallel join promotes them atomically. */
+  readonly stagedCoderProposal: string;
+  readonly stagedReviewerProposal: string;
+  /** `<coder-proposal>`: Coder's promoted independent proposal. */
+  readonly coderProposal: string;
+  /** `<reviewer-proposal>`: Reviewer's promoted independent proposal. */
+  readonly reviewerProposal: string;
+  /** `<coder-output>`: Coder's verbatim final synthesis text. */
+  readonly coderOutput: string;
+  /** `<decide-commit>`: DECIDE-3's accepted, receipt-owned `latestCommit`. */
+  readonly decideCommit: string;
+  /** Revision evaluated by the passing `review`. */
+  readonly evaluatedRevision: string;
+  /** Reported status when `review` did not pass the commit. */
+  readonly reviewStatus: ReviewStatus | null;
+  /** Compact failure DECIDE reports when `review` did not pass the commit. */
+  readonly reviewError: CompactError | null;
+  /** Sanitized evidence of the `review` result that ended DECIDE. */
+  readonly reviewEvidence: CompletedReviewResult | null;
+  readonly lastError: ErrorRecord | null;
+  readonly pendingBossQuestions: PendingBossQuestions;
+  readonly bossReplies: BossReplies;
+}
+
+export type DecideEvent =
+  | { readonly type: 'START_DECIDE'; readonly callerTopic: string }
+  | {
+      readonly type: 'BOSS_INTERRUPT';
+      readonly targetId: 'independentProposals';
+      /** The new topic both proposal players receive. */
+      readonly callerTopic: string;
+    }
+  | {
+      readonly type: 'BOSS_INTERRUPT';
+      readonly targetId: 'synthesizeCommit';
+    }
+  | {
+      readonly type: 'BOSS_REPLY';
+      readonly questionId: string;
+      readonly answer: string;
+    };
+
+/** Exactly the catalog's public `decide` output interface. */
+export type DecideOutput =
+  | {
+      readonly decideCommit: string;
+      readonly evaluatedRevision: string;
+      readonly noUnsettledFindings: true;
+    }
+  | {
+      readonly lastDecideCommit: string;
+      readonly noUnsettledFindings: false;
+      readonly reviewStatus: ReviewStatus;
+      readonly error?: CompactError;
+    };
+
+// ---------------------------------------------------------------------------
+// State descriptions and public metadata
+// ---------------------------------------------------------------------------
+
+const STATE_DESCRIPTIONS = {
+  ready: 'Waiting for the caller to give a topic to decide.',
+  independentProposals:
+    'Coder and Reviewer independently propose designs for the topic in parallel.',
+  coderProposalRegion: "Coder's independent proposal branch.",
+  askCoderProposal: 'Coder is independently proposing a design for the topic.',
+  awaitCoderProposalReply:
+    "Waiting for Boss to answer Coder's question about its independent proposal.",
+  coderProposalStaged:
+    "Coder's independent proposal is complete and staged for the join.",
+  reviewerProposalRegion: "Reviewer's independent proposal branch.",
+  askReviewerProposal:
+    'Reviewer is independently proposing a design for the topic.',
+  awaitReviewerProposalReply:
+    "Waiting for Boss to answer Reviewer's question about its independent proposal.",
+  reviewerProposalStaged:
+    "Reviewer's independent proposal is complete and staged for the join.",
+  synthesizeCommit:
+    'Coder synthesizes both proposals into the necessary DRs and/or spec items and commits the result as one new commit.',
+  awaitBossReply: "Waiting for Boss to answer the acting agent's question.",
+  reviewCommit: 'The review playbook examines the decide-owned commit.',
+  failed:
+    'DECIDE parked after a control-plane failure and waits for Boss to restart or resume it.',
+  reportedReviewFailure:
+    "DECIDE reported review's abort, failure, or unestablished result to its caller with the last decide-owned commit.",
+  done: 'DECIDE completed: review established no unsettled findings for the decide-owned commit at the reported evaluated revision.',
+} as const;
+
+type DescribedStateId = keyof typeof STATE_DESCRIPTIONS;
+
+function playbookMeta(stateId: DescribedStateId, role?: DecideRoleId) {
   return {
-    coderOutput: output.coderOutput,
-    latestCommit: output.latestCommit,
+    playbook: {
+      stateId,
+      description: STATE_DESCRIPTIONS[stateId],
+      ...(role === undefined ? {} : { role }),
+    },
   };
 }
 
-const committed = ({ event }: { event: unknown }) =>
-  commitOutput(event) !== undefined;
+function terminalMeta(
+  stateId: 'reportedReviewFailure' | 'done',
+  terminal: 'success' | 'failure',
+) {
+  return {
+    playbook: {
+      stateId,
+      description: STATE_DESCRIPTIONS[stateId],
+      terminal,
+    },
+  };
+}
 
-const needsBossReplyWithQuestion = ({ event }: { event: unknown }) => {
-  const output = outputOf(event);
-  return output.guard === 'needsBossReply' && isNonEmptyString(output.question);
-};
+// ---------------------------------------------------------------------------
+// Structural narrowing helpers
+// ---------------------------------------------------------------------------
+
+function isObject(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === 'object' && value !== null;
+}
 
-const needsBossReplyWithoutQuestion = ({ event }: { event: unknown }) => {
-  const output = outputOf(event);
+function isPlainRecord(
+  value: unknown,
+): value is Readonly<Record<string, unknown>> {
+  if (!isObject(value) || 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 isResumableStateId(value: unknown): value is ResumableStateId {
   return (
-    output.guard === 'needsBossReply' && !isNonEmptyString(output.question)
+    value === 'askCoderProposal' ||
+    value === 'askReviewerProposal' ||
+    value === 'synthesizeCommit'
   );
-};
+}
 
-const pendingQuestionIds = (context: DecideContext): ResumableStateId[] =>
-  Object.keys(context.pendingBossQuestions ?? {}) as ResumableStateId[];
+/** The actor's `output`, narrowed structurally from an unknown done event. */
+function actorOutput(
+  event: unknown,
+): Readonly<Record<string, unknown>> | undefined {
+  if (!isObject(event)) return undefined;
+  const output = event.output;
+  return isPlainRecord(output) ? output : undefined;
+}
 
-const resolvedQuestionId = (
-  context: DecideContext,
-  event: DecideEvent,
-): ResumableStateId | undefined => {
-  if (event.type !== 'BOSS_REPLY') return undefined;
-  if (event.questionId) return event.questionId;
-  const ids = pendingQuestionIds(context);
-  return ids.length === 1 ? ids[0] : undefined;
-};
+function outputString(event: unknown, field: string): string | undefined {
+  const value = actorOutput(event)?.[field];
+  return isNonEmptyString(value) ? value : undefined;
+}
 
-const bossReplyTargets =
-  (stateId: ResumableStateId, requireAnswer: boolean) =>
-  ({ context, event }: { context: DecideContext; event: DecideEvent }) =>
-    event.type === 'BOSS_REPLY' &&
-    resolvedQuestionId(context, event) === stateId &&
-    (requireAnswer
-      ? event.answer.trim().length > 0
-      : event.answer.trim().length === 0);
+function outputGuardIs(event: unknown, guard: PlayerOutput['guard']): boolean {
+  return actorOutput(event)?.guard === guard;
+}
 
-const bossReplyFields = (
-  context: DecideContext,
-  stateId: ResumableStateId,
-) => ({
-  ...(context.pendingBossQuestions?.[stateId]
-    ? { pendingBossQuestion: context.pendingBossQuestions[stateId] }
-    : {}),
-  ...(context.bossReplies?.[stateId]
-    ? { bossReply: context.bossReplies[stateId] }
-    : {}),
-});
+/** The actor's `error`, narrowed structurally from an unknown error event. */
+function actorError(event: unknown): unknown {
+  return isObject(event) ? event.error : undefined;
+}
+
+/** Normalizes any thrown or malformed value to a JSON-safe error record. */
+function errorRecord(value: unknown): ErrorRecord {
+  if (value instanceof Error) {
+    return {
+      name: isNonEmptyString(value.name) ? value.name : 'Error',
+      message: typeof value.message === 'string' ? value.message : '',
+      ...(typeof value.stack === 'string' ? { stack: value.stack } : {}),
+    };
+  }
+  if (isObject(value) && typeof value.message === 'string') {
+    return {
+      name: isNonEmptyString(value.name) ? value.name : 'Error',
+      message: value.message,
+    };
+  }
+  return {
+    name: 'Error',
+    message:
+      typeof value === 'string'
+        ? value
+        : 'The actor failed with a non-Error value.',
+  };
+}
 
-const withoutKey = <T>(
-  record: Partial<Record<ResumableStateId, T>> | undefined,
+function withoutKey<Value>(
+  record: Partial<Record<ResumableStateId, Value>>,
   stateId: ResumableStateId,
-): Partial<Record<ResumableStateId, T>> | undefined => {
-  if (!record || record[stateId] === undefined) return record;
-  const next = { ...record };
-  delete next[stateId];
-  return Object.keys(next).length > 0 ? next : undefined;
-};
+): Partial<Record<ResumableStateId, Value>> {
+  const next: Partial<Record<ResumableStateId, Value>> = {};
+  for (const key of Object.keys(record)) {
+    if (!isResumableStateId(key) || key === stateId) continue;
+    const value = record[key];
+    if (value !== undefined) next[key] = value;
+  }
+  return next;
+}
 
-const withNeedsBossReply = <T extends Record<string, string>>(result: T) => ({
-  ...result,
-  needsBossReply: NEEDS_BOSS_REPLY_DESCRIPTION,
-});
+/**
+ * Strict JSON validation: null, booleans, finite numbers, strings, exact
+ * arrays, and plain records of enumerable own data properties. Cycle
+ * detection tracks only the active recursion path.
+ */
+function isJsonValue(
+  value: unknown,
+  path: Set<object> = new Set(),
+): value is JsonValue {
+  if (value === null) return true;
+  switch (typeof value) {
+    case 'boolean':
+    case 'string':
+      return true;
+    case 'number':
+      return Number.isFinite(value);
+    case 'object':
+      break;
+    default:
+      return false;
+  }
+  const container = value as object;
+  if (path.has(container)) return false;
+  path.add(container);
+  try {
+    if (Array.isArray(container)) {
+      if (Object.getPrototypeOf(container) !== Array.prototype) return false;
+      const keys = Reflect.ownKeys(container);
+      if (keys.length !== container.length + 1) return false;
+      const lengthDescriptor = Object.getOwnPropertyDescriptor(
+        container,
+        'length',
+      );
+      if (
+        lengthDescriptor === undefined ||
+        lengthDescriptor.configurable !== false ||
+        lengthDescriptor.enumerable !== false ||
+        lengthDescriptor.value !== container.length
+      ) {
+        return false;
+      }
+      for (let index = 0; index < container.length; index += 1) {
+        const descriptor = Object.getOwnPropertyDescriptor(
+          container,
+          String(index),
+        );
+        if (
+          descriptor === undefined ||
+          !descriptor.enumerable ||
+          !('value' in descriptor) ||
+          !isJsonValue(descriptor.value, path)
+        ) {
+          return false;
+        }
+      }
+      return true;
+    }
+    const prototype = Object.getPrototypeOf(container);
+    if (prototype !== Object.prototype && prototype !== null) return false;
+    for (const key of Reflect.ownKeys(container)) {
+      if (typeof key !== 'string') return false;
+      const descriptor = Object.getOwnPropertyDescriptor(container, key);
+      if (
+        descriptor === undefined ||
+        !descriptor.enumerable ||
+        !('value' in descriptor) ||
+        !isJsonValue(descriptor.value, path)
+      ) {
+        return false;
+      }
+    }
+    return true;
+  } finally {
+    path.delete(container);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Actor-output narrowing (declared per-state result contracts)
+// ---------------------------------------------------------------------------
 
-const isPlainRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' &&
-  value !== null &&
-  !Array.isArray(value) &&
-  (Object.getPrototypeOf(value) === Object.prototype ||
-    Object.getPrototypeOf(value) === null);
-
-const isExactKeys = (
-  value: Record<string, unknown>,
-  keys: readonly string[],
-): boolean => {
-  const ownKeys = Reflect.ownKeys(value);
+function isCoderProposed(event: unknown): boolean {
   return (
-    ownKeys.length === keys.length &&
-    ownKeys.every((key) => typeof key === 'string' && keys.includes(key))
+    outputGuardIs(event, 'proposed') &&
+    outputString(event, 'coderProposal') !== undefined
   );
-};
+}
 
-function isStateValue(value: unknown, ancestors = new Set<object>()): boolean {
-  if (typeof value === 'string') return true;
-  if (!isPlainRecord(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 isReviewerProposed(event: unknown): boolean {
+  return (
+    outputGuardIs(event, 'proposed') &&
+    outputString(event, 'reviewerProposal') !== undefined
   );
 }
 
-function isStringArray(value: unknown): value is readonly string[] {
+function isCommitted(event: unknown): boolean {
   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
+    outputGuardIs(event, 'committed') &&
+    outputString(event, 'coderOutput') !== undefined &&
+    outputString(event, 'latestCommit') !== undefined
   );
 }
 
-function isPlaybookState(value: unknown): boolean {
-  if (!isPlainRecord(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;
-  }
+function isNeedsBossReply(event: unknown): boolean {
   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))
+    outputGuardIs(event, 'needsBossReply') &&
+    outputString(event, 'question') !== undefined
   );
 }
 
-// DECIDE supplied `review` a scope rooted at the `decide`-owned commit, so a
-// result applies to that scope only when it is the exact declared terminal
-// contract: the evaluated repository revision plus the affirmative
-// no-unsettled-findings fact. Any other shape does not establish those facts.
-function reviewSuccessFrom(event: unknown): ReviewSuccessOutput | undefined {
-  const output = playbookOutputOf(event);
-  if (!isPlainRecord(output)) return undefined;
-  if (!isExactKeys(output, ['evaluatedRevision', 'noUnsettledFindings'])) {
+// ---------------------------------------------------------------------------
+// Nested `review` results
+// ---------------------------------------------------------------------------
+
+/**
+ * Recognizes an authored rejected child result: a validated public result
+ * whose status is `aborted` or `error`, or `ok` at the child's own authored
+ * failure terminal. Anything else is a control-plane error.
+ */
+export function authoredChildResult(
+  error: unknown,
+  expectedPlaybookId: string,
+): PlaybookCallResult | undefined {
+  if (!(error instanceof Error)) return undefined;
+  try {
+    const result = validatePlaybookCallResult(
+      (error as Error & { result?: unknown }).result,
+      expectedPlaybookId,
+    );
+    return result.status !== 'ok' || result.terminal?.kind === 'failure'
+      ? result
+      : undefined;
+  } catch {
     return undefined;
   }
+}
+
+/**
+ * DECIDE-4's acceptance predicate on the builtin `review` public interface:
+ * the result gives the exact evaluated repository revision and affirmatively
+ * establishes that no unsettled findings remain. The shared bridge correlates
+ * the result with the supplied review scope.
+ */
+function reviewApprovalFrom(event: unknown): ReviewOutput | undefined {
+  const output = actorOutput(event);
+  if (output === undefined) return undefined;
   if (
-    !isNonEmptyString(output.evaluatedRevision) ||
-    output.noUnsettledFindings !== true
+    output.noUnsettledFindings !== true ||
+    !isNonEmptyString(output.evaluatedRevision)
   ) {
     return undefined;
   }
   return {
-    evaluatedRevision: output.evaluatedRevision,
     noUnsettledFindings: true,
+    evaluatedRevision: output.evaluatedRevision,
   };
 }
 
-const validReviewSuccess = ({ event }: { event: unknown }) =>
-  reviewSuccessFrom(event) !== undefined;
-
-function normalizedChildFailure(error: unknown): ChildFailure | undefined {
-  if (!(error instanceof Error)) return undefined;
-  const result = (error as Error & { result?: unknown }).result;
-  if (!isPlainRecord(result)) 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' ||
-    Object.prototype.hasOwnProperty.call(result, 'output')
-  ) {
-    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: ChildFailure['error'];
-  if (Object.prototype.hasOwnProperty.call(result, 'error')) {
-    if (!isPlainRecord(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')
-    ) {
-      return undefined;
-    }
-    if (
-      !isNonEmptyString(result.error.name) ||
-      typeof result.error.message !== 'string' ||
-      (Object.prototype.hasOwnProperty.call(result.error, 'stack') &&
-        typeof result.error.stack !== 'string')
-    ) {
-      return undefined;
+/** Reported status, compact error, and evidence of an authored review failure. */
+function authoredReviewFailureOf(event: unknown):
+  | {
+      readonly status: ReviewStatus;
+      readonly error: CompactError;
+      readonly evidence: CompletedReviewResult;
     }
-    normalizedError = {
-      name: result.error.name,
-      message: result.error.message,
+  | undefined {
+  const result = authoredChildResult(actorError(event), REVIEW_PLAYBOOK_ID);
+  if (result === undefined) return undefined;
+  if (result.status === 'ok') {
+    // `ok` at review's own authored failure terminal: a review failure whose
+    // own output is relayed as evidence.
+    const description = result.terminal?.description;
+    return {
+      status: 'error',
+      error: {
+        name: 'ReviewFailed',
+        message: isNonEmptyString(description)
+          ? `review ended at its authored failure terminal: ${description}`
+          : 'review ended at its authored failure terminal.',
+      },
+      evidence: {
+        playbookId: REVIEW_PLAYBOOK_ID,
+        status: 'ok',
+        ...(result.output === undefined ? {} : { output: result.output }),
+      },
     };
-  } else if (result.status === 'error') {
-    return undefined;
   }
+  const error: CompactError =
+    result.error !== undefined
+      ? { name: result.error.name, message: result.error.message }
+      : { name: 'AbortError', message: 'The review call was aborted.' };
   return {
     status: result.status,
-    playbookId: 'review',
-    ...(normalizedError ? { error: normalizedError } : {}),
+    error,
+    evidence: { playbookId: REVIEW_PLAYBOOK_ID, status: result.status, error },
   };
 }
 
-const authoredReviewFailure = ({ event }: { event: unknown }) =>
-  normalizedChildFailure((event as ActorErrorEvent).error) !== undefined;
-
-function bossInterrupts(ids: readonly JumpableStateId[]): any[] {
-  return ids.map((id) => ({
-    guard: ({ event }: { event: DecideEvent }) =>
-      event.type === 'BOSS_INTERRUPT' &&
-      event.targetId === id &&
-      typeof event.bossIntent === 'string' &&
-      event.bossIntent.trim().length > 0,
-    target: `#${id}`,
-    reenter: true,
-    actions: 'copyInterruptedTopic',
-  }));
+const REVIEW_NOT_ESTABLISHED: CompactError = {
+  name: 'ReviewNotEstablished',
+  message:
+    'review returned a terminal result that does not establish the exact evaluated repository revision with no unsettled findings.',
+};
+
+// ---------------------------------------------------------------------------
+// Nested call text composition (DECIDE-4 quoted relays)
+// ---------------------------------------------------------------------------
+
+const REVIEW_PLACEHOLDER =
+  /<caller-topic>|<decide-commit>|<coder-proposal>|<coder-output>/g;
+
+/**
+ * Composes the `review` call text from the verbatim template, one line at a
+ * time: a quoted relay line whose value is empty contributes no line, and a
+ * multi-line value is quoted line by line. The composer adds no empty quoted
+ * line of its own.
+ */
+function reviewCallText(context: DecideContext): string {
+  const values: Readonly<Record<string, string>> = {
+    '<caller-topic>': context.callerTopic,
+    '<decide-commit>': context.decideCommit,
+    '<coder-proposal>': context.coderProposal,
+    '<coder-output>': context.coderOutput,
+  };
+  const lines: string[] = [];
+  for (const line of REVIEW_COMMIT_TEMPLATE.split('\n')) {
+    const tokens = line.match(REVIEW_PLACEHOLDER) ?? [];
+    if (tokens.some((token) => values[token] === '')) continue;
+    lines.push(
+      line.replace(REVIEW_PLACEHOLDER, (token: string) =>
+        (values[token] ?? token).split('\n').join('\n> '),
+      ),
+    );
+  }
+  return lines.join('\n');
 }
 
-function resumableStates(ids: readonly ResumableStateId[]): any[] {
-  return ids.map((id) => ({
-    guard: ({ context, event }: { context: DecideContext; event: DecideEvent }) =>
-      event.type === 'BOSS_REPLY' &&
-      event.answer.trim().length > 0 &&
-      resolvedQuestionId(context, event) === id,
-    target: `#${id}`,
-    reenter: true,
-    actions: 'rememberBossReply',
-  }));
+// ---------------------------------------------------------------------------
+// Player input mapping (pure reads of typed, entry-validated context)
+// ---------------------------------------------------------------------------
+
+function bossReplyFields(
+  context: DecideContext,
+  stateId: ResumableStateId,
+): PlayerInputBase {
+  const pendingBossQuestion = context.pendingBossQuestions[stateId];
+  const bossReply = context.bossReplies[stateId];
+  return {
+    ...(pendingBossQuestion === undefined ? {} : { pendingBossQuestion }),
+    ...(bossReply === undefined ? {} : { bossReply }),
+  };
 }
 
-const stateMetadata: Record<
-  ResumableStateId,
-  { sourceItem: string; asker: { kind: 'role'; roleId: Role } }
-> = {
-  askCoderProposal: {
-    sourceItem: 'DECIDE-1',
-    asker: { kind: 'role', roleId: 'coder' },
-  },
-  askReviewerProposal: {
-    sourceItem: 'DECIDE-2',
-    asker: { kind: 'role', roleId: 'reviewer' },
-  },
-  commitCoderProposal: {
-    sourceItem: 'DECIDE-3',
-    asker: { kind: 'role', roleId: 'coder' },
-  },
+// ---------------------------------------------------------------------------
+// Context snapshots
+// ---------------------------------------------------------------------------
+
+const INITIAL_CONTEXT: DecideContext = {
+  callerTopic: '',
+  stagedCoderProposal: '',
+  stagedReviewerProposal: '',
+  coderProposal: '',
+  reviewerProposal: '',
+  coderOutput: '',
+  decideCommit: '',
+  evaluatedRevision: '',
+  reviewStatus: null,
+  reviewError: null,
+  reviewEvidence: null,
+  lastError: null,
+  pendingBossQuestions: {},
+  bossReplies: {},
+};
+
+/**
+ * A fresh run for a topic: clears every staged and promoted proposal, the
+ * commit, review evidence, errors, and every pending Boss question and reply.
+ */
+function freshRun(callerTopic: string): DecideContext {
+  return { ...INITIAL_CONTEXT, callerTopic };
+}
+
+/** Context reset shared by every exit into `failed`. */
+const FAILURE_RESET = {
+  pendingBossQuestions: {},
+  bossReplies: {},
+  stagedCoderProposal: '',
+  stagedReviewerProposal: '',
+} as const;
+
+/**
+ * A synthesis restart keeps the topic and the promoted proposals, and clears
+ * the prior commit, review evidence, error, and every pending question.
+ */
+const SYNTHESIS_RESTART = {
+  coderOutput: '',
+  decideCommit: '',
+  evaluatedRevision: '',
+  reviewStatus: null,
+  reviewError: null,
+  reviewEvidence: null,
+  lastError: null,
+  pendingBossQuestions: {},
+  bossReplies: {},
+} as const;
+
+// ---------------------------------------------------------------------------
+// Transition helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Accepted-outcome marker (artifact schema 3). `target` names the public
+ * state the next snapshot shows after the transition's macrostep.
+ */
+function acceptedOutcome(
+  source: ResumableStateId,
+  target: DescribedStateId,
+  outcome: 'proposed' | 'committed' | 'needsBossReply',
+) {
+  return {
+    type: 'playbook.acceptedOutcome',
+    params: { source, target, acceptedOutcome: outcome },
+  } as const;
+}
+
+/** Root `BOSS_INTERRUPT` arms, one per jumpable state. */
+function bossInterrupts<const Ids extends readonly JumpableStateId[]>(
+  ids: Ids,
+) {
+  return ids.map(
+    (targetId) =>
+      ({
+        guard: { type: 'interruptTargets', params: { targetId } },
+        target: `#${targetId}`,
+        reenter: true,
+        actions: 'restartFromInterrupt',
+      }) as const,
+  );
+}
+
+/** Keyed `BOSS_REPLY` arms of the wait that resumes the given working leaves. */
+function resumableStates<const Ids extends readonly ResumableStateId[]>(
+  ids: Ids,
+) {
+  return ids.flatMap((stateId) => [
+    {
+      guard: { type: 'bossReplyIsEmpty', params: { stateId } },
+      target: '#failed',
+      actions: 'rememberEmptyBossReply',
+    } as const,
+    {
+      guard: { type: 'bossReplyResumes', params: { stateId } },
+      target: `#${stateId}`,
+      reenter: true,
+      actions: { type: 'rememberBossReply', params: { stateId } },
+    } as const,
+  ]);
+}
+
+/**
+ * At the root synthesis wait, where no other task is active, a keyed
+ * `BOSS_REPLY` that names no pending question fails the run.
+ */
+const unknownBossReplyArm = {
+  guard: 'bossReplyNamesNoPendingQuestion',
+  target: '#failed',
+  actions: 'rememberUnknownBossReply',
+} as const;
+
+const startDecideArm = {
+  guard: 'validStartTopic',
+  target: '#independentProposals',
+  actions: 'startDecide',
+} as const;
+
+function suspendArm(
+  stateId: ResumableStateId,
+  wait: 'awaitCoderProposalReply' | 'awaitReviewerProposalReply' | 'awaitBossReply',
+) {
+  return {
+    guard: 'needsBossReply',
+    target: `#${wait}`,
+    actions: [
+      acceptedOutcome(stateId, wait, 'needsBossReply'),
+      { type: 'setPendingBossQuestion', params: { stateId } },
+    ],
+  } as const;
+}
+
+function malformedPlayerOutputArm(sourceItem: DecideSourceItem) {
+  return {
+    target: '#failed',
+    actions: { type: 'rememberMalformedPlayerOutput', params: { sourceItem } },
+  } as const;
+}
+
+const playerOnError = {
+  target: '#failed',
+  actions: 'rememberActorError',
+} as const;
+
+type EventArgs = { readonly event: unknown };
+type ContextEventArgs = {
+  readonly context: DecideContext;
+  readonly event: unknown;
 };
 
+// ---------------------------------------------------------------------------
+// Machine
+// ---------------------------------------------------------------------------
+
 export const decideMachine = setup({
   types: {
     context: {} as DecideContext,
@@ -541,10 +926,75 @@ export const decideMachine = setup({
     player: fromPromise<PlayerOutput, PlayerInput>(async () => {
       throw new Error('player actor must be provided by the runner');
     }),
-    playbook: fromPromise<JsonValue | undefined, PlaybookInput>(async () => {
+    playbook: fromPromise<PlaybookOutput, PlaybookInput>(async () => {
       throw new Error('playbook actor must be provided by the runner');
     }),
   },
+  guards: {
+    validStartTopic: ({ event }) =>
+      event.type === 'START_DECIDE' && isNonEmptyString(event.callerTopic),
+    // Each arm guards its target id and every typed precondition for
+    // entering that target safely.
+    interruptTargets: (
+      { context, event },
+      params: { readonly targetId: JumpableStateId },
+    ) => {
+      if (event.type !== 'BOSS_INTERRUPT') return false;
+      if (event.targetId !== params.targetId) return false;
+      if (event.targetId === 'independentProposals') {
+        return isNonEmptyString(event.callerTopic);
+      }
+      return (
+        isNonEmptyString(context.callerTopic) &&
+        isNonEmptyString(context.coderProposal) &&
+        isNonEmptyString(context.reviewerProposal)
+      );
+    },
+    // A branch completing after its sibling has staged its proposal also
+    // completes the join, so its accepted outcome lands on `synthesizeCommit`.
+    coderProposedJoining: ({ context, event }: ContextEventArgs) =>
+      isCoderProposed(event) &&
+      isNonEmptyString(context.stagedReviewerProposal) &&
+      isNonEmptyString(context.callerTopic),
+    coderProposed: ({ event }: EventArgs) => isCoderProposed(event),
+    reviewerProposedJoining: ({ context, event }: ContextEventArgs) =>
+      isReviewerProposed(event) &&
+      isNonEmptyString(context.stagedCoderProposal) &&
+      isNonEmptyString(context.callerTopic),
+    reviewerProposed: ({ event }: EventArgs) => isReviewerProposed(event),
+    committed: ({ context, event }: ContextEventArgs) =>
+      isCommitted(event) &&
+      isNonEmptyString(context.callerTopic) &&
+      isNonEmptyString(context.coderProposal),
+    needsBossReply: ({ event }: EventArgs) => isNeedsBossReply(event),
+    reviewApproved: ({ context, event }: ContextEventArgs) =>
+      isNonEmptyString(context.decideCommit) &&
+      reviewApprovalFrom(event) !== undefined,
+    authoredReviewFailure: ({ context, event }: ContextEventArgs) =>
+      isNonEmptyString(context.decideCommit) &&
+      authoredReviewFailureOf(event) !== undefined,
+    bossReplyNamesNoPendingQuestion: ({ context, event }) =>
+      event.type === 'BOSS_REPLY' &&
+      (!isResumableStateId(event.questionId) ||
+        context.pendingBossQuestions[event.questionId] === undefined),
+    bossReplyIsEmpty: (
+      { context, event },
+      params: { readonly stateId: ResumableStateId },
+    ) =>
+      event.type === 'BOSS_REPLY' &&
+      event.questionId === params.stateId &&
+      context.pendingBossQuestions[params.stateId] !== undefined &&
+      !isNonEmptyString(event.answer),
+    bossReplyResumes: (
+      { context, event },
+      params: { readonly stateId: ResumableStateId },
+    ) =>
+      event.type === 'BOSS_REPLY' &&
+      event.questionId === params.stateId &&
+      context.pendingBossQuestions[params.stateId] !== undefined &&
+      isNonEmptyString(event.answer) &&
+      isNonEmptyString(context.callerTopic),
+  },
   actions: {
     'playbook.acceptedOutcome': (
       _args,
@@ -554,702 +1004,474 @@ export const decideMachine = setup({
         readonly acceptedOutcome: string;
       },
     ) => undefined,
-    copyStartTopic: assign({
-      callerTopic: ({ event }) =>
-        event.type === 'START_DECIDE' ? event.callerTopic : undefined,
-      coderProposal: undefined,
-      reviewerProposal: undefined,
-      latestCommit: undefined,
-      coderOutput: undefined,
-      reviewResult: undefined,
-      reviewFailure: undefined,
-      lastResult: undefined,
-      lastError: undefined,
-      pendingBossQuestions: undefined,
-      bossReplies: undefined,
-      stagedCoderResult: undefined,
-      stagedReviewerResult: undefined,
-    }),
-    copyInterruptedTopic: assign({
-      callerTopic: ({ event }) =>
-        event.type === 'BOSS_INTERRUPT' ? event.bossIntent : undefined,
-      coderProposal: undefined,
-      reviewerProposal: undefined,
-      latestCommit: undefined,
-      coderOutput: undefined,
-      reviewResult: undefined,
-      reviewFailure: undefined,
-      lastResult: undefined,
-      lastError: undefined,
-      pendingBossQuestions: undefined,
-      bossReplies: undefined,
-      stagedCoderResult: undefined,
-      stagedReviewerResult: undefined,
-    }),
-    stageCoderProposal: assign({
-      stagedCoderResult: ({ event }) => outputOf(event),
-      lastResult: ({ event }) => outputOf(event),
-      lastError: undefined,
-    }),
-    stageReviewerProposal: assign({
-      stagedReviewerResult: ({ event }) => outputOf(event),
-      lastResult: ({ event }) => outputOf(event),
-      lastError: undefined,
-    }),
-    promoteProposals: assign({
-      coderProposal: ({ context }) =>
-        context.stagedCoderResult?.coderProposal,
-      reviewerProposal: ({ context }) =>
-        context.stagedReviewerResult?.reviewerProposal,
-      stagedCoderResult: undefined,
-      stagedReviewerResult: undefined,
-      lastResult: undefined,
-      lastError: undefined,
-    }),
-    rememberCommit: assign({
-      latestCommit: ({ event }) => outputOf(event).latestCommit,
-      coderOutput: ({ event }) => outputOf(event).coderOutput,
-      lastResult: ({ event }) => outputOf(event),
-      lastError: undefined,
+    startDecide: assign(({ event }) =>
+      event.type === 'START_DECIDE' ? freshRun(event.callerTopic) : {},
+    ),
+    // A new topic restarts the whole proposal pair from a fresh run; a
+    // synthesis restart keeps the topic and the promoted proposals.
+    restartFromInterrupt: assign(({ event }) => {
+      if (event.type !== 'BOSS_INTERRUPT') return {};
+      return event.targetId === 'independentProposals'
+        ? freshRun(event.callerTopic)
+        : SYNTHESIS_RESTART;
     }),
-    rememberReviewSuccess: assign({
-      reviewResult: ({ event }) => reviewSuccessFrom(event),
-      reviewFailure: undefined,
-      lastError: undefined,
-    }),
-    rememberReviewFailure: assign({
-      reviewFailure: ({ event }) =>
-        normalizedChildFailure((event as unknown as ActorErrorEvent).error),
-      lastError: undefined,
-    }),
-    rememberReviewProtocolFailure: assign({
-      reviewFailure: {
-        status: 'error',
-        playbookId: 'review',
-        error: {
-          name: 'ReviewProtocolError',
-          message:
-            'REVIEW returned without the evaluated repository revision and a no-unsettled-findings result for the supplied scope.',
-        },
+    // Each branch assigns only its own staged result.
+    stageCoderProposal: assign(({ context, event }) => ({
+      stagedCoderProposal: outputString(event, 'coderProposal') ?? '',
+      pendingBossQuestions: withoutKey(
+        context.pendingBossQuestions,
+        'askCoderProposal',
+      ),
+      bossReplies: withoutKey(context.bossReplies, 'askCoderProposal'),
+    })),
+    stageReviewerProposal: assign(({ context, event }) => ({
+      stagedReviewerProposal: outputString(event, 'reviewerProposal') ?? '',
+      pendingBossQuestions: withoutKey(
+        context.pendingBossQuestions,
+        'askReviewerProposal',
+      ),
+      bossReplies: withoutKey(context.bossReplies, 'askReviewerProposal'),
+    })),
+    // The join promotes both staged proposals atomically.
+    promoteProposals: assign(({ context }) => ({
+      coderProposal: context.stagedCoderProposal,
+      reviewerProposal: context.stagedReviewerProposal,
+      stagedCoderProposal: '',
+      stagedReviewerProposal: '',
+      pendingBossQuestions: {},
+      bossReplies: {},
+    })),
+    rememberCommit: assign(({ context, event }) => ({
+      coderOutput: outputString(event, 'coderOutput') ?? '',
+      decideCommit: outputString(event, 'latestCommit') ?? '',
+      lastError: null,
+      pendingBossQuestions: withoutKey(
+        context.pendingBossQuestions,
+        'synthesizeCommit',
+      ),
+      bossReplies: withoutKey(context.bossReplies, 'synthesizeCommit'),
+    })),
+    setPendingBossQuestion: assign(
+      (
+        { context, event },
+        params: { readonly stateId: ResumableStateId },
+      ) => {
+        const question = outputString(event, 'question');
+        if (question === undefined) return {};
+        const { sourceItem, roleId } = RESUMABLE_STATES[params.stateId];
+        const pending: PendingBossQuestion = {
+          questionId: params.stateId,
+          resumeStateId: params.stateId,
+          sourceItem,
+          asker: { kind: 'role', roleId },
+          question,
+        };
+        return {
+          pendingBossQuestions: {
+            ...context.pendingBossQuestions,
+            [params.stateId]: pending,
+          },
+          bossReplies: withoutKey(context.bossReplies, params.stateId),
+        };
       },
-      lastError: undefined,
-    }),
-    rememberActorError: assign({
-      lastError: ({ event }) =>
-        (event as unknown as ActorErrorEvent).error,
-    }),
-    rememberMalformedActorOutput: assign({
-      lastError: ({ event }) =>
-        (event as unknown as PlayerDoneEvent | PlaybookDoneEvent).output,
-    }),
-    rememberMalformedBossReply: assign({
-      lastError: ({ event }) => event,
-    }),
-    setPendingBossQuestion: assign({
-      pendingBossQuestions: (
+    ),
+    rememberBossReply: assign(
+      (
         { context, event },
-        params: PendingBossQuestionParams,
-      ) => ({
-        ...context.pendingBossQuestions,
-        [params.resumeStateId]: {
-          ...params,
-          questionId: params.resumeStateId,
-          question: outputOf(event).question ?? '',
-        },
-      }),
-      bossReplies: ({ context }, params: PendingBossQuestionParams) =>
-        withoutKey(context.bossReplies, params.resumeStateId),
-      lastResult: ({ event }) => outputOf(event),
-      lastError: undefined,
+        params: { readonly stateId: ResumableStateId },
+      ) =>
+        event.type === 'BOSS_REPLY'
+          ? {
+              bossReplies: {
+                ...context.bossReplies,
+                [params.stateId]: event.answer,
+              },
+            }
+          : {},
+    ),
+    rememberEmptyBossReply: assign({
+      lastError: {
+        name: 'MalformedBossReply',
+        message: 'BOSS_REPLY carried an empty answer.',
+      },
+      ...FAILURE_RESET,
     }),
-    rememberBossReply: assign({
-      bossReplies: ({ context, event }) => {
-        const questionId = resolvedQuestionId(context, event);
-        return event.type === 'BOSS_REPLY' && questionId
-          ? { ...context.bossReplies, [questionId]: event.answer }
-          : context.bossReplies;
+    rememberUnknownBossReply: assign({
+      lastError: {
+        name: 'MalformedBossReply',
+        message: 'BOSS_REPLY names no pending question.',
       },
-      lastError: undefined,
+      ...FAILURE_RESET,
     }),
-    clearBranchBossReplyContext: assign({
-      pendingBossQuestions: (
-        { context },
-        params: { stateId: ResumableStateId },
-      ) => withoutKey(context.pendingBossQuestions, params.stateId),
-      bossReplies: ({ context }, params: { stateId: ResumableStateId }) =>
-        withoutKey(context.bossReplies, params.stateId),
+    rememberMalformedPlayerOutput: assign(
+      ({ event }, params: { readonly sourceItem: DecideSourceItem }) => {
+        const output = actorOutput(event);
+        return {
+          lastError: {
+            name: 'MalformedPlayerOutput',
+            message:
+              output?.guard === 'needsBossReply'
+                ? `Player output for ${params.sourceItem} declared needsBossReply without a question.`
+                : `Player output for ${params.sourceItem} did not match an outcome declared for its state.`,
+          },
+          ...FAILURE_RESET,
+        };
+      },
+    ),
+    rememberActorError: assign(({ event }) => ({
+      lastError: errorRecord(actorError(event)),
+      ...FAILURE_RESET,
+    })),
+    rememberReviewApproval: assign(({ event }) => {
+      const approval = reviewApprovalFrom(event);
+      if (approval === undefined) return {};
+      const output = actorOutput(event);
+      const reviewEvidence: CompletedReviewResult = {
+        playbookId: REVIEW_PLAYBOOK_ID,
+        status: 'ok',
+        ...(isJsonValue(output) ? { output } : {}),
+      };
+      return {
+        evaluatedRevision: approval.evaluatedRevision,
+        reviewStatus: null,
+        reviewError: null,
+        reviewEvidence,
+        lastError: null,
+      };
     }),
-    clearProposalRoundContext: assign({
-      pendingBossQuestions: undefined,
-      bossReplies: undefined,
-      stagedCoderResult: undefined,
-      stagedReviewerResult: undefined,
+    rememberUnestablishedReview: assign(({ event }) => {
+      const output = actorOutput(event);
+      const reviewEvidence: CompletedReviewResult = {
+        playbookId: REVIEW_PLAYBOOK_ID,
+        status: 'ok',
+        ...(isJsonValue(output) ? { output } : {}),
+      };
+      return {
+        evaluatedRevision: '',
+        reviewStatus: 'error' as const,
+        reviewError: REVIEW_NOT_ESTABLISHED,
+        reviewEvidence,
+        lastError: null,
+      };
     }),
-    clearBossReplyContext: assign({
-      pendingBossQuestions: undefined,
-      bossReplies: undefined,
+    rememberAuthoredReviewFailure: assign(({ event }) => {
+      const failure = authoredReviewFailureOf(event);
+      return failure === undefined
+        ? {}
+        : {
+            evaluatedRevision: '',
+            reviewStatus: failure.status,
+            reviewError: failure.error,
+            reviewEvidence: failure.evidence,
+            lastError: null,
+          };
     }),
   },
-  guards: {
-    coderProposed,
-    reviewerProposed,
-    committed,
-    needsBossReplyWithQuestion,
-    needsBossReplyWithoutQuestion,
-    validReviewSuccess,
-    authoredReviewFailure,
-  },
 }).createMachine({
   id: 'decide',
+  description:
+    'DECIDE: independent Coder and Reviewer proposals, a synthesized decide-owned commit, and a nested review.',
   initial: 'ready',
-  context: (): DecideContext => ({}),
+  context: (): DecideContext => INITIAL_CONTEXT,
   output: ({ context }): DecideOutput => {
-    if (context.reviewResult) {
-      if (!context.latestCommit) {
-        throw new Error('DECIDE completed without its decide-owned commit');
-      }
+    const commit = context.decideCommit;
+    if (!isNonEmptyString(commit)) {
+      throw new Error(
+        'DECIDE reached a final state without its decide-owned commit',
+      );
+    }
+    if (context.reviewStatus !== null) {
       return {
-        decideCommit: context.latestCommit,
-        evaluatedRevision: context.reviewResult.evaluatedRevision,
-        noUnsettledFindings: true,
+        lastDecideCommit: commit,
+        noUnsettledFindings: false,
+        reviewStatus: context.reviewStatus,
+        ...(context.reviewError === null ? {} : { error: context.reviewError }),
       };
     }
-    if (!context.latestCommit || !context.reviewFailure) {
-      throw new Error('DECIDE reached a final state without a result');
+    const evaluatedRevision = context.evaluatedRevision;
+    if (!isNonEmptyString(evaluatedRevision)) {
+      throw new Error(
+        'DECIDE completed without the evaluated repository revision',
+      );
     }
     return {
-      lastDecideCommit: context.latestCommit,
-      noUnsettledFindings: false,
-      reviewStatus: context.reviewFailure.status,
-      ...(context.reviewFailure.error
-        ? { error: context.reviewFailure.error }
-        : {}),
+      decideCommit: commit,
+      evaluatedRevision,
+      noUnsettledFindings: true,
     };
   },
   on: {
-    BOSS_INTERRUPT: bossInterrupts(['independentProposals']),
+    BOSS_INTERRUPT: bossInterrupts([
+      'independentProposals',
+      'synthesizeCommit',
+    ] as const),
   },
   states: {
     ready: {
       id: 'ready',
-      tags: 'playbook.parked',
-      description: 'Waiting for a topic to decide.',
-      meta: {
-        playbook: {
-          stateId: 'ready',
-          description: 'Waiting for a topic to decide.',
-        },
-      },
+      description: STATE_DESCRIPTIONS.ready,
+      meta: playbookMeta('ready'),
+      tags: ['playbook.parked'],
       on: {
-        START_DECIDE: {
-          guard: ({ event }) => event.callerTopic.trim().length > 0,
-          target: 'independentProposals',
-          actions: 'copyStartTopic',
-        },
+        START_DECIDE: startDecideArm,
       },
     },
     independentProposals: {
       id: 'independentProposals',
+      description: STATE_DESCRIPTIONS.independentProposals,
+      meta: playbookMeta('independentProposals'),
       type: 'parallel',
-      description: 'Coder and Reviewer prepare independent proposals.',
-      meta: {
-        playbook: {
-          stateId: 'independentProposals',
-          description: 'Coder and Reviewer prepare independent proposals.',
-        },
-      },
+      // No group-level BOSS_REPLY handler: a reply is handled only by the
+      // branch wait whose pending question it names, and a reply naming no
+      // pending branch question moves no branch.
       states: {
-        coder: {
-          initial: 'working',
+        coderProposalRegion: {
+          id: 'coderProposalRegion',
+          description: STATE_DESCRIPTIONS.coderProposalRegion,
+          meta: playbookMeta('coderProposalRegion'),
+          initial: 'askCoderProposal',
           states: {
-            working: {
+            askCoderProposal: {
               id: 'askCoderProposal',
-              tags: 'playbook.busy',
-              description: 'Coder independently proposes a spec design.',
-              meta: {
-                playbook: {
-                  stateId: 'askCoderProposal',
-                  description: 'Coder independently proposes a spec design.',
-                  role: 'coder',
-                },
-              },
+              description: STATE_DESCRIPTIONS.askCoderProposal,
+              meta: playbookMeta('askCoderProposal', 'coder'),
+              tags: ['playbook.busy'],
               invoke: {
                 src: 'player',
-                input: ({ context }): PlayerInput => ({
+                input: ({ context }): CoderProposalInput => ({
                   stateId: 'askCoderProposal',
-                  sourceItem: 'DECIDE-1',
                   role: 'coder',
-                  prompt: INDEPENDENT_PROPOSAL_PROMPT,
-                  result: withNeedsBossReply({
-                    proposed:
-                      'Coder affirmatively provided a complete design proposal; a progress report, status update, or promise of a later proposal supports no proposal outcome. Output shall include `coderProposal: <verbatim final text>`.',
-                  }),
+                  sourceItem: 'DECIDE-1',
+                  prompt: CODER_PROPOSAL_PROMPT,
+                  result: CODER_PROPOSAL_RESULT,
                   callerTopic: context.callerTopic,
                   ...bossReplyFields(context, 'askCoderProposal'),
                 }),
                 onDone: [
+                  suspendArm('askCoderProposal', 'awaitCoderProposalReply'),
                   {
-                    guard: 'needsBossReplyWithQuestion',
-                    target: 'waiting',
-                    actions: [
-                      {
-                        type: 'playbook.acceptedOutcome',
-                        params: {
-                          source: 'askCoderProposal',
-                          target: 'waitCoderProposalReply',
-                          acceptedOutcome: 'needsBossReply',
-                        },
-                      },
-                      {
-                        type: 'setPendingBossQuestion',
-                        params: {
-                          ...stateMetadata.askCoderProposal,
-                          resumeStateId: 'askCoderProposal',
-                          question: '',
-                        },
-                      },
-                    ],
-                  },
-                  {
-                    guard: 'needsBossReplyWithoutQuestion',
-                    target: '#failed',
+                    guard: 'coderProposedJoining',
+                    target: 'coderProposalStaged',
                     actions: [
-                      'rememberMalformedActorOutput',
-                      'clearProposalRoundContext',
+                      acceptedOutcome(
+                        'askCoderProposal',
+                        'synthesizeCommit',
+                        'proposed',
+                      ),
+                      'stageCoderProposal',
                     ],
                   },
                   {
                     guard: 'coderProposed',
-                    target: 'complete',
+                    target: 'coderProposalStaged',
                     actions: [
-                      {
-                        type: 'playbook.acceptedOutcome',
-                        params: ({ context }) => ({
-                          source: 'askCoderProposal',
-                          target:
-                            context.stagedReviewerResult === undefined
-                              ? 'coderProposalComplete'
-                              : 'commitCoderProposal',
-                          acceptedOutcome: 'proposed',
-                        }),
-                      },
+                      acceptedOutcome(
+                        'askCoderProposal',
+                        'coderProposalStaged',
+                        'proposed',
+                      ),
                       'stageCoderProposal',
-                      {
-                        type: 'clearBranchBossReplyContext',
-                        params: { stateId: 'askCoderProposal' },
-                      },
-                    ],
-                  },
-                  {
-                    target: '#failed',
-                    actions: [
-                      'rememberMalformedActorOutput',
-                      'clearProposalRoundContext',
                     ],
                   },
+                  malformedPlayerOutputArm('DECIDE-1'),
                 ],
-                onError: {
-                  target: '#failed',
-                  actions: [
-                    'rememberActorError',
-                    'clearProposalRoundContext',
-                  ],
-                },
+                onError: playerOnError,
               },
             },
-            waiting: {
-              id: 'waitCoderProposalReply',
-              tags: 'playbook.parked',
-              description: 'Coder waits for Boss to answer a question.',
-              meta: {
-                playbook: {
-                  stateId: 'waitCoderProposalReply',
-                  description: 'Coder waits for Boss to answer a question.',
-                },
-              },
+            awaitCoderProposalReply: {
+              id: 'awaitCoderProposalReply',
+              description: STATE_DESCRIPTIONS.awaitCoderProposalReply,
+              meta: playbookMeta('awaitCoderProposalReply'),
+              tags: ['playbook.parked'],
               on: {
-                BOSS_REPLY: [
-                  {
-                    guard: bossReplyTargets('askCoderProposal', false),
-                    target: '#failed',
-                    actions: [
-                      'rememberMalformedBossReply',
-                      'clearProposalRoundContext',
-                    ],
-                  },
-                  {
-                    guard: bossReplyTargets('askCoderProposal', true),
-                    target: 'working',
-                    actions: 'rememberBossReply',
-                  },
-                ],
+                BOSS_REPLY: resumableStates(['askCoderProposal'] as const),
               },
             },
-            complete: {
+            coderProposalStaged: {
+              id: 'coderProposalStaged',
+              description: STATE_DESCRIPTIONS.coderProposalStaged,
+              meta: playbookMeta('coderProposalStaged'),
               type: 'final',
-              description: 'Coder proposal is staged for the parallel join.',
-              meta: {
-                playbook: {
-                  stateId: 'coderProposalComplete',
-                  description:
-                    'Coder proposal is staged for the parallel join.',
-                },
-              },
             },
           },
         },
-        reviewer: {
-          initial: 'working',
+        reviewerProposalRegion: {
+          id: 'reviewerProposalRegion',
+          description: STATE_DESCRIPTIONS.reviewerProposalRegion,
+          meta: playbookMeta('reviewerProposalRegion'),
+          initial: 'askReviewerProposal',
           states: {
-            working: {
+            askReviewerProposal: {
               id: 'askReviewerProposal',
-              tags: 'playbook.busy',
-              description: 'Reviewer independently proposes a spec design.',
-              meta: {
-                playbook: {
-                  stateId: 'askReviewerProposal',
-                  description:
-                    'Reviewer independently proposes a spec design.',
-                  role: 'reviewer',
-                },
-              },
+              description: STATE_DESCRIPTIONS.askReviewerProposal,
+              meta: playbookMeta('askReviewerProposal', 'reviewer'),
+              tags: ['playbook.busy'],
               invoke: {
                 src: 'player',
-                input: ({ context }): PlayerInput => ({
+                input: ({ context }): ReviewerProposalInput => ({
                   stateId: 'askReviewerProposal',
-                  sourceItem: 'DECIDE-2',
                   role: 'reviewer',
-                  prompt: INDEPENDENT_PROPOSAL_PROMPT,
-                  result: withNeedsBossReply({
-                    proposed:
-                      'Reviewer affirmatively provided a complete design proposal; a progress report, status update, or promise of a later proposal supports no proposal outcome. Output shall include `reviewerProposal: <verbatim final text>`.',
-                  }),
+                  sourceItem: 'DECIDE-2',
+                  prompt: REVIEWER_PROPOSAL_PROMPT,
+                  result: REVIEWER_PROPOSAL_RESULT,
                   callerTopic: context.callerTopic,
                   ...bossReplyFields(context, 'askReviewerProposal'),
                 }),
                 onDone: [
+                  suspendArm('askReviewerProposal', 'awaitReviewerProposalReply'),
                   {
-                    guard: 'needsBossReplyWithQuestion',
-                    target: 'waiting',
+                    guard: 'reviewerProposedJoining',
+                    target: 'reviewerProposalStaged',
                     actions: [
-                      {
-                        type: 'playbook.acceptedOutcome',
-                        params: {
-                          source: 'askReviewerProposal',
-                          target: 'waitReviewerProposalReply',
-                          acceptedOutcome: 'needsBossReply',
-                        },
-                      },
-                      {
-                        type: 'setPendingBossQuestion',
-                        params: {
-                          ...stateMetadata.askReviewerProposal,
-                          resumeStateId: 'askReviewerProposal',
-                          question: '',
-                        },
-                      },
-                    ],
-                  },
-                  {
-                    guard: 'needsBossReplyWithoutQuestion',
-                    target: '#failed',
-                    actions: [
-                      'rememberMalformedActorOutput',
-                      'clearProposalRoundContext',
+                      acceptedOutcome(
+                        'askReviewerProposal',
+                        'synthesizeCommit',
+                        'proposed',
+                      ),
+                      'stageReviewerProposal',
                     ],
                   },
                   {
                     guard: 'reviewerProposed',
-                    target: 'complete',
+                    target: 'reviewerProposalStaged',
                     actions: [
-                      {
-                        type: 'playbook.acceptedOutcome',
-                        params: ({ context }) => ({
-                          source: 'askReviewerProposal',
-                          target:
-                            context.stagedCoderResult === undefined
-                              ? 'reviewerProposalComplete'
-                              : 'commitCoderProposal',
-                          acceptedOutcome: 'proposed',
-                        }),
-                      },
+                      acceptedOutcome(
+                        'askReviewerProposal',
+                        'reviewerProposalStaged',
+                        'proposed',
+                      ),
                       'stageReviewerProposal',
-                      {
-                        type: 'clearBranchBossReplyContext',
-                        params: { stateId: 'askReviewerProposal' },
-                      },
-                    ],
-                  },
-                  {
-                    target: '#failed',
-                    actions: [
-                      'rememberMalformedActorOutput',
-                      'clearProposalRoundContext',
                     ],
                   },
+                  malformedPlayerOutputArm('DECIDE-2'),
                 ],
-                onError: {
-                  target: '#failed',
-                  actions: [
-                    'rememberActorError',
-                    'clearProposalRoundContext',
-                  ],
-                },
+                onError: playerOnError,
               },
             },
-            waiting: {
-              id: 'waitReviewerProposalReply',
-              tags: 'playbook.parked',
-              description: 'Reviewer waits for Boss to answer a question.',
-              meta: {
-                playbook: {
-                  stateId: 'waitReviewerProposalReply',
-                  description:
-                    'Reviewer waits for Boss to answer a question.',
-                },
-              },
+            awaitReviewerProposalReply: {
+              id: 'awaitReviewerProposalReply',
+              description: STATE_DESCRIPTIONS.awaitReviewerProposalReply,
+              meta: playbookMeta('awaitReviewerProposalReply'),
+              tags: ['playbook.parked'],
               on: {
-                BOSS_REPLY: [
-                  {
-                    guard: bossReplyTargets('askReviewerProposal', false),
-                    target: '#failed',
-                    actions: [
-                      'rememberMalformedBossReply',
-                      'clearProposalRoundContext',
-                    ],
-                  },
-                  {
-                    guard: bossReplyTargets('askReviewerProposal', true),
-                    target: 'working',
-                    actions: 'rememberBossReply',
-                  },
-                ],
+                BOSS_REPLY: resumableStates(['askReviewerProposal'] as const),
               },
             },
-            complete: {
+            reviewerProposalStaged: {
+              id: 'reviewerProposalStaged',
+              description: STATE_DESCRIPTIONS.reviewerProposalStaged,
+              meta: playbookMeta('reviewerProposalStaged'),
               type: 'final',
-              description:
-                'Reviewer proposal is staged for the parallel join.',
-              meta: {
-                playbook: {
-                  stateId: 'reviewerProposalComplete',
-                  description:
-                    'Reviewer proposal is staged for the parallel join.',
-                },
-              },
             },
           },
         },
       },
+      // The join: taken only after both regions reach final; it promotes both
+      // staged proposals atomically before DECIDE-3 begins.
       onDone: {
-        target: 'commitCoderProposal',
+        target: 'synthesizeCommit',
         actions: 'promoteProposals',
       },
     },
-    commitCoderProposal: {
-      id: 'commitCoderProposal',
-      tags: 'playbook.busy',
-      description: 'Coder synthesizes both proposals and commits the design.',
-      meta: {
-        playbook: {
-          stateId: 'commitCoderProposal',
-          description:
-            'Coder synthesizes both proposals and commits the design.',
-          role: 'coder',
-        },
-      },
+    synthesizeCommit: {
+      id: 'synthesizeCommit',
+      description: STATE_DESCRIPTIONS.synthesizeCommit,
+      meta: playbookMeta('synthesizeCommit', 'coder'),
+      tags: ['playbook.busy'],
       invoke: {
         src: 'player',
-        input: ({ context }): PlayerInput => ({
-          stateId: 'commitCoderProposal',
-          sourceItem: 'DECIDE-3',
+        input: ({ context }): SynthesizeCommitInput => ({
+          stateId: 'synthesizeCommit',
           role: 'coder',
+          sourceItem: 'DECIDE-3',
           prompt: SYNTHESIZE_COMMIT_PROMPT,
-          result: withNeedsBossReply({
-            committed:
-              'Coder synthesized both proposals and committed the resulting design as one new commit. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.',
-          }),
+          result: SYNTHESIZE_COMMIT_RESULT,
           callerTopic: context.callerTopic,
           reviewerProposal: context.reviewerProposal,
-          ...bossReplyFields(context, 'commitCoderProposal'),
+          ...bossReplyFields(context, 'synthesizeCommit'),
         }),
         onDone: [
-          {
-            guard: 'needsBossReplyWithQuestion',
-            target: 'awaitBossReply',
-            actions: [
-              {
-                type: 'playbook.acceptedOutcome',
-                params: {
-                  source: 'commitCoderProposal',
-                  target: 'awaitBossReply',
-                  acceptedOutcome: 'needsBossReply',
-                },
-              },
-              {
-                type: 'setPendingBossQuestion',
-                params: {
-                  ...stateMetadata.commitCoderProposal,
-                  resumeStateId: 'commitCoderProposal',
-                  question: '',
-                },
-              },
-            ],
-          },
-          {
-            guard: 'needsBossReplyWithoutQuestion',
-            target: 'failed',
-            actions: [
-              'rememberMalformedActorOutput',
-              'clearBossReplyContext',
-            ],
-          },
+          suspendArm('synthesizeCommit', 'awaitBossReply'),
           {
             guard: 'committed',
             target: 'reviewCommit',
             actions: [
-              {
-                type: 'playbook.acceptedOutcome',
-                params: {
-                  source: 'commitCoderProposal',
-                  target: 'reviewCommit',
-                  acceptedOutcome: 'committed',
-                },
-              },
+              acceptedOutcome('synthesizeCommit', 'reviewCommit', 'committed'),
               'rememberCommit',
-              {
-                type: 'clearBranchBossReplyContext',
-                params: { stateId: 'commitCoderProposal' },
-              },
-            ],
-          },
-          {
-            target: 'failed',
-            actions: [
-              'rememberMalformedActorOutput',
-              'clearBossReplyContext',
             ],
           },
+          malformedPlayerOutputArm('DECIDE-3'),
         ],
-        onError: {
-          target: 'failed',
-          actions: ['rememberActorError', 'clearBossReplyContext'],
-        },
+        onError: playerOnError,
       },
     },
     awaitBossReply: {
       id: 'awaitBossReply',
-      tags: 'playbook.parked',
-      description: 'Waiting for Boss to answer Coder’s question.',
-      meta: {
-        playbook: {
-          stateId: 'awaitBossReply',
-          description: 'Waiting for Boss to answer Coder’s question.',
-        },
-      },
+      description: STATE_DESCRIPTIONS.awaitBossReply,
+      meta: playbookMeta('awaitBossReply'),
+      tags: ['playbook.parked'],
       on: {
         BOSS_REPLY: [
-          {
-            guard: bossReplyTargets('commitCoderProposal', false),
-            target: 'failed',
-            actions: [
-              'rememberMalformedBossReply',
-              'clearBossReplyContext',
-            ],
-          },
-          ...resumableStates(['commitCoderProposal']),
+          unknownBossReplyArm,
+          ...resumableStates(['synthesizeCommit'] as const),
         ],
+        START_DECIDE: startDecideArm,
       },
     },
     reviewCommit: {
       id: 'reviewCommit',
-      tags: 'playbook.suspended',
-      description: 'REVIEW examines the committed proposal.',
-      meta: {
-        playbook: {
-          stateId: 'reviewCommit',
-          description: 'REVIEW examines the committed proposal.',
-        },
-      },
+      description: STATE_DESCRIPTIONS.reviewCommit,
+      meta: playbookMeta('reviewCommit'),
+      tags: ['playbook.suspended'],
       invoke: {
         src: 'playbook',
         input: ({ context }): PlaybookInput => ({
           stateId: 'reviewCommit',
           sourceItem: 'DECIDE-4',
-          playbookId: 'review',
-          text: composeReviewInput(
-            context.callerTopic,
-            context.latestCommit,
-            context.coderOutput,
-          ),
+          playbookId: REVIEW_PLAYBOOK_ID,
+          text: reviewCallText(context),
         }),
         onDone: [
           {
-            guard: 'validReviewSuccess',
+            guard: 'reviewApproved',
             target: 'done',
-            actions: 'rememberReviewSuccess',
+            actions: 'rememberReviewApproval',
           },
           {
             target: 'reportedReviewFailure',
-            actions: 'rememberReviewProtocolFailure',
+            actions: 'rememberUnestablishedReview',
           },
         ],
         onError: [
           {
             guard: 'authoredReviewFailure',
             target: 'reportedReviewFailure',
-            actions: 'rememberReviewFailure',
-          },
-          {
-            target: 'failed',
-            actions: 'rememberActorError',
+            actions: 'rememberAuthoredReviewFailure',
           },
+          { target: 'failed', actions: 'rememberActorError' },
         ],
       },
     },
     failed: {
       id: 'failed',
-      tags: 'playbook.parked',
-      description: 'DECIDE failed and is waiting for a new topic.',
-      meta: {
-        playbook: {
-          stateId: 'failed',
-          description: 'DECIDE failed and is waiting for a new topic.',
-        },
-      },
+      description: STATE_DESCRIPTIONS.failed,
+      meta: playbookMeta('failed'),
+      tags: ['playbook.parked'],
       on: {
-        START_DECIDE: {
-          guard: ({ event }) => event.callerTopic.trim().length > 0,
-          target: 'independentProposals',
-          actions: 'copyStartTopic',
-        },
+        START_DECIDE: startDecideArm,
       },
     },
     reportedReviewFailure: {
       id: 'reportedReviewFailure',
+      description: STATE_DESCRIPTIONS.reportedReviewFailure,
+      meta: terminalMeta('reportedReviewFailure', 'failure'),
       type: 'final',
-      description: 'DECIDE reports REVIEW’s failure and its last commit.',
-      meta: {
-        playbook: {
-          stateId: 'reportedReviewFailure',
-          description: 'DECIDE reports REVIEW’s failure and its last commit.',
-          // DR-048: this final state means the workflow failed, so a caller
-          // learns that from the machine rather than from DECIDE's output.
-          terminal: 'failure',
-        },
-      },
     },
     done: {
       id: 'done',
+      description: STATE_DESCRIPTIONS.done,
+      meta: terminalMeta('done', 'success'),
       type: 'final',
-      description: 'DECIDE completed with an approved commit.',
-      meta: {
-        playbook: {
-          stateId: 'done',
-          description: 'DECIDE completed with an approved commit.',
-          terminal: 'success',
-        },
-      },
     },
   },
 });