@sublang/playbook 13.1.0 → 13.2.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/playbook.config.template.yaml

@@ -78,8 +78,8 @@ players:
 # `roles` are launcher-owned; every other key is that playbook's option
 # slice.
 #
-# Every manifest role is bound explicitly. CODE, REVIEW, and DECIDE
-# intentionally reuse the same two stable players, while DEV keeps its own
+# Every manifest role is bound explicitly. CODE, REVIEW, DECIDE, BRANCH, and
+# PR intentionally reuse the same two stable players, while DEV keeps its own
 # Analyst; change an id to isolate its conversation.
 playbooks:
   code:
@@ -103,3 +103,17 @@ playbooks:
     from: "@sublang/playbook/dev/registry"
     roles:
       analyst: dev.analyst
+
+  # Pull-request delivery for DEV (DR-050). BRANCH and PR bind Coder to the
+  # same dev.coder player as CODE and REVIEW on purpose: the Coder that read
+  # the issue and named the branch makes the commits and then describes
+  # them in the pull request. Change an id to isolate its conversation.
+  branch:
+    from: "@sublang/playbook/branch/registry"
+    roles:
+      coder: dev.coder
+
+  pr:
+    from: "@sublang/playbook/pr/registry"
+    roles:
+      coder: dev.coder

package/reference/sdlc/dev.md

@@ -27,13 +27,14 @@ Do not change files or commit while planning or discussing the request.
 - If the discussion has concluded after a Boss reply and no repository work should follow, choose `discussion complete`.
 - If implementation can proceed under the existing decisions, choose `code`.
 - If implementation first requires a new or amended durable decision that the existing specs do not settle, choose `decide then code`.
+- If the request names a GitHub issue (number or URL) or explicitly asks for pull-request delivery, read the issue and its comments as part of the analysis (`gh issue view --comments` with the issue number) and choose `code via pull request` or `decide then code via pull request` in place of `code` or `decide then code`.
 
 A question or exploratory discussion is not by itself authorization to create a durable decision or implement changes.
 Do not choose `decide then code` merely because the work is large.
 Consult @specs/map.md for relevant context and @specs/meta.md for spec requirements, if needed.
 ```
 
-The planning result has four semantic outcomes: needs Boss reply, discussion complete, code, and decide then code.
+The planning result has six semantic outcomes: needs Boss reply, discussion complete, code, decide then code, code via pull request, and decide then code via pull request.
 Each outcome requires affirmative support in Analyst's result; absence of a reason to choose another outcome is not support.
 No outcome depends on a fixed presentation format of Analyst's reply.
 `dev` shall act on the accepted outcome itself and shall not return to the session Captain for another routing decision.
@@ -66,7 +67,27 @@ Only after `decide` succeeds shall `dev` call playbook `code` with the developme
 
 `dev` shall not separately call `review` for the design scope already reviewed by `decide`.
 
+For code via pull request and decide then code via pull request, `dev` shall first call playbook `branch` with the development request, relevant discussion context, and planning result in quotes (`>`).
+
+> Original request: <development-request>
+> Prior discussion: <discussion-context>
+> Planning result: <planning-result>
+
+Only after `branch` succeeds shall `dev` continue with the `code` call for code via pull request, or the `decide` call and then the `code` call for decide then code via pull request, each with the same input as its plain path above.
+
+On a plain path, `code` success completes `dev`.
+On a pull-request path, only after `code` succeeds shall `dev` call playbook `pr` with the development request, issue summary, branch, base revision, last `code`-owned commit, and exact final evaluated repository revision in quotes (`>`).
+
+> Original request: <development-request>
+> Issue summary: <issue-summary>
+> Branch: <branch>
+> Base revision: <base-revision>
+> CODE commit: <last-code-commit>
+> Evaluated revision: <final-evaluated-revision>
+
+A plain request calls neither `branch` nor `pr`.
+
 `dev` completes with the successful result of its final child call.
-If a child returns an authored abort or failure, or a terminal result that does not prove the success required for the selected path, `dev` shall start no later child and shall relay that canonical result.
+If a child returns an authored abort or failure, or a terminal result that does not prove the success required for the selected path, `dev` shall start no later child and shall relay that canonical result; a `branch` or `pr` failure ends `dev` under this same rule.
 If a child call fails outside its authored result contract, `dev` shall park as failed and retain the control-plane error.
-`dev` shall consume commit identities only from each child's canonical structured result, never from player prose.
+`dev` shall consume commit, revision, branch, and pull-request identities only from each child's canonical structured result, never from player prose.