@sublang/playbook 0.4.2 → 0.6.0

package/reference/sdlc/code.playbook/code.registry.ts

@@ -0,0 +1,159 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+import createPlaybookRuntime, {
+  type CodePlaybookOptions,
+  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`; the CODE registry entry 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']);
+export const codeCopyPasteGuardNames = [
+  'accepted',
+  'approved',
+  'challengeAccepted',
+  'challengeRejected',
+  'challengesRaised',
+  'changesMadeCode',
+  'changesMadeCodeAndChallenged',
+  'changesMadeMixed',
+  'changesMadeMixedAndChallenged',
+  'changesMadeSpecs',
+  'changesMadeSpecsAndChallenged',
+  'hasFindings',
+  'needsRevision',
+  'noFindings',
+  'noOpenItems',
+] as const;
+
+export const codeStateCountLabels = {
+  adjudicateChallenges: 'rebuttal',
+  reviewBossCommitSpecs: 'review round',
+  reviewBossCommitCode: 'review round',
+  reviewBossCommitMixed: 'review round',
+  reviewIrTaskCommitSpecs: 'review round',
+  reviewIrTaskCommitCode: 'review round',
+  reviewIrTaskCommitMixed: 'review round',
+  reviewChangesSpecs: 'review round',
+  reviewChangesCode: 'review round',
+  reviewChangesMixed: 'review round',
+  reviewChangesAndChallengesSpecs: 'review round',
+  reviewChangesAndChallengesCode: 'review round',
+  reviewChangesAndChallengesMixed: 'review round',
+} as const;
+
+// 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 interface RegistryPlayer {
+  id: string;
+  adapter?: string;
+  model?: string;
+}
+
+export interface CreateCodeRuntimeOptions {
+  captainOptions: unknown;
+  players: readonly RegistryPlayer[];
+}
+
+export interface CodePlaybookRegistryEntry {
+  id: 'code';
+  command: 'code';
+  intent: string;
+  idleStateId: 'ready';
+  finalStateId: 'done';
+  copyPasteGuardNames: readonly string[];
+  stateCountLabels: typeof codeStateCountLabels;
+  validateOptions(captainOptions: unknown): CodeOptions;
+  createRuntime(options: CreateCodeRuntimeOptions): PlaybookRuntime;
+}
+
+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;
+}
+
+function playerIdentity(
+  players: readonly RegistryPlayer[],
+  id: string,
+): string | undefined {
+  const entry = players.find((p) => p.id === id);
+  return entry?.model ?? entry?.adapter;
+}
+
+export function createCodeRuntimeOptions({
+  captainOptions,
+  players,
+}: CreateCodeRuntimeOptions): CodePlaybookOptions {
+  const codeOptions = validateCodeOptions(captainOptions);
+  const coderPlayer = playerIdentity(players, 'coder');
+  const reviewerPlayer = playerIdentity(players, 'reviewer');
+  return {
+    coderPlayer,
+    reviewerPlayer,
+    ...(codeOptions.committer !== undefined
+      ? { committerPlayer: codeOptions.committer }
+      : {}),
+  };
+}
+
+export const codePlaybookRegistryEntry: CodePlaybookRegistryEntry = {
+  id: 'code',
+  command: 'code',
+  intent: 'software development / SDLC coding workflow',
+  idleStateId: 'ready',
+  finalStateId: 'done',
+  copyPasteGuardNames: codeCopyPasteGuardNames,
+  stateCountLabels: codeStateCountLabels,
+  validateOptions: validateCodeOptions,
+  createRuntime(options) {
+    return createPlaybookRuntime(createCodeRuntimeOptions(options));
+  },
+};

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

@@ -1,2 +1,4 @@
 import type { Captain } from '@sublang/cligent/tmux-play';
+export { codeCopyPasteGuardNames, codeStateCountLabels, codePlaybookRegistryEntry, createCodeRuntimeOptions, validateCodeOptions, } from './code.registry.js';
+export type { CodeOptions, CodePlaybookRegistryEntry, CreateCodeRuntimeOptions, RegistryPlayer, } from './code.registry.js';
 export default function createCodeTmuxPlayCaptain(options: unknown): Captain;

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

@@ -1,97 +1,11 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
-import createPlaybookRuntime from './code.playbook.js';
-// 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.
+import createPlaybookCaptainShell from './playbook-captain.js';
+export { codeCopyPasteGuardNames, codeStateCountLabels, codePlaybookRegistryEntry, createCodeRuntimeOptions, validateCodeOptions, } from './code.registry.js';
+// Compatibility shim for the historic `./code/tmux-play` package
+// export. Public launch paths now target the Playbook Captain shell
+// directly; explicit configs that still import this module get the
+// same shell with CODE registered.
 export default function createCodeTmuxPlayCaptain(options) {
-    // CaptainSession is bound at init time and persists across turns;
-    // CaptainContext is rebuilt per turn and carries the call
-    // primitives. The runtime is constructed in `init` so identity
-    // strings derived from `session.players` can flow into its options;
-    // PlaybookPorts is built once at init, so the per-turn context
-    // lives in a closure-scoped slot the port callbacks query lazily.
-    let runtime;
-    let activeContext;
-    return {
-        async init(session) {
-            const playerIdentity = (id) => {
-                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,
-                coderPlayer,
-                reviewerPlayer,
-            });
-            const ports = {
-                callPlayer: async (playerId, prompt, _signal) => {
-                    if (!activeContext) {
-                        throw new Error('callPlayer invoked outside a Boss turn');
-                    }
-                    // PlayerRunResult per TMUX-033 already matches PlayerResult
-                    // (`status: 'ok' | 'aborted' | 'error'`, `finalText?`,
-                    // `error?`). cligent honors context.signal internally;
-                    // the runtime's signal is the same source forwarded
-                    // through handleBossInput, so dropping `_signal` is
-                    // safe.
-                    const r = await activeContext.callPlayer(playerId, prompt);
-                    return {
-                        status: r.status,
-                        finalText: r.finalText,
-                        error: r.error,
-                    };
-                },
-                callJudge: async (prompt, _signal) => {
-                    if (!activeContext) {
-                        throw new Error('callJudge invoked outside a Boss turn');
-                    }
-                    const r = await activeContext.callCaptain(prompt);
-                    if (r.status !== 'ok') {
-                        throw new Error(r.error ?? `callCaptain status "${r.status}"`);
-                    }
-                    if (r.finalText === undefined) {
-                        throw new Error('callCaptain returned status=ok with no finalText');
-                    }
-                    return r.finalText;
-                },
-                emitStatus: async (message, data) => {
-                    await session.emitStatus(message, data);
-                },
-                emitTelemetry: async (event) => {
-                    await session.emitTelemetry(event);
-                },
-            };
-            await runtime.init(ports);
-        },
-        async handleBossTurn(turn, context) {
-            if (!runtime) {
-                throw new Error('init must be called first');
-            }
-            activeContext = context;
-            try {
-                // Forward the Boss prompt + cligent's per-turn signal into
-                // the runtime; the runtime stashes the signal so the
-                // captain bridge passes it down to callPlayer / callJudge.
-                await runtime.handleBossInput({
-                    text: turn.prompt,
-                    signal: context.signal,
-                });
-            }
-            finally {
-                activeContext = undefined;
-            }
-        },
-        async dispose() {
-            await runtime?.dispose();
-        },
-    };
+    return createPlaybookCaptainShell(options);
 }

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

@@ -1,127 +1,29 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 
-// tmux-play host adapter for the CODE playbook — DR-004 §11. This is
-// the only file in IR-004 that imports cligent; removing the import
-// shall not affect code.playbook.ts or its tests.
+import type { Captain } from '@sublang/cligent/tmux-play';
+import createPlaybookCaptainShell from './playbook-captain.js';
 
-import type {
-  BossTurn,
-  Captain,
-  CaptainContext,
-  CaptainSession,
-} from '@sublang/cligent/tmux-play';
-import createPlaybookRuntime, {
-  type CodePlaybookOptions,
-  type PlaybookPorts,
-  type PlaybookRuntime,
-} from './code.playbook.js';
+export {
+  codeCopyPasteGuardNames,
+  codeStateCountLabels,
+  codePlaybookRegistryEntry,
+  createCodeRuntimeOptions,
+  validateCodeOptions,
+} from './code.registry.js';
+export type {
+  CodeOptions,
+  CodePlaybookRegistryEntry,
+  CreateCodeRuntimeOptions,
+  RegistryPlayer,
+} from './code.registry.js';
 
-// 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.
+// Compatibility shim for the historic `./code/tmux-play` package
+// export. Public launch paths now target the Playbook Captain shell
+// directly; explicit configs that still import this module get the
+// same shell with CODE registered.
 export default function createCodeTmuxPlayCaptain(
   options: unknown,
 ): Captain {
-  // CaptainSession is bound at init time and persists across turns;
-  // CaptainContext is rebuilt per turn and carries the call
-  // primitives. The runtime is constructed in `init` so identity
-  // strings derived from `session.players` can flow into its options;
-  // PlaybookPorts is built once at init, so the per-turn context
-  // lives in a closure-scoped slot the port callbacks query lazily.
-  let runtime: PlaybookRuntime | undefined;
-  let activeContext: CaptainContext | undefined;
-
-  return {
-    async init(session: CaptainSession): Promise<void> {
-      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),
-        coderPlayer,
-        reviewerPlayer,
-      });
-      const ports: PlaybookPorts = {
-        callPlayer: async (playerId, prompt, _signal) => {
-          if (!activeContext) {
-            throw new Error('callPlayer invoked outside a Boss turn');
-          }
-          // PlayerRunResult per TMUX-033 already matches PlayerResult
-          // (`status: 'ok' | 'aborted' | 'error'`, `finalText?`,
-          // `error?`). cligent honors context.signal internally;
-          // the runtime's signal is the same source forwarded
-          // through handleBossInput, so dropping `_signal` is
-          // safe.
-          const r = await activeContext.callPlayer(playerId, prompt);
-          return {
-            status: r.status,
-            finalText: r.finalText,
-            error: r.error,
-          };
-        },
-        callJudge: async (prompt, _signal) => {
-          if (!activeContext) {
-            throw new Error('callJudge invoked outside a Boss turn');
-          }
-          const r = await activeContext.callCaptain(prompt);
-          if (r.status !== 'ok') {
-            throw new Error(
-              r.error ?? `callCaptain status "${r.status}"`,
-            );
-          }
-          if (r.finalText === undefined) {
-            throw new Error(
-              'callCaptain returned status=ok with no finalText',
-            );
-          }
-          return r.finalText;
-        },
-        emitStatus: async (message, data) => {
-          await session.emitStatus(
-            message,
-            data as Record<string, unknown> | undefined,
-          );
-        },
-        emitTelemetry: async (event) => {
-          await session.emitTelemetry(event);
-        },
-      };
-      await runtime.init(ports);
-    },
-
-    async handleBossTurn(
-      turn: BossTurn,
-      context: CaptainContext,
-    ): Promise<void> {
-      if (!runtime) {
-        throw new Error('init must be called first');
-      }
-      activeContext = context;
-      try {
-        // Forward the Boss prompt + cligent's per-turn signal into
-        // the runtime; the runtime stashes the signal so the
-        // captain bridge passes it down to callPlayer / callJudge.
-        await runtime.handleBossInput({
-          text: turn.prompt,
-          signal: context.signal,
-        });
-      } finally {
-        activeContext = undefined;
-      }
-    },
-
-    async dispose(): Promise<void> {
-      await runtime?.dispose();
-    },
-  };
+  return createPlaybookCaptainShell(options);
 }

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

@@ -0,0 +1,21 @@
+import type { Captain } from '@sublang/cligent/tmux-play';
+import type { PlaybookRuntime } from './code.playbook.js';
+import { type RegistryPlayer } from './code.registry.js';
+export interface CreatePlaybookRuntimeOptions {
+    captainOptions: unknown;
+    players: readonly RegistryPlayer[];
+}
+export interface PlaybookCaptainRegistryEntry {
+    id: string;
+    command: string;
+    intent: string;
+    idleStateId: string;
+    finalStateId: string;
+    copyPasteGuardNames: readonly string[];
+    stateCountLabels?: Readonly<Record<string, string>>;
+    validateOptions(captainOptions: unknown): unknown;
+    createRuntime(options: CreatePlaybookRuntimeOptions): PlaybookRuntime;
+}
+export declare const playbookCaptainRegistry: readonly PlaybookCaptainRegistryEntry[];
+export declare function createPlaybookCaptainShell(options: unknown, registry?: readonly PlaybookCaptainRegistryEntry[]): Captain;
+export default createPlaybookCaptainShell;