@sublang/playbook 4.0.0 → 6.0.0

package/reference/sdlc/review.playbook/review.gears.md

@@ -0,0 +1,112 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
+
+# REVIEW: Commit Review Workflow
+
+Players:
+
+- Coder
+- Reviewer
+
+### REVIEW-1
+
+When the caller starts a review, Captain shall relay the complete caller input to Reviewer with the first-round and shared review instructions:
+
+> A new review begins on the latest commit.
+> Review the latest commit and resulting repository state; read the commit message first for its intent and rationale.
+>
+> > <caller-input>
+>
+> Understand the full picture and think systematically about the underlying design.
+> Continue to identify issues or improvements, if any (numbered; no duplication).
+> Treat as settled, and do not raise again, any finding in this review rejected twice with reasoning.
+> Flag only what materially affects correctness, behavior, or spec quality — not style, equally valid alternatives, or theoretical threats.
+> For specs, flag stale, missing, over-specified, or under-specified ones.
+> Avoid unnecessary complexity in code or tests, but flag any fundamental design flaw when leaving it would cost more in later patches than fixing it now.
+>
+> Do not re-run tests or builds whose inputs have not changed since any previous reported run.
+> Do not edit files or commit; report findings only.
+>
+> Consult @specs/map.md for context if needed; verify it remains accurate.
+> Consult @specs/meta.md for spec requirements if needed; verify affected specs follow it.
+
+Results:
+- `hasFindings`: Reviewer raised one or more unsettled findings. Output shall include `reviewerOutput: <verbatim final text>`.
+- `noFindings`: Reviewer raised no unsettled findings.
+
+### REVIEW-2
+
+When Reviewer raises or keeps any finding, Captain shall relay Reviewer's output to Coder with the disposition instruction:
+
+> > <reviewer-output>
+>
+> For each review item, accept or reject it.
+> Before deciding, understand the full picture and think systematically about the underlying design.
+> Reject anything that is not essential or is not worth fixing now.
+> If you accept an item, fix its root cause, including any fundamental design flaw - do not patch around it.
+> If you reject an item, give the reasoning and cite code or test output that supports it.
+> Do not re-run tests or builds whose inputs have not changed since any previous reported run.
+>
+> If you accept any item, make minimal changes and commit them as one new commit; never amend the reviewed commit.
+> Follow @specs/packages/git.md.
+> Make the commit message explain concisely what changed and why, including relevant verification.
+> Coder is <coder-llm>; Reviewer is <reviewer-llm>; format model tokens in conventional human form.
+>
+> If you reject every item, change nothing and make no commit.
+> Report every disposition, all relevant run results, and every rebuttal.
+
+Results:
+- `committed`: Coder accepted at least one item and made one new commit. Output shall include `coderOutput: <verbatim final text>`.
+- `rejectedAll`: Coder rejected every item and made no commit. Output shall include `coderOutput: <verbatim final text>`.
+
+### REVIEW-3
+
+When Coder makes a review-fix commit, Captain shall relay Coder's output to Reviewer with the next-round and shared review instructions:
+
+> Review the latest commit and resulting repository state; read the commit message first for its intent and rationale.
+>
+> > <coder-output>
+>
+> Understand the full picture and think systematically about the underlying design.
+> Continue to identify issues or improvements, if any (numbered; no duplication).
+> Treat as settled, and do not raise again, any finding in this review rejected twice with reasoning.
+> Flag only what materially affects correctness, behavior, or spec quality — not style, equally valid alternatives, or theoretical threats.
+> For specs, flag stale, missing, over-specified, or under-specified ones.
+> Avoid unnecessary complexity in code or tests, but flag any fundamental design flaw when leaving it would cost more in later patches than fixing it now.
+>
+> Do not re-run tests or builds whose inputs have not changed since any previous reported run.
+> Do not edit files or commit; report findings only.
+>
+> Consult @specs/map.md for context if needed; verify it remains accurate.
+> Consult @specs/meta.md for spec requirements if needed; verify affected specs follow it.
+
+Results:
+- `hasFindings`: Reviewer raised one or more unsettled findings. Output shall include `reviewerOutput: <verbatim final text>`.
+- `noFindings`: Reviewer raised no unsettled findings.
+
+### REVIEW-4
+
+When Coder rejects every finding and makes no commit, Captain shall relay Coder's output to Reviewer with the rebuttal and shared review instructions:
+
+> No new commit was made because Coder rejected every finding.
+> For any rebuttal, accept or challenge it.
+> State which findings, if any, remain.
+>
+> > <coder-output>
+>
+> Understand the full picture and think systematically about the underlying design.
+> Continue to identify issues or improvements, if any (numbered; no duplication).
+> Treat as settled, and do not raise again, any finding in this review rejected twice with reasoning.
+> Flag only what materially affects correctness, behavior, or spec quality — not style, equally valid alternatives, or theoretical threats.
+> For specs, flag stale, missing, over-specified, or under-specified ones.
+> Avoid unnecessary complexity in code or tests, but flag any fundamental design flaw when leaving it would cost more in later patches than fixing it now.
+>
+> Do not re-run tests or builds whose inputs have not changed since any previous reported run.
+> Do not edit files or commit; report findings only.
+>
+> Consult @specs/map.md for context if needed; verify it remains accurate.
+> Consult @specs/meta.md for spec requirements if needed; verify affected specs follow it.
+
+Results:
+- `hasFindings`: Reviewer kept one or more unsettled findings. Output shall include `reviewerOutput: <verbatim final text>`.
+- `noFindings`: Reviewer accepted the rebuttals and no unsettled findings remain.

package/reference/sdlc/review.playbook/review.playbook.d.ts

@@ -0,0 +1,12 @@
+import { type PlayerInput, type ReviewInput } from './review.fsm.js';
+import type { CaptainCallOptions, CaptainResult, JsonValue, NormalizedError, PlayerCallOptions, PlaybookCallRequest, PlaybookCallResult, PlaybookCallStart, PlaybookControlReceipt, PlaybookControlView, PlaybookPendingCall, PlaybookPorts, PlaybookRunResult, PlaybookRuntime, PlaybookRuntimeFactory, PlaybookRuntimeSnapshot, PlaybookSession, PlaybookState, PlaybookStateValue, PlaybookTraceEvent, PlaybookTraceType, PlayerResult, PlayerSessionStore } from '@sublang/playbook/runtime';
+export type { CaptainCallOptions, CaptainResult, JsonValue, NormalizedError, PlayerCallOptions, PlaybookCallRequest, PlaybookCallResult, PlaybookCallStart, PlaybookControlReceipt, PlaybookControlView, PlaybookPendingCall, PlaybookPorts, PlaybookRunResult, PlaybookRuntime, PlaybookRuntimeFactory, PlaybookRuntimeSnapshot, PlaybookSession, PlaybookState, PlaybookStateValue, PlaybookTraceEvent, PlaybookTraceType, PlayerResult, PlayerSessionStore, };
+export type ReviewPlaybookOptions = ReviewInput;
+/** Keep every line of a relayed runtime value inside its authored quote. */
+declare function composePlayerPrompt(input: PlayerInput): string;
+export declare const _internal: {
+    composePlayerPrompt: typeof composePlayerPrompt;
+    VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string>;
+};
+declare const createPlaybookRuntime: PlaybookRuntimeFactory<ReviewPlaybookOptions>;
+export default createPlaybookRuntime;

package/reference/sdlc/review.playbook/review.playbook.js

@@ -0,0 +1,112 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+//
+// Generated by slc/link.md (FSM-to-Runtime linker).
+// Source FSM:    ./review.fsm.ts
+// Player bind:   Coder→coder, Reviewer→reviewer (default lowercased binding)
+// Boss event:    deterministic START_REVIEW entry; exact Boss text becomes
+//                callerInput; pending player questions retain BOSS_REPLY
+// Adjudication:  LLM judge per state; coderOutput and reviewerOutput are
+//                carried verbatim
+// Compat:        artifact schema 1 / runtime ABI 1
+import { RUNTIME_ABI, createXStatePlaybookRuntime, snapshotJsonValue, } from '@sublang/playbook/xstate-runtime';
+import { reviewMachine, } from './review.fsm.js';
+const OPTION_KEYS = new Set(['coderLlm', 'reviewerLlm']);
+const PLACEHOLDER = /<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>/g;
+const CONTINUATION_PREAMBLE = 'You previously paused this task to ask Boss a question; Boss has now replied. Continue the same task using the reply below.';
+const VERBATIM_PAYLOAD_FIELDS = new Set([
+    'reviewerOutput',
+    'coderOutput',
+]);
+function snapshotReviewOptions(value) {
+    const captured = snapshotJsonValue(value, 'REVIEW runtime options');
+    if (captured === null ||
+        typeof captured !== 'object' ||
+        Array.isArray(captured)) {
+        throw new TypeError('REVIEW runtime options must be an object');
+    }
+    const record = captured;
+    for (const key of Object.keys(record)) {
+        if (!OPTION_KEYS.has(key)) {
+            throw new TypeError(`REVIEW runtime options.${key} is not declared`);
+        }
+    }
+    for (const key of OPTION_KEYS) {
+        const option = record[key];
+        if (typeof option !== 'string' || option.trim().length === 0) {
+            throw new TypeError(`REVIEW runtime options.${key} must be a non-empty string`);
+        }
+    }
+    return captured;
+}
+function placeholderField(token) {
+    if (token === '#')
+        return 'irNumber';
+    return token.replace(/-([A-Za-z0-9_$])/g, (_match, next) => next.toUpperCase());
+}
+function quotedContinuation(value) {
+    return value.replaceAll('\n', '\n> ');
+}
+/** Keep every line of a relayed runtime value inside its authored quote. */
+function composePlayerPrompt(input) {
+    const fields = input;
+    const body = input.prompt.replace(PLACEHOLDER, (match, token, offset, source) => {
+        const value = fields[placeholderField(token)];
+        if (typeof value !== 'string')
+            return match;
+        const lineStart = source.lastIndexOf('\n', offset - 1) + 1;
+        return source.slice(lineStart, offset) === '> '
+            ? quotedContinuation(value)
+            : value;
+    });
+    if (input.pendingBossQuestion === undefined ||
+        input.bossReply === undefined) {
+        return body;
+    }
+    return [
+        CONTINUATION_PREAMBLE,
+        `Boss question:\n${input.pendingBossQuestion.question}`,
+        `Boss reply:\n${input.bossReply}`,
+        body,
+    ].join('\n\n');
+}
+export const _internal = {
+    composePlayerPrompt,
+    VERBATIM_PAYLOAD_FIELDS,
+};
+const runtimeSpec = {
+    label: 'REVIEW',
+    compat: { artifactSchema: 1, runtimeAbi: RUNTIME_ABI },
+    snapshotOptions: snapshotReviewOptions,
+    entryEvent: { type: 'START_REVIEW', textField: 'callerInput' },
+    playerStates: {
+        reviewInitial: {
+            player: 'Reviewer',
+            label: 'REVIEW-1: Reviewer examines the latest commit against the caller input.',
+        },
+        addressFindings: {
+            player: 'Coder',
+            label: 'REVIEW-2: Coder accepts or rejects every current review finding.',
+        },
+        reviewAfterCommit: {
+            player: 'Reviewer',
+            label: 'REVIEW-3: Reviewer examines the new review-fix commit and repository state.',
+        },
+        reviewAfterRebuttal: {
+            player: 'Reviewer',
+            label: 'REVIEW-4: Reviewer adjudicates an all-rejected Coder disposition.',
+        },
+    },
+    composePlayerPrompt: (input) => composePlayerPrompt(input),
+    verbatimPayloadFields: VERBATIM_PAYLOAD_FIELDS,
+    controlContextFields: [],
+    transitionEventFields: [
+        'callerInput',
+        'bossIntent',
+        'targetId',
+        'answer',
+        'questionId',
+    ],
+};
+const createPlaybookRuntime = createXStatePlaybookRuntime(reviewMachine, runtimeSpec);
+export default createPlaybookRuntime;

package/reference/sdlc/review.playbook/review.playbook.ts

@@ -0,0 +1,201 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+//
+// Generated by slc/link.md (FSM-to-Runtime linker).
+// Source FSM:    ./review.fsm.ts
+// Player bind:   Coder→coder, Reviewer→reviewer (default lowercased binding)
+// Boss event:    deterministic START_REVIEW entry; exact Boss text becomes
+//                callerInput; pending player questions retain BOSS_REPLY
+// Adjudication:  LLM judge per state; coderOutput and reviewerOutput are
+//                carried verbatim
+// Compat:        artifact schema 1 / runtime ABI 1
+
+import {
+  RUNTIME_ABI,
+  createXStatePlaybookRuntime,
+  snapshotJsonValue,
+  type PlaybookPlayerInput,
+  type XStatePlaybookRuntimeSpec,
+} from '@sublang/playbook/xstate-runtime';
+import {
+  reviewMachine,
+  type PlayerInput,
+  type ReviewInput,
+} from './review.fsm.js';
+import type {
+  CaptainCallOptions,
+  CaptainResult,
+  JsonValue,
+  NormalizedError,
+  PlayerCallOptions,
+  PlaybookCallRequest,
+  PlaybookCallResult,
+  PlaybookCallStart,
+  PlaybookControlReceipt,
+  PlaybookControlView,
+  PlaybookPendingCall,
+  PlaybookPorts,
+  PlaybookRunResult,
+  PlaybookRuntime,
+  PlaybookRuntimeFactory,
+  PlaybookRuntimeSnapshot,
+  PlaybookSession,
+  PlaybookState,
+  PlaybookStateValue,
+  PlaybookTraceEvent,
+  PlaybookTraceType,
+  PlayerResult,
+  PlayerSessionStore,
+} from '@sublang/playbook/runtime';
+
+export type {
+  CaptainCallOptions,
+  CaptainResult,
+  JsonValue,
+  NormalizedError,
+  PlayerCallOptions,
+  PlaybookCallRequest,
+  PlaybookCallResult,
+  PlaybookCallStart,
+  PlaybookControlReceipt,
+  PlaybookControlView,
+  PlaybookPendingCall,
+  PlaybookPorts,
+  PlaybookRunResult,
+  PlaybookRuntime,
+  PlaybookRuntimeFactory,
+  PlaybookRuntimeSnapshot,
+  PlaybookSession,
+  PlaybookState,
+  PlaybookStateValue,
+  PlaybookTraceEvent,
+  PlaybookTraceType,
+  PlayerResult,
+  PlayerSessionStore,
+};
+
+export type ReviewPlaybookOptions = ReviewInput;
+
+const OPTION_KEYS = new Set(['coderLlm', 'reviewerLlm']);
+const PLACEHOLDER = /<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>/g;
+const CONTINUATION_PREAMBLE =
+  'You previously paused this task to ask Boss a question; Boss has now replied. Continue the same task using the reply below.';
+
+const VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string> = new Set([
+  'reviewerOutput',
+  'coderOutput',
+]);
+
+function snapshotReviewOptions(value: unknown): ReviewPlaybookOptions {
+  const captured = snapshotJsonValue(value, 'REVIEW runtime options');
+  if (
+    captured === null ||
+    typeof captured !== 'object' ||
+    Array.isArray(captured)
+  ) {
+    throw new TypeError('REVIEW runtime options must be an object');
+  }
+  const record = captured as Readonly<Record<string, JsonValue>>;
+  for (const key of Object.keys(record)) {
+    if (!OPTION_KEYS.has(key)) {
+      throw new TypeError(`REVIEW runtime options.${key} is not declared`);
+    }
+  }
+  for (const key of OPTION_KEYS) {
+    const option = record[key];
+    if (typeof option !== 'string' || option.trim().length === 0) {
+      throw new TypeError(
+        `REVIEW runtime options.${key} must be a non-empty string`,
+      );
+    }
+  }
+  return captured as unknown as ReviewPlaybookOptions;
+}
+
+function placeholderField(token: string): string {
+  if (token === '#') return 'irNumber';
+  return token.replace(/-([A-Za-z0-9_$])/g, (_match, next: string) =>
+    next.toUpperCase(),
+  );
+}
+
+function quotedContinuation(value: string): string {
+  return value.replaceAll('\n', '\n> ');
+}
+
+/** Keep every line of a relayed runtime value inside its authored quote. */
+function composePlayerPrompt(input: PlayerInput): string {
+  const fields = input as unknown as Record<string, unknown>;
+  const body = input.prompt.replace(
+    PLACEHOLDER,
+    (match: string, token: string, offset: number, source: string) => {
+      const value = fields[placeholderField(token)];
+      if (typeof value !== 'string') return match;
+      const lineStart = source.lastIndexOf('\n', offset - 1) + 1;
+      return source.slice(lineStart, offset) === '> '
+        ? quotedContinuation(value)
+        : value;
+    },
+  );
+  if (
+    input.pendingBossQuestion === undefined ||
+    input.bossReply === undefined
+  ) {
+    return body;
+  }
+  return [
+    CONTINUATION_PREAMBLE,
+    `Boss question:\n${input.pendingBossQuestion.question}`,
+    `Boss reply:\n${input.bossReply}`,
+    body,
+  ].join('\n\n');
+}
+
+export const _internal = {
+  composePlayerPrompt,
+  VERBATIM_PAYLOAD_FIELDS,
+};
+
+const runtimeSpec: XStatePlaybookRuntimeSpec<ReviewPlaybookOptions> = {
+  label: 'REVIEW',
+  compat: { artifactSchema: 1, runtimeAbi: RUNTIME_ABI },
+  snapshotOptions: snapshotReviewOptions,
+  entryEvent: { type: 'START_REVIEW', textField: 'callerInput' },
+  playerStates: {
+    reviewInitial: {
+      player: 'Reviewer',
+      label:
+        'REVIEW-1: Reviewer examines the latest commit against the caller input.',
+    },
+    addressFindings: {
+      player: 'Coder',
+      label: 'REVIEW-2: Coder accepts or rejects every current review finding.',
+    },
+    reviewAfterCommit: {
+      player: 'Reviewer',
+      label:
+        'REVIEW-3: Reviewer examines the new review-fix commit and repository state.',
+    },
+    reviewAfterRebuttal: {
+      player: 'Reviewer',
+      label:
+        'REVIEW-4: Reviewer adjudicates an all-rejected Coder disposition.',
+    },
+  },
+  composePlayerPrompt: (input: PlaybookPlayerInput) =>
+    composePlayerPrompt(input as PlayerInput),
+  verbatimPayloadFields: VERBATIM_PAYLOAD_FIELDS,
+  controlContextFields: [],
+  transitionEventFields: [
+    'callerInput',
+    'bossIntent',
+    'targetId',
+    'answer',
+    'questionId',
+  ],
+};
+
+const createPlaybookRuntime: PlaybookRuntimeFactory<ReviewPlaybookOptions> =
+  createXStatePlaybookRuntime(reviewMachine, runtimeSpec);
+
+export default createPlaybookRuntime;

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

@@ -0,0 +1,43 @@
+import { type PlaybookRuntime, type ReviewPlaybookOptions } from './review.playbook.js';
+export interface PlaybookSummaryPolicy {
+    stateCountLabels: Readonly<Record<string, string>>;
+    copyPasteGuardNames: readonly string[];
+    savedCountsLine(counts: {
+        interruptions: number;
+        copyPastes: number;
+    }, rounds: number): string;
+}
+export interface RegistryPlayer {
+    id: string;
+    adapter?: string;
+    model?: string;
+}
+export interface CreateReviewRuntimeOptions {
+    captainOptions: unknown;
+    players: readonly RegistryPlayer[];
+}
+export type ReviewOptions = Readonly<Record<string, never>>;
+export interface ReviewPlaybookRegistryEntry {
+    id: 'review';
+    command: 'review';
+    intent: string;
+    requiredRoleIds: readonly ['coder', 'reviewer'];
+    summaryPolicy: PlaybookSummaryPolicy;
+    validateOptions(captainOptions: unknown): ReviewOptions;
+    createRuntime(options: CreateReviewRuntimeOptions): PlaybookRuntime;
+}
+export declare const reviewStateCountLabels: {
+    readonly reviewInitial: "review round";
+    readonly reviewAfterCommit: "review round";
+    readonly reviewAfterRebuttal: "rebuttal";
+};
+export declare const reviewCopyPasteGuardNames: readonly ["hasFindings", "committed", "rejectedAll"];
+export declare function reviewSavedCountsLine(counts: {
+    interruptions: number;
+    copyPastes: number;
+}, rounds: number): string;
+export declare const reviewSummaryPolicy: PlaybookSummaryPolicy;
+export declare function validateReviewOptions(optionSlice: unknown): ReviewOptions;
+export declare function createReviewRuntimeOptions({ captainOptions, players, }: CreateReviewRuntimeOptions): ReviewPlaybookOptions;
+export declare const reviewPlaybookRegistryEntry: ReviewPlaybookRegistryEntry;
+export default reviewPlaybookRegistryEntry;

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

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+import createPlaybookRuntime from './review.playbook.js';
+export const reviewStateCountLabels = {
+    reviewInitial: 'review round',
+    reviewAfterCommit: 'review round',
+    reviewAfterRebuttal: 'rebuttal',
+};
+export const reviewCopyPasteGuardNames = [
+    'hasFindings',
+    'committed',
+    'rejectedAll',
+];
+function countNoun(count, singular, plural = `${singular}s`) {
+    return `${count} ${count === 1 ? singular : plural}`;
+}
+export function reviewSavedCountsLine(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 reviewSummaryPolicy = {
+    stateCountLabels: reviewStateCountLabels,
+    copyPasteGuardNames: reviewCopyPasteGuardNames,
+    savedCountsLine: reviewSavedCountsLine,
+};
+export function validateReviewOptions(optionSlice) {
+    if (optionSlice === undefined)
+        return Object.freeze({});
+    if (optionSlice === null ||
+        typeof optionSlice !== 'object' ||
+        Array.isArray(optionSlice)) {
+        throw new Error('captain.options.playbooks.review.options must be an object');
+    }
+    const keys = Object.keys(optionSlice);
+    if (keys.length > 0) {
+        throw new Error(`Unknown config field captain.options.playbooks.review.options.${keys[0]}`);
+    }
+    return Object.freeze({});
+}
+function playerIdentity(players, id) {
+    const player = players.find((entry) => entry.id === id);
+    const identity = player?.model ?? player?.adapter;
+    if (identity === undefined || identity.trim().length === 0) {
+        throw new Error(`REVIEW requires configured player ${id}`);
+    }
+    return identity;
+}
+export function createReviewRuntimeOptions({ captainOptions, players, }) {
+    validateReviewOptions(captainOptions);
+    return {
+        coderLlm: playerIdentity(players, 'coder'),
+        reviewerLlm: playerIdentity(players, 'reviewer'),
+    };
+}
+export const reviewPlaybookRegistryEntry = {
+    id: 'review',
+    command: 'review',
+    intent: 'review the latest commit until no material correctness or spec findings remain',
+    requiredRoleIds: ['coder', 'reviewer'],
+    summaryPolicy: reviewSummaryPolicy,
+    validateOptions: validateReviewOptions,
+    createRuntime(options) {
+        return createPlaybookRuntime(createReviewRuntimeOptions(options));
+    },
+};
+export default reviewPlaybookRegistryEntry;

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

@@ -0,0 +1,138 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+import createPlaybookRuntime, {
+  type PlaybookRuntime,
+  type ReviewPlaybookOptions,
+} from './review.playbook.js';
+
+export interface PlaybookSummaryPolicy {
+  stateCountLabels: Readonly<Record<string, string>>;
+  copyPasteGuardNames: readonly string[];
+  savedCountsLine(
+    counts: { interruptions: number; copyPastes: number },
+    rounds: number,
+  ): string;
+}
+
+export interface RegistryPlayer {
+  id: string;
+  adapter?: string;
+  model?: string;
+}
+
+export interface CreateReviewRuntimeOptions {
+  captainOptions: unknown;
+  players: readonly RegistryPlayer[];
+}
+
+export type ReviewOptions = Readonly<Record<string, never>>;
+
+export interface ReviewPlaybookRegistryEntry {
+  id: 'review';
+  command: 'review';
+  intent: string;
+  requiredRoleIds: readonly ['coder', 'reviewer'];
+  summaryPolicy: PlaybookSummaryPolicy;
+  validateOptions(captainOptions: unknown): ReviewOptions;
+  createRuntime(options: CreateReviewRuntimeOptions): PlaybookRuntime;
+}
+
+export const reviewStateCountLabels = {
+  reviewInitial: 'review round',
+  reviewAfterCommit: 'review round',
+  reviewAfterRebuttal: 'rebuttal',
+} as const;
+
+export const reviewCopyPasteGuardNames = [
+  'hasFindings',
+  'committed',
+  'rejectedAll',
+] as const;
+
+function countNoun(
+  count: number,
+  singular: string,
+  plural = `${singular}s`,
+): string {
+  return `${count} ${count === 1 ? singular : plural}`;
+}
+
+export function reviewSavedCountsLine(
+  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(' ');
+}
+
+export const reviewSummaryPolicy: PlaybookSummaryPolicy = {
+  stateCountLabels: reviewStateCountLabels,
+  copyPasteGuardNames: reviewCopyPasteGuardNames,
+  savedCountsLine: reviewSavedCountsLine,
+};
+
+export function validateReviewOptions(optionSlice: unknown): ReviewOptions {
+  if (optionSlice === undefined) return Object.freeze({});
+  if (
+    optionSlice === null ||
+    typeof optionSlice !== 'object' ||
+    Array.isArray(optionSlice)
+  ) {
+    throw new Error(
+      'captain.options.playbooks.review.options must be an object',
+    );
+  }
+  const keys = Object.keys(optionSlice);
+  if (keys.length > 0) {
+    throw new Error(
+      `Unknown config field captain.options.playbooks.review.options.${keys[0]}`,
+    );
+  }
+  return Object.freeze({});
+}
+
+function playerIdentity(
+  players: readonly RegistryPlayer[],
+  id: 'coder' | 'reviewer',
+): string {
+  const player = players.find((entry) => entry.id === id);
+  const identity = player?.model ?? player?.adapter;
+  if (identity === undefined || identity.trim().length === 0) {
+    throw new Error(`REVIEW requires configured player ${id}`);
+  }
+  return identity;
+}
+
+export function createReviewRuntimeOptions({
+  captainOptions,
+  players,
+}: CreateReviewRuntimeOptions): ReviewPlaybookOptions {
+  validateReviewOptions(captainOptions);
+  return {
+    coderLlm: playerIdentity(players, 'coder'),
+    reviewerLlm: playerIdentity(players, 'reviewer'),
+  };
+}
+
+export const reviewPlaybookRegistryEntry: ReviewPlaybookRegistryEntry = {
+  id: 'review',
+  command: 'review',
+  intent:
+    'review the latest commit until no material correctness or spec findings remain',
+  requiredRoleIds: ['coder', 'reviewer'],
+  summaryPolicy: reviewSummaryPolicy,
+  validateOptions: validateReviewOptions,
+  createRuntime(options) {
+    return createPlaybookRuntime(createReviewRuntimeOptions(options));
+  },
+};
+
+export default reviewPlaybookRegistryEntry;