@sublang/playbook 13.3.0 → 14.0.0

package/README.md

@@ -32,9 +32,10 @@ Run `playbook` for an interactive tmux UI powered by [cligent](https://github.co
 Out of the box, Playbook includes **CODE** for implementation, **REVIEW** for commit-based review and fixes, **DECIDE** for independently proposed and reviewed specification decisions, **DEV** for repository-aware planning of a development request, **BRANCH** for checking out a new branch for a GitHub issue, and **PR** for publishing, checking, and merging that branch through a pull request.
 CODE and DECIDE call REVIEW as a nested playbook; DEV calls CODE, or DECIDE and then CODE, and wraps them in BRANCH and PR when the request names a GitHub issue or asks for a pull request.
 
-The shared starter config uses Claude as both Captain and the `dev.coder`
-player, and Codex as `dev.reviewer`. CODE, REVIEW, DECIDE, BRANCH, and PR bind
-their local roles explicitly to those two stable players, so nested and later
+The shared starter config selects one adapter for the Captain and all players
+from locally visible credentials: Claude first, then Codex. If neither is
+configured, it seeds Claude and prints a notice. CODE, REVIEW, DECIDE, BRANCH, and PR bind
+their local roles explicitly to `dev.coder` and `dev.reviewer`, so nested and later
 engagements share a conversation only where their bindings name the same
 player ID; DEV's Analyst binds a distinct `dev.analyst` player.
 
@@ -49,8 +50,7 @@ If an SDK is missing or older than cligent supports, Playbook prints the pinned
 Prerequisites:
 
 - Node.js >= 20.6.0
-- Authenticated [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) or `ANTHROPIC_API_KEY`
-- Authenticated [Codex CLI](https://github.com/openai/codex) or `OPENAI_API_KEY`
+- Credentials for the configured adapter: authenticated [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) or `ANTHROPIC_API_KEY` for Claude; authenticated [Codex CLI](https://github.com/openai/codex) or `OPENAI_API_KEY` for Codex
 - [GitHub CLI](https://cli.github.com/) (`gh`) authenticated for the repository's GitHub remote, for `/branch`, `/pr`, and `/dev` requests that name an issue or ask for a pull request
 
 Interactive `playbook` additionally needs tmux 3.3 or newer and [`glow`](https://github.com/charmbracelet/glow#installation) on `PATH`; headless `playbook run` does not.

package/docs/configuration.md

@@ -55,8 +55,16 @@ key is that playbook's option slice. Every manifest role must be present
 exactly once. The launcher injects the rest — you do not write host wiring by
 hand.
 
-The seeded config runs every stable player on Claude Opus 5 — the Coder at
-`high` effort, the Reviewer and Analyst at `xhigh`:
+The launcher seeds one adapter for the Captain and all stable players from
+locally visible credentials: Claude first, then Codex. It uses Claude Opus 5
+for Claude or GPT-5.6 Sol for Codex, with Captain and Coder at `high` effort
+and Reviewer and Analyst at `xhigh`. If neither adapter is configured, it
+seeds Claude and prints a notice. Credentials do not prove SDK availability
+or remaining quota; launch still checks the configured adapter. Existing
+configs are left unchanged.
+
+The Claude default is shown below. A Codex seed also adds
+`permissions.writablePaths: ['.git']` to each agent:
 
 ```yaml
 captain:

package/docs/embedding.md

@@ -433,7 +433,7 @@ defines the files, versions and compatibility rules.
 
 ## Reading the published spec contracts
 
-The authored compiler-phase specs ship in the package and are exposed
+The compiler definitions and supporting assets ship in the package and are exposed
 as a public, semver-stable surface under `@sublang/playbook/slc/*`.
 Resolve and read one with `import.meta.resolve` plus `fs`:
 
@@ -450,3 +450,22 @@ The four specs are [`slc/text2gears.md`](../slc/text2gears.md),
 [`slc/link.md`](../slc/link.md) — the FSM-to-runtime contract that
 `@sublang/playbook/runtime` projects into TypeScript — and
 [`slc/optimize.md`](../slc/optimize.md).
+
+Five supporting assets use the same resolution mechanism:
+
+| Asset | Purpose |
+| --- | --- |
+| [`slc/workflow-contracts.json`](../slc/workflow-contracts.json) | Public output schemas and default literal target bindings for the builtin REVIEW, DECIDE, CODE, BRANCH, and PR workflows; compilers and embedders can read them without importing workflow implementations. |
+| [`slc/materialize-link.mjs`](../slc/materialize-link.mjs) | Optional CLI that emits a thin linked module from a supported FSM and JSON descriptor; see the profiles and invocation in `slc/link.md`. |
+| [`slc/scaffold-fsm.mjs`](../slc/scaffold-fsm.mjs) | Optional CLI that initializes an incomplete typed FSM from supported GEARS source. |
+| [`slc/experiments/fsm-scaffold-guidance.md`](../slc/experiments/fsm-scaffold-guidance.md) | Opt-in compiler guidance for the initializer, outside ordinary phase discovery. |
+| [`slc/slc.pin-inputs.json`](../slc/slc.pin-inputs.json) | SLC semantic-input closures for `gears2fsm` and `link`, including the workflow catalog and, for `link`, the materializer. Other phases use SLC's inline-input discovery. |
+
+For example, resolve `@sublang/playbook/slc/workflow-contracts.json`, read it
+with `readFile`, and parse the result as JSON to inspect the published workflow
+interfaces. Execute the `.mjs` helpers with Node and their documented CLI
+arguments: their supported public interfaces are their resolvable paths and CLI
+contracts. Their JavaScript module exports are internal implementation details
+and carry no SemVer compatibility guarantee.
+The initializer requires further semantic compilation and verification
+before its output is runnable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "13.3.0",
+  "version": "14.0.0",
   "type": "module",
   "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, REVIEW, DECIDE, DEV, BRANCH, and PR workflows driven by GEARS specs.",
   "license": "Apache-2.0",
@@ -38,6 +38,11 @@
     "src/xstate-playbook-runtime.js",
     "src/xstate-playbook-runtime.d.ts",
     "slc/link.md",
+    "slc/materialize-link.mjs",
+    "slc/scaffold-fsm.mjs",
+    "slc/experiments/fsm-scaffold-guidance.md",
+    "slc/slc.pin-inputs.json",
+    "slc/workflow-contracts.json",
     "slc/gears2fsm.md",
     "slc/text2gears.md",
     "slc/optimize.md",

package/reference/sdlc/code.playbook/bin/launch-config.js

@@ -180,7 +180,7 @@ export function resolveLaunchSessionsDir({
   if (sessionsDir !== undefined) return sessionsDir;
 
   if (preparePrimary) {
-    seedUserConfigIfMissing(userConfigPath, templatePath, onNotice);
+    seedUserConfigIfMissing(userConfigPath, templatePath, onNotice, env, homeDir);
     migrateUserConfigIfRetired(userConfigPath, onNotice);
   }
 
@@ -248,8 +248,10 @@ export async function loadLaunchPlan({
   templatePath = DEFAULT_TEMPLATE_PATH,
   onNotice = () => {},
   selectedMembers,
+  env = process.env,
+  homeDir = env.HOME ?? homedir(),
 }) {
-  seedUserConfigIfMissing(userConfigPath, templatePath, onNotice);
+  seedUserConfigIfMissing(userConfigPath, templatePath, onNotice, env, homeDir);
   // PBCLI-22/46: a reopen must not rewrite, validate, or otherwise inspect
   // config members outside the stored projection.
   if (selectedMembers === undefined) {
@@ -288,10 +290,12 @@ export async function loadSelectedLaunchPlanDataOnly({
   structuralProjection,
   templatePath = DEFAULT_TEMPLATE_PATH,
   onNotice = () => {},
+  env = process.env,
+  homeDir = env.HOME ?? homedir(),
 }) {
   const stored = validateStoredStructuralProjection(structuralProjection);
   const selectedMembers = selectedMembersFromStoredStructure(stored);
-  seedUserConfigIfMissing(userConfigPath, templatePath, onNotice);
+  seedUserConfigIfMissing(userConfigPath, templatePath, onNotice, env, homeDir);
 
   let top = parseYaml(readFileSync(userConfigPath, "utf8")) ?? {};
   if (overlayPaths.length > 0 && !isObject(top)) {
@@ -1335,11 +1339,90 @@ function assertLegacyRelocationLocatorsSafe(
   );
 }
 
-function seedUserConfigIfMissing(userConfigPath, templatePath, onNotice) {
+// PBCLI-11 / DR-053: the adapters a seeded lineup may take, highest
+// precedence first. A fixed order — not whichever the probe answers
+// first — is what makes one machine seed one file twice.
+const SEED_LINEUP = Object.freeze([
+  Object.freeze({ adapter: "claude", model: "claude-opus-5" }),
+  Object.freeze({ adapter: "codex", model: "gpt-5.6-sol" }),
+]);
+
+/**
+ * PBCLI-11: the lineup a seed would write here, and whether anything
+ * actually probed ready.
+ *
+ * Only the credential check participates. The SDK probe constructs an
+ * adapter and awaits `isAvailable()`, which reads whatever happens to
+ * be installed and spawns a subprocess for CLI-backed adapters: a seed
+ * consulting it would differ between a developer's machine and a clean
+ * one, and would make creating a file asynchronous.
+ */
+export function selectSeedLineup(env = process.env, home = homedir()) {
+  const ready = SEED_LINEUP.filter(
+    (entry) =>
+      checkReadiness([entry.adapter], env, home).failingAdapters.length === 0,
+  );
+  return { lineup: ready[0] ?? SEED_LINEUP[0], anyReady: ready.length > 0 };
+}
+
+/**
+ * The template is the documented default and the only source of the
+ * starter's structure and comments, so the default choice is still the
+ * byte copy it always was. A different adapter rewrites the agent
+ * scalars in place, which the Document API carries comments through.
+ */
+function seedTextForLineup(templatePath, lineup) {
+  const template = readFileSync(templatePath, "utf8");
+  if (lineup.adapter === SEED_LINEUP[0].adapter) return template;
+  const doc = parseYamlDocument(template);
+  const players = doc.getIn(["players"]);
+  const agentPaths = [
+    ["captain"],
+    ...[...(players?.items ?? [])].map((pair) => [
+      "players",
+      String(pair.key),
+    ]),
+  ];
+  for (const path of agentPaths) {
+    doc.setIn([...path, "adapter"], lineup.adapter);
+    doc.setIn([...path, "model"], lineup.model);
+    // A codex agent writes git metadata under its sandbox; claude's
+    // auto mode needs no grant, so the key exists for one adapter only.
+    if (lineup.adapter === "codex") {
+      doc.setIn([...path, "permissions", "writablePaths"], [".git"]);
+    } else {
+      doc.deleteIn([...path, "permissions", "writablePaths"]);
+    }
+  }
+  return String(doc);
+}
+
+function seedUserConfigIfMissing(
+  userConfigPath,
+  templatePath,
+  onNotice,
+  env = process.env,
+  homeDir = env.HOME ?? homedir(),
+) {
   if (existsSync(userConfigPath)) return;
   mkdirSync(dirname(userConfigPath), { recursive: true });
-  copyFileSync(templatePath, userConfigPath, constants.COPYFILE_EXCL);
+  const { lineup, anyReady } = selectSeedLineup(env, homeDir);
+  if (lineup.adapter === SEED_LINEUP[0].adapter && anyReady) {
+    // Unchanged default path: one exclusive create of the template bytes.
+    copyFileSync(templatePath, userConfigPath, constants.COPYFILE_EXCL);
+  } else {
+    // Still one exclusive create, so two seeding calls cannot disagree.
+    writeFileSync(userConfigPath, seedTextForLineup(templatePath, lineup), {
+      encoding: "utf8",
+      flag: "wx",
+    });
+  }
   onNotice(`playbook: created config at ${userConfigPath}\n`);
+  if (!anyReady) {
+    onNotice(
+      `playbook: no adapter probed ready; seeded ${lineup.adapter}\n`,
+    );
+  }
 }
 
 // DR-021 §3: migrate once, keeping the original before any rewrite.

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

@@ -346,10 +346,14 @@ export async function runPlaybookCli(options = {}) {
           overlayPaths: withPaths,
           structuralProjection: selectedRecord.structuralProjection,
           onNotice: (line) => stderr.write(line),
+          env,
+          homeDir: home,
         })
       : await loadLaunchPlan({
           userConfigPath,
           overlayPaths: withPaths,
+          env,
+          homeDir: home,
           loadModule,
           prepareRegistryModule:
             options.prepareRegistryModule ??

package/reference/sdlc/code.playbook/bin/repository-effects.js

@@ -659,10 +659,18 @@ export async function resolveCanonicalGitWorktree(cwd) {
 }
 
 async function sampleWorktree(worktree, env) {
-  const head = await resolveHead(worktree, env);
-  const indexVisibility = await rawIndexVisibility(worktree, env);
+  const [headResult, visibilityResult, statusResult] = await Promise.allSettled([
+    resolveHead(worktree, env),
+    rawIndexVisibility(worktree, env),
+    rawRepositoryStatus(worktree, env),
+  ]);
+  if (headResult.status === 'rejected') throw headResult.reason;
+  if (visibilityResult.status === 'rejected') throw visibilityResult.reason;
+  const head = headResult.value;
+  const indexVisibility = visibilityResult.value;
   assertIndexVisibility(indexVisibility);
-  const status = await rawRepositoryStatus(worktree, env);
+  if (statusResult.status === 'rejected') throw statusResult.reason;
+  const status = statusResult.value;
   const projection = await projectionFromStatus(worktree, status);
   return { head, indexVisibility, status, projection };
 }

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

@@ -359,10 +359,14 @@ export async function runPlaybookRun(options = {}) {
             overlayPaths: args.withPaths,
             structuralProjection: priorRecord.structuralProjection,
             onNotice: (line) => configNotices.push(line),
+            env,
+            homeDir: home,
           })
         : await loadLaunchPlan({
             userConfigPath,
             overlayPaths: args.withPaths,
+            env,
+            homeDir: home,
             loadModule,
             prepareRegistryModule,
             onNotice: (line) => configNotices.push(line),

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

@@ -3163,7 +3163,7 @@ async function createLease({
     }
     if (
       snapshot.mode !== 'chat' ||
-      snapshot.lastAction !== 'runtime' ||
+      (snapshot.lastAction !== 'runtime' && snapshot.lastAction !== 'dismiss') ||
       snapshot.lastSettlementStatus !== 'ok'
     ) {
       throw new Error(
@@ -4221,7 +4221,7 @@ function validateCanonicalCaptainSessionRecord(
     }
     if (
       snapshot.mode !== 'chat' ||
-      snapshot.lastAction !== 'runtime' ||
+      (snapshot.lastAction !== 'runtime' && snapshot.lastAction !== 'dismiss') ||
       snapshot.lastSettlementStatus !== 'ok' ||
       Object.hasOwn(record.retainedGenerations ?? {}, rootPlaybookId)
     ) {

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

@@ -3321,6 +3321,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
      * may return an executed receipt to its result phase.
      */
     const settleUnresolvedEffectAbandonment = async (unresolvedLeaf) => {
+        abandonmentSettlementUnsafe = true;
         if (leafFrame() !== unresolvedLeaf) {
             throw new Error('unresolved-effect abandonment requires the active leaf');
         }
@@ -3347,6 +3348,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             rootPlaybookId,
         });
         await runEffect(() => unresolvedEffectSettlement.complete(settlement));
+        abandonmentSettlementUnsafe = false;
     };
     const callResultFor = (frame, result) => {
         if (result.outcome === 'unresolved-effect') {
@@ -4693,6 +4695,12 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         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 —
         // unless the Boss gave up on it (CAPTAIN-44), in which case retaining it
@@ -5066,7 +5074,8 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                 selection.actionId === UNRESOLVED_EFFECT_ABANDONMENT_ACTION_ID) &&
             fencedLeaf !== undefined;
         if (retainedEffectReconciliation !== undefined &&
-            !routesRetainedReconciliation) {
+            !routesRetainedReconciliation &&
+            !(selection.action === 'dismiss' && turn.hostGiveUp === true)) {
             return rejectSelection(selection, 'retained work must reconcile its repository-effect evidence before an ordinary action can run');
         }
         if (selection.action === 'resume') {
@@ -5359,7 +5368,6 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                     await settleUnresolvedEffectAbandonment(leaf);
                 }
                 catch (error) {
-                    abandonmentSettlementUnsafe = true;
                     const normalized = normalizeErrorCompact(error) ?? {
                         name: 'Error',
                         message: String(error),
@@ -5473,8 +5481,13 @@ export function createPlaybookCaptainShell(options, deps = {}) {
     const giveUpReplyText = () => {
         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 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

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

@@ -5229,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',
@@ -5263,6 +5264,7 @@ export function createPlaybookCaptainShell(
       rootPlaybookId,
     });
     await runEffect(() => unresolvedEffectSettlement.complete(settlement));
+    abandonmentSettlementUnsafe = false;
   };
 
   const callResultFor = (
@@ -6913,6 +6915,14 @@ 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 —
     // unless the Boss gave up on it (CAPTAIN-44), in which case retaining it
@@ -7368,7 +7378,8 @@ export function createPlaybookCaptainShell(
       fencedLeaf !== undefined;
     if (
       retainedEffectReconciliation !== undefined &&
-      !routesRetainedReconciliation
+      !routesRetainedReconciliation &&
+      !(selection.action === 'dismiss' && turn.hostGiveUp === true)
     ) {
       return rejectSelection(
         selection,
@@ -7726,7 +7737,6 @@ export function createPlaybookCaptainShell(
         try {
           await settleUnresolvedEffectAbandonment(leaf);
         } catch (error) {
-          abandonmentSettlementUnsafe = true;
           const normalized = normalizeErrorCompact(error) ?? {
             name: 'Error',
             message: String(error),
@@ -7852,8 +7862,13 @@ export function createPlaybookCaptainShell(
   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 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

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:
 

package/reference/sdlc/pr.playbook/pr.fsm.d.ts

@@ -113,11 +113,21 @@ export type PrPlaybookOutput = {
     readonly childResult: CompletedChildResult;
 } | {
     readonly status: 'not-merged';
-    readonly reason: 'fix-not-published' | 'checks-failed' | 'merge-refused';
+    readonly reason: 'fix-not-published' | 'checks-failed';
+    readonly pullRequest: string;
+    readonly pullRequestUrl: string;
+}
+/**
+ * The merge command exited nonzero. It ran, so whether GitHub merged the
+ * pull request is unknown — script output never enters context — and the
+ * result claims neither a merge nor its absence.
+ */
+ | {
+    readonly status: 'merge-unconfirmed';
     readonly pullRequest: string;
     readonly pullRequestUrl: string;
 };
-export type PrCompletion = 'merged' | 'not-published' | 'fix-failed' | 'fix-not-published' | 'checks-failed' | 'merge-refused';
+export type PrCompletion = 'merged' | 'not-published' | 'fix-failed' | 'fix-not-published' | 'checks-failed' | 'merge-unconfirmed';
 /** The machine reads no input: the caller input arrives on `START_PR`. */
 export type PrInput = Readonly<Record<never, never>>;
 export type PrContext = {
@@ -290,7 +300,11 @@ export declare const prMachine: import("xstate").StateMachine<PrContext, {
     readonly childResult: CompletedChildResult;
 } | {
     readonly status: "not-merged";
-    readonly reason: "fix-not-published" | "checks-failed" | "merge-refused";
+    readonly reason: "fix-not-published" | "checks-failed";
+    readonly pullRequest: string;
+    readonly pullRequestUrl: string;
+} | {
+    readonly status: "merge-unconfirmed";
     readonly pullRequest: string;
     readonly pullRequestUrl: string;
 }, import("xstate").EventObject, import("xstate").MetaObject, {