@sublang/playbook 0.1.2 → 0.2.0

package/{code.fsm.ts → reference/sdlc/code.playbook/code.fsm.ts}

@@ -40,6 +40,14 @@ type WorkflowKind = 'singleCommit' | 'iteration' | 'specSummary';
 type ChangeOrigin = 'bossIntent' | 'irTask';
 type ReviewSubject = 'commit' | 'changes';
 type AfterReview = 'continueIr' | 'summarizeSpecs' | 'done';
+type ResumableStateId = Exclude<JumpableStateId, 'ready' | 'failed'>;
+
+type PendingBossQuestion = {
+  resumeStateId: ResumableStateId;
+  sourceItem: string;
+  player: Player;
+  question: string;
+};
 
 export type CaptainInput = {
   player: Player;
@@ -58,6 +66,8 @@ export type CaptainInput = {
   challenges?: string;
   coderPlayer?: string;
   reviewerPlayer?: string;
+  pendingBossQuestion?: PendingBossQuestion;
+  bossReply?: string;
 };
 
 export type CaptainOutput = {
@@ -67,6 +77,7 @@ export type CaptainOutput = {
   reviews?: string;
   challenges?: string;
   summary?: string;
+  question?: string;
   [k: string]: unknown;
 };
 
@@ -88,6 +99,8 @@ export type CodingContext = CodingInput & {
   challenges?: string;
   lastResult?: CaptainOutput;
   lastError?: unknown;
+  pendingBossQuestion?: PendingBossQuestion;
+  bossReply?: string;
 };
 
 export type CodingEvent =
@@ -99,7 +112,8 @@ export type CodingEvent =
       targetId: JumpableStateId;
       intent?: string;
       irNumber?: string;
-    };
+    }
+  | { type: 'BOSS_REPLY'; answer: string };
 
 const jumpableStateIds = [
   'ready',
@@ -125,6 +139,28 @@ const jumpableStateIds = [
   'failed',
 ] as const satisfies readonly JumpableStateId[];
 
+const resumableStateIds = [
+  'planAndImplement',
+  'respondToReview',
+  'continueIr',
+  'summarizeSpecs',
+  'reviewBossCommitSpecs',
+  'reviewBossCommitCode',
+  'reviewBossCommitMixed',
+  'reviewIrTaskCommitSpecs',
+  'reviewIrTaskCommitCode',
+  'reviewIrTaskCommitMixed',
+  'reviewChangesSpecs',
+  'reviewChangesCode',
+  'reviewChangesMixed',
+  'reviewChangesAndChallengesSpecs',
+  'reviewChangesAndChallengesCode',
+  'reviewChangesAndChallengesMixed',
+  'adjudicateChallenges',
+  'commitCoderInitial',
+  'commitJoint',
+] as const satisfies readonly ResumableStateId[];
+
 const outputOf = (event: unknown): CaptainOutput | undefined =>
   (event as { output?: CaptainOutput }).output;
 
@@ -160,6 +196,10 @@ const rememberCaptainError = assign({
   lastError: ({ event }: { event: unknown }) => (event as { error?: unknown }).error,
 });
 
+const rememberEmptyBossReplyError = assign({
+  lastError: () => new Error('BOSS_REPLY received empty answer'),
+});
+
 const rememberBossInput = assign({
   intent: ({ context, event }: { context: CodingContext; event: unknown }) =>
     (event as { intent?: string }).intent ?? context.intent,
@@ -167,15 +207,185 @@ const rememberBossInput = assign({
     (event as { irNumber?: string }).irNumber ?? context.irNumber,
 });
 
-const bossInterrupts = (ids: readonly JumpableStateId[]) =>
+type CaptainInputFactory = (context: Partial<CodingContext>) => CaptainInput;
+
+const needsBossReplyDescription =
+  "The player's prose surfaces a clarifying question for Boss that the player cannot answer alone. Output shall include `question: <verbatim question text from the player's prose>`.";
+
+const bossReplyInputFields = (context: Partial<CodingContext>) => ({
+  pendingBossQuestion: context.pendingBossQuestion,
+  bossReply: context.bossReply,
+});
+
+const withNeedsBossReply = <T extends Record<string, string>>(result: T) => ({
+  ...result,
+  needsBossReply: needsBossReplyDescription,
+});
+
+const captainStateMetadata = {
+  planAndImplement: { sourceItem: 'CODE-1', player: 'Coder' },
+  respondToReview: { sourceItem: 'CODE-2', player: 'Coder' },
+  continueIr: { sourceItem: 'CODE-3', player: 'Coder' },
+  summarizeSpecs: { sourceItem: 'CODE-4', player: 'Coder' },
+  reviewBossCommitSpecs: { sourceItem: 'CODE-5', player: 'Reviewer' },
+  reviewBossCommitCode: { sourceItem: 'CODE-6', player: 'Reviewer' },
+  reviewBossCommitMixed: { sourceItem: 'CODE-7', player: 'Reviewer' },
+  reviewIrTaskCommitSpecs: { sourceItem: 'CODE-8', player: 'Reviewer' },
+  reviewIrTaskCommitCode: { sourceItem: 'CODE-9', player: 'Reviewer' },
+  reviewIrTaskCommitMixed: { sourceItem: 'CODE-10', player: 'Reviewer' },
+  reviewChangesSpecs: { sourceItem: 'CODE-11', player: 'Reviewer' },
+  reviewChangesCode: { sourceItem: 'CODE-12', player: 'Reviewer' },
+  reviewChangesMixed: { sourceItem: 'CODE-13', player: 'Reviewer' },
+  reviewChangesAndChallengesSpecs: { sourceItem: 'CODE-15', player: 'Reviewer' },
+  reviewChangesAndChallengesCode: { sourceItem: 'CODE-16', player: 'Reviewer' },
+  reviewChangesAndChallengesMixed: { sourceItem: 'CODE-17', player: 'Reviewer' },
+  adjudicateChallenges: { sourceItem: 'CODE-14', player: 'Reviewer' },
+  commitCoderInitial: { sourceItem: 'CODE-18', player: 'Committer' },
+  commitJoint: { sourceItem: 'CODE-19', player: 'Committer' },
+} as const satisfies Record<
+  ResumableStateId,
+  { sourceItem: string; player: Player }
+>;
+
+const planAndImplementInput: CaptainInputFactory = (context) => ({
+  player: 'Coder',
+  sourceItem: 'CODE-1',
+  intent: context.intent,
+  ...bossReplyInputFields(context),
+  prompt: [
+    'Assess whether this can be completed in a single commit, following best practices.',
+    'If yes, implement and test, updating both code and specs; otherwise, decompose into tasks as a new IR under @specs/iterations.',
+    'Consult @specs/map.md for relevant context if needed; ensure it reflects the changes.',
+    'Do not commit.',
+  ].join('\n'),
+  result: withNeedsBossReply({
+    singleCommitReady:
+      'Coder produced uncommitted single-commit changes (Initial Changes).',
+    irDrafted:
+      'Coder decomposed the intent into a new IR and drafted it uncommitted (Initial Changes).',
+  }),
+});
+
+const continueIrInput: CaptainInputFactory = (context) => ({
+  player: 'Coder',
+  sourceItem: 'CODE-3',
+  irNumber: context.irNumber,
+  ...bossReplyInputFields(context),
+  prompt: [
+    'Continue to implement IR-<#> if not all deliverables and tasks are done.',
+    'Implement one task at a time (including corresponding tests if any).',
+    'Stop after each task for review — do not commit yet.',
+    'If relevant, mark progress in the IR.',
+  ].join('\n'),
+  result: withNeedsBossReply({
+    taskReady:
+      'Coder produced uncommitted changes for the next IR task (Initial Changes). Output shall include `taskDescription: <one-line description of the task just implemented>`.',
+    iterationDone: 'All IR deliverables and tasks are done.',
+  }),
+});
+
+const summarizeSpecsInput: CaptainInputFactory = (context) => ({
+  player: 'Coder',
+  sourceItem: 'CODE-4',
+  irNumber: context.irNumber,
+  ...bossReplyInputFields(context),
+  prompt: [
+    'Read IR-<#> and corresponding commits.',
+    'According to @specs/meta.md, add or update spec items to fully capture:',
+    '',
+    '- the user requirements in @specs/user,',
+    '- the system behavior in @specs/dev, and',
+    '- the integration/system test cases in @specs/test.',
+    '',
+    'The spec items should be the *minimal* set needed to reimplement code without the IR.',
+    'The set should be complete and coherent.',
+    'Avoid implementation specifics.',
+    'Avoid redundant spec items.',
+    'Consult @specs/map.md for relevant context and update it to reflect your changes.',
+  ].join('\n'),
+  result: withNeedsBossReply({
+    specsReady: 'Coder produced uncommitted spec updates (Initial Changes).',
+    noSpecChanges: 'Existing specs already capture the iteration.',
+  }),
+});
+
+const setPendingBossQuestion = (resumeStateId: ResumableStateId) =>
+  assign({
+    pendingBossQuestion: ({
+      context,
+      event,
+    }: {
+      context: CodingContext;
+      event: unknown;
+    }) => {
+      const input = captainStateMetadata[resumeStateId];
+      return {
+        resumeStateId,
+        sourceItem: input.sourceItem,
+        player: input.player,
+        question: outputOf(event)?.question ?? '',
+      };
+    },
+    bossReply: () => undefined,
+  });
+
+const rememberBossReply = assign({
+  bossReply: ({ event }: { event: unknown }) =>
+    (event as { answer?: string }).answer ?? '',
+});
+
+const clearBossReplyContext = assign({
+  pendingBossQuestion: () => undefined,
+  bossReply: () => undefined,
+});
+
+const actionsArray = (actions: unknown) =>
+  actions === undefined ? [] : Array.isArray(actions) ? actions : [actions];
+
+const withClearBossReplyContext = <T extends { actions?: unknown }>(transition: T): T => ({
+  ...transition,
+  actions: [clearBossReplyContext, ...actionsArray(transition.actions)],
+});
+
+const bossInterrupts = (
+  ids: readonly JumpableStateId[],
+  extraActions: readonly unknown[] = [],
+) =>
   ids.map((id) => ({
     target: `#${id}` as const,
     guard: ({ event }: { event: CodingEvent }) =>
       event.type === 'BOSS_INTERRUPT' && event.targetId === id,
     reenter: true,
-    actions: rememberBossInput,
+    actions: [...extraActions, rememberBossInput],
   }));
 
+const resumableStates = (ids: readonly ResumableStateId[]) =>
+  ids.map((id) => ({
+    target: `#${id}` as const,
+    guard: ({ context, event }: { context: CodingContext; event: CodingEvent }) =>
+      event.type === 'BOSS_REPLY' &&
+      context.pendingBossQuestion?.resumeStateId === id,
+    reenter: true,
+    actions: rememberBossReply,
+  }));
+
+const bossReplyIsEmpty = ({ event }: { event: CodingEvent }) =>
+  event.type === 'BOSS_REPLY' && event.answer.trim() === '';
+
+const withNeedsBossReplyTransition = <
+  T extends readonly { guard?: unknown; target?: unknown; actions?: unknown }[],
+>(
+  resumeStateId: ResumableStateId,
+  transitions: T,
+) => [
+  ...transitions.map((transition) => withClearBossReplyContext(transition)),
+  {
+    guard: guardIs('needsBossReply'),
+    target: '#awaitBossReply',
+    actions: [rememberCaptainOutput, setPendingBossQuestion(resumeStateId)],
+  },
+];
+
 const captainError = {
   target: '#failed',
   actions: rememberCaptainError,
@@ -217,6 +427,21 @@ const readyEvents = {
   },
 };
 
+const awaitBossReplyEvents = {
+  START_CODING: withClearBossReplyContext(readyEvents.START_CODING),
+  CONTINUE_IR: withClearBossReplyContext(readyEvents.CONTINUE_IR),
+  SUMMARIZE_IR: withClearBossReplyContext(readyEvents.SUMMARIZE_IR),
+  BOSS_INTERRUPT: bossInterrupts(jumpableStateIds, [clearBossReplyContext]),
+  BOSS_REPLY: [
+    {
+      guard: bossReplyIsEmpty,
+      target: '#failed',
+      actions: [clearBossReplyContext, rememberEmptyBossReplyError],
+    },
+    ...resumableStates(resumableStateIds),
+  ],
+};
+
 const captainPlaceholder = fromPromise<CaptainOutput, CaptainInput>(async () => {
   throw new Error('captain actor must be provided by the runner');
 });
@@ -250,31 +475,20 @@ export const codingMachine = setup({
       on: readyEvents,
     },
 
+    awaitBossReply: {
+      id: 'awaitBossReply',
+      description: 'Waiting for Boss to answer a player question.',
+      on: awaitBossReplyEvents,
+    },
+
     planAndImplement: {
       id: 'planAndImplement',
       description:
         'CODE-1: Coder assesses a Boss intent and either implements a single-commit change or drafts an IR.',
       invoke: {
         src: 'captain',
-        input: ({ context }): CaptainInput => ({
-          player: 'Coder',
-          sourceItem: 'CODE-1',
-          intent: context.intent,
-          prompt: [
-            'Assess whether this can be completed in a single commit, following best practices.',
-            'If yes, implement and test, updating both code and specs; otherwise, decompose into tasks as a new IR under @specs/iterations.',
-            'Consult @specs/map.md for relevant context if needed; ensure it reflects the changes.',
-            'Do not commit.',
-          ].join('\n'),
-          result: {
-            singleCommitReady:
-              'Coder produced uncommitted single-commit changes (Initial Changes).',
-            irDrafted:
-              'Coder decomposed the intent into a new IR and drafted it uncommitted (Initial Changes).',
-            needsBossInput: 'Progress requires additional Boss input.',
-          },
-        }),
-        onDone: [
+        input: ({ context }): CaptainInput => planAndImplementInput(context),
+        onDone: withNeedsBossReplyTransition('planAndImplement', [
           {
             guard: guardIs('singleCommitReady'),
             target: '#commitCoderInitial',
@@ -299,8 +513,7 @@ export const codingMachine = setup({
               }),
             ],
           },
-          { guard: guardIs('needsBossInput'), target: '#ready', actions: rememberCaptainOutput },
-        ],
+        ]),
         onError: captainError,
       },
     },
@@ -313,6 +526,7 @@ export const codingMachine = setup({
         input: ({ context }): CaptainInput => ({
           player: 'Coder',
           sourceItem: 'CODE-2',
+          ...bossReplyInputFields(context),
           reviews: context.reviews,
           prompt: [
             'For each review item below for the above changes, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.',
@@ -335,9 +549,10 @@ export const codingMachine = setup({
               'Coder challenged one or more review items without producing any code edits. Output shall include `challenges: <numbered rebuttals, one per challenged item>`.',
             accepted:
               'Coder accepted the review outcome without further edits.',
+            needsBossReply: needsBossReplyDescription,
           },
         }),
-        onDone: [
+        onDone: withNeedsBossReplyTransition('respondToReview', [
           {
             guard: guardIs('changesMadeSpecs'),
             target: '#reviewChangesSpecs',
@@ -402,7 +617,7 @@ export const codingMachine = setup({
             target: '#done',
             actions: rememberCaptainOutput,
           },
-        ],
+        ]),
         onError: captainError,
       },
     },
@@ -413,24 +628,8 @@ export const codingMachine = setup({
         'CODE-3: Coder continues an IR after the previous task or IR draft passed review.',
       invoke: {
         src: 'captain',
-        input: ({ context }): CaptainInput => ({
-          player: 'Coder',
-          sourceItem: 'CODE-3',
-          irNumber: context.irNumber,
-          prompt: [
-            'Continue to implement IR-<#> if not all deliverables and tasks are done.',
-            'Implement one task at a time (including corresponding tests if any).',
-            'Stop after each task for review — do not commit yet.',
-            'If relevant, mark progress in the IR.',
-          ].join('\n'),
-          result: {
-            taskReady:
-              'Coder produced uncommitted changes for the next IR task (Initial Changes). Output shall include `taskDescription: <one-line description of the task just implemented>`.',
-            iterationDone: 'All IR deliverables and tasks are done.',
-            needsBossInput: 'Progress requires additional Boss input.',
-          },
-        }),
-        onDone: [
+        input: ({ context }): CaptainInput => continueIrInput(context),
+        onDone: withNeedsBossReplyTransition('continueIr', [
           {
             guard: guardIs('taskReady'),
             target: '#commitCoderInitial',
@@ -454,8 +653,7 @@ export const codingMachine = setup({
               }),
             ],
           },
-          { guard: guardIs('needsBossInput'), target: '#ready', actions: rememberCaptainOutput },
-        ],
+        ]),
         onError: captainError,
       },
     },
@@ -465,31 +663,8 @@ export const codingMachine = setup({
       description: 'CODE-4: Coder summarizes a completed IR into minimal spec items.',
       invoke: {
         src: 'captain',
-        input: ({ context }): CaptainInput => ({
-          player: 'Coder',
-          sourceItem: 'CODE-4',
-          irNumber: context.irNumber,
-          prompt: [
-            'Read IR-<#> and corresponding commits.',
-            'According to @specs/meta.md, add or update spec items to fully capture:',
-            '',
-            '- the user requirements in @specs/user,',
-            '- the system behavior in @specs/dev, and',
-            '- the integration/system test cases in @specs/test.',
-            '',
-            'The spec items should be the *minimal* set needed to reimplement code without the IR.',
-            'The set should be complete and coherent.',
-            'Avoid implementation specifics.',
-            'Avoid redundant spec items.',
-            'Consult @specs/map.md for relevant context and update it to reflect your changes.',
-          ].join('\n'),
-          result: {
-            specsReady: 'Coder produced uncommitted spec updates (Initial Changes).',
-            noSpecChanges: 'Existing specs already capture the iteration.',
-            needsBossInput: 'Spec summarization requires additional Boss input.',
-          },
-        }),
-        onDone: [
+        input: ({ context }): CaptainInput => summarizeSpecsInput(context),
+        onDone: withNeedsBossReplyTransition('summarizeSpecs', [
           {
             guard: guardIs('specsReady'),
             target: '#commitCoderInitial',
@@ -502,9 +677,12 @@ export const codingMachine = setup({
               }),
             ],
           },
-          { guard: guardIs('noSpecChanges'), target: '#done', actions: rememberCaptainOutput },
-          { guard: guardIs('needsBossInput'), target: '#ready', actions: rememberCaptainOutput },
-        ],
+          {
+            guard: guardIs('noSpecChanges'),
+            target: '#done',
+            actions: rememberCaptainOutput,
+          },
+        ]),
         onError: captainError,
       },
     },
@@ -518,6 +696,7 @@ export const codingMachine = setup({
         input: ({ context }): CaptainInput => ({
           player: 'Reviewer',
           sourceItem: 'CODE-5',
+          ...bossReplyInputFields(context),
           intent: context.intent,
           prompt: [
             'Review the latest commit.',
@@ -536,9 +715,10 @@ export const codingMachine = setup({
             noFindings: 'The spec-only commit has no review findings.',
             hasFindings:
               'The review produced findings for Coder. Output shall include `reviews: <numbered list of findings, no duplication>`.',
+            needsBossReply: needsBossReplyDescription,
           },
         }),
-        onDone: [
+        onDone: withNeedsBossReplyTransition('reviewBossCommitSpecs', [
           { guard: noFindingsAfter('continueIr'), target: '#continueIr', actions: rememberCaptainOutput },
           { guard: noFindingsAfter('summarizeSpecs'), target: '#summarizeSpecs', actions: rememberCaptainOutput },
           { guard: noFindingsAfter('done'), target: '#done', actions: rememberCaptainOutput },
@@ -547,7 +727,7 @@ export const codingMachine = setup({
             target: '#respondToReview',
             actions: [rememberCaptainOutput, assign({ reviewSubject: () => 'commit' as const })],
           },
-        ],
+        ]),
         onError: captainError,
       },
     },
@@ -561,6 +741,7 @@ export const codingMachine = setup({
         input: ({ context }): CaptainInput => ({
           player: 'Reviewer',
           sourceItem: 'CODE-6',
+          ...bossReplyInputFields(context),
           intent: context.intent,
           prompt: [
             'Review the latest commit.',
@@ -574,9 +755,10 @@ export const codingMachine = setup({
             noFindings: 'The code-only commit has no review findings.',
             hasFindings:
               'The review produced findings for Coder. Output shall include `reviews: <numbered list of findings, no duplication>`.',
+            needsBossReply: needsBossReplyDescription,
           },
         }),
-        onDone: [
+        onDone: withNeedsBossReplyTransition('reviewBossCommitCode', [
           { guard: noFindingsAfter('continueIr'), target: '#continueIr', actions: rememberCaptainOutput },
           { guard: noFindingsAfter('summarizeSpecs'), target: '#summarizeSpecs', actions: rememberCaptainOutput },
           { guard: noFindingsAfter('done'), target: '#done', actions: rememberCaptainOutput },
@@ -585,7 +767,7 @@ export const codingMachine = setup({
             target: '#respondToReview',
             actions: [rememberCaptainOutput, assign({ reviewSubject: () => 'commit' as const })],
           },
-        ],
+        ]),
         onError: captainError,
       },
     },
@@ -599,6 +781,7 @@ export const codingMachine = setup({
         input: ({ context }): CaptainInput => ({
           player: 'Reviewer',
           sourceItem: 'CODE-7',
+          ...bossReplyInputFields(context),
           intent: context.intent,
           prompt: [
             'Review the latest commit.',
@@ -619,9 +802,10 @@ export const codingMachine = setup({
             noFindings: 'The mixed commit has no review findings.',
             hasFindings:
               'The review produced findings for Coder. Output shall include `reviews: <numbered list of findings, no duplication>`.',
+            needsBossReply: needsBossReplyDescription,
           },
         }),
-        onDone: [
+        onDone: withNeedsBossReplyTransition('reviewBossCommitMixed', [
           { guard: noFindingsAfter('continueIr'), target: '#continueIr', actions: rememberCaptainOutput },
           { guard: noFindingsAfter('summarizeSpecs'), target: '#summarizeSpecs', actions: rememberCaptainOutput },
           { guard: noFindingsAfter('done'), target: '#done', actions: rememberCaptainOutput },
@@ -630,7 +814,7 @@ export const codingMachine = setup({
             target: '#respondToReview',
             actions: [rememberCaptainOutput, assign({ reviewSubject: () => 'commit' as const })],
           },
-        ],
+        ]),
         onError: captainError,
       },
     },
@@ -644,6 +828,7 @@ export const codingMachine = setup({
         input: ({ context }): CaptainInput => ({
           player: 'Reviewer',
           sourceItem: 'CODE-8',
+          ...bossReplyInputFields(context),
           irNumber: context.irNumber,
           taskDescription: context.taskDescription,
           prompt: [
@@ -663,9 +848,10 @@ export const codingMachine = setup({
             noFindings: 'The IR-task spec-only commit has no review findings.',
             hasFindings:
               'The review produced findings for Coder. Output shall include `reviews: <numbered list of findings, no duplication>`.',
+            needsBossReply: needsBossReplyDescription,
           },
         }),
-        onDone: [
+        onDone: withNeedsBossReplyTransition('reviewIrTaskCommitSpecs', [
           { guard: noFindingsAfter('continueIr'), target: '#continueIr', actions: rememberCaptainOutput },
           { guard: noFindingsAfter('summarizeSpecs'), target: '#summarizeSpecs', actions: rememberCaptainOutput },
           { guard: noFindingsAfter('done'), target: '#done', actions: rememberCaptainOutput },
@@ -674,7 +860,7 @@ export const codingMachine = setup({
             target: '#respondToReview',
             actions: [rememberCaptainOutput, assign({ reviewSubject: () => 'commit' as const })],
           },
-        ],
+        ]),
         onError: captainError,
       },
     },
@@ -688,6 +874,7 @@ export const codingMachine = setup({
         input: ({ context }): CaptainInput => ({
           player: 'Reviewer',
           sourceItem: 'CODE-9',
+          ...bossReplyInputFields(context),
           irNumber: context.irNumber,
           taskDescription: context.taskDescription,
           prompt: [
@@ -702,9 +889,10 @@ export const codingMachine = setup({
             noFindings: 'The IR-task code-only commit has no review findings.',
             hasFindings:
               'The review produced findings for Coder. Output shall include `reviews: <numbered list of findings, no duplication>`.',
+            needsBossReply: needsBossReplyDescription,
           },
         }),
-        onDone: [
+        onDone: withNeedsBossReplyTransition('reviewIrTaskCommitCode', [
           { guard: noFindingsAfter('continueIr'), target: '#continueIr', actions: rememberCaptainOutput },
           { guard: noFindingsAfter('summarizeSpecs'), target: '#summarizeSpecs', actions: rememberCaptainOutput },
           { guard: noFindingsAfter('done'), target: '#done', actions: rememberCaptainOutput },
@@ -713,7 +901,7 @@ export const codingMachine = setup({
             target: '#respondToReview',
             actions: [rememberCaptainOutput, assign({ reviewSubject: () => 'commit' as const })],
           },
-        ],
+        ]),
         onError: captainError,
       },
     },
@@ -727,6 +915,7 @@ export const codingMachine = setup({
         input: ({ context }): CaptainInput => ({
           player: 'Reviewer',
           sourceItem: 'CODE-10',
+          ...bossReplyInputFields(context),
           irNumber: context.irNumber,
           taskDescription: context.taskDescription,
           prompt: [
@@ -748,9 +937,10 @@ export const codingMachine = setup({
             noFindings: 'The IR-task mixed commit has no review findings.',
             hasFindings:
               'The review produced findings for Coder. Output shall include `reviews: <numbered list of findings, no duplication>`.',
+            needsBossReply: needsBossReplyDescription,
           },
         }),
-        onDone: [
+        onDone: withNeedsBossReplyTransition('reviewIrTaskCommitMixed', [
           { guard: noFindingsAfter('continueIr'), target: '#continueIr', actions: rememberCaptainOutput },
           { guard: noFindingsAfter('summarizeSpecs'), target: '#summarizeSpecs', actions: rememberCaptainOutput },
           { guard: noFindingsAfter('done'), target: '#done', actions: rememberCaptainOutput },
@@ -759,7 +949,7 @@ export const codingMachine = setup({
             target: '#respondToReview',
             actions: [rememberCaptainOutput, assign({ reviewSubject: () => 'commit' as const })],
           },
-        ],
+        ]),
         onError: captainError,
       },
     },
@@ -770,9 +960,10 @@ export const codingMachine = setup({
         'CODE-11: Reviewer reviews uncommitted Coder changes that touch only @specs/{user,dev,test}/ with no accompanying rebuttals.',
       invoke: {
         src: 'captain',
-        input: (): CaptainInput => ({
+        input: ({ context }): CaptainInput => ({
           player: 'Reviewer',
           sourceItem: 'CODE-11',
+          ...bossReplyInputFields(context),
           prompt: [
             'Review the unstaged/untracked changes.',
             'Understand the intent.',
@@ -790,9 +981,10 @@ export const codingMachine = setup({
             noFindings: 'The uncommitted spec-only changes are ready to commit.',
             hasFindings:
               'The review produced findings for Coder. Output shall include `reviews: <numbered list of findings, no duplication>`.',
+            needsBossReply: needsBossReplyDescription,
           },
         }),
-        onDone: [
+        onDone: withNeedsBossReplyTransition('reviewChangesSpecs', [
           {
             guard: guardIs('noFindings'),
             target: '#commitJoint',
@@ -803,7 +995,7 @@ export const codingMachine = setup({
             target: '#respondToReview',
             actions: [rememberCaptainOutput, assign({ reviewSubject: () => 'changes' as const })],
           },
-        ],
+        ]),
         onError: captainError,
       },
     },
@@ -814,9 +1006,10 @@ export const codingMachine = setup({
         'CODE-12: Reviewer reviews uncommitted Coder changes that touch only files outside @specs/{user,dev,test}/ with no accompanying rebuttals.',
       invoke: {
         src: 'captain',
-        input: (): CaptainInput => ({
+        input: ({ context }): CaptainInput => ({
           player: 'Reviewer',
           sourceItem: 'CODE-12',
+          ...bossReplyInputFields(context),
           prompt: [
             'Review the unstaged/untracked changes.',
             'Understand the intent.',
@@ -829,9 +1022,10 @@ export const codingMachine = setup({
             noFindings: 'The uncommitted code-only changes are ready to commit.',
             hasFindings:
               'The review produced findings for Coder. Output shall include `reviews: <numbered list of findings, no duplication>`.',
+            needsBossReply: needsBossReplyDescription,
           },
         }),
-        onDone: [
+        onDone: withNeedsBossReplyTransition('reviewChangesCode', [
           {
             guard: guardIs('noFindings'),
             target: '#commitJoint',
@@ -842,7 +1036,7 @@ export const codingMachine = setup({
             target: '#respondToReview',
             actions: [rememberCaptainOutput, assign({ reviewSubject: () => 'changes' as const })],
           },
-        ],
+        ]),
         onError: captainError,
       },
     },
@@ -853,9 +1047,10 @@ export const codingMachine = setup({
         'CODE-13: Reviewer reviews uncommitted Coder changes that touch both @specs/{user,dev,test}/ and other files with no accompanying rebuttals.',
       invoke: {
         src: 'captain',
-        input: (): CaptainInput => ({
+        input: ({ context }): CaptainInput => ({
           player: 'Reviewer',
           sourceItem: 'CODE-13',
+          ...bossReplyInputFields(context),
           prompt: [
             'Review the unstaged/untracked changes.',
             'Understand the intent.',
@@ -875,9 +1070,10 @@ export const codingMachine = setup({
             noFindings: 'The uncommitted mixed changes are ready to commit.',
             hasFindings:
               'The review produced findings for Coder. Output shall include `reviews: <numbered list of findings, no duplication>`.',
+            needsBossReply: needsBossReplyDescription,
           },
         }),
-        onDone: [
+        onDone: withNeedsBossReplyTransition('reviewChangesMixed', [
           {
             guard: guardIs('noFindings'),
             target: '#commitJoint',
@@ -888,7 +1084,7 @@ export const codingMachine = setup({
             target: '#respondToReview',
             actions: [rememberCaptainOutput, assign({ reviewSubject: () => 'changes' as const })],
           },
-        ],
+        ]),
         onError: captainError,
       },
     },
@@ -902,6 +1098,7 @@ export const codingMachine = setup({
         input: ({ context }): CaptainInput => ({
           player: 'Reviewer',
           sourceItem: 'CODE-15',
+          ...bossReplyInputFields(context),
           reviews: context.reviews,
           challenges: context.challenges,
           prompt: [
@@ -923,9 +1120,10 @@ export const codingMachine = setup({
               'The new spec-only changes are ready to commit and every rebuttal was accepted (or no items remained open).',
             needsRevision:
               'The combined round needs more work: the review produced findings, one or more rebuttals were rejected, or both. Output shall include `reviews: <numbered list of any new findings or rejected rebuttals to address>`.',
+            needsBossReply: needsBossReplyDescription,
           },
         }),
-        onDone: [
+        onDone: withNeedsBossReplyTransition('reviewChangesAndChallengesSpecs', [
           {
             guard: guardIs('approved'),
             target: '#commitJoint',
@@ -936,7 +1134,7 @@ export const codingMachine = setup({
             target: '#respondToReview',
             actions: [rememberCaptainOutput, assign({ reviewSubject: () => 'changes' as const })],
           },
-        ],
+        ]),
         onError: captainError,
       },
     },
@@ -950,6 +1148,7 @@ export const codingMachine = setup({
         input: ({ context }): CaptainInput => ({
           player: 'Reviewer',
           sourceItem: 'CODE-16',
+          ...bossReplyInputFields(context),
           reviews: context.reviews,
           challenges: context.challenges,
           prompt: [
@@ -966,9 +1165,10 @@ export const codingMachine = setup({
               'The new code-only changes are ready to commit and every rebuttal was accepted (or no items remained open).',
             needsRevision:
               'The combined round needs more work: the review produced findings, one or more rebuttals were rejected, or both. Output shall include `reviews: <numbered list of any new findings or rejected rebuttals to address>`.',
+            needsBossReply: needsBossReplyDescription,
           },
         }),
-        onDone: [
+        onDone: withNeedsBossReplyTransition('reviewChangesAndChallengesCode', [
           {
             guard: guardIs('approved'),
             target: '#commitJoint',
@@ -979,7 +1179,7 @@ export const codingMachine = setup({
             target: '#respondToReview',
             actions: [rememberCaptainOutput, assign({ reviewSubject: () => 'changes' as const })],
           },
-        ],
+        ]),
         onError: captainError,
       },
     },
@@ -993,6 +1193,7 @@ export const codingMachine = setup({
         input: ({ context }): CaptainInput => ({
           player: 'Reviewer',
           sourceItem: 'CODE-17',
+          ...bossReplyInputFields(context),
           reviews: context.reviews,
           challenges: context.challenges,
           prompt: [
@@ -1016,9 +1217,10 @@ export const codingMachine = setup({
               'The new mixed changes are ready to commit and every rebuttal was accepted (or no items remained open).',
             needsRevision:
               'The combined round needs more work: the review produced findings, one or more rebuttals were rejected, or both. Output shall include `reviews: <numbered list of any new findings or rejected rebuttals to address>`.',
+            needsBossReply: needsBossReplyDescription,
           },
         }),
-        onDone: [
+        onDone: withNeedsBossReplyTransition('reviewChangesAndChallengesMixed', [
           {
             guard: guardIs('approved'),
             target: '#commitJoint',
@@ -1029,7 +1231,7 @@ export const codingMachine = setup({
             target: '#respondToReview',
             actions: [rememberCaptainOutput, assign({ reviewSubject: () => 'changes' as const })],
           },
-        ],
+        ]),
         onError: captainError,
       },
     },
@@ -1042,6 +1244,7 @@ export const codingMachine = setup({
         input: ({ context }): CaptainInput => ({
           player: 'Reviewer',
           sourceItem: 'CODE-14',
+          ...bossReplyInputFields(context),
           reviews: context.reviews,
           challenges: context.challenges,
           prompt: [
@@ -1053,9 +1256,10 @@ export const codingMachine = setup({
             challengeRejected:
               'Reviewer rejected the rebuttal — Coder must respond again.',
             noOpenItems: 'No review items remain open.',
+            needsBossReply: needsBossReplyDescription,
           },
         }),
-        onDone: [
+        onDone: withNeedsBossReplyTransition('adjudicateChallenges', [
           {
             guard: ({ context, event }) =>
               (outputOf(event)?.guard === 'challengeAccepted' ||
@@ -1096,7 +1300,7 @@ export const codingMachine = setup({
             target: '#respondToReview',
             actions: rememberCaptainOutput,
           },
-        ],
+        ]),
         onError: captainError,
       },
     },
@@ -1110,6 +1314,7 @@ export const codingMachine = setup({
         input: ({ context }): CaptainInput => ({
           player: 'Committer',
           sourceItem: 'CODE-18',
+          ...bossReplyInputFields(context),
           coderPlayer: context.coderPlayer,
           prompt: [
             'Make a commit of the changes that belong in the repo, following @specs/dev/git.md (reread if necessary).',
@@ -1121,9 +1326,10 @@ export const codingMachine = setup({
             committedMixed: 'Committed changes that span both @specs/{user,dev,test}/ and other files.',
             noRelevantChanges: 'There are no relevant changes to commit.',
             needsBossInput: 'Committing requires additional Boss input.',
+            needsBossReply: needsBossReplyDescription,
           },
         }),
-        onDone: [
+        onDone: withNeedsBossReplyTransition('commitCoderInitial', [
           {
             guard: guardAndOrigin('committedSpecs', 'bossIntent'),
             target: '#reviewBossCommitSpecs',
@@ -1156,7 +1362,7 @@ export const codingMachine = setup({
           },
           { guard: guardIs('noRelevantChanges'), target: '#ready', actions: rememberCaptainOutput },
           { guard: guardIs('needsBossInput'), target: '#ready', actions: rememberCaptainOutput },
-        ],
+        ]),
         onError: captainError,
       },
     },
@@ -1170,6 +1376,7 @@ export const codingMachine = setup({
         input: ({ context }): CaptainInput => ({
           player: 'Committer',
           sourceItem: 'CODE-19',
+          ...bossReplyInputFields(context),
           coderPlayer: context.coderPlayer,
           reviewerPlayer: context.reviewerPlayer,
           prompt: [
@@ -1180,9 +1387,10 @@ export const codingMachine = setup({
             committed: 'Relevant changes were committed.',
             noRelevantChanges: 'There are no relevant changes to commit.',
             needsBossInput: 'Committing requires additional Boss input.',
+            needsBossReply: needsBossReplyDescription,
           },
         }),
-        onDone: [
+        onDone: withNeedsBossReplyTransition('commitJoint', [
           {
             guard: ({ context, event }) =>
               outputOf(event)?.guard === 'committed' && context.afterReview === 'continueIr',
@@ -1203,7 +1411,7 @@ export const codingMachine = setup({
           },
           { guard: guardIs('noRelevantChanges'), target: '#done', actions: rememberCaptainOutput },
           { guard: guardIs('needsBossInput'), target: '#ready', actions: rememberCaptainOutput },
-        ],
+        ]),
         onError: captainError,
       },
     },