@sublang/playbook 13.1.0 → 13.3.0

package/reference/sdlc/branch.playbook/branch.playbook.ts

@@ -0,0 +1,217 @@
+// 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:    ./branch.fsm.ts
+// Role metadata: Coder→coder (canonical local role)
+// Boss event:    deterministic START_BRANCH entry; exact Boss text becomes
+//                callerInput; pending Coder questions retain BOSS_REPLY
+// Adjudication:  LLM judge for the one Coder state; coderOutput is carried
+//                verbatim; baseRevision is receipt-owned effect evidence —
+//                the unchanged receipt's observed HEAD — never taken from
+//                Coder's prose
+// 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 {
+  branchMachine,
+  type BranchInput,
+  type PlayerInput,
+} from './branch.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,
+};
+
+export type BranchPlaybookOptions = BranchInput;
+export type BranchPlaybookHostCapabilities =
+  PlaybookHostConstructionCapabilities &
+    XStatePlaybookRuntimeConstruction<BranchPlaybookOptions, object>['hostCapabilities'];
+
+const PLACEHOLDER = /<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>/g;
+
+const VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string> = new Set([
+  'coderOutput',
+]);
+const UNFINISHED_FINAL_STATE_IDS: ReadonlySet<string> = new Set(['refused']);
+
+function snapshotBranchOptions(value: unknown): BranchPlaybookOptions {
+  const captured = snapshotJsonValue(value, 'BRANCH runtime options');
+  if (
+    captured === null ||
+    typeof captured !== 'object' ||
+    Array.isArray(captured)
+  ) {
+    throw new TypeError('BRANCH runtime options must be an object');
+  }
+  const record = captured as Readonly<Record<string, JsonValue>>;
+  for (const key of Object.keys(record)) {
+    throw new TypeError(`BRANCH runtime options.${key} is not declared`);
+  }
+  return captured as unknown as BranchPlaybookOptions;
+}
+
+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 authored Markdown quote markers around every line of relayed
+ * runtime text. The generic composer preserves the marker itself; BRANCH's
+ * override additionally keeps a multiline caller input 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;
+      const literal = source.slice(lineStart, offset);
+      return literal.startsWith('> ') ? quotedContinuation(value) : value;
+    },
+  );
+  return composePlayerContinuation(input, body, resuming);
+}
+
+export const _internal = {
+  composePlayerPrompt,
+  VERBATIM_PAYLOAD_FIELDS,
+  UNFINISHED_FINAL_STATE_IDS,
+};
+
+const runtimeSpec = {
+  label: 'BRANCH',
+  // 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: snapshotBranchOptions,
+  entryEvent: {
+    type: 'START_BRANCH',
+    textField: 'callerInput',
+    // `startBranch` 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: {
+    createBranch: {
+      role: 'coder',
+      label:
+        'Coder is reading the named issue and creating and checking out a new branch at the current commit.',
+    },
+  },
+  // DR-050: BRANCH owns no repository commit — every Coder outcome, including
+  // the Boss question for an ambiguous request, is governed with the
+  // `unchanged` repository disposition, because a new branch at the current
+  // commit changes neither HEAD's OID nor the worktree projection.
+  outcomeAuthority: {
+    governedPlayerStates: {
+      createBranch: {
+        branched: {
+          fields: {
+            branch: 'semantic',
+            // DR-045: the unchanged receipt observes the commit the branch
+            // was created from as HEAD; the reconciler injects it here.
+            baseRevision: 'effect',
+            issueSummary: 'semantic',
+          },
+          repositoryDisposition: 'unchanged',
+        },
+        refused: {
+          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<BranchPlaybookOptions>;
+
+const createPlaybookRuntime: XStatePlaybookRuntimeFactory<
+  XStatePlaybookRuntimeConstruction<
+    BranchPlaybookOptions,
+    BranchPlaybookHostCapabilities
+  >,
+  3
+> = createXStatePlaybookRuntime<
+  BranchPlaybookOptions,
+  BranchPlaybookHostCapabilities
+>(branchMachine, runtimeSpec);
+
+export default createPlaybookRuntime;

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

@@ -0,0 +1,40 @@
+import { type BranchPlaybookHostCapabilities, type PlaybookRuntime } from './branch.playbook.js';
+export interface PlaybookSummaryPolicy {
+    stateCountLabels: Readonly<Record<string, string>>;
+    copyPasteGuardNames: readonly string[];
+    savedCountsLine(counts: {
+        interruptions: number;
+        copyPastes: number;
+    }, rounds: number): string;
+}
+export type BranchOptions = Readonly<Record<string, never>>;
+export interface BranchPlaybookRegistryEntry {
+    id: 'branch';
+    command: 'branch';
+    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): BranchOptions;
+    createRuntime(options: BranchOptions, hostCapabilities: BranchPlaybookHostCapabilities): PlaybookRuntime;
+}
+export declare const branchStateCountLabels: {
+    readonly createBranch: "branching round";
+};
+export declare const branchCopyPasteGuardNames: readonly ["branched"];
+export declare function branchSavedCountsLine(counts: {
+    interruptions: number;
+    copyPastes: number;
+}, rounds: number): string;
+export declare const branchSummaryPolicy: PlaybookSummaryPolicy;
+export declare function validateBranchOptions(optionSlice: unknown): BranchOptions;
+export declare const branchPlaybookRegistryEntry: BranchPlaybookRegistryEntry;
+export default branchPlaybookRegistryEntry;

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

@@ -0,0 +1,63 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+import createPlaybookRuntime from './branch.playbook.js';
+// BRANCH's one Coder call is its only round: the branching call that reads
+// the issue and creates and checks out the branch.
+export const branchStateCountLabels = {
+    createBranch: 'branching round',
+};
+export const branchCopyPasteGuardNames = ['branched'];
+function countNoun(count, singular, plural = `${singular}s`) {
+    return `${count} ${count === 1 ? singular : plural}`;
+}
+export function branchSavedCountsLine(counts, rounds) {
+    return [
+        'Saved you',
+        countNoun(counts.interruptions, 'interruption'),
+        'and',
+        countNoun(counts.copyPastes, 'copy-paste'),
+        'across',
+        countNoun(rounds, 'round'),
+        'of branching.',
+    ].join(' ');
+}
+export const branchSummaryPolicy = {
+    stateCountLabels: branchStateCountLabels,
+    copyPasteGuardNames: branchCopyPasteGuardNames,
+    savedCountsLine: branchSavedCountsLine,
+};
+export function validateBranchOptions(optionSlice) {
+    if (optionSlice === undefined)
+        return Object.freeze({});
+    if (optionSlice === null ||
+        typeof optionSlice !== 'object' ||
+        Array.isArray(optionSlice)) {
+        throw new Error('captain.options.playbooks.branch.options must be an object');
+    }
+    const keys = Object.keys(optionSlice);
+    if (keys.length > 0) {
+        throw new Error(`Unknown config field captain.options.playbooks.branch.options.${keys[0]}`);
+    }
+    return Object.freeze({});
+}
+export const branchPlaybookRegistryEntry = {
+    id: 'branch',
+    command: 'branch',
+    intent: 'create and check out a new branch for a GitHub issue or request before pull-request delivery',
+    artifactSchema: 3,
+    runtimeProfile: Object.freeze({
+        kind: 'shared-factory',
+        compat: createPlaybookRuntime.compat,
+    }),
+    requiredRoleIds: ['coder'],
+    concurrentRoleSets: [],
+    summaryPolicy: branchSummaryPolicy,
+    validateOptions: validateBranchOptions,
+    createRuntime(options, hostCapabilities) {
+        return createPlaybookRuntime({
+            configuredOptions: options,
+            hostCapabilities,
+        });
+    },
+};
+export default branchPlaybookRegistryEntry;

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

@@ -0,0 +1,121 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+import createPlaybookRuntime, {
+  type BranchPlaybookHostCapabilities,
+  type PlaybookRuntime,
+} from './branch.playbook.js';
+
+export interface PlaybookSummaryPolicy {
+  stateCountLabels: Readonly<Record<string, string>>;
+  copyPasteGuardNames: readonly string[];
+  savedCountsLine(
+    counts: { interruptions: number; copyPastes: number },
+    rounds: number,
+  ): string;
+}
+
+export type BranchOptions = Readonly<Record<string, never>>;
+
+export interface BranchPlaybookRegistryEntry {
+  id: 'branch';
+  command: 'branch';
+  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): BranchOptions;
+  createRuntime(
+    options: BranchOptions,
+    hostCapabilities: BranchPlaybookHostCapabilities,
+  ): PlaybookRuntime;
+}
+
+// BRANCH's one Coder call is its only round: the branching call that reads
+// the issue and creates and checks out the branch.
+export const branchStateCountLabels = {
+  createBranch: 'branching round',
+} as const;
+
+export const branchCopyPasteGuardNames = ['branched'] as const;
+
+function countNoun(
+  count: number,
+  singular: string,
+  plural = `${singular}s`,
+): string {
+  return `${count} ${count === 1 ? singular : plural}`;
+}
+
+export function branchSavedCountsLine(
+  counts: { interruptions: number; copyPastes: number },
+  rounds: number,
+): string {
+  return [
+    'Saved you',
+    countNoun(counts.interruptions, 'interruption'),
+    'and',
+    countNoun(counts.copyPastes, 'copy-paste'),
+    'across',
+    countNoun(rounds, 'round'),
+    'of branching.',
+  ].join(' ');
+}
+
+export const branchSummaryPolicy: PlaybookSummaryPolicy = {
+  stateCountLabels: branchStateCountLabels,
+  copyPasteGuardNames: branchCopyPasteGuardNames,
+  savedCountsLine: branchSavedCountsLine,
+};
+
+export function validateBranchOptions(optionSlice: unknown): BranchOptions {
+  if (optionSlice === undefined) return Object.freeze({});
+  if (
+    optionSlice === null ||
+    typeof optionSlice !== 'object' ||
+    Array.isArray(optionSlice)
+  ) {
+    throw new Error(
+      'captain.options.playbooks.branch.options must be an object',
+    );
+  }
+  const keys = Object.keys(optionSlice);
+  if (keys.length > 0) {
+    throw new Error(
+      `Unknown config field captain.options.playbooks.branch.options.${keys[0]}`,
+    );
+  }
+  return Object.freeze({});
+}
+
+export const branchPlaybookRegistryEntry: BranchPlaybookRegistryEntry = {
+  id: 'branch',
+  command: 'branch',
+  intent:
+    'create and check out a new branch for a GitHub issue or request before pull-request delivery',
+  artifactSchema: 3,
+  runtimeProfile: Object.freeze({
+    kind: 'shared-factory',
+    compat: createPlaybookRuntime.compat,
+  }),
+  requiredRoleIds: ['coder'],
+  concurrentRoleSets: [],
+  summaryPolicy: branchSummaryPolicy,
+  validateOptions: validateBranchOptions,
+  createRuntime(options, hostCapabilities) {
+    return createPlaybookRuntime({
+      configuredOptions: options,
+      hostCapabilities,
+    });
+  },
+};
+
+export default branchPlaybookRegistryEntry;

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

@@ -43,7 +43,7 @@ export async function openSessionHost(options) {
     await installRetainedGenerationsForLaunch({ lease, shell: created.shell, ...(record === undefined ? { freshBoundary: { cwd, structuralProjection: structure, executionProjection: config, snapshot: created.snapshot } } : {}), retainedGenerations: record?.retainedGenerations ?? {}, reconcileRepositoryEffects: created.reconcileRepositoryEffects });
     record = await lease.read();
     await replay.flushStoredRecords();
-    const execute = async (input, retry) => {
+    const execute = async (input, retry, actionId, shellActionId) => {
       if (closed || closing) throw new Error('session host is closing');
       if (active) throw new Error('session turn is already active');
       const operation = (async () => {
@@ -53,8 +53,18 @@ export async function openSessionHost(options) {
           input = prior.uncertain.input;
           if (!retryPending) throw new Error('retry requires reopening the uncertain checkpoint');
         } else if (prior?.state !== 'settled') throw new Error('session has an uncertain turn; select Retry or Discard');
-        if (typeof input !== 'string' || input.trim().length === 0) throw new Error('session input must be nonempty');
+        if (actionId === undefined && shellActionId === undefined && (typeof input !== 'string' || input.trim().length === 0)) throw new Error('session input must be nonempty');
         await created.reconcileRepositoryEffects();
+        // The selection is made after reconciliation, so the advertised
+        // reading it is validated against is the one this turn settles
+        // against, and its Boss text is this turn's durable input.
+        if (actionId !== undefined) {
+          if (typeof created.shell.submitRuntimeAction !== 'function') throw new Error('this Captain shell advertises no runtime actions');
+          input = created.shell.submitRuntimeAction(actionId);
+        } else if (shellActionId !== undefined) {
+          if (typeof created.shell.submitShellAction !== 'function') throw new Error('this Captain shell advertises no controls of its own');
+          input = created.shell.submitShellAction(shellActionId);
+        }
         terminal = undefined; replies = [];
         const attemptId = options.createAttemptId?.() ?? randomUUID();
         const marked = retry ? await lease.beginRetry({ expectedAttemptId: prior.uncertain.attemptId, nextAttemptId: attemptId }) : await lease.beginTurn({ input, attemptId, attemptedExecutionProjection: config });
@@ -84,7 +94,7 @@ export async function openSessionHost(options) {
       })();
       return closing;
     };
-    return Object.freeze({ sessionId, host: created.host, shell: created.shell, lease, read: () => lease.read(), handleBossTurn: (input) => execute(input, false), retry: () => execute(undefined, true), dispose });
+    return Object.freeze({ sessionId, host: created.host, shell: created.shell, lease, read: () => lease.read(), handleBossTurn: (input) => execute(input, false), listRuntimeActions: () => created.shell.describeRuntimeActions?.() ?? Object.freeze([]), submitRuntimeAction: (actionId) => execute(undefined, false, actionId), listShellActions: () => created.shell.describeShellActions?.() ?? Object.freeze([]), submitShellAction: (actionId) => execute(undefined, false, undefined, actionId), retry: () => execute(undefined, true), dispose });
   } catch (cause) {
     const failures = [cause];
     let disposed = true;

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

@@ -1,6 +1,6 @@
 import { type Captain, type CaptainSession, type TuningSelection } from '@sublang/cligent/tmux-play';
 import type { Effort, PermissionPolicy } from '@sublang/cligent';
-import type { JsonValue, PlaybookEffectLedger, PlaybookEffectLedgerCommandBatch, PlaybookRuntime, PlaybookRuntimeSnapshot } from '@sublang/playbook/runtime';
+import type { JsonValue, PlaybookEffectLedger, PlaybookEffectLedgerCommandBatch, PlaybookControlAction, PlaybookRuntime, PlaybookRuntimeSnapshot } from '@sublang/playbook/runtime';
 import { type CaptainControllerPort } from '../captain.playbook/captain.playbook.js';
 import type { PlaybookSummaryPolicy } from './code.registry.js';
 interface SessionAgent {
@@ -215,6 +215,31 @@ export interface PlaybookCaptainShell extends Captain {
     exportSnapshot(): PlaybookCaptainShellSnapshot | undefined;
     exportSettlement(): PlaybookCaptainSettlement | undefined;
     restore(session: CaptainSession, snapshot: PlaybookCaptainShellSnapshot): Promise<void>;
+    /**
+     * The active leaf's currently advertised runtime actions, as the host's own
+     * reading of the control view the ControlView digest reads (CAPTAIN-60).
+     * Declared optional because capability absence is member absence: a shell
+     * that publishes no reader advertises nothing.
+     */
+    describeRuntimeActions?(): readonly PlaybookControlAction[];
+    /**
+     * Select one currently advertised runtime action as the next Boss turn's
+     * decision and return that turn's Boss text, which the host submits through
+     * `handleBossTurn` (CAPTAIN-7).
+     */
+    submitRuntimeAction?(actionId: string): string;
+    /**
+     * The controls the shell effects on its own behalf, disjoint from the leaf's
+     * advertised runtime actions (CAPTAIN-62). Declared optional for the same
+     * reason: a shell that publishes no reader advertises nothing.
+     */
+    describeShellActions?(): readonly PlaybookControlAction[];
+    /**
+     * Select one currently advertised shell control as the next Boss turn's
+     * decision and return that turn's Boss text, which the host submits through
+     * `handleBossTurn` (CAPTAIN-7).
+     */
+    submitShellAction?(actionId: string): string;
 }
 export declare function assertPlaybookCaptainUnresolvedEffects(value: unknown): readonly PlaybookCaptainUnresolvedEffect[];
 /** Validate, detach, and freeze one untrusted shell snapshot. */