@sublang/playbook 5.0.0 → 6.0.0

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

@@ -3,51 +3,25 @@
 //
 // Generated by slc/link.md (FSM-to-Runtime linker).
 // Source FSM:    ./code.fsm.ts
-// Player bind:   Coder→coder, Reviewer→reviewer,
-//                Committer→ configured committerPlayer alias when set
-//                (per-run remapping via options — PBRT-8); else the
-//                baked CODE-18/19 fallback (coder-first: CODE-19 wires
-//                both coderPlayer and reviewerPlayer, Coder wins as the
-//                alias's first alternative)
-// Boss event:    free-text judge classification
-// Adjudication:  LLM-judge per state
-// Contract:      PlayerResult / PlaybookPorts / PlaybookSession /
-//                PlaybookRuntime imported and re-exported from
-//                @sublang/playbook/runtime
-//                (slc/link.md §Output, DR-004 Addendum A4)
-// Runtime:       the shared createXStatePlaybookRuntime factory from
-//                @sublang/playbook/xstate-runtime interprets the FSM
-//                (slc/link.md §Output, DR-019); this module carries only
-//                the CODE-specific spec — options validation, player
-//                binding, prompt composition, Boss-event classification,
-//                and Captain-pane status formatting.
+// Player bind:   Coder→coder (default lowercased binding)
+// 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 {
-  createPlayerBridge,
+  RUNTIME_ABI,
   createXStatePlaybookRuntime,
-  adjudicatePlayerOutput,
-  normalizeError,
-  normalizeErrorCompact,
-  normalizeErrorFull,
-  parseJudgeJson,
   snapshotJsonValue,
   type PlaybookPlayerInput,
-  type RuntimeBoundaryCalls,
-  type ScheduledStatus,
   type XStatePlaybookRuntimeSpec,
-} from '../../../src/xstate-runtime.js';
+} from '@sublang/playbook/xstate-runtime';
 import {
   codingMachine,
-  type PlayerInput,
-  type PlayerOutput,
-  type CodingEvent,
   type CodingInput,
+  type PlayerInput,
 } from './code.fsm.js';
-import {
-  enumerateAwaitBossReply,
-  enumerateCaptainStates,
-  enumerateRootEvents,
-} from './code.fsm.introspect.js';
 import type {
   CaptainCallOptions,
   CaptainResult,
@@ -57,27 +31,23 @@ import type {
   PlaybookCallRequest,
   PlaybookCallResult,
   PlaybookCallStart,
+  PlaybookControlReceipt,
+  PlaybookControlView,
   PlaybookPendingCall,
+  PlaybookPorts,
   PlaybookRunResult,
+  PlaybookRuntime,
+  PlaybookRuntimeFactory,
   PlaybookRuntimeSnapshot,
   PlaybookSession,
   PlaybookState,
   PlaybookStateValue,
   PlaybookTraceEvent,
   PlaybookTraceType,
-  PlaybookPorts,
-  PlaybookRuntime,
-  PlaybookRuntimeFactory,
   PlayerResult,
+  PlayerSessionStore,
 } from '@sublang/playbook/runtime';
 
-// Public contract. `PlayerResult`, `PlaybookPorts`, `PlaybookSession`, and
-// `PlaybookRuntime` are re-exported from the shared runtime module
-// (slc/link.md §Output, DR-004 Addendum A4) so this playbook and any
-// future one resolve one contract definition rather than redefining it.
-// `CodePlaybookOptions` and the default `createPlaybookRuntime` factory
-// (typed `PlaybookRuntimeFactory<CodePlaybookOptions>`) stay
-// CODE-specific.
 export type {
   CaptainCallOptions,
   CaptainResult,
@@ -87,23 +57,35 @@ export type {
   PlaybookCallRequest,
   PlaybookCallResult,
   PlaybookCallStart,
+  PlaybookControlReceipt,
+  PlaybookControlView,
   PlaybookPendingCall,
-  PlaybookRunResult,
-  PlayerResult,
   PlaybookPorts,
+  PlaybookRunResult,
+  PlaybookRuntime,
+  PlaybookRuntimeFactory,
+  PlaybookRuntimeSnapshot,
   PlaybookSession,
   PlaybookState,
   PlaybookStateValue,
   PlaybookTraceEvent,
   PlaybookTraceType,
-  PlaybookRuntime,
-  PlaybookRuntimeFactory,
-  PlaybookRuntimeSnapshot,
+  PlayerResult,
+  PlayerSessionStore,
 };
 
 export type CodePlaybookOptions = CodingInput;
 
-function snapshotCodePlaybookOptions(value: unknown): CodePlaybookOptions {
+const OPTION_KEYS = new Set(['coderPlayer', '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: ReadonlySet<string> = new Set([
+  'coderOutput',
+]);
+
+function snapshotCodeOptions(value: unknown): CodePlaybookOptions {
   const captured = snapshotJsonValue(value, 'CODE runtime options');
   if (
     captured === null ||
@@ -113,15 +95,8 @@ function snapshotCodePlaybookOptions(value: unknown): CodePlaybookOptions {
     throw new TypeError('CODE runtime options must be an object');
   }
   const record = captured as Readonly<Record<string, JsonValue>>;
-  const allowed = new Set([
-    'intent',
-    'irNumber',
-    'coderPlayer',
-    'reviewerPlayer',
-    'committerPlayer',
-  ]);
   for (const [key, option] of Object.entries(record)) {
-    if (!allowed.has(key)) {
+    if (!OPTION_KEYS.has(key)) {
       throw new TypeError(`CODE runtime options.${key} is not declared`);
     }
     if (typeof option !== 'string') {
@@ -131,834 +106,82 @@ function snapshotCodePlaybookOptions(value: unknown): CodePlaybookOptions {
   return captured as unknown as CodePlaybookOptions;
 }
 
-// Required-payload fields whose value is the player's verbatim long-form
-// prose. The runtime carries `finalText.trim()` into these fields rather
-// than asking the judge to round-trip the text through JSON. Short
-// extracted fields (`question`, `taskDescription`, `irNumber`, …) stay
-// judge-extracted — they are not in this set.
-const VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string> = new Set([
-  'reviews',
-  'challenges',
-]);
-
-// Normalize any `error` field inside a telemetry event so failed
-// transitions don't leak raw Error instances through the channel.
-function normalizeEventForTelemetry(event: unknown): unknown {
-  if (event === undefined) return undefined;
-  return normalizeEventValue(event, 'FSM event', new Set());
-}
-
-function normalizeEventValue(
-  value: unknown,
-  path: string,
-  ancestors: ReadonlySet<object>,
-): JsonValue {
-  if (Array.isArray(value)) return snapshotJsonValue(value, path);
-  if (value === null || typeof value !== 'object') {
-    return snapshotJsonValue(value, path);
-  }
-  if (ancestors.has(value)) {
-    throw new TypeError(`${path} must not contain a JSON cycle`);
-  }
-  const prototype = Object.getPrototypeOf(value) as unknown;
-  if (prototype !== Object.prototype && prototype !== null) {
-    return snapshotJsonValue(value, path);
-  }
-  if (Object.getOwnPropertySymbols(value).length > 0) {
-    return snapshotJsonValue(value, path);
-  }
-  const nextAncestors = new Set(ancestors).add(value);
-  const normalized: Record<string, JsonValue> = {};
-  for (const [key, descriptor] of Object.entries(
-    Object.getOwnPropertyDescriptors(value),
-  )) {
-    if (!descriptor.enumerable) {
-      throw new TypeError(`${path}.${key} must be an enumerable JSON property`);
-    }
-    if (!Object.prototype.hasOwnProperty.call(descriptor, 'value')) {
-      throw new TypeError(`${path}.${key} must be a JSON data property`);
-    }
-    if (descriptor.value === undefined) continue;
-    normalized[key] =
-      key === 'error'
-        ? snapshotJsonValue(normalizeError(descriptor.value), `${path}.error`)
-        : normalizeEventValue(
-            descriptor.value,
-            `${path}.${key}`,
-            nextAncestors,
-          );
-  }
-  return snapshotJsonValue(normalized, path);
-}
-
-// Player-prompt composer — DR-004 §6.
-// Substitutes the three placeholder tokens in `input.prompt` (literal
-// string replace, no escaping) and arranges labelled blocks around
-// the prompt body. Context blocks the body refers to as prior
-// material (`Boss intent:`, `Task description:`) are prepended;
-// action blocks the body refers to as material below
-// (`Review items:`, `Rebuttals:`) are appended after the body so the
-// CODE-N prompts' "review item below" / "rebuttal below" phrasing
-// matches the rendered layout. When a state resumes from a Boss
-// reply, the continuation preamble and Q/A blocks precede every
-// ordinary block. The FSM's prompt body is never re-flowed.
-
-function composePlayerPrompt(input: PlayerInput): string {
-  const blocks: string[] = [];
-  if (
-    input.pendingBossQuestion !== undefined &&
-    input.bossReply !== undefined
-  ) {
-    blocks.push(
-      'You previously paused this task to ask Boss a question; Boss has now replied. Continue the same task using the reply below.',
-    );
-    blocks.push(`Boss question:\n${input.pendingBossQuestion.question}`);
-    blocks.push(`Boss reply:\n${input.bossReply}`);
-  }
-  if (input.intent !== undefined) {
-    blocks.push(`Boss intent:\n${input.intent}`);
-  }
-  if (input.taskDescription !== undefined) {
-    blocks.push(`Task description:\n${input.taskDescription}`);
-  }
-
-  let body = input.prompt;
-  if (input.irNumber !== undefined) {
-    body = body.replaceAll('<#>', input.irNumber);
-  }
-  if (input.coderPlayer !== undefined) {
-    body = body.replaceAll('<coder-llm>', input.coderPlayer);
-  }
-  if (input.reviewerPlayer !== undefined) {
-    body = body.replaceAll('<reviewer-llm>', input.reviewerPlayer);
-  }
-
-  blocks.push(body);
-
-  if (input.reviews !== undefined) {
-    blocks.push(`Review items:\n${input.reviews}`);
-  }
-  if (input.challenges !== undefined) {
-    blocks.push(`Rebuttals:\n${input.challenges}`);
-  }
-
-  return blocks.join('\n\n');
-}
-
-// Player-id resolver — DR-004 §2 / PBRT-8.
-// Non-composite: Coder→'coder', Reviewer→'reviewer'. The composite
-// Committer (= Coder | Reviewer per code.gears.md) resolves to the
-// configured alias when present: `input.committerPlayer`, the
-// validated `captain.options.playbooks.code.options.committer`
-// (PBRT-8 / PBRT-30), already a baked player id ('coder' / 'reviewer').
-// Absent a
-// configured alias it falls back to the DR-004 §2 baked binding by
-// populated <playerName>Player field: prefer `coderPlayer` (CODE-18
-// wires only coderPlayer; CODE-19 wires both so coderPlayer still wins
-// as the alias's first alternative), fall back to `reviewerPlayer`
-// only if a future gear ships a reviewer-only Committer item, and
-// finally to the alias's first alternative (Coder) when neither is
-// set. The alias selects only the host pane; it is not a PBRT-4
-// identity string, so it leaves <coder-llm> / <reviewer-llm>
-// untouched and `input.player` stays `Committer` (PLAYBOOK-3).
-function resolvePlayerId(input: PlayerInput): string {
-  switch (input.player) {
-    case 'Coder':
-      return 'coder';
-    case 'Reviewer':
-      return 'reviewer';
-    case 'Committer':
-      if (input.committerPlayer !== undefined) return input.committerPlayer;
-      if (input.coderPlayer !== undefined) return 'coder';
-      if (input.reviewerPlayer !== undefined) return 'reviewer';
-      return 'coder';
-    default: {
-      const exhaustive: never = input.player;
-      throw new Error(`resolvePlayerId: unknown player ${String(exhaustive)}`);
-    }
-  }
-}
-
-function extractRequiredFields(description: string): string[] {
-  const fields: string[] = [];
-  const re = /Output shall include `([A-Za-z_][A-Za-z0-9_]*):/g;
-  for (const m of description.matchAll(re)) {
-    fields.push(m[1]);
-  }
-  return fields;
-}
-
-function buildJudgePrompt(input: PlayerInput, finalText: string): string {
-  const lines: string[] = [];
-  lines.push(
-    'This is hidden control work. Do not call tools, inspect files, or ' +
-      'seek external evidence. Decide only from the supplied player output ' +
-      'and outcome descriptions. Reply with exactly one JSON object and no prose.',
+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(),
   );
-  lines.push('');
-  lines.push(`The ${input.player} just produced this output:`);
-  lines.push('');
-  lines.push('```');
-  lines.push(finalText);
-  lines.push('```');
-  lines.push('');
-  lines.push(
-    'Pick exactly one outcome by `guard` and return JSON ' +
-      '`{ guard, …payloadFields }`. Required payload fields are ' +
-      'named in the outcome description. Do not copy long-form ' +
-      'verbatim fields (`reviews`, `challenges`) — the runtime ' +
-      "carries the player's output into those fields verbatim, " +
-      'so any value you supply for them will be overwritten.',
-  );
-  lines.push('');
-  for (const [key, description] of Object.entries(input.result)) {
-    lines.push(`- \`${key}\` — ${description}`);
-  }
-  return lines.join('\n');
 }
 
-// CODE-specific adjudication strategy: the CODE judge prompt above, the
-// DR-004 `Output shall include` required-field extraction, and the
-// verbatim long-form payload fields.
-const CODE_ADJUDICATION = {
-  buildJudgePrompt: (input: PlaybookPlayerInput, finalText: string) =>
-    buildJudgePrompt(input as unknown as PlayerInput, finalText),
-  extractRequiredFields,
-  verbatimPayloadFields: VERBATIM_PAYLOAD_FIELDS,
-};
-
-// LLM judge — DR-004 §4. Delegates to the shared adjudicator with the
-// CODE strategy: it lists each declared outcome verbatim, asks
-// ports.callJudge for a JSON `{ guard, …payloadFields }` response, and
-// returns the parsed object once the chosen guard is one of the
-// input.result keys. Adjudicator failures (malformed JSON,
-// missing/unknown guard) are control-plane errors and propagate via
-// throw per slc/link.md.
-async function adjudicate(
-  input: PlayerInput,
-  finalText: string,
-  ports: PlaybookPorts,
-  signal: AbortSignal,
-  boundary?: RuntimeBoundaryCalls,
-): Promise<PlayerOutput> {
-  return (await adjudicatePlayerOutput(
-    CODE_ADJUDICATION,
-    input,
-    finalText,
-    ports,
-    signal,
-    boundary,
-  )) as unknown as PlayerOutput;
+function quoteContinuation(value: string): string {
+  return value.replaceAll('\n', '\n> ');
 }
 
-// Boss-event classifier — DR-004 §3.
-// Every non-empty Boss turn goes through ports.callJudge. Slash-prefixed
-// text is ordinary content once a host has routed the turn to this
-// playbook; `/command` selection belongs outside handleBossInput. The
-// classifier is state-aware so awaitBossReply can distinguish a direct
-// answer (BOSS_REPLY) from a fresh directive that abandons the pending
-// question through the FSM's existing transitions.
-async function classifyBossText(
-  text: string,
-  ports: PlaybookPorts,
-  signal: AbortSignal,
-  snapshotOrState?: unknown,
-  boundary?: RuntimeBoundaryCalls,
-): Promise<CodingEvent | undefined> {
-  const trimmed = text.trim();
-  if (trimmed === '') return undefined;
-
-  return classifyWithLlm(text, ports, signal, snapshotOrState, boundary);
-}
-
-// JumpableStateId is internal to code.fsm.ts (not exported), so
-// recover it from the CodingEvent union for typed casts here.
-type JumpableStateId = Extract<
-  CodingEvent,
-  { type: 'BOSS_INTERRUPT' }
->['targetId'];
-
-const rootEvents = enumerateRootEvents(codingMachine);
-const bossInterruptTargets = rootEvents.bossInterruptTargetDescriptions;
-const bossInterruptTargetIds: ReadonlySet<string> = new Set(
-  bossInterruptTargets.map((target) => target.stateId),
-);
-
-async function classifyWithLlm(
-  text: string,
-  ports: PlaybookPorts,
-  signal: AbortSignal,
-  snapshotOrState?: unknown,
-  boundary?: RuntimeBoundaryCalls,
-): Promise<CodingEvent | undefined> {
-  const state = classifierState(snapshotOrState);
-  const prompt = buildClassifierPrompt(text, state);
-  const stateId = typeof state.value === 'string' ? state.value : undefined;
-  const raw = boundary
-    ? await boundary.callJudge(
-        'boss-input-classification',
-        stateId,
-        prompt,
-        signal,
-      )
-    : await ports.callJudge(prompt, signal);
-  let parsed: unknown;
-  try {
-    parsed = parseJudgeJson(raw);
-  } catch {
-    // No JSON value could be recovered. Classification failures are
-    // non-fatal — unlike adjudication, which throws to the failure
-    // state (PBRT-10) — so surface one status and take no FSM action,
-    // consistent with the other invalid-reply paths below (PBRT-7).
-    await ports.emitStatus('Classifier reply was not recoverable JSON');
-    return undefined;
-  }
-  if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-    await ports.emitStatus('Classifier returned a non-object JSON response');
-    return undefined;
-  }
-  const obj = parsed as Record<string, unknown>;
-  const eventType = obj.event;
-  if (typeof eventType !== 'string') {
-    await ports.emitStatus('Classifier did not name an event type');
-    return undefined;
-  }
-  const payload =
-    typeof obj.payload === 'object' &&
-    obj.payload !== null &&
-    !Array.isArray(obj.payload)
-      ? (obj.payload as Record<string, unknown>)
-      : {};
-
-  switch (eventType) {
-    case 'NO_ACTION':
-    case 'NO_FSM_ACTION':
-    case 'NONE':
-      return undefined;
-    case 'START_CODING': {
-      if (typeof payload.intent !== 'string') {
-        await ports.emitStatus('Classifier omitted intent for START_CODING');
-        return undefined;
-      }
-      return { type: 'START_CODING', intent: payload.intent };
-    }
-    case 'CONTINUE_IR': {
-      if (typeof payload.irNumber !== 'string') {
-        await ports.emitStatus('Classifier omitted irNumber for CONTINUE_IR');
-        return undefined;
-      }
-      return { type: 'CONTINUE_IR', irNumber: payload.irNumber };
-    }
-    case 'SUMMARIZE_IR': {
-      if (typeof payload.irNumber !== 'string') {
-        await ports.emitStatus('Classifier omitted irNumber for SUMMARIZE_IR');
-        return undefined;
-      }
-      return { type: 'SUMMARIZE_IR', irNumber: payload.irNumber };
-    }
-    case 'BOSS_INTERRUPT': {
-      if (typeof payload.targetId !== 'string') {
-        await ports.emitStatus(
-          'Classifier omitted targetId for BOSS_INTERRUPT',
-        );
-        return undefined;
-      }
-      if (!bossInterruptTargetIds.has(payload.targetId)) {
-        await ports.emitStatus(
-          `Classifier supplied invalid targetId for BOSS_INTERRUPT: ${payload.targetId}`,
-        );
-        return undefined;
-      }
-      return {
-        type: 'BOSS_INTERRUPT',
-        targetId: payload.targetId as JumpableStateId,
-        ...(typeof payload.intent === 'string'
-          ? { intent: payload.intent }
-          : {}),
-        ...(typeof payload.irNumber === 'string'
-          ? { irNumber: payload.irNumber }
-          : {}),
-      };
-    }
-    case 'BOSS_REPLY': {
-      if (state.value !== 'awaitBossReply') {
-        await ports.emitStatus(
-          'Classifier returned BOSS_REPLY outside awaitBossReply',
-        );
-        return undefined;
-      }
-      if (typeof payload.answer !== 'string') {
-        await ports.emitStatus('Classifier omitted answer for BOSS_REPLY');
-        return undefined;
-      }
-      const pending = pendingBossQuestionFromContext(state.context);
-      if (!pending) {
-        await ports.emitStatus(
-          'Classifier returned BOSS_REPLY without a pending question',
-        );
-        return undefined;
-      }
-      if (
-        payload.questionId !== undefined &&
-        typeof payload.questionId !== 'string'
-      ) {
-        await ports.emitStatus(
-          'Classifier supplied a non-string questionId for BOSS_REPLY',
-        );
-        return undefined;
-      }
-      if (
-        typeof payload.questionId === 'string' &&
-        payload.questionId !== pending.questionId
-      ) {
-        await ports.emitStatus(
-          `Classifier supplied unknown questionId for BOSS_REPLY: ${payload.questionId}`,
-        );
-        return undefined;
-      }
-      return {
-        type: 'BOSS_REPLY',
-        answer: payload.answer,
-        questionId: pending.questionId,
-      };
-    }
-    default:
-      await ports.emitStatus(
-        `Classifier returned unknown event type: ${eventType}`,
-      );
-      return undefined;
-  }
-}
-
-interface ClassifierState {
-  value: unknown;
-  context: Record<string, unknown>;
-}
-
-function classifierState(snapshotOrState: unknown): ClassifierState {
-  if (
-    snapshotOrState !== null &&
-    typeof snapshotOrState === 'object' &&
-    'value' in snapshotOrState
-  ) {
-    const candidate = snapshotOrState as {
-      value?: unknown;
-      context?: unknown;
-    };
-    return {
-      value: candidate.value,
-      context:
-        candidate.context !== null &&
-        typeof candidate.context === 'object' &&
-        !Array.isArray(candidate.context)
-          ? (candidate.context as Record<string, unknown>)
-          : {},
-    };
-  }
-  return { value: snapshotOrState, context: {} };
-}
-
-function buildClassifierPrompt(text: string, state: ClassifierState): string {
-  const currentState =
-    typeof state.value === 'string'
-      ? state.value
-      : JSON.stringify(state.value ?? null);
-  const pendingBossQuestion = pendingBossQuestionFromContext(state.context);
-  const lines = [
-    'Classify the following Boss message into exactly one of these events.',
-    'Respond with JSON: { "event": "<TYPE>", "payload": { ...fields } }.',
-    'Use { "event": "NO_ACTION", "payload": {} } when no FSM action should be taken.',
-    '',
-    `Current state: ${currentState}`,
-  ];
-  if (pendingBossQuestion !== undefined) {
-    lines.push(
-      `Pending question id: ${pendingBossQuestion.questionId}`,
-      `Pending asking player: ${pendingBossQuestion.player}`,
-      `Pending Boss question: ${pendingBossQuestion.question}`,
-    );
-  }
-  lines.push(
-    '',
-    'Events:',
-    '- START_CODING: payload { intent: "<free-form goal>" }',
-    '- CONTINUE_IR: payload { irNumber: "<number>" }',
-    '- SUMMARIZE_IR: payload { irNumber: "<number>" }',
-    '- BOSS_INTERRUPT: payload { targetId: "<stateId>", intent?: "<free-form goal>", irNumber?: "<number>" }',
-    '  targetId must be one of these jumpable states:',
-  );
-  for (const target of bossInterruptTargets) {
-    lines.push(`  - ${target.stateId}: ${target.description}`);
-  }
-  if (currentState === 'awaitBossReply') {
-    lines.push(
-      '- BOSS_REPLY: payload { answer: "<verbatim Boss answer>", questionId?: "<pending question id>" }',
-    );
-  } else {
-    lines.push('- BOSS_REPLY: valid only when Current state is awaitBossReply');
-  }
-  lines.push('', 'Boss message:', '```', text, '```');
-  return lines.join('\n');
-}
-
-// Delegated-player actor bridge — DR-004 §7. One PromiseActorLogic that the
-// codingMachine invokes from every player-invoking state, built by the
-// shared createPlayerBridge with the CODE binding, composer, and
-// adjudication strategy. Per turn: resolve playerId, compose the player
-// prompt, await ports.callPlayer, adjudicate the finalText. PlayerResult
-// status of 'aborted' or 'error' throws so XState routes via onError →
-// #failed (the single fail-stop sink for both Captain errors and player
-// failures). Captain remains the orchestrator and adjudicator; it is not
-// encoded as the delegated FSM actor.
-//
-// `getActiveSignal` is the runtime's hook for flowing the Boss's
-// `handleBossInput.signal` into the host port calls — fromPromise
-// hands the bridge XState's actor-scoped signal, which only fires
-// on actor.stop(), not on Boss abort. When omitted (e.g. direct
-// captainBridge tests), the bridge falls back to XState's signal.
-function captainBridge(
-  ports: PlaybookPorts,
-  getActiveSignal?: () => AbortSignal | undefined,
-  boundary?: RuntimeBoundaryCalls,
-  onControlPlaneError?: (error: unknown) => void,
-) {
-  return createPlayerBridge(
-    {
-      resolvePlayerId: (input) =>
-        resolvePlayerId(input as unknown as PlayerInput),
-      composePlayerPrompt: (input) =>
-        composePlayerPrompt(input as unknown as PlayerInput),
-      adjudication: CODE_ADJUDICATION,
-      resumableStateIds: registeredResumableStateIds,
+/**
+ * Preserve authored Markdown quote markers around every line of relayed
+ * 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 {
+  const fields = input as unknown as Record<string, unknown>;
+  const template = input.prompt
+    .split('\n')
+    .filter(
+      (line) => !(line === '> <run-results>' && input.runResults.length === 0),
+    )
+    .join('\n');
+  const body = template.replace(
+    PLACEHOLDER,
+    (match: string, token: string, offset: number, source: string) => {
+      const value = fields[placeholderField(token)];
+      if (typeof value !== 'string') return match;
+      const lineStart = source.lastIndexOf('\n', offset - 1) + 1;
+      const literal = source.slice(lineStart, offset);
+      return literal === '> ' ? quoteContinuation(value) : value;
     },
-    ports,
-    getActiveSignal,
-    boundary,
-    onControlPlaneError,
   );
-}
-
-// Captain pane display — PBRT-3 / PBRT-14.
-// The Captain pane is a stream of three glyphs plus one bare
-// captain-speech act, designed so a reader can parse each line at a
-// glance:
-//   (no glyph)  bare FSM event type — host renders as captain speech
-//               (e.g., `captain> START_CODING`)
-//   ⤷           player-invoking state entry: `<Player>: <label>`
-//   →           transition guard outcome (`· field=N` tallies
-//               appended); the host presenter owns any visual
-//               nesting under the preceding ⤷ entry
-
-//   ◆           failure state (with `lastError` data) and the
-//               `awaitBossReply` suspension state (custom payload)
-// The runtime emits no status line on entry to the idle state
-// (`ready`) or the terminal state (`done`); the next `boss>` prompt
-// is the implicit "turn over" signal. Prompts and full player output
-// ride the player panes; the Captain pane keeps to the state-machine
-// shape.
-
-const STATE_LABELS: Readonly<Record<string, string>> = {
-  planAndImplement: 'plan & implement',
-  respondToReview: 'respond to review',
-  continueIr: 'continue IR task',
-  summarizeSpecs: 'summarize IR into specs',
-  reviewBossCommitSpecs: 'review Boss-intent commit (specs only)',
-  reviewBossCommitCode: 'review Boss-intent commit (code only)',
-  reviewBossCommitMixed: 'review Boss-intent commit (specs + code)',
-  reviewIrTaskCommitSpecs: 'review IR-task commit (specs only)',
-  reviewIrTaskCommitCode: 'review IR-task commit (code only)',
-  reviewIrTaskCommitMixed: 'review IR-task commit (specs + code)',
-  reviewChangesSpecs: 'review uncommitted edits (specs only)',
-  reviewChangesCode: 'review uncommitted edits (code only)',
-  reviewChangesMixed: 'review uncommitted edits (specs + code)',
-  reviewChangesAndChallengesSpecs:
-    'review uncommitted edits + rebuttals (specs only)',
-  reviewChangesAndChallengesCode:
-    'review uncommitted edits + rebuttals (code only)',
-  reviewChangesAndChallengesMixed:
-    'review uncommitted edits + rebuttals (specs + code)',
-  adjudicateChallenges: 'adjudicate rebuttals',
-  commitCoderInitial: "commit Coder's initial changes",
-  commitJoint: 'commit reviewed changes',
-};
-
-interface StateMetadata {
-  player: PlayerInput['player'];
-  sourceItem: string;
-  label: string;
-}
-
-const stateMetadata: ReadonlyMap<string, StateMetadata> = (() => {
-  const m = new Map<string, StateMetadata>();
-  for (const s of enumerateCaptainStates(codingMachine)) {
-    const label = STATE_LABELS[s.stateId];
-    if (!label) {
-      throw new Error(
-        `code.playbook.ts: STATE_LABELS missing entry for player-invoking state '${s.stateId}'`,
-      );
-    }
-    const input = s.getInput({});
-    m.set(s.stateId, { player: input.player, sourceItem: s.sourceItem, label });
-  }
-  return m;
-})();
-
-const registeredResumableStateIds: ReadonlySet<string> = new Set(
-  enumerateAwaitBossReply(codingMachine).bossReplyTransitions.map(
-    (transition) => transition.target,
-  ),
-);
-
-const QUIESCENT_STATES: ReadonlySet<string> = new Set([
-  'ready',
-  'awaitBossReply',
-  'done',
-  'failed',
-]);
-
-// States whose entry the runtime does not surface on the Captain
-// pane per PBRT-3: the readline returning to its `boss>` prompt is
-// the implicit "turn over" signal, so a `◆ ready` / `◆ done`
-// tombstone is redundant.
-const SUPPRESSED_ENTRY_STATES: ReadonlySet<string> = new Set(['ready', 'done']);
-
-// Captain-pane surface (PBRT-3): every player-invoking state plus
-// the quiescent states whose entry still carries information
-// (failure with `lastError`, awaitBossReply with the pending
-// question). `ready` and `done` flow through the inspect handler
-// but their entries are dropped before emitStatus per
-// SUPPRESSED_ENTRY_STATES above.
-const CAPTAIN_PANE_STATES: ReadonlySet<string> = new Set([
-  ...stateMetadata.keys(),
-  ...QUIESCENT_STATES,
-]);
-
-type BossReplyQuestionId = NonNullable<
-  Extract<CodingEvent, { type: 'BOSS_REPLY' }>['questionId']
->;
-
-interface PendingBossQuestionForStatus {
-  questionId: BossReplyQuestionId;
-  resumeStateId: string;
-  sourceItem: string;
-  player: string;
-  question: string;
-}
-
-function pendingBossQuestionFromContext(
-  context: Record<string, unknown>,
-): PendingBossQuestionForStatus | undefined {
-  const pending = context.pendingBossQuestion;
-  if (pending === undefined || typeof pending !== 'object') {
-    return undefined;
-  }
-  const candidate = pending as Partial<
-    Record<keyof PendingBossQuestionForStatus, unknown>
-  >;
   if (
-    typeof candidate.resumeStateId !== 'string' ||
-    typeof candidate.questionId !== 'string' ||
-    typeof candidate.sourceItem !== 'string' ||
-    typeof candidate.player !== 'string' ||
-    typeof candidate.question !== 'string'
+    input.pendingBossQuestion === undefined ||
+    input.bossReply === undefined
   ) {
-    return undefined;
-  }
-  return {
-    questionId: candidate.questionId as BossReplyQuestionId,
-    resumeStateId: candidate.resumeStateId,
-    sourceItem: candidate.sourceItem,
-    player: candidate.player,
-    question: candidate.question,
-  };
-}
-
-// PBRT-3 / PBRT-14: on entry to `awaitBossReply` the runtime surfaces
-// the pending player question as a captain-speech act attributed to the
-// asking player (`<player> asks: <full question>`), emitted with no
-// glyph so the host renders it as captain speech. The question is
-// carried verbatim and in full — the judge JSON that produced it rides
-// a hidden callCaptain (PBRT-15), so this line is the Boss's only
-// legible view of what was asked.
-function formatAwaitBossReplyQuestion(
-  context: Record<string, unknown>,
-): string {
-  const pending = pendingBossQuestionFromContext(context);
-  const player = pending?.player ?? 'unknown';
-  const question = pending?.question ?? '';
-  return `${player} asks: ${question}`;
-}
-
-// The rider-less routing marker emitted right after the question line.
-// It carries only the resume target, asking player, and source item;
-// the former `q="<first 80 chars>"` excerpt rider is dropped now that
-// the full question rides the captain-speech line above.
-function formatAwaitBossReplyMarker(context: Record<string, unknown>): string {
-  const pending = pendingBossQuestionFromContext(context);
-  const resumeStateId = pending?.resumeStateId ?? 'unknown';
-  const player = pending?.player ?? 'unknown';
-  const sourceItem = pending?.sourceItem ?? 'unknown';
-  return `◆ awaiting Boss reply · ${resumeStateId} · ${player} · ${sourceItem}`;
-}
-
-function formatStateEntry(stateId: string): string | undefined {
-  if (SUPPRESSED_ENTRY_STATES.has(stateId)) return undefined;
-  if (stateId === 'failed') return '◆ failed';
-  const meta = stateMetadata.get(stateId);
-  if (!meta) return `⤷ ${stateId}`;
-  return `⤷ ${meta.player}: ${meta.label}`;
-}
-
-function formatTransition(event: unknown): string | undefined {
-  const output = (event as { output?: Record<string, unknown> })?.output;
-  if (!output || typeof output.guard !== 'string') return undefined;
-  const tallies: string[] = [];
-  for (const field of ['reviews', 'challenges'] as const) {
-    const value = output[field];
-    if (typeof value === 'string' && value.trim().length > 0) {
-      const items = value.match(/^\s*\d+\.\s/gm);
-      tallies.push(`${field}=${items ? items.length : 1}`);
-    }
-  }
-  const suffix = tallies.length > 0 ? ` · ${tallies.join(' · ')}` : '';
-  // No leading whitespace: visual nesting under the preceding ⤷
-  // entry is the host presenter's concern (cligent's writeStatusLine
-  // emits status messages verbatim, with its own chrome but no
-  // continuation indent; layout is its job, not ours).
-  return `→ ${output.guard}${suffix}`;
-}
-
-function formatClassification(eventType: string): string {
-  return eventType;
-}
-
-function stateTelemetryPayload(
-  from: unknown,
-  to: string,
-  event: unknown,
-  context: Record<string, unknown>,
-): Record<string, unknown> {
-  const payload: Record<string, unknown> = {
-    from: from ?? null,
-    to,
-    event: normalizeEventForTelemetry(event) ?? null,
-  };
-  if (to === 'awaitBossReply') {
-    const pendingBossQuestion = pendingBossQuestionFromContext(context);
-    if (pendingBossQuestion !== undefined) {
-      payload.pendingBossQuestion = pendingBossQuestion;
-    }
+    return body;
   }
-  if (to === 'failed') {
-    const lastError = normalizeErrorFull(context.lastError);
-    if (lastError !== undefined) {
-      payload.lastError = lastError;
-    }
-  }
-  return payload;
+  return [
+    CONTINUATION_PREAMBLE,
+    `Boss question:\n${input.pendingBossQuestion.question}`,
+    `Boss reply:\n${input.bossReply}`,
+    body,
+  ].join('\n\n');
 }
 
-// Captain-pane status lines for a root transition (PBRT-3 / PBRT-14):
-// the `→ guard` outcome line for the settling transition, then either
-// the awaitBossReply question + rider-less marker pair or the state's
-// entry line (with `lastError` data on `failed`).
-function statusesForState(
-  state: PlaybookState,
-  context: Record<string, unknown>,
-  event: unknown,
-): ScheduledStatus[] {
-  const to = state.stateId;
-  if (to === undefined || !CAPTAIN_PANE_STATES.has(to)) return [];
-  const statuses: ScheduledStatus[] = [];
-  const transitionLine = formatTransition(event);
-  if (transitionLine !== undefined) {
-    statuses.push({ message: transitionLine });
-  }
-  if (to === 'awaitBossReply') {
-    statuses.push(
-      { message: formatAwaitBossReplyQuestion(context) },
-      { message: formatAwaitBossReplyMarker(context) },
-    );
-  } else {
-    const entryLine = formatStateEntry(to);
-    if (entryLine !== undefined) {
-      const lastError =
-        to === 'failed' ? normalizeErrorCompact(context.lastError) : undefined;
-      statuses.push({
-        message: entryLine,
-        ...(lastError === undefined
-          ? {}
-          : {
-              data: snapshotJsonValue({ lastError }, 'failed status data'),
-            }),
-      });
-    }
-  }
-  return statuses;
-}
-
-// Internal export surface for tests. Not part of the stable public API;
-// the leading underscore signals "subject to change."
 export const _internal = {
   composePlayerPrompt,
-  resolvePlayerId,
-  adjudicate,
-  classifyBossText,
-  captainBridge,
-  STATE_LABELS,
-  stateMetadata,
-  pendingBossQuestionFromContext,
-  formatAwaitBossReplyQuestion,
-  formatAwaitBossReplyMarker,
-  formatStateEntry,
-  formatTransition,
-  formatClassification,
-  stateTelemetryPayload,
-  normalizeErrorCompact,
-  normalizeErrorFull,
-  normalizeEventForTelemetry,
   VERBATIM_PAYLOAD_FIELDS,
 };
 
-// The CODE-specific spec handed to the shared runtime factory
-// (slc/link.md §Output, DR-019). The generic machinery — actor wiring,
-// boundary tracing, Boss-turn lifecycle, nested-playbook bridge, and the
-// DR-014 parked-session snapshot capability — lives in
-// @sublang/playbook/xstate-runtime; this spec carries only what is
-// CODE-specific.
 const runtimeSpec: XStatePlaybookRuntimeSpec<CodePlaybookOptions> = {
   label: 'CODE',
-  snapshotOptions: snapshotCodePlaybookOptions,
-  resolvePlayerId: (input) => resolvePlayerId(input as unknown as PlayerInput),
-  composePlayerPrompt: (input) =>
-    composePlayerPrompt(input as unknown as PlayerInput),
-  buildJudgePrompt: CODE_ADJUDICATION.buildJudgePrompt,
-  extractRequiredFields,
+  compat: { artifactSchema: 1, runtimeAbi: RUNTIME_ABI },
+  snapshotOptions: snapshotCodeOptions,
+  entryEvent: { type: 'START_CODE', textField: 'callerInput' },
+  playerStates: {
+    runFirstPhase: {
+      player: 'Coder',
+      label:
+        'Coder is implementing one direct phase or committing a new intent record.',
+    },
+    runIrTask: {
+      player: 'Coder',
+      label: 'Coder is implementing exactly one unfinished intent-record task.',
+    },
+  },
+  placeholderFields: { 'coder-llm': 'coderPlayer' },
+  composePlayerPrompt: (input: PlaybookPlayerInput) =>
+    composePlayerPrompt(input as PlayerInput),
   verbatimPayloadFields: VERBATIM_PAYLOAD_FIELDS,
-  resumableStateIds: registeredResumableStateIds,
-  // PBRT-52: CODE's own ControlView context projection. Exactly the four
-  // closed-vocabulary classification members the FSM assigns itself, which
-  // are what a controller needs to see to describe or steer a CODE
-  // engagement. Everything else in `CodingContext` is deliberately absent:
-  // `coderPlayer` / `reviewerPlayer` / `committerPlayer` are the resolved
-  // host player roster, `intent` is an option value, and `irNumber`,
-  // `taskDescription`, `reviews`, `challenges`, and `lastResult` all carry
-  // player-authored text — all of which a session-Captain prompt must
-  // exclude, or may carry only as fenced quotes
-  // (CAPTAIN-9). A member added to `CodingContext`
-  // later stays private until it is named here.
-  controlContextFields: [
-    'workflow',
-    'changeOrigin',
-    'reviewSubject',
-    'afterReview',
-  ],
-  classifyBossText: (text, ports, signal, snapshotOrState, boundary) =>
-    classifyBossText(text, ports, signal, snapshotOrState, boundary),
-  classificationStatus: (event) => formatClassification(event.type),
-  statusesForState,
-  normalizeTransitionEvent: (event) =>
-    normalizeEventForTelemetry(event) as JsonValue | undefined,
+  controlContextFields: ['phase'],
+  transitionEventFields: ['callerInput', 'answer', 'questionId'],
 };
 
 const createPlaybookRuntime: PlaybookRuntimeFactory<CodePlaybookOptions> =