@sublang/playbook 13.2.0 → 14.0.0

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

@@ -24,6 +24,7 @@ import type {
   PlaybookCallRequest,
   PlaybookCallResult,
   PlaybookCallStart,
+  PlaybookControlAction,
   PlaybookControlView,
   PlaybookPorts,
   PlaybookRunResult,
@@ -353,6 +354,31 @@ export interface PlaybookCaptainShell extends Captain {
     session: CaptainSession,
     snapshot: PlaybookCaptainShellSnapshot,
   ): Promise<void>;
+  /**
+   * The active leaf's currently advertised runtime actions, as the host's own
+   * reading of the control view the ControlView digest reads (CAPTAIN-60).
+   * Declared optional because capability absence is member absence: a shell
+   * that publishes no reader advertises nothing.
+   */
+  describeRuntimeActions?(): readonly PlaybookControlAction[];
+  /**
+   * Select one currently advertised runtime action as the next Boss turn's
+   * decision and return that turn's Boss text, which the host submits through
+   * `handleBossTurn` (CAPTAIN-7).
+   */
+  submitRuntimeAction?(actionId: string): string;
+  /**
+   * The controls the shell effects on its own behalf, disjoint from the leaf's
+   * advertised runtime actions (CAPTAIN-62). Declared optional for the same
+   * reason: a shell that publishes no reader advertises nothing.
+   */
+  describeShellActions?(): readonly PlaybookControlAction[];
+  /**
+   * Select one currently advertised shell control as the next Boss turn's
+   * decision and return that turn's Boss text, which the host submits through
+   * `handleBossTurn` (CAPTAIN-7).
+   */
+  submitShellAction?(actionId: string): string;
 }
 
 // Per-enabled-playbook binding the shell resolves at init from the exact
@@ -575,6 +601,9 @@ function isCanonicalLocalRoleId(value: unknown): value is string {
 const UNRESOLVED_EFFECT_RECONCILIATION_ACTION_ID =
   'reconcile:unresolved-effect';
 const UNRESOLVED_EFFECT_ABANDONMENT_ACTION_ID = 'abandon:unresolved-effect';
+// CAPTAIN-62: the shell's own control, not a runtime action. The id is machine
+// data the host echoes back; the Boss never sees it (CAPPLAY-5).
+const GIVE_UP_ACTION_ID = 'give-up';
 // The fixed machine-syntax guard of a player's Boss-question suspension
 // (slc/link.md §Boss-reply suspension): the accepted outcome that parks on
 // Boss rather than sparing Boss a relay.
@@ -608,6 +637,19 @@ interface ActiveTurn {
    */
   readonly authoritativeText: string;
   readonly resolution?: CaptainParsedResolution;
+  /**
+   * The advertised action id the host selected for this turn (CAPTAIN-7). Its
+   * presence is the turn's decision: the decision state receives that
+   * selection from the shell and allocates no decision call.
+   */
+  readonly hostRuntimeActionId?: string;
+  /**
+   * Set where the host decided this turn by selecting the shell's own give-up
+   * control (CAPTAIN-62). Like `hostRuntimeActionId` its presence is the
+   * turn's decision, and it additionally settles the result phase in the shell
+   * so the turn makes no model call at all (CAPTAIN-63).
+   */
+  readonly hostGiveUp?: true;
   /** A settlement with status `ok` is final for the turn (DR-029). */
   settled: boolean;
   /**
@@ -3118,6 +3160,15 @@ export function createPlaybookCaptainShell(
         outcome: DurableCallOutcome;
       }
     | undefined;
+  // CAPTAIN-7: the control the host selected for the turn it is about to
+  // submit, held with the exact Boss text that turn carries so an unrelated
+  // turn never consumes the selection. One turn consumes it, whichever it is,
+  // and one slot holds it whichever surface it came from — the leaf's
+  // advertised actions or the shell's own controls (CAPTAIN-62).
+  let pendingHostSelection:
+    | { readonly kind: 'runtime'; readonly actionId: string; readonly text: string }
+    | { readonly kind: 'give-up'; readonly text: string }
+    | undefined;
   let lastAction: ControllerAction | undefined;
   let lastSettlementStatus: SettlementEvidence['status'] | undefined;
   // DR-038 §2: a turn can dispose its root before the durable caller asks
@@ -5178,6 +5229,7 @@ export function createPlaybookCaptainShell(
   const settleUnresolvedEffectAbandonment = async (
     unresolvedLeaf: EngagementFrame,
   ): Promise<void> => {
+    abandonmentSettlementUnsafe = true;
     if (leafFrame() !== unresolvedLeaf) {
       throw new Error(
         'unresolved-effect abandonment requires the active leaf',
@@ -5212,6 +5264,7 @@ export function createPlaybookCaptainShell(
       rootPlaybookId,
     });
     await runEffect(() => unresolvedEffectSettlement.complete(settlement));
+    abandonmentSettlementUnsafe = false;
   };
 
   const callResultFor = (
@@ -5900,6 +5953,132 @@ export function createPlaybookCaptainShell(
     return lines.join('\n');
   };
 
+  // CAPTAIN-60: the same reading the ControlView digest performs, published as
+  // data instead of prose. It states what the digest states and withholds what
+  // the digest withholds: an idle shell, a leaf with no control surface, and a
+  // control view that cannot be read all advertise nothing, and a leaf fenced
+  // for repository-effect reconciliation advertises only its fence controls.
+  // The pairs are detached and frozen, so a host holds the shell's reading
+  // rather than a live view the runtime can rewrite underneath it.
+  const advertisedRuntimeActions = (): readonly PlaybookControlAction[] => {
+    const empty: readonly PlaybookControlAction[] = Object.freeze([]);
+    if (lifecycle !== 'ready' || terminallyDisposed) return empty;
+    // Between turns: while a turn is running, the leaf's control view is the
+    // decision's grounding and the host can act on no selection, so the shell
+    // publishes none and reads nothing from a runtime mid-run.
+    if (activeTurn !== undefined || activeTurnHostCalls !== undefined) {
+      return empty;
+    }
+    const leaf = leafFrame();
+    if (!leaf || typeof leaf.runtime.describe !== 'function') return empty;
+    refreshRetainedEffectFence();
+    const fenced = retainedEffectReconciliation !== undefined;
+    if (fenced && typeof leaf.runtime.apply !== 'function') return empty;
+    let actions: readonly PlaybookControlAction[];
+    try {
+      actions = leaf.runtime.describe().actions;
+    } catch {
+      // An unreadable control view advertises nothing.
+      return empty;
+    }
+    return Object.freeze(
+      actions
+        .filter(
+          (action) =>
+            !fenced ||
+            action.id === UNRESOLVED_EFFECT_RECONCILIATION_ACTION_ID ||
+            action.id === UNRESOLVED_EFFECT_ABANDONMENT_ACTION_ID,
+        )
+        .map((action) => Object.freeze({ id: action.id, label: action.label })),
+    );
+  };
+
+  // CAPTAIN-62: the controls the shell effects itself, published beside the
+  // leaf's advertised actions and never mixed with them — these are the
+  // shell's own, so an engaged root offers one whatever its leaf advertises,
+  // fenced or not. A fenced root keeps its control because giving up reports
+  // unresolved effects (CAPTAIN-58) rather than reconciling them, and a run
+  // whose effects are unknown is exactly the run a Boss gives up on.
+  const advertisedShellActions = (): readonly PlaybookControlAction[] => {
+    const empty: readonly PlaybookControlAction[] = Object.freeze([]);
+    if (lifecycle !== 'ready' || terminallyDisposed) return empty;
+    // Between turns, on the same rule the leaf's actions take: mid-turn the
+    // host can act on no selection.
+    if (activeTurn !== undefined || activeTurnHostCalls !== undefined) {
+      return empty;
+    }
+    const root = rootFrame();
+    if (!root) return empty;
+    return Object.freeze([
+      Object.freeze({
+        id: GIVE_UP_ACTION_ID,
+        // The label is the turn's durable Boss text, so it names the run the
+        // way the Boss started it rather than the frame that happens to be
+        // parked inside it.
+        label: `Stop ${frameLabel(root)}`,
+      }),
+    ]);
+  };
+
+  // CAPTAIN-7: the host's selection of the shell's own control, validated here
+  // against the same live reading. The returned text is the turn the host
+  // submits, exactly as for an advertised runtime action.
+  const selectShellAction = (actionId: string): string => {
+    if (lifecycle !== 'ready' || terminallyDisposed) {
+      throw new Error(
+        'a shell control requires an initialized or restored Captain shell',
+      );
+    }
+    if (activeTurn !== undefined || activeTurnHostCalls !== undefined) {
+      throw new Error('a shell control cannot be selected during a Boss turn');
+    }
+    if (typeof actionId !== 'string' || actionId.length === 0) {
+      throw new TypeError('a shell control id must be a nonempty string');
+    }
+    const advertised = advertisedShellActions().find(
+      (action) => action.id === actionId,
+    );
+    if (advertised === undefined) {
+      throw new Error('the shell does not advertise that control');
+    }
+    pendingHostSelection = { kind: 'give-up', text: advertised.label };
+    return advertised.label;
+  };
+
+  // CAPTAIN-7: the host's own selection of one advertised action, validated
+  // here against the same live reading and validated again at the controller
+  // port before any effect. The returned text is the turn the host submits.
+  const selectRuntimeAction = (actionId: string): string => {
+    if (lifecycle !== 'ready' || terminallyDisposed) {
+      throw new Error(
+        'a runtime action requires an initialized or restored Captain shell',
+      );
+    }
+    if (activeTurn !== undefined || activeTurnHostCalls !== undefined) {
+      throw new Error('a runtime action cannot be selected during a Boss turn');
+    }
+    if (typeof actionId !== 'string' || actionId.length === 0) {
+      throw new TypeError('a runtime action id must be a nonempty string');
+    }
+    const advertised = advertisedRuntimeActions().find(
+      (action) => action.id === actionId,
+    );
+    if (advertised === undefined) {
+      // CAPPLAY-5: the chosen id is control data whether or not the leaf
+      // advertises it, so the refusal names the fact and not the string.
+      throw new Error('the active leaf does not advertise that action');
+    }
+    const text =
+      typeof advertised.label === 'string' ? advertised.label.trim() : '';
+    if (text.length === 0) {
+      throw new Error(
+        'the advertised action carries no Boss-facing label to submit as its turn',
+      );
+    }
+    pendingHostSelection = { kind: 'runtime', actionId, text };
+    return text;
+  };
+
   // The catalog is registry-authored, not shell-authored: an id, a command,
   // and an intent all arrive from an enabled module. They pass the same seam
   // the ControlView lines do, so an intent carrying a newline cannot open a
@@ -6471,6 +6650,42 @@ export function createPlaybookCaptainShell(
             ? []
             : [labeledBlock('Conversation recap', options.reseedDigest)]),
         ]);
+      // CAPTAIN-7: a turn whose decision the host already made allocates no
+      // decision call. The host's selection is this state's decision reply, so
+      // it passes the runtime's own reply validation and reaches the shell
+      // through the controller port like every other selection — validation,
+      // execution, the outcome report, and the closing reply are the loop's.
+      if (kind === 'decision' && turn?.hostRuntimeActionId !== undefined) {
+        return {
+          status: 'ok' as const,
+          finalText: JSON.stringify({
+            action: 'runtime',
+            actionId: turn.hostRuntimeActionId,
+          }),
+        };
+      }
+      // CAPTAIN-63: a give-up allocates neither call. Its decision is the
+      // host's, and its result phase is answered below from the settlement the
+      // shell already holds, so an exit from a failing provider does not ask
+      // that provider for permission.
+      if (kind === 'decision' && turn?.hostGiveUp === true) {
+        return {
+          status: 'ok' as const,
+          finalText: JSON.stringify({ action: 'dismiss' }),
+        };
+      }
+      if (kind === 'closingReply' && turn?.hostGiveUp === true) {
+        // The durable conversation did not receive this turn, so it is marked
+        // for the CAPTAIN-35 catch-up rather than left believing it is
+        // current: the next call carries the journal records it missed.
+        markConversationCatchUp();
+        // Through the one presentation seam, exactly where a model-composed
+        // reply is presented, so this reply is journaled and single-attempt
+        // like every other. It needs no reply validation or corrective re-ask:
+        // `giveUpReplyText` already validated what it composed.
+        await surfaceSettlement({ context, text: giveUpReplyText() });
+        return { status: 'ok' as const, finalText: 'ok' };
+      }
       const outcome = await durableCall(context, compose);
       if (kind === 'decision') {
         // A model-decided `respond` surfaces this call's own prose, so the
@@ -6700,9 +6915,26 @@ export function createPlaybookCaptainShell(
     const root = rootFrame();
     if (!root) return false;
     const label = frameLabel(root);
+    if (
+      activeTurn?.hostGiveUp === true &&
+      freezeTurnUnresolvedEffects().length > 0
+    ) {
+      await settleUnresolvedEffectAbandonment(leafFrame()!);
+      facts.push(`Dismissed the ${label} engagement with unresolved repository effects reported.`);
+      return false;
+    }
     // Dismissal leaves the procedure unfinished. Persist the latest safe
-    // generation captured for this turn before disposal erases the frames.
-    retainOrClearDisposedRoot(root);
+    // generation captured for this turn before disposal erases the frames —
+    // unless the Boss gave up on it (CAPTAIN-44), in which case retaining it
+    // would offer the abandoned run back on the idle digest's next reading.
+    if (activeTurn?.hostGiveUp === true) {
+      pendingRetentionUpdates.set(root.entry.id, {
+        kind: 'clear',
+        rootPlaybookId: root.entry.id,
+      });
+    } else {
+      retainOrClearDisposedRoot(root);
+    }
     try {
       await runEffect(() => disposeStack('dismiss'));
       facts.push(`Dismissed the ${label} engagement.`);
@@ -7146,7 +7378,8 @@ export function createPlaybookCaptainShell(
       fencedLeaf !== undefined;
     if (
       retainedEffectReconciliation !== undefined &&
-      !routesRetainedReconciliation
+      !routesRetainedReconciliation &&
+      !(selection.action === 'dismiss' && turn.hostGiveUp === true)
     ) {
       return rejectSelection(
         selection,
@@ -7276,10 +7509,16 @@ export function createPlaybookCaptainShell(
       if (!leaf) {
         return rejectSelection(selection, 'no engagement is active to dismiss');
       }
+      // CAPTAIN-63: a give-up ends the run. An ordinary dismissal of a nested
+      // call returns to its caller, which is the right reading of "stop this
+      // call" and the wrong one of "stop this workflow" — the Boss gave up on
+      // the root, not on whichever child was parked when they did.
+      const giveUp = turn.hostGiveUp === true;
+      const dismissed = giveUp ? (rootFrame() ?? leaf) : leaf;
       turn.settled = true;
-      journalAction({ action: 'dismiss', playbookId: leaf.entry.id });
-      const label = frameLabel(leaf);
-      if (leaf.parent) {
+      journalAction({ action: 'dismiss', playbookId: dismissed.entry.id });
+      const label = frameLabel(dismissed);
+      if (leaf.parent && !giveUp) {
         // No boundary around the return itself: `resumeParent` disposes the
         // child and drives the parent, and each of those is marked where it
         // happens. A visibility rejection raised on the way back is shell
@@ -7498,7 +7737,6 @@ export function createPlaybookCaptainShell(
         try {
           await settleUnresolvedEffectAbandonment(leaf);
         } catch (error) {
-          abandonmentSettlementUnsafe = true;
           const normalized = normalizeErrorCompact(error) ?? {
             name: 'Error',
             message: String(error),
@@ -7615,6 +7853,34 @@ export function createPlaybookCaptainShell(
   // The reply composes from the authoritative report, never the early
   // `settled` guard. That guard closes duplicate submissions before an effect
   // starts; it is not evidence that anything ran.
+  // CAPTAIN-63: the give-up's closing reply, composed from the same settlement
+  // facts the result-phase prompt would have carried. Shell-authored Boss
+  // prose passes the validation every model reply passes (CAPTAIN-34); what it
+  // interpolates is not host-authored all the way down, so a fact set that
+  // fails validation is dropped rather than spoken and the reply still states
+  // the settlement truthfully.
+  const giveUpReplyText = (): string => {
+    const report = activeTurn?.report;
+    const facts = report?.bossFacts ?? report?.facts ?? [];
+    const stopped = report?.status === 'ok';
+    const opening = stopped
+      ? 'Stopped that workflow. I will not resume it.'
+      : 'I could not confirm that the workflow was stopped.';
+    const closing = stopped
+      ? 'Send the command again to start fresh work.'
+      : 'The stop did not settle successfully; recover the session before continuing.';
+    const composed = [
+      opening,
+      ...(facts.length === 0
+        ? []
+        : ['Here is what happened:', ...facts.map((fact) => `- ${fact}`)]),
+      closing,
+    ].join('\n');
+    return replyRejection(composed) === undefined
+      ? composed
+      : [opening, closing].join('\n');
+  };
+
   const failureReplyText = (): string => {
     const commands = [...enablementById.values()]
       .map((enablement) => `/${enablement.command} <task>`)
@@ -8685,6 +8951,14 @@ export function createPlaybookCaptainShell(
 
     installRetainedGenerations,
 
+    describeRuntimeActions: advertisedRuntimeActions,
+
+    submitRuntimeAction: selectRuntimeAction,
+
+    describeShellActions: advertisedShellActions,
+
+    submitShellAction: selectShellAction,
+
     async handleBossTurn(
       turn: BossTurn,
       context: CaptainContext,
@@ -8724,13 +8998,28 @@ export function createPlaybookCaptainShell(
       const turnHostCalls = new Set<Promise<unknown>>();
       activeTurnHostCalls = turnHostCalls;
       activeContext = context;
-      const parsed = resolveCommandTurn(turn.prompt);
+      // CAPTAIN-7: one host selection is consumed by one turn. It decides only
+      // the turn carrying the exact text the selection was made for; any other
+      // turn drops it and resolves normally.
+      const selected = pendingHostSelection;
+      pendingHostSelection = undefined;
+      const decided =
+        selected !== undefined && selected.text === turn.prompt
+          ? selected
+          : undefined;
+      const hostRuntimeActionId =
+        decided?.kind === 'runtime' ? decided.actionId : undefined;
+      const hostGiveUp = decided?.kind === 'give-up' ? true : undefined;
+      const parsed =
+        decided === undefined ? resolveCommandTurn(turn.prompt) : undefined;
       activeTurn = {
         id: ++turnSequence,
         captainSyncedJournalSeq: journalSeq,
         bossText: turn.prompt,
         authoritativeText: parsed?.authoritativeText ?? turn.prompt,
         ...(parsed ? { resolution: parsed.resolution } : {}),
+        ...(hostRuntimeActionId === undefined ? {} : { hostRuntimeActionId }),
+        ...(hostGiveUp === undefined ? {} : { hostGiveUp }),
         settled: false,
         presentationAttempted: false,
         settlementFacts: [],
@@ -8880,6 +9169,7 @@ export function createPlaybookCaptainShell(
         failure ??= error;
       }
     }
+    pendingHostSelection = undefined;
     // Quarantine is session-wide by design. Only terminal teardown may drop
     // its ownership after every frame host call and the Captain are drained.
     playerTransactions.clear();

package/reference/sdlc/code.playbook/playbook.config.template.yaml

@@ -21,7 +21,8 @@
 # Drop an adapter from this file and you can skip its SDK entirely.
 # Every seeded agent runs in cligent's protected auto mode
 # (permissions.mode: auto): claude maps it to permissionMode auto, codex to
-# on-request + auto_review. Codex roles also grant writablePaths: ['.git']
+# on-request + auto_review. A codex agent additionally needs
+# writablePaths: ['.git'] to write git metadata under its sandbox.
 # so they can inspect and work with repository metadata under the sandbox.
 
 # The Captain/Judge agent.
@@ -46,15 +47,13 @@ notifications:
 # shares one provider conversation across those playbooks.
 players:
   dev.coder:
-    adapter: codex
-    model: gpt-5.6-sol
-    effort: ultra
+    adapter: claude
+    model: claude-opus-5
+    effort: high
     # Adapter-scoped fast mode is validated by the installed Cligent contract;
     # omitting it takes the provider default.
-    fastMode: true
     permissions:
       mode: auto
-      writablePaths: ['.git']
 
   dev.reviewer:
     adapter: claude

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

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 
+import type { PlaybookControlAction } from '@sublang/playbook/runtime';
 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';
@@ -68,6 +69,31 @@ export interface SessionHostController {
   readonly lease: PlaybookSessionLifecycle;
   read(): Promise<SessionRecovery | undefined>;
   handleBossTurn(input: string): Promise<SessionRecovery>;
+  /**
+   * The active leaf's currently advertised runtime actions, read live between
+   * turns; empty whenever nothing is advertised, a turn is active, or the
+   * leaf's control view cannot be read.
+   */
+  listRuntimeActions(): readonly PlaybookControlAction[];
+  /**
+   * Submit one currently advertised runtime action as the session's next turn.
+   * The turn is the same durable transaction `handleBossTurn` runs, and its
+   * decision is the submitted selection, so no decision model call is made.
+   */
+  submitRuntimeAction(actionId: string): Promise<SessionRecovery>;
+  /**
+   * The controls the shell offers on its own behalf, read live between turns;
+   * today one give-up while a root is engaged, and empty while idle or while a
+   * turn is active. Disjoint from `listRuntimeActions`, which reads the leaf.
+   */
+  listShellActions(): readonly PlaybookControlAction[];
+  /**
+   * Submit one currently advertised shell control as the session's next turn.
+   * The turn is the same durable transaction `handleBossTurn` runs; both its
+   * decision and its closing reply are the shell's, so the turn makes no model
+   * call and a give-up survives a provider that is refusing everything.
+   */
+  submitShellAction(actionId: string): Promise<SessionRecovery>;
   retry(): Promise<SessionRecovery>;
   dispose(): Promise<void>;
 }

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

@@ -1,19 +1,12 @@
-import { type XStatePlaybookRuntimeFactory, type XStatePlaybookRuntimeConstruction } from '@sublang/playbook/xstate-runtime';
-import { type DevInput, type PlayerInput } from './dev.fsm.js';
+import { type PlaybookPlayerInput, type XStatePlaybookRuntimeFactory, type XStatePlaybookRuntimeConstruction } from '@sublang/playbook/xstate-runtime';
+import { type DevInput } from './dev.fsm.js';
 import type { PlaybookHostConstructionCapabilities } from '../code.playbook/playbook-captain.js';
 import type { CaptainCallOptions, CaptainResult, JsonValue, NormalizedError, PlayerCallOptions, PlaybookCallRequest, PlaybookCallResult, PlaybookCallStart, PlaybookControlReceipt, PlaybookControlView, PlaybookPendingCall, PlaybookPorts, PlaybookRunResult, PlaybookRuntime, PlaybookRuntimeFactory, PlaybookRuntimeSnapshot, PlaybookSession, PlaybookState, PlaybookStateValue, PlaybookTraceEvent, PlaybookTraceType, PlayerResult, PlayerSessionStore } from '@sublang/playbook/runtime';
 export type { CaptainCallOptions, CaptainResult, JsonValue, NormalizedError, PlayerCallOptions, PlaybookCallRequest, PlaybookCallResult, PlaybookCallStart, PlaybookControlReceipt, PlaybookControlView, PlaybookPendingCall, PlaybookPorts, PlaybookRunResult, PlaybookRuntime, PlaybookRuntimeFactory, PlaybookRuntimeSnapshot, PlaybookSession, PlaybookState, PlaybookStateValue, PlaybookTraceEvent, PlaybookTraceType, PlayerResult, PlayerSessionStore, };
 export type DevPlaybookOptions = DevInput;
 export type DevPlaybookHostCapabilities = PlaybookHostConstructionCapabilities & XStatePlaybookRuntimeConstruction<DevPlaybookOptions, object>['hostCapabilities'];
-/**
- * Preserve authored Markdown quote markers around every line of relayed
- * runtime text. The generic composer preserves the marker itself; DEV's
- * override additionally keeps a multiline value inside that quote and drops
- * the optional relays that have no value yet.
- */
-declare function composePlayerPrompt(input: PlayerInput, resuming?: boolean): string;
 export declare const _internal: {
-    composePlayerPrompt: typeof composePlayerPrompt;
+    composePlayerPrompt: (input: PlaybookPlayerInput, _identity: import("@sublang/playbook/xstate-runtime").XStatePromptIdentity, resuming?: boolean) => string;
     VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string>;
     UNFINISHED_FINAL_STATE_IDS: ReadonlySet<string>;
 };

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

@@ -73,11 +73,6 @@ function composePlayerPrompt(input, resuming = false) {
     });
     return composePlayerContinuation(input, body, resuming);
 }
-export const _internal = {
-    composePlayerPrompt,
-    VERBATIM_PAYLOAD_FIELDS,
-    UNFINISHED_FINAL_STATE_IDS,
-};
 const runtimeSpec = {
     label: 'DEV',
     // DR-022 / slc/link.md: the declaration carries the value current at link
@@ -141,5 +136,10 @@ const runtimeSpec = {
     unfinishedFinalStateIds: UNFINISHED_FINAL_STATE_IDS,
     transitionEventFields: ['developmentRequest', 'answer', 'questionId'],
 };
+export const _internal = {
+    composePlayerPrompt: runtimeSpec.composePlayerPrompt,
+    VERBATIM_PAYLOAD_FIELDS,
+    UNFINISHED_FINAL_STATE_IDS,
+};
 const createPlaybookRuntime = createXStatePlaybookRuntime(devMachine, runtimeSpec);
 export default createPlaybookRuntime;

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

@@ -160,12 +160,6 @@ function composePlayerPrompt(input: PlayerInput, resuming = false): string {
   return composePlayerContinuation(input, body, resuming);
 }
 
-export const _internal = {
-  composePlayerPrompt,
-  VERBATIM_PAYLOAD_FIELDS,
-  UNFINISHED_FINAL_STATE_IDS,
-};
-
 const runtimeSpec = {
   label: 'DEV',
   // DR-022 / slc/link.md: the declaration carries the value current at link
@@ -224,7 +218,7 @@ const runtimeSpec = {
       },
     },
   },
-  composePlayerPrompt: (input: PlaybookPlayerInput, _identity, resuming) =>
+  composePlayerPrompt: (input: PlaybookPlayerInput, _identity, resuming?: boolean) =>
     composePlayerPrompt(input as PlayerInput, resuming),
   verbatimPayloadFields: VERBATIM_PAYLOAD_FIELDS,
   controlContextFields: [],
@@ -232,6 +226,12 @@ const runtimeSpec = {
   transitionEventFields: ['developmentRequest', 'answer', 'questionId'],
 } satisfies XStatePlaybookRuntimeSpecV3<DevPlaybookOptions>;
 
+export const _internal = {
+  composePlayerPrompt: runtimeSpec.composePlayerPrompt,
+  VERBATIM_PAYLOAD_FIELDS,
+  UNFINISHED_FINAL_STATE_IDS,
+};
+
 const createPlaybookRuntime: XStatePlaybookRuntimeFactory<
   XStatePlaybookRuntimeConstruction<
     DevPlaybookOptions,

package/reference/sdlc/pr.md

@@ -19,7 +19,9 @@ The caller supplies:
 `pr` delivers a reviewed branch into the repository default branch through a GitHub pull request: it publishes the branch, waits for the pull request's checks, fixes red checks through playbook `code` no more than once, and merges.
 It changes no files and owns no repository commit; the one fix it may request is owned by `code`.
 The check waits, the fix publication, the merge, and the local update are mechanical steps: each runs one fixed command whose exit status alone decides its two outcomes, reads no conversation, and produces no prose.
-`gh` infers the pull request from the checked-out branch, so no mechanical step needs a runtime value.
+`gh` infers the pull request from the checked-out branch, which the run does not own: the nested `code` call suspends across Boss turns, so the checkout can change before the fix is published or the merge runs.
+The two steps that act on the pull request itself therefore carry one runtime value — the pull request `pr` published — and refuse unless the checkout still infers exactly it.
+That identity is reported text, so it binds as a single-quoted shell literal: the command compares it as data and never executes it as shell syntax.
 
 When the caller gives its input, Captain shall relay the complete caller input in quotes (`>`) to Coder, along with the following instruction:
 
@@ -66,6 +68,7 @@ When the nested `code` call fails outside that authored result contract, `pr` sh
 
 When `code` succeeds, Captain shall publish the fix to the pull request by running exactly the following command in the repository, with no other action and without reading its output:
 
+> [ "$(gh pr view --json url --jq .url)" = '<pull-request-url>' ] || exit 1
 > git push || exit 1
 > n=0
 > until [ "$(gh pr view --json headRefOid --jq .headRefOid 2>/dev/null)" = "$(git rev-parse HEAD)" ]; do
@@ -75,6 +78,7 @@ When `code` succeeds, Captain shall publish the fix to the pull request by runni
 > done
 
 The publication has exactly two outcomes decided by the exit status alone: fix published on status zero, once the pull request's head is the pushed commit, and fix not published otherwise.
+The command pushes nothing until the checked-out branch infers the pull request `pr` published, so a checkout that changed while `code` ran publishes to no other branch.
 Fix not published is an authored failure that leaves the pull request open.
 
 When the fix is published, Captain shall wait for the pull request's checks again by running exactly the same command as the first wait in the repository, with no other action and without reading its output:
@@ -92,11 +96,20 @@ Checks still failing is an authored failure that leaves the pull request open; t
 
 When the checks pass, before or after the one fix attempt, Captain shall merge the pull request by running exactly the following command in the repository, with no other action and without reading its output:
 
-> gh pr merge --merge --delete-branch --match-head-commit "$(git rev-parse HEAD)"
+> pr=$(gh pr view --json url --jq .url) || exit 1
+> [ "$pr" = '<pull-request-url>' ] || exit 1
+> base=$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name) || exit 1
+> [ -n "$base" ] || exit 1
+> [ "$(gh pr view "$pr" --json baseRefName --jq .baseRefName)" = "$base" ] || exit 1
+> gh pr merge --merge --delete-branch --match-head-commit "$(git rev-parse HEAD)" || exit 1
+> [ "$(gh pr view "$pr" --json state --jq .state)" = MERGED ] || exit 1
+> [ "$(git branch --show-current)" = "$base" ]
 
-The merge creates a merge commit on the repository default branch, deletes the remote and local branch, and checks out the local default branch; GitHub closes the linked issue on merge.
+The merge creates a merge commit on the repository default branch, requests deletion of the remote and local branch, and checks out the local default branch; GitHub closes the linked issue on merge.
 The merge has exactly two outcomes decided by the exit status alone: merged on status zero and merge refused otherwise.
-Merge refused is an authored failure that leaves the pull request in the state GitHub reports: GitHub refused the merge for a conflict, a branch protection, a forbidden merge method, or a head that moved, or the merge landed but the local switch to the default branch or the branch deletion failed.
+The command requires the inferred pull request to be the one `pr` published and to target the repository default branch before the irreversible merge, and confirms that same pull request's merged state and the default-branch checkout after the merge command succeeds; a queued pull request is not a merged result.
+Merge refused is an authored failure that leaves the pull request in the state GitHub reports: the checkout no longer infers the published pull request, the pull request targets another branch, GitHub refused the merge for a conflict, a branch protection, a forbidden merge method, or a head that moved, or the merge may have landed while its confirmation, the local switch to the default branch, or the branch deletion failed.
+A refused merge does not establish that the pull request is unmerged, so `pr` reports it as an unconfirmed merge rather than as not merged, and no outcome claims a branch was deleted, because `gh` skips the remote deletion for a pull request from another repository or one already merged and exits zero anyway.
 
 When the pull request is merged, Captain shall bring the local default branch to the merged head by running exactly the following command in the repository, with no other action and without reading its output: