@sublang/playbook 7.0.0 → 9.0.0

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

@@ -1,4 +1,4 @@
-import { type PlaybookRuntime, type PlaybookRuntimeOptions } from './decide.playbook.js';
+import { type PlaybookRuntime } from './decide.playbook.js';
 export interface PlaybookSummaryPolicy {
     stateCountLabels: Readonly<Record<string, string>>;
     copyPasteGuardNames: readonly string[];
@@ -7,24 +7,17 @@ export interface PlaybookSummaryPolicy {
         copyPastes: number;
     }, rounds: number): string;
 }
-export interface RegistryPlayer {
-    id: string;
-    adapter?: string;
-    model?: string;
-}
-export interface CreateDecideRuntimeOptions {
-    captainOptions: unknown;
-    players: readonly RegistryPlayer[];
-}
 export type DecideOptions = Readonly<Record<string, never>>;
 export interface DecidePlaybookRegistryEntry {
     id: 'decide';
     command: 'decide';
     intent: string;
+    artifactSchema: 2;
     requiredRoleIds: readonly ['coder', 'reviewer'];
+    concurrentRoleSets: readonly [readonly ['coder', 'reviewer']];
     summaryPolicy: PlaybookSummaryPolicy;
-    validateOptions(captainOptions: unknown): DecideOptions;
-    createRuntime(options: CreateDecideRuntimeOptions): PlaybookRuntime;
+    validateOptions(optionSlice: unknown): DecideOptions;
+    createRuntime(options: DecideOptions): PlaybookRuntime;
 }
 export declare const decideStateCountLabels: {
     readonly independentProposals: "proposal round";
@@ -36,6 +29,5 @@ export declare function decideSavedCountsLine(counts: {
 }, rounds: number): string;
 export declare const decideSummaryPolicy: PlaybookSummaryPolicy;
 export declare function validateDecideOptions(optionSlice: unknown): DecideOptions;
-export declare function createDecideRuntimeOptions({ captainOptions, players, }: CreateDecideRuntimeOptions): PlaybookRuntimeOptions;
 export declare const decidePlaybookRegistryEntry: DecidePlaybookRegistryEntry;
 export default decidePlaybookRegistryEntry;

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

@@ -38,23 +38,17 @@ export function validateDecideOptions(optionSlice) {
     }
     return Object.freeze({});
 }
-function playerIdentity(players, id) {
-    const player = players.find((entry) => entry.id === id);
-    return player?.model ?? player?.adapter ?? id;
-}
-export function createDecideRuntimeOptions({ captainOptions, players, }) {
-    validateDecideOptions(captainOptions);
-    return { coderLlm: playerIdentity(players, 'coder') };
-}
 export const decidePlaybookRegistryEntry = {
     id: 'decide',
     command: 'decide',
     intent: 'turn independent Coder and Reviewer proposals into an approved spec-design commit',
+    artifactSchema: 2,
     requiredRoleIds: ['coder', 'reviewer'],
+    concurrentRoleSets: [['coder', 'reviewer']],
     summaryPolicy: decideSummaryPolicy,
     validateOptions: validateDecideOptions,
     createRuntime(options) {
-        return createPlaybookRuntime(createDecideRuntimeOptions(options));
+        return createPlaybookRuntime(options);
     },
 };
 export default decidePlaybookRegistryEntry;

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

@@ -3,7 +3,6 @@
 
 import createPlaybookRuntime, {
   type PlaybookRuntime,
-  type PlaybookRuntimeOptions,
 } from './decide.playbook.js';
 
 export interface PlaybookSummaryPolicy {
@@ -15,27 +14,18 @@ export interface PlaybookSummaryPolicy {
   ): string;
 }
 
-export interface RegistryPlayer {
-  id: string;
-  adapter?: string;
-  model?: string;
-}
-
-export interface CreateDecideRuntimeOptions {
-  captainOptions: unknown;
-  players: readonly RegistryPlayer[];
-}
-
 export type DecideOptions = Readonly<Record<string, never>>;
 
 export interface DecidePlaybookRegistryEntry {
   id: 'decide';
   command: 'decide';
   intent: string;
+  artifactSchema: 2;
   requiredRoleIds: readonly ['coder', 'reviewer'];
+  concurrentRoleSets: readonly [readonly ['coder', 'reviewer']];
   summaryPolicy: PlaybookSummaryPolicy;
-  validateOptions(captainOptions: unknown): DecideOptions;
-  createRuntime(options: CreateDecideRuntimeOptions): PlaybookRuntime;
+  validateOptions(optionSlice: unknown): DecideOptions;
+  createRuntime(options: DecideOptions): PlaybookRuntime;
 }
 
 export const decideStateCountLabels = {
@@ -93,32 +83,18 @@ export function validateDecideOptions(optionSlice: unknown): DecideOptions {
   return Object.freeze({});
 }
 
-function playerIdentity(
-  players: readonly RegistryPlayer[],
-  id: string,
-): string {
-  const player = players.find((entry) => entry.id === id);
-  return player?.model ?? player?.adapter ?? id;
-}
-
-export function createDecideRuntimeOptions({
-  captainOptions,
-  players,
-}: CreateDecideRuntimeOptions): PlaybookRuntimeOptions {
-  validateDecideOptions(captainOptions);
-  return { coderLlm: playerIdentity(players, 'coder') };
-}
-
 export const decidePlaybookRegistryEntry: DecidePlaybookRegistryEntry = {
   id: 'decide',
   command: 'decide',
   intent:
     'turn independent Coder and Reviewer proposals into an approved spec-design commit',
+  artifactSchema: 2,
   requiredRoleIds: ['coder', 'reviewer'],
+  concurrentRoleSets: [['coder', 'reviewer']],
   summaryPolicy: decideSummaryPolicy,
   validateOptions: validateDecideOptions,
   createRuntime(options) {
-    return createPlaybookRuntime(createDecideRuntimeOptions(options));
+    return createPlaybookRuntime(options);
   },
 };
 

package/reference/sdlc/review.md

@@ -4,7 +4,7 @@
 
 # Review
 
-Players:
+Roles:
 
 - Coder
 - Reviewer
@@ -20,21 +20,19 @@ At the first review round, Captain shall give Reviewer the following instruction
 
 ```markdown
 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.
+Review the latest commit and resulting repository state; read the commit message first for its intent, scope, and rationale.
 ```
 
 After every review-fix commit, Captain shall give Reviewer the following instruction:
 
 ```markdown
-Review the latest commit and resulting repository state; read the commit message first for its intent and rationale.
+Review the latest commit and resulting repository state; read the commit message first for its intent, scope, and rationale.
 ```
 
 When Coder rejects every finding and makes no commit, Captain shall give Reviewer the following instruction:
 
 ```markdown
 No new commit was made because Coder rejected every finding.
-For any rebuttal, accept or challenge it.
-State which findings, if any, remain.
 ```
 
 At the start of *every* review round, Captain shall relay to Reviewer any Coder feedback from the preceding round and any relevant run results, in quotes (`>`) after the instruction.
@@ -44,6 +42,7 @@ At the start of *every* review round, Captain shall append the following instruc
 ```markdown
 Understand the full picture and think systematically about the underlying design.
 Continue to identify issues or improvements, if any (numbered; no duplication).
+For any rebuttal, accept or challenge it.
 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.

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

@@ -1,22 +1,22 @@
-type Player = 'Coder' | 'Reviewer';
+type Role = 'coder' | 'reviewer';
 type JumpableStateId = 'reviewInitial';
 export type ResumableStateId = 'reviewInitial' | 'addressFindings' | 'reviewAfterCommit' | 'reviewAfterRebuttal';
 export interface PendingBossQuestion {
     questionId: ResumableStateId;
     resumeStateId: ResumableStateId;
     sourceItem: `REVIEW-${1 | 2 | 3 | 4}`;
-    player: Player;
+    asker: {
+        readonly kind: 'role';
+        readonly roleId: Role;
+    };
     question: string;
 }
 export interface ReviewOutput {
     approvedCommit: 'latest';
     noUnsettledFindings: true;
 }
-export interface ReviewInput {
-    coderLlm: string;
-    reviewerLlm: string;
-}
-export interface ReviewContext extends ReviewInput {
+export type ReviewInput = Readonly<Record<string, never>>;
+export interface ReviewContext {
     callerInput?: string;
     reviewerOutput?: string;
     coderOutput?: string;
@@ -39,14 +39,12 @@ export type ReviewEvent = {
 export interface PlayerInput {
     stateId: ResumableStateId;
     sourceItem: `REVIEW-${1 | 2 | 3 | 4}`;
-    player: Player;
+    role: Role;
     prompt: string;
     result: Readonly<Record<string, string>>;
     callerInput?: string;
     reviewerOutput?: string;
     coderOutput?: string;
-    coderLlm?: string;
-    reviewerLlm?: string;
     pendingBossQuestion?: PendingBossQuestion;
     bossReply?: string;
 }
@@ -151,7 +149,7 @@ export declare const reviewMachine: import("xstate").StateMachine<ReviewContext,
 } | {
     type: "restartInitialReview";
     params: unknown;
-}, never, "done" | "failed" | "awaitBossReply" | "ready" | "reviewInitial" | "addressFindings" | "reviewAfterCommit" | "reviewAfterRebuttal", string, ReviewInput, ReviewOutput, import("xstate").EventObject, import("xstate").MetaObject, {
+}, never, "done" | "failed" | "awaitBossReply" | "ready" | "reviewInitial" | "addressFindings" | "reviewAfterCommit" | "reviewAfterRebuttal", string, Readonly<Record<string, never>>, ReviewOutput, import("xstate").EventObject, import("xstate").MetaObject, {
     id: "review";
     states: {
         readonly ready: {

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

@@ -7,6 +7,7 @@ const NEEDS_BOSS_REPLY_DESCRIPTION = "The acting agent's prose surfaces a clarif
 const SHARED_REVIEW_INSTRUCTION = [
     'Understand the full picture and think systematically about the underlying design.',
     'Continue to identify issues or improvements, if any (numbered; no duplication).',
+    'For any rebuttal, accept or challenge it.',
     '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.',
@@ -20,14 +21,14 @@ const SHARED_REVIEW_INSTRUCTION = [
 ].join('\n');
 const INITIAL_REVIEW_PROMPT = [
     '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.',
+    'Review the latest commit and resulting repository state; read the commit message first for its intent, scope, and rationale.',
     '',
     '> <caller-input>',
     '',
     SHARED_REVIEW_INSTRUCTION,
 ].join('\n');
 const POST_COMMIT_REVIEW_PROMPT = [
-    'Review the latest commit and resulting repository state; read the commit message first for its intent and rationale.',
+    'Review the latest commit and resulting repository state; read the commit message first for its intent, scope, and rationale.',
     '',
     '> <coder-output>',
     '',
@@ -35,8 +36,6 @@ const POST_COMMIT_REVIEW_PROMPT = [
 ].join('\n');
 const REBUTTAL_REVIEW_PROMPT = [
     '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>',
     '',
@@ -85,20 +84,32 @@ const stateDescriptions = {
     failed: 'Retains a recoverable REVIEW failure for the caller.',
     done: 'The latest commit is approved with no unsettled findings.',
 };
-const playbookMeta = (stateId, player) => ({
+const playbookMeta = (stateId, role) => ({
     playbook: {
         stateId,
         description: stateDescriptions[stateId],
-        ...(player === undefined ? {} : { player }),
+        ...(role === undefined ? {} : { role }),
     },
 });
 const outputOf = (event) => event.output;
 const isNonEmptyString = (value) => typeof value === 'string' && value.trim().length > 0;
 const stateMetadata = {
-    reviewInitial: { sourceItem: 'REVIEW-1', player: 'Reviewer' },
-    addressFindings: { sourceItem: 'REVIEW-2', player: 'Coder' },
-    reviewAfterCommit: { sourceItem: 'REVIEW-3', player: 'Reviewer' },
-    reviewAfterRebuttal: { sourceItem: 'REVIEW-4', player: 'Reviewer' },
+    reviewInitial: {
+        sourceItem: 'REVIEW-1',
+        asker: { kind: 'role', roleId: 'reviewer' },
+    },
+    addressFindings: {
+        sourceItem: 'REVIEW-2',
+        asker: { kind: 'role', roleId: 'coder' },
+    },
+    reviewAfterCommit: {
+        sourceItem: 'REVIEW-3',
+        asker: { kind: 'role', roleId: 'reviewer' },
+    },
+    reviewAfterRebuttal: {
+        sourceItem: 'REVIEW-4',
+        asker: { kind: 'role', roleId: 'reviewer' },
+    },
 };
 const playerPlaceholder = fromPromise(async () => {
     throw new Error('player actor must be provided by the runner');
@@ -264,10 +275,7 @@ export const reviewMachine = setup({
     },
 }).createMachine({
     id: 'review',
-    context: ({ input }) => ({
-        coderLlm: input.coderLlm,
-        reviewerLlm: input.reviewerLlm,
-    }),
+    context: {},
     initial: 'ready',
     on: {
         BOSS_INTERRUPT: {
@@ -294,14 +302,14 @@ export const reviewMachine = setup({
         reviewInitial: {
             id: 'reviewInitial',
             description: stateDescriptions.reviewInitial,
-            meta: playbookMeta('reviewInitial', 'Reviewer'),
+            meta: playbookMeta('reviewInitial', 'reviewer'),
             tags: ['playbook.busy'],
             invoke: {
                 src: 'player',
                 input: ({ context }) => ({
                     stateId: 'reviewInitial',
                     sourceItem: 'REVIEW-1',
-                    player: 'Reviewer',
+                    role: 'reviewer',
                     prompt: INITIAL_REVIEW_PROMPT,
                     result: REVIEW_RESULTS,
                     callerInput: context.callerInput,
@@ -334,19 +342,17 @@ export const reviewMachine = setup({
         addressFindings: {
             id: 'addressFindings',
             description: stateDescriptions.addressFindings,
-            meta: playbookMeta('addressFindings', 'Coder'),
+            meta: playbookMeta('addressFindings', 'coder'),
             tags: ['playbook.busy'],
             invoke: {
                 src: 'player',
                 input: ({ context }) => ({
                     stateId: 'addressFindings',
                     sourceItem: 'REVIEW-2',
-                    player: 'Coder',
+                    role: 'coder',
                     prompt: CODER_DISPOSITION_PROMPT,
                     result: CODER_RESULTS,
                     reviewerOutput: context.reviewerOutput,
-                    coderLlm: context.coderLlm,
-                    reviewerLlm: context.reviewerLlm,
                     pendingBossQuestion: context.pendingBossQuestion,
                     bossReply: context.bossReply,
                 }),
@@ -376,14 +382,14 @@ export const reviewMachine = setup({
         reviewAfterCommit: {
             id: 'reviewAfterCommit',
             description: stateDescriptions.reviewAfterCommit,
-            meta: playbookMeta('reviewAfterCommit', 'Reviewer'),
+            meta: playbookMeta('reviewAfterCommit', 'reviewer'),
             tags: ['playbook.busy'],
             invoke: {
                 src: 'player',
                 input: ({ context }) => ({
                     stateId: 'reviewAfterCommit',
                     sourceItem: 'REVIEW-3',
-                    player: 'Reviewer',
+                    role: 'reviewer',
                     prompt: POST_COMMIT_REVIEW_PROMPT,
                     result: REVIEW_RESULTS,
                     coderOutput: context.coderOutput,
@@ -416,14 +422,14 @@ export const reviewMachine = setup({
         reviewAfterRebuttal: {
             id: 'reviewAfterRebuttal',
             description: stateDescriptions.reviewAfterRebuttal,
-            meta: playbookMeta('reviewAfterRebuttal', 'Reviewer'),
+            meta: playbookMeta('reviewAfterRebuttal', 'reviewer'),
             tags: ['playbook.busy'],
             invoke: {
                 src: 'player',
                 input: ({ context }) => ({
                     stateId: 'reviewAfterRebuttal',
                     sourceItem: 'REVIEW-4',
-                    player: 'Reviewer',
+                    role: 'reviewer',
                     prompt: REBUTTAL_REVIEW_PROMPT,
                     result: REBUTTAL_RESULTS,
                     coderOutput: context.coderOutput,

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

@@ -6,7 +6,7 @@
 
 import { assign, fromPromise, setup } from 'xstate';
 
-type Player = 'Coder' | 'Reviewer';
+type Role = 'coder' | 'reviewer';
 
 type JumpableStateId = 'reviewInitial';
 
@@ -20,7 +20,7 @@ export interface PendingBossQuestion {
   questionId: ResumableStateId;
   resumeStateId: ResumableStateId;
   sourceItem: `REVIEW-${1 | 2 | 3 | 4}`;
-  player: Player;
+  asker: { readonly kind: 'role'; readonly roleId: Role };
   question: string;
 }
 
@@ -29,12 +29,9 @@ export interface ReviewOutput {
   noUnsettledFindings: true;
 }
 
-export interface ReviewInput {
-  coderLlm: string;
-  reviewerLlm: string;
-}
+export type ReviewInput = Readonly<Record<string, never>>;
 
-export interface ReviewContext extends ReviewInput {
+export interface ReviewContext {
   callerInput?: string;
   reviewerOutput?: string;
   coderOutput?: string;
@@ -59,14 +56,12 @@ export type ReviewEvent =
 export interface PlayerInput {
   stateId: ResumableStateId;
   sourceItem: `REVIEW-${1 | 2 | 3 | 4}`;
-  player: Player;
+  role: Role;
   prompt: string;
   result: Readonly<Record<string, string>>;
   callerInput?: string;
   reviewerOutput?: string;
   coderOutput?: string;
-  coderLlm?: string;
-  reviewerLlm?: string;
   pendingBossQuestion?: PendingBossQuestion;
   bossReply?: string;
 }
@@ -86,6 +81,7 @@ const NEEDS_BOSS_REPLY_DESCRIPTION =
 const SHARED_REVIEW_INSTRUCTION = [
   'Understand the full picture and think systematically about the underlying design.',
   'Continue to identify issues or improvements, if any (numbered; no duplication).',
+  'For any rebuttal, accept or challenge it.',
   '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.',
@@ -100,7 +96,7 @@ const SHARED_REVIEW_INSTRUCTION = [
 
 const INITIAL_REVIEW_PROMPT = [
   '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.',
+  'Review the latest commit and resulting repository state; read the commit message first for its intent, scope, and rationale.',
   '',
   '> <caller-input>',
   '',
@@ -108,7 +104,7 @@ const INITIAL_REVIEW_PROMPT = [
 ].join('\n');
 
 const POST_COMMIT_REVIEW_PROMPT = [
-  'Review the latest commit and resulting repository state; read the commit message first for its intent and rationale.',
+  'Review the latest commit and resulting repository state; read the commit message first for its intent, scope, and rationale.',
   '',
   '> <coder-output>',
   '',
@@ -117,8 +113,6 @@ const POST_COMMIT_REVIEW_PROMPT = [
 
 const REBUTTAL_REVIEW_PROMPT = [
   '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>',
   '',
@@ -184,12 +178,12 @@ const stateDescriptions = {
 
 const playbookMeta = <StateId extends keyof typeof stateDescriptions>(
   stateId: StateId,
-  player?: Player,
+  role?: Role,
 ) => ({
   playbook: {
     stateId,
     description: stateDescriptions[stateId],
-    ...(player === undefined ? {} : { player }),
+    ...(role === undefined ? {} : { role }),
   },
 });
 
@@ -200,13 +194,28 @@ const isNonEmptyString = (value: unknown): value is string =>
   typeof value === 'string' && value.trim().length > 0;
 
 const stateMetadata = {
-  reviewInitial: { sourceItem: 'REVIEW-1', player: 'Reviewer' },
-  addressFindings: { sourceItem: 'REVIEW-2', player: 'Coder' },
-  reviewAfterCommit: { sourceItem: 'REVIEW-3', player: 'Reviewer' },
-  reviewAfterRebuttal: { sourceItem: 'REVIEW-4', player: 'Reviewer' },
+  reviewInitial: {
+    sourceItem: 'REVIEW-1',
+    asker: { kind: 'role', roleId: 'reviewer' },
+  },
+  addressFindings: {
+    sourceItem: 'REVIEW-2',
+    asker: { kind: 'role', roleId: 'coder' },
+  },
+  reviewAfterCommit: {
+    sourceItem: 'REVIEW-3',
+    asker: { kind: 'role', roleId: 'reviewer' },
+  },
+  reviewAfterRebuttal: {
+    sourceItem: 'REVIEW-4',
+    asker: { kind: 'role', roleId: 'reviewer' },
+  },
 } as const satisfies Record<
   ResumableStateId,
-  { sourceItem: `REVIEW-${1 | 2 | 3 | 4}`; player: Player }
+  {
+    sourceItem: `REVIEW-${1 | 2 | 3 | 4}`;
+    asker: { readonly kind: 'role'; readonly roleId: Role };
+  }
 >;
 
 const playerPlaceholder = fromPromise<PlayerOutput, PlayerInput>(async () => {
@@ -392,10 +401,7 @@ export const reviewMachine = setup({
   },
 }).createMachine({
   id: 'review',
-  context: ({ input }) => ({
-    coderLlm: input.coderLlm,
-    reviewerLlm: input.reviewerLlm,
-  }),
+  context: {},
   initial: 'ready',
   on: {
     BOSS_INTERRUPT: {
@@ -422,14 +428,14 @@ export const reviewMachine = setup({
     reviewInitial: {
       id: 'reviewInitial',
       description: stateDescriptions.reviewInitial,
-      meta: playbookMeta('reviewInitial', 'Reviewer'),
+      meta: playbookMeta('reviewInitial', 'reviewer'),
       tags: ['playbook.busy'],
       invoke: {
         src: 'player',
         input: ({ context }): PlayerInput => ({
           stateId: 'reviewInitial',
           sourceItem: 'REVIEW-1',
-          player: 'Reviewer',
+          role: 'reviewer',
           prompt: INITIAL_REVIEW_PROMPT,
           result: REVIEW_RESULTS,
           callerInput: context.callerInput,
@@ -462,19 +468,17 @@ export const reviewMachine = setup({
     addressFindings: {
       id: 'addressFindings',
       description: stateDescriptions.addressFindings,
-      meta: playbookMeta('addressFindings', 'Coder'),
+      meta: playbookMeta('addressFindings', 'coder'),
       tags: ['playbook.busy'],
       invoke: {
         src: 'player',
         input: ({ context }): PlayerInput => ({
           stateId: 'addressFindings',
           sourceItem: 'REVIEW-2',
-          player: 'Coder',
+          role: 'coder',
           prompt: CODER_DISPOSITION_PROMPT,
           result: CODER_RESULTS,
           reviewerOutput: context.reviewerOutput,
-          coderLlm: context.coderLlm,
-          reviewerLlm: context.reviewerLlm,
           pendingBossQuestion: context.pendingBossQuestion,
           bossReply: context.bossReply,
         }),
@@ -504,14 +508,14 @@ export const reviewMachine = setup({
     reviewAfterCommit: {
       id: 'reviewAfterCommit',
       description: stateDescriptions.reviewAfterCommit,
-      meta: playbookMeta('reviewAfterCommit', 'Reviewer'),
+      meta: playbookMeta('reviewAfterCommit', 'reviewer'),
       tags: ['playbook.busy'],
       invoke: {
         src: 'player',
         input: ({ context }): PlayerInput => ({
           stateId: 'reviewAfterCommit',
           sourceItem: 'REVIEW-3',
-          player: 'Reviewer',
+          role: 'reviewer',
           prompt: POST_COMMIT_REVIEW_PROMPT,
           result: REVIEW_RESULTS,
           coderOutput: context.coderOutput,
@@ -544,14 +548,14 @@ export const reviewMachine = setup({
     reviewAfterRebuttal: {
       id: 'reviewAfterRebuttal',
       description: stateDescriptions.reviewAfterRebuttal,
-      meta: playbookMeta('reviewAfterRebuttal', 'Reviewer'),
+      meta: playbookMeta('reviewAfterRebuttal', 'reviewer'),
       tags: ['playbook.busy'],
       invoke: {
         src: 'player',
         input: ({ context }): PlayerInput => ({
           stateId: 'reviewAfterRebuttal',
           sourceItem: 'REVIEW-4',
-          player: 'Reviewer',
+          role: 'reviewer',
           prompt: REBUTTAL_REVIEW_PROMPT,
           result: REBUTTAL_RESULTS,
           coderOutput: context.coderOutput,

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

@@ -3,7 +3,7 @@
 
 # REVIEW: Commit Review Workflow
 
-Players:
+Roles:
 
 - Coder
 - Reviewer
@@ -13,12 +13,13 @@ Players:
 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.
+> Review the latest commit and resulting repository state; read the commit message first for its intent, scope, 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).
+> For any rebuttal, accept or challenge it.
 > 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.
@@ -63,12 +64,13 @@ Results:
 
 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.
+> Review the latest commit and resulting repository state; read the commit message first for its intent, scope, 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).
+> For any rebuttal, accept or challenge it.
 > 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.
@@ -89,13 +91,12 @@ Results:
 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).
+> For any rebuttal, accept or challenge it.
 > 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.