@sublang/playbook 0.7.0 → 0.9.0

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

@@ -11,9 +11,9 @@ import type {
   PlaybookPorts,
   PlaybookRuntime,
 } from './code.playbook.js';
-import {
-  codePlaybookRegistryEntry,
-  type RegistryPlayer,
+import type {
+  PlaybookSummaryPolicy,
+  RegistryPlayer,
 } from './code.registry.js';
 
 export interface CreatePlaybookRuntimeOptions {
@@ -21,20 +21,38 @@ export interface CreatePlaybookRuntimeOptions {
   players: readonly RegistryPlayer[];
 }
 
+export interface PlaybookCaptainDeps {
+  loadModule?: (specifier: string) => Promise<unknown>;
+}
+
 export interface PlaybookCaptainRegistryEntry {
   id: string;
   command: string;
   intent: string;
+  requiredRoleIds: readonly string[];
   idleStateId: string;
   finalStateId: string;
-  copyPasteGuardNames: readonly string[];
-  stateCountLabels?: Readonly<Record<string, string>>;
+  parkStateIds: readonly string[];
+  summaryPolicy?: PlaybookSummaryPolicy;
   validateOptions(captainOptions: unknown): unknown;
   createRuntime(options: CreatePlaybookRuntimeOptions): PlaybookRuntime;
 }
 
+// Per-enabled-playbook binding the shell resolves at init from
+// `captain.options.playbooks`: each playbook binds its local roles to
+// `<id>-<role>` host players and carries the generated visible set.
+interface Enablement {
+  entry: PlaybookCaptainRegistryEntry;
+  command: string;
+  optionInput: unknown;
+  boundPlayers: readonly RegistryPlayer[];
+  hostPlayerId: (localRole: string) => string;
+  visiblePlayerIds?: readonly string[];
+}
+
 interface ActiveEngagement {
   entry: PlaybookCaptainRegistryEntry;
+  enablement: Enablement;
   runtime: PlaybookRuntime;
 }
 
@@ -70,10 +88,6 @@ interface ActiveTurnSummary {
   stateCounts: Map<string, number>;
 }
 
-export const playbookCaptainRegistry: readonly PlaybookCaptainRegistryEntry[] = [
-  codePlaybookRegistryEntry,
-];
-
 function parseRegisteredCommand(
   prompt: string,
 ): { command: string; text: string } | undefined {
@@ -84,10 +98,6 @@ function parseRegisteredCommand(
   return { command: match[1], text: (match[2] ?? '').trim() };
 }
 
-function playbookCommandLabel(entry: PlaybookCaptainRegistryEntry): string {
-  return `/${entry.command}`;
-}
-
 function visibleChatEnvelope(message: string): string {
   return [
     'You are the Playbook Captain shell.',
@@ -101,9 +111,9 @@ function visibleTurnSummaryEnvelope(input: {
   submittedText: string;
   counts: TurnSummaryCounts;
   progressPhrase: string;
-  reviewRebuttalRounds: number;
+  progressRounds: number;
+  savedLine: string;
 }): string {
-  const savedLine = savedCountsLine(input.counts, input.reviewRebuttalRounds);
   return [
     'You are the Playbook Captain shell.',
     'This is visible Boss chat after a sub-playbook command completed. Do not reveal hidden control JSON, hidden router decisions, or hidden judge replies.',
@@ -112,39 +122,20 @@ function visibleTurnSummaryEnvelope(input: {
     'State only what was done or what changed; do not explain how it was done.',
     'Do not list raw state names, transitions, guard names, prompts, tools, hidden calls, or reasoning.',
     'If progress detail is useful, use only the aggregate progress phrase supplied below.',
-    'Do not mention counts for plan or implementation steps, tests green, or any other internal state.',
-    `Then write the saved-counts line exactly: ${savedLine}`,
+    "Do not mention counts for states the active playbook's summary policy does not label.",
+    `Then write the saved-counts line exactly: ${input.savedLine}`,
     'Use the exact counts supplied; do not change them.',
-    'Do not repeat the exact review/rebuttal round count outside the saved-counts line.',
+    'Do not repeat the exact progress round count outside the saved-counts line.',
     `Playbook: ${input.playbookId}`,
     `Submitted Boss text:\n${input.submittedText}`,
     `Progress counts:\n${input.progressPhrase}`,
     `Counts:\n${JSON.stringify({
       ...input.counts,
-      reviewRebuttalRounds: input.reviewRebuttalRounds,
+      progressRounds: input.progressRounds,
     })}`,
   ].join('\n\n');
 }
 
-function countNoun(count: number, singular: string, plural = `${singular}s`): string {
-  return `${count} ${count === 1 ? singular : plural}`;
-}
-
-function savedCountsLine(
-  counts: TurnSummaryCounts,
-  reviewRebuttalRounds: number,
-): string {
-  return [
-    'Saved you',
-    countNoun(counts.interruptions, 'interruption'),
-    'and',
-    countNoun(counts.copyPastes, 'copy-paste'),
-    'across',
-    countNoun(reviewRebuttalRounds, 'round'),
-    'of reviews/rebuttals.',
-  ].join(' ');
-}
-
 function stateCountLabel(
   stateId: string,
   entry: PlaybookCaptainRegistryEntry,
@@ -152,7 +143,7 @@ function stateCountLabel(
   if (stateId === entry.idleStateId || stateId === entry.finalStateId) {
     return undefined;
   }
-  const registryLabel = entry.stateCountLabels?.[stateId]?.trim();
+  const registryLabel = entry.summaryPolicy?.stateCountLabels?.[stateId]?.trim();
   return registryLabel || undefined;
 }
 
@@ -178,27 +169,144 @@ function guardFromJudgeReply(finalText: string): string | undefined {
   return /"guard"\s*:\s*"([^"]+)"/.exec(finalText)?.[1];
 }
 
-function normalizeRegistry(
-  registry: readonly PlaybookCaptainRegistryEntry[],
-): {
+function isValidRegistryEntry(
+  value: unknown,
+): value is PlaybookCaptainRegistryEntry {
+  if (typeof value !== 'object' || value === null) return false;
+  const e = value as Record<string, unknown>;
+  return (
+    typeof e.id === 'string' &&
+    typeof e.command === 'string' &&
+    typeof e.intent === 'string' &&
+    Array.isArray(e.requiredRoleIds) &&
+    typeof e.idleStateId === 'string' &&
+    typeof e.finalStateId === 'string' &&
+    Array.isArray(e.parkStateIds) &&
+    typeof e.validateOptions === 'function' &&
+    typeof e.createRuntime === 'function'
+  );
+}
+
+function readPlaybooksConfig(
+  options: unknown,
+): Record<string, unknown> | undefined {
+  if (typeof options !== 'object' || options === null) return undefined;
+  const pb = (options as Record<string, unknown>).playbooks;
+  if (typeof pb !== 'object' || pb === null || Array.isArray(pb)) {
+    return undefined;
+  }
+  return pb as Record<string, unknown>;
+}
+
+interface BuiltRegistry {
   entries: readonly PlaybookCaptainRegistryEntry[];
   byCommand: Map<string, PlaybookCaptainRegistryEntry>;
   byId: Map<string, PlaybookCaptainRegistryEntry>;
-} {
+  enablementById: Map<string, Enablement>;
+}
+
+// Resolve the active registry at init from `captain.options.playbooks`
+// (CAPTAIN-16): each enabled playbook is loaded from its explicit `from`
+// module and bound to namespaced `<id>-<role>` host players.
+async function buildEnablements(
+  options: unknown,
+  players: readonly RegistryPlayer[],
+  loadModule: (specifier: string) => Promise<unknown>,
+): Promise<BuiltRegistry> {
+  const entries: PlaybookCaptainRegistryEntry[] = [];
   const byCommand = new Map<string, PlaybookCaptainRegistryEntry>();
   const byId = new Map<string, PlaybookCaptainRegistryEntry>();
-  for (const entry of registry) {
-    byCommand.set(entry.command, entry);
+  const enablementById = new Map<string, Enablement>();
+
+  const config = readPlaybooksConfig(options);
+  if (config === undefined) {
+    throw new Error('captain.options.playbooks is required');
+  }
+
+  const ids = Object.keys(config);
+  if (ids.length === 0) {
+    throw new Error(
+      'captain.options.playbooks must enable at least one playbook',
+    );
+  }
+  for (const id of ids) {
+    const block = config[id];
+    if (typeof block !== 'object' || block === null || Array.isArray(block)) {
+      throw new Error(`captain.options.playbooks.${id} must be an object`);
+    }
+    const record = block as Record<string, unknown>;
+    const from = record.from;
+    if (typeof from !== 'string' || from.length === 0) {
+      throw new Error(
+        `captain.options.playbooks.${id}.from must be a module specifier`,
+      );
+    }
+    let mod: unknown;
+    try {
+      mod = await loadModule(from);
+    } catch (cause) {
+      throw new Error(
+        `captain.options.playbooks.${id}.from "${from}" failed to import: ${String(
+          (cause as { message?: unknown })?.message ?? cause,
+        )}`,
+      );
+    }
+    const entry = (mod as { default?: unknown })?.default;
+    if (!isValidRegistryEntry(entry)) {
+      throw new Error(
+        `captain.options.playbooks.${id}.from "${from}" exposes no valid registry entry`,
+      );
+    }
+    if (entry.id !== id) {
+      throw new Error(
+        `captain.options.playbooks.${id} key must equal the module manifest id "${entry.id}"`,
+      );
+    }
+    if (byId.has(entry.id)) {
+      throw new Error(
+        `captain.options.playbooks has a duplicate playbook id "${entry.id}"`,
+      );
+    }
+    const command =
+      typeof record.command === 'string' && record.command.length > 0
+        ? record.command
+        : entry.command;
+    if (byCommand.has(command)) {
+      throw new Error(
+        `captain.options.playbooks has a duplicate effective command "${command}"`,
+      );
+    }
+    const boundPlayers = entry.requiredRoleIds.map((role) => {
+      const host = players.find((p) => p.id === `${entry.id}-${role}`);
+      return { id: role, adapter: host?.adapter, model: host?.model };
+    });
+    entries.push(entry);
     byId.set(entry.id, entry);
+    byCommand.set(command, entry);
+    enablementById.set(entry.id, {
+      entry,
+      command,
+      optionInput: record.options,
+      boundPlayers,
+      hostPlayerId: (localRole) => `${entry.id}-${localRole}`,
+      visiblePlayerIds: entry.requiredRoleIds.map(
+        (role) => `${entry.id}-${role}`,
+      ),
+    });
   }
-  return { entries: registry, byCommand, byId };
+  return { entries, byCommand, byId, enablementById };
 }
 
 export function createPlaybookCaptainShell(
   options: unknown,
-  registry: readonly PlaybookCaptainRegistryEntry[] = playbookCaptainRegistry,
+  deps: PlaybookCaptainDeps = {},
 ): Captain {
-  const { entries, byCommand, byId } = normalizeRegistry(registry);
+  const loadModule =
+    deps.loadModule ?? ((specifier: string) => import(specifier));
+  let entries: readonly PlaybookCaptainRegistryEntry[] = [];
+  let byCommand = new Map<string, PlaybookCaptainRegistryEntry>();
+  let byId = new Map<string, PlaybookCaptainRegistryEntry>();
+  let enablementById = new Map<string, Enablement>();
   let session: CaptainSession | undefined;
   let players: readonly RegistryPlayer[] = [];
   let activeContext: CaptainContext | undefined;
@@ -315,8 +423,7 @@ export function createPlaybookCaptainShell(
 
     if (
       stateId === active.entry.idleStateId ||
-      stateId === 'failed' ||
-      stateId === 'awaitBossReply'
+      active.entry.parkStateIds.includes(stateId)
     ) {
       await setMode('engaged.parked', `sub-runtime:${stateId}`);
     }
@@ -327,7 +434,10 @@ export function createPlaybookCaptainShell(
       if (!activeContext) {
         throw new Error('callPlayer invoked outside a Boss turn');
       }
-      const result = await activeContext.callPlayer(playerId, prompt);
+      const hostPlayerId = active
+        ? active.enablement.hostPlayerId(playerId)
+        : playerId;
+      const result = await activeContext.callPlayer(hostPlayerId, prompt);
       if (activeTurnSummary) {
         activeTurnSummary.counts.interruptions++;
       }
@@ -355,7 +465,7 @@ export function createPlaybookCaptainShell(
       const guard = guardFromJudgeReply(result.finalText);
       if (
         guard &&
-        active?.entry.copyPasteGuardNames.includes(guard) &&
+        active?.entry.summaryPolicy?.copyPasteGuardNames.includes(guard) &&
         activeTurnSummary
       ) {
         activeTurnSummary.counts.copyPastes++;
@@ -376,24 +486,33 @@ export function createPlaybookCaptainShell(
     },
   });
 
+  // CAPTAIN-22: before dispatching to a playbook, request tmux-play
+  // visibility for that playbook's generated host players. A pane
+  // reconciliation failure is display-only in tmux-play and does not
+  // reject; the legacy path carries no generated set and skips this.
+  const requestVisibility = async (enablement: Enablement): Promise<void> => {
+    const ids = enablement.visiblePlayerIds;
+    if (!ids || ids.length === 0 || !activeContext) return;
+    await activeContext.setVisiblePlayers(ids);
+  };
+
   const engage = async (
     entry: PlaybookCaptainRegistryEntry,
   ): Promise<ActiveEngagement> => {
     if (active?.entry.id === entry.id) return active;
+    const enablement = enablementById.get(entry.id)!;
     const runtime = entry.createRuntime({
-      captainOptions: options,
-      players,
+      captainOptions: enablement.optionInput,
+      players: enablement.boundPlayers,
     });
-    active = { entry, runtime };
+    active = { entry, enablement, runtime };
     latestSubRuntimeStateId = undefined;
     pendingBossQuestion = undefined;
     lastError = undefined;
     finalDisposalRequested = undefined;
     await setMode('engaged.parked', 'engage', entry.id);
     await runtime.init(createPorts());
-    await requireSession().emitStatus(
-      `◇ ${playbookCommandLabel(entry)} started`,
-    );
+    await requireSession().emitStatus(`◇ /${enablement.command} started`);
     return active;
   };
 
@@ -402,23 +521,24 @@ export function createPlaybookCaptainShell(
     text: string,
     context: CaptainContext,
   ): Promise<void> => {
+    await requestVisibility(engagement.enablement);
+    const policy = engagement.entry.summaryPolicy;
     const summaryCounts: TurnSummaryCounts = {
       interruptions: 0,
       copyPastes: 0,
     };
     const summaryStateCounts = new Map<string, number>();
     let shouldSummarize = false;
-    activeTurnSummary = {
-      counts: summaryCounts,
-      stateCounts: summaryStateCounts,
-    };
+    activeTurnSummary = policy
+      ? { counts: summaryCounts, stateCounts: summaryStateCounts }
+      : undefined;
     await setMode('engaged.driving', 'submit');
     try {
       await engagement.runtime.handleBossInput({
         text,
         signal: context.signal,
       });
-      shouldSummarize = true;
+      shouldSummarize = policy !== undefined;
     } finally {
       activeTurnSummary = undefined;
       if (active === engagement && finalDisposalRequested === engagement) {
@@ -428,13 +548,15 @@ export function createPlaybookCaptainShell(
         await setMode('engaged.parked', 'turn.settled');
       }
     }
-    if (shouldSummarize) {
+    if (shouldSummarize && policy) {
+      const progressRounds = summaryProgressRoundCount(summaryStateCounts);
       await callVisibleTurnSummary(context, {
         playbookId: engagement.entry.id,
         submittedText: text,
         counts: summaryCounts,
         progressPhrase: summaryProgressPhrase(summaryStateCounts),
-        reviewRebuttalRounds: summaryProgressRoundCount(summaryStateCounts),
+        progressRounds,
+        savedLine: policy.savedCountsLine(summaryCounts, progressRounds),
       });
     }
   };
@@ -445,7 +567,7 @@ export function createPlaybookCaptainShell(
     const engagement = active;
     if (!engagement) return;
     const playbookId = engagement.entry.id;
-    const commandLabel = playbookCommandLabel(engagement.entry);
+    const commandLabel = `/${engagement.enablement.command}`;
     active = undefined;
     finalDisposalRequested = undefined;
     if (reason === 'dispose') {
@@ -487,7 +609,8 @@ export function createPlaybookCaptainShell(
       submittedText: string;
       counts: TurnSummaryCounts;
       progressPhrase: string;
-      reviewRebuttalRounds: number;
+      progressRounds: number;
+      savedLine: string;
     },
   ): Promise<void> => {
     const result = await context.callCaptain(visibleTurnSummaryEnvelope(input));
@@ -513,7 +636,7 @@ export function createPlaybookCaptainShell(
       `Registry:\n${JSON.stringify(
         entries.map((entry) => ({
           id: entry.id,
-          command: entry.command,
+          command: enablementById.get(entry.id)?.command ?? entry.command,
           intent: entry.intent,
         })),
       )}`,
@@ -626,7 +749,7 @@ export function createPlaybookCaptainShell(
       return;
     }
 
-    const dismissedCommandLabel = playbookCommandLabel(active.entry);
+    const dismissedCommandLabel = `/${active.enablement.command}`;
     await disposeActive('dismiss');
     await callVisibleChat(
       context,
@@ -639,19 +762,21 @@ export function createPlaybookCaptainShell(
     text: string,
     context: CaptainContext,
   ): Promise<void> => {
+    const enablement = enablementById.get(entry.id)!;
     if (active && active.entry.id !== entry.id) {
       await callVisibleChat(
         context,
-        `/${active.entry.command} is already running. Finish or stop it before starting /${entry.command}.`,
+        `/${active.enablement.command} is already running. Finish or stop it before starting /${enablement.command}.`,
       );
       return;
     }
 
     const engagement = await engage(entry);
     if (text.length === 0) {
+      await requestVisibility(engagement.enablement);
       await callVisibleChat(
         context,
-        `Ask what task to run with /${entry.command}.`,
+        `Ask what task to run with /${enablement.command}.`,
       );
       return;
     }
@@ -663,8 +788,13 @@ export function createPlaybookCaptainShell(
     async init(initSession: CaptainSession): Promise<void> {
       session = initSession;
       players = initSession.players;
-      for (const entry of entries) {
-        entry.validateOptions(options);
+      const built = await buildEnablements(options, players, loadModule);
+      entries = built.entries;
+      byCommand = built.byCommand;
+      byId = built.byId;
+      enablementById = built.enablementById;
+      for (const enablement of enablementById.values()) {
+        enablement.entry.validateOptions(enablement.optionInput);
       }
       await setMode('chat', 'init');
     },

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

@@ -0,0 +1,58 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+# Generic `playbook` launcher config.
+# Top-level host fields only — no `config:` wrapper, no top-level `players`.
+# The launcher injects captain.from and the namespaced <id>-<role> host
+# players, then launches cligent's tmux-play under the Playbook Captain shell.
+
+# Reusable agent settings. A profile id must not be an adapter shorthand
+# (claude, codex). Reference a profile by id from captain / players below.
+# Profile ids name the underlying agent/model (e.g. claude-opus,
+# codex-gpt) so they read distinctly from the captain / coder / reviewer
+# player roles that reference them.
+# Every seeded agent runs in cligent's protected auto mode
+# (permissions.mode: auto): claude maps it to permissionMode auto, codex to
+# on-request + auto_review. Codex roles also grant writablePaths: ['.git']
+# so commit turns can write git metadata under the codex sandbox.
+profiles:
+  claude-opus:
+    adapter: claude
+    model: claude-opus-4-8
+    reasoningEffort: high
+    permissions:
+      mode: auto
+  claude-opus-1m:
+    adapter: claude
+    model: claude-opus-4-8[1m]
+    reasoningEffort: xhigh
+    permissions:
+      mode: auto
+  codex-gpt:
+    adapter: codex
+    model: gpt-5.5
+    reasoningEffort: xhigh
+    permissions:
+      mode: auto
+      writablePaths: ['.git']
+
+# The Captain/Judge agent: a profile id, an adapter shorthand, or a full
+# tmux-play agent block (which may carry a `profile:` key).
+captain: claude-opus
+
+# Host notifications. Omitting turn_aborted resolves it to off.
+notifications:
+  player_finished: bell
+  turn_finished: desktop
+
+# Enabled playbooks. Each is loaded from its explicit `from` module; the
+# `<id>` key must equal that module's manifest id. `from`, `command`, and
+# `players` are launcher-owned; every other key (e.g. CODE's `committer`)
+# is that playbook's option slice.
+playbooks:
+  code:
+    from: "@sublang/playbook/code/registry"
+    players:
+      coder: claude-opus-1m
+      reviewer: codex-gpt
+    committer: coder