@sublang/playbook 13.0.0 → 13.2.0

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

@@ -4,9 +4,9 @@
 // Generated by slc/gears2fsm.md from ./dev.gears.md.
 import { assign, fromPromise, setup } from 'xstate';
 const PLAN_ANALYSIS_PROMPT = [
-    '> <development-request>',
-    '> <discussion-context>',
-    '> <run-results>',
+    '> Original request: <development-request>',
+    '> Prior discussion: <discussion-context>',
+    '> Run results: <run-results>',
     '',
     'Inspect the request and the relevant repository and specs only as needed to determine the smallest sound next step.',
     'Do not change files or commit while planning or discussing the request.',
@@ -15,6 +15,7 @@ const PLAN_ANALYSIS_PROMPT = [
     '- 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.',
@@ -24,14 +25,18 @@ const PLAN_ANALYSIS_RESULTS = {
     discussionComplete: 'Analyst concluded the discussion after a Boss reply, with no repository work to follow.',
     code: 'Analyst determined implementation can proceed under the existing decisions. Output shall include `planningResult: <verbatim final text>`.',
     decideThenCode: 'Analyst determined implementation first requires a new or amended durable decision that the existing specs do not settle. Output shall include `planningResult: <verbatim final text>`.',
+    codeViaPullRequest: 'Analyst determined implementation can proceed under the existing decisions and the request names a GitHub issue or explicitly asks for pull-request delivery. Output shall include `planningResult: <verbatim final text>`.',
+    decideThenCodeViaPullRequest: 'Analyst determined implementation first requires a new or amended durable decision that the existing specs do not settle and the request names a GitHub issue or explicitly asks for pull-request delivery. Output shall include `planningResult: <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.',
     planAnalysis: 'Analyst is analyzing the development request to choose the smallest sound next step.',
+    createBranch: 'The BRANCH playbook is preparing the pull-request branch for the planned development path.',
     callCode: 'The CODE playbook is implementing the planned development path.',
     callDecide: 'The DECIDE playbook is settling the durable decision the planned path requires.',
     callCodeAfterDecide: 'The CODE playbook is implementing the decided development path.',
+    openPullRequest: 'The PR playbook is delivering the implemented branch through a pull request.',
     awaitBossReply: 'Waiting for Boss to answer Analyst.',
     failed: 'The development planning workflow failed and is waiting for a new development request.',
     discussionComplete: 'The planning discussion concluded after a Boss reply with no repository work to follow.',
@@ -89,6 +94,16 @@ function isDecideThenCode({ event }) {
     return (outputGuard(event, 'decideThenCode') &&
         outputString(event, 'planningResult') !== undefined);
 }
+// DR-050: the two pull-request outcomes select the same development paths
+// as `code` and `decide then code`, entered through `branch` first.
+function isCodeViaPullRequest({ event }) {
+    return (outputGuard(event, 'codeViaPullRequest') &&
+        outputString(event, 'planningResult') !== undefined);
+}
+function isDecideThenCodeViaPullRequest({ event, }) {
+    return (outputGuard(event, 'decideThenCodeViaPullRequest') &&
+        outputString(event, 'planningResult') !== undefined);
+}
 // Discussion complete is available only after a Boss reply: the round that
 // produced it must itself have been resumed with Boss's answer.
 function isDiscussionComplete({ context, event, }) {
@@ -111,6 +126,24 @@ function isDecideSuccessValue(value) {
 function isDecideSuccess({ event }) {
     return isDecideSuccessValue(childOutputOf(event));
 }
+// BRANCH's canonical successful terminal output carries the exact name of
+// the new checked-out branch, the exact receipt-owned base revision, and the
+// issue summary; DEV consumes exactly those three by name and never defaults
+// a missing one.
+function isBranchSuccessValue(value) {
+    return (isRecord(value) &&
+        isNonEmptyString(value.branch) &&
+        isNonEmptyString(value.baseRevision) &&
+        isNonEmptyString(value.issueSummary));
+}
+function isBranchSuccessForCode({ context, event, }) {
+    return (context.pullRequestPath === 'code' &&
+        isBranchSuccessValue(childOutputOf(event)));
+}
+function isBranchSuccessForDecide({ context, event, }) {
+    return (context.pullRequestPath === 'decide-then-code' &&
+        isBranchSuccessValue(childOutputOf(event)));
+}
 // CODE's canonical successful terminal output discriminates completion with
 // `status: 'complete'`, carries the exact last CODE-owned commit, and
 // affirms that every phase's review passed.
@@ -120,8 +153,22 @@ function isCodeSuccessValue(value) {
         isNonEmptyString(value.lastCodeCommit) &&
         value.allReviewsPassed === true);
 }
-function isCodeSuccess({ event }) {
-    return isCodeSuccessValue(childOutputOf(event));
+// A plain path completes DEV on that proof alone, exactly as before DR-050.
+function isPlainCodeSuccess({ context, event, }) {
+    return (context.deliveryViaPullRequest !== true &&
+        isCodeSuccessValue(childOutputOf(event)));
+}
+// A pull-request path additionally consumes the exact final evaluated
+// repository revision for the `pr` call, so a CODE result lacking it does not
+// prove the success that path requires.
+function isCodeSuccessValueForPullRequest(value) {
+    return (isCodeSuccessValue(value) &&
+        isRecord(value) &&
+        isNonEmptyString(value.finalEvaluatedRevision));
+}
+function isCodeSuccessViaPullRequest({ context, event, }) {
+    return (context.deliveryViaPullRequest === true &&
+        isCodeSuccessValueForPullRequest(childOutputOf(event)));
 }
 function isStateValue(value, ancestors = new Set()) {
     if (typeof value === 'string')
@@ -334,8 +381,8 @@ function archivedExchanges(context) {
 }
 function quotedRelay(values) {
     return values
-        .filter((value) => value.length > 0)
-        .map((value) => value
+        .filter(([, value]) => value.length > 0)
+        .map(([label, value]) => `${label}: ${value}`
         .split('\n')
         .map((line) => `> ${line}`)
         .join('\n'))
@@ -343,9 +390,9 @@ function quotedRelay(values) {
 }
 function planningRelayValues(context) {
     return [
-        context.developmentRequest ?? '',
-        renderDiscussionContext(context.discussionExchanges),
-        context.planningResult ?? '',
+        ['Original request', context.developmentRequest ?? ''],
+        ['Prior discussion', renderDiscussionContext(context.discussionExchanges)],
+        ['Planning result', context.planningResult ?? ''],
     ];
 }
 function codeCallText(context) {
@@ -357,10 +404,35 @@ function decideCallText(context) {
 function codeAfterDecideCallText(context) {
     return quotedRelay([
         ...planningRelayValues(context),
-        context.decideCommit ?? '',
-        context.evaluatedRevision ?? '',
+        ['DECIDE commit', context.decideCommit ?? ''],
+        ['Evaluated revision', context.evaluatedRevision ?? ''],
+    ]);
+}
+function branchCallText(context) {
+    return quotedRelay(planningRelayValues(context));
+}
+// DEV-6: every placeholder is substituted from typed context that only a
+// child's canonical structured result populated — never from player prose.
+function pullRequestCallText(context) {
+    return quotedRelay([
+        ['Original request', context.developmentRequest ?? ''],
+        ['Issue summary', context.issueSummary ?? ''],
+        ['Branch', context.branch ?? ''],
+        ['Base revision', context.baseRevision ?? ''],
+        ['CODE commit', context.lastCodeCommit ?? ''],
+        ['Evaluated revision', context.finalEvaluatedRevision ?? ''],
     ]);
 }
+function acceptedPlanningPath(context, event, pullRequestPath) {
+    return {
+        planningResult: outputString(event, 'planningResult'),
+        discussionExchanges: archivedExchanges(context),
+        deliveryViaPullRequest: pullRequestPath !== undefined,
+        pullRequestPath,
+        pendingBossQuestion: undefined,
+        bossReply: undefined,
+    };
+}
 const machineSetup = setup({
     types: {},
     actors: {
@@ -375,11 +447,18 @@ const machineSetup = setup({
         isDiscussionComplete,
         isCodePath,
         isDecideThenCode,
+        isCodeViaPullRequest,
+        isDecideThenCodeViaPullRequest,
         needsBossReply,
-        isCodeSuccess,
+        isBranchSuccessForCode,
+        isBranchSuccessForDecide,
+        isCodeSuccessViaPullRequest,
+        isPlainCodeSuccess,
         isDecideSuccess,
+        authoredBranchFailure: authoredChildFailureGuard('branch'),
         authoredCodeFailure: authoredChildFailureGuard('code'),
         authoredDecideFailure: authoredChildFailureGuard('decide'),
+        authoredPrFailure: authoredChildFailureGuard('pr'),
         emptyBossReply: ({ event }) => event.type === 'BOSS_REPLY' && event.answer.trim().length === 0,
         resumesPlanAnalysis: ({ context, event }) => event.type === 'BOSS_REPLY' &&
             event.answer.trim().length > 0 &&
@@ -398,6 +477,13 @@ const machineSetup = setup({
                 planningResult: undefined,
                 decideCommit: undefined,
                 evaluatedRevision: undefined,
+                deliveryViaPullRequest: false,
+                pullRequestPath: undefined,
+                branch: undefined,
+                baseRevision: undefined,
+                issueSummary: undefined,
+                lastCodeCommit: undefined,
+                finalEvaluatedRevision: undefined,
                 completion: undefined,
                 childOutput: undefined,
                 childFailure: undefined,
@@ -412,18 +498,10 @@ const machineSetup = setup({
             pendingBossQuestion: undefined,
             bossReply: undefined,
         })),
-        rememberCodePath: assign(({ context, event }) => ({
-            planningResult: outputString(event, 'planningResult'),
-            discussionExchanges: archivedExchanges(context),
-            pendingBossQuestion: undefined,
-            bossReply: undefined,
-        })),
-        rememberDecidePath: assign(({ context, event }) => ({
-            planningResult: outputString(event, 'planningResult'),
-            discussionExchanges: archivedExchanges(context),
-            pendingBossQuestion: undefined,
-            bossReply: undefined,
-        })),
+        rememberCodePath: assign(({ context, event }) => acceptedPlanningPath(context, event)),
+        rememberDecidePath: assign(({ context, event }) => acceptedPlanningPath(context, event)),
+        rememberCodeViaPullRequestPath: assign(({ context, event }) => acceptedPlanningPath(context, event, 'code')),
+        rememberDecideThenCodeViaPullRequestPath: assign(({ context, event }) => acceptedPlanningPath(context, event, 'decide-then-code')),
         rememberPendingQuestion: assign(({ context, event }) => {
             const question = outputString(event, 'question');
             if (question === undefined || !outputGuard(event, 'needsBossReply')) {
@@ -447,6 +525,16 @@ const machineSetup = setup({
             pendingBossQuestion: undefined,
             bossReply: undefined,
         }),
+        rememberBranchResult: assign(({ event }) => {
+            const output = childOutputOf(event);
+            if (!isBranchSuccessValue(output))
+                return {};
+            return {
+                branch: output.branch,
+                baseRevision: output.baseRevision,
+                issueSummary: output.issueSummary,
+            };
+        }),
         rememberDecideResult: assign(({ event }) => {
             const output = childOutputOf(event);
             if (!isDecideSuccessValue(output))
@@ -456,6 +544,15 @@ const machineSetup = setup({
                 evaluatedRevision: output.evaluatedRevision,
             };
         }),
+        rememberCodeResult: assign(({ event }) => {
+            const output = childOutputOf(event);
+            if (!isCodeSuccessValueForPullRequest(output))
+                return {};
+            return {
+                lastCodeCommit: output.lastCodeCommit,
+                finalEvaluatedRevision: output.finalEvaluatedRevision,
+            };
+        }),
         completeWithChildSuccess: assign(({ event }) => {
             const output = childOutputOf(event);
             return {
@@ -463,6 +560,10 @@ const machineSetup = setup({
                 ...(output === undefined ? {} : { childOutput: output }),
             };
         }),
+        completeWithInsufficientBranchResult: assign(({ event }) => ({
+            completion: 'child-failed',
+            childFailure: insufficientChildResult(event, 'branch'),
+        })),
         completeWithInsufficientCodeResult: assign(({ event }) => ({
             completion: 'child-failed',
             childFailure: insufficientChildResult(event, 'code'),
@@ -471,6 +572,10 @@ const machineSetup = setup({
             completion: 'child-failed',
             childFailure: insufficientChildResult(event, 'decide'),
         })),
+        completeWithBranchFailure: assign(({ event }) => ({
+            completion: 'child-failed',
+            childFailure: relayedChildFailure(event, 'branch'),
+        })),
         completeWithCodeFailure: assign(({ event }) => ({
             completion: 'child-failed',
             childFailure: relayedChildFailure(event, 'code'),
@@ -479,6 +584,10 @@ const machineSetup = setup({
             completion: 'child-failed',
             childFailure: relayedChildFailure(event, 'decide'),
         })),
+        completeWithPrFailure: assign(({ event }) => ({
+            completion: 'child-failed',
+            childFailure: relayedChildFailure(event, 'pr'),
+        })),
         rememberActorError: assign(({ event }) => ({
             lastError: event.error,
         })),
@@ -493,6 +602,7 @@ export const devMachine = machineSetup.createMachine({
     context: ({ input }) => ({
         runResults: typeof input.runResults === 'string' ? input.runResults : '',
         discussionExchanges: [],
+        deliveryViaPullRequest: false,
     }),
     output: ({ context }) => {
         if (context.completion === 'discussion-complete') {
@@ -501,7 +611,9 @@ export const devMachine = machineSetup.createMachine({
         if (context.completion === 'complete') {
             return {
                 status: 'complete',
-                childPlaybookId: 'code',
+                // `done` is entered by `pr` on a pull-request path and by `code` on a
+                // plain path; no other arm completes the workflow.
+                childPlaybookId: context.deliveryViaPullRequest ? 'pr' : 'code',
                 ...(context.childOutput === undefined
                     ? {}
                     : { childOutput: context.childOutput }),
@@ -594,6 +706,36 @@ export const devMachine = machineSetup.createMachine({
                             'rememberDecidePath',
                         ],
                     },
+                    {
+                        guard: 'isCodeViaPullRequest',
+                        target: 'createBranch',
+                        actions: [
+                            {
+                                type: 'playbook.acceptedOutcome',
+                                params: {
+                                    source: 'planAnalysis',
+                                    target: 'createBranch',
+                                    acceptedOutcome: 'codeViaPullRequest',
+                                },
+                            },
+                            'rememberCodeViaPullRequestPath',
+                        ],
+                    },
+                    {
+                        guard: 'isDecideThenCodeViaPullRequest',
+                        target: 'createBranch',
+                        actions: [
+                            {
+                                type: 'playbook.acceptedOutcome',
+                                params: {
+                                    source: 'planAnalysis',
+                                    target: 'createBranch',
+                                    acceptedOutcome: 'decideThenCodeViaPullRequest',
+                                },
+                            },
+                            'rememberDecideThenCodeViaPullRequestPath',
+                        ],
+                    },
                     {
                         guard: 'needsBossReply',
                         target: 'awaitBossReply',
@@ -617,6 +759,45 @@ export const devMachine = machineSetup.createMachine({
                 onError: { target: 'failed', actions: 'rememberActorError' },
             },
         },
+        createBranch: {
+            id: 'createBranch',
+            description: STATE_DESCRIPTIONS.createBranch,
+            meta: playbookMeta('createBranch'),
+            tags: ['playbook.suspended'],
+            invoke: {
+                src: 'playbook',
+                input: ({ context }) => ({
+                    stateId: 'createBranch',
+                    sourceItem: 'DEV-5',
+                    playbookId: 'branch',
+                    text: branchCallText(context),
+                }),
+                onDone: [
+                    {
+                        guard: 'isBranchSuccessForCode',
+                        target: 'callCode',
+                        actions: 'rememberBranchResult',
+                    },
+                    {
+                        guard: 'isBranchSuccessForDecide',
+                        target: 'callDecide',
+                        actions: 'rememberBranchResult',
+                    },
+                    {
+                        target: 'reportedChildFailure',
+                        actions: 'completeWithInsufficientBranchResult',
+                    },
+                ],
+                onError: [
+                    {
+                        guard: 'authoredBranchFailure',
+                        target: 'reportedChildFailure',
+                        actions: 'completeWithBranchFailure',
+                    },
+                    { target: 'failed', actions: 'rememberActorError' },
+                ],
+            },
+        },
         callCode: {
             id: 'callCode',
             description: STATE_DESCRIPTIONS.callCode,
@@ -632,7 +813,12 @@ export const devMachine = machineSetup.createMachine({
                 }),
                 onDone: [
                     {
-                        guard: 'isCodeSuccess',
+                        guard: 'isCodeSuccessViaPullRequest',
+                        target: 'openPullRequest',
+                        actions: 'rememberCodeResult',
+                    },
+                    {
+                        guard: 'isPlainCodeSuccess',
                         target: 'done',
                         actions: 'completeWithChildSuccess',
                     },
@@ -700,7 +886,12 @@ export const devMachine = machineSetup.createMachine({
                 }),
                 onDone: [
                     {
-                        guard: 'isCodeSuccess',
+                        guard: 'isCodeSuccessViaPullRequest',
+                        target: 'openPullRequest',
+                        actions: 'rememberCodeResult',
+                    },
+                    {
+                        guard: 'isPlainCodeSuccess',
                         target: 'done',
                         actions: 'completeWithChildSuccess',
                     },
@@ -719,6 +910,32 @@ export const devMachine = machineSetup.createMachine({
                 ],
             },
         },
+        openPullRequest: {
+            id: 'openPullRequest',
+            description: STATE_DESCRIPTIONS.openPullRequest,
+            meta: playbookMeta('openPullRequest'),
+            tags: ['playbook.suspended'],
+            invoke: {
+                src: 'playbook',
+                input: ({ context }) => ({
+                    stateId: 'openPullRequest',
+                    sourceItem: 'DEV-6',
+                    playbookId: 'pr',
+                    text: pullRequestCallText(context),
+                }),
+                // DR-048: `pr` declares its terminal kinds, so `onDone` alone proves
+                // its success; DEV consumes none of its fields by name.
+                onDone: { target: 'done', actions: 'completeWithChildSuccess' },
+                onError: [
+                    {
+                        guard: 'authoredPrFailure',
+                        target: 'reportedChildFailure',
+                        actions: 'completeWithPrFailure',
+                    },
+                    { target: 'failed', actions: 'rememberActorError' },
+                ],
+            },
+        },
         awaitBossReply: {
             id: 'awaitBossReply',
             description: STATE_DESCRIPTIONS.awaitBossReply,