@sublang/playbook 0.4.2 → 0.5.0

package/README.md

@@ -82,7 +82,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 +98,26 @@ $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
-[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`).
-
-For example, this swaps the Coder to Codex and the Reviewer to Claude:
+`captain.adapter`, `captain.model`, and each role's `adapter` and
+`model` under `players.coder` / `players.reviewer`. The composer owns
+`captain.from` and 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 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`).
+
+`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 +125,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "0.4.2",
+  "version": "0.5.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.",
   "license": "Apache-2.0",
@@ -41,7 +41,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"
@@ -58,7 +58,8 @@
   },
   "scripts": {
     "build": "tsc",
-    "test": "vitest run"
+    "test": "vitest run",
+    "playbook-code": "node reference/sdlc/code.playbook/bin/playbook-code.js"
   },
   "publishConfig": {
     "access": "public",
@@ -68,7 +69,8 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.143",
     "@openai/codex-sdk": "^0.130.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,39 @@ 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, 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;
+
+// PBCODE-16: the composer injects `captain.from` (the CODE adapter
+// module) and the `coder` / `reviewer` player ids, so the user-edited
+// overlay carries neither.
+export const CODE_ADAPTER_MODULE = '@sublang/playbook/code/tmux-play';
+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 +50,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 +59,226 @@ 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);
+
+  // 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;
+    // cligent's loader normalizes a discovered base to captain / players
+    // / theme and drops host fields it does not model yet — notably
+    // `layout`. Recover a base `layout` from the raw base YAML so base
+    // inheritance (PBCODE-16/17) holds; the `=== undefined` guard makes
+    // this inert once a future loader preserves `layout` itself.
+    if (base && base.layout === undefined) {
+      const rawBase = parseYaml(readFileSync(basePath, 'utf8'));
+      if (isObject(rawBase) && rawBase.layout !== undefined) {
+        base.layout = rawBase.layout;
+      }
     }
+  }
+  return composeRuntimeConfig(overlay, base);
+}
 
-    if (section === 'captain') {
-      captainChildIndent ??= indent;
-      if (indent === captainChildIndent) {
-        collectAdapterValue(trimmed, adapters);
-      }
-      continue;
+/**
+ * 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 = CODE_ADAPTER_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 === '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);
-        }
+  // 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;
+  }
+
+  // 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 `theme` and `layout` 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;
+  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 +301,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 });
@@ -175,10 +343,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 +389,15 @@ 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();
+function requireObject(value, path) {
+  if (!isObject(value)) {
+    throw new Error(`${path} must be an object`);
   }
-  return trimmed;
-}
-
-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;
+  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;
 };