@sublang/playbook 9.0.0 → 11.0.0

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

@@ -1,4 +1,4 @@
-import { type PlaybookRuntime } from './decide.playbook.js';
+import { type DecidePlaybookHostCapabilities, type PlaybookRuntime } from './decide.playbook.js';
 export interface PlaybookSummaryPolicy {
     stateCountLabels: Readonly<Record<string, string>>;
     copyPasteGuardNames: readonly string[];
@@ -12,12 +12,16 @@ export interface DecidePlaybookRegistryEntry {
     id: 'decide';
     command: 'decide';
     intent: string;
-    artifactSchema: 2;
+    artifactSchema: 3;
+    runtimeProfile: {
+        readonly kind: 'bespoke';
+        readonly artifactSchema: 3;
+    };
     requiredRoleIds: readonly ['coder', 'reviewer'];
     concurrentRoleSets: readonly [readonly ['coder', 'reviewer']];
     summaryPolicy: PlaybookSummaryPolicy;
     validateOptions(optionSlice: unknown): DecideOptions;
-    createRuntime(options: DecideOptions): PlaybookRuntime;
+    createRuntime(options: DecideOptions, hostCapabilities: DecidePlaybookHostCapabilities): PlaybookRuntime;
 }
 export declare const decideStateCountLabels: {
     readonly independentProposals: "proposal round";

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

@@ -42,13 +42,20 @@ export const decidePlaybookRegistryEntry = {
     id: 'decide',
     command: 'decide',
     intent: 'turn independent Coder and Reviewer proposals into an approved spec-design commit',
-    artifactSchema: 2,
+    artifactSchema: 3,
+    runtimeProfile: Object.freeze({
+        kind: 'bespoke',
+        artifactSchema: 3,
+    }),
     requiredRoleIds: ['coder', 'reviewer'],
     concurrentRoleSets: [['coder', 'reviewer']],
     summaryPolicy: decideSummaryPolicy,
     validateOptions: validateDecideOptions,
-    createRuntime(options) {
-        return createPlaybookRuntime(options);
+    createRuntime(options, hostCapabilities) {
+        return createPlaybookRuntime({
+            configuredOptions: options,
+            hostCapabilities,
+        });
     },
 };
 export default decidePlaybookRegistryEntry;

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

@@ -2,6 +2,7 @@
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 
 import createPlaybookRuntime, {
+  type DecidePlaybookHostCapabilities,
   type PlaybookRuntime,
 } from './decide.playbook.js';
 
@@ -20,12 +21,19 @@ export interface DecidePlaybookRegistryEntry {
   id: 'decide';
   command: 'decide';
   intent: string;
-  artifactSchema: 2;
+  artifactSchema: 3;
+  runtimeProfile: {
+    readonly kind: 'bespoke';
+    readonly artifactSchema: 3;
+  };
   requiredRoleIds: readonly ['coder', 'reviewer'];
   concurrentRoleSets: readonly [readonly ['coder', 'reviewer']];
   summaryPolicy: PlaybookSummaryPolicy;
   validateOptions(optionSlice: unknown): DecideOptions;
-  createRuntime(options: DecideOptions): PlaybookRuntime;
+  createRuntime(
+    options: DecideOptions,
+    hostCapabilities: DecidePlaybookHostCapabilities,
+  ): PlaybookRuntime;
 }
 
 export const decideStateCountLabels = {
@@ -88,13 +96,20 @@ export const decidePlaybookRegistryEntry: DecidePlaybookRegistryEntry = {
   command: 'decide',
   intent:
     'turn independent Coder and Reviewer proposals into an approved spec-design commit',
-  artifactSchema: 2,
+  artifactSchema: 3,
+  runtimeProfile: Object.freeze({
+    kind: 'bespoke',
+    artifactSchema: 3,
+  }),
   requiredRoleIds: ['coder', 'reviewer'],
   concurrentRoleSets: [['coder', 'reviewer']],
   summaryPolicy: decideSummaryPolicy,
   validateOptions: validateDecideOptions,
-  createRuntime(options) {
-    return createPlaybookRuntime(options);
+  createRuntime(options, hostCapabilities) {
+    return createPlaybookRuntime({
+      configuredOptions: options,
+      hostCapabilities,
+    });
   },
 };
 

package/reference/sdlc/review.md

@@ -9,45 +9,55 @@ Roles:
 - Coder
 - Reviewer
 
-The caller supplies the initial intent or any specific context and relevant run results.
+The caller supplies:
 
-`review` examines committed work only.
-Every review round begins with a new or existing commit.
+- the original intent;
+- the review scope in the caller's own words;
+- optional relevant context and run results.
 
-At the first review round, Captain shall relay to Reviewer the complete initial review request in quotes (`>`).
+The caller's review scope is the baseline for every round, and each review-fix commit joins that scope as it lands, so every later round reviews the cumulative committed state.
+`review` examines committed work only.
+Captain shall take the evaluated repository revision from repository authority, not from either player's prose.
 
 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, scope, and rationale.
+A new review begins for the review scope.
+Keep to the original intent and follow what it asks.
+When the scope names commits, read each commit message for its context and rationale; otherwise use repository history and commit messages wherever they help establish that context.
 ```
 
 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, scope, and rationale.
+A new review round begins for the review scope in the cumulative committed state, with particular attention to the latest review-fix commit.
+Keep to the original intent and follow what it asks.
+Read the latest review-fix commit's message and see Coder's feedback below.
 ```
 
 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.
+See Coder's feedback below.
 ```
 
-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.
+At the start of *every* review round, Captain shall relay to Reviewer the original intent, the review scope and context, the exact repository revision being evaluated, any Coder feedback from the preceding round, and any relevant run results, in quotes (`>`) after the instruction.
 
 At the start of *every* review round, Captain shall append the following instruction to the end of the prompt:
 
 ```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.
+Continue to identify issues or improvements, if any, without duplication.
+Number the findings consistently across rounds.
 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.
+For specs, flag stale, missing, over-specified, or under-specified ones, if any.
 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.
 
+If an issue represents a class of defect, find every instance within the review scope worth fixing rather than surfacing one or two per round, which drags out the review.
+For any rebuttal, accept or challenge it.
+Treat as settled, and do not raise again, any finding in this review rejected twice with reasoning.
+
 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.
 
@@ -55,26 +65,34 @@ 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.
 ```
 
-When Reviewer raises or keeps any finding, Captain shall relay the Reviewer's findings and any relevant run results to Coder, in quotes (`>`), along with the following prompt:
+Finding numbers are references within this review only.
+No review transition shall depend on numbering or any fixed presentation format of either player's reply.
+
+When Reviewer raises or keeps any finding, Captain shall relay the original intent, the review scope and context, the exact repository revision being evaluated, the Reviewer's findings, and any relevant run results to Coder, in quotes (`>`), along with the following prompt:
 
 ```markdown
 For each review item, accept or reject it.
 Before deciding, understand the full picture and think systematically about the underlying design.
+Keep to the original intent and follow what it asks.
 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 accept an item, fix its root cause, including any fundamental design flaw — do not patch around it; if it represents a class of defect, find every instance within the review scope worth fixing rather than addressing one or two per round, which drags out the review.
 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.
+If you accept any item, make minimal changes and add one new review-fix commit; never rewrite any existing 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.
+Identify every new commit you make.
+Coder is <coder-llm>; Reviewer is <reviewer-llm>.
 
 If you reject every item, change nothing and make no commit.
 Report every disposition, all relevant run results, and every rebuttal.
 ```
 
+Captain shall use the repository-effect receipt as the authoritative identity of any review-fix commit.
+
 When Coder makes a new commit or decides to reject all findings, Captain shall relay the above required context to Reviewer and begin the next review round.
 Reviewer shall read the context information and follow the corresponding instructions.
-Rounds continue until Reviewer raises no unsettled findings.
-`review` then returns the approved latest commit and the fact that no findings remain to its caller.
+Rounds continue until Reviewer affirmatively reports that the requested review is complete and no unsettled findings remain.
+A progress report, status update, or promise of a later result supports no review outcome.
+`review` then returns the exact repository revision at which the review scope was evaluated and the fact that no unsettled findings remain within that scope.

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

@@ -81,6 +81,13 @@ export declare const reviewMachine: import("xstate").StateMachine<ReviewContext,
     logic: import("xstate").PromiseActorLogic<PlayerOutput, PlayerInput, import("xstate").EventObject>;
     id: string | undefined;
 }, {
+    type: "playbook.acceptedOutcome";
+    params: {
+        readonly source: string;
+        readonly target: string;
+        readonly acceptedOutcome: string;
+    };
+} | {
     type: "rememberActorError";
     params: import("xstate").NonReducibleUnknown;
 } | {

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

@@ -170,6 +170,7 @@ export const reviewMachine = setup({
             event.bossIntent.trim().length > 0,
     },
     actions: {
+        'playbook.acceptedOutcome': (_args, _params) => undefined,
         copyStartInput: assign({
             callerInput: ({ event }) => event.type === 'START_REVIEW' ? event.callerInput : undefined,
             reviewerOutput: undefined,
@@ -320,17 +321,47 @@ export const reviewMachine = setup({
                     {
                         guard: 'hasFindings',
                         target: '#addressFindings',
-                        actions: 'rememberReviewerOutput',
+                        actions: [
+                            {
+                                type: 'playbook.acceptedOutcome',
+                                params: {
+                                    source: 'reviewInitial',
+                                    target: 'addressFindings',
+                                    acceptedOutcome: 'hasFindings',
+                                },
+                            },
+                            'rememberReviewerOutput',
+                        ],
                     },
                     {
                         guard: 'noFindings',
                         target: '#done',
-                        actions: 'clearBossReplyContext',
+                        actions: [
+                            {
+                                type: 'playbook.acceptedOutcome',
+                                params: {
+                                    source: 'reviewInitial',
+                                    target: 'done',
+                                    acceptedOutcome: 'noFindings',
+                                },
+                            },
+                            'clearBossReplyContext',
+                        ],
                     },
                     {
                         guard: 'needsBossReply',
                         target: '#awaitBossReply',
-                        actions: 'setPendingReviewInitial',
+                        actions: [
+                            {
+                                type: 'playbook.acceptedOutcome',
+                                params: {
+                                    source: 'reviewInitial',
+                                    target: 'awaitBossReply',
+                                    acceptedOutcome: 'needsBossReply',
+                                },
+                            },
+                            'setPendingReviewInitial',
+                        ],
                     },
                 ],
                 onError: {
@@ -360,17 +391,47 @@ export const reviewMachine = setup({
                     {
                         guard: 'committed',
                         target: '#reviewAfterCommit',
-                        actions: 'rememberCoderOutput',
+                        actions: [
+                            {
+                                type: 'playbook.acceptedOutcome',
+                                params: {
+                                    source: 'addressFindings',
+                                    target: 'reviewAfterCommit',
+                                    acceptedOutcome: 'committed',
+                                },
+                            },
+                            'rememberCoderOutput',
+                        ],
                     },
                     {
                         guard: 'rejectedAll',
                         target: '#reviewAfterRebuttal',
-                        actions: 'rememberCoderOutput',
+                        actions: [
+                            {
+                                type: 'playbook.acceptedOutcome',
+                                params: {
+                                    source: 'addressFindings',
+                                    target: 'reviewAfterRebuttal',
+                                    acceptedOutcome: 'rejectedAll',
+                                },
+                            },
+                            'rememberCoderOutput',
+                        ],
                     },
                     {
                         guard: 'needsBossReply',
                         target: '#awaitBossReply',
-                        actions: 'setPendingAddressFindings',
+                        actions: [
+                            {
+                                type: 'playbook.acceptedOutcome',
+                                params: {
+                                    source: 'addressFindings',
+                                    target: 'awaitBossReply',
+                                    acceptedOutcome: 'needsBossReply',
+                                },
+                            },
+                            'setPendingAddressFindings',
+                        ],
                     },
                 ],
                 onError: {
@@ -400,17 +461,47 @@ export const reviewMachine = setup({
                     {
                         guard: 'hasFindings',
                         target: '#addressFindings',
-                        actions: 'rememberReviewerOutput',
+                        actions: [
+                            {
+                                type: 'playbook.acceptedOutcome',
+                                params: {
+                                    source: 'reviewAfterCommit',
+                                    target: 'addressFindings',
+                                    acceptedOutcome: 'hasFindings',
+                                },
+                            },
+                            'rememberReviewerOutput',
+                        ],
                     },
                     {
                         guard: 'noFindings',
                         target: '#done',
-                        actions: 'clearBossReplyContext',
+                        actions: [
+                            {
+                                type: 'playbook.acceptedOutcome',
+                                params: {
+                                    source: 'reviewAfterCommit',
+                                    target: 'done',
+                                    acceptedOutcome: 'noFindings',
+                                },
+                            },
+                            'clearBossReplyContext',
+                        ],
                     },
                     {
                         guard: 'needsBossReply',
                         target: '#awaitBossReply',
-                        actions: 'setPendingReviewAfterCommit',
+                        actions: [
+                            {
+                                type: 'playbook.acceptedOutcome',
+                                params: {
+                                    source: 'reviewAfterCommit',
+                                    target: 'awaitBossReply',
+                                    acceptedOutcome: 'needsBossReply',
+                                },
+                            },
+                            'setPendingReviewAfterCommit',
+                        ],
                     },
                 ],
                 onError: {
@@ -440,17 +531,47 @@ export const reviewMachine = setup({
                     {
                         guard: 'hasFindings',
                         target: '#addressFindings',
-                        actions: 'rememberReviewerOutput',
+                        actions: [
+                            {
+                                type: 'playbook.acceptedOutcome',
+                                params: {
+                                    source: 'reviewAfterRebuttal',
+                                    target: 'addressFindings',
+                                    acceptedOutcome: 'hasFindings',
+                                },
+                            },
+                            'rememberReviewerOutput',
+                        ],
                     },
                     {
                         guard: 'noFindings',
                         target: '#done',
-                        actions: 'clearBossReplyContext',
+                        actions: [
+                            {
+                                type: 'playbook.acceptedOutcome',
+                                params: {
+                                    source: 'reviewAfterRebuttal',
+                                    target: 'done',
+                                    acceptedOutcome: 'noFindings',
+                                },
+                            },
+                            'clearBossReplyContext',
+                        ],
                     },
                     {
                         guard: 'needsBossReply',
                         target: '#awaitBossReply',
-                        actions: 'setPendingReviewAfterRebuttal',
+                        actions: [
+                            {
+                                type: 'playbook.acceptedOutcome',
+                                params: {
+                                    source: 'reviewAfterRebuttal',
+                                    target: 'awaitBossReply',
+                                    acceptedOutcome: 'needsBossReply',
+                                },
+                            },
+                            'setPendingReviewAfterRebuttal',
+                        ],
                     },
                 ],
                 onError: {

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

@@ -292,6 +292,14 @@ export const reviewMachine = setup({
       event.bossIntent.trim().length > 0,
   },
   actions: {
+    'playbook.acceptedOutcome': (
+      _args,
+      _params: {
+        readonly source: string;
+        readonly target: string;
+        readonly acceptedOutcome: string;
+      },
+    ) => undefined,
     copyStartInput: assign({
       callerInput: ({ event }) =>
         event.type === 'START_REVIEW' ? event.callerInput : undefined,
@@ -446,17 +454,47 @@ export const reviewMachine = setup({
           {
             guard: 'hasFindings',
             target: '#addressFindings',
-            actions: 'rememberReviewerOutput',
+            actions: [
+              {
+                type: 'playbook.acceptedOutcome',
+                params: {
+                  source: 'reviewInitial',
+                  target: 'addressFindings',
+                  acceptedOutcome: 'hasFindings',
+                },
+              },
+              'rememberReviewerOutput',
+            ],
           },
           {
             guard: 'noFindings',
             target: '#done',
-            actions: 'clearBossReplyContext',
+            actions: [
+              {
+                type: 'playbook.acceptedOutcome',
+                params: {
+                  source: 'reviewInitial',
+                  target: 'done',
+                  acceptedOutcome: 'noFindings',
+                },
+              },
+              'clearBossReplyContext',
+            ],
           },
           {
             guard: 'needsBossReply',
             target: '#awaitBossReply',
-            actions: 'setPendingReviewInitial',
+            actions: [
+              {
+                type: 'playbook.acceptedOutcome',
+                params: {
+                  source: 'reviewInitial',
+                  target: 'awaitBossReply',
+                  acceptedOutcome: 'needsBossReply',
+                },
+              },
+              'setPendingReviewInitial',
+            ],
           },
         ],
         onError: {
@@ -486,17 +524,47 @@ export const reviewMachine = setup({
           {
             guard: 'committed',
             target: '#reviewAfterCommit',
-            actions: 'rememberCoderOutput',
+            actions: [
+              {
+                type: 'playbook.acceptedOutcome',
+                params: {
+                  source: 'addressFindings',
+                  target: 'reviewAfterCommit',
+                  acceptedOutcome: 'committed',
+                },
+              },
+              'rememberCoderOutput',
+            ],
           },
           {
             guard: 'rejectedAll',
             target: '#reviewAfterRebuttal',
-            actions: 'rememberCoderOutput',
+            actions: [
+              {
+                type: 'playbook.acceptedOutcome',
+                params: {
+                  source: 'addressFindings',
+                  target: 'reviewAfterRebuttal',
+                  acceptedOutcome: 'rejectedAll',
+                },
+              },
+              'rememberCoderOutput',
+            ],
           },
           {
             guard: 'needsBossReply',
             target: '#awaitBossReply',
-            actions: 'setPendingAddressFindings',
+            actions: [
+              {
+                type: 'playbook.acceptedOutcome',
+                params: {
+                  source: 'addressFindings',
+                  target: 'awaitBossReply',
+                  acceptedOutcome: 'needsBossReply',
+                },
+              },
+              'setPendingAddressFindings',
+            ],
           },
         ],
         onError: {
@@ -526,17 +594,47 @@ export const reviewMachine = setup({
           {
             guard: 'hasFindings',
             target: '#addressFindings',
-            actions: 'rememberReviewerOutput',
+            actions: [
+              {
+                type: 'playbook.acceptedOutcome',
+                params: {
+                  source: 'reviewAfterCommit',
+                  target: 'addressFindings',
+                  acceptedOutcome: 'hasFindings',
+                },
+              },
+              'rememberReviewerOutput',
+            ],
           },
           {
             guard: 'noFindings',
             target: '#done',
-            actions: 'clearBossReplyContext',
+            actions: [
+              {
+                type: 'playbook.acceptedOutcome',
+                params: {
+                  source: 'reviewAfterCommit',
+                  target: 'done',
+                  acceptedOutcome: 'noFindings',
+                },
+              },
+              'clearBossReplyContext',
+            ],
           },
           {
             guard: 'needsBossReply',
             target: '#awaitBossReply',
-            actions: 'setPendingReviewAfterCommit',
+            actions: [
+              {
+                type: 'playbook.acceptedOutcome',
+                params: {
+                  source: 'reviewAfterCommit',
+                  target: 'awaitBossReply',
+                  acceptedOutcome: 'needsBossReply',
+                },
+              },
+              'setPendingReviewAfterCommit',
+            ],
           },
         ],
         onError: {
@@ -566,17 +664,47 @@ export const reviewMachine = setup({
           {
             guard: 'hasFindings',
             target: '#addressFindings',
-            actions: 'rememberReviewerOutput',
+            actions: [
+              {
+                type: 'playbook.acceptedOutcome',
+                params: {
+                  source: 'reviewAfterRebuttal',
+                  target: 'addressFindings',
+                  acceptedOutcome: 'hasFindings',
+                },
+              },
+              'rememberReviewerOutput',
+            ],
           },
           {
             guard: 'noFindings',
             target: '#done',
-            actions: 'clearBossReplyContext',
+            actions: [
+              {
+                type: 'playbook.acceptedOutcome',
+                params: {
+                  source: 'reviewAfterRebuttal',
+                  target: 'done',
+                  acceptedOutcome: 'noFindings',
+                },
+              },
+              'clearBossReplyContext',
+            ],
           },
           {
             guard: 'needsBossReply',
             target: '#awaitBossReply',
-            actions: 'setPendingReviewAfterRebuttal',
+            actions: [
+              {
+                type: 'playbook.acceptedOutcome',
+                params: {
+                  source: 'reviewAfterRebuttal',
+                  target: 'awaitBossReply',
+                  acceptedOutcome: 'needsBossReply',
+                },
+              },
+              'setPendingReviewAfterRebuttal',
+            ],
           },
         ],
         onError: {