@sublang/playbook 11.0.0 → 12.0.0

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

@@ -0,0 +1,988 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+//
+// Generated by slc/gears2fsm.md from ./dev.gears.md.
+
+import { assign, fromPromise, setup } from 'xstate';
+
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | readonly JsonValue[]
+  | { readonly [key: string]: JsonValue };
+
+export type DevStateId =
+  | 'planAnalysis'
+  | 'callCode'
+  | 'callDecide'
+  | 'callCodeAfterDecide';
+
+export type DevSourceItem = 'DEV-1' | 'DEV-2' | 'DEV-3' | 'DEV-4';
+
+export type DevChildPlaybookId = 'code' | 'decide';
+
+export type PendingBossQuestion = {
+  readonly questionId: 'planAnalysis';
+  readonly resumeStateId: 'planAnalysis';
+  readonly sourceItem: 'DEV-1';
+  readonly asker: { readonly kind: 'role'; readonly roleId: 'analyst' };
+  readonly question: string;
+};
+
+export type DiscussionExchange = {
+  readonly question: string;
+  readonly answer: string;
+};
+
+export type PlayerInput = {
+  readonly stateId: 'planAnalysis';
+  readonly role: 'analyst';
+  readonly sourceItem: 'DEV-1';
+  readonly prompt: string;
+  readonly result: Readonly<Record<string, string>>;
+  readonly developmentRequest: string;
+  readonly discussionContext: string;
+  readonly runResults: string;
+  readonly pendingBossQuestion?: PendingBossQuestion;
+  readonly bossReply?: string;
+};
+
+export type PlayerOutput =
+  | { readonly guard: 'discussionComplete' }
+  | { readonly guard: 'code'; readonly planningResult: string }
+  | { readonly guard: 'decideThenCode'; readonly planningResult: string }
+  | { readonly guard: 'needsBossReply'; readonly question: string };
+
+export type PlaybookInput = {
+  readonly stateId: 'callCode' | 'callDecide' | 'callCodeAfterDecide';
+  readonly sourceItem: 'DEV-2' | 'DEV-3' | 'DEV-4';
+  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;
+};
+
+export type CompactError = {
+  readonly name: string;
+  readonly message: string;
+};
+
+/** Sanitized canonical child result relayed as DEV's own failure outcome. */
+export type CompletedChildResult =
+  | {
+      readonly playbookId: DevChildPlaybookId;
+      readonly status: 'ok';
+      readonly output?: JsonValue;
+    }
+  | {
+      readonly playbookId: DevChildPlaybookId;
+      readonly status: 'aborted' | 'error';
+      readonly error: CompactError;
+    };
+
+export type DevPlaybookOutput =
+  | {
+      readonly status: 'discussion-complete';
+    }
+  | {
+      readonly status: 'complete';
+      readonly childPlaybookId: 'code';
+      /** The successful result of DEV's final child call, when it has one. */
+      readonly childOutput?: JsonValue;
+    }
+  | {
+      readonly status: 'child-failed';
+      /** The relayed canonical child result that ended the selected path. */
+      readonly childResult: CompletedChildResult;
+    };
+
+export type DevInput = {
+  readonly runResults?: string;
+};
+
+export type DevContext = {
+  readonly runResults: string;
+  readonly developmentRequest?: string;
+  readonly discussionExchanges: readonly DiscussionExchange[];
+  readonly planningResult?: string;
+  readonly decideCommit?: string;
+  readonly evaluatedRevision?: string;
+  readonly completion?: 'discussion-complete' | 'complete' | 'child-failed';
+  readonly childOutput?: JsonValue;
+  readonly childFailure?: CompletedChildResult;
+  readonly lastError?: unknown;
+  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';
+    };
+
+const PLAN_ANALYSIS_PROMPT = [
+  '> <development-request>',
+  '> <discussion-context>',
+  '> <run-results>',
+  '',
+  'Inspect the request and the relevant repository and specs only as needed to determine the smallest sound next step.',
+  'Do not change files or commit while planning or discussing the request.',
+  '',
+  '- If useful analysis or clarification should be discussed before any repository work, give Boss the useful response and ask one material question that advances the decision.',
+  '- If the discussion has concluded after a Boss reply and no repository work should follow, choose `discussion complete`.',
+  '- If implementation can proceed under the existing decisions, choose `code`.',
+  '- If implementation first requires a new or amended durable decision that the existing specs do not settle, choose `decide then code`.',
+  '',
+  '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.',
+  'Consult @specs/map.md for relevant context and @specs/meta.md for spec requirements, if needed.',
+].join('\n');
+
+const PLAN_ANALYSIS_RESULTS = {
+  discussionComplete:
+    'Analyst concluded the discussion after a Boss reply, with no repository work to follow.',
+  code:
+    'Analyst determined implementation can proceed under the existing decisions. Output shall include `planningResult: <verbatim final text>`.',
+  decideThenCode:
+    'Analyst determined implementation first requires a new or amended durable decision that the existing specs do not settle. 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>`.",
+} as const;
+
+const STATE_DESCRIPTIONS = {
+  ready: 'Waiting for a development request.',
+  planAnalysis:
+    'Analyst is analyzing the development request to choose the smallest sound next step.',
+  callCode: 'The CODE playbook is implementing the planned development path.',
+  callDecide:
+    'The DECIDE playbook is settling the durable decision the planned path requires.',
+  callCodeAfterDecide:
+    'The CODE playbook is implementing the decided development path.',
+  awaitBossReply: 'Waiting for Boss to answer Analyst.',
+  failed:
+    'The development planning workflow failed and is waiting 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.",
+  reportedChildFailure:
+    "The development workflow relayed a child playbook's authored abort, failure, or insufficient terminal result.",
+} as const;
+
+function playbookMeta<StateId extends keyof typeof STATE_DESCRIPTIONS>(
+  stateId: StateId,
+  role?: 'analyst',
+) {
+  return {
+    playbook: {
+      stateId,
+      description: STATE_DESCRIPTIONS[stateId],
+      ...(role === undefined ? {} : { role }),
+    },
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function playerOutput(event: unknown): Record<string, unknown> | undefined {
+  if (!isRecord(event)) return undefined;
+  return isRecord(event.output) ? event.output : undefined;
+}
+
+function outputGuard(event: unknown, guard: PlayerOutput['guard']): boolean {
+  return playerOutput(event)?.guard === guard;
+}
+
+function outputString(event: unknown, field: string): string | undefined {
+  const value = playerOutput(event)?.[field];
+  return isNonEmptyString(value) ? value : undefined;
+}
+
+function 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
+  );
+}
+
+// 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 {
+  return (
+    outputGuard(event, 'discussionComplete') &&
+    isNonEmptyString(context.bossReply)
+  );
+}
+
+function needsBossReply({ event }: { event: unknown }): boolean {
+  return (
+    outputGuard(event, 'needsBossReply') &&
+    outputString(event, 'question') !== undefined
+  );
+}
+
+function childOutputOf(event: unknown): unknown {
+  return isRecord(event) ? event.output : undefined;
+}
+
+function isDecideSuccessValue(value: unknown): value is DecideSuccessOutput {
+  return (
+    isRecord(value) &&
+    isNonEmptyString(value.decideCommit) &&
+    isNonEmptyString(value.evaluatedRevision) &&
+    value.noUnsettledFindings === true
+  );
+}
+
+function isDecideSuccess({ event }: { event: unknown }): boolean {
+  return isDecideSuccessValue(childOutputOf(event));
+}
+
+// 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
+  );
+}
+
+function isCodeSuccess({ event }: { event: unknown }): boolean {
+  return isCodeSuccessValue(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
+  );
+}
+
+function isPlaybookState(value: unknown): boolean {
+  if (!isRecord(value)) return false;
+  const allowed = new Set([
+    'value',
+    'activeStateIds',
+    'tags',
+    'status',
+    'quiescent',
+    'stateId',
+  ]);
+  if (
+    Reflect.ownKeys(value).some(
+      (key) => typeof key !== 'string' || !allowed.has(key),
+    ) ||
+    !Object.prototype.hasOwnProperty.call(value, 'value') ||
+    !Object.prototype.hasOwnProperty.call(value, 'activeStateIds') ||
+    !Object.prototype.hasOwnProperty.call(value, 'tags') ||
+    !Object.prototype.hasOwnProperty.call(value, 'status') ||
+    !Object.prototype.hasOwnProperty.call(value, 'quiescent')
+  ) {
+    return false;
+  }
+  return (
+    isStateValue(value.value) &&
+    isStringArray(value.activeStateIds) &&
+    isStringArray(value.tags) &&
+    (value.status === 'active' ||
+      value.status === 'done' ||
+      value.status === 'error' ||
+      value.status === 'stopped') &&
+    typeof value.quiescent === 'boolean' &&
+    (!Object.prototype.hasOwnProperty.call(value, 'stateId') ||
+      (isNonEmptyString(value.stateId) &&
+        value.activeStateIds.length === 1 &&
+        value.activeStateIds[0] === value.stateId))
+  );
+}
+
+function nestedResultFromError(
+  error: unknown,
+): Record<string, unknown> | undefined {
+  if (!(error instanceof Error)) return undefined;
+  const result = (error as Error & { readonly result?: unknown }).result;
+  return isRecord(result) ? result : undefined;
+}
+
+type AuthoredChildFailure = {
+  readonly status: 'aborted' | 'error';
+  readonly error?: CompactError;
+};
+
+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',
+    'error',
+  ]);
+  if (
+    Reflect.ownKeys(result).some(
+      (key) => typeof key !== 'string' || !allowed.has(key),
+    ) ||
+    (result.status !== 'aborted' && result.status !== 'error') ||
+    result.playbookId !== playbookId
+  ) {
+    return undefined;
+  }
+  if (
+    Object.prototype.hasOwnProperty.call(result, 'childSessionId') &&
+    !isNonEmptyString(result.childSessionId)
+  ) {
+    return undefined;
+  }
+  if (
+    Object.prototype.hasOwnProperty.call(result, 'state') &&
+    !isPlaybookState(result.state)
+  ) {
+    return undefined;
+  }
+  let normalizedError: CompactError | undefined;
+  if (Object.prototype.hasOwnProperty.call(result, 'error')) {
+    if (!isRecord(result.error)) return undefined;
+    const errorKeys = Reflect.ownKeys(result.error);
+    if (
+      errorKeys.some(
+        (key) =>
+          typeof key !== 'string' ||
+          (key !== 'name' && key !== 'message' && key !== 'stack'),
+      ) ||
+      !Object.prototype.hasOwnProperty.call(result.error, 'name') ||
+      !Object.prototype.hasOwnProperty.call(result.error, 'message') ||
+      !isNonEmptyString(result.error.name) ||
+      typeof result.error.message !== 'string' ||
+      (Object.prototype.hasOwnProperty.call(result.error, 'stack') &&
+        typeof result.error.stack !== 'string')
+    ) {
+      return undefined;
+    }
+    normalizedError = {
+      name: result.error.name,
+      message: result.error.message,
+    };
+  } else if (result.status === 'error') {
+    return undefined;
+  }
+  return {
+    status: result.status,
+    ...(normalizedError === undefined ? {} : { error: normalizedError }),
+  };
+}
+
+function authoredChildFailureGuard(
+  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?.error !== undefined) 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) };
+}
+
+function relayedChildFailure(
+  event: unknown,
+  playbookId: DevChildPlaybookId,
+): CompletedChildResult {
+  const outer = isRecord(event) ? event.error : undefined;
+  const failure = normalizedChildFailure(outer, playbookId);
+  return {
+    playbookId,
+    status: failure?.status ?? 'error',
+    error: authoredChildError(event, playbookId),
+  };
+}
+
+function insufficientChildResult(
+  event: unknown,
+  playbookId: DevChildPlaybookId,
+): CompletedChildResult {
+  const output = childOutputOf(event);
+  return {
+    playbookId,
+    status: 'ok',
+    ...(output === undefined ? {} : { output: output as JsonValue }),
+  };
+}
+
+/** 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 archivedExchanges(
+  context: DevContext,
+): readonly DiscussionExchange[] {
+  if (
+    context.pendingBossQuestion === undefined ||
+    !isNonEmptyString(context.bossReply)
+  ) {
+    return context.discussionExchanges;
+  }
+  return [
+    ...context.discussionExchanges,
+    {
+      question: context.pendingBossQuestion.question,
+      answer: context.bossReply,
+    },
+  ];
+}
+
+function quotedRelay(values: readonly string[]): string {
+  return values
+    .filter((value) => value.length > 0)
+    .map((value) =>
+      value
+        .split('\n')
+        .map((line) => `> ${line}`)
+        .join('\n'),
+    )
+    .join('\n');
+}
+
+function planningRelayValues(context: DevContext): readonly string[] {
+  return [
+    context.developmentRequest ?? '',
+    renderDiscussionContext(context.discussionExchanges),
+    context.planningResult ?? '',
+  ];
+}
+
+function codeCallText(context: DevContext): string {
+  return quotedRelay(planningRelayValues(context));
+}
+
+function decideCallText(context: DevContext): string {
+  return quotedRelay(planningRelayValues(context));
+}
+
+function codeAfterDecideCallText(context: DevContext): string {
+  return quotedRelay([
+    ...planningRelayValues(context),
+    context.decideCommit ?? '',
+    context.evaluatedRevision ?? '',
+  ]);
+}
+
+const machineSetup = setup({
+  types: {} as {
+    context: DevContext;
+    events: DevEvent;
+    input: DevInput;
+    output: DevPlaybookOutput;
+  },
+  actors: {
+    player: fromPromise<PlayerOutput, PlayerInput>(async () => {
+      throw new Error('player actor must be provided by the runner');
+    }),
+    playbook: fromPromise<JsonValue | undefined, PlaybookInput>(async () => {
+      throw new Error('playbook actor must be provided by the runner');
+    }),
+  },
+  guards: {
+    isDiscussionComplete,
+    isCodePath,
+    isDecideThenCode,
+    needsBossReply,
+    isCodeSuccess,
+    isDecideSuccess,
+    authoredCodeFailure: authoredChildFailureGuard('code'),
+    authoredDecideFailure: authoredChildFailureGuard('decide'),
+    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'),
+  },
+  actions: {
+    'playbook.acceptedOutcome': (
+      _args,
+      _params: {
+        readonly source: string;
+        readonly target: string;
+        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,
+        completion: undefined,
+        childOutput: undefined,
+        childFailure: undefined,
+        lastError: undefined,
+        pendingBossQuestion: undefined,
+        bossReply: undefined,
+      };
+    }),
+    completeDiscussion: assign(({ context }) => ({
+      discussionExchanges: archivedExchanges(context),
+      completion: 'discussion-complete' as const,
+      pendingBossQuestion: undefined,
+      bossReply: undefined,
+    })),
+    rememberCodePath: assign(({ context, event }) => ({
+      planningResult: outputString(event, 'planningResult'),
+      discussionExchanges: archivedExchanges(context),
+      pendingBossQuestion: undefined,
+      bossReply: undefined,
+    })),
+    rememberDecidePath: assign(({ context, event }) => ({
+      planningResult: outputString(event, 'planningResult'),
+      discussionExchanges: archivedExchanges(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),
+        pendingBossQuestion: {
+          questionId: 'planAnalysis' as const,
+          resumeStateId: 'planAnalysis' as const,
+          sourceItem: 'DEV-1' as const,
+          asker: { kind: 'role' as const, roleId: 'analyst' as const },
+          question,
+        },
+        bossReply: undefined,
+      };
+    }),
+    rememberBossReply: assign(({ event }) =>
+      event.type === 'BOSS_REPLY' ? { bossReply: event.answer } : {},
+    ),
+    rememberEmptyBossReplyError: assign({
+      lastError: () => new Error('BOSS_REPLY received an empty answer'),
+      pendingBossQuestion: undefined,
+      bossReply: undefined,
+    }),
+    rememberDecideResult: assign(({ event }) => {
+      const output = childOutputOf(event);
+      if (!isDecideSuccessValue(output)) return {};
+      return {
+        decideCommit: output.decideCommit,
+        evaluatedRevision: output.evaluatedRevision,
+      };
+    }),
+    completeWithChildSuccess: assign(({ event }) => {
+      const output = childOutputOf(event);
+      return {
+        completion: 'complete' as const,
+        ...(output === undefined ? {} : { childOutput: output as JsonValue }),
+      };
+    }),
+    completeWithInsufficientCodeResult: assign(({ event }) => ({
+      completion: 'child-failed' as const,
+      childFailure: insufficientChildResult(event, 'code'),
+    })),
+    completeWithInsufficientDecideResult: assign(({ event }) => ({
+      completion: 'child-failed' as const,
+      childFailure: insufficientChildResult(event, 'decide'),
+    })),
+    completeWithCodeFailure: assign(({ event }) => ({
+      completion: 'child-failed' as const,
+      childFailure: relayedChildFailure(event, 'code'),
+    })),
+    completeWithDecideFailure: assign(({ event }) => ({
+      completion: 'child-failed' as const,
+      childFailure: relayedChildFailure(event, 'decide'),
+    })),
+    rememberActorError: assign(({ event }) => ({
+      lastError: (event as unknown as { readonly error?: unknown }).error,
+    })),
+    rememberMalformedPlayerOutput: assign({
+      lastError: () =>
+        new Error('Analyst result for DEV-1 did not match an available outcome.'),
+    }),
+  },
+});
+
+export const devMachine = machineSetup.createMachine({
+  id: 'dev',
+  initial: 'ready',
+  context: ({ input }) => ({
+    runResults: typeof input.runResults === 'string' ? input.runResults : '',
+    discussionExchanges: [],
+  }),
+  output: ({ context }): DevPlaybookOutput => {
+    if (context.completion === 'discussion-complete') {
+      return { status: 'discussion-complete' };
+    }
+    if (context.completion === 'complete') {
+      return {
+        status: 'complete',
+        childPlaybookId: '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 };
+    }
+    throw new Error('DEV reached a final state without a recorded completion');
+  },
+  states: {
+    ready: {
+      id: 'ready',
+      description: STATE_DESCRIPTIONS.ready,
+      meta: playbookMeta('ready'),
+      tags: ['playbook.parked'],
+      on: {
+        START_DEV: { target: 'planAnalysis', actions: 'startDev' },
+      },
+    },
+    planAnalysis: {
+      id: 'planAnalysis',
+      description: STATE_DESCRIPTIONS.planAnalysis,
+      meta: playbookMeta('planAnalysis', 'analyst'),
+      tags: ['playbook.busy'],
+      invoke: {
+        src: 'player',
+        input: ({ context }): PlayerInput => ({
+          stateId: 'planAnalysis',
+          role: 'analyst',
+          sourceItem: 'DEV-1',
+          prompt: PLAN_ANALYSIS_PROMPT,
+          result: PLAN_ANALYSIS_RESULTS,
+          developmentRequest: context.developmentRequest ?? '',
+          discussionContext: renderDiscussionContext(
+            context.discussionExchanges,
+          ),
+          runResults: context.runResults,
+          ...(context.pendingBossQuestion === undefined
+            ? {}
+            : { pendingBossQuestion: context.pendingBossQuestion }),
+          ...(context.bossReply === undefined
+            ? {}
+            : { bossReply: context.bossReply }),
+        }),
+        onDone: [
+          {
+            guard: 'isDiscussionComplete',
+            target: 'discussionComplete',
+            actions: [
+              {
+                type: 'playbook.acceptedOutcome',
+                params: {
+                  source: 'planAnalysis',
+                  target: 'discussionComplete',
+                  acceptedOutcome: 'discussionComplete',
+                },
+              },
+              'completeDiscussion',
+            ],
+          },
+          {
+            guard: 'isCodePath',
+            target: 'callCode',
+            actions: [
+              {
+                type: 'playbook.acceptedOutcome',
+                params: {
+                  source: 'planAnalysis',
+                  target: 'callCode',
+                  acceptedOutcome: 'code',
+                },
+              },
+              'rememberCodePath',
+            ],
+          },
+          {
+            guard: 'isDecideThenCode',
+            target: 'callDecide',
+            actions: [
+              {
+                type: 'playbook.acceptedOutcome',
+                params: {
+                  source: 'planAnalysis',
+                  target: 'callDecide',
+                  acceptedOutcome: 'decideThenCode',
+                },
+              },
+              'rememberDecidePath',
+            ],
+          },
+          {
+            guard: 'needsBossReply',
+            target: 'awaitBossReply',
+            actions: [
+              {
+                type: 'playbook.acceptedOutcome',
+                params: {
+                  source: 'planAnalysis',
+                  target: 'awaitBossReply',
+                  acceptedOutcome: 'needsBossReply',
+                },
+              },
+              'rememberPendingQuestion',
+            ],
+          },
+          {
+            target: 'failed',
+            actions: 'rememberMalformedPlayerOutput',
+          },
+        ],
+        onError: { target: 'failed', actions: 'rememberActorError' },
+      },
+    },
+    callCode: {
+      id: 'callCode',
+      description: STATE_DESCRIPTIONS.callCode,
+      meta: playbookMeta('callCode'),
+      tags: ['playbook.suspended'],
+      invoke: {
+        src: 'playbook',
+        input: ({ context }): PlaybookInput => ({
+          stateId: 'callCode',
+          sourceItem: 'DEV-2',
+          playbookId: 'code',
+          text: codeCallText(context),
+        }),
+        onDone: [
+          {
+            guard: 'isCodeSuccess',
+            target: 'done',
+            actions: 'completeWithChildSuccess',
+          },
+          {
+            target: 'reportedChildFailure',
+            actions: 'completeWithInsufficientCodeResult',
+          },
+        ],
+        onError: [
+          {
+            guard: 'authoredCodeFailure',
+            target: 'reportedChildFailure',
+            actions: 'completeWithCodeFailure',
+          },
+          { target: 'failed', actions: 'rememberActorError' },
+        ],
+      },
+    },
+    callDecide: {
+      id: 'callDecide',
+      description: STATE_DESCRIPTIONS.callDecide,
+      meta: playbookMeta('callDecide'),
+      tags: ['playbook.suspended'],
+      invoke: {
+        src: 'playbook',
+        input: ({ context }): PlaybookInput => ({
+          stateId: 'callDecide',
+          sourceItem: 'DEV-3',
+          playbookId: 'decide',
+          text: decideCallText(context),
+        }),
+        onDone: [
+          {
+            guard: 'isDecideSuccess',
+            target: 'callCodeAfterDecide',
+            actions: 'rememberDecideResult',
+          },
+          {
+            target: 'reportedChildFailure',
+            actions: 'completeWithInsufficientDecideResult',
+          },
+        ],
+        onError: [
+          {
+            guard: 'authoredDecideFailure',
+            target: 'reportedChildFailure',
+            actions: 'completeWithDecideFailure',
+          },
+          { target: 'failed', actions: 'rememberActorError' },
+        ],
+      },
+    },
+    callCodeAfterDecide: {
+      id: 'callCodeAfterDecide',
+      description: STATE_DESCRIPTIONS.callCodeAfterDecide,
+      meta: playbookMeta('callCodeAfterDecide'),
+      tags: ['playbook.suspended'],
+      invoke: {
+        src: 'playbook',
+        input: ({ context }): PlaybookInput => ({
+          stateId: 'callCodeAfterDecide',
+          sourceItem: 'DEV-4',
+          playbookId: 'code',
+          text: codeAfterDecideCallText(context),
+        }),
+        onDone: [
+          {
+            guard: 'isCodeSuccess',
+            target: 'done',
+            actions: 'completeWithChildSuccess',
+          },
+          {
+            target: 'reportedChildFailure',
+            actions: 'completeWithInsufficientCodeResult',
+          },
+        ],
+        onError: [
+          {
+            guard: 'authoredCodeFailure',
+            target: 'reportedChildFailure',
+            actions: 'completeWithCodeFailure',
+          },
+          { 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' },
+      },
+    },
+    discussionComplete: {
+      id: 'discussionComplete',
+      description: STATE_DESCRIPTIONS.discussionComplete,
+      meta: playbookMeta('discussionComplete'),
+      type: 'final',
+    },
+    done: {
+      id: 'done',
+      description: STATE_DESCRIPTIONS.done,
+      meta: playbookMeta('done'),
+      type: 'final',
+    },
+    reportedChildFailure: {
+      id: 'reportedChildFailure',
+      description: STATE_DESCRIPTIONS.reportedChildFailure,
+      meta: playbookMeta('reportedChildFailure'),
+      type: 'final',
+    },
+  },
+});
+
+export default devMachine;