@sublang/playbook 13.1.0 → 13.3.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
@@ -5900,6 +5951,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 +6648,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
@@ -6701,8 +6914,17 @@ export function createPlaybookCaptainShell(
     if (!root) return false;
     const label = frameLabel(root);
     // 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.`);
@@ -7276,10 +7498,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
@@ -7615,6 +7843,29 @@ 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 opening = 'Stopped that workflow. I will not resume it.';
+    const closing = 'Send the command again to start fresh work.';
+    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 +8936,14 @@ export function createPlaybookCaptainShell(
 
     installRetainedGenerations,
 
+    describeRuntimeActions: advertisedRuntimeActions,
+
+    submitRuntimeAction: selectRuntimeAction,
+
+    describeShellActions: advertisedShellActions,
+
+    submitShellAction: selectShellAction,
+
     async handleBossTurn(
       turn: BossTurn,
       context: CaptainContext,
@@ -8724,13 +8983,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 +9154,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
@@ -78,8 +77,8 @@ players:
 # `roles` are launcher-owned; every other key is that playbook's option
 # slice.
 #
-# Every manifest role is bound explicitly. CODE, REVIEW, and DECIDE
-# intentionally reuse the same two stable players, while DEV keeps its own
+# Every manifest role is bound explicitly. CODE, REVIEW, DECIDE, BRANCH, and
+# PR intentionally reuse the same two stable players, while DEV keeps its own
 # Analyst; change an id to isolate its conversation.
 playbooks:
   code:
@@ -103,3 +102,17 @@ playbooks:
     from: "@sublang/playbook/dev/registry"
     roles:
       analyst: dev.analyst
+
+  # Pull-request delivery for DEV (DR-050). BRANCH and PR bind Coder to the
+  # same dev.coder player as CODE and REVIEW on purpose: the Coder that read
+  # the issue and named the branch makes the commits and then describes
+  # them in the pull request. Change an id to isolate its conversation.
+  branch:
+    from: "@sublang/playbook/branch/registry"
+    roles:
+      coder: dev.coder
+
+  pr:
+    from: "@sublang/playbook/pr/registry"
+    roles:
+      coder: dev.coder

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.md

@@ -27,13 +27,14 @@ Do not change files or commit while planning or discussing the request.
 - If the discussion has concluded after a Boss reply and no repository work should follow, choose `discussion complete`.
 - If implementation can proceed under the existing decisions, choose `code`.
 - If implementation first requires a new or amended durable decision that the existing specs do not settle, choose `decide then code`.
+- If the request names a GitHub issue (number or URL) or explicitly asks for pull-request delivery, read the issue and its comments as part of the analysis (`gh issue view --comments` with the issue number) and choose `code via pull request` or `decide then code via pull request` in place of `code` or `decide then code`.
 
 A question or exploratory discussion is not by itself authorization to create a durable decision or implement changes.
 Do not choose `decide then code` merely because the work is large.
 Consult @specs/map.md for relevant context and @specs/meta.md for spec requirements, if needed.
 ```
 
-The planning result has four semantic outcomes: needs Boss reply, discussion complete, code, and decide then code.
+The planning result has six semantic outcomes: needs Boss reply, discussion complete, code, decide then code, code via pull request, and decide then code via pull request.
 Each outcome requires affirmative support in Analyst's result; absence of a reason to choose another outcome is not support.
 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.
@@ -66,7 +67,27 @@ Only after `decide` succeeds shall `dev` call playbook `code` with the developme
 
 `dev` shall not separately call `review` for the design scope already reviewed by `decide`.
 
+For code via pull request and decide then code via pull request, `dev` shall first call playbook `branch` 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 `branch` succeeds shall `dev` continue with the `code` call for code via pull request, or the `decide` call and then the `code` call for decide then code via pull request, each with the same input as its plain path above.
+
+On a plain path, `code` success completes `dev`.
+On a pull-request path, only after `code` succeeds shall `dev` call playbook `pr` with the development request, issue summary, branch, base revision, last `code`-owned commit, and exact final evaluated repository revision in quotes (`>`).
+
+> Original request: <development-request>
+> Issue summary: <issue-summary>
+> Branch: <branch>
+> Base revision: <base-revision>
+> CODE commit: <last-code-commit>
+> Evaluated revision: <final-evaluated-revision>
+
+A plain request calls neither `branch` nor `pr`.
+
 `dev` completes with the successful result of its final child call.
-If a child returns an authored abort or failure, or a terminal result that does not prove the success required for the selected path, `dev` shall start no later child and shall relay that canonical result.
+If a child returns an authored abort or failure, or a terminal result that does not prove the success required for the selected path, `dev` shall start no later child and shall relay that canonical result; a `branch` or `pr` failure ends `dev` under this same rule.
 If a child call fails outside its authored result contract, `dev` shall park as failed and retain the control-plane error.
-`dev` shall consume commit identities only from each child's canonical structured result, never from player prose.
+`dev` shall consume commit, revision, branch, and pull-request identities only from each child's canonical structured result, never from player prose.