@sublang/playbook 9.0.0 → 10.0.0

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

@@ -8,20 +8,23 @@
 //                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,
   type PlaybookPlayerInput,
+  type XStatePlaybookRuntimeFactory,
+  type XStatePlaybookRuntimeConstruction,
   type XStatePromptIdentity,
-  type XStatePlaybookRuntimeSpec,
+  type XStatePlaybookRuntimeSpecV3,
 } from '@sublang/playbook/xstate-runtime';
 import {
   reviewMachine,
   type PlayerInput,
   type ReviewInput,
 } from './review.fsm.js';
+import type { PlaybookHostConstructionCapabilities } from '../code.playbook/playbook-captain.js';
 import type {
   CaptainCallOptions,
   CaptainResult,
@@ -75,6 +78,9 @@ export type {
 };
 
 export type ReviewPlaybookOptions = ReviewInput;
+export type ReviewPlaybookHostCapabilities =
+  PlaybookHostConstructionCapabilities &
+    XStatePlaybookRuntimeConstruction<ReviewPlaybookOptions, object>['hostCapabilities'];
 
 const PLACEHOLDER = /<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>/g;
 const CONTINUATION_PREAMBLE =
@@ -84,6 +90,7 @@ const VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string> = new Set([
   'reviewerOutput',
   'coderOutput',
 ]);
+const UNFINISHED_FINAL_STATE_IDS: ReadonlySet<string> = new Set();
 
 function snapshotReviewOptions(value: unknown): ReviewPlaybookOptions {
   const captured = snapshotJsonValue(value, 'REVIEW runtime options');
@@ -151,6 +158,7 @@ function composePlayerPrompt(
 export const _internal = {
   composePlayerPrompt,
   VERBATIM_PAYLOAD_FIELDS,
+  UNFINISHED_FINAL_STATE_IDS,
 };
 
 const runtimeSpec = {
@@ -159,7 +167,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',
@@ -190,12 +198,73 @@ const runtimeSpec = {
         '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: PlaybookPlayerInput,
     promptIdentity: XStatePromptIdentity,
   ) => composePlayerPrompt(input as PlayerInput, promptIdentity),
   verbatimPayloadFields: VERBATIM_PAYLOAD_FIELDS,
   controlContextFields: [],
+  unfinishedFinalStateIds: UNFINISHED_FINAL_STATE_IDS,
   transitionEventFields: [
     'callerInput',
     'bossIntent',
@@ -203,9 +272,17 @@ const runtimeSpec = {
     'answer',
     'questionId',
   ],
-} satisfies XStatePlaybookRuntimeSpec<ReviewPlaybookOptions>;
+} satisfies XStatePlaybookRuntimeSpecV3<ReviewPlaybookOptions>;
 
-const createPlaybookRuntime: PlaybookRuntimeFactory<ReviewPlaybookOptions> =
-  createXStatePlaybookRuntime(reviewMachine, runtimeSpec);
+const createPlaybookRuntime: XStatePlaybookRuntimeFactory<
+  XStatePlaybookRuntimeConstruction<
+    ReviewPlaybookOptions,
+    ReviewPlaybookHostCapabilities
+  >,
+  3
+> = createXStatePlaybookRuntime<
+  ReviewPlaybookOptions,
+  ReviewPlaybookHostCapabilities
+>(reviewMachine, runtimeSpec);
 
 export default createPlaybookRuntime;

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

@@ -1,4 +1,4 @@
-import { type PlaybookRuntime } from './review.playbook.js';
+import { type ReviewPlaybookHostCapabilities, type PlaybookRuntime } from './review.playbook.js';
 export interface PlaybookSummaryPolicy {
     stateCountLabels: Readonly<Record<string, string>>;
     copyPasteGuardNames: readonly string[];
@@ -12,12 +12,19 @@ export interface ReviewPlaybookRegistryEntry {
     id: 'review';
     command: 'review';
     intent: string;
-    artifactSchema: 2;
+    artifactSchema: 3;
+    runtimeProfile: {
+        readonly kind: 'shared-factory';
+        readonly compat: {
+            readonly artifactSchema: 3;
+            readonly runtimeAbi: number;
+        };
+    };
     requiredRoleIds: readonly ['coder', 'reviewer'];
     concurrentRoleSets: readonly [];
     summaryPolicy: PlaybookSummaryPolicy;
     validateOptions(optionSlice: unknown): ReviewOptions;
-    createRuntime(options: ReviewOptions): PlaybookRuntime;
+    createRuntime(options: ReviewOptions, hostCapabilities: ReviewPlaybookHostCapabilities): PlaybookRuntime;
 }
 export declare const reviewStateCountLabels: {
     readonly reviewInitial: "review round";

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

@@ -48,13 +48,20 @@ export const reviewPlaybookRegistryEntry = {
     id: 'review',
     command: 'review',
     intent: 'review the latest commit until no material correctness or spec findings remain',
-    artifactSchema: 2,
+    artifactSchema: 3,
+    runtimeProfile: Object.freeze({
+        kind: 'shared-factory',
+        compat: createPlaybookRuntime.compat,
+    }),
     requiredRoleIds: ['coder', 'reviewer'],
     concurrentRoleSets: [],
     summaryPolicy: reviewSummaryPolicy,
     validateOptions: validateReviewOptions,
-    createRuntime(options) {
-        return createPlaybookRuntime(options);
+    createRuntime(options, hostCapabilities) {
+        return createPlaybookRuntime({
+            configuredOptions: options,
+            hostCapabilities,
+        });
     },
 };
 export default reviewPlaybookRegistryEntry;

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

@@ -2,6 +2,7 @@
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 
 import createPlaybookRuntime, {
+  type ReviewPlaybookHostCapabilities,
   type PlaybookRuntime,
 } from './review.playbook.js';
 
@@ -20,12 +21,22 @@ export interface ReviewPlaybookRegistryEntry {
   id: 'review';
   command: 'review';
   intent: string;
-  artifactSchema: 2;
+  artifactSchema: 3;
+  runtimeProfile: {
+    readonly kind: 'shared-factory';
+    readonly compat: {
+      readonly artifactSchema: 3;
+      readonly runtimeAbi: number;
+    };
+  };
   requiredRoleIds: readonly ['coder', 'reviewer'];
   concurrentRoleSets: readonly [];
   summaryPolicy: PlaybookSummaryPolicy;
   validateOptions(optionSlice: unknown): ReviewOptions;
-  createRuntime(options: ReviewOptions): PlaybookRuntime;
+  createRuntime(
+    options: ReviewOptions,
+    hostCapabilities: ReviewPlaybookHostCapabilities,
+  ): PlaybookRuntime;
 }
 
 export const reviewStateCountLabels = {
@@ -94,13 +105,20 @@ export const reviewPlaybookRegistryEntry: ReviewPlaybookRegistryEntry = {
   command: 'review',
   intent:
     'review the latest commit until no material correctness or spec findings remain',
-  artifactSchema: 2,
+  artifactSchema: 3,
+  runtimeProfile: Object.freeze({
+    kind: 'shared-factory',
+    compat: createPlaybookRuntime.compat,
+  }),
   requiredRoleIds: ['coder', 'reviewer'],
   concurrentRoleSets: [],
   summaryPolicy: reviewSummaryPolicy,
   validateOptions: validateReviewOptions,
-  createRuntime(options) {
-    return createPlaybookRuntime(options);
+  createRuntime(options, hostCapabilities) {
+    return createPlaybookRuntime({
+      configuredOptions: options,
+      hostCapabilities,
+    });
   },
 };
 

package/slc/gears2fsm.md

@@ -222,12 +222,13 @@ teardown event. The completion rule of
 output clause binds only where Source declares a terminal result, which a
 controller Source does not.
 The controller decision state's direct-Captain result contract discriminates
-the closed action set of DR-029. Its guard discriminants are a stable
-compiler contract, not names the compiler may invent — `respond`, `start`,
-`switch`, `dismiss`, `deliver`, and `runtime` — with each guard's required
-payload fields:
+the closed action set of DR-029 as extended by DR-038. Its guard discriminants
+are a stable compiler contract, not names the compiler may invent — `respond`, `resume`,
+`start`, `switch`, `dismiss`, `deliver`, and `runtime` — with each guard's
+required payload fields:
 
 - `respond` requires `text`;
+- `resume` requires `playbookId` and carries no `input`;
 - `start` and `switch` each require `playbookId` and `input`;
 - `runtime` requires `actionId`;
 - `dismiss` and `deliver` require none — a `deliver` result in particular
@@ -653,7 +654,7 @@ Boss-reply suspension, because its hub already receives every Boss turn and a
 clarifying question to Boss is a `respond` selection over the closed action
 set. The rule below is therefore universal over workflow states and silent
 about that class; in particular, adding `needsBossReply` to the controller
-decision state would add a seventh outcome to a closed six-action contract
+decision state would add an eighth outcome to a closed seven-action contract
 whose guard discriminants [Setup](#setup) fixes, and is nonconformant.
 There is no source-level opt-in annotation and no `needsBossReply` result metadata in GEARS output.
 The FSM compiler shall preserve the GEARS blockquote as the state's domain `prompt` body and shall not inject any Boss-question instruction into `invoke.input.prompt`.