@sublang/playbook 13.2.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 the stable Coder player on GPT-5.6 Sol with fast mode
-enabled and the stable Reviewer player on Claude Opus 5:
+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:
@@ -68,14 +76,11 @@ captain:
 
 players:
   dev.coder:
-    adapter: codex
-    model: gpt-5.6-sol
-    effort: ultra
-    fastMode: true
+    adapter: claude
+    model: claude-opus-5
+    effort: high
     permissions:
-      mode: auto
-      writablePaths:
-        - .git # allow git metadata writes under Codex auto mode
+      mode: auto # protected auto mode for the Claude Coder
 
   dev.reviewer:
     adapter: claude

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.2.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-host.js

@@ -43,7 +43,7 @@ export async function openSessionHost(options) {
     await installRetainedGenerationsForLaunch({ lease, shell: created.shell, ...(record === undefined ? { freshBoundary: { cwd, structuralProjection: structure, executionProjection: config, snapshot: created.snapshot } } : {}), retainedGenerations: record?.retainedGenerations ?? {}, reconcileRepositoryEffects: created.reconcileRepositoryEffects });
     record = await lease.read();
     await replay.flushStoredRecords();
-    const execute = async (input, retry) => {
+    const execute = async (input, retry, actionId, shellActionId) => {
       if (closed || closing) throw new Error('session host is closing');
       if (active) throw new Error('session turn is already active');
       const operation = (async () => {
@@ -53,8 +53,18 @@ export async function openSessionHost(options) {
           input = prior.uncertain.input;
           if (!retryPending) throw new Error('retry requires reopening the uncertain checkpoint');
         } else if (prior?.state !== 'settled') throw new Error('session has an uncertain turn; select Retry or Discard');
-        if (typeof input !== 'string' || input.trim().length === 0) throw new Error('session input must be nonempty');
+        if (actionId === undefined && shellActionId === undefined && (typeof input !== 'string' || input.trim().length === 0)) throw new Error('session input must be nonempty');
         await created.reconcileRepositoryEffects();
+        // The selection is made after reconciliation, so the advertised
+        // reading it is validated against is the one this turn settles
+        // against, and its Boss text is this turn's durable input.
+        if (actionId !== undefined) {
+          if (typeof created.shell.submitRuntimeAction !== 'function') throw new Error('this Captain shell advertises no runtime actions');
+          input = created.shell.submitRuntimeAction(actionId);
+        } else if (shellActionId !== undefined) {
+          if (typeof created.shell.submitShellAction !== 'function') throw new Error('this Captain shell advertises no controls of its own');
+          input = created.shell.submitShellAction(shellActionId);
+        }
         terminal = undefined; replies = [];
         const attemptId = options.createAttemptId?.() ?? randomUUID();
         const marked = retry ? await lease.beginRetry({ expectedAttemptId: prior.uncertain.attemptId, nextAttemptId: attemptId }) : await lease.beginTurn({ input, attemptId, attemptedExecutionProjection: config });
@@ -84,7 +94,7 @@ export async function openSessionHost(options) {
       })();
       return closing;
     };
-    return Object.freeze({ sessionId, host: created.host, shell: created.shell, lease, read: () => lease.read(), handleBossTurn: (input) => execute(input, false), retry: () => execute(undefined, true), dispose });
+    return Object.freeze({ sessionId, host: created.host, shell: created.shell, lease, read: () => lease.read(), handleBossTurn: (input) => execute(input, false), listRuntimeActions: () => created.shell.describeRuntimeActions?.() ?? Object.freeze([]), submitRuntimeAction: (actionId) => execute(undefined, false, actionId), listShellActions: () => created.shell.describeShellActions?.() ?? Object.freeze([]), submitShellAction: (actionId) => execute(undefined, false, undefined, actionId), retry: () => execute(undefined, true), dispose });
   } catch (cause) {
     const failures = [cause];
     let disposed = true;

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.d.ts

@@ -1,6 +1,6 @@
 import { type Captain, type CaptainSession, type TuningSelection } from '@sublang/cligent/tmux-play';
 import type { Effort, PermissionPolicy } from '@sublang/cligent';
-import type { JsonValue, PlaybookEffectLedger, PlaybookEffectLedgerCommandBatch, PlaybookRuntime, PlaybookRuntimeSnapshot } from '@sublang/playbook/runtime';
+import type { JsonValue, PlaybookEffectLedger, PlaybookEffectLedgerCommandBatch, PlaybookControlAction, PlaybookRuntime, PlaybookRuntimeSnapshot } from '@sublang/playbook/runtime';
 import { type CaptainControllerPort } from '../captain.playbook/captain.playbook.js';
 import type { PlaybookSummaryPolicy } from './code.registry.js';
 interface SessionAgent {
@@ -215,6 +215,31 @@ export interface PlaybookCaptainShell extends Captain {
     exportSnapshot(): PlaybookCaptainShellSnapshot | undefined;
     exportSettlement(): PlaybookCaptainSettlement | undefined;
     restore(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;
 }
 export declare function assertPlaybookCaptainUnresolvedEffects(value: unknown): readonly PlaybookCaptainUnresolvedEffect[];
 /** Validate, detach, and freeze one untrusted shell snapshot. */