@sublang/playbook 0.7.0 → 0.9.0

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

@@ -6,19 +6,15 @@ 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`; 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.
+// PBRT-30: the CODE registry entry validates the option slice the shell
+// passes it (`captain.options.playbooks.code.options`), not a namespace
+// it extracts from the full Captain options bag. The schema defines one
+// key, `committer`: an optional Committer-alias player id, one of the
+// baked role ids `coder` / `reviewer`. A valid slice is absent, `{}`, or
+// `{ committer: 'coder' | 'reviewer' }`; every other key is unknown and
+// rejected with a path-named error. 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 = [
@@ -55,6 +51,47 @@ export const codeStateCountLabels = {
   reviewChangesAndChallengesMixed: 'review round',
 } as const;
 
+function countNoun(count: number, singular: string, plural = `${singular}s`): string {
+  return `${count} ${count === 1 ? singular : plural}`;
+}
+
+// PBRT-15 / CAPTAIN-19: the CODE saved-counts line wording is
+// registry-owned. The shell renders this exact line through the active
+// entry's summary policy rather than hardcoding CODE phrasing.
+export function codeSavedCountsLine(
+  counts: { interruptions: number; copyPastes: number },
+  rounds: number,
+): string {
+  return [
+    'Saved you',
+    countNoun(counts.interruptions, 'interruption'),
+    'and',
+    countNoun(counts.copyPastes, 'copy-paste'),
+    'across',
+    countNoun(rounds, 'round'),
+    'of reviews/rebuttals.',
+  ].join(' ');
+}
+
+// CAPTAIN-20 summary policy: the counted state-id labels, the
+// copy-paste guard names, and the saved-counts line wording an entry
+// owns for the shell's turn-summary aggregation. An entry without a
+// summary policy opts out of visible turn summaries.
+export interface PlaybookSummaryPolicy {
+  stateCountLabels: Readonly<Record<string, string>>;
+  copyPasteGuardNames: readonly string[];
+  savedCountsLine(
+    counts: { interruptions: number; copyPastes: number },
+    rounds: number,
+  ): string;
+}
+
+export const codeSummaryPolicy: PlaybookSummaryPolicy = {
+  stateCountLabels: codeStateCountLabels,
+  copyPasteGuardNames: codeCopyPasteGuardNames,
+  savedCountsLine: codeSavedCountsLine,
+};
+
 // 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`.
@@ -77,31 +114,39 @@ export interface CodePlaybookRegistryEntry {
   id: 'code';
   command: 'code';
   intent: string;
+  requiredRoleIds: readonly string[];
   idleStateId: 'ready';
   finalStateId: 'done';
-  copyPasteGuardNames: readonly string[];
-  stateCountLabels: typeof codeStateCountLabels;
+  parkStateIds: readonly string[];
+  summaryPolicy: PlaybookSummaryPolicy;
   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');
+export function validateCodeOptions(optionSlice: unknown): CodeOptions {
+  if (optionSlice === undefined) return {};
+  if (
+    typeof optionSlice !== 'object' ||
+    optionSlice === null ||
+    Array.isArray(optionSlice)
+  ) {
+    throw new Error('captain.options.playbooks.code.options must be an object');
   }
-  for (const key of Object.keys(code)) {
+  const slice = optionSlice as Record<string, unknown>;
+  for (const key of Object.keys(slice)) {
     if (!CODE_OPTION_KEYS.has(key)) {
-      throw new Error(`Unknown config field captain.options.code.${key}`);
+      throw new Error(
+        `Unknown config field captain.options.playbooks.code.options.${key}`,
+      );
     }
   }
   const options: CodeOptions = {};
-  const committer = (code as Record<string, unknown>).committer;
+  const committer = slice.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'",
+        "captain.options.playbooks.code.options.committer must be " +
+          "'coder' or 'reviewer'",
       );
     }
     options.committer = committer as 'coder' | 'reviewer';
@@ -109,17 +154,6 @@ export function validateCodeOptions(captainOptions: unknown): CodeOptions {
   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,
@@ -148,12 +182,18 @@ export const codePlaybookRegistryEntry: CodePlaybookRegistryEntry = {
   id: 'code',
   command: 'code',
   intent: 'software development / SDLC coding workflow',
+  requiredRoleIds: ['coder', 'reviewer'],
   idleStateId: 'ready',
   finalStateId: 'done',
-  copyPasteGuardNames: codeCopyPasteGuardNames,
-  stateCountLabels: codeStateCountLabels,
+  parkStateIds: ['failed', 'awaitBossReply'],
+  summaryPolicy: codeSummaryPolicy,
   validateOptions: validateCodeOptions,
   createRuntime(options) {
     return createPlaybookRuntime(createCodeRuntimeOptions(options));
   },
 };
+
+// CAPTAIN-16 / PBRT-16: the published `@sublang/playbook/code/registry`
+// module's default export is the CODE registry entry the Playbook Captain
+// shell loads when a playbook block's `from` names this module.
+export default codePlaybookRegistryEntry;

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

@@ -1,21 +1,24 @@
 import type { Captain } from '@sublang/cligent/tmux-play';
 import type { PlaybookRuntime } from './code.playbook.js';
-import { type RegistryPlayer } from './code.registry.js';
+import type { PlaybookSummaryPolicy, RegistryPlayer } from './code.registry.js';
 export interface CreatePlaybookRuntimeOptions {
     captainOptions: unknown;
     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;
 }
-export declare const playbookCaptainRegistry: readonly PlaybookCaptainRegistryEntry[];
-export declare function createPlaybookCaptainShell(options: unknown, registry?: readonly PlaybookCaptainRegistryEntry[]): Captain;
+export declare function createPlaybookCaptainShell(options: unknown, deps?: PlaybookCaptainDeps): Captain;
 export default createPlaybookCaptainShell;

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

@@ -1,20 +1,13 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
-import { codePlaybookRegistryEntry, } from './code.registry.js';
 const SUB_RUNTIME_FSM_TOPIC = 'playbook.fsm.state';
 const SHELL_FSM_TOPIC = 'playbook.captain.fsm.state';
-export const playbookCaptainRegistry = [
-    codePlaybookRegistryEntry,
-];
 function parseRegisteredCommand(prompt) {
     const match = /^\/([A-Za-z][A-Za-z0-9_-]*)(?:\s+([\s\S]*))?$/.exec(prompt.trim());
     if (!match)
         return undefined;
     return { command: match[1], text: (match[2] ?? '').trim() };
 }
-function playbookCommandLabel(entry) {
-    return `/${entry.command}`;
-}
 function visibleChatEnvelope(message) {
     return [
         'You are the Playbook Captain shell.',
@@ -23,7 +16,6 @@ function visibleChatEnvelope(message) {
     ].join('\n\n');
 }
 function visibleTurnSummaryEnvelope(input) {
-    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.',
@@ -32,38 +24,24 @@ 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, singular, plural = `${singular}s`) {
-    return `${count} ${count === 1 ? singular : plural}`;
-}
-function savedCountsLine(counts, reviewRebuttalRounds) {
-    return [
-        'Saved you',
-        countNoun(counts.interruptions, 'interruption'),
-        'and',
-        countNoun(counts.copyPastes, 'copy-paste'),
-        'across',
-        countNoun(reviewRebuttalRounds, 'round'),
-        'of reviews/rebuttals.',
-    ].join(' ');
-}
 function stateCountLabel(stateId, entry) {
     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;
 }
 function pluralizeStateCount(label, count) {
@@ -88,17 +66,102 @@ function summaryProgressRoundCount(stateCounts) {
 function guardFromJudgeReply(finalText) {
     return /"guard"\s*:\s*"([^"]+)"/.exec(finalText)?.[1];
 }
-function normalizeRegistry(registry) {
+function isValidRegistryEntry(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const e = value;
+    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) {
+    if (typeof options !== 'object' || options === null)
+        return undefined;
+    const pb = options.playbooks;
+    if (typeof pb !== 'object' || pb === null || Array.isArray(pb)) {
+        return undefined;
+    }
+    return pb;
+}
+// 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, players, loadModule) {
+    const entries = [];
     const byCommand = new Map();
     const byId = new Map();
-    for (const entry of registry) {
-        byCommand.set(entry.command, entry);
+    const enablementById = new Map();
+    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;
+        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;
+        try {
+            mod = await loadModule(from);
+        }
+        catch (cause) {
+            throw new Error(`captain.options.playbooks.${id}.from "${from}" failed to import: ${String(cause?.message ?? cause)}`);
+        }
+        const entry = mod?.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, registry = playbookCaptainRegistry) {
-    const { entries, byCommand, byId } = normalizeRegistry(registry);
+export function createPlaybookCaptainShell(options, deps = {}) {
+    const loadModule = deps.loadModule ?? ((specifier) => import(specifier));
+    let entries = [];
+    let byCommand = new Map();
+    let byId = new Map();
+    let enablementById = new Map();
     let session;
     let players = [];
     let activeContext;
@@ -189,8 +252,7 @@ export function createPlaybookCaptainShell(options, registry = playbookCaptainRe
             return;
         }
         if (stateId === active.entry.idleStateId ||
-            stateId === 'failed' ||
-            stateId === 'awaitBossReply') {
+            active.entry.parkStateIds.includes(stateId)) {
             await setMode('engaged.parked', `sub-runtime:${stateId}`);
         }
     };
@@ -199,7 +261,10 @@ export function createPlaybookCaptainShell(options, registry = playbookCaptainRe
             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++;
             }
@@ -224,7 +289,7 @@ export function createPlaybookCaptainShell(options, registry = playbookCaptainRe
             }
             const guard = guardFromJudgeReply(result.finalText);
             if (guard &&
-                active?.entry.copyPasteGuardNames.includes(guard) &&
+                active?.entry.summaryPolicy?.copyPasteGuardNames.includes(guard) &&
                 activeTurnSummary) {
                 activeTurnSummary.counts.copyPastes++;
             }
@@ -240,41 +305,53 @@ export function createPlaybookCaptainShell(options, registry = playbookCaptainRe
             await requireSession().emitTelemetry(event);
         },
     });
+    // 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) => {
+        const ids = enablement.visiblePlayerIds;
+        if (!ids || ids.length === 0 || !activeContext)
+            return;
+        await activeContext.setVisiblePlayers(ids);
+    };
     const engage = async (entry) => {
         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;
     };
     const submitToActive = async (engagement, text, context) => {
+        await requestVisibility(engagement.enablement);
+        const policy = engagement.entry.summaryPolicy;
         const summaryCounts = {
             interruptions: 0,
             copyPastes: 0,
         };
         const summaryStateCounts = new Map();
         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;
@@ -286,13 +363,15 @@ export function createPlaybookCaptainShell(options, registry = playbookCaptainRe
                 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),
             });
         }
     };
@@ -301,7 +380,7 @@ export function createPlaybookCaptainShell(options, registry = playbookCaptainRe
         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') {
@@ -349,7 +428,7 @@ export function createPlaybookCaptainShell(options, registry = playbookCaptainRe
         `Ledger:\n${JSON.stringify(ledgerSnapshot())}`,
         `Registry:\n${JSON.stringify(entries.map((entry) => ({
             id: entry.id,
-            command: entry.command,
+            command: enablementById.get(entry.id)?.command ?? entry.command,
             intent: entry.intent,
         })))}`,
         `Boss message:\n${prompt}`,
@@ -439,18 +518,20 @@ export function createPlaybookCaptainShell(options, registry = playbookCaptainRe
             await routerClarification(context);
             return;
         }
-        const dismissedCommandLabel = playbookCommandLabel(active.entry);
+        const dismissedCommandLabel = `/${active.enablement.command}`;
         await disposeActive('dismiss');
         await callVisibleChat(context, decision.text ?? `${dismissedCommandLabel} stopped.`);
     };
     const handleRegisteredCommand = async (entry, text, context) => {
+        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}.`);
+            await callVisibleChat(context, `/${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 callVisibleChat(context, `Ask what task to run with /${entry.command}.`);
+            await requestVisibility(engagement.enablement);
+            await callVisibleChat(context, `Ask what task to run with /${enablement.command}.`);
             return;
         }
         await submitToActive(engagement, text, context);
@@ -459,8 +540,13 @@ export function createPlaybookCaptainShell(options, registry = playbookCaptainRe
         async init(initSession) {
             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');
         },