@sublang/playbook 12.2.1 → 12.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "12.2.1",
+  "version": "12.3.0",
   "type": "module",
   "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, REVIEW, DECIDE, and DEV workflows driven by GEARS specs.",
   "license": "Apache-2.0",

package/reference/sdlc/code.playbook/bin/launch-config.js

@@ -28,7 +28,10 @@ import {
   stringify as stringifyYaml,
 } from "yaml";
 import { loadTmuxPlayConfig } from "@sublang/cligent/tmux-play";
-import { defaultCaptainSessionsDir } from "./session-store.js";
+import {
+  defaultCaptainSessionsDir,
+  isCanonicalLocalRoleId,
+} from "./session-store.js";
 
 const here = dirname(fileURLToPath(import.meta.url));
 const DEFAULT_TEMPLATE_PATH = resolve(
@@ -53,7 +56,6 @@ const PLAYBOOK_TOP_LEVEL_KEYS = new Set([
 const RESERVED_CAPTAIN_PLAYBOOK_ID = "captain";
 const RESERVED_CAPTAIN_ROLE_ID = "captain";
 const PLAYER_ID_PATTERN = /^[a-z][a-z0-9_-]*(?:\.[a-z][a-z0-9_-]*)*$/;
-const ROLE_ID_PATTERN = /^[a-z][a-z0-9_-]*$/;
 
 // PBCLI-26: split ordered `--with <path>` pairs out of an argument vector.
 // The returned arrays are new values; the caller's vector is never changed.
@@ -2060,8 +2062,11 @@ function assertPlayerId(value, path) {
 }
 
 function assertRoleId(value, path) {
-  if (typeof value !== "string" || !ROLE_ID_PATTERN.test(value)) {
-    throw new Error(`${path} must use a canonical lowercase local role id`);
+  if (!isCanonicalLocalRoleId(value)) {
+    throw new Error(
+      `${path} must be a canonical lowercase local role id ` +
+        "(the role name lowercased, no whitespace)",
+    );
   }
   if (value === RESERVED_CAPTAIN_ROLE_ID) {
     throw new Error(`${path} uses reserved local role id "captain"`);
@@ -2077,7 +2082,7 @@ function invalidManifestRoles(value) {
   if (new Set(canonical).size !== canonical.length) {
     return "contains roles that collide after canonical lowercase derivation";
   }
-  const invalid = value.find((role) => !ROLE_ID_PATTERN.test(role));
+  const invalid = value.find((role) => !isCanonicalLocalRoleId(role));
   if (invalid !== undefined) {
     return `contains noncanonical role ${JSON.stringify(invalid)}`;
   }
@@ -2099,8 +2104,7 @@ function invalidConcurrentRoleSets(value, requiredRoleIds) {
     if (
       set.some(
         (role) =>
-          typeof role !== "string" ||
-          !ROLE_ID_PATTERN.test(role) ||
+          !isCanonicalLocalRoleId(role) ||
           role === RESERVED_CAPTAIN_ROLE_ID ||
           !required.has(role),
       )

package/reference/sdlc/code.playbook/bin/repository-effects.js

@@ -1952,9 +1952,9 @@ async function releaseRepositoryClaim(claim, primaryError) {
   }
 }
 
-// A host binds the governed worktree identity for each durable call — fixed
-// at construction for the Captain host, resolved afresh from `cwd` for the
-// worktree host capability — and derives the schema-3 authority naming it.
+// A host binds the governed worktree identity for each durable call —
+// resolved afresh from `cwd` by both the Captain host and the worktree host
+// capability — and derives the schema-3 authority naming it.
 function bindHostWorktree(host) {
   return host.resolveIdentity().then((identity) => ({
     identity,
@@ -2978,33 +2978,43 @@ export async function createRepositoryEffectCapabilities({
   await sessionLease.assertOwner();
   const createdWriteAhead = await createWriteAhead(sessionLease);
   const ledgerService = assertEffectLedgerService(createdWriteAhead);
-  const identity = await resolveCanonicalGitWorktree(cwd);
+  // The governed worktree is bound afresh from `cwd` at every governed call
+  // and observation, so a working directory that is not a repository yet is
+  // governed from launch as its own prospective root and the `git init` a
+  // workflow's own setup step runs there keeps that one identity.
+  const resolveIdentity = async () => (await resolveGovernedWorktree(cwd)).identity;
+  const identity = await resolveIdentity();
   await sessionLease.assertOwner();
   const coordinator = createRepositoryEffectCoordinator();
 
   const capabilities = schema3Entries.map(
     ({ playbookId, requiredRoleIds, concurrentRoleSets }) => {
-      const authority = deepFreeze({
-        playbookId,
-        artifactSchema: 3,
-        cwd,
-        sessionId,
-        leaseOwnerToken: sessionLease.ownerToken,
-        canonicalWorktree: identity,
-        requiredRoleIds,
-        concurrentRoleSets,
-      });
+      const authorityNaming = (canonicalWorktree) =>
+        deepFreeze({
+          playbookId,
+          artifactSchema: 3,
+          cwd,
+          sessionId,
+          leaseOwnerToken: sessionLease.ownerToken,
+          canonicalWorktree,
+          requiredRoleIds,
+          concurrentRoleSets,
+        });
+      const authority = authorityNaming(identity);
       const host = Object.freeze({
-        resolveIdentity: async () => identity,
-        authorityFor: () => authority,
+        resolveIdentity,
+        authorityFor: (canonicalWorktree) =>
+          isDeepStrictEqual(canonicalWorktree, identity)
+            ? authority
+            : authorityNaming(canonicalWorktree),
       });
       const observe = async (options = {}) => {
         rejectBoundRepositoryOverride(options, 'observe', ['cwd']);
-        return observeResolvedWorktree(identity, options);
+        return observeGovernedWorktree(await resolveGovernedWorktree(cwd), options);
       };
       const acquire = async (options = {}) => {
         rejectBoundRepositoryOverride(options, 'acquire', ['cwd']);
-        return coordinator.acquire(identity.worktree, options);
+        return coordinator.acquire(cwd, options);
       };
       const runExclusive = async (options) => {
         return runDurableExclusive({
@@ -3139,11 +3149,11 @@ async function assertExistingDirectory(cwd, label) {
 // DR-046: the lease-free worktree capability an embedding host constructs
 // through `@sublang/playbook/host-capabilities`. It runs the same claim,
 // observation, receipt, completion, and deferred-operation path as the
-// Captain-hosted capability above, over one host-owned in-memory ledger.
-// Unlike that capability, it binds its worktree lazily: `cwd` need not be a
-// repository yet, and every governed call and observation re-resolves the
-// governed worktree of `cwd`, so a `git init` there — inside a governed call
-// or between calls — is observed rather than hidden behind a stale identity.
+// Captain-hosted capability above, over one host-owned in-memory ledger, and
+// binds its worktree the same lazy way: `cwd` need not be a repository yet,
+// and every governed call and observation re-resolves the governed worktree
+// of `cwd`, so a `git init` there — inside a governed call or between calls —
+// is observed rather than hidden behind a stale identity.
 export async function createWorktreeHostCapabilities(options = {}) {
   if (!isPlainObject(options)) {
     throw new TypeError('worktree host capability options must be an object');

package/reference/sdlc/code.playbook/bin/session-store.js

@@ -57,8 +57,22 @@ export const CAPTAIN_SESSION_STRUCTURAL_PROJECTION_SCHEMA_VERSION = 1;
 export const CAPTAIN_SESSION_EXECUTION_PROJECTION_SCHEMA_VERSION = 2;
 
 const PLAYER_ID_PATTERN = /^[a-z][a-z0-9_-]*(?:\.[a-z][a-z0-9_-]*)*$/;
-const ROLE_ID_PATTERN = /^[a-z][a-z0-9_-]*$/;
+const ROLE_ID_WHITESPACE_OR_CONTROL = /[\s\p{Cc}]/u;
 const RESERVED_ID = 'captain';
+
+// PBCLI-4: a local role id is its source role name lowercased by Unicode case
+// mapping — nonempty, free of whitespace and control characters, and equal to
+// its own lowercase form. The rule restricts neither script nor alphabet, so
+// `coder`, `编码者`, and `作者` are canonical while `Coder` is not. Callers
+// enforce the reserved `captain` name separately.
+export function isCanonicalLocalRoleId(value) {
+  return (
+    typeof value === 'string' &&
+    value.length > 0 &&
+    value === value.toLowerCase() &&
+    !ROLE_ID_WHITESPACE_OR_CONTROL.test(value)
+  );
+}
 const HOST_CAPABILITIES_OPTION_KEY = 'hostCapabilities';
 const KNOWN_ADAPTERS = new Set(KNOWN_PLAYER_ADAPTERS);
 
@@ -5080,10 +5094,7 @@ function validateRoleIds(value, path) {
   if (
     !Array.isArray(value) ||
     value.some(
-      (roleId) =>
-        typeof roleId !== 'string' ||
-        !ROLE_ID_PATTERN.test(roleId) ||
-        roleId === RESERVED_ID,
+      (roleId) => !isCanonicalLocalRoleId(roleId) || roleId === RESERVED_ID,
     ) ||
     new Set(value).size !== value.length
   ) {

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

@@ -77,6 +77,18 @@ function playbookMeta(stateId, role) {
         },
     };
 }
+// DR-048: a final state additionally declares whether its outcome means the
+// workflow succeeded or failed, so a caller learns that from the machine
+// rather than from CODE's output fields.
+function terminalMeta(stateId, terminal) {
+    return {
+        playbook: {
+            stateId,
+            description: STATE_DESCRIPTIONS[stateId],
+            terminal,
+        },
+    };
+}
 function isRecord(value) {
     if (value === null || typeof value !== 'object' || Array.isArray(value)) {
         return false;
@@ -206,6 +218,16 @@ function nestedResultFromError(error) {
     const result = error.result;
     return isRecord(result) ? result : undefined;
 }
+function isFailureTerminalRecord(value) {
+    if (!isRecord(value))
+        return false;
+    const allowed = new Set(['stateId', 'kind', 'description']);
+    return (Reflect.ownKeys(value).every((key) => typeof key === 'string' && allowed.has(key)) &&
+        isNonEmptyString(value.stateId) &&
+        value.kind === 'failure' &&
+        (!Object.prototype.hasOwnProperty.call(value, 'description') ||
+            typeof value.description === 'string'));
+}
 function normalizedReviewFailure(error) {
     const result = nestedResultFromError(error);
     if (result === undefined)
@@ -215,10 +237,12 @@ function normalizedReviewFailure(error) {
         'playbookId',
         'childSessionId',
         'state',
-        'error',
+        ...(result.status === 'ok' ? ['output', 'terminal'] : ['error']),
     ]);
     if (Reflect.ownKeys(result).some((key) => typeof key !== 'string' || !allowed.has(key)) ||
-        (result.status !== 'aborted' && result.status !== 'error') ||
+        (result.status !== 'aborted' &&
+            result.status !== 'error' &&
+            result.status !== 'ok') ||
         result.playbookId !== 'review') {
         return undefined;
     }
@@ -230,6 +254,19 @@ function normalizedReviewFailure(error) {
         !isPlaybookState(result.state)) {
         return undefined;
     }
+    if (result.status === 'ok') {
+        if (!Object.prototype.hasOwnProperty.call(result, 'terminal') ||
+            !isFailureTerminalRecord(result.terminal) ||
+            !isNonEmptyString(result.childSessionId)) {
+            return undefined;
+        }
+        return {
+            status: 'ok',
+            ...(result.output === undefined
+                ? {}
+                : { output: result.output }),
+        };
+    }
     let normalizedError;
     if (Object.prototype.hasOwnProperty.call(result, 'error')) {
         if (!isRecord(result.error))
@@ -274,8 +311,9 @@ function compactError(value) {
 function authoredReviewError(event) {
     const outer = isRecord(event) ? event.error : undefined;
     const failure = normalizedReviewFailure(outer);
-    if (failure?.error !== undefined)
+    if (failure !== undefined && failure.status !== 'ok' && failure.error) {
         return failure.error;
+    }
     if (failure?.status === 'aborted') {
         return { name: 'AbortError', message: 'REVIEW was aborted.' };
     }
@@ -787,13 +825,13 @@ export const codingMachine = machineSetup.createMachine({
         reportedReviewFailure: {
             id: 'reportedReviewFailure',
             description: STATE_DESCRIPTIONS.reportedReviewFailure,
-            meta: playbookMeta('reportedReviewFailure'),
+            meta: terminalMeta('reportedReviewFailure', 'failure'),
             type: 'final',
         },
         done: {
             id: 'done',
             description: STATE_DESCRIPTIONS.done,
-            meta: playbookMeta('done'),
+            meta: terminalMeta('done', 'success'),
             type: 'final',
         },
     },

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

@@ -241,6 +241,22 @@ function playbookMeta<StateId extends keyof typeof STATE_DESCRIPTIONS>(
   };
 }
 
+// DR-048: a final state additionally declares whether its outcome means the
+// workflow succeeded or failed, so a caller learns that from the machine
+// rather than from CODE's output fields.
+function terminalMeta<StateId extends keyof typeof STATE_DESCRIPTIONS>(
+  stateId: StateId,
+  terminal: 'success' | 'failure',
+) {
+  return {
+    playbook: {
+      stateId,
+      description: STATE_DESCRIPTIONS[stateId],
+      terminal,
+    },
+  };
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   if (value === null || typeof value !== 'object' || Array.isArray(value)) {
     return false;
@@ -419,10 +435,32 @@ function nestedResultFromError(error: unknown): Record<string, unknown> | undefi
   return isRecord(result) ? result : undefined;
 }
 
-type AuthoredReviewFailure = {
-  readonly status: 'aborted' | 'error';
-  readonly error?: CompactError;
-};
+type AuthoredReviewFailure =
+  | {
+      readonly status: 'aborted' | 'error';
+      readonly error?: CompactError;
+    }
+  // DR-048: a child that completed at an authored failure terminal. The
+  // bridge rejects it through the same error path, so CODE recognizes the
+  // failure from REVIEW's own machine and never from its output fields.
+  | {
+      readonly status: 'ok';
+      readonly output?: JsonValue;
+    };
+
+function isFailureTerminalRecord(value: unknown): boolean {
+  if (!isRecord(value)) return false;
+  const allowed = new Set(['stateId', 'kind', 'description']);
+  return (
+    Reflect.ownKeys(value).every(
+      (key) => typeof key === 'string' && allowed.has(key),
+    ) &&
+    isNonEmptyString(value.stateId) &&
+    value.kind === 'failure' &&
+    (!Object.prototype.hasOwnProperty.call(value, 'description') ||
+      typeof value.description === 'string')
+  );
+}
 
 function normalizedReviewFailure(
   error: unknown,
@@ -434,13 +472,15 @@ function normalizedReviewFailure(
     'playbookId',
     'childSessionId',
     'state',
-    'error',
+    ...(result.status === 'ok' ? ['output', 'terminal'] : ['error']),
   ]);
   if (
     Reflect.ownKeys(result).some(
       (key) => typeof key !== 'string' || !allowed.has(key),
     ) ||
-    (result.status !== 'aborted' && result.status !== 'error') ||
+    (result.status !== 'aborted' &&
+      result.status !== 'error' &&
+      result.status !== 'ok') ||
     result.playbookId !== 'review'
   ) {
     return undefined;
@@ -457,6 +497,21 @@ function normalizedReviewFailure(
   ) {
     return undefined;
   }
+  if (result.status === 'ok') {
+    if (
+      !Object.prototype.hasOwnProperty.call(result, 'terminal') ||
+      !isFailureTerminalRecord(result.terminal) ||
+      !isNonEmptyString(result.childSessionId)
+    ) {
+      return undefined;
+    }
+    return {
+      status: 'ok',
+      ...(result.output === undefined
+        ? {}
+        : { output: result.output as JsonValue }),
+    };
+  }
   let normalizedError: CompactError | undefined;
   if (Object.prototype.hasOwnProperty.call(result, 'error')) {
     if (!isRecord(result.error)) return undefined;
@@ -507,7 +562,9 @@ function compactError(value: unknown): CompactError {
 function authoredReviewError(event: unknown): CompactError {
   const outer = isRecord(event) ? event.error : undefined;
   const failure = normalizedReviewFailure(outer);
-  if (failure?.error !== undefined) return failure.error;
+  if (failure !== undefined && failure.status !== 'ok' && failure.error) {
+    return failure.error;
+  }
   if (failure?.status === 'aborted') {
     return { name: 'AbortError', message: 'REVIEW was aborted.' };
   }
@@ -1052,13 +1109,13 @@ export const codingMachine = machineSetup.createMachine({
     reportedReviewFailure: {
       id: 'reportedReviewFailure',
       description: STATE_DESCRIPTIONS.reportedReviewFailure,
-      meta: playbookMeta('reportedReviewFailure'),
+      meta: terminalMeta('reportedReviewFailure', 'failure'),
       type: 'final',
     },
     done: {
       id: 'done',
       description: STATE_DESCRIPTIONS.done,
-      meta: playbookMeta('done'),
+      meta: terminalMeta('done', 'success'),
       type: 'final',
     },
   },

package/reference/sdlc/code.playbook/playbook-captain.js

@@ -60,8 +60,21 @@ const SHELL_FSM_TOPIC = 'playbook.captain.fsm.state';
 const INTERNAL_CAPTAIN_ID = 'captain';
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const PLAYER_ID_PATTERN = /^[a-z][a-z0-9_-]*(?:\.[a-z][a-z0-9_-]*)*$/;
-const ROLE_ID_PATTERN = /^[a-z][a-z0-9_-]*$/;
+const ROLE_ID_WHITESPACE_OR_CONTROL = /[\s\p{Cc}]/u;
 const HOST_CAPABILITIES_OPTION_KEY = 'hostCapabilities';
+// PBCLI-4: a local role id is its source role name lowercased by Unicode case
+// mapping — nonempty, free of whitespace and control characters, and equal to
+// its own lowercase form. The rule restricts neither script nor alphabet, so
+// `coder`, `编码者`, and `作者` are canonical while `Coder` is not. Callers
+// enforce the reserved `captain` name separately. The CLI host owns the same
+// predicate in `bin/session-store.js`; that private module already imports
+// this one, so the text is repeated here rather than cycled back.
+function isCanonicalLocalRoleId(value) {
+    return (typeof value === 'string' &&
+        value.length > 0 &&
+        value === value.toLowerCase() &&
+        !ROLE_ID_WHITESPACE_OR_CONTROL.test(value));
+}
 const UNRESOLVED_EFFECT_RECONCILIATION_ACTION_ID = 'reconcile:unresolved-effect';
 const UNRESOLVED_EFFECT_ABANDONMENT_ACTION_ID = 'abandon:unresolved-effect';
 // The fixed machine-syntax guard of a player's Boss-question suspension
@@ -685,9 +698,7 @@ function isValidRegistryEntry(value, artifactSchema) {
         return false;
     const e = value;
     if (!Array.isArray(e.requiredRoleIds) ||
-        e.requiredRoleIds.some((role) => typeof role !== 'string' ||
-            !ROLE_ID_PATTERN.test(role) ||
-            role === INTERNAL_CAPTAIN_ID) ||
+        e.requiredRoleIds.some((role) => !isCanonicalLocalRoleId(role) || role === INTERNAL_CAPTAIN_ID) ||
         new Set(e.requiredRoleIds).size !== e.requiredRoleIds.length ||
         !Array.isArray(e.concurrentRoleSets)) {
         return false;
@@ -911,7 +922,7 @@ function snapshotPlayerSessions(value, path) {
 function snapshotFrameRoleBindings(value, path) {
     const bindings = snapshotRecord(value, path);
     return Object.fromEntries(Object.entries(bindings).map(([roleId, raw]) => {
-        if (!ROLE_ID_PATTERN.test(roleId) || roleId === INTERNAL_CAPTAIN_ID) {
+        if (!isCanonicalLocalRoleId(roleId) || roleId === INTERNAL_CAPTAIN_ID) {
             throw new TypeError(`${path} has invalid role id ${JSON.stringify(roleId)}`);
         }
         const playerId = snapshotString(raw, `${path}.${roleId}`);
@@ -3305,6 +3316,12 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                 childSessionId: frame.sessionId,
                 state: result.state,
                 ...(result.output !== undefined ? { output: result.output } : {}),
+                // DR-048: the child runtime read this record from its own artifact;
+                // the host relays it unchanged so the caller's bridge can route a
+                // failure terminal without knowing the callee's output fields.
+                ...(result.terminal !== undefined
+                    ? { terminal: result.terminal }
+                    : {}),
             };
         }
         if (result.outcome === 'aborted') {

package/reference/sdlc/code.playbook/playbook-captain.ts

@@ -549,8 +549,24 @@ const INTERNAL_CAPTAIN_ID = 'captain';
 const UUID_PATTERN =
   /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const PLAYER_ID_PATTERN = /^[a-z][a-z0-9_-]*(?:\.[a-z][a-z0-9_-]*)*$/;
-const ROLE_ID_PATTERN = /^[a-z][a-z0-9_-]*$/;
+const ROLE_ID_WHITESPACE_OR_CONTROL = /[\s\p{Cc}]/u;
 const HOST_CAPABILITIES_OPTION_KEY = 'hostCapabilities';
+
+// PBCLI-4: a local role id is its source role name lowercased by Unicode case
+// mapping — nonempty, free of whitespace and control characters, and equal to
+// its own lowercase form. The rule restricts neither script nor alphabet, so
+// `coder`, `编码者`, and `作者` are canonical while `Coder` is not. Callers
+// enforce the reserved `captain` name separately. The CLI host owns the same
+// predicate in `bin/session-store.js`; that private module already imports
+// this one, so the text is repeated here rather than cycled back.
+function isCanonicalLocalRoleId(value: unknown): value is string {
+  return (
+    typeof value === 'string' &&
+    value.length > 0 &&
+    value === value.toLowerCase() &&
+    !ROLE_ID_WHITESPACE_OR_CONTROL.test(value)
+  );
+}
 const UNRESOLVED_EFFECT_RECONCILIATION_ACTION_ID =
   'reconcile:unresolved-effect';
 const UNRESOLVED_EFFECT_ABANDONMENT_ACTION_ID = 'abandon:unresolved-effect';
@@ -1452,9 +1468,7 @@ function isValidRegistryEntry(
     !Array.isArray(e.requiredRoleIds) ||
     e.requiredRoleIds.some(
       (role) =>
-        typeof role !== 'string' ||
-        !ROLE_ID_PATTERN.test(role) ||
-        role === INTERNAL_CAPTAIN_ID,
+        !isCanonicalLocalRoleId(role) || role === INTERNAL_CAPTAIN_ID,
     ) ||
     new Set(e.requiredRoleIds).size !== e.requiredRoleIds.length ||
     !Array.isArray(e.concurrentRoleSets)
@@ -1773,7 +1787,7 @@ function snapshotFrameRoleBindings(
   const bindings = snapshotRecord(value, path);
   return Object.fromEntries(
     Object.entries(bindings).map(([roleId, raw]) => {
-      if (!ROLE_ID_PATTERN.test(roleId) || roleId === INTERNAL_CAPTAIN_ID) {
+      if (!isCanonicalLocalRoleId(roleId) || roleId === INTERNAL_CAPTAIN_ID) {
         throw new TypeError(`${path} has invalid role id ${JSON.stringify(roleId)}`);
       }
       const playerId = snapshotString(raw, `${path}.${roleId}`);
@@ -5177,6 +5191,12 @@ export function createPlaybookCaptainShell(
         childSessionId: frame.sessionId,
         state: result.state,
         ...(result.output !== undefined ? { output: result.output } : {}),
+        // DR-048: the child runtime read this record from its own artifact;
+        // the host relays it unchanged so the caller's bridge can route a
+        // failure terminal without knowing the callee's output fields.
+        ...(result.terminal !== undefined
+          ? { terminal: result.terminal }
+          : {}),
       };
     }
     if (result.outcome === 'aborted') {

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

@@ -960,6 +960,9 @@ export const decideMachine = setup({
                 playbook: {
                     stateId: 'reportedReviewFailure',
                     description: 'DECIDE reports REVIEW’s failure and its last commit.',
+                    // DR-048: this final state means the workflow failed, so a caller
+                    // learns that from the machine rather than from DECIDE's output.
+                    terminal: 'failure',
                 },
             },
         },
@@ -971,6 +974,7 @@ export const decideMachine = setup({
                 playbook: {
                     stateId: 'done',
                     description: 'DECIDE completed with an approved commit.',
+                    terminal: 'success',
                 },
             },
         },

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

@@ -1233,6 +1233,9 @@ export const decideMachine = setup({
         playbook: {
           stateId: 'reportedReviewFailure',
           description: 'DECIDE reports REVIEW’s failure and its last commit.',
+          // DR-048: this final state means the workflow failed, so a caller
+          // learns that from the machine rather than from DECIDE's output.
+          terminal: 'failure',
         },
       },
     },
@@ -1244,6 +1247,7 @@ export const decideMachine = setup({
         playbook: {
           stateId: 'done',
           description: 'DECIDE completed with an approved commit.',
+          terminal: 'success',
         },
       },
     },

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

@@ -19,7 +19,7 @@ import { randomUUID } from 'node:crypto';
 import PQueue from 'p-queue';
 import { createActor, fromPromise } from 'xstate';
 import { createAcceptedOutcomeConsumer, } from '../../../src/accepted-outcome.js';
-import { assertJsonSafe, assertPlaybookEffectLedger, assertPlaybookRuntimeSnapshot, combineAbortSignals, createNestedPlaybookBridge, detachPersistedMachineSnapshot, normalizeError, normalizePlaybookSnapshot, PlaybookSemanticCandidateStructureError, reconcilePlaybookSemanticEvidence, renderGovernedOutcomeContract, snapshotJsonValue, snapshotPlaybookSession, validatePlayerResult, waitForPlaybookQuiescence, } from '../../../src/xstate-runtime.js';
+import { assertJsonSafe, assertPlaybookEffectLedger, assertPlaybookRuntimeSnapshot, combineAbortSignals, createNestedPlaybookBridge, detachPersistedMachineSnapshot, normalizeError, normalizePlaybookSnapshot, PlaybookSemanticCandidateStructureError, reconcilePlaybookSemanticEvidence, renderGovernedOutcomeContract, snapshotJsonValue, snapshotPlaybookSession, terminalOutcomesFromMachine, validatePlayerResult, waitForPlaybookQuiescence, } from '../../../src/xstate-runtime.js';
 import decideMachine from './decide.fsm.js';
 function snapshotDecideRuntimeOptions(value) {
     const captured = snapshotJsonValue(value, 'DECIDE runtime options');
@@ -54,6 +54,9 @@ function authoredStateDescriptions(states) {
     return Object.freeze(descriptions);
 }
 const STATE_DESCRIPTIONS = authoredStateDescriptions(decideMachine.config.states);
+// DR-048: each root final state's compiled terminal kind, read from this
+// artifact through the shared reader the factory-backed runtimes use.
+const TERMINAL_KINDS = terminalOutcomesFromMachine(decideMachine, 'DECIDE');
 const ROLE_STATES = [
     { stateId: 'askCoderProposal', role: 'coder', sourceItem: 'DECIDE-1' },
     {
@@ -2814,18 +2817,33 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
             const output = snapshot.output;
             if (output !== undefined)
                 assertJsonSafe(output, 'terminal output');
-            const stateDescription = state.activeStateIds.includes('done')
-                ? STATE_DESCRIPTIONS.done
+            const finalStateId = state.activeStateIds.includes('done')
+                ? 'done'
                 : state.activeStateIds.includes('reportedReviewFailure')
-                    ? STATE_DESCRIPTIONS.reportedReviewFailure
+                    ? 'reportedReviewFailure'
                     : undefined;
-            if (stateDescription === undefined) {
+            const stateDescription = finalStateId === undefined
+                ? undefined
+                : STATE_DESCRIPTIONS[finalStateId];
+            if (finalStateId === undefined || stateDescription === undefined) {
                 throw new Error('decide runtime: completed actor has no authored final-state description');
             }
+            // DR-048: the reached final state's compiled terminal kind, read from
+            // this artifact exactly as the shared factory reads it.
+            const terminalKind = TERMINAL_KINDS.get(finalStateId);
             return {
                 outcome: 'terminal',
                 state,
                 stateDescription,
+                ...(terminalKind === undefined
+                    ? {}
+                    : {
+                        terminal: {
+                            stateId: finalStateId,
+                            kind: terminalKind,
+                            description: stateDescription,
+                        },
+                    }),
                 ...(output === undefined ? {} : { output }),
             };
         }