@sublang/playbook 14.0.0 → 14.1.0

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.js

@@ -92,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

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

@@ -179,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

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.playbook/pr.fsm.d.ts

@@ -278,7 +278,7 @@ export declare const prMachine: import("xstate").StateMachine<PrContext, {
 } | {
     type: "resumesOpenPullRequest";
     params: unknown;
-}, never, "failed" | "awaitBossReply" | "ready" | "openPullRequest" | "waitForChecks" | "fixChecks" | "publishFix" | "waitForChecksAfterFix" | "mergePullRequest" | "updateLocalDefault" | "notPublished" | "fixNotPublished" | "checksStillFailing" | "merged" | "mergeRefused" | "mergedLocalBehind" | "fixFailed", string, Readonly<Record<never, never>>, {
+}, never, "failed" | "ready" | "awaitBossReply" | "openPullRequest" | "waitForChecks" | "fixChecks" | "publishFix" | "waitForChecksAfterFix" | "mergePullRequest" | "updateLocalDefault" | "notPublished" | "fixNotPublished" | "checksStillFailing" | "merged" | "mergeRefused" | "mergedLocalBehind" | "fixFailed", string, Readonly<Record<never, never>>, {
     readonly status: "merged";
     /** The pull request number, exactly as Coder reported it. */
     readonly pullRequest: string;

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

@@ -169,7 +169,7 @@ export declare const reviewMachine: import("xstate").StateMachine<ReviewContext,
 } | {
     type: "restartInitialReview";
     params: unknown;
-}, never, "done" | "failed" | "awaitBossReply" | "ready" | "reviewInitial" | "addressFindings" | "reviewAfterCommit" | "reviewAfterRebuttal", string, Readonly<Record<string, never>>, ReviewOutput, import("xstate").EventObject, import("xstate").MetaObject, {
+}, never, "done" | "failed" | "ready" | "awaitBossReply" | "reviewInitial" | "addressFindings" | "reviewAfterCommit" | "reviewAfterRebuttal", string, Readonly<Record<string, never>>, ReviewOutput, import("xstate").EventObject, import("xstate").MetaObject, {
     id: "review";
     states: {
         readonly ready: {

package/slc/link.md

@@ -247,10 +247,36 @@ type JsonValue =
   | readonly JsonValue[]
   | { readonly [key: string]: JsonValue };
 
+// DR-063: the closed failure-cause contract. `code` is one of
+// PLAYBOOK_FAILURE_CODES and `evidence` holds exactly the members that code
+// names — repository paths, dispositions, classifications, and revisions, never
+// content or internal identity.
+type PlaybookFailureCode =
+  | 'commit-missing'
+  | 'commit-residual'
+  | 'pre-existing-lost'
+  | 'commits-more-than-one'
+  | 'history-rewritten'
+  | 'foreign-change'
+  | 'observation-unstable'
+  | 'attribution-ambiguous'
+  | 'receipt-missing'
+  | 'judge-failed'
+  | 'player-failed'
+  | 'aborted'
+  | 'child-failed'
+  | 'runtime-defect';
+
+interface PlaybookFailureCause {
+  readonly code: PlaybookFailureCode;
+  readonly evidence: PlaybookFailureEvidence;
+}
+
 interface NormalizedError {
   name: string;
   message: string;
   stack?: string;
+  cause?: PlaybookFailureCause;   // present when the error carried a valid one
 }
 
 type PlaybookStateValue =
@@ -2045,9 +2071,15 @@ parked-session snapshot capability; the pair changes no runtime ABI and no
 artifact or snapshot schema.
 
 ```typescript
+type PlaybookControlStanding = 'ready' | 'no-op' | 'blocked';
+type PlaybookControlActionReason = 'receipt-complete';
+
 interface PlaybookControlAction {
   id: string;      // stable within the returned view
   label: string;   // runtime-written, Boss-appropriate
+  standing?: PlaybookControlStanding;     // what running it would do (DR-063);
+                                          // absent reads as `ready`
+  reason?: PlaybookControlActionReason;   // why it is not `ready`
 }
 
 interface PlaybookControlView {

package/src/runtime.d.ts

@@ -32,10 +32,65 @@ export interface CaptainResult {
 export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
     readonly [key: string]: JsonValue;
 };
+export declare const PLAYBOOK_FAILURE_CODES: readonly ["commit-missing", "commit-residual", "pre-existing-lost", "commits-more-than-one", "history-rewritten", "foreign-change", "observation-unstable", "attribution-ambiguous", "receipt-missing", "judge-failed", "player-failed", "aborted", "child-failed", "runtime-defect"];
+export type PlaybookFailureCode = (typeof PLAYBOOK_FAILURE_CODES)[number];
+/** The bounded path lists one failure code's evidence may carry (DR-063 §1). */
+export interface PlaybookFailurePaths {
+    /** Paths changed in the worktree that no commit carries. */
+    readonly uncommitted?: readonly string[];
+    /** Pre-existing baseline paths the call changed before committing. */
+    readonly altered?: readonly string[];
+    /** Pre-existing baseline paths whose content is nowhere. */
+    readonly lost?: readonly string[];
+    /** Paths whose entry differs or is missing on either side. */
+    readonly changed?: readonly string[];
+    /** Paths omitted from the lists above by the 32-path bound. */
+    readonly truncated?: number;
+}
+/** The bounded error record a failure cause may carry (DR-063 §1). */
+export interface PlaybookFailureErrorEvidence {
+    readonly name: string;
+    readonly message: string;
+}
+/** The closed evidence object of one failure cause (DR-063 §1). */
+export interface PlaybookFailureEvidence {
+    readonly required?: PlaybookRepositoryDisposition;
+    readonly observed?: PlaybookRepositoryReceipt['classification'];
+    readonly baselineHead?: string;
+    readonly afterHead?: string;
+    readonly commitOid?: string;
+    readonly paths?: PlaybookFailurePaths;
+    readonly reason?: string;
+    readonly error?: PlaybookFailureErrorEvidence;
+    readonly errorCode?: string;
+    readonly roleId?: string;
+    readonly playerId?: string;
+    readonly playbookId?: string;
+    readonly cause?: PlaybookFailureCause;
+}
+/**
+ * Why a parked workflow failed (DR-063 §1): one code from the closed list and
+ * the closed evidence object that code names. Evidence holds repository paths,
+ * dispositions, classifications, and revision identities only — never file
+ * content, player prose, or internal call and session identities.
+ */
+export interface PlaybookFailureCause {
+    readonly code: PlaybookFailureCode;
+    readonly evidence: PlaybookFailureEvidence;
+}
+/**
+ * Validate, detach, and freeze one failure cause (DR-063 §1). The check is
+ * closed per code: exactly the evidence members that code names, nothing else,
+ * and a `child-failed` cause nests at most four deep. A value this rejects is
+ * not a cause, so a caller omits it rather than publishing an invented one.
+ */
+export declare function assertPlaybookFailureCause(value: unknown): PlaybookFailureCause;
 export interface NormalizedError {
     name: string;
     message: string;
     stack?: string;
+    /** DR-063 §2: present exactly when the underlying error carried a valid one. */
+    cause?: PlaybookFailureCause;
 }
 export type PlaybookStateValue = string | {
     readonly [key: string]: PlaybookStateValue;
@@ -181,12 +236,23 @@ export interface PlaybookRepositoryObservation {
     readonly projection: Readonly<Record<string, JsonValue>>;
     readonly projectionDigest: string;
 }
+/**
+ * The fate of the baseline projection entries a governed call absorbed into
+ * its one commit, altered, or lost (DR-062). Each list holds sorted unique
+ * baseline paths and the three are pairwise disjoint.
+ */
+export interface PlaybookRepositoryPreExistingChanges {
+    readonly absorbed: readonly string[];
+    readonly altered: readonly string[];
+    readonly lost: readonly string[];
+}
 /** The fail-closed classification of one complete physical or logical receipt. */
 export interface PlaybookRepositoryReceipt {
     readonly classification: 'unchanged' | 'one-descendant-commit' | 'multiple-commits' | 'rewritten-or-non-descendant' | 'worktree-only-change' | 'concurrent-or-foreign-change' | 'observation-ambiguous';
     readonly baseline: PlaybookRepositoryObservation;
     readonly after?: PlaybookRepositoryObservation;
     readonly commitOid?: string;
+    readonly preExisting?: PlaybookRepositoryPreExistingChanges;
 }
 /** One durably ordered physical governed-player boundary (DR-040). */
 export interface PlaybookEffectBoundary {
@@ -324,9 +390,13 @@ export interface PlaybookRuntimeSnapshot {
     };
     suspendedCall?: PlaybookSuspendedCall;
 }
+export type PlaybookControlStanding = 'ready' | 'no-op' | 'blocked';
+export type PlaybookControlActionReason = 'receipt-complete';
 export interface PlaybookControlAction {
     id: string;
     label: string;
+    standing?: PlaybookControlStanding;
+    reason?: PlaybookControlActionReason;
 }
 export interface PlaybookControlView {
     state: PlaybookState;