@sublang/playbook 13.3.0 → 14.1.0

package/reference/sdlc/code.playbook/session-host.d.ts

@@ -72,7 +72,9 @@ export interface SessionHostController {
   /**
    * The active leaf's currently advertised runtime actions, read live between
    * turns; empty whenever nothing is advertised, a turn is active, or the
-   * leaf's control view cannot be read.
+   * leaf's control view cannot be read. Each pair carries the leaf's own
+   * `standing` and its `reason`, so a host never draws a control without
+   * saying what running it would do (DR-063).
    */
   listRuntimeActions(): readonly PlaybookControlAction[];
   /**
@@ -83,8 +85,9 @@ export interface SessionHostController {
   submitRuntimeAction(actionId: string): Promise<SessionRecovery>;
   /**
    * The controls the shell offers on its own behalf, read live between turns;
-   * today one give-up while a root is engaged, and empty while idle or while a
-   * turn is active. Disjoint from `listRuntimeActions`, which reads the leaf.
+   * today one `ready` give-up while a root is engaged, and empty while idle or
+   * while a turn is active. Disjoint from `listRuntimeActions`, which reads the
+   * leaf.
    */
   listShellActions(): readonly PlaybookControlAction[];
   /**

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

@@ -214,7 +214,7 @@ export declare const decideMachine: import("xstate").StateMachine<DecideContext,
 } | {
     type: "validReviewSuccess";
     params: unknown;
-}, never, "done" | "failed" | "awaitBossReply" | "ready" | "reportedReviewFailure" | "commitCoderProposal" | "reviewCommit" | {
+}, never, "done" | "failed" | "ready" | "awaitBossReply" | "reportedReviewFailure" | "commitCoderProposal" | "reviewCommit" | {
     independentProposals: {
         coder: "complete" | "working" | "waiting";
         reviewer: "complete" | "working" | "waiting";

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

@@ -2481,20 +2481,42 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
         }
         return 'restored';
     };
+    /**
+     * DR-063 §3: reconciliation re-reads the host's ledger, which the control
+     * view has just done. With no eligible checkpoint restoration and a complete
+     * receipt on every unresolved boundary, re-reading resolves nothing.
+     */
+    const reconciliationStanding = (restorationEligible) => {
+        if (restorationEligible)
+            return { standing: 'ready' };
+        const envelopes = unresolvedEffectEnvelopeIdentities();
+        if (envelopes.length === 0)
+            return { standing: 'ready' };
+        const boundaryIds = envelopes.flatMap((envelope) => envelope.kind === 'boundary'
+            ? [envelope.boundaryId]
+            : (effectLedgerMirror.logicalOperations.find(({ operationId }) => operationId === envelope.operationId)?.boundaryIds ?? []));
+        if (boundaryIds.length === 0)
+            return { standing: 'ready' };
+        return boundaryIds.every((boundaryId) => effectLedgerMirror.boundaries.find((candidate) => candidate.boundaryId === boundaryId)?.physicalReceipt !== undefined)
+            ? { standing: 'no-op', reason: 'receipt-complete' }
+            : { standing: 'ready' };
+    };
     const unresolvedControlCandidates = () => {
         if (!hasUnresolvedReconciliation())
             return [];
         const operation = hiddenDeferredOperationId === undefined
             ? undefined
             : effectLedgerMirror.logicalOperations.find(({ operationId }) => operationId === hiddenDeferredOperationId);
+        const restorationEligible = operation?.checkpointRestorationEligible === true;
         return [
             {
                 action: {
                     id: UNRESOLVED_EFFECT_RECONCILIATION_ACTION_ID,
                     label: 'Retry unresolved effect reconciliation',
+                    ...reconciliationStanding(restorationEligible),
                 },
                 kind: 'reconcile',
-                ...(operation?.checkpointRestorationEligible === true
+                ...(restorationEligible
                     ? { deferredRestoreOperationId: operation.operationId }
                     : {}),
             },
@@ -2502,6 +2524,8 @@ function createDecidePlaybookRuntime(options, deferredEffects) {
                 action: {
                     id: UNRESOLVED_EFFECT_ABANDONMENT_ACTION_ID,
                     label: 'Abandon unresolved workflow attempt',
+                    // DR-063 §3: abandonment always changes the session's standing.
+                    standing: 'ready',
                 },
                 kind: 'abandon',
             },

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

@@ -3850,6 +3850,35 @@ function createDecidePlaybookRuntime(
   };
   type UnresolvedControlCandidates = readonly UnresolvedControlCandidate[];
 
+  /**
+   * DR-063 §3: reconciliation re-reads the host's ledger, which the control
+   * view has just done. With no eligible checkpoint restoration and a complete
+   * receipt on every unresolved boundary, re-reading resolves nothing.
+   */
+  const reconciliationStanding = (
+    restorationEligible: boolean,
+  ): Pick<PlaybookControlAction, 'standing' | 'reason'> => {
+    if (restorationEligible) return { standing: 'ready' };
+    const envelopes = unresolvedEffectEnvelopeIdentities();
+    if (envelopes.length === 0) return { standing: 'ready' };
+    const boundaryIds = envelopes.flatMap((envelope) =>
+      envelope.kind === 'boundary'
+        ? [envelope.boundaryId]
+        : (effectLedgerMirror.logicalOperations.find(
+            ({ operationId }) => operationId === envelope.operationId,
+          )?.boundaryIds ?? []),
+    );
+    if (boundaryIds.length === 0) return { standing: 'ready' };
+    return boundaryIds.every(
+      (boundaryId) =>
+        effectLedgerMirror.boundaries.find(
+          (candidate) => candidate.boundaryId === boundaryId,
+        )?.physicalReceipt !== undefined,
+    )
+      ? { standing: 'no-op', reason: 'receipt-complete' }
+      : { standing: 'ready' };
+  };
+
   const unresolvedControlCandidates = (): UnresolvedControlCandidates => {
     if (!hasUnresolvedReconciliation()) return [];
     const operation =
@@ -3859,21 +3888,25 @@ function createDecidePlaybookRuntime(
             ({ operationId }) =>
               operationId === hiddenDeferredOperationId,
           );
+    const restorationEligible = operation?.checkpointRestorationEligible === true;
     return [
       {
         action: {
           id: UNRESOLVED_EFFECT_RECONCILIATION_ACTION_ID,
           label: 'Retry unresolved effect reconciliation',
+          ...reconciliationStanding(restorationEligible),
         },
         kind: 'reconcile',
-        ...(operation?.checkpointRestorationEligible === true
-          ? { deferredRestoreOperationId: operation.operationId }
+        ...(restorationEligible
+          ? { deferredRestoreOperationId: operation!.operationId }
           : {}),
       },
       {
         action: {
           id: UNRESOLVED_EFFECT_ABANDONMENT_ACTION_ID,
           label: 'Abandon unresolved workflow attempt',
+          // DR-063 §3: abandonment always changes the session's standing.
+          standing: 'ready',
         },
         kind: 'abandon',
       },

package/reference/sdlc/dev.md

@@ -12,6 +12,7 @@ The caller supplies a development request including any desired outcome, scope,
 
 `dev` is an optional repository-aware planner for a development request that needs more analysis before choosing a development path.
 It coordinates existing playbooks and owns no repository commit itself.
+Analyst chooses the path and states why in a short planning note; analysis, design, and implementation belong to the playbooks `dev` calls, and a question to Boss serves only the choice of path.
 
 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:
 
@@ -20,17 +21,23 @@ At the start of `dev` and after each Boss reply, Captain shall relay the develop
 > Run results: <run-results>
 
 ```markdown
-Inspect the request and the relevant repository and specs only as needed to determine the smallest sound next step.
+Plan which playbooks run for this request; the playbooks do the work.
+Read the request, then the specs and the repository only as far as choosing the path requires.
 Do not change files or commit while planning or discussing the request.
 
-- If useful analysis or clarification should be discussed before any repository work, give Boss the useful response and ask one material question that advances the decision.
-- 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`.
+Choose exactly one:
 
+- `code`: the existing decisions and spec items settle how the work is done.
+- `decide then code`: the work turns on a rule, concept, term, shape, or trade-off the specs leave open or contradict; name what is open, do not settle it.
+- `code via pull request` or `decide then code via pull request`, in place of the two above, when the request names a GitHub issue (number or URL) or explicitly asks for pull-request delivery; read the issue and its comments (`gh issue view --comments` with the issue number) while choosing.
+- A question to Boss, only when the answer would change which path runs or whether any work is wanted: one short question naming the alternatives it decides between, and nothing else. When every answer leads to the same path, choose it; the playbook settles the open point.
+- `discussion complete`, after a Boss reply, when no repository work should follow.
+
+Your reply is the planning note the chosen playbook receives. It holds only the path and, in at most ten lines, why — the decisions and spec items that settle the work, or the open point a decision must settle — plus the scope the request implies and any fact from the issue the playbooks need.
+It holds no design, proposal, implementation instruction, or file-level finding: the playbooks own those.
+A reply that chooses a path asks Boss nothing; a reply that asks Boss chooses no path.
 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.
+Do not choose `decide then code` merely because the work is large, nor `code` merely because it is small.
 Consult @specs/map.md for relevant context and @specs/meta.md for spec requirements, if needed.
 ```
 
@@ -42,7 +49,7 @@ No outcome depends on a fixed presentation format of Analyst's reply.
 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 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.
+Discussion complete is available only after a Boss reply, when that reply settles that no repository work should follow.
 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 (`>`).

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

@@ -296,7 +296,7 @@ export declare const devMachine: import("xstate").StateMachine<DevContext, {
 } | {
     type: "resumesPlanAnalysis";
     params: unknown;
-}, never, "done" | "failed" | "awaitBossReply" | "ready" | "planAnalysis" | "createBranch" | "callCode" | "callDecide" | "callCodeAfterDecide" | "openPullRequest" | "discussionComplete" | "reportedChildFailure", string, DevInput, {
+}, never, "done" | "failed" | "ready" | "awaitBossReply" | "planAnalysis" | "createBranch" | "callCode" | "callDecide" | "callCodeAfterDecide" | "openPullRequest" | "discussionComplete" | "reportedChildFailure", string, DevInput, {
     readonly status: "discussion-complete";
 } | {
     readonly status: "complete";

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

@@ -8,30 +8,36 @@ const PLAN_ANALYSIS_PROMPT = [
     '> 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.',
+    'Plan which playbooks run for this request; the playbooks do the work.',
+    'Read the request, then the specs and the repository only as far as choosing the path requires.',
     'Do not change files or commit while planning or discussing the request.',
     '',
-    '- If useful analysis or clarification should be discussed before any repository work, give Boss the useful response and ask one material question that advances the decision.',
-    '- 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`.',
+    'Choose exactly one:',
     '',
+    '- `code`: the existing decisions and spec items settle how the work is done.',
+    '- `decide then code`: the work turns on a rule, concept, term, shape, or trade-off the specs leave open or contradict; name what is open, do not settle it.',
+    '- `code via pull request` or `decide then code via pull request`, in place of the two above, when the request names a GitHub issue (number or URL) or explicitly asks for pull-request delivery; read the issue and its comments (`gh issue view --comments` with the issue number) while choosing.',
+    '- A question to Boss, only when the answer would change which path runs or whether any work is wanted: one short question naming the alternatives it decides between, and nothing else. When every answer leads to the same path, choose it; the playbook settles the open point.',
+    '- `discussion complete`, after a Boss reply, when no repository work should follow.',
+    '',
+    'Your reply is the planning note the chosen playbook receives. It holds only the path and, in at most ten lines, why — the decisions and spec items that settle the work, or the open point a decision must settle — plus the scope the request implies and any fact from the issue the playbooks need.',
+    'It holds no design, proposal, implementation instruction, or file-level finding: the playbooks own those.',
+    'A reply that chooses a path asks Boss nothing; a reply that asks Boss chooses no path.',
     '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.',
+    'Do not choose `decide then code` merely because the work is large, nor `code` merely because it is small.',
     'Consult @specs/map.md for relevant context and @specs/meta.md for spec requirements, if needed.',
 ].join('\n');
 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>`.',
+    code: 'Analyst chose `code`: the existing decisions and spec items settle how the work is done. Output shall include `planningResult: <verbatim final text>`.',
+    decideThenCode: 'Analyst chose `decide then code`: the work turns on a point the specs leave open or contradict. Output shall include `planningResult: <verbatim final text>`.',
+    codeViaPullRequest: 'Analyst chose `code via pull request`: the existing decisions settle the work, and the request names a GitHub issue or explicitly asks for pull-request delivery. Output shall include `planningResult: <verbatim final text>`.',
+    decideThenCodeViaPullRequest: 'Analyst chose `decide then code via pull request`: the work turns on a point the specs leave open or contradict, 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.',
+    planAnalysis: 'Analyst is choosing the development path.',
     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.',

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

@@ -198,17 +198,23 @@ const PLAN_ANALYSIS_PROMPT = [
   '> 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.',
+  'Plan which playbooks run for this request; the playbooks do the work.',
+  'Read the request, then the specs and the repository only as far as choosing the path requires.',
   'Do not change files or commit while planning or discussing the request.',
   '',
-  '- If useful analysis or clarification should be discussed before any repository work, give Boss the useful response and ask one material question that advances the decision.',
-  '- 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`.',
+  'Choose exactly one:',
   '',
+  '- `code`: the existing decisions and spec items settle how the work is done.',
+  '- `decide then code`: the work turns on a rule, concept, term, shape, or trade-off the specs leave open or contradict; name what is open, do not settle it.',
+  '- `code via pull request` or `decide then code via pull request`, in place of the two above, when the request names a GitHub issue (number or URL) or explicitly asks for pull-request delivery; read the issue and its comments (`gh issue view --comments` with the issue number) while choosing.',
+  '- A question to Boss, only when the answer would change which path runs or whether any work is wanted: one short question naming the alternatives it decides between, and nothing else. When every answer leads to the same path, choose it; the playbook settles the open point.',
+  '- `discussion complete`, after a Boss reply, when no repository work should follow.',
+  '',
+  'Your reply is the planning note the chosen playbook receives. It holds only the path and, in at most ten lines, why — the decisions and spec items that settle the work, or the open point a decision must settle — plus the scope the request implies and any fact from the issue the playbooks need.',
+  'It holds no design, proposal, implementation instruction, or file-level finding: the playbooks own those.',
+  'A reply that chooses a path asks Boss nothing; a reply that asks Boss chooses no path.',
   '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.',
+  'Do not choose `decide then code` merely because the work is large, nor `code` merely because it is small.',
   'Consult @specs/map.md for relevant context and @specs/meta.md for spec requirements, if needed.',
 ].join('\n');
 
@@ -216,21 +222,20 @@ 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>`.',
+    'Analyst chose `code`: the existing decisions and spec items settle how the work is done. 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>`.',
+    'Analyst chose `decide then code`: the work turns on a point the specs leave open or contradict. 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>`.',
+    'Analyst chose `code via pull request`: the existing decisions settle the work, 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>`.',
+    'Analyst chose `decide then code via pull request`: the work turns on a point the specs leave open or contradict, 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>`.",
 } as const;
 
 const STATE_DESCRIPTIONS = {
   ready: 'Waiting for a development request.',
-  planAnalysis:
-    'Analyst is analyzing the development request to choose the smallest sound next step.',
+  planAnalysis: 'Analyst is choosing the development path.',
   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.',

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

@@ -9,6 +9,7 @@ Roles:
 
 `dev` is an optional repository-aware planner for a development request that needs more analysis before choosing a development path.
 It coordinates existing playbooks and owns no repository commit itself.
+Analyst chooses the path and states why in a short planning note; analysis, design, and implementation belong to the playbooks `dev` calls, and a question to Boss serves only the choice of path.
 
 ## Analyst
 
@@ -20,31 +21,37 @@ At the start of `dev` and after each Boss reply, Captain shall relay the develop
 > > 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.
+> Plan which playbooks run for this request; the playbooks do the work.
+> Read the request, then the specs and the repository only as far as choosing the path requires.
 > Do not change files or commit while planning or discussing the request.
 >
-> - If useful analysis or clarification should be discussed before any repository work, give Boss the useful response and ask one material question that advances the decision.
-> - 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`.
+> Choose exactly one:
 >
+> - `code`: the existing decisions and spec items settle how the work is done.
+> - `decide then code`: the work turns on a rule, concept, term, shape, or trade-off the specs leave open or contradict; name what is open, do not settle it.
+> - `code via pull request` or `decide then code via pull request`, in place of the two above, when the request names a GitHub issue (number or URL) or explicitly asks for pull-request delivery; read the issue and its comments (`gh issue view --comments` with the issue number) while choosing.
+> - A question to Boss, only when the answer would change which path runs or whether any work is wanted: one short question naming the alternatives it decides between, and nothing else. When every answer leads to the same path, choose it; the playbook settles the open point.
+> - `discussion complete`, after a Boss reply, when no repository work should follow.
+>
+> Your reply is the planning note the chosen playbook receives. It holds only the path and, in at most ten lines, why — the decisions and spec items that settle the work, or the open point a decision must settle — plus the scope the request implies and any fact from the issue the playbooks need.
+> It holds no design, proposal, implementation instruction, or file-level finding: the playbooks own those.
+> A reply that chooses a path asks Boss nothing; a reply that asks Boss chooses no path.
 > 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.
+> Do not choose `decide then code` merely because the work is large, nor `code` merely because it is small.
 > Consult @specs/map.md for relevant context and @specs/meta.md for spec requirements, if needed.
 
 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>`.
+- `code`: Analyst chose `code`: the existing decisions and spec items settle how the work is done. Output shall include `planningResult: <verbatim final text>`.
+- `decideThenCode`: Analyst chose `decide then code`: the work turns on a point the specs leave open or contradict. Output shall include `planningResult: <verbatim final text>`.
+- `codeViaPullRequest`: Analyst chose `code via pull request`: the existing decisions settle the work, and the request names a GitHub issue or explicitly asks for pull-request delivery. Output shall include `planningResult: <verbatim final text>`.
+- `decideThenCodeViaPullRequest`: Analyst chose `decide then code via pull request`: the work turns on a point the specs leave open or contradict, 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 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 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.
+- Discussion complete is available only after a Boss reply, when that reply settles that no repository work should follow; 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.
 
 ## Nested development paths

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

@@ -1,19 +1,12 @@
-import { type XStatePlaybookRuntimeFactory, type XStatePlaybookRuntimeConstruction } from '@sublang/playbook/xstate-runtime';
-import { type DevInput, type PlayerInput } from './dev.fsm.js';
+import { type PlaybookPlayerInput, type XStatePlaybookRuntimeFactory, type XStatePlaybookRuntimeConstruction } from '@sublang/playbook/xstate-runtime';
+import { type DevInput } from './dev.fsm.js';
 import type { PlaybookHostConstructionCapabilities } from '../code.playbook/playbook-captain.js';
 import type { CaptainCallOptions, CaptainResult, JsonValue, NormalizedError, PlayerCallOptions, PlaybookCallRequest, PlaybookCallResult, PlaybookCallStart, PlaybookControlReceipt, PlaybookControlView, PlaybookPendingCall, PlaybookPorts, PlaybookRunResult, PlaybookRuntime, PlaybookRuntimeFactory, PlaybookRuntimeSnapshot, PlaybookSession, PlaybookState, PlaybookStateValue, PlaybookTraceEvent, PlaybookTraceType, PlayerResult, PlayerSessionStore } from '@sublang/playbook/runtime';
 export type { CaptainCallOptions, CaptainResult, JsonValue, NormalizedError, PlayerCallOptions, PlaybookCallRequest, PlaybookCallResult, PlaybookCallStart, PlaybookControlReceipt, PlaybookControlView, PlaybookPendingCall, PlaybookPorts, PlaybookRunResult, PlaybookRuntime, PlaybookRuntimeFactory, PlaybookRuntimeSnapshot, PlaybookSession, PlaybookState, PlaybookStateValue, PlaybookTraceEvent, PlaybookTraceType, PlayerResult, PlayerSessionStore, };
 export type DevPlaybookOptions = DevInput;
 export type DevPlaybookHostCapabilities = PlaybookHostConstructionCapabilities & XStatePlaybookRuntimeConstruction<DevPlaybookOptions, object>['hostCapabilities'];
-/**
- * Preserve authored Markdown quote markers around every line of relayed
- * runtime text. The generic composer preserves the marker itself; DEV's
- * override additionally keeps a multiline value inside that quote and drops
- * the optional relays that have no value yet.
- */
-declare function composePlayerPrompt(input: PlayerInput, resuming?: boolean): string;
 export declare const _internal: {
-    composePlayerPrompt: typeof composePlayerPrompt;
+    composePlayerPrompt: (input: PlaybookPlayerInput, _identity: import("@sublang/playbook/xstate-runtime").XStatePromptIdentity, resuming?: boolean) => string;
     VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string>;
     UNFINISHED_FINAL_STATE_IDS: ReadonlySet<string>;
 };

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

@@ -73,11 +73,6 @@ function composePlayerPrompt(input, resuming = false) {
     });
     return composePlayerContinuation(input, body, resuming);
 }
-export const _internal = {
-    composePlayerPrompt,
-    VERBATIM_PAYLOAD_FIELDS,
-    UNFINISHED_FINAL_STATE_IDS,
-};
 const runtimeSpec = {
     label: 'DEV',
     // DR-022 / slc/link.md: the declaration carries the value current at link
@@ -97,7 +92,7 @@ const runtimeSpec = {
     roleStates: {
         planAnalysis: {
             role: 'analyst',
-            label: 'Analyst is analyzing the development request to choose the smallest sound next step.',
+            label: 'Analyst is choosing the development path.',
         },
     },
     // DR-044: DEV owns no repository commit — every Analyst outcome is
@@ -141,5 +136,10 @@ const runtimeSpec = {
     unfinishedFinalStateIds: UNFINISHED_FINAL_STATE_IDS,
     transitionEventFields: ['developmentRequest', 'answer', 'questionId'],
 };
+export const _internal = {
+    composePlayerPrompt: runtimeSpec.composePlayerPrompt,
+    VERBATIM_PAYLOAD_FIELDS,
+    UNFINISHED_FINAL_STATE_IDS,
+};
 const createPlaybookRuntime = createXStatePlaybookRuntime(devMachine, runtimeSpec);
 export default createPlaybookRuntime;

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

@@ -160,12 +160,6 @@ function composePlayerPrompt(input: PlayerInput, resuming = false): string {
   return composePlayerContinuation(input, body, resuming);
 }
 
-export const _internal = {
-  composePlayerPrompt,
-  VERBATIM_PAYLOAD_FIELDS,
-  UNFINISHED_FINAL_STATE_IDS,
-};
-
 const runtimeSpec = {
   label: 'DEV',
   // DR-022 / slc/link.md: the declaration carries the value current at link
@@ -185,8 +179,7 @@ const runtimeSpec = {
   roleStates: {
     planAnalysis: {
       role: 'analyst',
-      label:
-        'Analyst is analyzing the development request to choose the smallest sound next step.',
+      label: 'Analyst is choosing the development path.',
     },
   },
   // DR-044: DEV owns no repository commit — every Analyst outcome is
@@ -224,7 +217,7 @@ const runtimeSpec = {
       },
     },
   },
-  composePlayerPrompt: (input: PlaybookPlayerInput, _identity, resuming) =>
+  composePlayerPrompt: (input: PlaybookPlayerInput, _identity, resuming?: boolean) =>
     composePlayerPrompt(input as PlayerInput, resuming),
   verbatimPayloadFields: VERBATIM_PAYLOAD_FIELDS,
   controlContextFields: [],
@@ -232,6 +225,12 @@ const runtimeSpec = {
   transitionEventFields: ['developmentRequest', 'answer', 'questionId'],
 } satisfies XStatePlaybookRuntimeSpecV3<DevPlaybookOptions>;
 
+export const _internal = {
+  composePlayerPrompt: runtimeSpec.composePlayerPrompt,
+  VERBATIM_PAYLOAD_FIELDS,
+  UNFINISHED_FINAL_STATE_IDS,
+};
+
 const createPlaybookRuntime: XStatePlaybookRuntimeFactory<
   XStatePlaybookRuntimeConstruction<
     DevPlaybookOptions,

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

@@ -49,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, delivered through a pull request when the request names a GitHub issue or asks for one',
+    intent: 'plan the development path for a request: 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

@@ -104,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, delivered through a pull request when the request names a GitHub issue or asks for one',
+    'plan the development path for a request: 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

@@ -19,7 +19,9 @@ The caller supplies:
 `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.
 
 When the caller gives its input, Captain shall relay the complete caller input in quotes (`>`) to Coder, along with the following instruction:
 
@@ -66,6 +68,7 @@ When the nested `code` call fails outside that authored result contract, `pr` sh
 
 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:
 
+> [ "$(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
@@ -75,6 +78,7 @@ When `code` succeeds, Captain shall publish the fix to the pull request by runni
 > 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.
+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.
 
 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:
@@ -92,11 +96,20 @@ Checks still failing is an authored failure that leaves the pull request open; t
 
 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)"
+> 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" ]
 
-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.
 
 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: