@sublang/playbook 15.0.0 → 16.0.0

package/reference/sdlc/pr.playbook/pr.playbook.ts

@@ -1,236 +1,182 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
-//
-// Generated by slc/link.md (FSM-to-Runtime linker).
-// Source FSM:    ./pr.fsm.ts
-// Role metadata: Coder→coder (canonical local role)
-// Boss event:    deterministic START_PR entry; exact Boss text becomes
-//                callerInput; pending Coder questions retain BOSS_REPLY
-// Adjudication:  LLM judge for the one Coder state; coderOutput is carried
-//                verbatim; pullRequest and pullRequestUrl are judge-authored
-//                semantic fields; every arm is governed `unchanged`
-// Scripts:       five DR-016 script states run through the shared factory's
-//                `sh -c` actor in the optional `cwd` option
-// Nested calls:  literal code target through the shared bridge
-// Compat:        artifact schema 3 / runtime ABI 1
-
+// Generated by slc/materialize-link.mjs; governed by the complete slc/link.md.
+// FSM: "./pr.fsm.js"; export: prMachine; strategies: shared defaults with labelled string relays and nested actors.
+import { prMachine as machine } from "./pr.fsm.js";
+import type { PlayerInput as SourcePlayerInput } from "./pr.fsm.js";
 import {
-  createXStatePlaybookRuntime,
-  composePlayerContinuation,
-  snapshotJsonValue,
+  createXStatePlaybookRuntime, snapshotJsonValue,
+  composePlayerContinuation, type XStatePromptIdentity,
   type PlaybookPlayerInput,
-  type XStatePlaybookRuntimeFactory,
   type XStatePlaybookRuntimeConstruction,
+  type XStatePlaybookRuntimeFactory,
   type XStatePlaybookRuntimeSpecV3,
 } from '@sublang/playbook/xstate-runtime';
-import {
-  prMachine,
-  type PlayerInput,
-  type PrInput,
-} from './pr.fsm.js';
-import type { PlaybookHostConstructionCapabilities } from '../code.playbook/playbook-captain.js';
-import type {
-  CaptainCallOptions,
-  CaptainResult,
-  JsonValue,
-  NormalizedError,
-  PlayerCallOptions,
-  PlaybookCallRequest,
-  PlaybookCallResult,
-  PlaybookCallStart,
-  PlaybookControlReceipt,
-  PlaybookControlView,
-  PlaybookPendingCall,
-  PlaybookPorts,
-  PlaybookRunResult,
-  PlaybookRuntime,
-  PlaybookRuntimeFactory,
-  PlaybookRuntimeSnapshot,
-  PlaybookSession,
-  PlaybookState,
-  PlaybookStateValue,
-  PlaybookTraceEvent,
-  PlaybookTraceType,
+export type {
   PlayerResult,
+  PlayerCallOptions,
   PlayerSessionStore,
-} from '@sublang/playbook/runtime';
-
-export type {
-  CaptainCallOptions,
   CaptainResult,
+  CaptainCallOptions,
   JsonValue,
   NormalizedError,
-  PlayerCallOptions,
   PlaybookCallRequest,
   PlaybookCallResult,
   PlaybookCallStart,
-  PlaybookControlReceipt,
-  PlaybookControlView,
+  PlaybookStateValue,
+  PlaybookState,
   PlaybookPendingCall,
-  PlaybookPorts,
   PlaybookRunResult,
   PlaybookRuntime,
   PlaybookRuntimeFactory,
   PlaybookRuntimeSnapshot,
   PlaybookSession,
-  PlaybookState,
-  PlaybookStateValue,
+  PlaybookPorts,
   PlaybookTraceEvent,
   PlaybookTraceType,
-  PlayerResult,
-  PlayerSessionStore,
-};
-
-/**
- * PR's per-run options. The machine reads no input of its own; the one
- * linker-owned option is the working directory its five script states run
- * in (slc/link.md §Script execution). Absent, the process working directory.
- */
-export type PrPlaybookOptions = PrInput & {
-  readonly cwd?: string;
-};
-export type PrPlaybookHostCapabilities =
-  PlaybookHostConstructionCapabilities &
-    XStatePlaybookRuntimeConstruction<PrPlaybookOptions, object>['hostCapabilities'];
+  PlaybookControlReceipt,
+  PlaybookControlView,
+} from '@sublang/playbook/runtime';
 
-const OPTION_KEYS = new Set(['cwd']);
-const PLACEHOLDER = /<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>/g;
+export interface PlaybookRuntimeOptions {
+  readonly "cwd"?: string;
+}
+export type PlaybookHostCapabilities = XStatePlaybookRuntimeConstruction<
+  PlaybookRuntimeOptions, { readonly authority: object }
+>['hostCapabilities'];
 
-const VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string> = new Set([
-  'coderOutput',
+const OPTION_SCHEMA = {
+  "cwd": {
+    "type": "string",
+    "required": false
+  }
+} as const;
+const INPUT_MAPPING = {} as const;
+const RESUMABLE_STATE_IDS: ReadonlySet<string> = new Set([
+  "openPullRequest"
 ]);
-// Every failure terminal leaves the delivery unfinished: no pull request is
-// guaranteed to exist after notPublished, the three fix terminals leave it
-// open, and mergeRefused leaves it in the state GitHub reports.
 const UNFINISHED_FINAL_STATE_IDS: ReadonlySet<string> = new Set([
-  'notPublished',
-  'fixFailed',
-  'fixNotPublished',
-  'checksStillFailing',
-  'mergeRefused',
+  "notPublished",
+  "fixFailed",
+  "fixNotPublished",
+  "checksFailed",
+  "mergeUnconfirmed"
 ]);
-
-function snapshotPrOptions(value: unknown): PrPlaybookOptions {
-  const captured = snapshotJsonValue(value, 'PR runtime options');
-  if (
-    captured === null ||
-    typeof captured !== 'object' ||
-    Array.isArray(captured)
-  ) {
-    throw new TypeError('PR runtime options must be an object');
+const VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string> = new Set([
+  "coderOutput"
+]);
+export function validateOptions(value: unknown): PlaybookRuntimeOptions {
+  const captured = snapshotJsonValue(value === undefined ? {} : value, "PR runtime options");
+  if (captured === null || typeof captured !== 'object' || Array.isArray(captured)) {
+    throw new TypeError("PR runtime options must be an object");
   }
-  const record = captured as Readonly<Record<string, JsonValue>>;
-  for (const [key, option] of Object.entries(record)) {
-    if (!OPTION_KEYS.has(key)) {
-      throw new TypeError(`PR runtime options.${key} is not declared`);
-    }
-    if (typeof option !== 'string' || option.length === 0) {
-      throw new TypeError(`PR runtime options.${key} must be a non-empty string`);
+  const fields = captured as Readonly<Record<string, unknown>>;
+  for (const key of Object.keys(captured)) {
+    if (!Object.hasOwn(OPTION_SCHEMA, key)) throw new TypeError("PR runtime options." + key + ' is not declared');
+  }
+  for (const [key, schema] of Object.entries(OPTION_SCHEMA) as [string, { type: string; required: boolean }][]) {
+    if (!Object.hasOwn(captured, key)) {
+      if (schema.required) throw new TypeError("PR runtime options." + key + ' is required');
+    } else if (typeof fields[key] !== schema.type || (schema.type === 'number' && !Number.isFinite(fields[key]))) {
+      throw new TypeError("PR runtime options." + key + ' must be a ' + schema.type);
     }
   }
-  return captured as unknown as PrPlaybookOptions;
+  return captured as unknown as PlaybookRuntimeOptions;
 }
-
-function placeholderField(token: string): string {
-  if (token === '#') return 'irNumber';
-  return token.replace(/-([A-Za-z0-9_$])/g, (_match, next: string) =>
-    next.toUpperCase(),
-  );
-}
-
-function quotedContinuation(value: string): string {
-  return value.replaceAll('\n', '\n> ');
-}
-
-/**
- * Preserve the authored Markdown quote marker around every line of the
- * relayed caller input. The generic composer preserves the marker itself;
- * PR's override additionally keeps a multiline value inside that quote.
- */
-function composePlayerPrompt(input: PlayerInput, resuming = false): string {
-  const fields = input as unknown as Record<string, unknown>;
-  const body = input.prompt.replace(
-    PLACEHOLDER,
-    (match: string, token: string, offset: number, source: string) => {
-      const value = fields[placeholderField(token)];
+function renderPlayerPrompt(input: SourcePlayerInput, promptIdentity: XStatePromptIdentity, resuming = false): string {
+  const fields = input as unknown as Readonly<Record<string, unknown>>;
+  const mapping: Readonly<Record<string, string>> = {};
+  const identities: Readonly<Record<string, string>> = {};
+  const omitted = new Set<string>([]);
+  const fieldFor = (token: string): string => Object.hasOwn(mapping, token) ? mapping[token]! : (token === '#' ? 'irNumber' : token.replace(/-([A-Za-z0-9_$])/g, (_match: string, next: string) => next.toUpperCase()));
+  const parts = input.prompt.split(/(\r?\n)/);
+  let body = '';
+  for (let index = 0; index < parts.length; index += 2) {
+    const line = parts[index]!;
+    if (omitted.has(line)) {
+      const token = /<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>$/.exec(line)![1]!;
+      if (fields[fieldFor(token)] === '') continue;
+    }
+    body += line.replace(/<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>/g, (match: string, token: string): string => {
+      const value = Object.hasOwn(identities, token) ? promptIdentity(identities[token]!) : fields[fieldFor(token)];
       if (typeof value !== 'string') return match;
-      const lineStart = source.lastIndexOf('\n', offset - 1) + 1;
-      return source.slice(lineStart, offset).startsWith('> ')
-        ? quotedContinuation(value)
-        : value;
-    },
-  );
+      return line.startsWith('> ') ? value.replace(/\r?\n/g, (ending: string) => ending + '> ') : value;
+    }) + (parts[index + 1] ?? '');
+  }
   return composePlayerContinuation(input, body, resuming);
 }
-
-export const _internal = {
-  composePlayerPrompt,
-  VERBATIM_PAYLOAD_FIELDS,
-  UNFINISHED_FINAL_STATE_IDS,
-};
-
+const composePlayerPrompt = (input: PlaybookPlayerInput, promptIdentity: XStatePromptIdentity, resuming?: boolean): string =>
+  renderPlayerPrompt(input as SourcePlayerInput, promptIdentity, resuming);
 const runtimeSpec = {
-  label: 'PR',
-  // 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: 3, runtimeAbi: 1 },
-  snapshotOptions: snapshotPrOptions,
-  entryEvent: {
-    type: 'START_PR',
-    textField: 'callerInput',
-    // `startPr` 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',
+  composePlayerPrompt,
+  ...{
+  "label": "PR",
+  "compat": {
+    "artifactSchema": 3,
+    "runtimeAbi": 1
   },
-  roleStates: {
-    openPullRequest: {
-      role: 'coder',
-      label: 'Coder is publishing the branch and opening its pull request.',
-    },
+  "entryEvent": {
+    "type": "START_PR",
+    "textField": "callerInput",
+    "contextField": "callerInput"
   },
-  // DR-050: PR owns no repository commit — pushing a branch and opening a
-  // pull request move only remote-tracking refs and forge state, so every
-  // Coder outcome is governed with the `unchanged` repository disposition.
-  // The pull request number and URL are judge-authored semantic fields; the
-  // Coder's report on a refused publication is carried verbatim.
-  outcomeAuthority: {
-    governedPlayerStates: {
-      openPullRequest: {
-        opened: {
-          fields: { pullRequest: 'semantic', pullRequestUrl: 'semantic' },
-          repositoryDisposition: 'unchanged',
-        },
-        notPublished: {
-          fields: { coderOutput: 'presentation' },
-          repositoryDisposition: 'unchanged',
+  "bossEvents": [],
+  "roleStates": {
+    "openPullRequest": {
+      "role": "coder",
+      "label": "Coder is publishing the branch and opening its pull request without changing any file or making any commit."
+    }
+  },
+  "outcomeAuthority": {
+    "governedPlayerStates": {
+      "openPullRequest": {
+        "opened": {
+          "fields": {
+            "pullRequest": "semantic",
+            "pullRequestUrl": "semantic"
+          },
+          "repositoryDisposition": "unchanged"
         },
-        needsBossReply: {
-          fields: { question: 'presentation' },
-          repositoryDisposition: 'unchanged',
+        "notPublished": {
+          "fields": {
+            "coderOutput": "presentation"
+          },
+          "repositoryDisposition": "unchanged"
         },
-      },
-    },
+        "needsBossReply": {
+          "fields": {
+            "question": "presentation"
+          },
+          "repositoryDisposition": "unchanged"
+        }
+      }
+    }
   },
-  composePlayerPrompt: (input: PlaybookPlayerInput, _identity, resuming) =>
-    composePlayerPrompt(input as PlayerInput, resuming),
+  "placeholderFields": {},
+  "transitionEventFields": [
+    "callerInput",
+    "answer",
+    "questionId"
+  ],
+  "controlContextFields": []
+},
+  snapshotOptions: validateOptions,
+  machineInput: (options: PlaybookRuntimeOptions) => Object.fromEntries(
+    Object.entries(INPUT_MAPPING).filter(([, key]) => options[key as keyof PlaybookRuntimeOptions] !== undefined)
+      .map(([field, key]) => [field, options[key as keyof PlaybookRuntimeOptions]]),
+  ),
   verbatimPayloadFields: VERBATIM_PAYLOAD_FIELDS,
-  controlContextFields: [],
+  resumableStateIds: RESUMABLE_STATE_IDS,
   unfinishedFinalStateIds: UNFINISHED_FINAL_STATE_IDS,
-  transitionEventFields: ['callerInput', 'answer', 'questionId'],
-} satisfies XStatePlaybookRuntimeSpecV3<PrPlaybookOptions>;
+} satisfies XStatePlaybookRuntimeSpecV3<PlaybookRuntimeOptions>;
 
+export const _internal = {
+  composePlayerPrompt,
+  RESUMABLE_STATE_IDS,
+  UNFINISHED_FINAL_STATE_IDS,
+  VERBATIM_PAYLOAD_FIELDS,
+};
 const createPlaybookRuntime: XStatePlaybookRuntimeFactory<
-  XStatePlaybookRuntimeConstruction<
-    PrPlaybookOptions,
-    PrPlaybookHostCapabilities
-  >,
-  3
-> = createXStatePlaybookRuntime<
-  PrPlaybookOptions,
-  PrPlaybookHostCapabilities
->(prMachine, runtimeSpec);
-
+  XStatePlaybookRuntimeConstruction<PlaybookRuntimeOptions, PlaybookHostCapabilities>, 3
+> = createXStatePlaybookRuntime<PlaybookRuntimeOptions, PlaybookHostCapabilities>(machine, runtimeSpec);
 export default createPlaybookRuntime;

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

@@ -1,4 +1,5 @@
-import { type PrPlaybookHostCapabilities, type PlaybookRuntime } from './pr.playbook.js';
+import type { PlaybookHostConstructionCapabilities } from '../code.playbook/playbook-captain.js';
+import { type PlaybookHostCapabilities, type PlaybookRuntime } from './pr.playbook.js';
 export interface PlaybookSummaryPolicy {
     stateCountLabels: Readonly<Record<string, string>>;
     copyPasteGuardNames: readonly string[];
@@ -24,7 +25,7 @@ export interface PrPlaybookRegistryEntry {
     concurrentRoleSets: readonly [];
     summaryPolicy: PlaybookSummaryPolicy;
     validateOptions(optionSlice: unknown): PrOptions;
-    createRuntime(options: PrOptions, hostCapabilities: PrPlaybookHostCapabilities): PlaybookRuntime;
+    createRuntime(options: PrOptions, hostCapabilities: PlaybookHostConstructionCapabilities & PlaybookHostCapabilities): PlaybookRuntime;
 }
 export declare const prStateCountLabels: {
     readonly openPullRequest: "publication round";

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

@@ -1,8 +1,9 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 
+import type { PlaybookHostConstructionCapabilities } from '../code.playbook/playbook-captain.js';
 import createPlaybookRuntime, {
-  type PrPlaybookHostCapabilities,
+  type PlaybookHostCapabilities,
   type PlaybookRuntime,
 } from './pr.playbook.js';
 
@@ -35,7 +36,8 @@ export interface PrPlaybookRegistryEntry {
   validateOptions(optionSlice: unknown): PrOptions;
   createRuntime(
     options: PrOptions,
-    hostCapabilities: PrPlaybookHostCapabilities,
+    hostCapabilities: PlaybookHostConstructionCapabilities &
+      PlaybookHostCapabilities,
   ): PlaybookRuntime;
 }
 

package/reference/sdlc/review.md

@@ -57,7 +57,7 @@ Captain shall append the round’s context in quotes (`>`):
 > Original request: <caller-input>
 > Coder output: <coder-output>
 
-At the start of *every* review round, Captain shall relay to Reviewer the original intent, the review scope and context, the exact repository revision being evaluated, any Coder feedback from the preceding round, and any relevant run results, in quotes (`>`) after the instruction.
+At the start of *every* review round, Captain shall relay to Reviewer the original intent, the review scope and context, any Coder feedback from the preceding round, and any relevant run results, in quotes (`>`) after the instruction.
 
 At the start of *every* review round, Captain shall append the following instruction to the end of the prompt:
 
@@ -83,7 +83,7 @@ Consult @specs/meta.md for spec requirements if needed; verify affected specs fo
 Finding numbers are references within this review only.
 No review transition shall depend on numbering or any fixed presentation format of either player's reply.
 
-When Reviewer raises or keeps any finding, Captain shall relay the original intent, the review scope and context, the exact repository revision being evaluated, the Reviewer's findings, and any relevant run results to Coder, in quotes (`>`), along with the following prompt:
+When Reviewer raises or keeps any finding, Captain shall relay the original intent, the review scope and context, the Reviewer's findings, and any relevant run results to Coder, in quotes (`>`), along with the following prompt:
 
 > Original request: <caller-input>
 > Reviewer findings: <reviewer-output>
@@ -109,7 +109,7 @@ Report every disposition, all relevant run results, and every rebuttal.
 
 Captain shall use the repository-effect receipt as the authoritative identity of any review-fix commit.
 
-When Coder makes a new commit or decides to reject all findings, Captain shall relay the above required context to Reviewer and begin the next review round.
+When Coder makes a new commit or decides to reject all findings, Captain shall relay the round's context above to Reviewer and begin the next review round.
 Reviewer shall read the context information and follow the corresponding instructions.
 Rounds continue until Reviewer affirmatively reports that the requested review is complete and no unsettled findings remain.
 A progress report, status update, or promise of a later result supports no review outcome.