@sublang/playbook 0.4.2 → 0.5.0

package/reference/sdlc/code.playbook/code.tmux-play.ts

@@ -17,15 +17,75 @@ import createPlaybookRuntime, {
   type PlaybookRuntime,
 } from './code.playbook.js';
 
+// PBRT-29/30: CODE runtime options are carried under
+// `captain.options.code`, a namespaced object the host forwards
+// verbatim through `captain.options`. cligent neither reads nor
+// validates `options.code` (PBRT-30); this adapter is the sole
+// validator. The CODE options schema defines one key, `committer`: an
+// optional Committer-alias player id, one of the baked player ids
+// `coder` / `reviewer`. A valid `options.code` is absent, `{}`, or
+// `{ committer: 'coder' | 'reviewer' }`; every other key is unknown
+// and rejected with a path-named error, and an out-of-range
+// `committer` value is rejected naming `captain.options.code.committer`.
+// A further CODE option shall be introduced as its own higher-numbered
+// item that widens `CODE_OPTION_KEYS`; the validator still fails closed
+// on stray keys.
+const CODE_OPTION_KEYS = new Set<string>(['committer']);
+const COMMITTER_PLAYER_IDS = new Set<string>(['coder', 'reviewer']);
+
+// The validated CODE options set. `committer`, when present, is the
+// resolved Committer-alias player id (PBRT-8 / PBRT-30); a future CODE
+// option widens both this type and `CODE_OPTION_KEYS`.
+export interface CodeOptions {
+  committer?: 'coder' | 'reviewer';
+}
+
+export function validateCodeOptions(captainOptions: unknown): CodeOptions {
+  const code = readCodeNamespace(captainOptions);
+  if (code === undefined) return {};
+  if (typeof code !== 'object' || code === null || Array.isArray(code)) {
+    throw new Error('captain.options.code must be an object');
+  }
+  for (const key of Object.keys(code)) {
+    if (!CODE_OPTION_KEYS.has(key)) {
+      throw new Error(`Unknown config field captain.options.code.${key}`);
+    }
+  }
+  const options: CodeOptions = {};
+  const committer = (code as Record<string, unknown>).committer;
+  if (committer !== undefined) {
+    if (typeof committer !== 'string' || !COMMITTER_PLAYER_IDS.has(committer)) {
+      throw new Error(
+        "captain.options.code.committer must be 'coder' or 'reviewer'",
+      );
+    }
+    options.committer = committer as 'coder' | 'reviewer';
+  }
+  return options;
+}
+
+function readCodeNamespace(captainOptions: unknown): unknown {
+  if (
+    typeof captainOptions !== 'object' ||
+    captainOptions === null ||
+    Array.isArray(captainOptions)
+  ) {
+    return undefined;
+  }
+  return (captainOptions as Record<string, unknown>).code;
+}
+
 // Captain factory per TMUX-014: `(options: unknown) => Captain`.
-// `options` is whatever `captain.options` carries in the YAML config.
-// The per-run player identity strings (`coderPlayer`, `reviewerPlayer`)
-// are derived from `session.players` at init time per PBRT-4 —
-// preferring each entry's `model` and falling back to `adapter` when
-// no model is pinned — so player prompts and commit-message trailers
-// carry the concrete model identity (e.g. `claude-opus-4-7`) rather
-// than the adapter family name (e.g. `claude`). Any same-named keys
-// in `options` are ignored.
+// `options` is whatever `captain.options` carries in the YAML config;
+// CODE reads only the namespaced `options.code` (PBRT-30). The per-run
+// player identity strings (`coderPlayer`, `reviewerPlayer`) are
+// derived from `session.players` at init time per PBRT-4 — preferring
+// each entry's `model` and falling back to `adapter` when no model is
+// pinned — so player prompts and commit-message trailers carry the
+// concrete model identity (e.g. `claude-opus-4-7`) rather than the
+// adapter family name (e.g. `claude`). They come from `session.players`
+// independent of `captain.options.code` and override any same-named
+// keys.
 export default function createCodeTmuxPlayCaptain(
   options: unknown,
 ): Captain {
@@ -40,17 +100,28 @@ export default function createCodeTmuxPlayCaptain(
 
   return {
     async init(session: CaptainSession): Promise<void> {
+      // PBRT-30: validate `captain.options.code` before constructing
+      // the runtime so a stray key fails `init` closed with a
+      // path-named error; the empty schema yields an empty options set.
+      const codeOptions = validateCodeOptions(options);
       const playerIdentity = (id: string): string | undefined => {
         const entry = session.players.find((p) => p.id === id);
         return entry?.model ?? entry?.adapter;
       };
       const coderPlayer = playerIdentity('coder');
       const reviewerPlayer = playerIdentity('reviewer');
-      runtime = createPlaybookRuntime({
-        ...(options as CodePlaybookOptions),
+      // Identity strings from `session.players` override any same-named
+      // keys and are independent of `captain.options.code` (PBRT-30).
+      // The validated `committer` alias threads in as the runtime's
+      // Committer player id (`committerPlayer`, PBRT-8).
+      const runtimeOptions: CodePlaybookOptions = {
         coderPlayer,
         reviewerPlayer,
-      });
+        ...(codeOptions.committer !== undefined
+          ? { committerPlayer: codeOptions.committer }
+          : {}),
+      };
+      runtime = createPlaybookRuntime(runtimeOptions);
       const ports: PlaybookPorts = {
         callPlayer: async (playerId, prompt, _signal) => {
           if (!activeContext) {
@@ -73,7 +144,12 @@ export default function createCodeTmuxPlayCaptain(
           if (!activeContext) {
             throw new Error('callJudge invoked outside a Boss turn');
           }
-          const r = await activeContext.callCaptain(prompt);
+          // PBRT-15 / DR-007: run the judge call hidden so its JSON
+          // reply never reaches the Boss pane; the runtime composes the
+          // human-readable pane lines (PBRT-3) from the parsed result.
+          const r = await activeContext.callCaptain(prompt, {
+            visibility: 'hidden',
+          });
           if (r.status !== 'ok') {
             throw new Error(
               r.error ?? `callCaptain status "${r.status}"`,

package/reference/sdlc/code.playbook/playbook-code.config.template.yaml

@@ -1,29 +1,44 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 
-# Seed template for the user-level playbook-code config.
+# Seed template for the user-level playbook-code CODE overlay.
 # First run copies this file to:
 #   ${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook-code.config.yaml
 #
-# Safe tuning points:
-# - Change captain.adapter / captain.model / captain.reasoningEffort to
-#   pick the judge/Captain agent and its reasoning tier.
-# - Change each player's adapter, model, and reasoningEffort to pick
-#   the Coder and Reviewer agents.
+# This is a CODE *overlay*, not a full tmux-play config: playbook-code
+# composes the launched tmux-play config from it at startup (PBCODE-16).
+# The composer injects captain.from (the CODE adapter module) and the
+# coder / reviewer player ids, and can inherit theme plus captain-judge
+# defaults from an existing tmux-play config — so you only tune the
+# fields below.
 #
-# PBRT-4 host-configuration invariants:
-# - captain.from must keep pointing at the CODE tmux-play adapter module.
-# - players[].id must remain exactly "coder" and "reviewer"; the runtime routes
-#   to those baked ids and does not remap them. The adapter derives the
-#   per-run player identity strings (substituted into <coder-llm> /
-#   <reviewer-llm> in player prompts) from each entry's model when pinned
-#   and falls back to its adapter when no model is set, so the Committer's
-#   commit-message trailers can name the concrete model.
+# Safe tuning points:
+# - captain.adapter / model / reasoningEffort pick the judge/Captain
+#   agent and its reasoning tier.
+# - players.coder and players.reviewer pick the Coder and Reviewer
+#   agents; set each role's adapter (required) and optional model /
+#   reasoningEffort / permissions. Each role's model when pinned, else
+#   its adapter, doubles as the identity string the adapter substitutes
+#   into <coder-llm> / <reviewer-llm> in player prompts (PBRT-4), so pin
+#   a model if you want the Committer's commit-message trailers to name
+#   the concrete model.
+# - Codex roles that run git under mode: auto need .git in
+#   permissions.writablePaths so git metadata writes stay profile-scoped
+#   instead of requiring bypass permissions.
+# - players.committer optionally aliases the Committer to a role
+#   (coder or reviewer); that role's pane runs the commit turn. The
+#   seeded value is reviewer; omit it to fall back to the coder.
+# - layout sizes the tmux window (layout.window: columns × rows) and
+#   sets the relative column widths (layout.columnWeights) for the
+#   Boss/Captain, Coder, and Reviewer columns.
+
+layout:
+  window:
+    columns: 174
+    rows: 49
+  columnWeights: [4, 6, 6]
 
 captain:
-  # PBRT-4 invariant: keep this adapter module path unchanged.
-  from: "@sublang/playbook/code/tmux-play"
-  # Tunable: the Captain/Judge adapter, model, and reasoning effort.
   adapter: claude
   model: claude-sonnet-4-6
   reasoningEffort: high
@@ -31,17 +46,18 @@ captain:
     mode: auto
 
 players:
-  # PBRT-4 invariant: keep id: coder. Tune adapter/model if desired.
-  - id: coder
-    adapter: claude
-    model: claude-opus-4-7
+  coder:
+    adapter: codex
+    model: gpt-5.5
     reasoningEffort: xhigh
     permissions:
       mode: auto
-  # PBRT-4 invariant: keep id: reviewer. Tune adapter/model if desired.
-  - id: reviewer
-    adapter: codex
-    model: gpt-5.5
+      writablePaths:
+        - .git
+  reviewer:
+    adapter: claude
+    model: claude-opus-4-8
     reasoningEffort: xhigh
     permissions:
       mode: auto
+  committer: reviewer