@sublang/playbook 15.0.0 → 16.0.0

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

@@ -1,7 +1,7 @@
 <!-- SPDX-License-Identifier: Apache-2.0 -->
 <!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
 
-# BRANCH: Pull-Request Branch Preparation Workflow
+# Branch
 
 Roles:
 
@@ -11,16 +11,13 @@ The caller supplies a development request that names a GitHub issue (number or U
 
 `branch` prepares pull-request delivery of one development request: it creates and checks out a new branch at the current commit.
 It changes no files and owns no repository commit.
-Captain takes the base revision from repository authority, not from Coder's prose: the `unchanged` repository-effect receipt of the branching call proves the observed HEAD the branch was created from.
 
-## Coder
+## Workflow
 
 ### BRANCH-1
 
-When the caller gives the request, Captain shall relay the complete caller input in quotes (`>`) to Coder, along with the branching instruction:
+Where every outcome keeps the repository exact, so that a new branch at the current commit changes neither HEAD's commit nor the working tree, where Captain takes the base revision from repository authority rather than from Coder's prose, where each outcome requires affirmative support in Coder's result and depends on no fixed presentation format of Coder's reply, and where Boss's answer to Coder's question about which issue or work the request means resumes this same behavior with that answer as continuation context, when the caller gives the request, Captain shall relay the complete caller input in quotes (`>`) to Coder, along with the following instruction:
 
-> > Original request: <caller-input>
->
 > Prepare a new branch for this work without changing any file or making any commit.
 > Identify the GitHub issue the request names, if any, and read it with its comments (`gh issue view --comments` with the issue number).
 > If the request could refer to more than one issue, or does not say which work to branch for, ask Boss before creating anything.
@@ -29,16 +26,9 @@ When the caller gives the request, Captain shall relay the complete caller input
 > Create the branch from the current commit and check it out; do not pull, reset, stash, or move HEAD to another commit.
 > Report the exact branch name, the commit it was created from, and a concise summary of the issue and its comments, or of the request when no issue is named.
 > If the working tree is not clean, `gh` is not authenticated, the named issue does not exist or cannot be read, or a branch with that name already exists locally or on the remote, create nothing and report the failure with its reason.
+>
+> > Original request: <caller-input>
 
 Results:
-- `branched`: Coder created the new branch from the current commit and checked it out, reporting its exact name and a concise summary of the issue and its comments, or of the request when no issue is named; the absence of a reported obstacle is not support. Output shall include `branch: <exact branch name>`, `baseRevision: <repository revision>`, and `issueSummary: <concise summary>`.
-- `refused`: Coder created nothing and reported the failure with its reason: the working tree is not clean, `gh` is not authenticated, the named issue does not exist or cannot be read, or a branch with that name already exists locally or on the remote. Output shall include `coderOutput: <verbatim final text>`.
-
-Workflow outcomes:
-- The result has two semantic outcomes: branched and refused, plus the Boss question when the request is ambiguous about the issue or work it means.
-- Each outcome requires affirmative support in Coder's result; the absence of a reported obstacle is not support for branched, and no outcome depends on a fixed presentation format of Coder's reply.
-- Every outcome keeps the repository exact: a new branch at the current commit changes neither HEAD's commit nor the working tree.
-- Captain takes the base revision from repository authority, not from Coder's prose.
-- The Boss question uses the standard Boss-question suspension with Coder's complete response; after Boss replies, `branch` resumes with the answer in the same Coder conversation, and the previous question is included only when that conversation must start fresh.
-- For branched, `branch` is complete and returns the exact branch name, the exact base revision, and the issue summary to its caller.
-- For refused, `branch` fails and reports Coder's complete result with its reason to its caller; no branch was created.
+- `branched`: Coder affirmatively reported that it created the new branch from the current commit and checked it out, with the exact branch name and a concise summary of the issue and its comments, or of the request when no issue is named; the absence of a reported obstacle is not support. The branch workflow is then complete and returns the exact branch name, the exact base revision taken from repository authority, and the issue summary to its caller. Output shall include `branch: <exact branch name>`, `baseRevision: <exact base revision from repository authority, not from Coder's prose>`, and `issueSummary: <concise summary of the issue and its comments, or of the request when no issue is named>`.
+- `refused`: Coder affirmatively reported that it created no branch and gave the failure with its reason, such as a working tree that is not clean, gh not being authenticated, a named issue that does not exist or cannot be read, or a branch with that name already existing locally or on the remote. The branch workflow then fails and reports Coder's complete result with its reason to its caller; no branch was created. Output shall include `coderOutput: <verbatim final text>`.

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

@@ -1,20 +1,16 @@
-import { type XStatePlaybookRuntimeFactory, type XStatePlaybookRuntimeConstruction } from '@sublang/playbook/xstate-runtime';
-import { 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'];
-/**
- * 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.
- */
-declare function composePlayerPrompt(input: PlayerInput, resuming?: boolean): string;
+import { type XStatePromptIdentity, type PlaybookPlayerInput, type XStatePlaybookRuntimeConstruction, type XStatePlaybookRuntimeFactory } from '@sublang/playbook/xstate-runtime';
+export type { PlayerResult, PlayerCallOptions, PlayerSessionStore, CaptainResult, CaptainCallOptions, JsonValue, NormalizedError, PlaybookCallRequest, PlaybookCallResult, PlaybookCallStart, PlaybookStateValue, PlaybookState, PlaybookPendingCall, PlaybookRunResult, PlaybookRuntime, PlaybookRuntimeFactory, PlaybookRuntimeSnapshot, PlaybookSession, PlaybookPorts, PlaybookTraceEvent, PlaybookTraceType, PlaybookControlReceipt, PlaybookControlView, } from '@sublang/playbook/runtime';
+export interface PlaybookRuntimeOptions {
+}
+export type PlaybookHostCapabilities = XStatePlaybookRuntimeConstruction<PlaybookRuntimeOptions, {
+    readonly authority: object;
+}>['hostCapabilities'];
+export declare function validateOptions(value: unknown): PlaybookRuntimeOptions;
 export declare const _internal: {
-    composePlayerPrompt: typeof composePlayerPrompt;
-    VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string>;
+    composePlayerPrompt: (input: PlaybookPlayerInput, promptIdentity: XStatePromptIdentity, resuming?: boolean) => string;
+    RESUMABLE_STATE_IDS: ReadonlySet<string>;
     UNFINISHED_FINAL_STATE_IDS: ReadonlySet<string>;
+    VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string>;
 };
-declare const createPlaybookRuntime: XStatePlaybookRuntimeFactory<XStatePlaybookRuntimeConstruction<BranchPlaybookOptions, BranchPlaybookHostCapabilities>, 3>;
+declare const createPlaybookRuntime: XStatePlaybookRuntimeFactory<XStatePlaybookRuntimeConstruction<PlaybookRuntimeOptions, PlaybookHostCapabilities>, 3>;
 export default createPlaybookRuntime;

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

@@ -1,121 +1,132 @@
 // 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, } from '@sublang/playbook/xstate-runtime';
-import { branchMachine, } from './branch.fsm.js';
-const PLACEHOLDER = /<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>/g;
+// Generated by slc/materialize-link.mjs; governed by the complete slc/link.md.
+// FSM: "./branch.fsm.js"; export: branchMachine; strategies: shared defaults with labelled string relays and nested actors.
+import { branchMachine as machine } from "./branch.fsm.js";
+import { createXStatePlaybookRuntime, snapshotJsonValue, composePlayerContinuation, } from '@sublang/playbook/xstate-runtime';
+const OPTION_SCHEMA = {};
+const INPUT_MAPPING = {};
+const RESUMABLE_STATE_IDS = new Set([
+    "createBranch"
+]);
+const UNFINISHED_FINAL_STATE_IDS = new Set([
+    "refused"
+]);
 const VERBATIM_PAYLOAD_FIELDS = new Set([
-    'coderOutput',
+    "coderOutput"
 ]);
-const UNFINISHED_FINAL_STATE_IDS = new Set(['refused']);
-function snapshotBranchOptions(value) {
-    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');
+export function validateOptions(value) {
+    const captured = snapshotJsonValue(value === undefined ? {} : value, "BRANCH runtime options");
+    if (captured === null || typeof captured !== 'object' || Array.isArray(captured)) {
+        throw new TypeError("BRANCH runtime options must be an object");
+    }
+    const fields = captured;
+    for (const key of Object.keys(captured)) {
+        if (!Object.hasOwn(OPTION_SCHEMA, key))
+            throw new TypeError("BRANCH runtime options." + key + ' is not declared');
     }
-    const record = captured;
-    for (const key of Object.keys(record)) {
-        throw new TypeError(`BRANCH runtime options.${key} is not declared`);
+    for (const [key, schema] of Object.entries(OPTION_SCHEMA)) {
+        if (!Object.hasOwn(captured, key)) {
+            if (schema.required)
+                throw new TypeError("BRANCH runtime options." + key + ' is required');
+        }
+        else if (typeof fields[key] !== schema.type || (schema.type === 'number' && !Number.isFinite(fields[key]))) {
+            throw new TypeError("BRANCH runtime options." + key + ' must be a ' + schema.type);
+        }
     }
     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 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, resuming = false) {
+function renderPlayerPrompt(input, promptIdentity, 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;
-        const literal = source.slice(lineStart, offset);
-        return literal.startsWith('> ') ? quotedContinuation(value) : value;
-    });
+    const mapping = {};
+    const identities = {};
+    const omitted = new Set([]);
+    const fieldFor = (token) => Object.hasOwn(mapping, token) ? mapping[token] : (token === '#' ? 'irNumber' : token.replace(/-([A-Za-z0-9_$])/g, (_match, next) => 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, token) => {
+            const value = Object.hasOwn(identities, token) ? promptIdentity(identities[token]) : fields[fieldFor(token)];
+            if (typeof value !== 'string')
+                return match;
+            return line.startsWith('> ') ? value.replace(/\r?\n/g, (ending) => ending + '> ') : value;
+        }) + (parts[index + 1] ?? '');
+    }
     return composePlayerContinuation(input, body, resuming);
 }
-export const _internal = {
-    composePlayerPrompt,
-    VERBATIM_PAYLOAD_FIELDS,
-    UNFINISHED_FINAL_STATE_IDS,
-};
+const composePlayerPrompt = (input, promptIdentity, resuming) => renderPlayerPrompt(input, promptIdentity, resuming);
 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.',
+    composePlayerPrompt,
+    ...{
+        "label": "BRANCH",
+        "compat": {
+            "artifactSchema": 3,
+            "runtimeAbi": 1
         },
-    },
-    // 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',
+        "entryEvent": {
+            "type": "START_BRANCH",
+            "textField": "callerInput",
+            "contextField": "callerInput"
+        },
+        "bossEvents": [],
+        "roleStates": {
+            "createBranch": {
+                "role": "coder",
+                "label": "Coder is identifying the request's issue and creating and checking out a new branch at the current commit."
+            }
+        },
+        "outcomeAuthority": {
+            "governedPlayerStates": {
+                "createBranch": {
+                    "branched": {
+                        "fields": {
+                            "branch": "semantic",
+                            "baseRevision": "effect",
+                            "issueSummary": "semantic"
+                        },
+                        "repositoryDisposition": "unchanged"
+                    },
+                    "refused": {
+                        "fields": {
+                            "coderOutput": "presentation"
+                        },
+                        "repositoryDisposition": "unchanged"
                     },
-                    repositoryDisposition: 'unchanged',
-                },
-                refused: {
-                    fields: { coderOutput: 'presentation' },
-                    repositoryDisposition: 'unchanged',
-                },
-                needsBossReply: {
-                    fields: { question: 'presentation' },
-                    repositoryDisposition: 'unchanged',
-                },
-            },
+                    "needsBossReply": {
+                        "fields": {
+                            "question": "presentation"
+                        },
+                        "repositoryDisposition": "unchanged"
+                    }
+                }
+            }
         },
+        "placeholderFields": {},
+        "transitionEventFields": [
+            "callerInput",
+            "answer",
+            "questionId"
+        ],
+        "controlContextFields": []
     },
-    composePlayerPrompt: (input, _identity, resuming) => composePlayerPrompt(input, resuming),
+    snapshotOptions: validateOptions,
+    machineInput: (options) => Object.fromEntries(Object.entries(INPUT_MAPPING).filter(([, key]) => options[key] !== undefined)
+        .map(([field, key]) => [field, options[key]])),
     verbatimPayloadFields: VERBATIM_PAYLOAD_FIELDS,
-    controlContextFields: [],
+    resumableStateIds: RESUMABLE_STATE_IDS,
     unfinishedFinalStateIds: UNFINISHED_FINAL_STATE_IDS,
-    transitionEventFields: ['callerInput', 'answer', 'questionId'],
 };
-const createPlaybookRuntime = createXStatePlaybookRuntime(branchMachine, runtimeSpec);
+export const _internal = {
+    composePlayerPrompt,
+    RESUMABLE_STATE_IDS,
+    UNFINISHED_FINAL_STATE_IDS,
+    VERBATIM_PAYLOAD_FIELDS,
+};
+const createPlaybookRuntime = createXStatePlaybookRuntime(machine, runtimeSpec);
 export default createPlaybookRuntime;