@sublang/playbook 13.1.0 → 13.3.0

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

@@ -0,0 +1,155 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
+
+# PR: Pull-Request Delivery Workflow
+
+Roles:
+
+- Coder
+
+The caller supplies the original request including the issue it names, if any; the issue summary; the branch to deliver and the base revision it was created from; the last `code`-owned commit and the exact evaluated repository revision; and optional relevant context.
+`pr` delivers a reviewed branch into the repository default branch through a GitHub pull request: it publishes the branch, waits for the pull request's checks, fixes red checks through playbook `code` no more than once, and merges.
+It changes no files and owns no repository commit; the one fix it may request is owned by `code`.
+The check waits, the fix publication, the merge, and the local update are mechanical steps: each runs one fixed command whose exit status alone decides its two outcomes, reads no conversation, and produces no prose.
+`gh` infers the pull request from the checked-out branch, so no mechanical step needs a runtime value.
+
+## Coder
+
+### PR-1
+
+When the caller gives its input, Captain shall relay the complete caller input in quotes (`>`) to Coder, along with the following instruction:
+
+> > Original request: <caller-input>
+>
+> Publish the branch and open its pull request without changing any file or making any commit.
+> Confirm that the working tree is clean and that the checked-out branch is the branch to deliver, not the repository default branch.
+> Push the branch to the repository's GitHub remote with its upstream set; never force-push.
+> If an open pull request for this branch already exists, use it; otherwise open one against the repository default branch with `gh pr create`.
+> Give the pull request a title naming the change and a body with a summary of what changed and why from the base revision to the last commit, the verification the commits report, and a `Closes #N` line for issue number N when the request names one.
+> Report the pull request number and URL exactly.
+> If the working tree is not clean, the checked-out branch is wrong, the push is rejected, or the pull request cannot be opened, open nothing further and report the failure with its reason.
+
+Results:
+- `opened`: Coder pushed the branch with its upstream set and reported the open pull request for it. Output shall include `pullRequest: <pull request number>` and `pullRequestUrl: <pull request URL>`.
+- `notPublished`: Coder reported that the branch could not be published or its pull request could not be opened, with the reason. Output shall include `coderOutput: <verbatim final text>`.
+
+Workflow outcomes:
+- The result has two semantic outcomes: opened and not published.
+- Each outcome requires affirmative support in Coder's result, and no outcome depends on a fixed presentation format of Coder's reply.
+- Every outcome keeps the repository exact: pushing a branch and opening a pull request change neither HEAD's commit nor the working tree.
+- For not published, `pr` fails and reports Coder's complete result with its reason to its caller.
+
+## Checks, the one fix, and the merge
+
+### PR-2
+
+When the pull request is open and no fix has been attempted, Captain shall run:
+
+> n=0
+> while gh pr checks 2>&1 | grep -q 'no checks reported'; do
+> n=$((n + 1))
+> [ "$n" -ge 6 ] && exit 0
+> sleep 10
+> done
+> gh pr checks --watch --fail-fast >/dev/null 2>&1
+
+Results:
+- `checksPassed`: The command exited with status zero: the pull request's checks passed, or the repository still reported no checks after a brief wait for them to register.
+- `checksFailed`: The command exited with a nonzero status: the pull request's checks failed.
+
+Workflow outcomes:
+- The wait has exactly two outcomes decided by the command's exit status alone: checks passed on status zero and checks failed otherwise.
+- A pull request whose repository still reports no checks after a brief wait for them to register counts as passed.
+- Checks passed continues with the merge; checks failed continues with the one `code` fix attempt.
+
+### PR-3
+
+When the checks fail before any fix attempt, Captain shall call playbook `code`:
+
+> > Original request: <caller-input>
+> > Pull request: <pull-request-url>
+> > Coding request: The pull request's checks are red on the checked-out branch. Inspect the failing checks with `gh pr checks` and `gh run view --log-failed`, fix their cause on this branch with a minimal change, and make the checks pass.
+
+Workflow outcomes:
+- `pr` makes no more than one fix attempt.
+- Only after `code` succeeds does `pr` publish the fix and wait for the checks again.
+- An authored `code` abort or failure, or a terminal `code` result that does not prove its success, terminates `pr` with that canonical result relayed and the pull request left open.
+- Any other nested-call error parks `pr` as failed and retains the control-plane error.
+
+### PR-4
+
+When `code` succeeds, Captain shall run:
+
+> git push || exit 1
+> n=0
+> until [ "$(gh pr view --json headRefOid --jq .headRefOid 2>/dev/null)" = "$(git rev-parse HEAD)" ]; do
+> n=$((n + 1))
+> [ "$n" -ge 12 ] && exit 1
+> sleep 5
+> done
+
+Results:
+- `fixPublished`: The command exited with status zero: the fix is pushed and the pull request's head is the pushed commit.
+- `fixNotPublished`: The command exited with a nonzero status: the push was rejected or the pull request's head did not advance to the pushed commit.
+
+Workflow outcomes:
+- The publication has exactly two outcomes decided by the exit status alone: fix published on status zero, once the pull request's head is the pushed commit, and fix not published otherwise.
+- Fix not published is an authored failure that leaves the pull request open.
+
+### PR-5
+
+When the fix is published, Captain shall run:
+
+> n=0
+> while gh pr checks 2>&1 | grep -q 'no checks reported'; do
+> n=$((n + 1))
+> [ "$n" -ge 6 ] && exit 0
+> sleep 10
+> done
+> gh pr checks --watch --fail-fast >/dev/null 2>&1
+
+Results:
+- `checksPassed`: The command exited with status zero: the pull request's checks passed after the fix, or the repository still reported no checks after a brief wait for them to register.
+- `checksStillFailing`: The command exited with a nonzero status: the pull request's checks are still failing after the one fix attempt.
+
+Workflow outcomes:
+- This wait has exactly two outcomes decided by the exit status alone: checks passed on status zero and checks still failing otherwise.
+- Checks still failing is an authored failure that leaves the pull request open; there is no second fix attempt.
+
+### PR-6
+
+When the checks pass, before or after the one fix attempt, Captain shall run:
+
+> gh pr merge --merge --delete-branch --match-head-commit "$(git rev-parse HEAD)"
+
+Results:
+- `merged`: The command exited with status zero: the pull request is merged with a merge commit on the repository default branch, the remote and local branch are deleted, and the local default branch is checked out.
+- `mergeRefused`: The command exited with a nonzero status: GitHub refused the merge, or the merge landed but the local switch to the default branch or the branch deletion failed.
+
+Workflow outcomes:
+- The merge creates a merge commit on the repository default branch, deletes the remote and local branch, and checks out the local default branch; GitHub closes the linked issue on merge.
+- The merge has exactly two outcomes decided by the exit status alone: merged on status zero and merge refused otherwise.
+- Merge refused is an authored failure that leaves the pull request in the state GitHub reports: GitHub refused the merge for a conflict, a branch protection, a forbidden merge method, or a head that moved, or the merge landed but the local switch to the default branch or the branch deletion failed.
+
+### PR-7
+
+When the pull request is merged, Captain shall run:
+
+> git pull --ff-only
+
+Results:
+- `localDefaultUpdated`: The command exited with status zero: the local default branch is fast-forwarded to the merged head.
+- `localDefaultNotUpdated`: The command exited with a nonzero status: the local default branch was not fast-forwarded to the merged head.
+
+Workflow outcomes:
+- The update has exactly two outcomes decided by the exit status alone: local default updated on status zero and local default not updated otherwise.
+- Both complete `pr`: the pull request is merged either way, and the result states whether the local default branch was fast-forwarded to the merged head.
+- On completion, `pr` returns the pull request number and URL, the fact that the pull request is merged, and whether the local default branch was fast-forwarded to the merged head.
+
+## Optimizations
+
+- PR-2: captain → script
+- PR-4: captain → script
+- PR-5: captain → script
+- PR-6: captain → script
+- PR-7: captain → script

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

@@ -0,0 +1,27 @@
+import { type XStatePlaybookRuntimeFactory, type XStatePlaybookRuntimeConstruction } from '@sublang/playbook/xstate-runtime';
+import { 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, 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, };
+/**
+ * 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'];
+/**
+ * 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.
+ */
+declare function composePlayerPrompt(input: PlayerInput, resuming?: boolean): string;
+export declare const _internal: {
+    composePlayerPrompt: typeof composePlayerPrompt;
+    VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string>;
+    UNFINISHED_FINAL_STATE_IDS: ReadonlySet<string>;
+};
+declare const createPlaybookRuntime: XStatePlaybookRuntimeFactory<XStatePlaybookRuntimeConstruction<PrPlaybookOptions, PrPlaybookHostCapabilities>, 3>;
+export default createPlaybookRuntime;

package/reference/sdlc/pr.playbook/pr.playbook.js

@@ -0,0 +1,133 @@
+// 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
+import { createXStatePlaybookRuntime, composePlayerContinuation, snapshotJsonValue, } from '@sublang/playbook/xstate-runtime';
+import { prMachine, } from './pr.fsm.js';
+const OPTION_KEYS = new Set(['cwd']);
+const PLACEHOLDER = /<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>/g;
+const VERBATIM_PAYLOAD_FIELDS = new Set([
+    'coderOutput',
+]);
+// Every failure terminal leaves the delivery unfinished: no pull request is
+// guaranteed to exist after notPublished, and the other four leave it open.
+const UNFINISHED_FINAL_STATE_IDS = new Set([
+    'notPublished',
+    'fixFailed',
+    'fixNotPublished',
+    'checksStillFailing',
+    'mergeRefused',
+]);
+function snapshotPrOptions(value) {
+    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 record = captured;
+    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`);
+        }
+    }
+    return captured;
+}
+function placeholderField(token) {
+    if (token === '#')
+        return 'irNumber';
+    return token.replace(/-([A-Za-z0-9_$])/g, (_match, next) => next.toUpperCase());
+}
+function quotedContinuation(value) {
+    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, resuming = false) {
+    const fields = input;
+    const body = input.prompt.replace(PLACEHOLDER, (match, token, offset, source) => {
+        const value = fields[placeholderField(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 composePlayerContinuation(input, body, resuming);
+}
+export const _internal = {
+    composePlayerPrompt,
+    VERBATIM_PAYLOAD_FIELDS,
+    UNFINISHED_FINAL_STATE_IDS,
+};
+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',
+    },
+    roleStates: {
+        openPullRequest: {
+            role: 'coder',
+            label: 'Coder is publishing the branch and opening its pull request.',
+        },
+    },
+    // 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',
+                },
+                needsBossReply: {
+                    fields: { question: 'presentation' },
+                    repositoryDisposition: 'unchanged',
+                },
+            },
+        },
+    },
+    composePlayerPrompt: (input, _identity, resuming) => composePlayerPrompt(input, resuming),
+    verbatimPayloadFields: VERBATIM_PAYLOAD_FIELDS,
+    controlContextFields: [],
+    unfinishedFinalStateIds: UNFINISHED_FINAL_STATE_IDS,
+    transitionEventFields: ['callerInput', 'answer', 'questionId'],
+};
+const createPlaybookRuntime = createXStatePlaybookRuntime(prMachine, runtimeSpec);
+export default createPlaybookRuntime;

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

@@ -0,0 +1,235 @@
+// 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
+
+import {
+  createXStatePlaybookRuntime,
+  composePlayerContinuation,
+  snapshotJsonValue,
+  type PlaybookPlayerInput,
+  type XStatePlaybookRuntimeFactory,
+  type XStatePlaybookRuntimeConstruction,
+  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,
+  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,
+};
+
+/**
+ * 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'];
+
+const OPTION_KEYS = new Set(['cwd']);
+const PLACEHOLDER = /<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>/g;
+
+const VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string> = new Set([
+  'coderOutput',
+]);
+// Every failure terminal leaves the delivery unfinished: no pull request is
+// guaranteed to exist after notPublished, and the other four leave it open.
+const UNFINISHED_FINAL_STATE_IDS: ReadonlySet<string> = new Set([
+  'notPublished',
+  'fixFailed',
+  'fixNotPublished',
+  'checksStillFailing',
+  'mergeRefused',
+]);
+
+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 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`);
+    }
+  }
+  return captured as unknown as PrPlaybookOptions;
+}
+
+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)];
+      if (typeof value !== 'string') return match;
+      const lineStart = source.lastIndexOf('\n', offset - 1) + 1;
+      return source.slice(lineStart, offset).startsWith('> ')
+        ? quotedContinuation(value)
+        : value;
+    },
+  );
+  return composePlayerContinuation(input, body, resuming);
+}
+
+export const _internal = {
+  composePlayerPrompt,
+  VERBATIM_PAYLOAD_FIELDS,
+  UNFINISHED_FINAL_STATE_IDS,
+};
+
+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',
+  },
+  roleStates: {
+    openPullRequest: {
+      role: 'coder',
+      label: 'Coder is publishing the branch and opening its pull request.',
+    },
+  },
+  // 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',
+        },
+        needsBossReply: {
+          fields: { question: 'presentation' },
+          repositoryDisposition: 'unchanged',
+        },
+      },
+    },
+  },
+  composePlayerPrompt: (input: PlaybookPlayerInput, _identity, resuming) =>
+    composePlayerPrompt(input as PlayerInput, resuming),
+  verbatimPayloadFields: VERBATIM_PAYLOAD_FIELDS,
+  controlContextFields: [],
+  unfinishedFinalStateIds: UNFINISHED_FINAL_STATE_IDS,
+  transitionEventFields: ['callerInput', 'answer', 'questionId'],
+} satisfies XStatePlaybookRuntimeSpecV3<PrPlaybookOptions>;
+
+const createPlaybookRuntime: XStatePlaybookRuntimeFactory<
+  XStatePlaybookRuntimeConstruction<
+    PrPlaybookOptions,
+    PrPlaybookHostCapabilities
+  >,
+  3
+> = createXStatePlaybookRuntime<
+  PrPlaybookOptions,
+  PrPlaybookHostCapabilities
+>(prMachine, runtimeSpec);
+
+export default createPlaybookRuntime;

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

@@ -0,0 +1,40 @@
+import { type PrPlaybookHostCapabilities, type PlaybookRuntime } from './pr.playbook.js';
+export interface PlaybookSummaryPolicy {
+    stateCountLabels: Readonly<Record<string, string>>;
+    copyPasteGuardNames: readonly string[];
+    savedCountsLine(counts: {
+        interruptions: number;
+        copyPastes: number;
+    }, rounds: number): string;
+}
+export type PrOptions = Readonly<Record<string, never>>;
+export interface PrPlaybookRegistryEntry {
+    id: 'pr';
+    command: 'pr';
+    intent: string;
+    artifactSchema: 3;
+    runtimeProfile: {
+        readonly kind: 'shared-factory';
+        readonly compat: {
+            readonly artifactSchema: 3;
+            readonly runtimeAbi: number;
+        };
+    };
+    requiredRoleIds: readonly ['coder'];
+    concurrentRoleSets: readonly [];
+    summaryPolicy: PlaybookSummaryPolicy;
+    validateOptions(optionSlice: unknown): PrOptions;
+    createRuntime(options: PrOptions, hostCapabilities: PrPlaybookHostCapabilities): PlaybookRuntime;
+}
+export declare const prStateCountLabels: {
+    readonly openPullRequest: "publication round";
+};
+export declare const prCopyPasteGuardNames: readonly ["opened"];
+export declare function prSavedCountsLine(counts: {
+    interruptions: number;
+    copyPastes: number;
+}, rounds: number): string;
+export declare const prSummaryPolicy: PlaybookSummaryPolicy;
+export declare function validatePrOptions(optionSlice: unknown): PrOptions;
+export declare const prPlaybookRegistryEntry: PrPlaybookRegistryEntry;
+export default prPlaybookRegistryEntry;

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

@@ -0,0 +1,68 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+import createPlaybookRuntime from './pr.playbook.js';
+// CODE owns and labels the rounds of the one fix it may make. PR's suspended
+// call state only delegates to that child and must not double-count its
+// rounds; its script states run no agent at all. Only the Coder publication
+// round is PR's own.
+export const prStateCountLabels = {
+    openPullRequest: 'publication round',
+};
+export const prCopyPasteGuardNames = ['opened'];
+function countNoun(count, singular, plural = `${singular}s`) {
+    return `${count} ${count === 1 ? singular : plural}`;
+}
+export function prSavedCountsLine(counts, rounds) {
+    return [
+        'Saved you',
+        countNoun(counts.interruptions, 'interruption'),
+        'and',
+        countNoun(counts.copyPastes, 'copy-paste'),
+        'across',
+        countNoun(rounds, 'round'),
+        'of delivery.',
+    ].join(' ');
+}
+export const prSummaryPolicy = {
+    stateCountLabels: prStateCountLabels,
+    copyPasteGuardNames: prCopyPasteGuardNames,
+    savedCountsLine: prSavedCountsLine,
+};
+export function validatePrOptions(optionSlice) {
+    if (optionSlice === undefined)
+        return Object.freeze({});
+    if (optionSlice === null ||
+        typeof optionSlice !== 'object' ||
+        Array.isArray(optionSlice)) {
+        throw new Error('captain.options.playbooks.pr.options must be an object');
+    }
+    const keys = Object.keys(optionSlice);
+    if (keys.length > 0) {
+        throw new Error(`Unknown config field captain.options.playbooks.pr.options.${keys[0]}`);
+    }
+    return Object.freeze({});
+}
+export const prPlaybookRegistryEntry = {
+    id: 'pr',
+    command: 'pr',
+    intent: 'publish a reviewed branch as a pull request, wait for its checks, fix red checks once through code, and merge it',
+    artifactSchema: 3,
+    runtimeProfile: Object.freeze({
+        kind: 'shared-factory',
+        compat: createPlaybookRuntime.compat,
+    }),
+    requiredRoleIds: ['coder'],
+    concurrentRoleSets: [],
+    summaryPolicy: prSummaryPolicy,
+    validateOptions: validatePrOptions,
+    createRuntime(options, hostCapabilities) {
+        // The five script states run `gh` and `git` in the repository the host
+        // governs: the linked `cwd` option is composed here from the host's
+        // authority working directory (DR-040 §2), never from configuration.
+        return createPlaybookRuntime({
+            configuredOptions: { ...options, cwd: hostCapabilities.authority.cwd },
+            hostCapabilities,
+        });
+    },
+};
+export default prPlaybookRegistryEntry;