@sublang/playbook 0.4.2 → 0.6.0

package/README.md

@@ -36,7 +36,8 @@ The reference is the canonical worked example —
 [CODE source](reference/sdlc/code.md) →
 [gears](reference/sdlc/code.playbook/code.gears.md) →
 [FSM](reference/sdlc/code.playbook/code.fsm.ts) → runtime — with
-the runtime ported to cligent's `tmux-play` host out of the box.
+the runtime registered behind the built-in Playbook Captain shell for
+cligent's `tmux-play` host out of the box.
 The compiled artifacts live under
 [`reference/sdlc/code.playbook/`](reference/sdlc/code.playbook),
 the slc pipeline's `<basename>.<pipeline>/` output directory.
@@ -82,7 +83,10 @@ playbook-code --help
 ```
 
 The seed template runs each agent in cligent's protected auto mode
-(`permissions.mode: auto`), suppressing routine approval prompts.
+(`permissions.mode: auto`), suppressing routine approval prompts. Its
+Codex Coder also grants `permissions.writablePaths: [.git]` so git
+metadata writes stay available under auto mode without switching to
+bypass permissions.
 
 ### Configure agents
 
@@ -95,20 +99,27 @@ $EDITOR "${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook-code.config.yaml"
 Both CODE players can use `claude` or `codex`; other adapter ids are
 passed through to `tmux-play` with a warning because `playbook-code`
 does not know how to preflight their auth. The safe tuning points are
-`captain.adapter`, `captain.model`, each player's `adapter`, and each
-player's `model`. Keep `captain.from` and the `players[].id` values
-fixed; the runtime binds to those host-configuration invariants per
+`captain.adapter`, `captain.model`, and each role's `adapter` and
+`model` under `players.coder` / `players.reviewer`. The composer owns
+`captain.from` and points it at the Playbook Captain shell adapter, and
+it owns the `coder` / `reviewer` role keys, so leave those keys as-is;
+the runtime binds to those host-configuration invariants per
 [PBRT-4](specs/user/playbook-runtime.md#pbrt-4) and derives the
-`<coder-llm>` / `<reviewer-llm>` substitution strings from each
-player entry's `model` when pinned and `adapter` otherwise — so the
-Committer's commit-message trailers can name the concrete model
-(e.g. `claude-opus-4-7`) rather than the adapter family (`claude`).
+`<coder-llm>` / `<reviewer-llm>` substitution strings from each role's
+`model` when pinned and `adapter` otherwise — so the Committer's
+commit-message trailers can name the concrete model
+(e.g. `claude-opus-4-8`) rather than the adapter family (`claude`).
 
-For example, this swaps the Coder to Codex and the Reviewer to Claude:
+`players.committer` is an optional alias naming which role — `coder`
+or `reviewer` — runs the commit turn; the seeded overlay points it at
+the Reviewer. Absent the alias the Committer falls back to the Coder
+([PBRT-8](specs/user/playbook-runtime.md#pbrt-8)).
+
+For example, the seeded overlay runs the Coder on Codex and the
+Reviewer on Claude, with the Committer aliased to the Reviewer:
 
 ```yaml
 captain:
-  from: "@sublang/playbook/code/tmux-play"
   adapter: claude
   model: claude-sonnet-4-6
   reasoningEffort: high
@@ -116,18 +127,21 @@ captain:
     mode: auto
 
 players:
-  - id: coder      # must stay `coder` — see PBRT-4
+  coder:              # role key must stay `coder` — see PBRT-4
     adapter: codex
     model: gpt-5.5
     reasoningEffort: xhigh
     permissions:
       mode: auto
-  - id: reviewer   # must stay `reviewer` — see PBRT-4
+      writablePaths:
+        - .git          # allow git metadata writes under Codex auto mode
+  reviewer:           # role key must stay `reviewer` — see PBRT-4
     adapter: claude
-    model: claude-opus-4-7
+    model: claude-opus-4-8
     reasoningEffort: xhigh
     permissions:
       mode: auto
+  committer: reviewer   # which role commits — `coder` or `reviewer`
 ```
 
 Normal `playbook-code` runs use the seeded path above. If you need a
@@ -174,7 +188,7 @@ production install.
 
 Drive a Boss turn against the source tree (uses the developer
 [`tmux-play.config.yaml`](reference/sdlc/code.playbook/tmux-play.config.yaml)
-that imports the compiled adapter via relative path):
+that imports the compiled Playbook Captain shell via relative path):
 
 ```sh
 pnpm exec tmux-play --config reference/sdlc/code.playbook/tmux-play.config.yaml
@@ -186,7 +200,9 @@ installed globally.
 
 ### Running a Boss turn
 
-The Boss pane takes plain-language turns; the judge classifies each
+The Boss pane starts at the Playbook Captain shell. Use `/code <task>`
+to explicitly select the CODE playbook, or use ordinary text and let the
+shell route it. Once a turn reaches CODE, the CODE judge classifies it
 into an FSM event (start a coding turn, continue or summarize an IR,
 interrupt to a named state, or nothing) per
 [PBRT-1](specs/user/playbook-runtime.md#pbrt-1).
@@ -195,9 +211,16 @@ the FSM parks at `awaitBossReply` and the pane shows the question; your
 next turn is normally classified as the reply, or a fresh directive
 abandons it ([PBRT-2](specs/user/playbook-runtime.md#pbrt-2)).
 
-The Captain pane streams the state machine with a four-glyph vocabulary —
-`◆ ▸ ⮕ ⤷` per [PBRT-3](specs/user/playbook-runtime.md#pbrt-3) — while
-player prompts ride their own panes.
+The Captain pane shows `/code` start/stop/finished status with `◇` lines
+and streams the CODE state machine with the four-glyph vocabulary `◆ ▸ ⮕ ⤷` per
+[PBRT-3](specs/user/playbook-runtime.md#pbrt-3), while player prompts
+ride their own panes.
+
+Published configs should import the shell adapter from
+`@sublang/playbook/playbook-captain`. Existing explicit configs that
+still import `@sublang/playbook/code/tmux-play` keep resolving through
+a compatibility shim that delegates to the same shell with CODE
+registered.
 
 ### Embedding the runtime in your own host
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@sublang/playbook",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "type": "module",
-  "description": "Reference CODE playbook — XState v5 FSM, host-agnostic runtime, and tmux-play adapter for a coder/reviewer/committer loop driven by GEARS spec items.",
+  "description": "Reference CODE playbook — XState v5 FSM, host-agnostic runtime, and Playbook Captain shell for a coder/reviewer/committer loop driven by GEARS spec items.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/sublang-ai/playbook#readme",
   "repository": {
@@ -34,6 +34,12 @@
     "reference/sdlc/code.playbook/code.playbook.ts",
     "reference/sdlc/code.playbook/code.playbook.js",
     "reference/sdlc/code.playbook/code.playbook.d.ts",
+    "reference/sdlc/code.playbook/code.registry.ts",
+    "reference/sdlc/code.playbook/code.registry.js",
+    "reference/sdlc/code.playbook/code.registry.d.ts",
+    "reference/sdlc/code.playbook/playbook-captain.ts",
+    "reference/sdlc/code.playbook/playbook-captain.js",
+    "reference/sdlc/code.playbook/playbook-captain.d.ts",
     "reference/sdlc/code.playbook/code.tmux-play.ts",
     "reference/sdlc/code.playbook/code.tmux-play.js",
     "reference/sdlc/code.playbook/code.tmux-play.d.ts",
@@ -41,7 +47,7 @@
     "reference/sdlc/code.playbook/tmux-play.config.yaml",
     "reference/sdlc/code.playbook/tmux-play.production.config.yaml",
     "reference/sdlc/code.playbook/playbook-code.config.template.yaml",
-    "reference/sdlc/code.playbook/bin"
+    "reference/sdlc/code.playbook/bin/playbook-code.js"
   ],
   "bin": {
     "playbook-code": "reference/sdlc/code.playbook/bin/playbook-code.js"
@@ -51,6 +57,10 @@
       "types": "./reference/sdlc/code.playbook/code.playbook.d.ts",
       "default": "./reference/sdlc/code.playbook/code.playbook.js"
     },
+    "./playbook-captain": {
+      "types": "./reference/sdlc/code.playbook/playbook-captain.d.ts",
+      "default": "./reference/sdlc/code.playbook/playbook-captain.js"
+    },
     "./code/tmux-play": {
       "types": "./reference/sdlc/code.playbook/code.tmux-play.d.ts",
       "default": "./reference/sdlc/code.playbook/code.tmux-play.js"
@@ -58,7 +68,8 @@
   },
   "scripts": {
     "build": "tsc",
-    "test": "vitest run"
+    "test": "vitest run",
+    "playbook-code": "node reference/sdlc/code.playbook/bin/playbook-code.js"
   },
   "publishConfig": {
     "access": "public",
@@ -66,9 +77,10 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.143",
-    "@openai/codex-sdk": "^0.130.0",
+    "@openai/codex-sdk": "^0.139.0",
     "@sublang/cligent": "latest",
-    "xstate": "^5.19.4"
+    "xstate": "^5.19.4",
+    "yaml": "^2.9.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

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

@@ -8,16 +8,52 @@ import {
   copyFileSync,
   existsSync,
   mkdirSync,
+  mkdtempSync,
   readFileSync,
   realpathSync,
+  rmSync,
+  writeFileSync,
 } from 'node:fs';
-import { homedir } from 'node:os';
+import { homedir, tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import {
+  findTmuxPlayConfig,
+  loadTmuxPlayConfig,
+} from '@sublang/cligent/tmux-play';
+import {
+  parse as parseYaml,
+  parseDocument as parseYamlDocument,
+  stringify as stringifyYaml,
+} from 'yaml';
 
 const here = dirname(fileURLToPath(import.meta.url));
 const templatePath = resolve(here, '..', 'playbook-code.config.template.yaml');
 const READINESS_FAILURE_EXIT_CODE = 2;
+const COMPOSITION_FAILURE_EXIT_CODE = 1;
+const DEFAULT_NOTIFICATION_BLOCK = [
+  '',
+  '# tmux-play host notifications. Omitted turn_aborted resolves to off.',
+  'notifications:',
+  '  player_finished: bell',
+  '  turn_finished: desktop',
+  '',
+].join('\n');
+
+// PBCODE-16: the composer injects `captain.from` (the Playbook
+// Captain shell adapter module) and the `coder` / `reviewer` player
+// ids, so the user-edited overlay carries neither.
+export const PLAYBOOK_CAPTAIN_MODULE = '@sublang/playbook/playbook-captain';
+export const CODE_ADAPTER_MODULE = PLAYBOOK_CAPTAIN_MODULE;
+const CODE_ROLES = ['coder', 'reviewer'];
+// Accepted `players` keys: the two fixed CODE roles plus the optional
+// `committer` alias (a string naming one of the roles); PBCODE-17.
+const CODE_PLAYER_KEYS = [...CODE_ROLES, 'committer'];
+// Captain-judge fields inherited from a base config when the overlay
+// leaves them unset (PBCODE-16); `adapter` is handled separately
+// because it is required in the composed config.
+const CAPTAIN_INHERITED_FIELDS = ['model', 'reasoningEffort', 'permissions'];
+const PLAYER_FIELDS = ['model', 'reasoningEffort', 'permissions'];
 
 export async function runPlaybookCodeCli(options = {}) {
   const argv = [...(options.argv ?? process.argv.slice(2))];
@@ -27,6 +63,8 @@ export async function runPlaybookCodeCli(options = {}) {
   const spawnFn = options.spawn ?? spawn;
   const tmuxPlayBin = options.tmuxPlayBin ?? resolveTmuxPlayBin();
   const home = options.homeDir ?? env.HOME ?? homedir();
+  const cwd = options.cwd ?? process.cwd();
+  const configHome = resolveConfigHome(env, home);
   const userConfigPath = resolveUserConfigPath(env, home);
 
   if (argv.includes('--help') || argv.includes('-h')) {
@@ -34,92 +72,218 @@ export async function runPlaybookCodeCli(options = {}) {
     return { code: 0 };
   }
 
-  const explicitConfig = hasExplicitConfig(argv);
-  const configPath = explicitConfig ? undefined : userConfigPath;
+  // PBCODE-1: explicit `--config <path>` bypasses seeding, readiness,
+  // and composition — the path is launched verbatim.
+  if (hasExplicitConfig(argv)) {
+    return await launchTmuxPlay(spawnFn, [tmuxPlayBin, ...argv], stderr);
+  }
 
-  if (!explicitConfig) {
-    seedUserConfigIfMissing(userConfigPath, stderr);
-    const readiness = checkReadiness(userConfigPath, env, home);
-    for (const adapter of readiness.unknownAdapters) {
-      stderr.write(
-        `playbook-code: warning: no readiness check for adapter "${adapter}"\n`,
-      );
-    }
-    if (readiness.failingAdapters.length > 0) {
-      stderr.write(
-        helpText({
-          userConfigPath,
-          failingAdapters: readiness.failingAdapters,
-        }),
-      );
-      return { code: READINESS_FAILURE_EXIT_CODE };
-    }
+  seedUserConfigIfMissing(userConfigPath, stderr);
+  migrateUserConfigNotificationsIfMissing(userConfigPath, stderr);
+
+  // PBCODE-16/17: compose the launched config from the overlay plus an
+  // optional base tmux-play config. Composition failures (missing role,
+  // non-CODE role id, missing `captain.adapter`) surface a path-named
+  // error and abort before launch.
+  let composed;
+  try {
+    composed = await composeLaunchConfig({
+      overlayPath: userConfigPath,
+      cwd,
+      configHome,
+    });
+  } catch (error) {
+    stderr.write(`playbook-code: ${errorMessage(error)}\n`);
+    return { code: COMPOSITION_FAILURE_EXIT_CODE };
   }
 
-  const childArgs = explicitConfig
-    ? [tmuxPlayBin, ...argv]
-    : [tmuxPlayBin, '--config', configPath, ...argv];
-  return await launchTmuxPlay(spawnFn, childArgs, stderr);
+  // PBCODE-8: readiness reads the adapters of the composed config —
+  // including a captain adapter that may have been inherited from the
+  // base — not the raw overlay.
+  const readiness = checkReadiness(
+    adaptersFromComposedConfig(composed),
+    env,
+    home,
+  );
+  for (const adapter of readiness.unknownAdapters) {
+    stderr.write(
+      `playbook-code: warning: no readiness check for adapter "${adapter}"\n`,
+    );
+  }
+  if (readiness.failingAdapters.length > 0) {
+    stderr.write(
+      helpText({
+        userConfigPath,
+        failingAdapters: readiness.failingAdapters,
+      }),
+    );
+    return { code: READINESS_FAILURE_EXIT_CODE };
+  }
+
+  // PBCODE-16: materialize the composed config to a temp file, launch
+  // against it, and remove it before the shim exits — on normal exit,
+  // on non-zero child exit, and before re-raising a forwarded signal.
+  const { dir: tempDir, path: composedPath } = writeComposedConfig(composed);
+  try {
+    return await launchTmuxPlay(
+      spawnFn,
+      [tmuxPlayBin, '--config', composedPath, ...argv],
+      stderr,
+    );
+  } finally {
+    rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+export function resolveConfigHome(env = process.env, home = homedir()) {
+  return env.XDG_CONFIG_HOME || join(home, '.config');
 }
 
 export function resolveUserConfigPath(env = process.env, home = homedir()) {
-  const configHome = env.XDG_CONFIG_HOME || join(home, '.config');
-  return join(configHome, 'playbook', 'playbook-code.config.yaml');
+  return join(resolveConfigHome(env, home), 'playbook', 'playbook-code.config.yaml');
 }
 
-export function collectAdaptersFromConfig(source) {
-  const adapters = new Set();
-  let section = '';
-  let captainChildIndent;
-  let playerItemIndent;
-  let playerChildIndent;
-
-  for (const line of source.split(/\r?\n/)) {
-    const uncommented = stripYamlComment(line);
-    if (uncommented.trim() === '') continue;
-
-    const indent = leadingSpaceCount(uncommented);
-    const trimmed = uncommented.trim();
-
-    if (indent === 0) {
-      if (trimmed === 'captain:') section = 'captain';
-      else if (trimmed === 'players:') section = 'players';
-      else section = '';
-      captainChildIndent = undefined;
-      playerItemIndent = undefined;
-      playerChildIndent = undefined;
-      continue;
+// PBCODE-17: read the overlay, locate an optional base tmux-play config
+// with cligent's exported `findTmuxPlayConfig` (never the bare
+// `loadTmuxPlayConfig`, which writes a default config when none is
+// found), load the base only when a path is located, and compose.
+async function composeLaunchConfig({ overlayPath, cwd, configHome }) {
+  const overlay = parseYaml(readFileSync(overlayPath, 'utf8')) ?? {};
+  const basePath = findTmuxPlayConfig(cwd, configHome);
+  let base;
+  if (basePath) {
+    base = (await loadTmuxPlayConfig({ configPath: basePath })).config;
+  }
+  return composeRuntimeConfig(overlay, base);
+}
+
+/**
+ * Compose the launched tmux-play config (PBCODE-16/17) from the CODE
+ * overlay and an optional base tmux-play config.
+ *
+ * @returns {import('@sublang/cligent/tmux-play').TmuxPlayConfig}
+ */
+export function composeRuntimeConfig(
+  overlay,
+  base,
+  adapterModule = PLAYBOOK_CAPTAIN_MODULE,
+) {
+  const overlayConfig = requireObject(overlay, 'config');
+  const overlayPlayers = requireObject(overlayConfig.players, 'players');
+
+  // Reject any players key other than the two fixed CODE roles and the
+  // optional `committer` alias.
+  for (const key of Object.keys(overlayPlayers)) {
+    if (!CODE_PLAYER_KEYS.includes(key)) {
+      throw new Error(`Unknown config field players.${key}`);
     }
+  }
 
-    if (section === 'captain') {
-      captainChildIndent ??= indent;
-      if (indent === captainChildIndent) {
-        collectAdapterValue(trimmed, adapters);
-      }
-      continue;
+  // PBCODE-17: `players.committer` is an optional string naming `coder`
+  // or `reviewer`. The composer resolves it into the composed
+  // `captain.options.code.committer` below and emits no extra
+  // `players[]` entry, so the roster stays coder + reviewer.
+  let committerAlias;
+  if (overlayPlayers.committer !== undefined) {
+    const value = overlayPlayers.committer;
+    if (!CODE_ROLES.includes(value)) {
+      throw new Error(
+        `players.committer must name one of: ${CODE_ROLES.join(', ')}`,
+      );
     }
+    committerAlias = value;
+  }
 
-    if (section === 'players') {
-      if (trimmed.startsWith('- ')) {
-        playerItemIndent = indent;
-        playerChildIndent = undefined;
-        collectAdapterValue(trimmed.slice(2).trim(), adapters);
-        continue;
-      }
-      if (playerItemIndent !== undefined && indent > playerItemIndent) {
-        playerChildIndent ??= indent;
-        if (indent === playerChildIndent) {
-          collectAdapterValue(trimmed, adapters);
-        }
+  // One composed `players[]` entry per role, with `id` = the role key
+  // and that role's required `adapter` plus optional fields.
+  const players = CODE_ROLES.map((role) => {
+    if (overlayPlayers[role] === undefined) {
+      throw new Error(`Missing required field players.${role}`);
+    }
+    const block = requireObject(overlayPlayers[role], `players.${role}`);
+    if (block.adapter === undefined) {
+      throw new Error(`Missing required field players.${role}.adapter`);
+    }
+    const entry = { id: role, adapter: block.adapter };
+    for (const field of PLAYER_FIELDS) {
+      if (block[field] !== undefined) entry[field] = block[field];
+    }
+    return entry;
+  });
+
+  const overlayCaptain =
+    overlayConfig.captain === undefined
+      ? {}
+      : requireObject(overlayConfig.captain, 'captain');
+  const baseCaptain = isObject(base?.captain) ? base.captain : {};
+
+  // `captain.adapter` comes from the overlay when present, else the
+  // base; composition fails with a path-named error when neither
+  // supplies it. Role adapters are required in the overlay and are not
+  // inherited.
+  const captainAdapter = overlayCaptain.adapter ?? baseCaptain.adapter;
+  if (captainAdapter === undefined) {
+    throw new Error('Missing required field captain.adapter');
+  }
+
+  const captain = { from: adapterModule, adapter: captainAdapter };
+  for (const field of CAPTAIN_INHERITED_FIELDS) {
+    const value = overlayCaptain[field] ?? baseCaptain[field];
+    if (value !== undefined) captain[field] = value;
+  }
+
+  // PBCODE-17: the shim is the sole writer of the composed
+  // `captain.options.code.committer`. Read the overlay's
+  // `captain.options.code` (carried through unchanged), reject a
+  // directly-set `committer` there, then layer the resolved
+  // `players.committer` alias on top.
+  let overlayCode;
+  if (overlayCaptain.options !== undefined) {
+    const captainOptions = requireObject(
+      overlayCaptain.options,
+      'captain.options',
+    );
+    if (captainOptions.code !== undefined) {
+      overlayCode = requireObject(captainOptions.code, 'captain.options.code');
+      if (overlayCode.committer !== undefined) {
+        throw new Error(
+          'captain.options.code.committer is composer-owned; ' +
+            'set players.committer instead',
+        );
       }
     }
   }
+  if (overlayCode !== undefined || committerAlias !== undefined) {
+    const code = { ...(overlayCode ?? {}) };
+    if (committerAlias !== undefined) code.committer = committerAlias;
+    captain.options = { code };
+  }
+
+  // Inherit host-owned top-level fields from the base when the overlay
+  // omits them; never the base `players[]` roster.
+  const composed = {};
+  const theme = overlayConfig.theme ?? base?.theme;
+  if (theme !== undefined) composed.theme = theme;
+  const layout = overlayConfig.layout ?? base?.layout;
+  if (layout !== undefined) composed.layout = layout;
+  const notifications = overlayConfig.notifications ?? base?.notifications;
+  if (notifications !== undefined) composed.notifications = notifications;
+  composed.captain = captain;
+  composed.players = players;
+  return composed;
+}
+
+export function adaptersFromComposedConfig(config) {
+  const adapters = new Set();
+  const captainAdapter = config?.captain?.adapter;
+  if (captainAdapter) adapters.add(captainAdapter);
+  for (const player of config?.players ?? []) {
+    if (player?.adapter) adapters.add(player.adapter);
+  }
   return [...adapters];
 }
 
-export function checkReadiness(configPath, env = process.env, home = homedir()) {
-  const config = readFileSync(configPath, 'utf8');
-  const adapters = collectAdaptersFromConfig(config);
+export function checkReadiness(adapters, env = process.env, home = homedir()) {
   const failingAdapters = [];
   const unknownAdapters = [];
 
@@ -142,6 +306,15 @@ export function checkReadiness(configPath, env = process.env, home = homedir())
   return { failingAdapters, unknownAdapters };
 }
 
+function writeComposedConfig(composed) {
+  const dir = mkdtempSync(join(tmpdir(), 'playbook-code-'));
+  // cligent's loader only accepts a `.yaml` extension; name the temp
+  // file accordingly.
+  const path = join(dir, 'tmux-play.config.yaml');
+  writeFileSync(path, stringifyYaml(composed));
+  return { dir, path };
+}
+
 function seedUserConfigIfMissing(userConfigPath, stderr) {
   if (existsSync(userConfigPath)) return;
   mkdirSync(dirname(userConfigPath), { recursive: true });
@@ -149,6 +322,27 @@ function seedUserConfigIfMissing(userConfigPath, stderr) {
   stderr.write(`playbook-code: created config at ${userConfigPath}\n`);
 }
 
+function migrateUserConfigNotificationsIfMissing(userConfigPath, stderr) {
+  const source = readFileSync(userConfigPath, 'utf8');
+  let parsed;
+  try {
+    const document = parseYamlDocument(source);
+    if (document.errors.length > 0) return;
+    parsed = document.contents === null ? {} : document.toJS();
+  } catch {
+    return;
+  }
+  if (!isObject(parsed) || hasOwn(parsed, 'notifications')) return;
+  const separator = source.endsWith('\n') ? '' : '\n';
+  writeFileSync(
+    userConfigPath,
+    `${source}${separator}${DEFAULT_NOTIFICATION_BLOCK}`,
+  );
+  stderr.write(
+    `playbook-code: added notifications defaults to config at ${userConfigPath}\n`,
+  );
+}
+
 function hasExplicitConfig(argv) {
   return argv.some((arg) => arg === '--config' || arg.startsWith('--config='));
 }
@@ -175,10 +369,11 @@ function helpText({ userConfigPath, failingAdapters = [] }) {
     '',
     'Agent swap recipe:',
     '  - change captain.adapter and captain.model for the Captain/Judge',
-    '  - change each player adapter and (optional) model for the Coder',
-    '    and Reviewer; model when pinned, else adapter, is substituted',
-    '    into <coder-llm>/<reviewer-llm> player prompts (PBRT-4)',
-    '  - keep captain.from and players[].id fixed',
+    '  - change adapter and model under players.coder and players.reviewer',
+    '    for the Coder and Reviewer; model when pinned, else adapter, is',
+    '    substituted into <coder-llm>/<reviewer-llm> player prompts (PBRT-4)',
+    '  - the composer injects captain.from; the role keys coder and',
+    '    reviewer are fixed',
     '',
   ].join('\n');
 }
@@ -220,41 +415,19 @@ function resolveTmuxPlayBin() {
   return join(dirname(fileURLToPath(tmuxPlayIndexUrl)), 'cli.js');
 }
 
-function stripYamlComment(line) {
-  let quote = '';
-  for (let index = 0; index < line.length; index += 1) {
-    const char = line[index];
-    if ((char === '"' || char === "'") && line[index - 1] !== '\\') {
-      quote = quote === char ? '' : quote || char;
-      continue;
-    }
-    if (char === '#' && !quote) {
-      return line.slice(0, index);
-    }
-  }
-  return line;
+function isObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
-function unquoteYamlScalar(value) {
-  const trimmed = value.trim();
-  if (
-    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
-    (trimmed.startsWith("'") && trimmed.endsWith("'"))
-  ) {
-    return trimmed.slice(1, -1).trim();
-  }
-  return trimmed;
+function hasOwn(value, key) {
+  return Object.prototype.hasOwnProperty.call(value, key);
 }
 
-function collectAdapterValue(trimmedLine, adapters) {
-  const match = trimmedLine.match(/^adapter\s*:\s*(.+?)\s*$/);
-  if (!match) return;
-  const value = unquoteYamlScalar(match[1].trim());
-  if (value) adapters.add(value);
-}
-
-function leadingSpaceCount(line) {
-  return line.length - line.trimStart().length;
+function requireObject(value, path) {
+  if (!isObject(value)) {
+    throw new Error(`${path} must be an object`);
+  }
+  return value;
 }
 
 function errorMessage(error) {

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

@@ -23,6 +23,7 @@ export type CaptainInput = {
     challenges?: string;
     coderPlayer?: string;
     reviewerPlayer?: string;
+    committerPlayer?: string;
     pendingBossQuestion?: PendingBossQuestion;
     bossReply?: string;
 };