@sublang/playbook 0.5.0 → 0.7.0

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

@@ -11,6 +11,9 @@
 //                alias's first alternative)
 // Boss event:    free-text judge classification
 // Adjudication:  LLM-judge per state
+// Contract:      PlayerResult / PlaybookPorts / PlaybookRuntime imported
+//                and re-exported from @sublang/playbook/runtime
+//                (slc/link.md §Output, DR-004 Addendum A4)
 import { createActor, fromPromise } from 'xstate';
 import { codingMachine, } from './code.fsm.js';
 import { enumerateAwaitBossReply, enumerateCaptainStates, enumerateRootEvents, } from './code.fsm.introspect.js';

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

@@ -11,6 +11,9 @@
 //                alias's first alternative)
 // Boss event:    free-text judge classification
 // Adjudication:  LLM-judge per state
+// Contract:      PlayerResult / PlaybookPorts / PlaybookRuntime imported
+//                and re-exported from @sublang/playbook/runtime
+//                (slc/link.md §Output, DR-004 Addendum A4)
 
 import { createActor, fromPromise } from 'xstate';
 import {
@@ -25,33 +28,20 @@ import {
   enumerateCaptainStates,
   enumerateRootEvents,
 } from './code.fsm.introspect.js';
-
-// Public contract — `PlayerResult`, `PlaybookPorts`, `PlaybookRuntime`,
-// `CodePlaybookOptions`, and the default `createPlaybookRuntime` factory
-// per slc/link.md and DR-004 §10.
-
-export interface PlayerResult {
-  status: 'ok' | 'aborted' | 'error';
-  finalText?: string;
-  error?: string;
-}
-
-export interface PlaybookPorts {
-  callPlayer(
-    playerId: string,
-    prompt: string,
-    signal: AbortSignal,
-  ): Promise<PlayerResult>;
-  callJudge(prompt: string, signal: AbortSignal): Promise<string>;
-  emitStatus(message: string, data?: unknown): Promise<void>;
-  emitTelemetry(event: { topic: string; payload: unknown }): Promise<void>;
-}
-
-export interface PlaybookRuntime {
-  init(ports: PlaybookPorts): Promise<void>;
-  handleBossInput(turn: { text: string; signal: AbortSignal }): Promise<void>;
-  dispose(): Promise<void>;
-}
+import type {
+  PlaybookPorts,
+  PlaybookRuntime,
+  PlayerResult,
+} from '@sublang/playbook/runtime';
+
+// Public contract. `PlayerResult`, `PlaybookPorts`, and `PlaybookRuntime`
+// are re-exported from the shared `@sublang/playbook/runtime` module
+// (slc/link.md §Output, DR-004 Addendum A4) so this playbook and any
+// future one resolve one contract definition rather than redefining it.
+// `CodePlaybookOptions` and the default `createPlaybookRuntime` factory
+// (typed `PlaybookRuntimeFactory<CodePlaybookOptions>`) stay
+// CODE-specific.
+export type { PlayerResult, PlaybookPorts, PlaybookRuntime };
 
 export type CodePlaybookOptions = CodingInput;
 

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

@@ -0,0 +1,43 @@
+import { type CodePlaybookOptions, type PlaybookRuntime } from './code.playbook.js';
+export declare const codeCopyPasteGuardNames: readonly ["accepted", "approved", "challengeAccepted", "challengeRejected", "challengesRaised", "changesMadeCode", "changesMadeCodeAndChallenged", "changesMadeMixed", "changesMadeMixedAndChallenged", "changesMadeSpecs", "changesMadeSpecsAndChallenged", "hasFindings", "needsRevision", "noFindings", "noOpenItems"];
+export declare const codeStateCountLabels: {
+    readonly adjudicateChallenges: "rebuttal";
+    readonly reviewBossCommitSpecs: "review round";
+    readonly reviewBossCommitCode: "review round";
+    readonly reviewBossCommitMixed: "review round";
+    readonly reviewIrTaskCommitSpecs: "review round";
+    readonly reviewIrTaskCommitCode: "review round";
+    readonly reviewIrTaskCommitMixed: "review round";
+    readonly reviewChangesSpecs: "review round";
+    readonly reviewChangesCode: "review round";
+    readonly reviewChangesMixed: "review round";
+    readonly reviewChangesAndChallengesSpecs: "review round";
+    readonly reviewChangesAndChallengesCode: "review round";
+    readonly reviewChangesAndChallengesMixed: "review round";
+};
+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 declare function validateCodeOptions(captainOptions: unknown): CodeOptions;
+export declare function createCodeRuntimeOptions({ captainOptions, players, }: CreateCodeRuntimeOptions): CodePlaybookOptions;
+export declare const codePlaybookRegistryEntry: CodePlaybookRegistryEntry;

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

@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+import createPlaybookRuntime 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(['committer']);
+const COMMITTER_PLAYER_IDS = new Set(['coder', 'reviewer']);
+export const codeCopyPasteGuardNames = [
+    'accepted',
+    'approved',
+    'challengeAccepted',
+    'challengeRejected',
+    'challengesRaised',
+    'changesMadeCode',
+    'changesMadeCodeAndChallenged',
+    'changesMadeMixed',
+    'changesMadeMixedAndChallenged',
+    'changesMadeSpecs',
+    'changesMadeSpecsAndChallenged',
+    'hasFindings',
+    'needsRevision',
+    'noFindings',
+    'noOpenItems',
+];
+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',
+};
+export function validateCodeOptions(captainOptions) {
+    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 = {};
+    const committer = code.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;
+    }
+    return options;
+}
+function readCodeNamespace(captainOptions) {
+    if (typeof captainOptions !== 'object' ||
+        captainOptions === null ||
+        Array.isArray(captainOptions)) {
+        return undefined;
+    }
+    return captainOptions.code;
+}
+function playerIdentity(players, id) {
+    const entry = players.find((p) => p.id === id);
+    return entry?.model ?? entry?.adapter;
+}
+export function createCodeRuntimeOptions({ captainOptions, players, }) {
+    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 = {
+    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.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,6 +1,4 @@
 import type { Captain } from '@sublang/cligent/tmux-play';
-export interface CodeOptions {
-    committer?: 'coder' | 'reviewer';
-}
-export declare function validateCodeOptions(captainOptions: unknown): CodeOptions;
+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,160 +1,11 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
-import createPlaybookRuntime 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(['committer']);
-const COMMITTER_PLAYER_IDS = new Set(['coder', 'reviewer']);
-export function validateCodeOptions(captainOptions) {
-    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 = {};
-    const committer = code.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;
-    }
-    return options;
-}
-function readCodeNamespace(captainOptions) {
-    if (typeof captainOptions !== 'object' ||
-        captainOptions === null ||
-        Array.isArray(captainOptions)) {
-        return undefined;
-    }
-    return captainOptions.code;
-}
-// Captain factory per TMUX-014: `(options: unknown) => Captain`.
-// `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.
+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) {
-            // 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) => {
-                const entry = session.players.find((p) => p.id === id);
-                return entry?.model ?? entry?.adapter;
-            };
-            const coderPlayer = playerIdentity('coder');
-            const reviewerPlayer = playerIdentity('reviewer');
-            // 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 = {
-                coderPlayer,
-                reviewerPlayer,
-                ...(codeOptions.committer !== undefined
-                    ? { committerPlayer: codeOptions.committer }
-                    : {}),
-            };
-            runtime = createPlaybookRuntime(runtimeOptions);
-            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');
-                    }
-                    // 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}"`);
-                    }
-                    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);
 }