@sublang/playbook 13.0.0 → 13.2.0

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

@@ -16,9 +16,9 @@ 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 planning instruction:
 
-> > <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.
@@ -27,6 +27,7 @@ At the start of `dev` and after each Boss reply, Captain shall relay the develop
 > - 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.
@@ -36,11 +37,13 @@ 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>`.
 
 Workflow outcomes:
-- 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, and no outcome depends on a fixed presentation format of Analyst's reply.
-- Needs Boss reply uses the standard Boss-question suspension with Analyst's complete response; after Boss replies, `dev` resumes with the question and answer in the same Analyst conversation.
+- Needs Boss reply uses the standard Boss-question suspension with Analyst's complete response; after Boss replies, `dev` resumes with the answer in the same Analyst conversation; the previous question is included 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.
 - `dev` acts on the accepted outcome itself and does not return to the session Captain for another routing decision.
 
@@ -48,25 +51,26 @@ Workflow outcomes:
 
 ### DEV-2
 
-When the accepted planning result selects `code`, Captain shall call playbook `code`:
+When the accepted planning result selects `code`, or `branch` succeeds for `code via pull request`, Captain shall call playbook `code`:
 
-> > <development-request>
-> > <discussion-context>
-> > <planning-result>
+> > Original request: <development-request>
+> > Prior discussion: <discussion-context>
+> > Planning result: <planning-result>
 
 Workflow outcomes:
-- `code` success completes `dev` with the successful `code` result.
+- On a plain path, `code` success completes `dev` with the successful `code` result.
+- On a pull-request path, `code` success provides the exact last `code`-owned commit and the exact final evaluated repository revision from `code`'s canonical structured result and continues with the `pr` call.
 - An authored `code` abort or failure, or a terminal `code` result that does not prove the success required for the selected path, terminates `dev` with that canonical result relayed and no later child call.
 - Any other nested-call error parks `dev` as failed and retains the control-plane error.
-- `dev` consumes commit identities only from each child's canonical structured result, never from player prose.
+- `dev` consumes commit, revision, branch, and pull-request identities only from each child's canonical structured result, never from player prose.
 
 ### DEV-3
 
-When the accepted planning result selects `decide then code`, Captain shall call playbook `decide`:
+When the accepted planning result selects `decide then code`, or `branch` succeeds for `decide then code via pull request`, Captain shall call playbook `decide`:
 
-> > <development-request>
-> > <discussion-context>
-> > <planning-result>
+> > Original request: <development-request>
+> > Prior discussion: <discussion-context>
+> > Planning result: <planning-result>
 
 Workflow outcomes:
 - `decide` success provides the `decide`-owned commit and the exact evaluated repository revision from `decide`'s canonical structured result and continues with the `code` call.
@@ -78,14 +82,48 @@ Workflow outcomes:
 
 When `decide` succeeds, Captain shall call playbook `code`:
 
-> > <development-request>
-> > <discussion-context>
-> > <planning-result>
-> > <decide-commit>
-> > <evaluated-revision>
+> > Original request: <development-request>
+> > Prior discussion: <discussion-context>
+> > Planning result: <planning-result>
+> > DECIDE commit: <decide-commit>
+> > Evaluated revision: <evaluated-revision>
 
 Workflow outcomes:
-- `code` success completes `dev` with the successful `code` result.
+- On a plain path, `code` success completes `dev` with the successful `code` result.
+- On a pull-request path, `code` success provides the exact last `code`-owned commit and the exact final evaluated repository revision from `code`'s canonical structured result and continues with the `pr` call.
 - An authored `code` abort or failure, or a terminal `code` result that does not prove the success required for the selected path, terminates `dev` with that canonical result relayed and no later child call.
 - Any other nested-call error parks `dev` as failed and retains the control-plane error.
-- `dev` consumes commit identities only from each child's canonical structured result, never from player prose.
+- `dev` consumes commit, revision, branch, and pull-request identities only from each child's canonical structured result, never from player prose.
+
+## Pull-request delivery
+
+### DEV-5
+
+When the accepted planning result selects `code via pull request` or `decide then code via pull request`, Captain shall call playbook `branch`:
+
+> > Original request: <development-request>
+> > Prior discussion: <discussion-context>
+> > Planning result: <planning-result>
+
+Workflow outcomes:
+- `branch` success provides the exact branch name, the exact base revision, and the issue summary from `branch`'s canonical structured result and continues 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.
+- An authored `branch` abort or failure, or a terminal `branch` result that does not prove that success, terminates `dev` with that canonical result relayed and no later child call.
+- Any other nested-call error parks `dev` as failed and retains the control-plane error.
+- A plain request calls neither `branch` nor `pr`.
+
+### DEV-6
+
+When `code` succeeds on a pull-request path, Captain shall call playbook `pr`:
+
+> > Original request: <development-request>
+> > Issue summary: <issue-summary>
+> > Branch: <branch>
+> > Base revision: <base-revision>
+> > CODE commit: <last-code-commit>
+> > Evaluated revision: <final-evaluated-revision>
+
+Workflow outcomes:
+- `pr` success completes `dev` with the successful `pr` result.
+- An authored `pr` abort or failure, or a terminal `pr` result that does not prove the success required for the selected path, terminates `dev` with that canonical result relayed and no later child call.
+- Any other nested-call error parks `dev` as failed and retains the control-plane error.
+- `dev` consumes 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.playbook.d.ts

@@ -11,7 +11,7 @@ export type DevPlaybookHostCapabilities = PlaybookHostConstructionCapabilities &
  * override additionally keeps a multiline value inside that quote and drops
  * the optional relays that have no value yet.
  */
-declare function composePlayerPrompt(input: PlayerInput): string;
+declare function composePlayerPrompt(input: PlayerInput, resuming?: boolean): string;
 export declare const _internal: {
     composePlayerPrompt: typeof composePlayerPrompt;
     VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string>;

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

@@ -9,13 +9,14 @@
 //                BOSS_REPLY
 // Adjudication:  LLM judge for the one Analyst state; planningResult is
 //                carried verbatim
-// Nested calls:  literal code and decide targets through the shared bridge
+// Nested calls:  literal code, decide, branch, and pr targets through the
+//                shared bridge; branch, revision, commit, and pull-request
+//                identities enter only from canonical child results
 // Compat:        artifact schema 3 / runtime ABI 1
-import { createXStatePlaybookRuntime, snapshotJsonValue, } from '@sublang/playbook/xstate-runtime';
+import { createXStatePlaybookRuntime, composePlayerContinuation, snapshotJsonValue, } from '@sublang/playbook/xstate-runtime';
 import { devMachine, } from './dev.fsm.js';
 const OPTION_KEYS = new Set(['runResults']);
 const PLACEHOLDER = /<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>/g;
-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 VERBATIM_PAYLOAD_FIELDS = new Set([
     'planningResult',
 ]);
@@ -54,13 +55,13 @@ function quotedContinuation(value) {
  * override additionally keeps a multiline value inside that quote and drops
  * the optional relays that have no value yet.
  */
-function composePlayerPrompt(input) {
+function composePlayerPrompt(input, resuming = false) {
     const fields = input;
     const template = input.prompt
         .split('\n')
-        .filter((line) => !(line === '> <discussion-context>' &&
+        .filter((line) => !(line === '> Prior discussion: <discussion-context>' &&
         input.discussionContext.length === 0) &&
-        !(line === '> <run-results>' && input.runResults.length === 0))
+        !(line === '> Run results: <run-results>' && input.runResults.length === 0))
         .join('\n');
     const body = template.replace(PLACEHOLDER, (match, token, offset, source) => {
         const value = fields[placeholderField(token)];
@@ -68,18 +69,9 @@ function composePlayerPrompt(input) {
             return match;
         const lineStart = source.lastIndexOf('\n', offset - 1) + 1;
         const literal = source.slice(lineStart, offset);
-        return literal === '> ' ? quotedContinuation(value) : value;
+        return literal.startsWith('> ') ? quotedContinuation(value) : value;
     });
-    if (input.pendingBossQuestion === undefined ||
-        input.bossReply === undefined) {
-        return body;
-    }
-    return [
-        CONTINUATION_PREAMBLE,
-        `Boss question:\n${input.pendingBossQuestion.question}`,
-        `Boss reply:\n${input.bossReply}`,
-        body,
-    ].join('\n\n');
+    return composePlayerContinuation(input, body, resuming);
 }
 export const _internal = {
     composePlayerPrompt,
@@ -126,6 +118,16 @@ const runtimeSpec = {
                     fields: { planningResult: 'presentation' },
                     repositoryDisposition: 'unchanged',
                 },
+                // DR-050: reading a GitHub issue during planning is not an effect, so
+                // the two pull-request outcomes stay `unchanged` like the plain ones.
+                codeViaPullRequest: {
+                    fields: { planningResult: 'presentation' },
+                    repositoryDisposition: 'unchanged',
+                },
+                decideThenCodeViaPullRequest: {
+                    fields: { planningResult: 'presentation' },
+                    repositoryDisposition: 'unchanged',
+                },
                 needsBossReply: {
                     fields: { question: 'presentation' },
                     repositoryDisposition: 'unchanged',
@@ -133,7 +135,7 @@ const runtimeSpec = {
             },
         },
     },
-    composePlayerPrompt: (input) => composePlayerPrompt(input),
+    composePlayerPrompt: (input, _identity, resuming) => composePlayerPrompt(input, resuming),
     verbatimPayloadFields: VERBATIM_PAYLOAD_FIELDS,
     controlContextFields: [],
     unfinishedFinalStateIds: UNFINISHED_FINAL_STATE_IDS,

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

@@ -9,11 +9,14 @@
 //                BOSS_REPLY
 // Adjudication:  LLM judge for the one Analyst state; planningResult is
 //                carried verbatim
-// Nested calls:  literal code and decide targets through the shared bridge
+// Nested calls:  literal code, decide, branch, and pr targets through the
+//                shared bridge; branch, revision, commit, and pull-request
+//                identities enter only from canonical child results
 // Compat:        artifact schema 3 / runtime ABI 1
 
 import {
   createXStatePlaybookRuntime,
+  composePlayerContinuation,
   snapshotJsonValue,
   type PlaybookPlayerInput,
   type XStatePlaybookRuntimeFactory,
@@ -85,8 +88,6 @@ export type DevPlaybookHostCapabilities =
 
 const OPTION_KEYS = new Set(['runResults']);
 const PLACEHOLDER = /<(#|[A-Za-z_$][A-Za-z0-9_$-]*)>/g;
-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 VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string> = new Set([
   'planningResult',
@@ -133,17 +134,17 @@ function quotedContinuation(value: string): string {
  * override additionally keeps a multiline value inside that quote and drops
  * the optional relays that have no value yet.
  */
-function composePlayerPrompt(input: PlayerInput): string {
+function composePlayerPrompt(input: PlayerInput, resuming = false): string {
   const fields = input as unknown as Record<string, unknown>;
   const template = input.prompt
     .split('\n')
     .filter(
       (line) =>
         !(
-          line === '> <discussion-context>' &&
+          line === '> Prior discussion: <discussion-context>' &&
           input.discussionContext.length === 0
         ) &&
-        !(line === '> <run-results>' && input.runResults.length === 0),
+        !(line === '> Run results: <run-results>' && input.runResults.length === 0),
     )
     .join('\n');
   const body = template.replace(
@@ -153,21 +154,10 @@ function composePlayerPrompt(input: PlayerInput): string {
       if (typeof value !== 'string') return match;
       const lineStart = source.lastIndexOf('\n', offset - 1) + 1;
       const literal = source.slice(lineStart, offset);
-      return literal === '> ' ? quotedContinuation(value) : value;
+      return literal.startsWith('> ') ? quotedContinuation(value) : value;
     },
   );
-  if (
-    input.pendingBossQuestion === undefined ||
-    input.bossReply === undefined
-  ) {
-    return body;
-  }
-  return [
-    CONTINUATION_PREAMBLE,
-    `Boss question:\n${input.pendingBossQuestion.question}`,
-    `Boss reply:\n${input.bossReply}`,
-    body,
-  ].join('\n\n');
+  return composePlayerContinuation(input, body, resuming);
 }
 
 export const _internal = {
@@ -217,6 +207,16 @@ const runtimeSpec = {
           fields: { planningResult: 'presentation' },
           repositoryDisposition: 'unchanged',
         },
+        // DR-050: reading a GitHub issue during planning is not an effect, so
+        // the two pull-request outcomes stay `unchanged` like the plain ones.
+        codeViaPullRequest: {
+          fields: { planningResult: 'presentation' },
+          repositoryDisposition: 'unchanged',
+        },
+        decideThenCodeViaPullRequest: {
+          fields: { planningResult: 'presentation' },
+          repositoryDisposition: 'unchanged',
+        },
         needsBossReply: {
           fields: { question: 'presentation' },
           repositoryDisposition: 'unchanged',
@@ -224,8 +224,8 @@ const runtimeSpec = {
       },
     },
   },
-  composePlayerPrompt: (input: PlaybookPlayerInput) =>
-    composePlayerPrompt(input as PlayerInput),
+  composePlayerPrompt: (input: PlaybookPlayerInput, _identity, resuming) =>
+    composePlayerPrompt(input as PlayerInput, resuming),
   verbatimPayloadFields: VERBATIM_PAYLOAD_FIELDS,
   controlContextFields: [],
   unfinishedFinalStateIds: UNFINISHED_FINAL_STATE_IDS,

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

@@ -29,7 +29,7 @@ export interface DevPlaybookRegistryEntry {
 export declare const devStateCountLabels: {
     readonly planAnalysis: "planning round";
 };
-export declare const devCopyPasteGuardNames: readonly ["code", "decideThenCode"];
+export declare const devCopyPasteGuardNames: readonly ["code", "decideThenCode", "codeViaPullRequest", "decideThenCodeViaPullRequest"];
 export declare function devSavedCountsLine(counts: {
     interruptions: number;
     copyPastes: number;

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

@@ -7,7 +7,12 @@ import createPlaybookRuntime from './dev.playbook.js';
 export const devStateCountLabels = {
     planAnalysis: 'planning round',
 };
-export const devCopyPasteGuardNames = ['code', 'decideThenCode'];
+export const devCopyPasteGuardNames = [
+    'code',
+    'decideThenCode',
+    'codeViaPullRequest',
+    'decideThenCodeViaPullRequest',
+];
 function countNoun(count, singular, plural = `${singular}s`) {
     return `${count} ${count === 1 ? singular : plural}`;
 }
@@ -44,7 +49,7 @@ export function validateDevOptions(optionSlice) {
 export const devPlaybookRegistryEntry = {
     id: 'dev',
     command: 'dev',
-    intent: 'analyze a development request that needs planning before choosing direct implementation or a durable decision first',
+    intent: 'analyze a development request that needs planning before choosing direct implementation or a durable decision first, delivered through a pull request when the request names a GitHub issue or asks for one',
     artifactSchema: 3,
     runtimeProfile: Object.freeze({
         kind: 'shared-factory',

package/reference/sdlc/dev.playbook/dev.registry.ts

@@ -46,7 +46,12 @@ export const devStateCountLabels = {
   planAnalysis: 'planning round',
 } as const;
 
-export const devCopyPasteGuardNames = ['code', 'decideThenCode'] as const;
+export const devCopyPasteGuardNames = [
+  'code',
+  'decideThenCode',
+  'codeViaPullRequest',
+  'decideThenCodeViaPullRequest',
+] as const;
 
 function countNoun(
   count: number,
@@ -99,7 +104,7 @@ export const devPlaybookRegistryEntry: DevPlaybookRegistryEntry = {
   id: 'dev',
   command: 'dev',
   intent:
-    'analyze a development request that needs planning before choosing direct implementation or a durable decision first',
+    'analyze a development request that needs planning before choosing direct implementation or a durable decision first, delivered through a pull request when the request names a GitHub issue or asks for one',
   artifactSchema: 3,
   runtimeProfile: Object.freeze({
     kind: 'shared-factory',

package/reference/sdlc/pr.md

@@ -0,0 +1,108 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
+<!-- AI agents: do not edit this file without human approval. -->
+
+# PR
+
+Roles:
+
+- Coder
+
+The caller supplies:
+
+- the original request, including the issue it names, if any;
+- the issue summary;
+- the branch to deliver and the base revision it was created from;
+- the last `code`-owned commit and the exact evaluated repository revision;
+- optional relevant context.
+
+`pr` delivers a reviewed branch into the repository default branch through a GitHub pull request: it publishes the branch, waits for the pull request's checks, fixes red checks through playbook `code` no more than once, and merges.
+It changes no files and owns no repository commit; the one fix it may request is owned by `code`.
+The check waits, the fix publication, the merge, and the local update are mechanical steps: each runs one fixed command whose exit status alone decides its two outcomes, reads no conversation, and produces no prose.
+`gh` infers the pull request from the checked-out branch, so no mechanical step needs a runtime value.
+
+When the caller gives its input, Captain shall relay the complete caller input in quotes (`>`) to Coder, along with the following instruction:
+
+> Original request: <caller-input>
+
+```markdown
+Publish the branch and open its pull request without changing any file or making any commit.
+Confirm that the working tree is clean and that the checked-out branch is the branch to deliver, not the repository default branch.
+Push the branch to the repository's GitHub remote with its upstream set; never force-push.
+If an open pull request for this branch already exists, use it; otherwise open one against the repository default branch with `gh pr create`.
+Give the pull request a title naming the change and a body with a summary of what changed and why from the base revision to the last commit, the verification the commits report, and a `Closes #N` line for issue number N when the request names one.
+Report the pull request number and URL exactly.
+If the working tree is not clean, the checked-out branch is wrong, the push is rejected, or the pull request cannot be opened, open nothing further and report the failure with its reason.
+```
+
+The result has two semantic outcomes: opened and not published.
+Each outcome requires affirmative support in Coder's result, and no outcome depends on a fixed presentation format of Coder's reply.
+Every outcome keeps the repository exact: pushing a branch and opening a pull request change neither HEAD's commit nor the working tree.
+For not published, `pr` fails and reports Coder's complete result with its reason to its caller.
+
+When the pull request is open and no fix has been attempted, Captain shall wait for the pull request's checks by running exactly the following command in the repository, with no other action and without reading its output:
+
+> n=0
+> while gh pr checks 2>&1 | grep -q 'no checks reported'; do
+> n=$((n + 1))
+> [ "$n" -ge 6 ] && exit 0
+> sleep 10
+> done
+> gh pr checks --watch --fail-fast >/dev/null 2>&1
+
+The wait has exactly two outcomes decided by the command's exit status alone: checks passed on status zero and checks failed otherwise.
+A pull request whose repository still reports no checks after a brief wait for them to register counts as passed.
+
+When the checks fail before any fix attempt, Captain shall call playbook `code` with the original request, the pull request, and the coding request in quotes (`>`):
+
+> Original request: <caller-input>
+> Pull request: <pull-request-url>
+> Coding request: The pull request's checks are red on the checked-out branch. Inspect the failing checks with `gh pr checks` and `gh run view --log-failed`, fix their cause on this branch with a minimal change, and make the checks pass.
+
+`pr` makes no more than one fix attempt.
+Only after `code` succeeds shall `pr` publish the fix and wait for the checks again.
+When `code` returns an authored abort or failure, or a terminal result that does not prove its success, `pr` shall fail relaying that canonical result and shall leave the pull request open.
+When the nested `code` call fails outside that authored result contract, `pr` shall park as failed and retain the control-plane error instead of reporting an authored outcome.
+
+When `code` succeeds, Captain shall publish the fix to the pull request by running exactly the following command in the repository, with no other action and without reading its output:
+
+> git push || exit 1
+> n=0
+> until [ "$(gh pr view --json headRefOid --jq .headRefOid 2>/dev/null)" = "$(git rev-parse HEAD)" ]; do
+> n=$((n + 1))
+> [ "$n" -ge 12 ] && exit 1
+> sleep 5
+> done
+
+The publication has exactly two outcomes decided by the exit status alone: fix published on status zero, once the pull request's head is the pushed commit, and fix not published otherwise.
+Fix not published is an authored failure that leaves the pull request open.
+
+When the fix is published, Captain shall wait for the pull request's checks again by running exactly the same command as the first wait in the repository, with no other action and without reading its output:
+
+> n=0
+> while gh pr checks 2>&1 | grep -q 'no checks reported'; do
+> n=$((n + 1))
+> [ "$n" -ge 6 ] && exit 0
+> sleep 10
+> done
+> gh pr checks --watch --fail-fast >/dev/null 2>&1
+
+This wait has exactly two outcomes decided by the exit status alone: checks passed on status zero and checks still failing otherwise.
+Checks still failing is an authored failure that leaves the pull request open; there is no second fix attempt.
+
+When the checks pass, before or after the one fix attempt, Captain shall merge the pull request by running exactly the following command in the repository, with no other action and without reading its output:
+
+> gh pr merge --merge --delete-branch --match-head-commit "$(git rev-parse HEAD)"
+
+The merge creates a merge commit on the repository default branch, deletes the remote and local branch, and checks out the local default branch; GitHub closes the linked issue on merge.
+The merge has exactly two outcomes decided by the exit status alone: merged on status zero and merge refused otherwise.
+Merge refused is an authored failure that leaves the pull request in the state GitHub reports: GitHub refused the merge for a conflict, a branch protection, a forbidden merge method, or a head that moved, or the merge landed but the local switch to the default branch or the branch deletion failed.
+
+When the pull request is merged, Captain shall bring the local default branch to the merged head by running exactly the following command in the repository, with no other action and without reading its output:
+
+> git pull --ff-only
+
+The update has exactly two outcomes decided by the exit status alone: local default updated on status zero and local default not updated otherwise.
+Both complete `pr`: the pull request is merged either way, and the result states whether the local default branch was fast-forwarded to the merged head.
+
+On completion, `pr` returns the pull request number and URL, the fact that the pull request is merged, and whether the local default branch was fast-forwarded to the merged head.