@sublang/playbook 13.1.0 → 13.3.0

package/reference/sdlc/dev.playbook/dev.fsm.d.ts

@@ -1,9 +1,15 @@
 export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
     readonly [key: string]: JsonValue;
 };
-export type DevStateId = 'planAnalysis' | 'callCode' | 'callDecide' | 'callCodeAfterDecide';
-export type DevSourceItem = 'DEV-1' | 'DEV-2' | 'DEV-3' | 'DEV-4';
-export type DevChildPlaybookId = 'code' | 'decide';
+export type DevStateId = 'planAnalysis' | 'createBranch' | 'callCode' | 'callDecide' | 'callCodeAfterDecide' | 'openPullRequest';
+export type DevSourceItem = 'DEV-1' | 'DEV-2' | 'DEV-3' | 'DEV-4' | 'DEV-5' | 'DEV-6';
+export type DevChildPlaybookId = 'code' | 'decide' | 'branch' | 'pr';
+/**
+ * DR-050: the development path a pull-request planning outcome selected. It
+ * routes the `branch` success into `callCode` or `callDecide`, so the plain
+ * `code` and `decide then code` paths keep their items, prompts, and edges.
+ */
+export type DevPullRequestPath = 'code' | 'decide-then-code';
 export type PendingBossQuestion = {
     readonly questionId: 'planAnalysis';
     readonly resumeStateId: 'planAnalysis';
@@ -38,13 +44,19 @@ export type PlayerOutput = {
 } | {
     readonly guard: 'decideThenCode';
     readonly planningResult: string;
+} | {
+    readonly guard: 'codeViaPullRequest';
+    readonly planningResult: string;
+} | {
+    readonly guard: 'decideThenCodeViaPullRequest';
+    readonly planningResult: string;
 } | {
     readonly guard: 'needsBossReply';
     readonly question: string;
 };
 export type PlaybookInput = {
-    readonly stateId: 'callCode' | 'callDecide' | 'callCodeAfterDecide';
-    readonly sourceItem: 'DEV-2' | 'DEV-3' | 'DEV-4';
+    readonly stateId: 'createBranch' | 'callCode' | 'callDecide' | 'callCodeAfterDecide' | 'openPullRequest';
+    readonly sourceItem: 'DEV-2' | 'DEV-3' | 'DEV-4' | 'DEV-5' | 'DEV-6';
     readonly playbookId: DevChildPlaybookId;
     readonly text: string;
 };
@@ -60,6 +72,27 @@ export type DecideSuccessOutput = {
     readonly evaluatedRevision: string;
     readonly noUnsettledFindings: true;
 };
+/**
+ * The fields DEV consumes from `branch`'s canonical structured terminal
+ * output before continuing a pull-request path: the exact branch name, the
+ * exact base revision, and the issue summary. Additional members belong to
+ * BRANCH's own contract and do not disprove success; a missing member is an
+ * insufficient result, never an empty default.
+ */
+export type BranchSuccessOutput = {
+    readonly branch: string;
+    readonly baseRevision: string;
+    readonly issueSummary: string;
+};
+/**
+ * The fields DEV consumes from `code`'s canonical structured terminal output
+ * before starting the dependent `pr` call: the exact last `code`-owned commit
+ * and the exact final evaluated repository revision.
+ */
+export type CodeSuccessOutput = {
+    readonly lastCodeCommit: string;
+    readonly finalEvaluatedRevision: string;
+};
 export type CompactError = {
     readonly name: string;
     readonly message: string;
@@ -78,7 +111,8 @@ export type DevPlaybookOutput = {
     readonly status: 'discussion-complete';
 } | {
     readonly status: 'complete';
-    readonly childPlaybookId: 'code';
+    /** The final child of the selected path: `pr` on a pull-request path. */
+    readonly childPlaybookId: 'code' | 'pr';
     /** The successful result of DEV's final child call, when it has one. */
     readonly childOutput?: JsonValue;
 } | {
@@ -96,6 +130,14 @@ export type DevContext = {
     readonly planningResult?: string;
     readonly decideCommit?: string;
     readonly evaluatedRevision?: string;
+    /** DR-050: whether the accepted planning outcome selected a pull-request path. */
+    readonly deliveryViaPullRequest: boolean;
+    readonly pullRequestPath?: DevPullRequestPath;
+    readonly branch?: string;
+    readonly baseRevision?: string;
+    readonly issueSummary?: string;
+    readonly lastCodeCommit?: string;
+    readonly finalEvaluatedRevision?: string;
     readonly completion?: 'discussion-complete' | 'complete' | 'child-failed';
     readonly childOutput?: JsonValue;
     readonly childFailure?: CompletedChildResult;
@@ -164,24 +206,45 @@ export declare const devMachine: import("xstate").StateMachine<DevContext, {
 } | {
     type: "rememberDecidePath";
     params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberCodeViaPullRequestPath";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberDecideThenCodeViaPullRequestPath";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberBranchResult";
+    params: import("xstate").NonReducibleUnknown;
 } | {
     type: "rememberDecideResult";
     params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberCodeResult";
+    params: import("xstate").NonReducibleUnknown;
 } | {
     type: "completeWithChildSuccess";
     params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "completeWithInsufficientBranchResult";
+    params: import("xstate").NonReducibleUnknown;
 } | {
     type: "completeWithInsufficientCodeResult";
     params: import("xstate").NonReducibleUnknown;
 } | {
     type: "completeWithInsufficientDecideResult";
     params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "completeWithBranchFailure";
+    params: import("xstate").NonReducibleUnknown;
 } | {
     type: "completeWithCodeFailure";
     params: import("xstate").NonReducibleUnknown;
 } | {
     type: "completeWithDecideFailure";
     params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "completeWithPrFailure";
+    params: import("xstate").NonReducibleUnknown;
 }, {
     type: "needsBossReply";
     params: unknown;
@@ -198,25 +261,47 @@ export declare const devMachine: import("xstate").StateMachine<DevContext, {
     type: "isDecideThenCode";
     params: unknown;
 } | {
-    type: "isCodeSuccess";
+    type: "isCodeViaPullRequest";
+    params: unknown;
+} | {
+    type: "isDecideThenCodeViaPullRequest";
+    params: unknown;
+} | {
+    type: "isBranchSuccessForCode";
+    params: unknown;
+} | {
+    type: "isBranchSuccessForDecide";
+    params: unknown;
+} | {
+    type: "isCodeSuccessViaPullRequest";
+    params: unknown;
+} | {
+    type: "isPlainCodeSuccess";
     params: unknown;
 } | {
     type: "isDecideSuccess";
     params: unknown;
+} | {
+    type: "authoredBranchFailure";
+    params: unknown;
 } | {
     type: "authoredCodeFailure";
     params: unknown;
 } | {
     type: "authoredDecideFailure";
     params: unknown;
+} | {
+    type: "authoredPrFailure";
+    params: unknown;
 } | {
     type: "resumesPlanAnalysis";
     params: unknown;
-}, never, "done" | "failed" | "awaitBossReply" | "ready" | "planAnalysis" | "callCode" | "callDecide" | "callCodeAfterDecide" | "discussionComplete" | "reportedChildFailure", string, DevInput, {
+}, never, "done" | "failed" | "awaitBossReply" | "ready" | "planAnalysis" | "createBranch" | "callCode" | "callDecide" | "callCodeAfterDecide" | "openPullRequest" | "discussionComplete" | "reportedChildFailure", string, DevInput, {
     readonly status: "discussion-complete";
 } | {
     readonly status: "complete";
-    readonly childPlaybookId: "code";
+    /** The final child of the selected path: `pr` on a pull-request path. */
+    readonly childPlaybookId: "code" | "pr";
     /** The successful result of DEV's final child call, when it has one. */
     readonly childOutput?: JsonValue;
 } | {
@@ -232,6 +317,9 @@ export declare const devMachine: import("xstate").StateMachine<DevContext, {
         readonly planAnalysis: {
             id: "planAnalysis";
         };
+        readonly createBranch: {
+            id: "createBranch";
+        };
         readonly callCode: {
             id: "callCode";
         };
@@ -241,6 +329,9 @@ export declare const devMachine: import("xstate").StateMachine<DevContext, {
         readonly callCodeAfterDecide: {
             id: "callCodeAfterDecide";
         };
+        readonly openPullRequest: {
+            id: "openPullRequest";
+        };
         readonly awaitBossReply: {
             id: "awaitBossReply";
         };

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

@@ -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')
@@ -361,6 +408,31 @@ function codeAfterDecideCallText(context) {
         ['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,