@sublang/playbook 9.0.0 → 10.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.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: {

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

@@ -1,13 +1,16 @@
-import { type XStatePromptIdentity } from '@sublang/playbook/xstate-runtime';
+import { type XStatePlaybookRuntimeFactory, type XStatePlaybookRuntimeConstruction, type XStatePromptIdentity } from '@sublang/playbook/xstate-runtime';
 import { type PlayerInput, type ReviewInput } from './review.fsm.js';
+import type { PlaybookHostConstructionCapabilities } from '../code.playbook/playbook-captain.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;
+export type ReviewPlaybookHostCapabilities = PlaybookHostConstructionCapabilities & XStatePlaybookRuntimeConstruction<ReviewPlaybookOptions, object>['hostCapabilities'];
 /** Keep every line of a relayed runtime value inside its authored quote. */
 declare function composePlayerPrompt(input: PlayerInput, promptIdentity: XStatePromptIdentity): string;
 export declare const _internal: {
     composePlayerPrompt: typeof composePlayerPrompt;
     VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string>;
+    UNFINISHED_FINAL_STATE_IDS: ReadonlySet<string>;
 };
-declare const createPlaybookRuntime: PlaybookRuntimeFactory<ReviewPlaybookOptions>;
+declare const createPlaybookRuntime: XStatePlaybookRuntimeFactory<XStatePlaybookRuntimeConstruction<ReviewPlaybookOptions, ReviewPlaybookHostCapabilities>, 3>;
 export default createPlaybookRuntime;

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

@@ -8,7 +8,7 @@
 //                callerInput; pending player questions retain BOSS_REPLY
 // Adjudication:  LLM judge per state; coderOutput and reviewerOutput are
 //                carried verbatim
-// Compat:        artifact schema 2 / runtime ABI 1
+// Compat:        artifact schema 3 / runtime ABI 1
 import { createXStatePlaybookRuntime, snapshotJsonValue, } from '@sublang/playbook/xstate-runtime';
 import { reviewMachine, } from './review.fsm.js';
 const PLACEHOLDER = /<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>/g;
@@ -17,6 +17,7 @@ const VERBATIM_PAYLOAD_FIELDS = new Set([
     'reviewerOutput',
     'coderOutput',
 ]);
+const UNFINISHED_FINAL_STATE_IDS = new Set();
 function snapshotReviewOptions(value) {
     const captured = snapshotJsonValue(value, 'REVIEW runtime options');
     if (captured === null ||
@@ -68,6 +69,7 @@ function composePlayerPrompt(input, promptIdentity) {
 export const _internal = {
     composePlayerPrompt,
     VERBATIM_PAYLOAD_FIELDS,
+    UNFINISHED_FINAL_STATE_IDS,
 };
 const runtimeSpec = {
     label: 'REVIEW',
@@ -75,7 +77,7 @@ const runtimeSpec = {
     // time — a literal, never the loading engine's RUNTIME_ABI self-report,
     // which would follow whatever engine loads the module and make the
     // factory's skew check compare that engine with itself.
-    compat: { artifactSchema: 2, runtimeAbi: 1 },
+    compat: { artifactSchema: 3, runtimeAbi: 1 },
     snapshotOptions: snapshotReviewOptions,
     entryEvent: {
         type: 'START_REVIEW',
@@ -103,9 +105,70 @@ const runtimeSpec = {
             label: 'REVIEW-4: Reviewer adjudicates an all-rejected Coder disposition.',
         },
     },
+    outcomeAuthority: {
+        governedPlayerStates: {
+            reviewInitial: {
+                hasFindings: {
+                    fields: { reviewerOutput: 'presentation' },
+                    repositoryDisposition: 'unchanged',
+                },
+                noFindings: {
+                    fields: {},
+                    repositoryDisposition: 'unchanged',
+                },
+                needsBossReply: {
+                    fields: { question: 'presentation' },
+                    repositoryDisposition: 'unchanged',
+                },
+            },
+            addressFindings: {
+                committed: {
+                    fields: { coderOutput: 'presentation' },
+                    repositoryDisposition: 'one-descendant-commit',
+                },
+                rejectedAll: {
+                    fields: { coderOutput: 'presentation' },
+                    repositoryDisposition: 'unchanged',
+                },
+                needsBossReply: {
+                    fields: { question: 'presentation' },
+                    repositoryDisposition: 'deferred',
+                },
+            },
+            reviewAfterCommit: {
+                hasFindings: {
+                    fields: { reviewerOutput: 'presentation' },
+                    repositoryDisposition: 'unchanged',
+                },
+                noFindings: {
+                    fields: {},
+                    repositoryDisposition: 'unchanged',
+                },
+                needsBossReply: {
+                    fields: { question: 'presentation' },
+                    repositoryDisposition: 'unchanged',
+                },
+            },
+            reviewAfterRebuttal: {
+                hasFindings: {
+                    fields: { reviewerOutput: 'presentation' },
+                    repositoryDisposition: 'unchanged',
+                },
+                noFindings: {
+                    fields: {},
+                    repositoryDisposition: 'unchanged',
+                },
+                needsBossReply: {
+                    fields: { question: 'presentation' },
+                    repositoryDisposition: 'unchanged',
+                },
+            },
+        },
+    },
     composePlayerPrompt: (input, promptIdentity) => composePlayerPrompt(input, promptIdentity),
     verbatimPayloadFields: VERBATIM_PAYLOAD_FIELDS,
     controlContextFields: [],
+    unfinishedFinalStateIds: UNFINISHED_FINAL_STATE_IDS,
     transitionEventFields: [
         'callerInput',
         'bossIntent',