@sublang/playbook 0.8.0 → 1.0.0

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

@@ -15,6 +15,19 @@ export declare const codeStateCountLabels: {
     readonly reviewChangesAndChallengesCode: "review round";
     readonly reviewChangesAndChallengesMixed: "review round";
 };
+export declare function codeSavedCountsLine(counts: {
+    interruptions: number;
+    copyPastes: number;
+}, rounds: number): string;
+export interface PlaybookSummaryPolicy {
+    stateCountLabels: Readonly<Record<string, string>>;
+    copyPasteGuardNames: readonly string[];
+    savedCountsLine(counts: {
+        interruptions: number;
+        copyPastes: number;
+    }, rounds: number): string;
+}
+export declare const codeSummaryPolicy: PlaybookSummaryPolicy;
 export interface CodeOptions {
     committer?: 'coder' | 'reviewer';
 }
@@ -31,13 +44,12 @@ export interface CodePlaybookRegistryEntry {
     id: 'code';
     command: 'code';
     intent: string;
-    idleStateId: 'ready';
-    finalStateId: 'done';
-    copyPasteGuardNames: readonly string[];
-    stateCountLabels: typeof codeStateCountLabels;
+    requiredRoleIds: readonly string[];
+    summaryPolicy: PlaybookSummaryPolicy;
     validateOptions(captainOptions: unknown): CodeOptions;
     createRuntime(options: CreateCodeRuntimeOptions): PlaybookRuntime;
 }
-export declare function validateCodeOptions(captainOptions: unknown): CodeOptions;
+export declare function validateCodeOptions(optionSlice: unknown): CodeOptions;
 export declare function createCodeRuntimeOptions({ captainOptions, players, }: CreateCodeRuntimeOptions): CodePlaybookOptions;
 export declare const codePlaybookRegistryEntry: CodePlaybookRegistryEntry;
+export default codePlaybookRegistryEntry;

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

@@ -1,19 +1,15 @@
 // 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.
+// 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(['committer']);
 const COMMITTER_PLAYER_IDS = new Set(['coder', 'reviewer']);
 export const codeCopyPasteGuardNames = [
@@ -48,36 +44,53 @@ export const codeStateCountLabels = {
     reviewChangesAndChallengesCode: 'review round',
     reviewChangesAndChallengesMixed: 'review round',
 };
-export function validateCodeOptions(captainOptions) {
-    const code = readCodeNamespace(captainOptions);
-    if (code === undefined)
+function countNoun(count, singular, plural = `${singular}s`) {
+    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, rounds) {
+    return [
+        'Saved you',
+        countNoun(counts.interruptions, 'interruption'),
+        'and',
+        countNoun(counts.copyPastes, 'copy-paste'),
+        'across',
+        countNoun(rounds, 'round'),
+        'of reviews/rebuttals.',
+    ].join(' ');
+}
+export const codeSummaryPolicy = {
+    stateCountLabels: codeStateCountLabels,
+    copyPasteGuardNames: codeCopyPasteGuardNames,
+    savedCountsLine: codeSavedCountsLine,
+};
+export function validateCodeOptions(optionSlice) {
+    if (optionSlice === undefined)
         return {};
-    if (typeof code !== 'object' || code === null || Array.isArray(code)) {
-        throw new Error('captain.options.code must be an object');
+    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;
+    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 = {};
-    const committer = code.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'");
+            throw new Error("captain.options.playbooks.code.options.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;
@@ -98,12 +111,14 @@ export const codePlaybookRegistryEntry = {
     id: 'code',
     command: 'code',
     intent: 'software development / SDLC coding workflow',
-    idleStateId: 'ready',
-    finalStateId: 'done',
-    copyPasteGuardNames: codeCopyPasteGuardNames,
-    stateCountLabels: codeStateCountLabels,
+    requiredRoleIds: ['coder', 'reviewer'],
+    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/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,36 @@ export interface CodePlaybookRegistryEntry {
   id: 'code';
   command: 'code';
   intent: string;
-  idleStateId: 'ready';
-  finalStateId: 'done';
-  copyPasteGuardNames: readonly string[];
-  stateCountLabels: typeof codeStateCountLabels;
+  requiredRoleIds: 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 +151,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 +179,15 @@ export const codePlaybookRegistryEntry: CodePlaybookRegistryEntry = {
   id: 'code',
   command: 'code',
   intent: 'software development / SDLC coding workflow',
-  idleStateId: 'ready',
-  finalStateId: 'done',
-  copyPasteGuardNames: codeCopyPasteGuardNames,
-  stateCountLabels: codeStateCountLabels,
+  requiredRoleIds: ['coder', 'reviewer'],
+  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,29 @@
 import type { Captain } from '@sublang/cligent/tmux-play';
-import type { PlaybookRuntime } from './code.playbook.js';
-import { type RegistryPlayer } from './code.registry.js';
+import type { PlaybookRuntime } from '@sublang/playbook/runtime';
+import type { PlaybookSummaryPolicy, RegistryPlayer } from './code.registry.js';
 export interface CreatePlaybookRuntimeOptions {
     captainOptions: unknown;
     players: readonly RegistryPlayer[];
 }
+export interface PlaybookCaptainDeps {
+    loadModule?: (specifier: string) => Promise<unknown>;
+    createSessionId?: () => string;
+    createCaptainRuntime?: (options: {
+        readonly enabledPlaybooks: readonly {
+            readonly id: string;
+            readonly command: string;
+            readonly intent: string;
+        }[];
+    }) => PlaybookRuntime;
+}
 export interface PlaybookCaptainRegistryEntry {
     id: string;
     command: string;
     intent: string;
-    idleStateId: string;
-    finalStateId: string;
-    copyPasteGuardNames: readonly string[];
-    stateCountLabels?: Readonly<Record<string, string>>;
+    requiredRoleIds: 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;