@sublang/playbook 12.3.0 → 13.1.0

package/reference/sdlc/code.playbook/session-host.d.ts

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+import type { PlaybookCaptainShell, PlaybookCaptainShellSnapshot } from './playbook-captain.js';
+import type { PlaybookEffectLedger } from './host-capabilities.js';
+import type { PlaybookSessionLifecycle, SessionExecutionProjection, SessionStructuralProjection, SessionFreshBoundary, SessionRecovery } from './session-store.js';
+
+export interface SessionHost {
+  readonly shell: PlaybookCaptainShell;
+  readonly host: { runBossTurn(input: string): Promise<void>; abortActiveTurn(): void; dispose(): Promise<void>; [key: string]: any };
+  readonly snapshot: PlaybookCaptainShellSnapshot;
+  reconcileRepositoryEffects(): Promise<PlaybookEffectLedger>;
+}
+export interface SessionHostOptions {
+  readonly config: SessionExecutionProjection;
+  readonly sessionId?: string;
+  readonly cwd: string;
+  readonly sessionLease: PlaybookSessionLifecycle;
+  readonly loadModule: (specifier: string) => Promise<any>;
+  readonly restoreSnapshot?: PlaybookCaptainShellSnapshot;
+  readonly reconcileUncertainTurnReplay?: boolean;
+  readonly signal?: AbortSignal;
+  readonly [key: string]: any;
+}
+export declare function createCaptainSessionHost(options: SessionHostOptions): Promise<SessionHost>;
+export declare function installRetainedGenerationsForLaunch(options: {
+  lease: PlaybookSessionLifecycle;
+  shell: PlaybookCaptainShell;
+  freshBoundary?: SessionFreshBoundary;
+  onFreshRecord?: (record: SessionRecovery | undefined) => void;
+  onLegacyRecord?: (record: any) => void | Promise<void>;
+  onInvalidRecord?: (record: any) => void | Promise<void>;
+  retainedGenerations?: Readonly<Record<string, any>>;
+  reconcileRepositoryEffects?: () => Promise<PlaybookEffectLedger>;
+}): Promise<Readonly<Record<string, any>>>;
+export declare function executionConfigFromPlan(plan: any): SessionExecutionProjection;
+export declare function validateFrozenExecutionConfig(structural: SessionStructuralProjection, execution: SessionExecutionProjection, dependencies: { loadModule: (specifier: string) => Promise<any>; prepareRegistryModule?: (request: {id: string; from: string; authoredFrom: string}) => Promise<string | void> }): Promise<SessionExecutionProjection>;
+export declare function driveHeadlessCaptainTurn(options: any): Promise<any>;
+export declare function normalizeLaunchPlan(top: any, options?: any): Promise<any>;
+export declare function loadLaunchPlan(options: any): Promise<any>;
+export declare function composeGenericConfig(top: any, loadModule: (specifier: string) => Promise<any>, configPath?: string): Promise<any>;
+export declare function projectTmuxConfig(plan: any): any;
+export declare function resolveLaunchSessionsDir(options: any): string;
+
+import type { SharedSessionStore, ReplayStreamStatus, ReplayStreamEntry, SessionGraph } from './session-store.js';
+export interface OpenSessionHostOptions {
+  readonly store?: SharedSessionStore;
+  readonly sessionsDir?: string;
+  readonly sessionId?: string;
+  readonly mode?: 'new' | 'continue' | 'retry';
+  readonly cwd?: string;
+  readonly config?: SessionExecutionProjection;
+  readonly plan?: any;
+  readonly loadModule?: (specifier: string) => Promise<any>;
+  readonly prepareRegistryModule?: (request: {id: string; from: string; authoredFrom: string}) => Promise<string | void>;
+  readonly observers?: readonly { onRecord?(record: any): void | Promise<void> }[];
+  readonly onStoredRecord?: (record: ReplayStreamEntry, status: ReplayStreamStatus) => void | Promise<void>;
+  readonly onCheckpoint?: (record: SessionRecovery) => void | Promise<void>;
+  readonly onIncomplete?: () => void | Promise<void>;
+  readonly graphs?: readonly { playbookId: string; graph: SessionGraph | null }[];
+  readonly initialVisible?: readonly string[];
+  readonly [key: string]: any;
+}
+export interface SessionHostController {
+  readonly sessionId: string;
+  readonly host: SessionHost['host'];
+  readonly shell: PlaybookCaptainShell;
+  readonly lease: PlaybookSessionLifecycle;
+  read(): Promise<SessionRecovery | undefined>;
+  handleBossTurn(input: string): Promise<SessionRecovery>;
+  retry(): Promise<SessionRecovery>;
+  dispose(): Promise<void>;
+}
+export declare function openSessionHost(options: OpenSessionHostOptions): Promise<SessionHostController>;
+export declare function discardSessionUncertain(store: SharedSessionStore, sessionId: string): Promise<SessionRecovery | undefined>;

package/reference/sdlc/code.playbook/session-host.js

@@ -0,0 +1,18 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+export {
+  createCaptainSessionHost,
+  installRetainedGenerationsForLaunch,
+  executionConfigFromPlan,
+  validateFrozenExecutionConfig,
+  driveHeadlessCaptainTurn,
+} from './bin/run.js';
+export {
+  normalizeLaunchPlan,
+  loadLaunchPlan,
+  composeGenericConfig,
+  projectTmuxConfig,
+  resolveLaunchSessionsDir,
+} from './bin/launch-config.js';
+export { openSessionHost, discardSessionUncertain } from './bin/session-host.js';

package/reference/sdlc/code.playbook/session-store.d.ts

@@ -48,7 +48,7 @@ export type ReplayStreamStatus =
 export interface PlaybookSessionSummary {
   readonly schemaVersion: number;
   readonly sessionId: string;
-  readonly state: 'settled' | 'uncertain';
+  readonly state: 'settled' | 'uncertain' | 'history-only';
   readonly cwd: string;
   readonly updatedAt: string;
 }
@@ -80,3 +80,178 @@ export interface PlaybookSessionLease {
   streamStatus(): ReplayStreamStatus;
   release(): Promise<ReplayStreamStatus>;
 }
+
+/** Recovery data is interpreted by the version-aware codec, not by live runtimes. */
+export type SessionSnapshot = Readonly<Record<string, any>>;
+export interface SessionEffectLedger {
+  readonly schemaVersion: 1;
+  readonly revision: number;
+  readonly boundaries: readonly Readonly<Record<string, any>>[];
+  readonly logicalOperations: readonly Readonly<Record<string, any>>[];
+}
+export interface SessionUnresolvedEffect {
+  readonly classification: 'one-descendant-commit' | 'multiple-commits' |
+    'rewritten-or-non-descendant' | 'worktree-only-change' |
+    'concurrent-or-foreign-change' | 'observation-ambiguous' | 'incomplete';
+  readonly baselineHead: string;
+  readonly afterHead?: string;
+  readonly commitOid?: string;
+}
+export type SessionRetentionUpdate =
+  | { readonly kind: 'retain'; readonly rootPlaybookId: string; readonly generation: Readonly<Record<string, any>> }
+  | { readonly kind: 'clear'; readonly rootPlaybookId: string };
+
+export interface SessionExecutionProjection {
+  readonly schemaVersion: 2;
+  readonly captain: Readonly<Record<string, any>>;
+  readonly players: readonly Readonly<Record<string, any>>[];
+  readonly catalog: Readonly<Record<string, any>>;
+}
+export interface SessionStructuralProjection {
+  readonly schemaVersion: 1;
+  readonly captain: Readonly<Record<string, any>>;
+  readonly players: readonly Readonly<Record<string, any>>[];
+  readonly catalog: Readonly<Record<string, any>>;
+}
+export interface SessionRecovery {
+  readonly schemaVersion: 6;
+  readonly kind: 'captain-session';
+  readonly sessionId: string;
+  readonly cwd: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  readonly state: 'settled' | 'uncertain';
+  readonly structuralProjection: SessionStructuralProjection;
+  readonly lastAppliedExecutionProjection: SessionExecutionProjection;
+  readonly snapshot: SessionSnapshot;
+  readonly effectLedger: SessionEffectLedger;
+  readonly unresolvedEffects: readonly SessionUnresolvedEffect[];
+  readonly retainedGenerations?: Readonly<Record<string, any>>;
+  readonly uncertain?: {
+    readonly input: string;
+    readonly attemptId: string;
+    readonly attemptNumber: number;
+    readonly baseUpdatedAt: string | null;
+    readonly markedAt: string;
+    readonly attemptedExecutionProjection: SessionExecutionProjection;
+    readonly abandonment?: Readonly<Record<string, any>>;
+  };
+}
+export interface SessionReplayCheckpoint {
+  readonly seq: number;
+  readonly sha256: string;
+  readonly incomplete: boolean;
+}
+export type SessionManifest = Omit<SessionRecovery, 'schemaVersion'> & {
+  readonly schemaVersion: 7;
+  readonly replay: SessionReplayCheckpoint;
+  readonly contextSeq: number;
+} | {
+  readonly schemaVersion: 7;
+  readonly kind: 'captain-session';
+  readonly state: 'history-only';
+  readonly sessionId: string;
+  readonly cwd: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  readonly replay: SessionReplayCheckpoint;
+  readonly contextSeq: number | null;
+  readonly reason: string;
+};
+export type StoredSessionManifest = SessionManifest | {
+  readonly schemaVersion: number;
+  readonly sessionId: string;
+  readonly cwd?: unknown;
+  readonly [key: string]: unknown;
+};
+export interface SessionGraph {
+  readonly initial: string;
+  readonly nodes: readonly { readonly id: string; readonly kind: 'state' | 'final'; readonly tags: readonly string[]; readonly parent?: string; readonly role?: string; readonly description?: string }[];
+  readonly edges: readonly { readonly id: string; readonly from: string; readonly to: string; readonly event: string }[];
+}
+export interface SessionContext {
+  readonly type: 'session_context';
+  readonly timestamp: number;
+  readonly contextVersion: 1;
+  readonly captainId: string;
+  readonly configuration: SessionExecutionProjection;
+  readonly graphs: readonly { readonly playbookId: string; readonly graph: SessionGraph | null }[];
+  readonly initialVisible: readonly string[];
+}
+export interface SessionHistory extends ReplayStreamReadResult {
+  readonly synthetic?: true;
+  readonly missing: boolean;
+  readonly incomplete: boolean;
+  readonly pendingTail: boolean;
+  readonly damage?: { readonly seq: number; readonly offset: number; readonly reason: string };
+  readonly digests: readonly string[];
+  readonly completeBytes: number;
+}
+export interface SessionValidation {
+  readonly integrityValid: boolean;
+  readonly sessionId: string;
+  readonly resumable: boolean;
+  readonly reasons: readonly string[];
+  readonly manifest: StoredSessionManifest;
+  readonly history: SessionHistory;
+}
+export interface SessionHints {
+  readonly players: Readonly<Record<string, string>>;
+  readonly captain?: { readonly kind: 'pinned'; readonly token: string } | { readonly kind: 'needsCatchUp'; readonly resume: string | false; readonly afterJournalSeq: number };
+}
+export interface SessionFreshBoundary {
+  readonly cwd: string;
+  readonly structuralProjection: SessionStructuralProjection;
+  readonly executionProjection: SessionExecutionProjection;
+  readonly snapshot: SessionSnapshot;
+  readonly context?: SessionContext;
+  readonly onLegacyRecord?: (record: any) => void | Promise<void>;
+  readonly onInvalidRecord?: (record: any) => void | Promise<void>;
+}
+export interface PlaybookSessionLifecycle extends PlaybookSessionLease {
+  read(): Promise<SessionRecovery | undefined>;
+  readManifest(): Promise<StoredSessionManifest>;
+  initializeSettledWithPredecessor(options: SessionFreshBoundary): Promise<SessionRecovery>;
+  abandonFreshSettled(options: { expected: SessionRecovery }): Promise<boolean>;
+  beginTurn(options: { input: string; attemptId: string; attemptedExecutionProjection: SessionExecutionProjection }): Promise<SessionRecovery>;
+  beginRetry(options: { expectedAttemptId: string; nextAttemptId: string }): Promise<SessionRecovery>;
+  settle(options: { attemptId: string; snapshot: SessionSnapshot; unresolvedEffects: readonly SessionUnresolvedEffect[]; retentionUpdates?: readonly SessionRetentionUpdate[] }): Promise<SessionRecovery>;
+  discard(options: { attemptId: string }): Promise<SessionRecovery | undefined>;
+  beginUnresolvedEffectAbandonment(options: any): Promise<any>;
+  completeUnresolvedEffectAbandonment(options: any): Promise<any>;
+  recoverUnresolvedEffectAbandonment(): Promise<SessionRecovery | undefined>;
+  writeEffectLedger(authority: any, commands: readonly Readonly<Record<string, any>>[]): Promise<SessionEffectLedger>;
+  assertOwner(): Promise<any>;
+  assertContinuable(context?: { cwd?: string; executionProjection?: SessionExecutionProjection }): Promise<SessionValidation>;
+  recordContext(context: SessionContext): Promise<number>;
+  consumeHints(): Promise<SessionHints>;
+  acknowledgeHint(participantId: string, token: string): void;
+  clearHint(participantId: string): void;
+}
+export interface SharedSessionStore {
+  readonly sessionsDir: string;
+  prepare(): Promise<void>;
+  read(sessionId: string): Promise<SessionRecovery>;
+  readManifest(sessionId: string): Promise<StoredSessionManifest>;
+  /** Observation only; mutations still require acquiring the lease. */
+  readLeaseState(sessionId: string): Promise<'active' | 'idle' | 'unknown'>;
+  readHistory(sessionId: string, options?: ReplayStreamReadOptions): Promise<SessionHistory>;
+  readStream(sessionId: string, options?: ReplayStreamReadOptions): Promise<ReplayStreamReadResult>;
+  readSummary(sessionId: string): Promise<PlaybookSessionSummary>;
+  listSummaries(): Promise<PlaybookSessionListResult>;
+  latest(options?: { preferredCwd?: string; onLegacyRecord?: (record: any) => void | Promise<void> }): Promise<SessionRecovery>;
+  acquire(sessionId: string): Promise<PlaybookSessionLifecycle>;
+  acquireManagement(sessionId: string): Promise<{ readonly sessionId: string; readonly ownerToken: string; assertOwner(): Promise<unknown>; release(): Promise<void> }>;
+  validate(sessionId: string, context?: { cwd?: string; executionProjection?: SessionExecutionProjection }): Promise<SessionValidation>;
+  delete(sessionId: string): Promise<void>;
+  migrateLegacyDefault(options?: { env?: Readonly<Record<string, string | undefined>>; homeDir?: string }): Promise<{ sourceDir: string; migrated: readonly string[]; skipped: readonly { sessionId: string; reason: string }[] }>;
+  migrate(sessionId: string, options?: { sourcePath?: string; cwd?: string; backupDir?: string }): Promise<{ manifest: SessionManifest; migrated: boolean; reasons: readonly string[] }>;
+}
+export declare function createSessionStore(options?: { sessionsDir?: string; env?: Readonly<Record<string, string | undefined>>; homeDir?: string; [key: string]: any }): SharedSessionStore;
+export declare function validateSessionManifest(value: unknown): SessionManifest;
+export declare function validateSessionContext(value: unknown): SessionContext;
+export declare function projectCaptainSessionStructure(value: SessionExecutionProjection): SessionStructuralProjection;
+export declare function validateCaptainSessionExecutionProjection(value: unknown): SessionExecutionProjection;
+export declare function validateCaptainSessionStructuralProjection(value: unknown): SessionStructuralProjection;
+export declare function assertCaptainSessionExecutionCompatible(structural: SessionStructuralProjection, execution: SessionExecutionProjection): SessionExecutionProjection;
+export declare function attachSessionHints(snapshot: SessionSnapshot, hints: SessionHints): SessionSnapshot;

package/reference/sdlc/code.playbook/session-store.js

@@ -21,14 +21,17 @@ export function openSessionStore(sessionsDir) {
 }
 
 function wrapStore(store) {
+  let preparation;
+  const prepared = async (operation) => {
+    await (preparation ??= store.prepare());
+    return operation();
+  };
   return Object.freeze({
     sessionsDir: store.sessionsDir,
-    list: async () => projectListResult(await store.listSummaries()),
-    read: async (sessionId) =>
-      projectSummary(await store.readSummary(sessionId)),
-    readStream: async (sessionId, options) =>
-      projectReadResult(await store.readStream(sessionId, options)),
-    acquire: async (sessionId) => wrapLease(await store.acquire(sessionId)),
+    list: () => prepared(async () => projectListResult(await store.listSummaries())),
+    read: (sessionId) => prepared(async () => projectSummary(await store.readSummary(sessionId))),
+    readStream: (sessionId, options) => prepared(async () => projectReadResult(await store.readStream(sessionId, options))),
+    acquire: (sessionId) => prepared(async () => wrapLease(await store.acquire(sessionId))),
   });
 }
 
@@ -111,3 +114,16 @@ function projectStatus(status) {
     incomplete: status.incomplete,
   });
 }
+
+export {
+  createCaptainSessionStore as createSessionStore,
+  projectCaptainSessionStructure,
+  validateCaptainSessionExecutionProjection,
+  validateCaptainSessionStructuralProjection,
+  assertCaptainSessionExecutionCompatible,
+} from './bin/session-store.js';
+export {
+  validateSessionManifest,
+  validateSessionContext,
+  attachSessionHints,
+} from './bin/portable-codec.js';

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.