@sublang/playbook 7.0.0 → 9.0.0

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

@@ -8,18 +8,20 @@ export type PendingBossQuestion = {
     readonly questionId: 'runFirstPhase' | 'runIrTask';
     readonly resumeStateId: 'runFirstPhase' | 'runIrTask';
     readonly sourceItem: 'CODE-1' | 'CODE-3';
-    readonly player: 'Coder';
+    readonly asker: {
+        readonly kind: 'role';
+        readonly roleId: 'coder';
+    };
     readonly question: string;
 };
 export type PlayerInput = {
     readonly stateId: 'runFirstPhase' | 'runIrTask';
-    readonly player: 'Coder';
+    readonly role: 'coder';
     readonly sourceItem: 'CODE-1' | 'CODE-3';
     readonly prompt: string;
     readonly result: Readonly<Record<string, string>>;
     readonly callerInput: string;
     readonly runResults: string;
-    readonly coderPlayer: string;
     readonly irNumber?: string;
     readonly irTask?: string;
     readonly pendingBossQuestion?: PendingBossQuestion;
@@ -77,11 +79,9 @@ export type CodePlaybookOutput = {
     readonly error: CompactError;
 };
 export type CodingInput = {
-    readonly coderPlayer?: string;
     readonly runResults?: string;
 };
 export type CodingContext = {
-    readonly coderPlayer: string;
     readonly runResults: string;
     readonly callerInput?: string;
     readonly coderOutput?: string;
@@ -202,7 +202,7 @@ export declare const codingMachine: import("xstate").StateMachine<CodingContext,
 } | {
     type: "resumesIrTask";
     params: unknown;
-}, never, "done" | "failed" | "awaitBossReply" | "ready" | "runFirstPhase" | "reviewFirstCommit" | "runIrTask" | "reviewIrTask", string, CodingInput, {
+}, never, "done" | "failed" | "awaitBossReply" | "ready" | "runFirstPhase" | "reviewFirstCommit" | "runIrTask" | "reviewIrTask" | "reportedReviewFailure", string, CodingInput, {
     readonly status: "complete";
     /** Exact identity of the latest CODE-owned commit. */
     readonly lastCodeCommit: string;
@@ -239,6 +239,9 @@ export declare const codingMachine: import("xstate").StateMachine<CodingContext,
         readonly failed: {
             id: "failed";
         };
+        readonly reportedReviewFailure: {
+            id: "reportedReviewFailure";
+        };
         readonly done: {
             id: "done";
         };

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

@@ -27,7 +27,7 @@ export function enumeratePlayerStates(machine) {
         if (invoke?.src !== 'player' || invoke.input === undefined)
             return [];
         const getInput = (context) => invoke.input?.({ context });
-        const input = getInput({ coderPlayer: 'Coder', runResults: '' });
+        const input = getInput({ runResults: '' });
         return [
             {
                 stateId,
@@ -47,7 +47,7 @@ export function enumerateNestedPlaybookStates(machine) {
         if (invoke?.src !== 'playbook' || invoke.input === undefined)
             return [];
         const getInput = (context) => invoke.input?.({ context });
-        const input = getInput({ coderPlayer: 'Coder', runResults: '' });
+        const input = getInput({ runResults: '' });
         return [
             {
                 stateId,

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

@@ -92,7 +92,7 @@ export function enumeratePlayerStates(
     if (invoke?.src !== 'player' || invoke.input === undefined) return [];
     const getInput = (context: CodingContext): PlayerInput =>
       invoke.input?.({ context }) as PlayerInput;
-    const input = getInput({ coderPlayer: 'Coder', runResults: '' });
+    const input = getInput({ runResults: '' });
     return [
       {
         stateId,
@@ -116,7 +116,7 @@ export function enumerateNestedPlaybookStates(
     if (invoke?.src !== 'playbook' || invoke.input === undefined) return [];
     const getInput = (context: CodingContext): PlaybookInput =>
       invoke.input?.({ context }) as PlaybookInput;
-    const input = getInput({ coderPlayer: 'Coder', runResults: '' });
+    const input = getInput({ runResults: '' });
     return [
       {
         stateId,

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

@@ -53,14 +53,15 @@ const STATE_DESCRIPTIONS = {
     reviewIrTask: 'The REVIEW playbook is checking the latest task commit.',
     awaitBossReply: 'Waiting for Boss to answer Coder.',
     failed: 'The coding workflow failed and is waiting for a new coding intent.',
+    reportedReviewFailure: 'The coding workflow reported a REVIEW failure and the last code-owned commit.',
     done: 'The coding workflow completed after REVIEW found no unsettled findings.',
 };
-function playbookMeta(stateId, player) {
+function playbookMeta(stateId, role) {
     return {
         playbook: {
             stateId,
             description: STATE_DESCRIPTIONS[stateId],
-            ...(player === undefined ? {} : { player }),
+            ...(role === undefined ? {} : { role }),
         },
     };
 }
@@ -324,7 +325,6 @@ const machineSetup = setup({
             if (event.type !== 'START_CODE')
                 return {};
             return {
-                coderPlayer: context.coderPlayer,
                 runResults: context.runResults,
                 callerInput: event.callerInput,
                 coderOutput: undefined,
@@ -389,7 +389,7 @@ const machineSetup = setup({
                     questionId: stateId,
                     resumeStateId: stateId,
                     sourceItem: stateId === 'runFirstPhase' ? 'CODE-1' : 'CODE-3',
-                    player: 'Coder',
+                    asker: { kind: 'role', roleId: 'coder' },
                     question,
                 },
                 bossReply: undefined,
@@ -430,7 +430,6 @@ export const codingMachine = machineSetup.createMachine({
     id: 'code',
     initial: 'ready',
     context: ({ input }) => ({
-        coderPlayer: isNonEmptyString(input.coderPlayer) ? input.coderPlayer : 'Coder',
         runResults: typeof input.runResults === 'string' ? input.runResults : '',
     }),
     output: ({ context }) => {
@@ -465,19 +464,18 @@ export const codingMachine = machineSetup.createMachine({
         runFirstPhase: {
             id: 'runFirstPhase',
             description: STATE_DESCRIPTIONS.runFirstPhase,
-            meta: playbookMeta('runFirstPhase', 'Coder'),
+            meta: playbookMeta('runFirstPhase', 'coder'),
             tags: ['playbook.busy'],
             invoke: {
                 src: 'player',
                 input: ({ context }) => ({
                     stateId: 'runFirstPhase',
-                    player: 'Coder',
+                    role: 'coder',
                     sourceItem: 'CODE-1',
                     prompt: FIRST_PHASE_PROMPT,
                     result: FIRST_PHASE_RESULTS,
                     callerInput: context.callerInput ?? '',
                     runResults: context.runResults,
-                    coderPlayer: context.coderPlayer,
                     ...(context.pendingBossQuestion === undefined
                         ? {}
                         : { pendingBossQuestion: context.pendingBossQuestion }),
@@ -533,14 +531,14 @@ export const codingMachine = machineSetup.createMachine({
                         target: 'runIrTask',
                     },
                     {
-                        target: 'done',
+                        target: 'reportedReviewFailure',
                         actions: 'completeWithInvalidReviewOutput',
                     },
                 ],
                 onError: [
                     {
                         guard: 'authoredReviewFailure',
-                        target: 'done',
+                        target: 'reportedReviewFailure',
                         actions: 'completeWithReviewFailure',
                     },
                     { target: 'failed', actions: 'rememberActorError' },
@@ -550,19 +548,18 @@ export const codingMachine = machineSetup.createMachine({
         runIrTask: {
             id: 'runIrTask',
             description: STATE_DESCRIPTIONS.runIrTask,
-            meta: playbookMeta('runIrTask', 'Coder'),
+            meta: playbookMeta('runIrTask', 'coder'),
             tags: ['playbook.busy'],
             invoke: {
                 src: 'player',
                 input: ({ context }) => ({
                     stateId: 'runIrTask',
-                    player: 'Coder',
+                    role: 'coder',
                     sourceItem: 'CODE-3',
                     prompt: IR_TASK_PROMPT,
                     result: IR_TASK_RESULTS,
                     callerInput: context.callerInput ?? '',
                     runResults: context.runResults,
-                    coderPlayer: context.coderPlayer,
                     ...(context.irNumber === undefined
                         ? {}
                         : { irNumber: context.irNumber }),
@@ -623,14 +620,14 @@ export const codingMachine = machineSetup.createMachine({
                         actions: 'completeSuccessfully',
                     },
                     {
-                        target: 'done',
+                        target: 'reportedReviewFailure',
                         actions: 'completeWithInvalidReviewOutput',
                     },
                 ],
                 onError: [
                     {
                         guard: 'authoredReviewFailure',
-                        target: 'done',
+                        target: 'reportedReviewFailure',
                         actions: 'completeWithReviewFailure',
                     },
                     { target: 'failed', actions: 'rememberActorError' },
@@ -674,6 +671,12 @@ export const codingMachine = machineSetup.createMachine({
                 START_CODE: { target: 'runFirstPhase', actions: 'startCoding' },
             },
         },
+        reportedReviewFailure: {
+            id: 'reportedReviewFailure',
+            description: STATE_DESCRIPTIONS.reportedReviewFailure,
+            meta: playbookMeta('reportedReviewFailure'),
+            type: 'final',
+        },
         done: {
             id: 'done',
             description: STATE_DESCRIPTIONS.done,

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

@@ -31,19 +31,18 @@ export type PendingBossQuestion = {
   readonly questionId: 'runFirstPhase' | 'runIrTask';
   readonly resumeStateId: 'runFirstPhase' | 'runIrTask';
   readonly sourceItem: 'CODE-1' | 'CODE-3';
-  readonly player: 'Coder';
+  readonly asker: { readonly kind: 'role'; readonly roleId: 'coder' };
   readonly question: string;
 };
 
 export type PlayerInput = {
   readonly stateId: 'runFirstPhase' | 'runIrTask';
-  readonly player: 'Coder';
+  readonly role: 'coder';
   readonly sourceItem: 'CODE-1' | 'CODE-3';
   readonly prompt: string;
   readonly result: Readonly<Record<string, string>>;
   readonly callerInput: string;
   readonly runResults: string;
-  readonly coderPlayer: string;
   readonly irNumber?: string;
   readonly irTask?: string;
   readonly pendingBossQuestion?: PendingBossQuestion;
@@ -114,12 +113,10 @@ export type CodePlaybookOutput =
     };
 
 export type CodingInput = {
-  readonly coderPlayer?: string;
   readonly runResults?: string;
 };
 
 export type CodingContext = {
-  readonly coderPlayer: string;
   readonly runResults: string;
   readonly callerInput?: string;
   readonly coderOutput?: string;
@@ -205,18 +202,20 @@ const STATE_DESCRIPTIONS = {
   reviewIrTask: 'The REVIEW playbook is checking the latest task commit.',
   awaitBossReply: 'Waiting for Boss to answer Coder.',
   failed: 'The coding workflow failed and is waiting for a new coding intent.',
+  reportedReviewFailure:
+    'The coding workflow reported a REVIEW failure and the last code-owned commit.',
   done: 'The coding workflow completed after REVIEW found no unsettled findings.',
 } as const;
 
 function playbookMeta<StateId extends keyof typeof STATE_DESCRIPTIONS>(
   stateId: StateId,
-  player?: 'Coder',
+  role?: 'coder',
 ) {
   return {
     playbook: {
       stateId,
       description: STATE_DESCRIPTIONS[stateId],
-      ...(player === undefined ? {} : { player }),
+      ...(role === undefined ? {} : { role }),
     },
   };
 }
@@ -557,7 +556,6 @@ const machineSetup = setup({
     startCoding: assign(({ context, event }) => {
       if (event.type !== 'START_CODE') return {};
       return {
-        coderPlayer: context.coderPlayer,
         runResults: context.runResults,
         callerInput: event.callerInput,
         coderOutput: undefined,
@@ -623,7 +621,7 @@ const machineSetup = setup({
           questionId: stateId,
           resumeStateId: stateId,
           sourceItem: stateId === 'runFirstPhase' ? 'CODE-1' : 'CODE-3',
-          player: 'Coder',
+          asker: { kind: 'role', roleId: 'coder' },
           question,
         },
         bossReply: undefined,
@@ -670,8 +668,6 @@ export const codingMachine = machineSetup.createMachine({
   id: 'code',
   initial: 'ready',
   context: ({ input }) => ({
-    coderPlayer:
-      isNonEmptyString(input.coderPlayer) ? input.coderPlayer : 'Coder',
     runResults: typeof input.runResults === 'string' ? input.runResults : '',
   }),
   output: ({ context }): CodePlaybookOutput => {
@@ -707,19 +703,18 @@ export const codingMachine = machineSetup.createMachine({
     runFirstPhase: {
       id: 'runFirstPhase',
       description: STATE_DESCRIPTIONS.runFirstPhase,
-      meta: playbookMeta('runFirstPhase', 'Coder'),
+      meta: playbookMeta('runFirstPhase', 'coder'),
       tags: ['playbook.busy'],
       invoke: {
         src: 'player',
         input: ({ context }): PlayerInput => ({
           stateId: 'runFirstPhase',
-          player: 'Coder',
+          role: 'coder',
           sourceItem: 'CODE-1',
           prompt: FIRST_PHASE_PROMPT,
           result: FIRST_PHASE_RESULTS,
           callerInput: context.callerInput ?? '',
           runResults: context.runResults,
-          coderPlayer: context.coderPlayer,
           ...(context.pendingBossQuestion === undefined
             ? {}
             : { pendingBossQuestion: context.pendingBossQuestion }),
@@ -775,14 +770,14 @@ export const codingMachine = machineSetup.createMachine({
             target: 'runIrTask',
           },
           {
-            target: 'done',
+            target: 'reportedReviewFailure',
             actions: 'completeWithInvalidReviewOutput',
           },
         ],
         onError: [
           {
             guard: 'authoredReviewFailure',
-            target: 'done',
+            target: 'reportedReviewFailure',
             actions: 'completeWithReviewFailure',
           },
           { target: 'failed', actions: 'rememberActorError' },
@@ -792,19 +787,18 @@ export const codingMachine = machineSetup.createMachine({
     runIrTask: {
       id: 'runIrTask',
       description: STATE_DESCRIPTIONS.runIrTask,
-      meta: playbookMeta('runIrTask', 'Coder'),
+      meta: playbookMeta('runIrTask', 'coder'),
       tags: ['playbook.busy'],
       invoke: {
         src: 'player',
         input: ({ context }): PlayerInput => ({
           stateId: 'runIrTask',
-          player: 'Coder',
+          role: 'coder',
           sourceItem: 'CODE-3',
           prompt: IR_TASK_PROMPT,
           result: IR_TASK_RESULTS,
           callerInput: context.callerInput ?? '',
           runResults: context.runResults,
-          coderPlayer: context.coderPlayer,
           ...(context.irNumber === undefined
             ? {}
             : { irNumber: context.irNumber }),
@@ -865,14 +859,14 @@ export const codingMachine = machineSetup.createMachine({
             actions: 'completeSuccessfully',
           },
           {
-            target: 'done',
+            target: 'reportedReviewFailure',
             actions: 'completeWithInvalidReviewOutput',
           },
         ],
         onError: [
           {
             guard: 'authoredReviewFailure',
-            target: 'done',
+            target: 'reportedReviewFailure',
             actions: 'completeWithReviewFailure',
           },
           { target: 'failed', actions: 'rememberActorError' },
@@ -916,6 +910,12 @@ export const codingMachine = machineSetup.createMachine({
         START_CODE: { target: 'runFirstPhase', actions: 'startCoding' },
       },
     },
+    reportedReviewFailure: {
+      id: 'reportedReviewFailure',
+      description: STATE_DESCRIPTIONS.reportedReviewFailure,
+      meta: playbookMeta('reportedReviewFailure'),
+      type: 'final',
+    },
     done: {
       id: 'done',
       description: STATE_DESCRIPTIONS.done,

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

@@ -3,7 +3,7 @@
 
 # CODE: Commit-Based Coding Workflow
 
-Players:
+Roles:
 
 - Coder
 

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

@@ -1,3 +1,4 @@
+import { type XStatePromptIdentity } from '@sublang/playbook/xstate-runtime';
 import { type CodingInput, type PlayerInput } from './code.fsm.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, };
@@ -7,7 +8,7 @@ export type CodePlaybookOptions = CodingInput;
  * runtime text. The generic composer preserves the marker itself; CODE's
  * override additionally keeps a multiline value inside that quote.
  */
-declare function composePlayerPrompt(input: PlayerInput): string;
+declare function composePlayerPrompt(input: PlayerInput, promptIdentity: XStatePromptIdentity): string;
 export declare const _internal: {
     composePlayerPrompt: typeof composePlayerPrompt;
     VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string>;

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

@@ -3,15 +3,15 @@
 //
 // Generated by slc/link.md (FSM-to-Runtime linker).
 // Source FSM:    ./code.fsm.ts
-// Player bind:   Coder→coder (default lowercased binding)
+// Role metadata: Coder→coder (canonical local role)
 // Boss event:    deterministic START_CODE entry; exact Boss text becomes
 //                callerInput; pending Coder questions retain BOSS_REPLY
 // Adjudication:  LLM judge per player state; coderOutput is carried verbatim
 // Nested call:   literal review target through the shared bridge
-// Compat:        artifact schema 1 / runtime ABI 1
-import { RUNTIME_ABI, createXStatePlaybookRuntime, snapshotJsonValue, } from '@sublang/playbook/xstate-runtime';
+// Compat:        artifact schema 2 / runtime ABI 1
+import { createXStatePlaybookRuntime, snapshotJsonValue, } from '@sublang/playbook/xstate-runtime';
 import { codingMachine, } from './code.fsm.js';
-const OPTION_KEYS = new Set(['coderPlayer', 'runResults']);
+const OPTION_KEYS = new Set(['runResults']);
 const PLACEHOLDER = /<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>/g;
 const CONTINUATION_PREAMBLE = 'You previously paused this task to ask Boss a question; Boss has now replied. Continue the same task using the reply below.';
 const VERBATIM_PAYLOAD_FIELDS = new Set([
@@ -38,8 +38,6 @@ function snapshotCodeOptions(value) {
 function placeholderField(token) {
     if (token === '#')
         return 'irNumber';
-    if (token === 'coder-llm')
-        return 'coderPlayer';
     return token.replace(/-([A-Za-z0-9_$])/g, (_match, next) => next.toUpperCase());
 }
 function quoteContinuation(value) {
@@ -50,14 +48,16 @@ function quoteContinuation(value) {
  * runtime text. The generic composer preserves the marker itself; CODE's
  * override additionally keeps a multiline value inside that quote.
  */
-function composePlayerPrompt(input) {
+function composePlayerPrompt(input, promptIdentity) {
     const fields = input;
     const template = input.prompt
         .split('\n')
         .filter((line) => !(line === '> <run-results>' && input.runResults.length === 0))
         .join('\n');
     const body = template.replace(PLACEHOLDER, (match, token, offset, source) => {
-        const value = fields[placeholderField(token)];
+        const value = token === 'coder-llm'
+            ? promptIdentity('coder')
+            : fields[placeholderField(token)];
         if (typeof value !== 'string')
             return match;
         const lineStart = source.lastIndexOf('\n', offset - 1) + 1;
@@ -81,21 +81,31 @@ export const _internal = {
 };
 const runtimeSpec = {
     label: 'CODE',
-    compat: { artifactSchema: 1, runtimeAbi: RUNTIME_ABI },
+    // DR-022 / slc/link.md: the declaration carries the value current at link
+    // 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 },
     snapshotOptions: snapshotCodeOptions,
-    entryEvent: { type: 'START_CODE', textField: 'callerInput' },
-    playerStates: {
+    entryEvent: {
+        type: 'START_CODE',
+        textField: 'callerInput',
+        // `startCoding` copies the entry text here, so the failure-state retry
+        // reads it back from the persisted machine snapshot and survives a
+        // continued session (DR-034).
+        contextField: 'callerInput',
+    },
+    roleStates: {
         runFirstPhase: {
-            player: 'Coder',
+            role: 'coder',
             label: 'Coder is implementing one direct phase or committing a new intent record.',
         },
         runIrTask: {
-            player: 'Coder',
+            role: 'coder',
             label: 'Coder is implementing exactly one unfinished intent-record task.',
         },
     },
-    placeholderFields: { 'coder-llm': 'coderPlayer' },
-    composePlayerPrompt: (input) => composePlayerPrompt(input),
+    composePlayerPrompt: (input, promptIdentity) => composePlayerPrompt(input, promptIdentity),
     verbatimPayloadFields: VERBATIM_PAYLOAD_FIELDS,
     controlContextFields: ['phase'],
     transitionEventFields: ['callerInput', 'answer', 'questionId'],

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

@@ -3,18 +3,18 @@
 //
 // Generated by slc/link.md (FSM-to-Runtime linker).
 // Source FSM:    ./code.fsm.ts
-// Player bind:   Coder→coder (default lowercased binding)
+// Role metadata: Coder→coder (canonical local role)
 // Boss event:    deterministic START_CODE entry; exact Boss text becomes
 //                callerInput; pending Coder questions retain BOSS_REPLY
 // Adjudication:  LLM judge per player state; coderOutput is carried verbatim
 // Nested call:   literal review target through the shared bridge
-// Compat:        artifact schema 1 / runtime ABI 1
+// Compat:        artifact schema 2 / runtime ABI 1
 
 import {
-  RUNTIME_ABI,
   createXStatePlaybookRuntime,
   snapshotJsonValue,
   type PlaybookPlayerInput,
+  type XStatePromptIdentity,
   type XStatePlaybookRuntimeSpec,
 } from '@sublang/playbook/xstate-runtime';
 import {
@@ -76,7 +76,7 @@ export type {
 
 export type CodePlaybookOptions = CodingInput;
 
-const OPTION_KEYS = new Set(['coderPlayer', 'runResults']);
+const OPTION_KEYS = new Set(['runResults']);
 const PLACEHOLDER = /<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>/g;
 const CONTINUATION_PREAMBLE =
   'You previously paused this task to ask Boss a question; Boss has now replied. Continue the same task using the reply below.';
@@ -108,7 +108,6 @@ function snapshotCodeOptions(value: unknown): CodePlaybookOptions {
 
 function placeholderField(token: string): string {
   if (token === '#') return 'irNumber';
-  if (token === 'coder-llm') return 'coderPlayer';
   return token.replace(/-([A-Za-z0-9_$])/g, (_match, next: string) =>
     next.toUpperCase(),
   );
@@ -123,7 +122,10 @@ function quoteContinuation(value: string): string {
  * runtime text. The generic composer preserves the marker itself; CODE's
  * override additionally keeps a multiline value inside that quote.
  */
-function composePlayerPrompt(input: PlayerInput): string {
+function composePlayerPrompt(
+  input: PlayerInput,
+  promptIdentity: XStatePromptIdentity,
+): string {
   const fields = input as unknown as Record<string, unknown>;
   const template = input.prompt
     .split('\n')
@@ -134,7 +136,10 @@ function composePlayerPrompt(input: PlayerInput): string {
   const body = template.replace(
     PLACEHOLDER,
     (match: string, token: string, offset: number, source: string) => {
-      const value = fields[placeholderField(token)];
+      const value =
+        token === 'coder-llm'
+          ? promptIdentity('coder')
+          : fields[placeholderField(token)];
       if (typeof value !== 'string') return match;
       const lineStart = source.lastIndexOf('\n', offset - 1) + 1;
       const literal = source.slice(lineStart, offset);
@@ -160,29 +165,41 @@ export const _internal = {
   VERBATIM_PAYLOAD_FIELDS,
 };
 
-const runtimeSpec: XStatePlaybookRuntimeSpec<CodePlaybookOptions> = {
+const runtimeSpec = {
   label: 'CODE',
-  compat: { artifactSchema: 1, runtimeAbi: RUNTIME_ABI },
+  // DR-022 / slc/link.md: the declaration carries the value current at link
+  // 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 },
   snapshotOptions: snapshotCodeOptions,
-  entryEvent: { type: 'START_CODE', textField: 'callerInput' },
-  playerStates: {
+  entryEvent: {
+    type: 'START_CODE',
+    textField: 'callerInput',
+    // `startCoding` copies the entry text here, so the failure-state retry
+    // reads it back from the persisted machine snapshot and survives a
+    // continued session (DR-034).
+    contextField: 'callerInput',
+  },
+  roleStates: {
     runFirstPhase: {
-      player: 'Coder',
+      role: 'coder',
       label:
         'Coder is implementing one direct phase or committing a new intent record.',
     },
     runIrTask: {
-      player: 'Coder',
+      role: 'coder',
       label: 'Coder is implementing exactly one unfinished intent-record task.',
     },
   },
-  placeholderFields: { 'coder-llm': 'coderPlayer' },
-  composePlayerPrompt: (input: PlaybookPlayerInput) =>
-    composePlayerPrompt(input as PlayerInput),
+  composePlayerPrompt: (
+    input: PlaybookPlayerInput,
+    promptIdentity: XStatePromptIdentity,
+  ) => composePlayerPrompt(input as PlayerInput, promptIdentity),
   verbatimPayloadFields: VERBATIM_PAYLOAD_FIELDS,
   controlContextFields: ['phase'],
   transitionEventFields: ['callerInput', 'answer', 'questionId'],
-};
+} satisfies XStatePlaybookRuntimeSpec<CodePlaybookOptions>;
 
 const createPlaybookRuntime: PlaybookRuntimeFactory<CodePlaybookOptions> =
   createXStatePlaybookRuntime(codingMachine, runtimeSpec);

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

@@ -1,4 +1,4 @@
-import { type CodePlaybookOptions, type PlaybookRuntime } from './code.playbook.js';
+import { type PlaybookRuntime } from './code.playbook.js';
 export interface PlaybookSummaryPolicy {
     stateCountLabels: Readonly<Record<string, string>>;
     copyPasteGuardNames: readonly string[];
@@ -7,24 +7,17 @@ export interface PlaybookSummaryPolicy {
         copyPastes: number;
     }, rounds: number): string;
 }
-export interface RegistryPlayer {
-    id: string;
-    adapter?: string;
-    model?: string;
-}
-export interface CreateCodeRuntimeOptions {
-    captainOptions: unknown;
-    players: readonly RegistryPlayer[];
-}
 export type CodeOptions = Readonly<Record<string, never>>;
 export interface CodePlaybookRegistryEntry {
     id: 'code';
     command: 'code';
     intent: string;
+    artifactSchema: 2;
     requiredRoleIds: readonly ['coder'];
+    concurrentRoleSets: readonly [];
     summaryPolicy: PlaybookSummaryPolicy;
-    validateOptions(captainOptions: unknown): CodeOptions;
-    createRuntime(options: CreateCodeRuntimeOptions): PlaybookRuntime;
+    validateOptions(optionSlice: unknown): CodeOptions;
+    createRuntime(options: CodeOptions): PlaybookRuntime;
 }
 export declare const codeStateCountLabels: {};
 export declare const codeCopyPasteGuardNames: readonly ["directCommit", "irCommit", "moreTasks", "finalTask"];
@@ -34,6 +27,5 @@ export declare function codeSavedCountsLine(counts: {
 }, rounds: number): string;
 export declare const codeSummaryPolicy: PlaybookSummaryPolicy;
 export declare function validateCodeOptions(optionSlice: unknown): CodeOptions;
-export declare function createCodeRuntimeOptions({ captainOptions, players, }: CreateCodeRuntimeOptions): CodePlaybookOptions;
 export declare const codePlaybookRegistryEntry: CodePlaybookRegistryEntry;
 export default codePlaybookRegistryEntry;