@sublang/playbook 13.0.0 → 13.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "13.0.0",
+  "version": "13.1.0",
   "type": "module",
   "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, REVIEW, DECIDE, and DEV workflows driven by GEARS specs.",
   "license": "Apache-2.0",
@@ -198,7 +198,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@sublang/cligent": "^0.25.0",
+    "@sublang/cligent": "^0.26.0",
     "@sublang/spex": "^3.0.0",
     "p-queue": "^9.3.1",
     "xstate": "^5.19.4",

package/reference/sdlc/code.md

@@ -25,6 +25,9 @@ When the nested `review` call fails outside that authored result contract, `code
 
 At the start of the first phase, Captain shall relay to Coder the complete caller input and any relevant run results in quotes (`>`), along with the following instruction:
 
+> Original request: <caller-input>
+> Run results: <run-results>
+
 ```markdown
 First determine whether the coding request starts a new coding intent or continues an existing IR with unfinished work.
 If the request may continue an existing IR but does not identify it unambiguously, ask Boss before changing files.
@@ -44,6 +47,10 @@ Consult @specs/map.md for relevant context and @specs/meta.md for spec requireme
 
 At the start of every later IR-task phase, Captain shall relay to Coder the original caller input, the IR identity, and any relevant run results in quotes (`>`), along with the following instruction:
 
+> Original request: <caller-input>
+> IR number: <ir-number>
+> Run results: <run-results>
+
 ```markdown
 Read the identified IR and implement exactly its next unfinished task, including corresponding tests or specs if any.
 Do not implement a later task in this phase.

package/reference/sdlc/code.playbook/code.fsm.js

@@ -12,8 +12,8 @@ const APPENDED_PHASE_PROMPT = [
     'Coder is <coder-llm>.',
 ];
 const FIRST_PHASE_PROMPT = [
-    '> <caller-input>',
-    '> <run-results>',
+    '> Original request: <caller-input>',
+    '> Run results: <run-results>',
     '',
     'First determine whether the coding request starts a new coding intent or continues an existing IR with unfinished work.',
     'If the request may continue an existing IR but does not identify it unambiguously, ask Boss before changing files.',
@@ -33,9 +33,9 @@ const FIRST_PHASE_PROMPT = [
     ...APPENDED_PHASE_PROMPT,
 ].join('\n');
 const IR_TASK_PROMPT = [
-    '> <caller-input>',
-    '> <ir-number>',
-    '> <run-results>',
+    '> Original request: <caller-input>',
+    '> IR number: <ir-number>',
+    '> Run results: <run-results>',
     '',
     'Read the identified IR and implement exactly its next unfinished task, including corresponding tests or specs if any.',
     'Do not implement a later task in this phase.',

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

@@ -156,8 +156,8 @@ const APPENDED_PHASE_PROMPT = [
 ];
 
 const FIRST_PHASE_PROMPT = [
-  '> <caller-input>',
-  '> <run-results>',
+  '> Original request: <caller-input>',
+  '> Run results: <run-results>',
   '',
   'First determine whether the coding request starts a new coding intent or continues an existing IR with unfinished work.',
   'If the request may continue an existing IR but does not identify it unambiguously, ask Boss before changing files.',
@@ -178,9 +178,9 @@ const FIRST_PHASE_PROMPT = [
 ].join('\n');
 
 const IR_TASK_PROMPT = [
-  '> <caller-input>',
-  '> <ir-number>',
-  '> <run-results>',
+  '> Original request: <caller-input>',
+  '> IR number: <ir-number>',
+  '> Run results: <run-results>',
   '',
   'Read the identified IR and implement exactly its next unfinished task, including corresponding tests or specs if any.',
   'Do not implement a later task in this phase.',

package/reference/sdlc/code.playbook/code.gears.md

@@ -13,8 +13,8 @@ Roles:
 
 When the first coding phase begins, Captain shall prompt Coder:
 
-> > <caller-input>
-> > <run-results>
+> > Original request: <caller-input>
+> > Run results: <run-results>
 >
 > First determine whether the coding request starts a new coding intent or continues an existing IR with unfinished work.
 > If the request may continue an existing IR but does not identify it unambiguously, ask Boss before changing files.
@@ -63,9 +63,9 @@ Workflow outcomes:
 
 When a later IR-task phase begins, Captain shall prompt Coder:
 
-> > <caller-input>
-> > <ir-number>
-> > <run-results>
+> > Original request: <caller-input>
+> > IR number: <ir-number>
+> > Run results: <run-results>
 >
 > Read the identified IR and implement exactly its next unfinished task, including corresponding tests or specs if any.
 > Do not implement a later task in this phase.

package/reference/sdlc/code.playbook/code.playbook.d.ts

@@ -10,7 +10,7 @@ export type CodePlaybookHostCapabilities = PlaybookHostConstructionCapabilities
  * runtime text. The generic composer preserves the marker itself; CODE's
  * override additionally keeps a multiline value inside that quote.
  */
-declare function composePlayerPrompt(input: PlayerInput, promptIdentity: XStatePromptIdentity): string;
+declare function composePlayerPrompt(input: PlayerInput, promptIdentity: XStatePromptIdentity, resuming?: boolean): string;
 export declare const _internal: {
     composePlayerPrompt: typeof composePlayerPrompt;
     VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string>;

package/reference/sdlc/code.playbook/code.playbook.js

@@ -10,11 +10,10 @@
 //                the first phase decides among four semantic outcomes
 // Nested call:   literal review target through the shared bridge
 // Compat:        artifact schema 3 / runtime ABI 1
-import { createXStatePlaybookRuntime, snapshotJsonValue, } from '@sublang/playbook/xstate-runtime';
+import { createXStatePlaybookRuntime, composePlayerContinuation, snapshotJsonValue, } from '@sublang/playbook/xstate-runtime';
 import { codingMachine, } from './code.fsm.js';
 const OPTION_KEYS = new Set(['runResults']);
 const PLACEHOLDER = /<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>/g;
-const CONTINUATION_PREAMBLE = 'You previously paused this task to ask Boss a question; Boss has now replied. Continue the same task using the reply below.';
 const VERBATIM_PAYLOAD_FIELDS = new Set([
     'coderOutput',
 ]);
@@ -52,11 +51,11 @@ function quoteContinuation(value) {
  * runtime text. The generic composer preserves the marker itself; CODE's
  * override additionally keeps a multiline value inside that quote.
  */
-function composePlayerPrompt(input, promptIdentity) {
+function composePlayerPrompt(input, promptIdentity, resuming = false) {
     const fields = input;
     const template = input.prompt
         .split('\n')
-        .filter((line) => !(line === '> <run-results>' && input.runResults.length === 0))
+        .filter((line) => !(line === '> Run results: <run-results>' && input.runResults.length === 0))
         .join('\n');
     const body = template.replace(PLACEHOLDER, (match, token, offset, source) => {
         const value = token === 'coder-llm'
@@ -66,18 +65,9 @@ function composePlayerPrompt(input, promptIdentity) {
             return match;
         const lineStart = source.lastIndexOf('\n', offset - 1) + 1;
         const literal = source.slice(lineStart, offset);
-        return literal === '> ' ? quoteContinuation(value) : value;
+        return literal.startsWith('> ') ? quoteContinuation(value) : value;
     });
-    if (input.pendingBossQuestion === undefined ||
-        input.bossReply === undefined) {
-        return body;
-    }
-    return [
-        CONTINUATION_PREAMBLE,
-        `Boss question:\n${input.pendingBossQuestion.question}`,
-        `Boss reply:\n${input.bossReply}`,
-        body,
-    ].join('\n\n');
+    return composePlayerContinuation(input, body, resuming);
 }
 export const _internal = {
     composePlayerPrompt,
@@ -177,7 +167,7 @@ const runtimeSpec = {
             },
         },
     },
-    composePlayerPrompt: (input, promptIdentity) => composePlayerPrompt(input, promptIdentity),
+    composePlayerPrompt: (input, promptIdentity, resuming) => composePlayerPrompt(input, promptIdentity, resuming),
     verbatimPayloadFields: VERBATIM_PAYLOAD_FIELDS,
     controlContextFields: ['phase'],
     unfinishedFinalStateIds: UNFINISHED_FINAL_STATE_IDS,

package/reference/sdlc/code.playbook/code.playbook.ts

@@ -13,6 +13,7 @@
 
 import {
   createXStatePlaybookRuntime,
+  composePlayerContinuation,
   snapshotJsonValue,
   type PlaybookPlayerInput,
   type XStatePlaybookRuntimeFactory,
@@ -85,8 +86,6 @@ export type CodePlaybookHostCapabilities =
 
 const OPTION_KEYS = new Set(['runResults']);
 const PLACEHOLDER = /<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>/g;
-const CONTINUATION_PREAMBLE =
-  'You previously paused this task to ask Boss a question; Boss has now replied. Continue the same task using the reply below.';
 
 const VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string> = new Set([
   'coderOutput',
@@ -135,12 +134,13 @@ function quoteContinuation(value: string): string {
 function composePlayerPrompt(
   input: PlayerInput,
   promptIdentity: XStatePromptIdentity,
+  resuming = false,
 ): string {
   const fields = input as unknown as Record<string, unknown>;
   const template = input.prompt
     .split('\n')
     .filter(
-      (line) => !(line === '> <run-results>' && input.runResults.length === 0),
+      (line) => !(line === '> Run results: <run-results>' && input.runResults.length === 0),
     )
     .join('\n');
   const body = template.replace(
@@ -153,21 +153,10 @@ function composePlayerPrompt(
       if (typeof value !== 'string') return match;
       const lineStart = source.lastIndexOf('\n', offset - 1) + 1;
       const literal = source.slice(lineStart, offset);
-      return literal === '> ' ? quoteContinuation(value) : value;
+      return literal.startsWith('> ') ? quoteContinuation(value) : value;
     },
   );
-  if (
-    input.pendingBossQuestion === undefined ||
-    input.bossReply === undefined
-  ) {
-    return body;
-  }
-  return [
-    CONTINUATION_PREAMBLE,
-    `Boss question:\n${input.pendingBossQuestion.question}`,
-    `Boss reply:\n${input.bossReply}`,
-    body,
-  ].join('\n\n');
+  return composePlayerContinuation(input, body, resuming);
 }
 
 export const _internal = {
@@ -273,7 +262,8 @@ const runtimeSpec = {
   composePlayerPrompt: (
     input: PlaybookPlayerInput,
     promptIdentity: XStatePromptIdentity,
-  ) => composePlayerPrompt(input as PlayerInput, promptIdentity),
+    resuming?: boolean,
+  ) => composePlayerPrompt(input as PlayerInput, promptIdentity, resuming),
   verbatimPayloadFields: VERBATIM_PAYLOAD_FIELDS,
   controlContextFields: ['phase'],
   unfinishedFinalStateIds: UNFINISHED_FINAL_STATE_IDS,

package/reference/sdlc/code.playbook/playbook-captain.js

@@ -2599,6 +2599,9 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             if (!ledger) {
                 throw new Error(`${frameLabel(frame)} resolved absent session player ${JSON.stringify(binding.playerId)}`);
             }
+            if (options.freshPrompt !== undefined && typeof options.freshPrompt !== 'string') {
+                throw new TypeError('player freshPrompt must be a string');
+            }
             const expectedResume = ledger.resumeToken ?? false;
             if (options.resume !== expectedResume) {
                 throw new Error(`${frameLabel(frame)} player continuation changed before dispatch`);
@@ -2625,7 +2628,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                     const call = async (resume) => {
                         await continuity?.beforeCall(binding.playerId);
                         signal.throwIfAborted();
-                        const raw = await trackHostCall(frame, classifySettingsCall(() => context.callPlayer(binding.playerId, prompt, { resume, settings })));
+                        const raw = await trackHostCall(frame, classifySettingsCall(() => context.callPlayer(binding.playerId, resume === false ? options.freshPrompt ?? prompt : prompt, { resume, settings })));
                         hostResolved = true;
                         return raw;
                     };

package/reference/sdlc/code.playbook/playbook-captain.ts

@@ -4361,6 +4361,9 @@ export function createPlaybookCaptainShell(
           `${frameLabel(frame)} resolved absent session player ${JSON.stringify(binding.playerId)}`,
         );
       }
+      if (options.freshPrompt !== undefined && typeof options.freshPrompt !== 'string') {
+        throw new TypeError('player freshPrompt must be a string');
+      }
       const expectedResume = ledger.resumeToken ?? false;
       if (options.resume !== expectedResume) {
         throw new Error(
@@ -4394,7 +4397,7 @@ export function createPlaybookCaptainShell(
             const raw = await trackHostCall(
               frame,
               classifySettingsCall(() =>
-                context.callPlayer(binding.playerId, prompt, { resume, settings }),
+                context.callPlayer(binding.playerId, resume === false ? options.freshPrompt ?? prompt : prompt, { resume, settings }),
               ),
             );
             hostResolved = true;

package/reference/sdlc/decide.md

@@ -15,6 +15,8 @@ When the caller gives a topic, Captain shall relay the complete topic in quotes
 Captain shall not wait for either proposal before requesting the other.
 Captain shall give the player bound to each role the following instruction:
 
+> Original topic: <caller-topic>
+
 ```markdown
 Assess whether the topic is better expressed as a few spec items under @specs/packages/ or requires one or more DRs under @specs/decisions/.
 Propose your design.

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

@@ -7,7 +7,7 @@ import { assign, fromPromise, setup } from 'xstate';
 export const concurrentRoleSets = [['coder', 'reviewer']];
 const NEEDS_BOSS_REPLY_DESCRIPTION = "The acting agent's prose surfaces a clarifying question for Boss that the agent cannot answer alone. Output shall include `question: <verbatim question text from the acting agent's prose>`.";
 const INDEPENDENT_PROPOSAL_PROMPT = [
-    '> <caller-topic>',
+    '> Original topic: <caller-topic>',
     '',
     'Assess whether the topic is better expressed as a few spec items under @specs/packages/ or requires one or more DRs under @specs/decisions/.',
     'Propose your design.',

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

@@ -148,7 +148,7 @@ const NEEDS_BOSS_REPLY_DESCRIPTION =
   "The acting agent's prose surfaces a clarifying question for Boss that the agent cannot answer alone. Output shall include `question: <verbatim question text from the acting agent's prose>`.";
 
 const INDEPENDENT_PROPOSAL_PROMPT = [
-  '> <caller-topic>',
+  '> Original topic: <caller-topic>',
   '',
   'Assess whether the topic is better expressed as a few spec items under @specs/packages/ or requires one or more DRs under @specs/decisions/.',
   'Propose your design.',

package/reference/sdlc/decide.playbook/decide.gears.md

@@ -22,7 +22,7 @@ Parallel group: independent-proposals
 
 When the caller gives a topic, Captain shall relay the complete topic to Coder in quotes and prompt Coder:
 
-> > <caller-topic>
+> > Original topic: <caller-topic>
 >
 > Assess whether the topic is better expressed as a few spec items under @specs/packages/ or requires one or more DRs under @specs/decisions/.
 > Propose your design.
@@ -39,7 +39,7 @@ Parallel group: independent-proposals
 
 When the caller gives a topic, Captain shall relay the complete topic to Reviewer in quotes and prompt Reviewer:
 
-> > <caller-topic>
+> > Original topic: <caller-topic>
 >
 > Assess whether the topic is better expressed as a few spec items under @specs/packages/ or requires one or more DRs under @specs/decisions/.
 > Propose your design.

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

@@ -10,7 +10,7 @@ export interface DecidePlaybookRuntimeConstruction {
     readonly hostCapabilities: DecidePlaybookHostCapabilities;
 }
 type PromptIdentity = (roleId: RoleId) => string;
-declare function composePlayerPrompt(input: PlayerInput, promptIdentity: PromptIdentity): string;
+declare function composePlayerPrompt(input: PlayerInput, promptIdentity: PromptIdentity, resuming?: boolean): string;
 declare function requiredFieldsFor(description: string): string[];
 declare function extractJson(raw: string): Record<string, unknown> | null;
 declare function buildClassifierPrompt(text: string, ctx: {
@@ -67,7 +67,6 @@ export declare const _internal: {
     VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string>;
     BOSS_INTERRUPT_TARGETS: readonly ["independentProposals"];
     UNFINISHED_FINAL_STATE_IDS: ReadonlySet<string>;
-    CONTINUATION_PREAMBLE: string;
     TELEMETRY_TOPIC: string;
 };
 export default createPlaybookRuntime;

package/reference/sdlc/decide.playbook/decide.playbook.js

@@ -19,7 +19,7 @@ import { randomUUID } from 'node:crypto';
 import PQueue from 'p-queue';
 import { createActor, fromPromise } from 'xstate';
 import { createAcceptedOutcomeConsumer, } from '../../../src/accepted-outcome.js';
-import { assertJsonSafe, assertPlaybookEffectLedger, assertPlaybookRuntimeSnapshot, combineAbortSignals, createNestedPlaybookBridge, detachPersistedMachineSnapshot, normalizeError, normalizePlaybookSnapshot, PlaybookSemanticCandidateStructureError, reconcilePlaybookSemanticEvidence, renderGovernedOutcomeContract, snapshotJsonValue, snapshotPlaybookSession, terminalOutcomesFromMachine, validatePlayerResult, waitForPlaybookQuiescence, } from '../../../src/xstate-runtime.js';
+import { assertJsonSafe, assertPlaybookEffectLedger, assertPlaybookRuntimeSnapshot, combineAbortSignals, composePlayerContinuation, createNestedPlaybookBridge, detachPersistedMachineSnapshot, normalizeError, normalizePlaybookSnapshot, PlaybookSemanticCandidateStructureError, reconcilePlaybookSemanticEvidence, renderGovernedOutcomeContract, snapshotJsonValue, snapshotPlaybookSession, terminalOutcomesFromMachine, validatePlayerResult, waitForPlaybookQuiescence, } from '../../../src/xstate-runtime.js';
 import decideMachine from './decide.fsm.js';
 function snapshotDecideRuntimeOptions(value) {
     const captured = snapshotJsonValue(value, 'DECIDE runtime options');
@@ -125,7 +125,6 @@ const TELEMETRY_TOPIC = 'playbook.fsm.state';
 const TRACE_TOPIC = 'playbook.trace';
 const UNRESOLVED_EFFECT_RECONCILIATION_ACTION_ID = 'reconcile:unresolved-effect';
 const UNRESOLVED_EFFECT_ABANDONMENT_ACTION_ID = 'abandon:unresolved-effect';
-const CONTINUATION_PREAMBLE = 'You previously paused this task to ask Boss a question; Boss has now replied. Continue the same task using the reply below.';
 const PLACEHOLDER_FIELDS = [
     ['<caller-topic>', 'callerTopic'],
     ['<reviewer-proposal>', 'reviewerProposal'],
@@ -135,19 +134,7 @@ const VERBATIM_PAYLOAD_FIELDS = new Set([
     'reviewerProposal',
     'coderOutput',
 ]);
-function composePlayerPrompt(input, promptIdentity) {
-    const blocks = [];
-    if (input.pendingBossQuestion && input.bossReply !== undefined) {
-        blocks.push([
-            CONTINUATION_PREAMBLE,
-            '',
-            'Boss question:',
-            input.pendingBossQuestion.question,
-            '',
-            'Boss reply:',
-            input.bossReply,
-        ].join('\n'));
-    }
+function composePlayerPrompt(input, promptIdentity, resuming = false) {
     const replacements = new Map();
     for (const [placeholder, field] of PLACEHOLDER_FIELDS) {
         const value = input[field];
@@ -171,8 +158,7 @@ function composePlayerPrompt(input, promptIdentity) {
             ? value.replaceAll('\n', '\n> ')
             : value;
     });
-    blocks.push(body);
-    return blocks.join('\n\n');
+    return composePlayerContinuation(input, body, resuming);
 }
 // A `result` description names required payload fields in its
 // "Output shall include ..." sentence.
@@ -883,7 +869,7 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
     };
     const resolvedPlayerId = (roleId) => requireSessionIdentity().roleBindings?.[roleId]?.playerId;
     const promptIdentity = (roleId) => requireSessionIdentity().roleBindings?.[roleId]?.promptIdentity ?? roleId;
-    const composeInvocationPrompt = (input) => {
+    const composeInvocationPrompt = (input, resuming = false) => {
         let active = true;
         const lookup = (roleId) => {
             if (!active) {
@@ -895,7 +881,7 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
             return promptIdentity(roleId);
         };
         try {
-            return composePlayerPrompt(input, lookup);
+            return composePlayerPrompt(input, lookup, resuming);
         }
         finally {
             active = false;
@@ -1339,7 +1325,7 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
         const roleId = input.role;
         const playerId = resolvedPlayerId(roleId);
         const playerKey = continuationKey(roleId, playerId);
-        const prompt = composeInvocationPrompt(input);
+        const freshPrompt = composeInvocationPrompt(input);
         let resume;
         try {
             signal.throwIfAborted();
@@ -1353,6 +1339,7 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
             latchControlPlaneError(error, signal);
             throw error;
         }
+        const prompt = resume === false ? freshPrompt : composeInvocationPrompt(input, true);
         const callId = continuation?.callId ?? `player-${++playerCallSequence}`;
         const identity = {
             stateId: input.stateId,
@@ -1384,7 +1371,7 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
             let rawResult;
             try {
                 signal.throwIfAborted();
-                const boundary = Promise.resolve(requirePorts().callPlayer(roleId, prompt, signal, { resume }));
+                const boundary = Promise.resolve(requirePorts().callPlayer(roleId, prompt, signal, { resume, ...(prompt === freshPrompt ? {} : { freshPrompt }) }));
                 rawResult = await boundary;
                 // An XState sibling cancellation does not cancel an arbitrary coder
                 // promise. Re-check before a late resolution can mutate continuity or
@@ -3586,7 +3573,6 @@ export const _internal = {
     VERBATIM_PAYLOAD_FIELDS,
     BOSS_INTERRUPT_TARGETS,
     UNFINISHED_FINAL_STATE_IDS,
-    CONTINUATION_PREAMBLE,
     TELEMETRY_TOPIC,
 };
 export default createPlaybookRuntime;

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

@@ -32,6 +32,7 @@ import {
   assertPlaybookEffectLedger,
   assertPlaybookRuntimeSnapshot,
   combineAbortSignals,
+  composePlayerContinuation,
   createNestedPlaybookBridge,
   detachPersistedMachineSnapshot,
   normalizeError,
@@ -286,8 +287,6 @@ const UNRESOLVED_EFFECT_RECONCILIATION_ACTION_ID =
 const UNRESOLVED_EFFECT_ABANDONMENT_ACTION_ID =
   'abandon:unresolved-effect';
 
-const CONTINUATION_PREAMBLE =
-  'You previously paused this task to ask Boss a question; Boss has now replied. Continue the same task using the reply below.';
 
 const PLACEHOLDER_FIELDS: ReadonlyArray<readonly [string, keyof PlayerInput]> =
   [
@@ -306,23 +305,8 @@ type PromptIdentity = (roleId: RoleId) => string;
 function composePlayerPrompt(
   input: PlayerInput,
   promptIdentity: PromptIdentity,
+  resuming = false,
 ): string {
-  const blocks: string[] = [];
-
-  if (input.pendingBossQuestion && input.bossReply !== undefined) {
-    blocks.push(
-      [
-        CONTINUATION_PREAMBLE,
-        '',
-        'Boss question:',
-        input.pendingBossQuestion.question,
-        '',
-        'Boss reply:',
-        input.bossReply,
-      ].join('\n'),
-    );
-  }
-
   const replacements = new Map<string, string>();
   for (const [placeholder, field] of PLACEHOLDER_FIELDS) {
     const value = input[field];
@@ -348,8 +332,7 @@ function composePlayerPrompt(
     },
   );
 
-  blocks.push(body);
-  return blocks.join('\n\n');
+  return composePlayerContinuation(input, body, resuming);
 }
 
 // A `result` description names required payload fields in its
@@ -1518,7 +1501,7 @@ function createDecidePlaybookRuntime(
   const promptIdentity = (roleId: RoleId): string =>
     requireSessionIdentity().roleBindings?.[roleId]?.promptIdentity ?? roleId;
 
-  const composeInvocationPrompt = (input: PlayerInput): string => {
+  const composeInvocationPrompt = (input: PlayerInput, resuming = false): string => {
     let active = true;
     const lookup: PromptIdentity = (roleId) => {
       if (!active) {
@@ -1534,7 +1517,7 @@ function createDecidePlaybookRuntime(
       return promptIdentity(roleId);
     };
     try {
-      return composePlayerPrompt(input, lookup);
+      return composePlayerPrompt(input, lookup, resuming);
     } finally {
       active = false;
     }
@@ -2182,7 +2165,7 @@ function createDecidePlaybookRuntime(
     const roleId = input.role;
     const playerId = resolvedPlayerId(roleId);
     const playerKey = continuationKey(roleId, playerId);
-    const prompt = composeInvocationPrompt(input);
+    const freshPrompt = composeInvocationPrompt(input);
     let resume: PlayerCallOptions['resume'];
     try {
       signal.throwIfAborted();
@@ -2195,6 +2178,7 @@ function createDecidePlaybookRuntime(
       latchControlPlaneError(error, signal);
       throw error;
     }
+    const prompt = resume === false ? freshPrompt : composeInvocationPrompt(input, true);
     const callId =
       continuation?.callId ?? `player-${++playerCallSequence}`;
     const identity = {
@@ -2249,7 +2233,7 @@ function createDecidePlaybookRuntime(
       try {
         signal.throwIfAborted();
         const boundary = Promise.resolve(
-          requirePorts().callPlayer(roleId, prompt, signal, { resume }),
+          requirePorts().callPlayer(roleId, prompt, signal, { resume, ...(prompt === freshPrompt ? {} : { freshPrompt }) }),
         );
         rawResult = await boundary;
         // An XState sibling cancellation does not cancel an arbitrary coder
@@ -5081,7 +5065,6 @@ export const _internal = {
   VERBATIM_PAYLOAD_FIELDS,
   BOSS_INTERRUPT_TARGETS,
   UNFINISHED_FINAL_STATE_IDS,
-  CONTINUATION_PREAMBLE,
   TELEMETRY_TOPIC,
 };
 

package/reference/sdlc/dev.md

@@ -15,6 +15,10 @@ It coordinates existing playbooks and owns no repository commit itself.
 
 At the start of `dev` and after each Boss reply, Captain shall relay the development request, relevant discussion context, and any relevant run results to Analyst in quotes (`>`), along with the following instruction:
 
+> Original request: <development-request>
+> Prior discussion: <discussion-context>
+> Run results: <run-results>
+
 ```markdown
 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.
@@ -35,15 +39,31 @@ No outcome depends on a fixed presentation format of Analyst's reply.
 `dev` shall act on the accepted outcome itself and shall not return to the session Captain for another routing decision.
 
 For needs Boss reply, `dev` shall use the standard Boss-question suspension with Analyst's complete response.
-The session Captain shall present that response to Boss and, after Boss replies, resume `dev` with the question and answer in the same Analyst conversation.
+The session Captain shall present that response to Boss and, after Boss replies, resume `dev` with the answer in the same Analyst conversation; include the previous question only when that conversation must start fresh.
 
 Discussion complete is available only after a Boss reply, when any useful analysis has already been presented through needs Boss reply.
 It completes `dev` without a child call or repository change.
 
 For code, `dev` shall directly call playbook `code` with the development request, relevant discussion context, and planning result in quotes (`>`).
 
+> Original request: <development-request>
+> Prior discussion: <discussion-context>
+> Planning result: <planning-result>
+
 For decide then code, `dev` shall call playbook `decide` with the development request, relevant discussion context, and planning result in quotes (`>`).
+
+> Original request: <development-request>
+> Prior discussion: <discussion-context>
+> Planning result: <planning-result>
+
 Only after `decide` succeeds shall `dev` call playbook `code` with the development request, relevant discussion context, planning result, `decide`-owned commit, and exact evaluated repository revision in quotes (`>`).
+
+> Original request: <development-request>
+> Prior discussion: <discussion-context>
+> Planning result: <planning-result>
+> DECIDE commit: <decide-commit>
+> Evaluated revision: <evaluated-revision>
+
 `dev` shall not separately call `review` for the design scope already reviewed by `decide`.
 
 `dev` completes with the successful result of its final child call.

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

@@ -4,9 +4,9 @@
 // Generated by slc/gears2fsm.md from ./dev.gears.md.
 import { assign, fromPromise, setup } from 'xstate';
 const PLAN_ANALYSIS_PROMPT = [
-    '> <development-request>',
-    '> <discussion-context>',
-    '> <run-results>',
+    '> Original request: <development-request>',
+    '> Prior discussion: <discussion-context>',
+    '> Run results: <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.',
@@ -334,8 +334,8 @@ function archivedExchanges(context) {
 }
 function quotedRelay(values) {
     return values
-        .filter((value) => value.length > 0)
-        .map((value) => value
+        .filter(([, value]) => value.length > 0)
+        .map(([label, value]) => `${label}: ${value}`
         .split('\n')
         .map((line) => `> ${line}`)
         .join('\n'))
@@ -343,9 +343,9 @@ function quotedRelay(values) {
 }
 function planningRelayValues(context) {
     return [
-        context.developmentRequest ?? '',
-        renderDiscussionContext(context.discussionExchanges),
-        context.planningResult ?? '',
+        ['Original request', context.developmentRequest ?? ''],
+        ['Prior discussion', renderDiscussionContext(context.discussionExchanges)],
+        ['Planning result', context.planningResult ?? ''],
     ];
 }
 function codeCallText(context) {
@@ -357,8 +357,8 @@ function decideCallText(context) {
 function codeAfterDecideCallText(context) {
     return quotedRelay([
         ...planningRelayValues(context),
-        context.decideCommit ?? '',
-        context.evaluatedRevision ?? '',
+        ['DECIDE commit', context.decideCommit ?? ''],
+        ['Evaluated revision', context.evaluatedRevision ?? ''],
     ]);
 }
 const machineSetup = setup({