@sublang/playbook 13.3.0 → 14.0.0

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

@@ -20,9 +20,34 @@ const OPEN_PULL_REQUEST_RESULTS = {
     notPublished: 'Coder reported that the branch could not be published or its pull request could not be opened, with the reason. Output shall include `coderOutput: <verbatim final text>`.',
     needsBossReply: NEEDS_BOSS_REPLY_RESULT,
 };
-// The mechanical steps are static POSIX shell text (slc/optimize.md): no
-// placeholder, no runtime value, and no prose — `gh` infers the pull request
-// from the checked-out branch.
+// The mechanical steps are static POSIX shell text (slc/optimize.md) with no
+// prose. `gh` infers the pull request from the checked-out branch, which the
+// run does not own, so the two steps that act on the pull request itself relay
+// one runtime value — the pull request PR-1 published — through the same
+// placeholder relay an acting prompt uses.
+// The placeholder occupies a single-quoted shell word, and binding replaces
+// that whole word — quotes included — with the value's own quoted literal.
+const QUOTED_PULL_REQUEST_URL = "'<pull-request-url>'";
+// A retained value is reported text, so it reaches the shell as one
+// single-quoted literal word: no command substitution, no expansion, no word
+// splitting. A single quote inside the value closes the literal, escapes
+// itself, and reopens it — the only character single quotes cannot hold.
+function shellLiteral(value) {
+    return `'${value.split("'").join("'\\''")}'`;
+}
+// Bind the retained identity into a script command. Without it the quoted
+// placeholder stays, and no `gh` output equals it, so the step refuses instead
+// of acting on whatever the checkout now infers. Every script state is
+// reachable only after `rememberPullRequest`, so the refusal is unreachable by
+// construction and exists to keep the failure closed if that ever changes.
+function scriptCommand(command, context) {
+    const url = context.pullRequestUrl;
+    if (!isNonEmptyString(url))
+        return command;
+    // A function replacement keeps `$`-patterns in the value from being read as
+    // replacement syntax.
+    return command.replaceAll(QUOTED_PULL_REQUEST_URL, () => shellLiteral(url));
+}
 const WAIT_FOR_CHECKS_COMMAND = [
     'n=0',
     "while gh pr checks 2>&1 | grep -q 'no checks reported'; do",
@@ -33,6 +58,7 @@ const WAIT_FOR_CHECKS_COMMAND = [
     'gh pr checks --watch --fail-fast >/dev/null 2>&1',
 ].join('\n');
 const PUBLISH_FIX_COMMAND = [
+    '[ "$(gh pr view --json url --jq .url)" = \'<pull-request-url>\' ] || exit 1',
     'git push || exit 1',
     'n=0',
     'until [ "$(gh pr view --json headRefOid --jq .headRefOid 2>/dev/null)" = "$(git rev-parse HEAD)" ]; do',
@@ -41,7 +67,7 @@ const PUBLISH_FIX_COMMAND = [
     'sleep 5',
     'done',
 ].join('\n');
-const MERGE_PULL_REQUEST_COMMAND = 'gh pr merge --merge --delete-branch --match-head-commit "$(git rev-parse HEAD)"';
+const MERGE_PULL_REQUEST_COMMAND = "pr=$(gh pr view --json url --jq .url) || exit 1\n[ \"$pr\" = '<pull-request-url>' ] || exit 1\nbase=$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name) || exit 1\n[ -n \"$base\" ] || exit 1\n[ \"$(gh pr view \"$pr\" --json baseRefName --jq .baseRefName)\" = \"$base\" ] || exit 1\ngh pr merge --merge --delete-branch --match-head-commit \"$(git rev-parse HEAD)\" || exit 1\n[ \"$(gh pr view \"$pr\" --json state --jq .state)\" = MERGED ] || exit 1\n[ \"$(git branch --show-current)\" = \"$base\" ]";
 const UPDATE_LOCAL_DEFAULT_COMMAND = 'git pull --ff-only';
 const WAIT_FOR_CHECKS_RESULTS = {
     checksPassed: "The command exited with status zero: the pull request's checks passed, or the repository still reported no checks after a brief wait for them to register.",
@@ -49,15 +75,15 @@ const WAIT_FOR_CHECKS_RESULTS = {
 };
 const PUBLISH_FIX_RESULTS = {
     fixPublished: "The command exited with status zero: the fix is pushed and the pull request's head is the pushed commit.",
-    fixNotPublished: "The command exited with a nonzero status: the push was rejected or the pull request's head did not advance to the pushed commit.",
+    fixNotPublished: "The command exited with a nonzero status: the checkout no longer infers the published pull request, the push was rejected, or the pull request's head did not advance to the pushed commit.",
 };
 const WAIT_FOR_CHECKS_AFTER_FIX_RESULTS = {
     checksPassed: "The command exited with status zero: the pull request's checks passed after the fix, or the repository still reported no checks after a brief wait for them to register.",
     checksStillFailing: "The command exited with a nonzero status: the pull request's checks are still failing after the one fix attempt.",
 };
 const MERGE_PULL_REQUEST_RESULTS = {
-    merged: 'The command exited with status zero: the pull request is merged with a merge commit on the repository default branch, the remote and local branch are deleted, and the local default branch is checked out.',
-    mergeRefused: 'The command exited with a nonzero status: GitHub refused the merge, or the merge landed but the local switch to the default branch or the branch deletion failed.',
+    merged: 'The command exited with status zero: the pull request targeted the repository default branch and is merged into it with a merge commit, deletion of the remote and local branch was requested, and the local default branch is checked out.',
+    mergeRefused: 'The command exited with a nonzero status: the checkout no longer infers the published pull request, the pull request does not target the repository default branch, GitHub refused the merge, its merged state could not be confirmed, or the local switch to the default branch or the branch deletion failed.',
 };
 const UPDATE_LOCAL_DEFAULT_RESULTS = {
     localDefaultUpdated: 'The command exited with status zero: the local default branch is fast-forwarded to the merged head.',
@@ -76,13 +102,13 @@ const STATE_DESCRIPTIONS = {
     updateLocalDefault: 'Fast-forwarding the local default branch to the merged head.',
     awaitBossReply: 'Waiting for Boss to answer Coder.',
     failed: 'The pull-request delivery workflow failed and is waiting for new caller input.',
-    merged: 'The pull request is merged with a merge commit on the repository default branch, both branches are deleted, and the local default branch is fast-forwarded to the merged head.',
-    mergedLocalBehind: 'The pull request is merged with a merge commit on the repository default branch and both branches are deleted, but the local default branch could not be fast-forwarded to the merged head.',
+    merged: 'The pull request is merged with a merge commit on the repository default branch, which is checked out and fast-forwarded to the merged head; the merge requested deletion of the remote and local branch.',
+    mergedLocalBehind: 'The pull request is merged with a merge commit on the repository default branch, which is checked out but could not be fast-forwarded to the merged head; the merge requested deletion of the remote and local branch.',
     notPublished: 'The branch was not published or its pull request could not be opened; Coder reported the reason and no pull request is guaranteed to exist.',
     fixFailed: "The pull request's checks were red and the single CODE fix attempt returned an authored abort, failure, or insufficient terminal result; the pull request remains open.",
-    fixNotPublished: "The fix could not be published: the push was rejected or the pull request's head did not advance to the pushed commit; the pull request remains open.",
+    fixNotPublished: "The fix could not be published: the checked-out branch no longer carries the published pull request, the push was rejected, or the pull request's head did not advance to the pushed commit; the pull request remains open.",
     checksStillFailing: "The pull request's checks are still failing after the one fix attempt; the pull request remains open.",
-    mergeRefused: 'GitHub refused the merge, or the merge landed but the local switch to the default branch or the branch deletion failed; the pull request is in the state GitHub reports.',
+    mergeRefused: 'The merge did not complete: the checked-out branch no longer carries the published pull request, the pull request does not target the repository default branch, GitHub refused the merge, or the merge may have landed while its confirmation, the local switch to the default branch, or the branch deletion failed; the pull request is in the state GitHub reports.',
 };
 function playbookMeta(stateId, role) {
     return {
@@ -489,7 +515,7 @@ const machineSetup = setup({
             completion: 'checks-failed',
         }),
         completeMergeRefused: assign({
-            completion: 'merge-refused',
+            completion: 'merge-unconfirmed',
         }),
         completeMerged: assign({
             completion: 'merged',
@@ -543,9 +569,14 @@ export const prMachine = machineSetup.createMachine({
                 childResult: context.childFailure,
             };
         }
+        if (context.completion === 'merge-unconfirmed') {
+            return {
+                status: 'merge-unconfirmed',
+                ...pullRequestIdentity(context),
+            };
+        }
         if (context.completion === 'fix-not-published' ||
-            context.completion === 'checks-failed' ||
-            context.completion === 'merge-refused') {
+            context.completion === 'checks-failed') {
             return {
                 status: 'not-merged',
                 reason: context.completion,
@@ -703,10 +734,10 @@ export const prMachine = machineSetup.createMachine({
             tags: ['playbook.busy'],
             invoke: {
                 src: 'script',
-                input: () => ({
+                input: ({ context }) => ({
                     stateId: 'publishFix',
                     sourceItem: 'PR-4',
-                    command: PUBLISH_FIX_COMMAND,
+                    command: scriptCommand(PUBLISH_FIX_COMMAND, context),
                     result: PUBLISH_FIX_RESULTS,
                 }),
                 onDone: [
@@ -765,10 +796,10 @@ export const prMachine = machineSetup.createMachine({
             tags: ['playbook.busy'],
             invoke: {
                 src: 'script',
-                input: () => ({
+                input: ({ context }) => ({
                     stateId: 'mergePullRequest',
                     sourceItem: 'PR-6',
-                    command: MERGE_PULL_REQUEST_COMMAND,
+                    command: scriptCommand(MERGE_PULL_REQUEST_COMMAND, context),
                     result: MERGE_PULL_REQUEST_RESULTS,
                 }),
                 onDone: [

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

@@ -139,7 +139,17 @@ export type PrPlaybookOutput =
     }
   | {
       readonly status: 'not-merged';
-      readonly reason: 'fix-not-published' | 'checks-failed' | 'merge-refused';
+      readonly reason: 'fix-not-published' | 'checks-failed';
+      readonly pullRequest: string;
+      readonly pullRequestUrl: string;
+    }
+  /**
+   * The merge command exited nonzero. It ran, so whether GitHub merged the
+   * pull request is unknown — script output never enters context — and the
+   * result claims neither a merge nor its absence.
+   */
+  | {
+      readonly status: 'merge-unconfirmed';
       readonly pullRequest: string;
       readonly pullRequestUrl: string;
     };
@@ -150,7 +160,7 @@ export type PrCompletion =
   | 'fix-failed'
   | 'fix-not-published'
   | 'checks-failed'
-  | 'merge-refused';
+  | 'merge-unconfirmed';
 
 /** The machine reads no input: the caller input arrives on `START_PR`. */
 export type PrInput = Readonly<Record<never, never>>;
@@ -199,9 +209,36 @@ const OPEN_PULL_REQUEST_RESULTS = {
   needsBossReply: NEEDS_BOSS_REPLY_RESULT,
 } as const;
 
-// The mechanical steps are static POSIX shell text (slc/optimize.md): no
-// placeholder, no runtime value, and no prose — `gh` infers the pull request
-// from the checked-out branch.
+// The mechanical steps are static POSIX shell text (slc/optimize.md) with no
+// prose. `gh` infers the pull request from the checked-out branch, which the
+// run does not own, so the two steps that act on the pull request itself relay
+// one runtime value — the pull request PR-1 published — through the same
+// placeholder relay an acting prompt uses.
+// The placeholder occupies a single-quoted shell word, and binding replaces
+// that whole word — quotes included — with the value's own quoted literal.
+const QUOTED_PULL_REQUEST_URL = "'<pull-request-url>'";
+
+// A retained value is reported text, so it reaches the shell as one
+// single-quoted literal word: no command substitution, no expansion, no word
+// splitting. A single quote inside the value closes the literal, escapes
+// itself, and reopens it — the only character single quotes cannot hold.
+function shellLiteral(value: string): string {
+  return `'${value.split("'").join("'\\''")}'`;
+}
+
+// Bind the retained identity into a script command. Without it the quoted
+// placeholder stays, and no `gh` output equals it, so the step refuses instead
+// of acting on whatever the checkout now infers. Every script state is
+// reachable only after `rememberPullRequest`, so the refusal is unreachable by
+// construction and exists to keep the failure closed if that ever changes.
+function scriptCommand(command: string, context: PrContext): string {
+  const url = context.pullRequestUrl;
+  if (!isNonEmptyString(url)) return command;
+  // A function replacement keeps `$`-patterns in the value from being read as
+  // replacement syntax.
+  return command.replaceAll(QUOTED_PULL_REQUEST_URL, () => shellLiteral(url));
+}
+
 const WAIT_FOR_CHECKS_COMMAND = [
   'n=0',
   "while gh pr checks 2>&1 | grep -q 'no checks reported'; do",
@@ -213,6 +250,7 @@ const WAIT_FOR_CHECKS_COMMAND = [
 ].join('\n');
 
 const PUBLISH_FIX_COMMAND = [
+  '[ "$(gh pr view --json url --jq .url)" = \'<pull-request-url>\' ] || exit 1',
   'git push || exit 1',
   'n=0',
   'until [ "$(gh pr view --json headRefOid --jq .headRefOid 2>/dev/null)" = "$(git rev-parse HEAD)" ]; do',
@@ -223,7 +261,7 @@ const PUBLISH_FIX_COMMAND = [
 ].join('\n');
 
 const MERGE_PULL_REQUEST_COMMAND =
-  'gh pr merge --merge --delete-branch --match-head-commit "$(git rev-parse HEAD)"';
+  "pr=$(gh pr view --json url --jq .url) || exit 1\n[ \"$pr\" = '<pull-request-url>' ] || exit 1\nbase=$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name) || exit 1\n[ -n \"$base\" ] || exit 1\n[ \"$(gh pr view \"$pr\" --json baseRefName --jq .baseRefName)\" = \"$base\" ] || exit 1\ngh pr merge --merge --delete-branch --match-head-commit \"$(git rev-parse HEAD)\" || exit 1\n[ \"$(gh pr view \"$pr\" --json state --jq .state)\" = MERGED ] || exit 1\n[ \"$(git branch --show-current)\" = \"$base\" ]";
 
 const UPDATE_LOCAL_DEFAULT_COMMAND = 'git pull --ff-only';
 
@@ -238,7 +276,7 @@ const PUBLISH_FIX_RESULTS = {
   fixPublished:
     "The command exited with status zero: the fix is pushed and the pull request's head is the pushed commit.",
   fixNotPublished:
-    "The command exited with a nonzero status: the push was rejected or the pull request's head did not advance to the pushed commit.",
+    "The command exited with a nonzero status: the checkout no longer infers the published pull request, the push was rejected, or the pull request's head did not advance to the pushed commit.",
 } as const;
 
 const WAIT_FOR_CHECKS_AFTER_FIX_RESULTS = {
@@ -250,9 +288,9 @@ const WAIT_FOR_CHECKS_AFTER_FIX_RESULTS = {
 
 const MERGE_PULL_REQUEST_RESULTS = {
   merged:
-    'The command exited with status zero: the pull request is merged with a merge commit on the repository default branch, the remote and local branch are deleted, and the local default branch is checked out.',
+    'The command exited with status zero: the pull request targeted the repository default branch and is merged into it with a merge commit, deletion of the remote and local branch was requested, and the local default branch is checked out.',
   mergeRefused:
-    'The command exited with a nonzero status: GitHub refused the merge, or the merge landed but the local switch to the default branch or the branch deletion failed.',
+    'The command exited with a nonzero status: the checkout no longer infers the published pull request, the pull request does not target the repository default branch, GitHub refused the merge, its merged state could not be confirmed, or the local switch to the default branch or the branch deletion failed.',
 } as const;
 
 const UPDATE_LOCAL_DEFAULT_RESULTS = {
@@ -286,19 +324,19 @@ const STATE_DESCRIPTIONS = {
   failed:
     'The pull-request delivery workflow failed and is waiting for new caller input.',
   merged:
-    'The pull request is merged with a merge commit on the repository default branch, both branches are deleted, and the local default branch is fast-forwarded to the merged head.',
+    'The pull request is merged with a merge commit on the repository default branch, which is checked out and fast-forwarded to the merged head; the merge requested deletion of the remote and local branch.',
   mergedLocalBehind:
-    'The pull request is merged with a merge commit on the repository default branch and both branches are deleted, but the local default branch could not be fast-forwarded to the merged head.',
+    'The pull request is merged with a merge commit on the repository default branch, which is checked out but could not be fast-forwarded to the merged head; the merge requested deletion of the remote and local branch.',
   notPublished:
     'The branch was not published or its pull request could not be opened; Coder reported the reason and no pull request is guaranteed to exist.',
   fixFailed:
     "The pull request's checks were red and the single CODE fix attempt returned an authored abort, failure, or insufficient terminal result; the pull request remains open.",
   fixNotPublished:
-    "The fix could not be published: the push was rejected or the pull request's head did not advance to the pushed commit; the pull request remains open.",
+    "The fix could not be published: the checked-out branch no longer carries the published pull request, the push was rejected, or the pull request's head did not advance to the pushed commit; the pull request remains open.",
   checksStillFailing:
     "The pull request's checks are still failing after the one fix attempt; the pull request remains open.",
   mergeRefused:
-    'GitHub refused the merge, or the merge landed but the local switch to the default branch or the branch deletion failed; the pull request is in the state GitHub reports.',
+    'The merge did not complete: the checked-out branch no longer carries the published pull request, the pull request does not target the repository default branch, GitHub refused the merge, or the merge may have landed while its confirmation, the local switch to the default branch, or the branch deletion failed; the pull request is in the state GitHub reports.',
 } as const;
 
 function playbookMeta<StateId extends keyof typeof STATE_DESCRIPTIONS>(
@@ -829,7 +867,7 @@ const machineSetup = setup({
       completion: 'checks-failed' as const,
     }),
     completeMergeRefused: assign({
-      completion: 'merge-refused' as const,
+      completion: 'merge-unconfirmed' as const,
     }),
     completeMerged: assign({
       completion: 'merged' as const,
@@ -889,10 +927,15 @@ export const prMachine = machineSetup.createMachine({
         childResult: context.childFailure,
       };
     }
+    if (context.completion === 'merge-unconfirmed') {
+      return {
+        status: 'merge-unconfirmed',
+        ...pullRequestIdentity(context),
+      };
+    }
     if (
       context.completion === 'fix-not-published' ||
-      context.completion === 'checks-failed' ||
-      context.completion === 'merge-refused'
+      context.completion === 'checks-failed'
     ) {
       return {
         status: 'not-merged',
@@ -1051,10 +1094,10 @@ export const prMachine = machineSetup.createMachine({
       tags: ['playbook.busy'],
       invoke: {
         src: 'script',
-        input: (): ScriptInput => ({
+        input: ({ context }): ScriptInput => ({
           stateId: 'publishFix',
           sourceItem: 'PR-4',
-          command: PUBLISH_FIX_COMMAND,
+          command: scriptCommand(PUBLISH_FIX_COMMAND, context),
           result: PUBLISH_FIX_RESULTS,
         }),
         onDone: [
@@ -1113,10 +1156,10 @@ export const prMachine = machineSetup.createMachine({
       tags: ['playbook.busy'],
       invoke: {
         src: 'script',
-        input: (): ScriptInput => ({
+        input: ({ context }): ScriptInput => ({
           stateId: 'mergePullRequest',
           sourceItem: 'PR-6',
-          command: MERGE_PULL_REQUEST_COMMAND,
+          command: scriptCommand(MERGE_PULL_REQUEST_COMMAND, context),
           result: MERGE_PULL_REQUEST_RESULTS,
         }),
         onDone: [

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

@@ -11,7 +11,9 @@ The caller supplies the original request including the issue it names, if any; t
 `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.
+`gh` infers the pull request from the checked-out branch, which the run does not own: the nested `code` call suspends across Boss turns, so the checkout can change before the fix is published or the merge runs.
+The two steps that act on the pull request itself therefore carry one runtime value — the pull request `pr` published — and refuse unless the checkout still infers exactly it.
+That identity is reported text, so it binds as a single-quoted shell literal: the command compares it as data and never executes it as shell syntax.
 
 ## Coder
 
@@ -80,6 +82,7 @@ Workflow outcomes:
 
 When `code` succeeds, Captain shall run:
 
+> [ "$(gh pr view --json url --jq .url)" = '<pull-request-url>' ] || exit 1
 > git push || exit 1
 > n=0
 > until [ "$(gh pr view --json headRefOid --jq .headRefOid 2>/dev/null)" = "$(git rev-parse HEAD)" ]; do
@@ -90,10 +93,11 @@ When `code` succeeds, Captain shall run:
 
 Results:
 - `fixPublished`: The command exited with status zero: the fix is pushed and the pull request's head is the pushed commit.
-- `fixNotPublished`: The command exited with a nonzero status: the push was rejected or the pull request's head did not advance to the pushed commit.
+- `fixNotPublished`: The command exited with a nonzero status: the checkout no longer infers the published pull request, the push was rejected, or the pull request's head did not advance to the pushed commit.
 
 Workflow outcomes:
 - 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.
+- The command pushes nothing until the checked-out branch infers the pull request `pr` published, so a checkout that changed while `code` ran publishes to no other branch.
 - Fix not published is an authored failure that leaves the pull request open.
 
 ### PR-5
@@ -120,16 +124,25 @@ Workflow outcomes:
 
 When the checks pass, before or after the one fix attempt, Captain shall run:
 
-> gh pr merge --merge --delete-branch --match-head-commit "$(git rev-parse HEAD)"
+> pr=$(gh pr view --json url --jq .url) || exit 1
+> [ "$pr" = '<pull-request-url>' ] || exit 1
+> base=$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name) || exit 1
+> [ -n "$base" ] || exit 1
+> [ "$(gh pr view "$pr" --json baseRefName --jq .baseRefName)" = "$base" ] || exit 1
+> gh pr merge --merge --delete-branch --match-head-commit "$(git rev-parse HEAD)" || exit 1
+> [ "$(gh pr view "$pr" --json state --jq .state)" = MERGED ] || exit 1
+> [ "$(git branch --show-current)" = "$base" ]
 
 Results:
-- `merged`: The command exited with status zero: the pull request is merged with a merge commit on the repository default branch, the remote and local branch are deleted, and the local default branch is checked out.
-- `mergeRefused`: The command exited with a nonzero status: GitHub refused the merge, or the merge landed but the local switch to the default branch or the branch deletion failed.
+- `merged`: The command exited with status zero: the pull request targeted the repository default branch and is merged into it with a merge commit, deletion of the remote and local branch was requested, and the local default branch is checked out.
+- `mergeRefused`: The command exited with a nonzero status: the checkout no longer infers the published pull request, the pull request does not target the repository default branch, GitHub refused the merge, its merged state could not be confirmed, or the local switch to the default branch or the branch deletion failed.
 
 Workflow outcomes:
-- 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 creates a merge commit on the repository default branch, requests deletion of 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.
+- The command requires the inferred pull request to be the one `pr` published and to target the repository default branch before the irreversible merge, and confirms that same pull request's merged state and the default-branch checkout after the merge command succeeds; a queued pull request is not a merged result.
+- Merge refused is an authored failure that leaves the pull request in the state GitHub reports: the checkout no longer infers the published pull request, the pull request targets another branch, GitHub refused the merge for a conflict, a branch protection, a forbidden merge method, or a head that moved, or the merge may have landed while its confirmation, the local switch to the default branch, or the branch deletion failed.
+- A refused merge does not establish that the pull request is unmerged, so `pr` reports it as an unconfirmed merge rather than as not merged, and no outcome claims a branch was deleted, because `gh` skips the remote deletion for a pull request from another repository or one already merged and exits zero anyway.
 
 ### PR-7
 

package/reference/sdlc/pr.playbook/pr.playbook.js

@@ -21,7 +21,8 @@ const VERBATIM_PAYLOAD_FIELDS = new Set([
     'coderOutput',
 ]);
 // Every failure terminal leaves the delivery unfinished: no pull request is
-// guaranteed to exist after notPublished, and the other four leave it open.
+// guaranteed to exist after notPublished, the three fix terminals leave it
+// open, and mergeRefused leaves it in the state GitHub reports.
 const UNFINISHED_FINAL_STATE_IDS = new Set([
     'notPublished',
     'fixFailed',

package/reference/sdlc/pr.playbook/pr.playbook.ts

@@ -100,7 +100,8 @@ const VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string> = new Set([
   'coderOutput',
 ]);
 // Every failure terminal leaves the delivery unfinished: no pull request is
-// guaranteed to exist after notPublished, and the other four leave it open.
+// guaranteed to exist after notPublished, the three fix terminals leave it
+// open, and mergeRefused leaves it in the state GitHub reports.
 const UNFINISHED_FINAL_STATE_IDS: ReadonlySet<string> = new Set([
   'notPublished',
   'fixFailed',

package/slc/experiments/fsm-scaffold-guidance.md

@@ -0,0 +1,31 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
+
+## Optional FSM authoring initializer (unmeasured experiment)
+
+For an LF English GEARS artifact with ordinary Captain/player items and static nested calls, you may initialize a **new** target with the adjacent [scaffold-fsm.mjs](../scaffold-fsm.mjs):
+
+```sh
+node <definition-directory>/scaffold-fsm.mjs --source <source> --out <target.fsm.ts>
+```
+
+Resolve the helper from the actual definition directory supplied with the phase invocation.
+The target must resolve XState with `setup.extend` and `createStateConfig`; otherwise initialization refuses.
+It copies exact prompt/result constants and emits an **incomplete** XState setup scaffold.
+Script, dynamic-call, parallel, malformed or ambiguous layouts refuse without modifying Source or replacing the target; continue ordinary authoring on refusal.
+The output intentionally contains unresolved `__AUTHOR_*` markers, so successful initialization is not successful compilation.
+
+Read the full Source and this phase's normative rules, then complete the target directly:
+
+- Keep acting `GEARS_ITEMS[id].prompt` literal and carry every Source-owned runtime value in typed `invoke.input` fields beside it. Nested constants are templates; compose child text as the nested-call contract requires.
+- Exact `GEARS_ITEMS[id].result` values contain only authored outcomes. Apply the existing phase's single-outcome, universal question and controller rules where appropriate. Derive required payloads from Source and actual public child interfaces.
+- Replace all type/code markers with the real context, events, inputs, outputs, field relays, assignments, routing, guards, public state metadata, continuation and failure behavior. Rename or remove the example assignment as appropriate.
+- Register reusable assignments with `actorSetup.extend({ actions: { name: assign(...) } })` and reference their registered names. Narrow heterogeneous actor output from `unknown`; do not erase actor/event types with casts to reuse a standalone assignment on `onDone`.
+- For a nested call, the scaffold also exports `authoredChildResult(error, expectedPlaybookId)`. It delegates public-envelope validation to the installed stateless validator. Use the actual selected target id, not a fabricated request or child-session id; Source still owns recovery routes, output predicates and compact evidence. Remove the helper if unused.
+- Shared configuration fragments may use `machineSetup.createStateConfig(...)` to preserve their literal transition types.
+
+Emit one self-contained `.fsm.ts`, with no imports from the initializer or auxiliary semantic files.
+Its only generated imports are XState and, for a child actor, the selected Playbook public validator and public type; those stateless imports bind no runner or actor implementation.
+All ordinary strict, Source, GEARS/FSM and later runtime checks remain authoritative.
+No workflow route, child acceptance predicate or default context value is supplied by this helper.
+This technique has no accepted performance result yet.