@sublang/playbook 13.0.0 → 13.2.0

package/reference/sdlc/code.playbook/playbook-captain.js

@@ -2599,6 +2599,9 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             if (!ledger) {
                 throw new Error(`${frameLabel(frame)} resolved absent session player ${JSON.stringify(binding.playerId)}`);
             }
+            if (options.freshPrompt !== undefined && typeof options.freshPrompt !== 'string') {
+                throw new TypeError('player freshPrompt must be a string');
+            }
             const expectedResume = ledger.resumeToken ?? false;
             if (options.resume !== expectedResume) {
                 throw new Error(`${frameLabel(frame)} player continuation changed before dispatch`);
@@ -2625,7 +2628,7 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                     const call = async (resume) => {
                         await continuity?.beforeCall(binding.playerId);
                         signal.throwIfAborted();
-                        const raw = await trackHostCall(frame, classifySettingsCall(() => context.callPlayer(binding.playerId, prompt, { resume, settings })));
+                        const raw = await trackHostCall(frame, classifySettingsCall(() => context.callPlayer(binding.playerId, resume === false ? options.freshPrompt ?? prompt : prompt, { resume, settings })));
                         hostResolved = true;
                         return raw;
                     };

package/reference/sdlc/code.playbook/playbook-captain.ts

@@ -4361,6 +4361,9 @@ export function createPlaybookCaptainShell(
           `${frameLabel(frame)} resolved absent session player ${JSON.stringify(binding.playerId)}`,
         );
       }
+      if (options.freshPrompt !== undefined && typeof options.freshPrompt !== 'string') {
+        throw new TypeError('player freshPrompt must be a string');
+      }
       const expectedResume = ledger.resumeToken ?? false;
       if (options.resume !== expectedResume) {
         throw new Error(
@@ -4394,7 +4397,7 @@ export function createPlaybookCaptainShell(
             const raw = await trackHostCall(
               frame,
               classifySettingsCall(() =>
-                context.callPlayer(binding.playerId, prompt, { resume, settings }),
+                context.callPlayer(binding.playerId, resume === false ? options.freshPrompt ?? prompt : prompt, { resume, settings }),
               ),
             );
             hostResolved = true;

package/reference/sdlc/code.playbook/playbook.config.template.yaml

@@ -78,8 +78,8 @@ players:
 # `roles` are launcher-owned; every other key is that playbook's option
 # slice.
 #
-# Every manifest role is bound explicitly. CODE, REVIEW, and DECIDE
-# intentionally reuse the same two stable players, while DEV keeps its own
+# Every manifest role is bound explicitly. CODE, REVIEW, DECIDE, BRANCH, and
+# PR intentionally reuse the same two stable players, while DEV keeps its own
 # Analyst; change an id to isolate its conversation.
 playbooks:
   code:
@@ -103,3 +103,17 @@ playbooks:
     from: "@sublang/playbook/dev/registry"
     roles:
       analyst: dev.analyst
+
+  # Pull-request delivery for DEV (DR-050). BRANCH and PR bind Coder to the
+  # same dev.coder player as CODE and REVIEW on purpose: the Coder that read
+  # the issue and named the branch makes the commits and then describes
+  # them in the pull request. Change an id to isolate its conversation.
+  branch:
+    from: "@sublang/playbook/branch/registry"
+    roles:
+      coder: dev.coder
+
+  pr:
+    from: "@sublang/playbook/pr/registry"
+    roles:
+      coder: dev.coder

package/reference/sdlc/decide.md

@@ -15,6 +15,8 @@ When the caller gives a topic, Captain shall relay the complete topic in quotes
 Captain shall not wait for either proposal before requesting the other.
 Captain shall give the player bound to each role the following instruction:
 
+> Original topic: <caller-topic>
+
 ```markdown
 Assess whether the topic is better expressed as a few spec items under @specs/packages/ or requires one or more DRs under @specs/decisions/.
 Propose your design.

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

@@ -7,7 +7,7 @@ import { assign, fromPromise, setup } from 'xstate';
 export const concurrentRoleSets = [['coder', 'reviewer']];
 const NEEDS_BOSS_REPLY_DESCRIPTION = "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 INDEPENDENT_PROPOSAL_PROMPT = [
-    '> <caller-topic>',
+    '> Original topic: <caller-topic>',
     '',
     'Assess whether the topic is better expressed as a few spec items under @specs/packages/ or requires one or more DRs under @specs/decisions/.',
     'Propose your design.',

package/reference/sdlc/decide.playbook/decide.fsm.ts

@@ -148,7 +148,7 @@ const NEEDS_BOSS_REPLY_DESCRIPTION =
   "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 INDEPENDENT_PROPOSAL_PROMPT = [
-  '> <caller-topic>',
+  '> Original topic: <caller-topic>',
   '',
   'Assess whether the topic is better expressed as a few spec items under @specs/packages/ or requires one or more DRs under @specs/decisions/.',
   'Propose your design.',

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

@@ -22,7 +22,7 @@ Parallel group: independent-proposals
 
 When the caller gives a topic, Captain shall relay the complete topic to Coder in quotes and prompt Coder:
 
-> > <caller-topic>
+> > Original topic: <caller-topic>
 >
 > Assess whether the topic is better expressed as a few spec items under @specs/packages/ or requires one or more DRs under @specs/decisions/.
 > Propose your design.
@@ -39,7 +39,7 @@ Parallel group: independent-proposals
 
 When the caller gives a topic, Captain shall relay the complete topic to Reviewer in quotes and prompt Reviewer:
 
-> > <caller-topic>
+> > Original topic: <caller-topic>
 >
 > Assess whether the topic is better expressed as a few spec items under @specs/packages/ or requires one or more DRs under @specs/decisions/.
 > Propose your design.

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

@@ -10,7 +10,7 @@ export interface DecidePlaybookRuntimeConstruction {
     readonly hostCapabilities: DecidePlaybookHostCapabilities;
 }
 type PromptIdentity = (roleId: RoleId) => string;
-declare function composePlayerPrompt(input: PlayerInput, promptIdentity: PromptIdentity): string;
+declare function composePlayerPrompt(input: PlayerInput, promptIdentity: PromptIdentity, resuming?: boolean): string;
 declare function requiredFieldsFor(description: string): string[];
 declare function extractJson(raw: string): Record<string, unknown> | null;
 declare function buildClassifierPrompt(text: string, ctx: {
@@ -67,7 +67,6 @@ export declare const _internal: {
     VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string>;
     BOSS_INTERRUPT_TARGETS: readonly ["independentProposals"];
     UNFINISHED_FINAL_STATE_IDS: ReadonlySet<string>;
-    CONTINUATION_PREAMBLE: string;
     TELEMETRY_TOPIC: string;
 };
 export default createPlaybookRuntime;

package/reference/sdlc/decide.playbook/decide.playbook.js

@@ -19,7 +19,7 @@ import { randomUUID } from 'node:crypto';
 import PQueue from 'p-queue';
 import { createActor, fromPromise } from 'xstate';
 import { createAcceptedOutcomeConsumer, } from '../../../src/accepted-outcome.js';
-import { assertJsonSafe, assertPlaybookEffectLedger, assertPlaybookRuntimeSnapshot, combineAbortSignals, createNestedPlaybookBridge, detachPersistedMachineSnapshot, normalizeError, normalizePlaybookSnapshot, PlaybookSemanticCandidateStructureError, reconcilePlaybookSemanticEvidence, renderGovernedOutcomeContract, snapshotJsonValue, snapshotPlaybookSession, terminalOutcomesFromMachine, validatePlayerResult, waitForPlaybookQuiescence, } from '../../../src/xstate-runtime.js';
+import { assertJsonSafe, assertPlaybookEffectLedger, assertPlaybookRuntimeSnapshot, combineAbortSignals, composePlayerContinuation, createNestedPlaybookBridge, detachPersistedMachineSnapshot, normalizeError, normalizePlaybookSnapshot, PlaybookSemanticCandidateStructureError, reconcilePlaybookSemanticEvidence, renderGovernedOutcomeContract, snapshotJsonValue, snapshotPlaybookSession, terminalOutcomesFromMachine, validatePlayerResult, waitForPlaybookQuiescence, } from '../../../src/xstate-runtime.js';
 import decideMachine from './decide.fsm.js';
 function snapshotDecideRuntimeOptions(value) {
     const captured = snapshotJsonValue(value, 'DECIDE runtime options');
@@ -125,7 +125,6 @@ const TELEMETRY_TOPIC = 'playbook.fsm.state';
 const TRACE_TOPIC = 'playbook.trace';
 const UNRESOLVED_EFFECT_RECONCILIATION_ACTION_ID = 'reconcile:unresolved-effect';
 const UNRESOLVED_EFFECT_ABANDONMENT_ACTION_ID = 'abandon:unresolved-effect';
-const CONTINUATION_PREAMBLE = 'You previously paused this task to ask Boss a question; Boss has now replied. Continue the same task using the reply below.';
 const PLACEHOLDER_FIELDS = [
     ['<caller-topic>', 'callerTopic'],
     ['<reviewer-proposal>', 'reviewerProposal'],
@@ -135,19 +134,7 @@ const VERBATIM_PAYLOAD_FIELDS = new Set([
     'reviewerProposal',
     'coderOutput',
 ]);
-function composePlayerPrompt(input, promptIdentity) {
-    const blocks = [];
-    if (input.pendingBossQuestion && input.bossReply !== undefined) {
-        blocks.push([
-            CONTINUATION_PREAMBLE,
-            '',
-            'Boss question:',
-            input.pendingBossQuestion.question,
-            '',
-            'Boss reply:',
-            input.bossReply,
-        ].join('\n'));
-    }
+function composePlayerPrompt(input, promptIdentity, resuming = false) {
     const replacements = new Map();
     for (const [placeholder, field] of PLACEHOLDER_FIELDS) {
         const value = input[field];
@@ -171,8 +158,7 @@ function composePlayerPrompt(input, promptIdentity) {
             ? value.replaceAll('\n', '\n> ')
             : value;
     });
-    blocks.push(body);
-    return blocks.join('\n\n');
+    return composePlayerContinuation(input, body, resuming);
 }
 // A `result` description names required payload fields in its
 // "Output shall include ..." sentence.
@@ -883,7 +869,7 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
     };
     const resolvedPlayerId = (roleId) => requireSessionIdentity().roleBindings?.[roleId]?.playerId;
     const promptIdentity = (roleId) => requireSessionIdentity().roleBindings?.[roleId]?.promptIdentity ?? roleId;
-    const composeInvocationPrompt = (input) => {
+    const composeInvocationPrompt = (input, resuming = false) => {
         let active = true;
         const lookup = (roleId) => {
             if (!active) {
@@ -895,7 +881,7 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
             return promptIdentity(roleId);
         };
         try {
-            return composePlayerPrompt(input, lookup);
+            return composePlayerPrompt(input, lookup, resuming);
         }
         finally {
             active = false;
@@ -1339,7 +1325,7 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
         const roleId = input.role;
         const playerId = resolvedPlayerId(roleId);
         const playerKey = continuationKey(roleId, playerId);
-        const prompt = composeInvocationPrompt(input);
+        const freshPrompt = composeInvocationPrompt(input);
         let resume;
         try {
             signal.throwIfAborted();
@@ -1353,6 +1339,7 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
             latchControlPlaneError(error, signal);
             throw error;
         }
+        const prompt = resume === false ? freshPrompt : composeInvocationPrompt(input, true);
         const callId = continuation?.callId ?? `player-${++playerCallSequence}`;
         const identity = {
             stateId: input.stateId,
@@ -1384,7 +1371,7 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
             let rawResult;
             try {
                 signal.throwIfAborted();
-                const boundary = Promise.resolve(requirePorts().callPlayer(roleId, prompt, signal, { resume }));
+                const boundary = Promise.resolve(requirePorts().callPlayer(roleId, prompt, signal, { resume, ...(prompt === freshPrompt ? {} : { freshPrompt }) }));
                 rawResult = await boundary;
                 // An XState sibling cancellation does not cancel an arbitrary coder
                 // promise. Re-check before a late resolution can mutate continuity or
@@ -3586,7 +3573,6 @@ export const _internal = {
     VERBATIM_PAYLOAD_FIELDS,
     BOSS_INTERRUPT_TARGETS,
     UNFINISHED_FINAL_STATE_IDS,
-    CONTINUATION_PREAMBLE,
     TELEMETRY_TOPIC,
 };
 export default createPlaybookRuntime;

package/reference/sdlc/decide.playbook/decide.playbook.ts

@@ -32,6 +32,7 @@ import {
   assertPlaybookEffectLedger,
   assertPlaybookRuntimeSnapshot,
   combineAbortSignals,
+  composePlayerContinuation,
   createNestedPlaybookBridge,
   detachPersistedMachineSnapshot,
   normalizeError,
@@ -286,8 +287,6 @@ const UNRESOLVED_EFFECT_RECONCILIATION_ACTION_ID =
 const UNRESOLVED_EFFECT_ABANDONMENT_ACTION_ID =
   'abandon:unresolved-effect';
 
-const CONTINUATION_PREAMBLE =
-  'You previously paused this task to ask Boss a question; Boss has now replied. Continue the same task using the reply below.';
 
 const PLACEHOLDER_FIELDS: ReadonlyArray<readonly [string, keyof PlayerInput]> =
   [
@@ -306,23 +305,8 @@ type PromptIdentity = (roleId: RoleId) => string;
 function composePlayerPrompt(
   input: PlayerInput,
   promptIdentity: PromptIdentity,
+  resuming = false,
 ): string {
-  const blocks: string[] = [];
-
-  if (input.pendingBossQuestion && input.bossReply !== undefined) {
-    blocks.push(
-      [
-        CONTINUATION_PREAMBLE,
-        '',
-        'Boss question:',
-        input.pendingBossQuestion.question,
-        '',
-        'Boss reply:',
-        input.bossReply,
-      ].join('\n'),
-    );
-  }
-
   const replacements = new Map<string, string>();
   for (const [placeholder, field] of PLACEHOLDER_FIELDS) {
     const value = input[field];
@@ -348,8 +332,7 @@ function composePlayerPrompt(
     },
   );
 
-  blocks.push(body);
-  return blocks.join('\n\n');
+  return composePlayerContinuation(input, body, resuming);
 }
 
 // A `result` description names required payload fields in its
@@ -1518,7 +1501,7 @@ function createDecidePlaybookRuntime(
   const promptIdentity = (roleId: RoleId): string =>
     requireSessionIdentity().roleBindings?.[roleId]?.promptIdentity ?? roleId;
 
-  const composeInvocationPrompt = (input: PlayerInput): string => {
+  const composeInvocationPrompt = (input: PlayerInput, resuming = false): string => {
     let active = true;
     const lookup: PromptIdentity = (roleId) => {
       if (!active) {
@@ -1534,7 +1517,7 @@ function createDecidePlaybookRuntime(
       return promptIdentity(roleId);
     };
     try {
-      return composePlayerPrompt(input, lookup);
+      return composePlayerPrompt(input, lookup, resuming);
     } finally {
       active = false;
     }
@@ -2182,7 +2165,7 @@ function createDecidePlaybookRuntime(
     const roleId = input.role;
     const playerId = resolvedPlayerId(roleId);
     const playerKey = continuationKey(roleId, playerId);
-    const prompt = composeInvocationPrompt(input);
+    const freshPrompt = composeInvocationPrompt(input);
     let resume: PlayerCallOptions['resume'];
     try {
       signal.throwIfAborted();
@@ -2195,6 +2178,7 @@ function createDecidePlaybookRuntime(
       latchControlPlaneError(error, signal);
       throw error;
     }
+    const prompt = resume === false ? freshPrompt : composeInvocationPrompt(input, true);
     const callId =
       continuation?.callId ?? `player-${++playerCallSequence}`;
     const identity = {
@@ -2249,7 +2233,7 @@ function createDecidePlaybookRuntime(
       try {
         signal.throwIfAborted();
         const boundary = Promise.resolve(
-          requirePorts().callPlayer(roleId, prompt, signal, { resume }),
+          requirePorts().callPlayer(roleId, prompt, signal, { resume, ...(prompt === freshPrompt ? {} : { freshPrompt }) }),
         );
         rawResult = await boundary;
         // An XState sibling cancellation does not cancel an arbitrary coder
@@ -5081,7 +5065,6 @@ export const _internal = {
   VERBATIM_PAYLOAD_FIELDS,
   BOSS_INTERRUPT_TARGETS,
   UNFINISHED_FINAL_STATE_IDS,
-  CONTINUATION_PREAMBLE,
   TELEMETRY_TOPIC,
 };
 

package/reference/sdlc/dev.md

@@ -15,6 +15,10 @@ It coordinates existing playbooks and owns no repository commit itself.
 
 At the start of `dev` and after each Boss reply, Captain shall relay the development request, relevant discussion context, and any relevant run results to Analyst in quotes (`>`), along with the following instruction:
 
+> Original request: <development-request>
+> Prior discussion: <discussion-context>
+> Run results: <run-results>
+
 ```markdown
 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.
@@ -23,30 +27,67 @@ Do not change files or commit while planning or discussing the request.
 - 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.
 Consult @specs/map.md for relevant context and @specs/meta.md for spec requirements, if needed.
 ```
 
-The planning result has four semantic outcomes: needs Boss reply, discussion complete, code, and decide then code.
+The planning result has six semantic outcomes: needs Boss reply, discussion complete, code, decide then code, code via pull request, and decide then code via pull request.
 Each outcome requires affirmative support in Analyst's result; absence of a reason to choose another outcome is not support.
 No outcome depends on a fixed presentation format of Analyst's reply.
 `dev` shall act on the accepted outcome itself and shall not return to the session Captain for another routing decision.
 
 For needs Boss reply, `dev` shall use the standard Boss-question suspension with Analyst's complete response.
-The session Captain shall present that response to Boss and, after Boss replies, resume `dev` with the question and answer in the same Analyst conversation.
+The session Captain shall present that response to Boss and, after Boss replies, resume `dev` with the answer in the same Analyst conversation; include the previous question only when that conversation must start fresh.
 
 Discussion complete is available only after a Boss reply, when any useful analysis has already been presented through needs Boss reply.
 It completes `dev` without a child call or repository change.
 
 For code, `dev` shall directly call playbook `code` with the development request, relevant discussion context, and planning result in quotes (`>`).
 
+> Original request: <development-request>
+> Prior discussion: <discussion-context>
+> Planning result: <planning-result>
+
 For decide then code, `dev` shall call playbook `decide` with the development request, relevant discussion context, and planning result in quotes (`>`).
+
+> Original request: <development-request>
+> Prior discussion: <discussion-context>
+> Planning result: <planning-result>
+
 Only after `decide` succeeds shall `dev` call playbook `code` with the development request, relevant discussion context, planning result, `decide`-owned commit, and exact evaluated repository revision in quotes (`>`).
+
+> Original request: <development-request>
+> Prior discussion: <discussion-context>
+> Planning result: <planning-result>
+> DECIDE commit: <decide-commit>
+> Evaluated revision: <evaluated-revision>
+
 `dev` shall not separately call `review` for the design scope already reviewed by `decide`.
 
+For code via pull request and decide then code via pull request, `dev` shall first call playbook `branch` with the development request, relevant discussion context, and planning result in quotes (`>`).
+
+> Original request: <development-request>
+> Prior discussion: <discussion-context>
+> Planning result: <planning-result>
+
+Only after `branch` succeeds shall `dev` continue with the `code` call for code via pull request, or the `decide` call and then the `code` call for decide then code via pull request, each with the same input as its plain path above.
+
+On a plain path, `code` success completes `dev`.
+On a pull-request path, only after `code` succeeds shall `dev` call playbook `pr` with the development request, issue summary, branch, base revision, last `code`-owned commit, and exact final evaluated repository revision in quotes (`>`).
+
+> Original request: <development-request>
+> Issue summary: <issue-summary>
+> Branch: <branch>
+> Base revision: <base-revision>
+> CODE commit: <last-code-commit>
+> Evaluated revision: <final-evaluated-revision>
+
+A plain request calls neither `branch` nor `pr`.
+
 `dev` completes with the successful result of its final child call.
-If a child returns an authored abort or failure, or a terminal result that does not prove the success required for the selected path, `dev` shall start no later child and shall relay that canonical result.
+If a child returns an authored abort or failure, or a terminal result that does not prove the success required for the selected path, `dev` shall start no later child and shall relay that canonical result; a `branch` or `pr` failure ends `dev` under this same rule.
 If a child call fails outside its authored result contract, `dev` shall park as failed and retain the control-plane error.
-`dev` shall consume commit identities only from each child's canonical structured result, never from player prose.
+`dev` shall consume commit, revision, branch, and pull-request identities only from each child's canonical structured result, never from player prose.

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";
         };