@sublang/playbook 15.0.0 → 16.0.0

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

@@ -1,9 +1,13 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 //
-// Generated by slc/gears2fsm.md from ./dev.gears.md.
+// FSM object artifact compiled from ./dev.gears.md by gears2fsm.
+// It defines only the machine, 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';
 
 export type JsonValue =
   | null
@@ -13,56 +17,59 @@ export type JsonValue =
   | readonly JsonValue[]
   | { readonly [key: string]: JsonValue };
 
-export type DevStateId =
-  | 'planAnalysis'
-  | 'createBranch'
+/** DEV declares no parallel group. */
+export const concurrentRoleSets: readonly (readonly string[])[] = [];
+
+export type DevRole = 'analyst';
+
+export type DevChildPlaybookId = 'code' | 'decide' | 'branch' | 'pr';
+
+export type DevCallStateId =
   | 'callCode'
   | 'callDecide'
   | 'callCodeAfterDecide'
+  | 'createBranch'
   | 'openPullRequest';
 
-export type DevSourceItem =
-  | 'DEV-1'
-  | 'DEV-2'
-  | 'DEV-3'
-  | 'DEV-4'
-  | 'DEV-5'
-  | 'DEV-6';
+export type DevCallSourceItem = 'DEV-2' | 'DEV-3' | 'DEV-4' | 'DEV-5' | 'DEV-6';
 
-export type DevChildPlaybookId = 'code' | 'decide' | 'branch' | 'pr';
+type ResumableStateId = 'planAnalysis';
 
 /**
- * DR-050: the development path a pull-request planning outcome selected. It
- * routes the `branch` success into `callCode` or `callDecide`, so the plain
- * `code` and `decide then code` paths keep their items, prompts, and edges.
+ * The development path a pull-request planning outcome selected. It routes
+ * the `branch` success into the `code` call (DEV-2) or the `decide` call
+ * (DEV-3); its absence means a plain path that calls neither `branch` nor `pr`.
  */
 export type DevPullRequestPath = 'code' | 'decide-then-code';
 
-export type PendingBossQuestion = {
-  readonly questionId: 'planAnalysis';
-  readonly resumeStateId: 'planAnalysis';
+export interface PendingBossQuestion {
+  readonly questionId: ResumableStateId;
+  readonly resumeStateId: ResumableStateId;
   readonly sourceItem: 'DEV-1';
-  readonly asker: { readonly kind: 'role'; readonly roleId: 'analyst' };
+  readonly asker: { readonly kind: 'role'; readonly roleId: DevRole };
   readonly question: string;
-};
+}
 
-export type DiscussionExchange = {
-  readonly question: string;
-  readonly answer: string;
-};
+type PendingBossQuestionParams = Omit<
+  PendingBossQuestion,
+  'questionId' | 'question'
+>;
 
-export type PlayerInput = {
-  readonly stateId: 'planAnalysis';
-  readonly role: 'analyst';
+export interface PlayerInput {
+  readonly stateId: ResumableStateId;
+  readonly role: DevRole;
   readonly sourceItem: 'DEV-1';
   readonly prompt: string;
   readonly result: Readonly<Record<string, string>>;
+  /** Substitutes `<development-request>`. */
   readonly developmentRequest: string;
+  /** Substitutes `<discussion-context>`. */
   readonly discussionContext: string;
+  /** Substitutes `<run-results>`. */
   readonly runResults: string;
   readonly pendingBossQuestion?: PendingBossQuestion;
   readonly bossReply?: string;
-};
+}
 
 export type PlayerOutput =
   | { readonly guard: 'discussionComplete' }
@@ -75,60 +82,29 @@ export type PlayerOutput =
     }
   | { readonly guard: 'needsBossReply'; readonly question: string };
 
-export type PlaybookInput = {
-  readonly stateId:
-    | 'createBranch'
-    | 'callCode'
-    | 'callDecide'
-    | 'callCodeAfterDecide'
-    | 'openPullRequest';
-  readonly sourceItem: 'DEV-2' | 'DEV-3' | 'DEV-4' | 'DEV-5' | 'DEV-6';
+export interface PlaybookInput {
+  readonly stateId: DevCallStateId;
+  readonly sourceItem: DevCallSourceItem;
   readonly playbookId: DevChildPlaybookId;
   readonly text: string;
-};
+}
 
-/**
- * The affirmative success proof DEV requires from `decide`'s canonical
- * structured terminal output before starting the dependent `code` call:
- * the `decide`-owned commit, the exact evaluated repository revision, and
- * the affirmative no-unsettled-findings fact. Additional members belong to
- * DECIDE's own contract and do not disprove success.
- */
-export type DecideSuccessOutput = {
-  readonly decideCommit: string;
-  readonly evaluatedRevision: string;
-  readonly noUnsettledFindings: true;
-};
+/** The child's JSON-safe machine output itself, delivered on `onDone`. */
+export type PlaybookOutput = JsonValue | undefined;
 
-/**
- * The fields DEV consumes from `branch`'s canonical structured terminal
- * output before continuing a pull-request path: the exact branch name, the
- * exact base revision, and the issue summary. Additional members belong to
- * BRANCH's own contract and do not disprove success; a missing member is an
- * insufficient result, never an empty default.
- */
-export type BranchSuccessOutput = {
-  readonly branch: string;
-  readonly baseRevision: string;
-  readonly issueSummary: string;
-};
-
-/**
- * The fields DEV consumes from `code`'s canonical structured terminal output
- * before starting the dependent `pr` call: the exact last `code`-owned commit
- * and the exact final evaluated repository revision.
- */
-export type CodeSuccessOutput = {
-  readonly lastCodeCommit: string;
-  readonly finalEvaluatedRevision: string;
-};
+export interface CompactError {
+  readonly name: string;
+  readonly message: string;
+}
 
-export type CompactError = {
+/** A control-plane error retained for inspection while DEV is parked. */
+export interface ControlError {
   readonly name: string;
   readonly message: string;
-};
+  readonly stack?: string;
+}
 
-/** Sanitized canonical child result relayed as DEV's own failure outcome. */
+/** Sanitized canonical child result that DEV relays as its own outcome. */
 export type CompletedChildResult =
   | {
       readonly playbookId: DevChildPlaybookId;
@@ -142,14 +118,12 @@ export type CompletedChildResult =
     };
 
 export type DevPlaybookOutput =
-  | {
-      readonly status: 'discussion-complete';
-    }
+  | { readonly status: 'discussion-complete' }
   | {
       readonly status: 'complete';
       /** The final child of the selected path: `pr` on a pull-request path. */
       readonly childPlaybookId: 'code' | 'pr';
-      /** The successful result of DEV's final child call, when it has one. */
+      /** The successful result of that final child call, when it has one. */
       readonly childOutput?: JsonValue;
     }
   | {
@@ -158,46 +132,50 @@ export type DevPlaybookOutput =
       readonly childResult: CompletedChildResult;
     };
 
-export type DevInput = {
+type DevCompletion =
+  | { readonly kind: 'discussion-complete' }
+  | {
+      readonly kind: 'complete';
+      readonly childPlaybookId: 'code' | 'pr';
+      readonly childOutput?: JsonValue;
+    }
+  | { readonly kind: 'child-failed'; readonly childResult: CompletedChildResult };
+
+export interface DevInput {
+  /** Optional seed for `<run-results>`; absent means no relevant run results. */
   readonly runResults?: string;
-};
+}
 
-export type DevContext = {
+export interface DevContext {
   readonly runResults: string;
   readonly developmentRequest?: string;
-  readonly discussionExchanges: readonly DiscussionExchange[];
+  /** Consumed Analyst Q&A for `<discussion-context>`; empty before any reply. */
+  readonly discussionContext: string;
   readonly planningResult?: string;
+  readonly pullRequestPath?: DevPullRequestPath;
   readonly decideCommit?: string;
   readonly evaluatedRevision?: string;
-  /** DR-050: whether the accepted planning outcome selected a pull-request path. */
-  readonly deliveryViaPullRequest: boolean;
-  readonly pullRequestPath?: DevPullRequestPath;
   readonly branch?: string;
   readonly baseRevision?: string;
   readonly issueSummary?: string;
   readonly lastCodeCommit?: string;
   readonly finalEvaluatedRevision?: string;
-  readonly completion?: 'discussion-complete' | 'complete' | 'child-failed';
-  readonly childOutput?: JsonValue;
-  readonly childFailure?: CompletedChildResult;
-  readonly lastError?: unknown;
+  readonly completion?: DevCompletion;
+  readonly lastError?: ControlError;
   readonly pendingBossQuestion?: PendingBossQuestion;
   readonly bossReply?: string;
-};
+}
 
 export type DevEvent =
   | { readonly type: 'START_DEV'; readonly developmentRequest: string }
   | {
       readonly type: 'BOSS_REPLY';
       readonly answer: string;
-      readonly questionId?: 'planAnalysis';
+      readonly questionId?: string;
     };
 
+// DEV-1: the item's blockquote, verbatim, with the outer GEARS marker removed.
 const PLAN_ANALYSIS_PROMPT = [
-  '> Original request: <development-request>',
-  '> Prior discussion: <discussion-context>',
-  '> Run results: <run-results>',
-  '',
   'Plan which playbooks run for this request; the playbooks do the work.',
   'Read the request, then the specs and the repository only as far as choosing the path requires.',
   'Do not change files or commit while planning or discussing the request.',
@@ -216,79 +194,112 @@ const PLAN_ANALYSIS_PROMPT = [
   'A question or exploratory discussion is not by itself authorization to create a durable decision or implement changes.',
   'Do not choose `decide then code` merely because the work is large, nor `code` merely because it is small.',
   'Consult @specs/map.md for relevant context and @specs/meta.md for spec requirements, if needed.',
+  '',
+  '> Original request: <development-request>',
+  '> Prior discussion: <discussion-context>',
+  '> Run results: <run-results>',
 ].join('\n');
 
-const PLAN_ANALYSIS_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>`.";
+
+// DEV-1 local result contract: the authored `Results:` bullets in declared
+// order, plus the universal Boss-reply suspension.
+const PLAN_ANALYSIS_RESULT = {
   discussionComplete:
-    'Analyst concluded the discussion after a Boss reply, with no repository work to follow.',
-  code:
-    'Analyst chose `code`: the existing decisions and spec items settle how the work is done. Output shall include `planningResult: <verbatim final text>`.',
+    'After a Boss reply that settles that no repository work should follow, Analyst concluded the discussion; dev completes without a child call or repository change.',
+  code: 'Analyst chose the code path because the existing decisions and spec items settle how the work is done. Output shall include `planningResult: <verbatim final text>`.',
   decideThenCode:
-    'Analyst chose `decide then code`: the work turns on a point the specs leave open or contradict. Output shall include `planningResult: <verbatim final text>`.',
+    'Analyst chose the decide then code path because the work turns on a rule, concept, term, shape, or trade-off the specs leave open or contradict. Output shall include `planningResult: <verbatim final text>`.',
   codeViaPullRequest:
-    'Analyst chose `code via pull request`: the existing decisions settle the work, and the request names a GitHub issue or explicitly asks for pull-request delivery. Output shall include `planningResult: <verbatim final text>`.',
+    'Analyst chose the code via pull request path because the existing decisions and spec items settle how the work is done and the request names a GitHub issue or explicitly asks for pull-request delivery. Output shall include `planningResult: <verbatim final text>`.',
   decideThenCodeViaPullRequest:
-    'Analyst chose `decide then code via pull request`: the work turns on a point the specs leave open or contradict, and the request names a GitHub issue or explicitly asks for pull-request delivery. Output shall include `planningResult: <verbatim final text>`.',
-  needsBossReply:
-    "The acting agent's prose surfaces a clarifying question for Boss that the agent cannot answer alone. Output shall include `question: <verbatim question text from the acting agent's prose>`.",
+    'Analyst chose the decide then code via pull request path because the work turns on a rule, concept, term, shape, or trade-off the specs leave open or contradict and the request names a GitHub issue or explicitly asks for pull-request delivery. Output shall include `planningResult: <verbatim final text>`.',
+  needsBossReply: NEEDS_BOSS_REPLY_DESCRIPTION,
 } as const;
 
+// DEV-2 and DEV-3 and DEV-5: identical composed blockquotes.
+const PLANNED_CALL_TEMPLATE = [
+  '> Original request: <development-request>',
+  '> Prior discussion: <discussion-context>',
+  '> Planning result: <planning-result>',
+] as const;
+
+// DEV-4.
+const CODE_AFTER_DECIDE_CALL_TEMPLATE = [
+  '> Original request: <development-request>',
+  '> Prior discussion: <discussion-context>',
+  '> Planning result: <planning-result>',
+  '> DECIDE commit: <decide-commit>',
+  '> Evaluated revision: <evaluated-revision>',
+] as const;
+
+// DEV-6.
+const PULL_REQUEST_CALL_TEMPLATE = [
+  '> Original request: <development-request>',
+  '> Issue summary: <issue-summary>',
+  '> Branch: <branch>',
+  '> Base revision: <base-revision>',
+  '> CODE commit: <last-code-commit>',
+  '> Evaluated revision: <final-evaluated-revision>',
+] as const;
+
 const STATE_DESCRIPTIONS = {
   ready: 'Waiting for a development request.',
-  planAnalysis: 'Analyst is choosing the development path.',
+  planAnalysis: 'Analyst chooses the development path in a short planning note.',
+  awaitBossReply: "Waiting for Boss to answer the acting agent's question.",
   createBranch:
-    'The BRANCH playbook is preparing the pull-request branch for the planned development path.',
-  callCode: 'The CODE playbook is implementing the planned development path.',
+    'The BRANCH playbook prepares the branch for the pull-request delivery path.',
+  callCode: 'The CODE playbook implements the planned development path.',
   callDecide:
-    'The DECIDE playbook is settling the durable decision the planned path requires.',
+    'The DECIDE playbook settles the decision the planned development path requires.',
   callCodeAfterDecide:
-    'The CODE playbook is implementing the decided development path.',
+    'The CODE playbook implements the development path DECIDE settled.',
   openPullRequest:
-    'The PR playbook is delivering the implemented branch through a pull request.',
-  awaitBossReply: 'Waiting for Boss to answer Analyst.',
+    'The PR playbook delivers the implemented branch through a pull request.',
   failed:
-    'The development planning workflow failed and is waiting for a new development request.',
+    'DEV failed outside a child result contract and waits for a new development request.',
   discussionComplete:
-    'The planning discussion concluded after a Boss reply with no repository work to follow.',
-  done: "The selected development path completed with the final child playbook's successful result.",
+    'After a Boss reply, the planning discussion concluded with no child call or repository change.',
+  done: "The selected development path completed with its final child playbook's successful result.",
   reportedChildFailure:
-    "The development workflow relayed a child playbook's authored abort, failure, or insufficient terminal result.",
+    "DEV ended by relaying a child playbook's authored abort, failure, or result that did not prove the required success.",
 } as const;
 
-function playbookMeta<StateId extends keyof typeof STATE_DESCRIPTIONS>(
-  stateId: StateId,
-  role?: 'analyst',
-) {
+type DevStateKey = keyof typeof STATE_DESCRIPTIONS;
+
+function playbookMeta<const Key extends DevStateKey>(stateId: Key) {
   return {
-    playbook: {
-      stateId,
-      description: STATE_DESCRIPTIONS[stateId],
-      ...(role === undefined ? {} : { role }),
-    },
-  };
+    playbook: { stateId, description: STATE_DESCRIPTIONS[stateId] },
+  } as const;
+}
+
+function roleMeta<const Key extends DevStateKey>(stateId: Key, role: DevRole) {
+  return {
+    playbook: { stateId, description: STATE_DESCRIPTIONS[stateId], role },
+  } as const;
 }
 
-// DR-048: a final state additionally declares whether its outcome means the
-// workflow succeeded or failed, so DEV's own caller learns that from the
-// machine rather than from DEV's output fields.
-function terminalMeta<StateId extends keyof typeof STATE_DESCRIPTIONS>(
-  stateId: StateId,
+function terminalMeta<const Key extends DevStateKey>(
+  stateId: Key,
   terminal: 'success' | 'failure',
 ) {
   return {
-    playbook: {
-      stateId,
-      description: STATE_DESCRIPTIONS[stateId],
-      terminal,
-    },
-  };
+    playbook: { stateId, description: STATE_DESCRIPTIONS[stateId], terminal },
+  } as const;
 }
 
+const PLAN_ANALYSIS_QUESTION: PendingBossQuestionParams = {
+  resumeStateId: 'planAnalysis',
+  sourceItem: 'DEV-1',
+  asker: { kind: 'role', roleId: 'analyst' },
+};
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   if (value === null || typeof value !== 'object' || Array.isArray(value)) {
     return false;
   }
-  const prototype = Object.getPrototypeOf(value);
+  const prototype: unknown = Object.getPrototypeOf(value);
   return prototype === Object.prototype || prototype === null;
 }
 
@@ -296,146 +307,147 @@ function isNonEmptyString(value: unknown): value is string {
   return typeof value === 'string' && value.trim().length > 0;
 }
 
-function playerOutput(event: unknown): Record<string, unknown> | undefined {
+// ---------------------------------------------------------------------------
+// Player output (DEV-1), narrowed structurally from an unknown done event.
+
+function playerOutputOf(event: unknown): Record<string, unknown> | undefined {
   if (!isRecord(event)) return undefined;
   return isRecord(event.output) ? event.output : undefined;
 }
 
-function outputGuard(event: unknown, guard: PlayerOutput['guard']): boolean {
-  return playerOutput(event)?.guard === guard;
+function hasGuard(event: unknown, guard: PlayerOutput['guard']): boolean {
+  return playerOutputOf(event)?.guard === guard;
 }
 
-function outputString(event: unknown, field: string): string | undefined {
-  const value = playerOutput(event)?.[field];
+function outputText(event: unknown, field: string): string | undefined {
+  const value = playerOutputOf(event)?.[field];
   return isNonEmptyString(value) ? value : undefined;
 }
 
-function isCodePath({ event }: { event: unknown }): boolean {
-  return (
-    outputGuard(event, 'code') &&
-    outputString(event, 'planningResult') !== undefined
-  );
-}
-
-function isDecideThenCode({ event }: { event: unknown }): boolean {
-  return (
-    outputGuard(event, 'decideThenCode') &&
-    outputString(event, 'planningResult') !== undefined
-  );
-}
-
-// DR-050: the two pull-request outcomes select the same development paths
-// as `code` and `decide then code`, entered through `branch` first.
-function isCodeViaPullRequest({ event }: { event: unknown }): boolean {
-  return (
-    outputGuard(event, 'codeViaPullRequest') &&
-    outputString(event, 'planningResult') !== undefined
-  );
+function plannedPath(
+  guard: 'code' | 'decideThenCode' | 'codeViaPullRequest' | 'decideThenCodeViaPullRequest',
+): (args: { event: unknown }) => boolean {
+  return ({ event }) =>
+    hasGuard(event, guard) && outputText(event, 'planningResult') !== undefined;
 }
 
-function isDecideThenCodeViaPullRequest({
+// Discussion complete is available only after a Boss reply: the Analyst
+// invocation that returns it must have been resumed with Boss's answer.
+function discussionCompleteAfterBossReply({
+  context,
   event,
 }: {
+  context: DevContext;
   event: unknown;
 }): boolean {
   return (
-    outputGuard(event, 'decideThenCodeViaPullRequest') &&
-    outputString(event, 'planningResult') !== undefined
+    hasGuard(event, 'discussionComplete') &&
+    context.pendingBossQuestion !== undefined &&
+    isNonEmptyString(context.bossReply)
   );
 }
 
-// Discussion complete is available only after a Boss reply: the round that
-// produced it must itself have been resumed with Boss's answer.
-function isDiscussionComplete({
-  context,
-  event,
-}: {
-  context: DevContext;
-  event: unknown;
-}): boolean {
+function needsBossReplyWithQuestion({ event }: { event: unknown }): boolean {
   return (
-    outputGuard(event, 'discussionComplete') &&
-    isNonEmptyString(context.bossReply)
+    hasGuard(event, 'needsBossReply') && outputText(event, 'question') !== undefined
   );
 }
 
-function needsBossReply({ event }: { event: unknown }): boolean {
+function needsBossReplyWithoutQuestion({ event }: { event: unknown }): boolean {
   return (
-    outputGuard(event, 'needsBossReply') &&
-    outputString(event, 'question') !== undefined
+    hasGuard(event, 'needsBossReply') && outputText(event, 'question') === undefined
   );
 }
 
-function childOutputOf(event: unknown): unknown {
-  return isRecord(event) ? event.output : undefined;
+// ---------------------------------------------------------------------------
+// Child outputs, read only from each child's canonical structured result and
+// checked against the packaged public output interfaces.
+
+function childOutputOf(event: unknown): PlaybookOutput {
+  return isRecord(event) ? (event.output as PlaybookOutput) : undefined;
 }
 
-function isDecideSuccessValue(value: unknown): value is DecideSuccessOutput {
-  return (
-    isRecord(value) &&
-    isNonEmptyString(value.decideCommit) &&
-    isNonEmptyString(value.evaluatedRevision) &&
-    value.noUnsettledFindings === true
-  );
+function childErrorOf(event: unknown): unknown {
+  return isRecord(event) ? event.error : undefined;
 }
 
-function isDecideSuccess({ event }: { event: unknown }): boolean {
-  return isDecideSuccessValue(childOutputOf(event));
+interface BranchSuccess {
+  readonly branch: string;
+  readonly baseRevision: string;
+  readonly issueSummary: string;
 }
 
-// BRANCH's canonical successful terminal output carries the exact name of
-// the new checked-out branch, the exact receipt-owned base revision, and the
-// issue summary; DEV consumes exactly those three by name and never defaults
-// a missing one.
-function isBranchSuccessValue(value: unknown): value is BranchSuccessOutput {
-  return (
-    isRecord(value) &&
-    isNonEmptyString(value.branch) &&
-    isNonEmptyString(value.baseRevision) &&
-    isNonEmptyString(value.issueSummary)
-  );
+function branchSuccessOf(value: unknown): BranchSuccess | undefined {
+  if (
+    !isRecord(value) ||
+    value.status !== 'branched' ||
+    !isNonEmptyString(value.branch) ||
+    !isNonEmptyString(value.baseRevision) ||
+    !isNonEmptyString(value.issueSummary)
+  ) {
+    return undefined;
+  }
+  return {
+    branch: value.branch,
+    baseRevision: value.baseRevision,
+    issueSummary: value.issueSummary,
+  };
 }
 
-function isBranchSuccessForCode({
-  context,
-  event,
-}: {
-  context: DevContext;
-  event: unknown;
-}): boolean {
-  return (
-    context.pullRequestPath === 'code' &&
-    isBranchSuccessValue(childOutputOf(event))
-  );
+interface DecideSuccess {
+  readonly decideCommit: string;
+  readonly evaluatedRevision: string;
 }
 
-function isBranchSuccessForDecide({
-  context,
-  event,
-}: {
-  context: DevContext;
-  event: unknown;
-}): boolean {
-  return (
-    context.pullRequestPath === 'decide-then-code' &&
-    isBranchSuccessValue(childOutputOf(event))
-  );
+function decideSuccessOf(value: unknown): DecideSuccess | undefined {
+  if (
+    !isRecord(value) ||
+    value.noUnsettledFindings !== true ||
+    !isNonEmptyString(value.decideCommit) ||
+    !isNonEmptyString(value.evaluatedRevision)
+  ) {
+    return undefined;
+  }
+  return {
+    decideCommit: value.decideCommit,
+    evaluatedRevision: value.evaluatedRevision,
+  };
 }
 
-// CODE's canonical successful terminal output discriminates completion with
-// `status: 'complete'`, carries the exact last CODE-owned commit, and
-// affirms that every phase's review passed.
-function isCodeSuccessValue(value: unknown): boolean {
-  return (
-    isRecord(value) &&
-    value.status === 'complete' &&
-    isNonEmptyString(value.lastCodeCommit) &&
-    value.allReviewsPassed === true
-  );
+interface CodeSuccess {
+  readonly lastCodeCommit: string;
+  readonly finalEvaluatedRevision: string;
+}
+
+function codeSuccessOf(value: unknown): CodeSuccess | undefined {
+  if (
+    !isRecord(value) ||
+    value.status !== 'complete' ||
+    value.allReviewsPassed !== true ||
+    !isNonEmptyString(value.lastCodeCommit) ||
+    !isNonEmptyString(value.finalEvaluatedRevision)
+  ) {
+    return undefined;
+  }
+  return {
+    lastCodeCommit: value.lastCodeCommit,
+    finalEvaluatedRevision: value.finalEvaluatedRevision,
+  };
+}
+
+function branchSucceededFor(
+  path: DevPullRequestPath,
+): (args: { context: DevContext; event: unknown }) => boolean {
+  return ({ context, event }) =>
+    context.pullRequestPath === path &&
+    branchSuccessOf(childOutputOf(event)) !== undefined;
 }
 
-// A plain path completes DEV on that proof alone, exactly as before DR-050.
-function isPlainCodeSuccess({
+function decideSucceeded({ event }: { event: unknown }): boolean {
+  return decideSuccessOf(childOutputOf(event)) !== undefined;
+}
+
+function codeSucceededOnPullRequestPath({
   context,
   event,
 }: {
@@ -443,25 +455,12 @@ function isPlainCodeSuccess({
   event: unknown;
 }): boolean {
   return (
-    context.deliveryViaPullRequest !== true &&
-    isCodeSuccessValue(childOutputOf(event))
-  );
-}
-
-// A pull-request path additionally consumes the exact final evaluated
-// repository revision for the `pr` call, so a CODE result lacking it does not
-// prove the success that path requires.
-function isCodeSuccessValueForPullRequest(
-  value: unknown,
-): value is CodeSuccessOutput & Record<string, unknown> {
-  return (
-    isCodeSuccessValue(value) &&
-    isRecord(value) &&
-    isNonEmptyString(value.finalEvaluatedRevision)
+    context.pullRequestPath !== undefined &&
+    codeSuccessOf(childOutputOf(event)) !== undefined
   );
 }
 
-function isCodeSuccessViaPullRequest({
+function codeSucceededOnPlainPath({
   context,
   event,
 }: {
@@ -469,249 +468,62 @@ function isCodeSuccessViaPullRequest({
   event: unknown;
 }): boolean {
   return (
-    context.deliveryViaPullRequest === true &&
-    isCodeSuccessValueForPullRequest(childOutputOf(event))
-  );
-}
-
-function isStateValue(value: unknown, ancestors = new Set<object>()): boolean {
-  if (typeof value === 'string') return true;
-  if (!isRecord(value) || ancestors.has(value)) return false;
-  const next = new Set(ancestors).add(value);
-  return Reflect.ownKeys(value).every(
-    (key) =>
-      typeof key === 'string' &&
-      Object.prototype.propertyIsEnumerable.call(value, key) &&
-      isStateValue(value[key], next),
-  );
-}
-
-function isStringArray(value: unknown): value is readonly string[] {
-  return (
-    Array.isArray(value) &&
-    Reflect.ownKeys(value).length === value.length + 1 &&
-    Reflect.ownKeys(value).every((key) => {
-      if (key === 'length') return true;
-      return (
-        typeof key === 'string' &&
-        /^(0|[1-9][0-9]*)$/.test(key) &&
-        Number(key) < value.length
-      );
-    }) &&
-    value.every((entry) => isNonEmptyString(entry)) &&
-    new Set(value).size === value.length
+    context.pullRequestPath === undefined &&
+    codeSuccessOf(childOutputOf(event)) !== undefined
   );
 }
 
-function isPlaybookState(value: unknown): boolean {
-  if (!isRecord(value)) return false;
-  const allowed = new Set([
-    'value',
-    'activeStateIds',
-    'tags',
-    'status',
-    'quiescent',
-    'stateId',
-  ]);
-  if (
-    Reflect.ownKeys(value).some(
-      (key) => typeof key !== 'string' || !allowed.has(key),
-    ) ||
-    !Object.prototype.hasOwnProperty.call(value, 'value') ||
-    !Object.prototype.hasOwnProperty.call(value, 'activeStateIds') ||
-    !Object.prototype.hasOwnProperty.call(value, 'tags') ||
-    !Object.prototype.hasOwnProperty.call(value, 'status') ||
-    !Object.prototype.hasOwnProperty.call(value, 'quiescent')
-  ) {
-    return false;
-  }
-  return (
-    isStateValue(value.value) &&
-    isStringArray(value.activeStateIds) &&
-    isStringArray(value.tags) &&
-    (value.status === 'active' ||
-      value.status === 'done' ||
-      value.status === 'error' ||
-      value.status === 'stopped') &&
-    typeof value.quiescent === 'boolean' &&
-    (!Object.prototype.hasOwnProperty.call(value, 'stateId') ||
-      (isNonEmptyString(value.stateId) &&
-        value.activeStateIds.length === 1 &&
-        value.activeStateIds[0] === value.stateId))
-  );
-}
+// ---------------------------------------------------------------------------
+// Authored rejected child results.
 
-function nestedResultFromError(
+export function authoredChildResult(
   error: unknown,
-): Record<string, unknown> | undefined {
+  expectedPlaybookId: string,
+): PlaybookCallResult | undefined {
   if (!(error instanceof Error)) return undefined;
-  const result = (error as Error & { readonly result?: unknown }).result;
-  return isRecord(result) ? result : undefined;
-}
-
-type AuthoredChildFailure =
-  | {
-      readonly status: 'aborted' | 'error';
-      readonly error?: CompactError;
-    }
-  // DR-048: a child that completed at an authored failure terminal. The
-  // bridge rejects it through the same error path, so DEV recognizes the
-  // failure from the child's own machine and never from its output fields.
-  | {
-      readonly status: 'ok';
-      readonly output?: JsonValue;
-    };
-
-function isFailureTerminalRecord(value: unknown): boolean {
-  if (!isRecord(value)) return false;
-  const allowed = new Set(['stateId', 'kind', 'description']);
-  return (
-    Reflect.ownKeys(value).every(
-      (key) => typeof key === 'string' && allowed.has(key),
-    ) &&
-    isNonEmptyString(value.stateId) &&
-    value.kind === 'failure' &&
-    (!Object.prototype.hasOwnProperty.call(value, 'description') ||
-      typeof value.description === 'string')
-  );
-}
-
-function normalizedChildFailure(
-  error: unknown,
-  playbookId: DevChildPlaybookId,
-): AuthoredChildFailure | undefined {
-  const result = nestedResultFromError(error);
-  if (result === undefined) return undefined;
-  const allowed = new Set([
-    'status',
-    'playbookId',
-    'childSessionId',
-    'state',
-    ...(result.status === 'ok' ? ['output', 'terminal'] : ['error']),
-  ]);
-  if (
-    Reflect.ownKeys(result).some(
-      (key) => typeof key !== 'string' || !allowed.has(key),
-    ) ||
-    (result.status !== 'aborted' &&
-      result.status !== 'error' &&
-      result.status !== 'ok') ||
-    result.playbookId !== playbookId
-  ) {
-    return undefined;
-  }
-  if (
-    Object.prototype.hasOwnProperty.call(result, 'childSessionId') &&
-    !isNonEmptyString(result.childSessionId)
-  ) {
-    return undefined;
-  }
-  if (result.status === 'ok') {
-    if (
-      !Object.prototype.hasOwnProperty.call(result, 'terminal') ||
-      !isFailureTerminalRecord(result.terminal) ||
-      !isNonEmptyString(result.childSessionId) ||
-      (Object.prototype.hasOwnProperty.call(result, 'state') &&
-        !isPlaybookState(result.state))
-    ) {
-      return undefined;
-    }
-    return {
-      status: 'ok',
-      ...(result.output === undefined
-        ? {}
-        : { output: result.output as JsonValue }),
-    };
-  }
-  if (
-    Object.prototype.hasOwnProperty.call(result, 'state') &&
-    !isPlaybookState(result.state)
-  ) {
-    return undefined;
-  }
-  let normalizedError: CompactError | undefined;
-  if (Object.prototype.hasOwnProperty.call(result, 'error')) {
-    if (!isRecord(result.error)) return undefined;
-    const errorKeys = Reflect.ownKeys(result.error);
-    if (
-      errorKeys.some(
-        (key) =>
-          typeof key !== 'string' ||
-          (key !== 'name' && key !== 'message' && key !== 'stack'),
-      ) ||
-      !Object.prototype.hasOwnProperty.call(result.error, 'name') ||
-      !Object.prototype.hasOwnProperty.call(result.error, 'message') ||
-      !isNonEmptyString(result.error.name) ||
-      typeof result.error.message !== 'string' ||
-      (Object.prototype.hasOwnProperty.call(result.error, 'stack') &&
-        typeof result.error.stack !== 'string')
-    ) {
-      return undefined;
-    }
-    normalizedError = {
-      name: result.error.name,
-      message: result.error.message,
-    };
-  } else if (result.status === 'error') {
+  try {
+    const result = validatePlaybookCallResult(
+      (error as Error & { result?: unknown }).result,
+      expectedPlaybookId,
+    );
+    return result.status !== 'ok' || result.terminal?.kind === 'failure'
+      ? result
+      : undefined;
+  } catch {
     return undefined;
   }
-  return {
-    status: result.status,
-    ...(normalizedError === undefined ? {} : { error: normalizedError }),
-  };
 }
 
-function authoredChildFailureGuard(
+function authoredResultFrom(
   playbookId: DevChildPlaybookId,
 ): (args: { event: unknown }) => boolean {
-  return ({ event }) => {
-    const error = isRecord(event) ? event.error : undefined;
-    return normalizedChildFailure(error, playbookId) !== undefined;
-  };
-}
-
-function authoredChildError(
-  event: unknown,
-  playbookId: DevChildPlaybookId,
-): CompactError {
-  const outer = isRecord(event) ? event.error : undefined;
-  const failure = normalizedChildFailure(outer, playbookId);
-  if (failure !== undefined && failure.status !== 'ok' && failure.error) {
-    return failure.error;
-  }
-  if (failure?.status === 'aborted') {
-    return {
-      name: 'AbortError',
-      message: `${playbookId.toUpperCase()} was aborted.`,
-    };
-  }
-  if (outer instanceof Error) {
-    return { name: outer.name || 'Error', message: outer.message };
-  }
-  return { name: 'Error', message: String(outer) };
+  return ({ event }) =>
+    authoredChildResult(childErrorOf(event), playbookId) !== undefined;
 }
 
-function relayedChildFailure(
+function relayedChildResult(
   event: unknown,
   playbookId: DevChildPlaybookId,
-): CompletedChildResult {
-  const outer = isRecord(event) ? event.error : undefined;
-  const failure = normalizedChildFailure(outer, playbookId);
-  // DR-048: a completed child that reached an authored failure terminal
-  // relays its own output, exactly as a terminal result that did not prove
-  // success did before it was routed through the error path.
-  if (failure?.status === 'ok') {
+): CompletedChildResult | undefined {
+  const result = authoredChildResult(childErrorOf(event), playbookId);
+  if (result === undefined) return undefined;
+  if (result.status === 'ok') {
+    // A child that completed at its own authored failure terminal relays its
+    // own output; an absent output is omitted rather than stored.
     return {
       playbookId,
       status: 'ok',
-      ...(failure.output === undefined ? {} : { output: failure.output }),
+      ...(result.output === undefined ? {} : { output: result.output }),
     };
   }
-  return {
-    playbookId,
-    status: failure?.status === 'aborted' ? 'aborted' : 'error',
-    error: authoredChildError(event, playbookId),
-  };
+  const error: CompactError =
+    result.error === undefined
+      ? {
+          name: 'AbortError',
+          message: `The ${playbookId} playbook call was aborted.`,
+        }
+      : { name: result.error.name, message: result.error.message };
+  return { playbookId, status: result.status, error };
 }
 
 function insufficientChildResult(
@@ -722,106 +534,140 @@ function insufficientChildResult(
   return {
     playbookId,
     status: 'ok',
-    ...(output === undefined ? {} : { output: output as JsonValue }),
+    ...(output === undefined ? {} : { output }),
   };
 }
 
-/** Consumed planning Q&A rendered for later relayed discussion context. */
-export function renderDiscussionContext(
-  exchanges: readonly DiscussionExchange[],
-): string {
-  return exchanges
-    .map(
-      (exchange) =>
-        `Analyst question: ${exchange.question}\nBoss reply: ${exchange.answer}`,
-    )
-    .join('\n\n');
+function normalizedControlError(error: unknown): ControlError {
+  if (error instanceof Error) {
+    return {
+      name: error.name.length > 0 ? error.name : 'Error',
+      message: error.message,
+      ...(typeof error.stack === 'string' ? { stack: error.stack } : {}),
+    };
+  }
+  return {
+    name: 'Error',
+    message: typeof error === 'string' ? error : 'Actor failed with a non-Error value.',
+  };
 }
 
-function archivedExchanges(
-  context: DevContext,
-): readonly DiscussionExchange[] {
+// ---------------------------------------------------------------------------
+// Discussion history and quoted-relay composition.
+
+/** One consumed Analyst question and Boss reply, as relayed discussion. */
+export function renderDiscussionExchange(question: string, answer: string): string {
+  return `Analyst question: ${question}\nBoss reply: ${answer}`;
+}
+
+// Persists the answered pending Q&A pair into the typed discussion context
+// before the pending fields are replaced or cleared, so later calls relay it.
+function archivedDiscussion(context: DevContext): string {
   if (
     context.pendingBossQuestion === undefined ||
     !isNonEmptyString(context.bossReply)
   ) {
-    return context.discussionExchanges;
+    return context.discussionContext;
   }
-  return [
-    ...context.discussionExchanges,
-    {
-      question: context.pendingBossQuestion.question,
-      answer: context.bossReply,
-    },
-  ];
+  const exchange = renderDiscussionExchange(
+    context.pendingBossQuestion.question,
+    context.bossReply,
+  );
+  return context.discussionContext.length > 0
+    ? `${context.discussionContext}\n\n${exchange}`
+    : exchange;
 }
 
-function quotedRelay(values: readonly (readonly [string, string])[]): string {
-  return values
-    .filter(([, value]) => value.length > 0)
-    .map(([label, value]) =>
-      `${label}: ${value}`
-        .split('\n')
-        .map((line) => `> ${line}`)
-        .join('\n'),
-    )
-    .join('\n');
-}
+const RELAY_TOKEN = /<[a-z][a-z0-9-]*>/g;
 
-function planningRelayValues(context: DevContext): readonly (readonly [string, string])[] {
-  return [
-    ['Original request', context.developmentRequest ?? ''],
-    ['Prior discussion', renderDiscussionContext(context.discussionExchanges)],
-    ['Planning result', context.planningResult ?? ''],
-  ];
+// Quoted-relay composition: an empty value contributes no line, every
+// continuation line of a multi-line value is quoted with `> ` (keeping LF/CRLF
+// separators), and no quoted line is inserted. Substitution is single-pass and
+// literal; a missing value keeps its placeholder literal.
+function composeRelay(
+  template: readonly string[],
+  values: Readonly<Record<string, string | undefined>>,
+): string {
+  const lines: string[] = [];
+  for (const line of template) {
+    const tokens = line.match(RELAY_TOKEN) ?? [];
+    if (tokens.some((token) => values[token] === '')) continue;
+    const composed = line.replace(RELAY_TOKEN, (token) => {
+      const value = values[token];
+      return value === undefined
+        ? token
+        : value.replace(/\r?\n/g, (separator) => `${separator}> `);
+    });
+    lines.push(composed);
+  }
+  return lines.join('\n');
 }
 
-function codeCallText(context: DevContext): string {
-  return quotedRelay(planningRelayValues(context));
+function plannedCallValues(
+  context: DevContext,
+): Readonly<Record<string, string | undefined>> {
+  return {
+    '<development-request>': context.developmentRequest,
+    '<discussion-context>': context.discussionContext,
+    '<planning-result>': context.planningResult,
+  };
 }
 
-function decideCallText(context: DevContext): string {
-  return quotedRelay(planningRelayValues(context));
+function plannedCallText(context: DevContext): string {
+  return composeRelay(PLANNED_CALL_TEMPLATE, plannedCallValues(context));
 }
 
 function codeAfterDecideCallText(context: DevContext): string {
-  return quotedRelay([
-    ...planningRelayValues(context),
-    ['DECIDE commit', context.decideCommit ?? ''],
-    ['Evaluated revision', context.evaluatedRevision ?? ''],
-  ]);
+  return composeRelay(CODE_AFTER_DECIDE_CALL_TEMPLATE, {
+    ...plannedCallValues(context),
+    '<decide-commit>': context.decideCommit,
+    '<evaluated-revision>': context.evaluatedRevision,
+  });
 }
 
-function branchCallText(context: DevContext): string {
-  return quotedRelay(planningRelayValues(context));
+function pullRequestCallText(context: DevContext): string {
+  return composeRelay(PULL_REQUEST_CALL_TEMPLATE, {
+    '<development-request>': context.developmentRequest,
+    '<issue-summary>': context.issueSummary,
+    '<branch>': context.branch,
+    '<base-revision>': context.baseRevision,
+    '<last-code-commit>': context.lastCodeCommit,
+    '<final-evaluated-revision>': context.finalEvaluatedRevision,
+  });
 }
 
-// DEV-6: every placeholder is substituted from typed context that only a
-// child's canonical structured result populated — never from player prose.
-function pullRequestCallText(context: DevContext): string {
-  return quotedRelay([
-    ['Original request', context.developmentRequest ?? ''],
-    ['Issue summary', context.issueSummary ?? ''],
-    ['Branch', context.branch ?? ''],
-    ['Base revision', context.baseRevision ?? ''],
-    ['CODE commit', context.lastCodeCommit ?? ''],
-    ['Evaluated revision', context.finalEvaluatedRevision ?? ''],
-  ]);
+// ---------------------------------------------------------------------------
+// Boss entry and reply surfaces.
+
+function startsDev({ event }: { event: DevEvent }): boolean {
+  return (
+    event.type === 'START_DEV' &&
+    typeof event.developmentRequest === 'string' &&
+    event.developmentRequest.trim().length > 0
+  );
 }
 
-function acceptedPlanningPath(
-  context: DevContext,
-  event: unknown,
-  pullRequestPath?: DevPullRequestPath,
+function emptyBossReply({ event }: { event: DevEvent }): boolean {
+  return (
+    event.type === 'BOSS_REPLY' &&
+    (typeof event.answer !== 'string' || event.answer.trim().length === 0)
+  );
+}
+
+function resumableStates<const Id extends ResumableStateId>(
+  ids: readonly Id[],
 ) {
-  return {
-    planningResult: outputString(event, 'planningResult'),
-    discussionExchanges: archivedExchanges(context),
-    deliveryViaPullRequest: pullRequestPath !== undefined,
-    pullRequestPath,
-    pendingBossQuestion: undefined,
-    bossReply: undefined,
-  };
+  return ids.map((id) => ({
+    guard: ({ context, event }: { context: DevContext; event: DevEvent }) =>
+      event.type === 'BOSS_REPLY' &&
+      typeof event.answer === 'string' &&
+      event.answer.trim().length > 0 &&
+      context.pendingBossQuestion?.resumeStateId === id &&
+      (event.questionId === undefined || event.questionId === id),
+    target: `#${id}` as const,
+    reenter: true as const,
+    actions: 'rememberBossReply' as const,
+  }));
 }
 
 const machineSetup = setup({
@@ -835,33 +681,31 @@ const machineSetup = 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: {
-    isDiscussionComplete,
-    isCodePath,
-    isDecideThenCode,
-    isCodeViaPullRequest,
-    isDecideThenCodeViaPullRequest,
-    needsBossReply,
-    isBranchSuccessForCode,
-    isBranchSuccessForDecide,
-    isCodeSuccessViaPullRequest,
-    isPlainCodeSuccess,
-    isDecideSuccess,
-    authoredBranchFailure: authoredChildFailureGuard('branch'),
-    authoredCodeFailure: authoredChildFailureGuard('code'),
-    authoredDecideFailure: authoredChildFailureGuard('decide'),
-    authoredPrFailure: authoredChildFailureGuard('pr'),
-    emptyBossReply: ({ event }) =>
-      event.type === 'BOSS_REPLY' && event.answer.trim().length === 0,
-    resumesPlanAnalysis: ({ context, event }) =>
-      event.type === 'BOSS_REPLY' &&
-      event.answer.trim().length > 0 &&
-      context.pendingBossQuestion?.resumeStateId === 'planAnalysis' &&
-      (event.questionId === undefined || event.questionId === 'planAnalysis'),
+    startsDev,
+    emptyBossReply,
+    discussionCompleteAfterBossReply,
+    codePlanned: plannedPath('code'),
+    decideThenCodePlanned: plannedPath('decideThenCode'),
+    codeViaPullRequestPlanned: plannedPath('codeViaPullRequest'),
+    decideThenCodeViaPullRequestPlanned: plannedPath(
+      'decideThenCodeViaPullRequest',
+    ),
+    needsBossReplyWithQuestion,
+    needsBossReplyWithoutQuestion,
+    branchSucceededForCode: branchSucceededFor('code'),
+    branchSucceededForDecide: branchSucceededFor('decide-then-code'),
+    decideSucceeded,
+    codeSucceededOnPullRequestPath,
+    codeSucceededOnPlainPath,
+    authoredBranchResult: authoredResultFrom('branch'),
+    authoredDecideResult: authoredResultFrom('decide'),
+    authoredCodeResult: authoredResultFrom('code'),
+    authoredPrResult: authoredResultFrom('pr'),
   },
   actions: {
     'playbook.acceptedOutcome': (
@@ -872,173 +716,154 @@ const machineSetup = setup({
         readonly acceptedOutcome: string;
       },
     ) => undefined,
-    startDev: assign(({ context, event }) => {
-      if (event.type !== 'START_DEV') return {};
-      return {
-        runResults: context.runResults,
-        developmentRequest: event.developmentRequest,
-        discussionExchanges: [] as readonly DiscussionExchange[],
-        planningResult: undefined,
-        decideCommit: undefined,
-        evaluatedRevision: undefined,
-        deliveryViaPullRequest: false,
-        pullRequestPath: undefined,
-        branch: undefined,
-        baseRevision: undefined,
-        issueSummary: undefined,
-        lastCodeCommit: undefined,
-        finalEvaluatedRevision: undefined,
-        completion: undefined,
-        childOutput: undefined,
-        childFailure: undefined,
-        lastError: undefined,
-        pendingBossQuestion: undefined,
-        bossReply: undefined,
-      };
-    }),
+    startDev: assign(({ event }) => ({
+      developmentRequest:
+        event.type === 'START_DEV' ? event.developmentRequest : undefined,
+      discussionContext: '',
+      planningResult: undefined,
+      pullRequestPath: undefined,
+      decideCommit: undefined,
+      evaluatedRevision: undefined,
+      branch: undefined,
+      baseRevision: undefined,
+      issueSummary: undefined,
+      lastCodeCommit: undefined,
+      finalEvaluatedRevision: undefined,
+      completion: undefined,
+      lastError: undefined,
+      pendingBossQuestion: undefined,
+      bossReply: undefined,
+    })),
     completeDiscussion: assign(({ context }) => ({
-      discussionExchanges: archivedExchanges(context),
-      completion: 'discussion-complete' as const,
+      discussionContext: archivedDiscussion(context),
+      completion: { kind: 'discussion-complete' } as const,
       pendingBossQuestion: undefined,
       bossReply: undefined,
     })),
-    rememberCodePath: assign(({ context, event }) =>
-      acceptedPlanningPath(context, event),
-    ),
-    rememberDecidePath: assign(({ context, event }) =>
-      acceptedPlanningPath(context, event),
-    ),
-    rememberCodeViaPullRequestPath: assign(({ context, event }) =>
-      acceptedPlanningPath(context, event, 'code'),
-    ),
-    rememberDecideThenCodeViaPullRequestPath: assign(({ context, event }) =>
-      acceptedPlanningPath(context, event, 'decide-then-code'),
+    acceptPlainPlan: assign(({ context, event }) => ({
+      planningResult: outputText(event, 'planningResult'),
+      discussionContext: archivedDiscussion(context),
+      pendingBossQuestion: undefined,
+      bossReply: undefined,
+    })),
+    acceptPullRequestPlan: assign(
+      ({ context, event }, params: { readonly path: DevPullRequestPath }) => ({
+        planningResult: outputText(event, 'planningResult'),
+        pullRequestPath: params.path,
+        discussionContext: archivedDiscussion(context),
+        pendingBossQuestion: undefined,
+        bossReply: undefined,
+      }),
     ),
-    rememberPendingQuestion: assign(({ context, event }) => {
-      const question = outputString(event, 'question');
-      if (question === undefined || !outputGuard(event, 'needsBossReply')) {
-        return { lastError: new Error('Analyst question output was malformed') };
-      }
-      return {
-        discussionExchanges: archivedExchanges(context),
+    setPendingBossQuestion: assign(
+      ({ context, event }, params: PendingBossQuestionParams) => ({
+        discussionContext: archivedDiscussion(context),
         pendingBossQuestion: {
-          questionId: 'planAnalysis' as const,
-          resumeStateId: 'planAnalysis' as const,
-          sourceItem: 'DEV-1' as const,
-          asker: { kind: 'role' as const, roleId: 'analyst' as const },
-          question,
+          ...params,
+          questionId: params.resumeStateId,
+          question: outputText(event, 'question') ?? '',
         },
         bossReply: undefined,
-      };
-    }),
+      }),
+    ),
     rememberBossReply: assign(({ event }) =>
       event.type === 'BOSS_REPLY' ? { bossReply: event.answer } : {},
     ),
-    rememberEmptyBossReplyError: assign({
-      lastError: () => new Error('BOSS_REPLY received an empty answer'),
+    clearBossReplyContext: assign({
       pendingBossQuestion: undefined,
       bossReply: undefined,
     }),
     rememberBranchResult: assign(({ event }) => {
-      const output = childOutputOf(event);
-      if (!isBranchSuccessValue(output)) return {};
-      return {
-        branch: output.branch,
-        baseRevision: output.baseRevision,
-        issueSummary: output.issueSummary,
-      };
+      const success = branchSuccessOf(childOutputOf(event));
+      return success === undefined ? {} : { ...success };
     }),
     rememberDecideResult: assign(({ event }) => {
-      const output = childOutputOf(event);
-      if (!isDecideSuccessValue(output)) return {};
-      return {
-        decideCommit: output.decideCommit,
-        evaluatedRevision: output.evaluatedRevision,
-      };
+      const success = decideSuccessOf(childOutputOf(event));
+      return success === undefined ? {} : { ...success };
     }),
     rememberCodeResult: assign(({ event }) => {
-      const output = childOutputOf(event);
-      if (!isCodeSuccessValueForPullRequest(output)) return {};
-      return {
-        lastCodeCommit: output.lastCodeCommit,
-        finalEvaluatedRevision: output.finalEvaluatedRevision,
-      };
+      const success = codeSuccessOf(childOutputOf(event));
+      return success === undefined ? {} : { ...success };
     }),
-    completeWithChildSuccess: assign(({ event }) => {
-      const output = childOutputOf(event);
-      return {
-        completion: 'complete' as const,
-        ...(output === undefined ? {} : { childOutput: output as JsonValue }),
-      };
-    }),
-    completeWithInsufficientBranchResult: assign(({ event }) => ({
-      completion: 'child-failed' as const,
-      childFailure: insufficientChildResult(event, 'branch'),
-    })),
-    completeWithInsufficientCodeResult: assign(({ event }) => ({
-      completion: 'child-failed' as const,
-      childFailure: insufficientChildResult(event, 'code'),
-    })),
-    completeWithInsufficientDecideResult: assign(({ event }) => ({
-      completion: 'child-failed' as const,
-      childFailure: insufficientChildResult(event, 'decide'),
-    })),
-    completeWithBranchFailure: assign(({ event }) => ({
-      completion: 'child-failed' as const,
-      childFailure: relayedChildFailure(event, 'branch'),
-    })),
-    completeWithCodeFailure: assign(({ event }) => ({
-      completion: 'child-failed' as const,
-      childFailure: relayedChildFailure(event, 'code'),
-    })),
-    completeWithDecideFailure: assign(({ event }) => ({
-      completion: 'child-failed' as const,
-      childFailure: relayedChildFailure(event, 'decide'),
-    })),
-    completeWithPrFailure: assign(({ event }) => ({
-      completion: 'child-failed' as const,
-      childFailure: relayedChildFailure(event, 'pr'),
-    })),
+    completeWithChildSuccess: assign(
+      ({ event }, params: { readonly childPlaybookId: 'code' | 'pr' }) => {
+        const output = childOutputOf(event);
+        return {
+          completion: {
+            kind: 'complete',
+            childPlaybookId: params.childPlaybookId,
+            ...(output === undefined ? {} : { childOutput: output }),
+          } as const,
+        };
+      },
+    ),
+    completeWithInsufficientResult: assign(
+      ({ event }, params: { readonly playbookId: DevChildPlaybookId }) => ({
+        completion: {
+          kind: 'child-failed',
+          childResult: insufficientChildResult(event, params.playbookId),
+        } as const,
+      }),
+    ),
+    completeWithAuthoredChildResult: assign(
+      ({ event }, params: { readonly playbookId: DevChildPlaybookId }) => {
+        const childResult = relayedChildResult(event, params.playbookId);
+        return childResult === undefined
+          ? {}
+          : { completion: { kind: 'child-failed', childResult } as const };
+      },
+    ),
     rememberActorError: assign(({ event }) => ({
-      lastError: (event as unknown as { readonly error?: unknown }).error,
+      lastError: normalizedControlError(childErrorOf(event)),
     })),
     rememberMalformedPlayerOutput: assign({
-      lastError: () =>
-        new Error('Analyst result for DEV-1 did not match an available outcome.'),
+      lastError: {
+        name: 'MalformedActorOutput',
+        message:
+          'Analyst output for DEV-1 did not match an available declared result.',
+      },
+      pendingBossQuestion: undefined,
+      bossReply: undefined,
+    }),
+    rememberMalformedBossReply: assign({
+      lastError: {
+        name: 'MalformedBossReply',
+        message: 'BOSS_REPLY carried an empty or whitespace-only answer.',
+      },
+      pendingBossQuestion: undefined,
+      bossReply: undefined,
     }),
   },
 });
 
 export const devMachine = machineSetup.createMachine({
   id: 'dev',
+  description:
+    'Plans the development path for a request and runs the child playbooks it selects.',
   initial: 'ready',
-  context: ({ input }) => ({
-    runResults: typeof input.runResults === 'string' ? input.runResults : '',
-    discussionExchanges: [],
-    deliveryViaPullRequest: false,
+  context: ({ input }): DevContext => ({
+    runResults: typeof input?.runResults === 'string' ? input.runResults : '',
+    discussionContext: '',
   }),
   output: ({ context }): DevPlaybookOutput => {
-    if (context.completion === 'discussion-complete') {
-      return { status: 'discussion-complete' };
+    const completion = context.completion;
+    if (completion === undefined) {
+      throw new Error('DEV reached a final state without a recorded completion');
     }
-    if (context.completion === 'complete') {
-      return {
-        status: 'complete',
-        // `done` is entered by `pr` on a pull-request path and by `code` on a
-        // plain path; no other arm completes the workflow.
-        childPlaybookId: context.deliveryViaPullRequest ? 'pr' : 'code',
-        ...(context.childOutput === undefined
-          ? {}
-          : { childOutput: context.childOutput }),
-      };
-    }
-    if (context.completion === 'child-failed') {
-      if (context.childFailure === undefined) {
-        throw new Error('DEV reached a final state without a child result');
-      }
-      return { status: 'child-failed', childResult: context.childFailure };
+    switch (completion.kind) {
+      case 'discussion-complete':
+        return { status: 'discussion-complete' };
+      case 'complete':
+        return {
+          status: 'complete',
+          childPlaybookId: completion.childPlaybookId,
+          ...(completion.childOutput === undefined
+            ? {}
+            : { childOutput: completion.childOutput }),
+        };
+      case 'child-failed':
+        return { status: 'child-failed', childResult: completion.childResult };
     }
-    throw new Error('DEV reached a final state without a recorded completion');
   },
   states: {
     ready: {
@@ -1047,13 +872,17 @@ export const devMachine = machineSetup.createMachine({
       meta: playbookMeta('ready'),
       tags: ['playbook.parked'],
       on: {
-        START_DEV: { target: 'planAnalysis', actions: 'startDev' },
+        START_DEV: {
+          guard: 'startsDev',
+          target: 'planAnalysis',
+          actions: 'startDev',
+        },
       },
     },
     planAnalysis: {
       id: 'planAnalysis',
       description: STATE_DESCRIPTIONS.planAnalysis,
-      meta: playbookMeta('planAnalysis', 'analyst'),
+      meta: roleMeta('planAnalysis', 'analyst'),
       tags: ['playbook.busy'],
       invoke: {
         src: 'player',
@@ -1062,11 +891,9 @@ export const devMachine = machineSetup.createMachine({
           role: 'analyst',
           sourceItem: 'DEV-1',
           prompt: PLAN_ANALYSIS_PROMPT,
-          result: PLAN_ANALYSIS_RESULTS,
+          result: PLAN_ANALYSIS_RESULT,
           developmentRequest: context.developmentRequest ?? '',
-          discussionContext: renderDiscussionContext(
-            context.discussionExchanges,
-          ),
+          discussionContext: context.discussionContext,
           runResults: context.runResults,
           ...(context.pendingBossQuestion === undefined
             ? {}
@@ -1077,7 +904,27 @@ export const devMachine = machineSetup.createMachine({
         }),
         onDone: [
           {
-            guard: 'isDiscussionComplete',
+            guard: 'needsBossReplyWithQuestion',
+            target: 'awaitBossReply',
+            actions: [
+              {
+                type: 'playbook.acceptedOutcome',
+                params: {
+                  source: 'planAnalysis',
+                  target: 'awaitBossReply',
+                  acceptedOutcome: 'needsBossReply',
+                },
+              },
+              { type: 'setPendingBossQuestion', params: PLAN_ANALYSIS_QUESTION },
+            ],
+          },
+          {
+            guard: 'needsBossReplyWithoutQuestion',
+            target: 'failed',
+            actions: 'rememberMalformedPlayerOutput',
+          },
+          {
+            guard: 'discussionCompleteAfterBossReply',
             target: 'discussionComplete',
             actions: [
               {
@@ -1092,7 +939,7 @@ export const devMachine = machineSetup.createMachine({
             ],
           },
           {
-            guard: 'isCodePath',
+            guard: 'codePlanned',
             target: 'callCode',
             actions: [
               {
@@ -1103,11 +950,11 @@ export const devMachine = machineSetup.createMachine({
                   acceptedOutcome: 'code',
                 },
               },
-              'rememberCodePath',
+              'acceptPlainPlan',
             ],
           },
           {
-            guard: 'isDecideThenCode',
+            guard: 'decideThenCodePlanned',
             target: 'callDecide',
             actions: [
               {
@@ -1118,11 +965,11 @@ export const devMachine = machineSetup.createMachine({
                   acceptedOutcome: 'decideThenCode',
                 },
               },
-              'rememberDecidePath',
+              'acceptPlainPlan',
             ],
           },
           {
-            guard: 'isCodeViaPullRequest',
+            guard: 'codeViaPullRequestPlanned',
             target: 'createBranch',
             actions: [
               {
@@ -1133,11 +980,11 @@ export const devMachine = machineSetup.createMachine({
                   acceptedOutcome: 'codeViaPullRequest',
                 },
               },
-              'rememberCodeViaPullRequestPath',
+              { type: 'acceptPullRequestPlan', params: { path: 'code' } },
             ],
           },
           {
-            guard: 'isDecideThenCodeViaPullRequest',
+            guard: 'decideThenCodeViaPullRequestPlanned',
             target: 'createBranch',
             actions: [
               {
@@ -1148,22 +995,10 @@ export const devMachine = machineSetup.createMachine({
                   acceptedOutcome: 'decideThenCodeViaPullRequest',
                 },
               },
-              'rememberDecideThenCodeViaPullRequestPath',
-            ],
-          },
-          {
-            guard: 'needsBossReply',
-            target: 'awaitBossReply',
-            actions: [
               {
-                type: 'playbook.acceptedOutcome',
-                params: {
-                  source: 'planAnalysis',
-                  target: 'awaitBossReply',
-                  acceptedOutcome: 'needsBossReply',
-                },
+                type: 'acceptPullRequestPlan',
+                params: { path: 'decide-then-code' },
               },
-              'rememberPendingQuestion',
             ],
           },
           {
@@ -1171,7 +1006,31 @@ export const devMachine = machineSetup.createMachine({
             actions: 'rememberMalformedPlayerOutput',
           },
         ],
-        onError: { target: 'failed', actions: 'rememberActorError' },
+        onError: {
+          target: 'failed',
+          actions: ['rememberActorError', 'clearBossReplyContext'],
+        },
+      },
+    },
+    awaitBossReply: {
+      id: 'awaitBossReply',
+      description: STATE_DESCRIPTIONS.awaitBossReply,
+      meta: playbookMeta('awaitBossReply'),
+      tags: ['playbook.parked'],
+      on: {
+        BOSS_REPLY: [
+          {
+            guard: 'emptyBossReply',
+            target: 'failed',
+            actions: 'rememberMalformedBossReply',
+          },
+          ...resumableStates(['planAnalysis']),
+        ],
+        START_DEV: {
+          guard: 'startsDev',
+          target: 'planAnalysis',
+          actions: 'startDev',
+        },
       },
     },
     createBranch: {
@@ -1185,29 +1044,35 @@ export const devMachine = machineSetup.createMachine({
           stateId: 'createBranch',
           sourceItem: 'DEV-5',
           playbookId: 'branch',
-          text: branchCallText(context),
+          text: plannedCallText(context),
         }),
         onDone: [
           {
-            guard: 'isBranchSuccessForCode',
+            guard: 'branchSucceededForCode',
             target: 'callCode',
             actions: 'rememberBranchResult',
           },
           {
-            guard: 'isBranchSuccessForDecide',
+            guard: 'branchSucceededForDecide',
             target: 'callDecide',
             actions: 'rememberBranchResult',
           },
           {
             target: 'reportedChildFailure',
-            actions: 'completeWithInsufficientBranchResult',
+            actions: {
+              type: 'completeWithInsufficientResult',
+              params: { playbookId: 'branch' },
+            },
           },
         ],
         onError: [
           {
-            guard: 'authoredBranchFailure',
+            guard: 'authoredBranchResult',
             target: 'reportedChildFailure',
-            actions: 'completeWithBranchFailure',
+            actions: {
+              type: 'completeWithAuthoredChildResult',
+              params: { playbookId: 'branch' },
+            },
           },
           { target: 'failed', actions: 'rememberActorError' },
         ],
@@ -1224,29 +1089,38 @@ export const devMachine = machineSetup.createMachine({
           stateId: 'callCode',
           sourceItem: 'DEV-2',
           playbookId: 'code',
-          text: codeCallText(context),
+          text: plannedCallText(context),
         }),
         onDone: [
           {
-            guard: 'isCodeSuccessViaPullRequest',
+            guard: 'codeSucceededOnPullRequestPath',
             target: 'openPullRequest',
             actions: 'rememberCodeResult',
           },
           {
-            guard: 'isPlainCodeSuccess',
+            guard: 'codeSucceededOnPlainPath',
             target: 'done',
-            actions: 'completeWithChildSuccess',
+            actions: {
+              type: 'completeWithChildSuccess',
+              params: { childPlaybookId: 'code' },
+            },
           },
           {
             target: 'reportedChildFailure',
-            actions: 'completeWithInsufficientCodeResult',
+            actions: {
+              type: 'completeWithInsufficientResult',
+              params: { playbookId: 'code' },
+            },
           },
         ],
         onError: [
           {
-            guard: 'authoredCodeFailure',
+            guard: 'authoredCodeResult',
             target: 'reportedChildFailure',
-            actions: 'completeWithCodeFailure',
+            actions: {
+              type: 'completeWithAuthoredChildResult',
+              params: { playbookId: 'code' },
+            },
           },
           { target: 'failed', actions: 'rememberActorError' },
         ],
@@ -1263,24 +1137,30 @@ export const devMachine = machineSetup.createMachine({
           stateId: 'callDecide',
           sourceItem: 'DEV-3',
           playbookId: 'decide',
-          text: decideCallText(context),
+          text: plannedCallText(context),
         }),
         onDone: [
           {
-            guard: 'isDecideSuccess',
+            guard: 'decideSucceeded',
             target: 'callCodeAfterDecide',
             actions: 'rememberDecideResult',
           },
           {
             target: 'reportedChildFailure',
-            actions: 'completeWithInsufficientDecideResult',
+            actions: {
+              type: 'completeWithInsufficientResult',
+              params: { playbookId: 'decide' },
+            },
           },
         ],
         onError: [
           {
-            guard: 'authoredDecideFailure',
+            guard: 'authoredDecideResult',
             target: 'reportedChildFailure',
-            actions: 'completeWithDecideFailure',
+            actions: {
+              type: 'completeWithAuthoredChildResult',
+              params: { playbookId: 'decide' },
+            },
           },
           { target: 'failed', actions: 'rememberActorError' },
         ],
@@ -1301,25 +1181,34 @@ export const devMachine = machineSetup.createMachine({
         }),
         onDone: [
           {
-            guard: 'isCodeSuccessViaPullRequest',
+            guard: 'codeSucceededOnPullRequestPath',
             target: 'openPullRequest',
             actions: 'rememberCodeResult',
           },
           {
-            guard: 'isPlainCodeSuccess',
+            guard: 'codeSucceededOnPlainPath',
             target: 'done',
-            actions: 'completeWithChildSuccess',
+            actions: {
+              type: 'completeWithChildSuccess',
+              params: { childPlaybookId: 'code' },
+            },
           },
           {
             target: 'reportedChildFailure',
-            actions: 'completeWithInsufficientCodeResult',
+            actions: {
+              type: 'completeWithInsufficientResult',
+              params: { playbookId: 'code' },
+            },
           },
         ],
         onError: [
           {
-            guard: 'authoredCodeFailure',
+            guard: 'authoredCodeResult',
             target: 'reportedChildFailure',
-            actions: 'completeWithCodeFailure',
+            actions: {
+              type: 'completeWithAuthoredChildResult',
+              params: { playbookId: 'code' },
+            },
           },
           { target: 'failed', actions: 'rememberActorError' },
         ],
@@ -1338,67 +1227,58 @@ export const devMachine = machineSetup.createMachine({
           playbookId: 'pr',
           text: pullRequestCallText(context),
         }),
-        // DR-048: `pr` declares its terminal kinds, so `onDone` alone proves
-        // its success; DEV consumes none of its fields by name.
-        onDone: { target: 'done', actions: 'completeWithChildSuccess' },
+        // `pr` success completes DEV with that result; a `pr` failure
+        // terminal arrives through `onError` and is relayed below.
+        onDone: {
+          target: 'done',
+          actions: {
+            type: 'completeWithChildSuccess',
+            params: { childPlaybookId: 'pr' },
+          },
+        },
         onError: [
           {
-            guard: 'authoredPrFailure',
+            guard: 'authoredPrResult',
             target: 'reportedChildFailure',
-            actions: 'completeWithPrFailure',
+            actions: {
+              type: 'completeWithAuthoredChildResult',
+              params: { playbookId: 'pr' },
+            },
           },
           { target: 'failed', actions: 'rememberActorError' },
         ],
       },
     },
-    awaitBossReply: {
-      id: 'awaitBossReply',
-      description: STATE_DESCRIPTIONS.awaitBossReply,
-      meta: playbookMeta('awaitBossReply'),
-      tags: ['playbook.parked'],
-      on: {
-        BOSS_REPLY: [
-          {
-            guard: 'emptyBossReply',
-            target: '#failed',
-            actions: 'rememberEmptyBossReplyError',
-          },
-          {
-            guard: 'resumesPlanAnalysis',
-            target: '#planAnalysis',
-            reenter: true,
-            actions: 'rememberBossReply',
-          },
-        ],
-        START_DEV: { target: 'planAnalysis', actions: 'startDev' },
-      },
-    },
     failed: {
       id: 'failed',
       description: STATE_DESCRIPTIONS.failed,
       meta: playbookMeta('failed'),
       tags: ['playbook.parked'],
       on: {
-        START_DEV: { target: 'planAnalysis', actions: 'startDev' },
+        START_DEV: {
+          guard: 'startsDev',
+          target: 'planAnalysis',
+          actions: 'startDev',
+        },
       },
     },
     discussionComplete: {
       id: 'discussionComplete',
+      type: 'final',
       description: STATE_DESCRIPTIONS.discussionComplete,
       meta: terminalMeta('discussionComplete', 'success'),
-      type: 'final',
     },
     done: {
       id: 'done',
+      type: 'final',
       description: STATE_DESCRIPTIONS.done,
       meta: terminalMeta('done', 'success'),
-      type: 'final',
     },
     reportedChildFailure: {
       id: 'reportedChildFailure',
+      type: 'final',
       description: STATE_DESCRIPTIONS.reportedChildFailure,
       meta: terminalMeta('reportedChildFailure', 'failure'),
-      type: 'final',
     },
   },
 });