@sublang/playbook 15.0.0 → 16.0.0

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

@@ -1,11 +1,15 @@
 // 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';
+/**
+ * Stable working-leaf ids that may suspend on a Boss question and be resumed
+ * by `BOSS_REPLY`. The machine has at most one active player task, so the
+ * scalar Boss-reply form applies.
+ */
+const RESUMABLE_STATE_IDS = ['createBranch'];
+/** No parallel group in this playbook. */
+export const concurrentRoleSets = [];
 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.',
@@ -14,19 +18,22 @@ const CREATE_BRANCH_PROMPT = [
     '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>',
 ].join('\n');
+const NEEDS_BOSS_REPLY_RESULT = "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 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>`.",
+    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>`.",
+    needsBossReply: NEEDS_BOSS_REPLY_RESULT,
 };
 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.',
+    ready: 'Waiting for the caller to give a development request to branch for.',
+    createBranch: 'Coder is identifying the request\'s issue and creating and checking out a new branch at the current commit.',
+    awaitBossReply: "Waiting for Boss to answer the acting agent's question.",
+    failed: 'The branch workflow failed and is waiting for the caller to give the request again.',
+    branched: 'A new branch for the request was created at the current commit and checked out; the workflow returns its exact name, the exact base revision taken from repository authority, and the issue summary.',
+    refused: "No branch was created: Coder reported the failure with its reason, and the workflow fails and reports Coder's complete result to its caller.",
 };
 function playbookMeta(stateId, role) {
     return {
@@ -37,9 +44,7 @@ function playbookMeta(stateId, 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.
+/** A final state also publishes whether its outcome is success or failure. */
 function terminalMeta(stateId, terminal) {
     return {
         playbook: {
@@ -59,33 +64,69 @@ function isRecord(value) {
 function isNonEmptyString(value) {
     return typeof value === 'string' && value.trim().length > 0;
 }
-function playerOutput(event) {
-    if (!isRecord(event))
+/**
+ * Narrows an unknown event's `output` structurally to the declared `player`
+ * contract. Output missing a field its guard requires narrows to `undefined`.
+ */
+function playerOutputOf(event) {
+    if (!isRecord(event) || !isRecord(event.output))
         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;
+    const output = event.output;
+    if (output.guard === 'branched' &&
+        isNonEmptyString(output.branch) &&
+        isNonEmptyString(output.baseRevision) &&
+        isNonEmptyString(output.issueSummary)) {
+        return {
+            guard: 'branched',
+            branch: output.branch,
+            baseRevision: output.baseRevision,
+            issueSummary: output.issueSummary,
+        };
+    }
+    if (output.guard === 'refused' && isNonEmptyString(output.coderOutput)) {
+        return { guard: 'refused', coderOutput: output.coderOutput };
+    }
+    if (output.guard === 'needsBossReply' && isNonEmptyString(output.question)) {
+        return { guard: 'needsBossReply', question: output.question };
+    }
+    return 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);
+/** Narrows an unknown event's `error` structurally to a JSON-safe record. */
+function normalizedErrorOf(event) {
+    const error = isRecord(event) ? event.error : undefined;
+    if (error instanceof Error) {
+        const name = error.name || 'Error';
+        return typeof error.stack === 'string'
+            ? { name, message: error.message, stack: error.stack }
+            : { name, message: error.message };
+    }
+    if (isRecord(error)) {
+        const name = typeof error.name === 'string' ? error.name : 'Error';
+        const message = typeof error.message === 'string'
+            ? error.message
+            : 'player actor rejected without a normalized error';
+        return typeof error.stack === 'string'
+            ? { name, message, stack: error.stack }
+            : { name, message };
+    }
+    return {
+        name: 'Error',
+        message: typeof error === 'string'
+            ? error
+            : 'player actor rejected without a normalized error',
+    };
 }
-function isRefused({ event }) {
-    return (outputGuard(event, 'refused') &&
-        outputString(event, 'coderOutput') !== undefined);
+function isResumableStateId(value) {
+    return RESUMABLE_STATE_IDS.includes(value);
 }
-function needsBossReply({ event }) {
-    return (outputGuard(event, 'needsBossReply') &&
-        outputString(event, 'question') !== undefined);
+/** Builds one guarded `BOSS_REPLY` resume arm per registered working-leaf id. */
+function resumableStates(ids) {
+    return ids.map((id) => ({
+        guard: { type: 'canResume', params: { stateId: id } },
+        target: `#${id}`,
+        reenter: true,
+        actions: 'acceptBossReply',
+    }));
 }
 const machineSetup = setup({
     types: {},
@@ -95,87 +136,114 @@ const machineSetup = setup({
         }),
     },
     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'),
+        // The entry guard validates the text the current event supplies, before
+        // the entry action copies it into context.
+        givesRequest: ({ event }) => event.type === 'START_BRANCH' && isNonEmptyString(event.callerInput),
+        isBranched: ({ event }) => playerOutputOf(event)?.guard === 'branched',
+        isRefused: ({ event }) => playerOutputOf(event)?.guard === 'refused',
+        needsBossReply: ({ event }, params) => playerOutputOf(event)?.guard === 'needsBossReply' &&
+            isResumableStateId(params.stateId),
+        canResume: ({ context, event }, params) => {
+            if (event.type !== 'BOSS_REPLY' || !isNonEmptyString(event.answer)) {
+                return false;
+            }
+            const pending = context.pendingBossQuestion;
+            if (pending === undefined || pending.resumeStateId !== params.stateId) {
+                return false;
+            }
+            return (event.questionId === undefined ||
+                event.questionId === pending.questionId);
+        },
     },
     actions: {
         'playbook.acceptedOutcome': (_args, _params) => undefined,
-        startBranch: assign(({ event }) => {
+        startBranch: assign(({ context, 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,
+                ...(context.lastError === undefined ? {} : { lastError: undefined }),
+                ...(context.pendingBossQuestion === undefined
+                    ? {}
+                    : { pendingBossQuestion: undefined }),
+                ...(context.bossReply === 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') };
-            }
+        rememberBranched: assign(({ context, event }) => {
+            const output = playerOutputOf(event);
+            if (output?.guard !== 'branched')
+                return {};
+            return {
+                branch: output.branch,
+                baseRevision: output.baseRevision,
+                issueSummary: output.issueSummary,
+                completion: 'branched',
+                ...(context.pendingBossQuestion === undefined
+                    ? {}
+                    : { pendingBossQuestion: undefined }),
+                ...(context.bossReply === undefined ? {} : { bossReply: undefined }),
+            };
+        }),
+        rememberRefused: assign(({ context, event }) => {
+            const output = playerOutputOf(event);
+            if (output?.guard !== 'refused')
+                return {};
+            return {
+                coderOutput: output.coderOutput,
+                completion: 'refused',
+                ...(context.pendingBossQuestion === undefined
+                    ? {}
+                    : { pendingBossQuestion: undefined }),
+                ...(context.bossReply === undefined ? {} : { bossReply: undefined }),
+            };
+        }),
+        setPendingBossQuestion: assign(({ context, event }, params) => {
+            const output = playerOutputOf(event);
+            if (output?.guard !== 'needsBossReply')
+                return {};
             return {
                 pendingBossQuestion: {
-                    questionId: 'createBranch',
-                    resumeStateId: 'createBranch',
-                    sourceItem: 'BRANCH-1',
+                    questionId: params.stateId,
+                    resumeStateId: params.stateId,
+                    sourceItem: params.sourceItem,
                     asker: { kind: 'role', roleId: 'coder' },
-                    question,
+                    question: output.question,
                 },
-                bossReply: undefined,
+                ...(context.bossReply === undefined ? {} : { 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,
-        }),
+        acceptBossReply: assign(({ event }) => event.type === 'BOSS_REPLY' ? { bossReply: event.answer } : {}),
+        clearBossReplyContext: assign(({ context }) => context.pendingBossQuestion === undefined &&
+            context.bossReply === undefined
+            ? {}
+            : { pendingBossQuestion: undefined, bossReply: undefined }),
         rememberActorError: assign(({ event }) => ({
-            lastError: event.error,
+            lastError: normalizedErrorOf(event),
+        })),
+        rememberMalformedPlayerOutput: assign(() => ({
+            lastError: {
+                name: 'MalformedPlayerOutput',
+                message: 'Coder result for BRANCH-1 did not satisfy a declared outcome of its result contract.',
+            },
+        })),
+        rememberMalformedBossReply: assign(() => ({
+            lastError: {
+                name: 'MalformedBossReply',
+                message: 'BOSS_REPLY carried an empty answer or named no pending question.',
+            },
         })),
-        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: {},
+    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');
+                throw new Error('BRANCH reached branched without the exact branch name, base revision, and issue summary');
             }
             return {
                 status: 'branched',
@@ -186,7 +254,7 @@ export const branchMachine = machineSetup.createMachine({
         }
         if (context.completion === 'refused') {
             if (!isNonEmptyString(context.coderOutput)) {
-                throw new Error("BRANCH reached refused without Coder's report");
+                throw new Error("BRANCH reached refused without Coder's complete result");
             }
             return { status: 'refused', coderOutput: context.coderOutput };
         }
@@ -199,7 +267,11 @@ export const branchMachine = machineSetup.createMachine({
             meta: playbookMeta('ready'),
             tags: ['playbook.parked'],
             on: {
-                START_BRANCH: { target: 'createBranch', actions: 'startBranch' },
+                START_BRANCH: {
+                    guard: 'givesRequest',
+                    target: 'createBranch',
+                    actions: 'startBranch',
+                },
             },
         },
         createBranch: {
@@ -215,6 +287,8 @@ export const branchMachine = machineSetup.createMachine({
                     sourceItem: 'BRANCH-1',
                     prompt: CREATE_BRANCH_PROMPT,
                     result: CREATE_BRANCH_RESULTS,
+                    // Entry is guarded on a non-empty caller input, so this state is
+                    // never entered without it.
                     callerInput: context.callerInput ?? '',
                     ...(context.pendingBossQuestion === undefined
                         ? {}
@@ -255,7 +329,10 @@ export const branchMachine = machineSetup.createMachine({
                         ],
                     },
                     {
-                        guard: 'needsBossReply',
+                        guard: {
+                            type: 'needsBossReply',
+                            params: { stateId: 'createBranch' },
+                        },
                         target: 'awaitBossReply',
                         actions: [
                             {
@@ -266,7 +343,10 @@ export const branchMachine = machineSetup.createMachine({
                                     acceptedOutcome: 'needsBossReply',
                                 },
                             },
-                            'rememberPendingQuestion',
+                            {
+                                type: 'setPendingBossQuestion',
+                                params: { stateId: 'createBranch', sourceItem: 'BRANCH-1' },
+                            },
                         ],
                     },
                     {
@@ -284,19 +364,17 @@ export const branchMachine = machineSetup.createMachine({
             tags: ['playbook.parked'],
             on: {
                 BOSS_REPLY: [
+                    ...resumableStates(RESUMABLE_STATE_IDS),
                     {
-                        guard: 'emptyBossReply',
-                        target: '#failed',
-                        actions: 'rememberEmptyBossReplyError',
-                    },
-                    {
-                        guard: 'resumesCreateBranch',
-                        target: '#createBranch',
-                        reenter: true,
-                        actions: 'rememberBossReply',
+                        target: 'failed',
+                        actions: ['rememberMalformedBossReply', 'clearBossReplyContext'],
                     },
                 ],
-                START_BRANCH: { target: 'createBranch', actions: 'startBranch' },
+                START_BRANCH: {
+                    guard: 'givesRequest',
+                    target: 'createBranch',
+                    actions: 'startBranch',
+                },
             },
         },
         failed: {
@@ -305,7 +383,11 @@ export const branchMachine = machineSetup.createMachine({
             meta: playbookMeta('failed'),
             tags: ['playbook.parked'],
             on: {
-                START_BRANCH: { target: 'createBranch', actions: 'startBranch' },
+                START_BRANCH: {
+                    guard: 'givesRequest',
+                    target: 'createBranch',
+                    actions: 'startBranch',
+                },
             },
         },
         branched: {