@sublang/playbook 13.0.0 → 13.2.0

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

@@ -0,0 +1,325 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+//
+// Generated by slc/gears2fsm.md from ./branch.gears.md.
+import { assign, fromPromise, setup } from 'xstate';
+const CREATE_BRANCH_PROMPT = [
+    '> 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.',
+    "Confirm that the working tree is clean and that `gh` is authenticated for the repository's GitHub remote.",
+    'Name the branch `issue-N-short-kebab-slug` for issue number N, otherwise a short kebab-case slug of the request.',
+    '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.',
+].join('\n');
+const CREATE_BRANCH_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>`.',
+    needsBossReply: "The acting agent's prose surfaces a clarifying question for Boss that the agent cannot answer alone. Output shall include `question: <verbatim question text from the acting agent's prose>`.",
+};
+const STATE_DESCRIPTIONS = {
+    ready: 'Waiting for a development request to branch for.',
+    createBranch: 'Coder is reading the named issue and creating and checking out a new branch at the current commit.',
+    awaitBossReply: 'Waiting for Boss to answer Coder.',
+    failed: 'The branch workflow failed and is waiting for a new development request.',
+    branched: "A new branch for the request is checked out at the caller's current commit; no file changed and no commit was made.",
+    refused: 'No branch was created: Coder reported the obstacle with its reason — a dirty working tree, an unauthenticated `gh`, an unreadable issue, or a branch-name collision.',
+};
+function playbookMeta(stateId, role) {
+    return {
+        playbook: {
+            stateId,
+            description: STATE_DESCRIPTIONS[stateId],
+            ...(role === undefined ? {} : { role }),
+        },
+    };
+}
+// DR-048: a final state additionally declares whether its outcome means the
+// workflow succeeded or failed, so BRANCH's own caller learns that from the
+// machine rather than from BRANCH's output fields.
+function terminalMeta(stateId, terminal) {
+    return {
+        playbook: {
+            stateId,
+            description: STATE_DESCRIPTIONS[stateId],
+            terminal,
+        },
+    };
+}
+function isRecord(value) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function playerOutput(event) {
+    if (!isRecord(event))
+        return undefined;
+    return isRecord(event.output) ? event.output : undefined;
+}
+function outputGuard(event, guard) {
+    return playerOutput(event)?.guard === guard;
+}
+function outputString(event, field) {
+    const value = playerOutput(event)?.[field];
+    return isNonEmptyString(value) ? value : undefined;
+}
+// DR-045: the branched outcome is accepted only with the receipt-observed
+// base revision the linked runtime injects; Coder's prose never supplies it.
+function isBranched({ event }) {
+    return (outputGuard(event, 'branched') &&
+        outputString(event, 'branch') !== undefined &&
+        outputString(event, 'baseRevision') !== undefined &&
+        outputString(event, 'issueSummary') !== undefined);
+}
+function isRefused({ event }) {
+    return (outputGuard(event, 'refused') &&
+        outputString(event, 'coderOutput') !== undefined);
+}
+function needsBossReply({ event }) {
+    return (outputGuard(event, 'needsBossReply') &&
+        outputString(event, 'question') !== undefined);
+}
+const machineSetup = setup({
+    types: {},
+    actors: {
+        player: fromPromise(async () => {
+            throw new Error('player actor must be provided by the runner');
+        }),
+    },
+    guards: {
+        isBranched,
+        isRefused,
+        needsBossReply,
+        emptyBossReply: ({ event }) => event.type === 'BOSS_REPLY' && event.answer.trim().length === 0,
+        resumesCreateBranch: ({ context, event }) => event.type === 'BOSS_REPLY' &&
+            event.answer.trim().length > 0 &&
+            context.pendingBossQuestion?.resumeStateId === 'createBranch' &&
+            (event.questionId === undefined || event.questionId === 'createBranch'),
+    },
+    actions: {
+        'playbook.acceptedOutcome': (_args, _params) => undefined,
+        startBranch: assign(({ event }) => {
+            if (event.type !== 'START_BRANCH')
+                return {};
+            return {
+                callerInput: event.callerInput,
+                branch: undefined,
+                baseRevision: undefined,
+                issueSummary: undefined,
+                coderOutput: undefined,
+                completion: undefined,
+                lastError: undefined,
+                pendingBossQuestion: undefined,
+                bossReply: undefined,
+            };
+        }),
+        rememberBranched: assign(({ event }) => ({
+            branch: outputString(event, 'branch'),
+            // DR-045: the receipt-observed HEAD the branch was created from.
+            baseRevision: outputString(event, 'baseRevision'),
+            issueSummary: outputString(event, 'issueSummary'),
+            completion: 'branched',
+            pendingBossQuestion: undefined,
+            bossReply: undefined,
+        })),
+        rememberRefused: assign(({ event }) => ({
+            coderOutput: outputString(event, 'coderOutput'),
+            completion: 'refused',
+            pendingBossQuestion: undefined,
+            bossReply: undefined,
+        })),
+        rememberPendingQuestion: assign(({ event }) => {
+            const question = outputString(event, 'question');
+            if (question === undefined || !outputGuard(event, 'needsBossReply')) {
+                return { lastError: new Error('Coder question output was malformed') };
+            }
+            return {
+                pendingBossQuestion: {
+                    questionId: 'createBranch',
+                    resumeStateId: 'createBranch',
+                    sourceItem: 'BRANCH-1',
+                    asker: { kind: 'role', roleId: 'coder' },
+                    question,
+                },
+                bossReply: undefined,
+            };
+        }),
+        rememberBossReply: assign(({ event }) => event.type === 'BOSS_REPLY' ? { bossReply: event.answer } : {}),
+        rememberEmptyBossReplyError: assign({
+            lastError: () => new Error('BOSS_REPLY received an empty answer'),
+            pendingBossQuestion: undefined,
+            bossReply: undefined,
+        }),
+        rememberActorError: assign(({ event }) => ({
+            lastError: event.error,
+        })),
+        rememberMalformedPlayerOutput: assign({
+            lastError: () => new Error('Coder result for BRANCH-1 did not match an available outcome.'),
+        }),
+    },
+});
+export const branchMachine = machineSetup.createMachine({
+    id: 'branch',
+    initial: 'ready',
+    context: {},
+    output: ({ context }) => {
+        if (context.completion === 'branched') {
+            if (!isNonEmptyString(context.branch) ||
+                !isNonEmptyString(context.baseRevision) ||
+                !isNonEmptyString(context.issueSummary)) {
+                throw new Error('BRANCH reached branched without the exact branch name, a receipt-observed base revision, and an issue summary');
+            }
+            return {
+                status: 'branched',
+                branch: context.branch,
+                baseRevision: context.baseRevision,
+                issueSummary: context.issueSummary,
+            };
+        }
+        if (context.completion === 'refused') {
+            if (!isNonEmptyString(context.coderOutput)) {
+                throw new Error("BRANCH reached refused without Coder's report");
+            }
+            return { status: 'refused', coderOutput: context.coderOutput };
+        }
+        throw new Error('BRANCH reached a final state without a recorded completion');
+    },
+    states: {
+        ready: {
+            id: 'ready',
+            description: STATE_DESCRIPTIONS.ready,
+            meta: playbookMeta('ready'),
+            tags: ['playbook.parked'],
+            on: {
+                START_BRANCH: { target: 'createBranch', actions: 'startBranch' },
+            },
+        },
+        createBranch: {
+            id: 'createBranch',
+            description: STATE_DESCRIPTIONS.createBranch,
+            meta: playbookMeta('createBranch', 'coder'),
+            tags: ['playbook.busy'],
+            invoke: {
+                src: 'player',
+                input: ({ context }) => ({
+                    stateId: 'createBranch',
+                    role: 'coder',
+                    sourceItem: 'BRANCH-1',
+                    prompt: CREATE_BRANCH_PROMPT,
+                    result: CREATE_BRANCH_RESULTS,
+                    callerInput: context.callerInput ?? '',
+                    ...(context.pendingBossQuestion === undefined
+                        ? {}
+                        : { pendingBossQuestion: context.pendingBossQuestion }),
+                    ...(context.bossReply === undefined
+                        ? {}
+                        : { bossReply: context.bossReply }),
+                }),
+                onDone: [
+                    {
+                        guard: 'isBranched',
+                        target: 'branched',
+                        actions: [
+                            {
+                                type: 'playbook.acceptedOutcome',
+                                params: {
+                                    source: 'createBranch',
+                                    target: 'branched',
+                                    acceptedOutcome: 'branched',
+                                },
+                            },
+                            'rememberBranched',
+                        ],
+                    },
+                    {
+                        guard: 'isRefused',
+                        target: 'refused',
+                        actions: [
+                            {
+                                type: 'playbook.acceptedOutcome',
+                                params: {
+                                    source: 'createBranch',
+                                    target: 'refused',
+                                    acceptedOutcome: 'refused',
+                                },
+                            },
+                            'rememberRefused',
+                        ],
+                    },
+                    {
+                        guard: 'needsBossReply',
+                        target: 'awaitBossReply',
+                        actions: [
+                            {
+                                type: 'playbook.acceptedOutcome',
+                                params: {
+                                    source: 'createBranch',
+                                    target: 'awaitBossReply',
+                                    acceptedOutcome: 'needsBossReply',
+                                },
+                            },
+                            'rememberPendingQuestion',
+                        ],
+                    },
+                    {
+                        target: 'failed',
+                        actions: 'rememberMalformedPlayerOutput',
+                    },
+                ],
+                onError: { target: 'failed', actions: 'rememberActorError' },
+            },
+        },
+        awaitBossReply: {
+            id: 'awaitBossReply',
+            description: STATE_DESCRIPTIONS.awaitBossReply,
+            meta: playbookMeta('awaitBossReply'),
+            tags: ['playbook.parked'],
+            on: {
+                BOSS_REPLY: [
+                    {
+                        guard: 'emptyBossReply',
+                        target: '#failed',
+                        actions: 'rememberEmptyBossReplyError',
+                    },
+                    {
+                        guard: 'resumesCreateBranch',
+                        target: '#createBranch',
+                        reenter: true,
+                        actions: 'rememberBossReply',
+                    },
+                ],
+                START_BRANCH: { target: 'createBranch', actions: 'startBranch' },
+            },
+        },
+        failed: {
+            id: 'failed',
+            description: STATE_DESCRIPTIONS.failed,
+            meta: playbookMeta('failed'),
+            tags: ['playbook.parked'],
+            on: {
+                START_BRANCH: { target: 'createBranch', actions: 'startBranch' },
+            },
+        },
+        branched: {
+            id: 'branched',
+            description: STATE_DESCRIPTIONS.branched,
+            meta: terminalMeta('branched', 'success'),
+            type: 'final',
+        },
+        refused: {
+            id: 'refused',
+            description: STATE_DESCRIPTIONS.refused,
+            meta: terminalMeta('refused', 'failure'),
+            type: 'final',
+        },
+    },
+});
+export default branchMachine;