@sublang/playbook 17.4.0 → 17.5.0

package/reference/sdlc/code.playbook/bin/session-store.js

@@ -1161,12 +1161,18 @@ export function createCaptainSessionStore(options = {}) {
     try {
       await assertPrivateDirectory(assetsDirectory, fs);
       const names = await fs.readdir(assetsDirectory);
-      for (const name of names) {
-        if (!/^(?:[0-9a-f]{64}(?:\.json)?|\.import-[0-9a-f-]+\.tmp)$/.test(name)) throw new Error('unknown session asset entry prevents deletion');
-        await assertPrivateRegularPath(join(assetsDirectory, name), 0o600, fs, 'session asset');
+      const owned = names.filter((name) => /^(?:[0-9a-f]{64}(?:\.json)?|\.import-[0-9a-f-]+\.tmp)$/.test(name));
+      for (const name of owned) await assertPrivateRegularPath(join(assetsDirectory, name), 0o600, fs, 'session asset');
+      for (const name of owned) await fs.unlink(join(assetsDirectory, name));
+      // Foreign regular files (Finder or editor files) go with the session; a
+      // remaining subdirectory or link keeps the directory, not the session.
+      for (const name of names.filter((entry) => !owned.includes(entry))) {
+        const path = join(assetsDirectory, name);
+        try { const stat = await fs.lstat(path); if (stat.isFile() && !stat.isSymbolicLink()) await fs.unlink(path); }
+        catch (cause) { if (cause?.code !== 'ENOENT') throw cause; }
       }
-      for (const name of names) await fs.unlink(join(assetsDirectory, name));
-      await fs.rmdir(assetsDirectory);
+      try { await fs.rmdir(assetsDirectory); }
+      catch (cause) { if (cause?.code !== 'ENOTEMPTY' && cause?.code !== 'EEXIST') throw cause; }
       await syncDirectory(sessionsDir, fs);
     } catch (cause) { if (cause?.code !== 'ENOENT') throw cause; }
     for (const suffix of ['.records.jsonl', '.hints.json', '.spex.json', '.json']) {

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

@@ -51,6 +51,8 @@ export interface IrTaskPhasePlayerInput extends PlayerInputBase {
     readonly sourceItem: 'CODE-3';
     /** `<ir-number>`: the IR whose next unfinished task this phase implements. */
     readonly irNumber?: string;
+    /** Source-owned relay; historical canonical evidence, not present approval. */
+    readonly previousPhaseReview: string;
 }
 export type PlayerInput = FirstPhasePlayerInput | IrTaskPhasePlayerInput;
 export type PlayerOutput = {
@@ -125,6 +127,14 @@ export interface CodeInput {
     /** Optional seed for `<run-results>`; `START_CODE` may supply its own. */
     readonly runResults?: string;
 }
+export interface PreviousPhaseReview {
+    readonly phaseKind: 'direct' | 'new-intent' | 'ir-task';
+    readonly phaseOutcome: PhaseOutcome;
+    readonly scopeCommit: string;
+    readonly evaluatedRevision: string;
+    readonly irNumber?: string;
+    readonly irTask?: string;
+}
 export interface CodeContext {
     /** `<run-results>`: relevant run results relayed to every phase. */
     readonly runResults: string;
@@ -142,6 +152,8 @@ export interface CodeContext {
     readonly phaseOutcome?: PhaseOutcome;
     /** Revision evaluated by the latest passing review. */
     readonly evaluatedRevision?: string;
+    /** Frozen only by an accepted canonical clean child REVIEW. */
+    readonly previousPhaseReview?: PreviousPhaseReview;
     /** Compact failure CODE reports when review did not pass a phase. */
     readonly reviewError?: CompactError;
     /** Sanitized evidence of the review result that ended CODE. */

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

@@ -25,13 +25,19 @@ const FIRST_PHASE_PROMPT = [
     'For an existing IR, read the identified IR and implement exactly its next unfinished task, including corresponding tests or specs if any.',
     'Do not implement a later task in this phase.',
     "Mark the IR's progress and deliverables when relevant.",
+    "After implementing an IR task, identify it and state whether any IR task still has unfinished Coder work; if so identify the next unfinished task, otherwise state this was the final IR task's Coder work.",
+    "Report pending independent REVIEW, owner acceptance and later delivery/workshop steps separately; they imply an unfinished IR task only when the IR assigns that work to a remaining task.",
+    "Report only what the IR and completed work establish, in ordinary prose without a required marker.",
     'If the IR will be finished after this phase, double-check that all acceptance criteria are met.',
     '',
     'Consult @specs/map.md for relevant context and @specs/meta.md for spec requirements, if needed.',
     '',
     'Keep to the original intent and follow what it asks.',
     'Do not re-run tests or builds whose inputs have not changed since any previous reported run.',
-    "Make the phase's minimal changes and then one new commit, following @specs/packages/git.md; never amend an existing commit.",
+    "If a required Boss answer prevents completion of the current phase or IR task, ask that question and return without committing.",
+    "Preserve permitted uncommitted work for the deferred continuation; do not create a partial or blocker-only commit to meet the one-commit requirement.",
+    "After the answer allows completion, make exactly one phase-owned commit before REVIEW.",
+    "When the phase is complete, make its minimal changes and then one new commit, following @specs/packages/git.md; never amend an existing commit.",
     'Make the commit message explain concisely what changed and why, including relevant verification.',
     'Identify every new commit you make.',
     'Credit every AI that contributed to this commit: Coder <coder-llm>.',
@@ -43,11 +49,20 @@ const IR_TASK_PHASE_PROMPT = [
     'Read the identified IR and implement exactly its next unfinished task, including corresponding tests or specs if any.',
     'Do not implement a later task in this phase.',
     "Mark the IR's progress and deliverables when relevant.",
+    "After implementing an IR task, identify it and state whether any IR task still has unfinished Coder work; if so identify the next unfinished task, otherwise state this was the final IR task's Coder work.",
+    "Report pending independent REVIEW, owner acceptance and later delivery/workshop steps separately; they imply an unfinished IR task only when the IR assigns that work to a remaining task.",
+    "Report only what the IR and completed work establish, in ordinary prose without a required marker.",
     'If the IR will be finished after this phase, double-check that all acceptance criteria are met.',
+    'Use the quoted previous-phase review only for its exact recorded scope; committed pending-review text may predate that canonical result.',
+    'Before treating it as current review evidence, verify clean current HEAD equals its evaluatedRevision; a mismatch is not approval.',
+    'It does not replace independent review of this task or any new owner or release decision.',
     '',
     'Keep to the original intent and follow what it asks.',
     'Do not re-run tests or builds whose inputs have not changed since any previous reported run.',
-    "Make the phase's minimal changes and then one new commit, following @specs/packages/git.md; never amend an existing commit.",
+    "If a required Boss answer prevents completion of the current phase or IR task, ask that question and return without committing.",
+    "Preserve permitted uncommitted work for the deferred continuation; do not create a partial or blocker-only commit to meet the one-commit requirement.",
+    "After the answer allows completion, make exactly one phase-owned commit before REVIEW.",
+    "When the phase is complete, make its minimal changes and then one new commit, following @specs/packages/git.md; never amend an existing commit.",
     'Make the commit message explain concisely what changed and why, including relevant verification.',
     'Identify every new commit you make.',
     'Credit every AI that contributed to this commit: Coder <coder-llm>.',
@@ -55,6 +70,7 @@ const IR_TASK_PHASE_PROMPT = [
     '> Original request: <caller-input>',
     '> IR number: <ir-number>',
     '> Run results: <run-results>',
+    '> Previous phase review: <previous-phase-review>',
 ].join('\n');
 const REVIEW_NEW_INTENT_PHASE_TEMPLATE = [
     '> Original intent: <caller-input>',
@@ -68,7 +84,7 @@ const REVIEW_IR_TASK_PHASE_TEMPLATE = [
     '',
     '> Current IR task: <ir-task>',
 ].join('\n');
-const NEEDS_BOSS_REPLY_DESCRIPTION = "The acting agent's prose surfaces a clarifying question for Boss that the agent cannot answer alone. Output shall include `question: <verbatim question text from the acting agent's prose>`.";
+const NEEDS_BOSS_REPLY_DESCRIPTION = "At the end of this call, Coder has an unanswered clarifying question for Boss whose answer is required to complete the current coding phase. Earlier interim questions resolved or superseded by later affirmative current-phase completion, and prerequisites only for later review, acceptance or release stages, do not establish this outcome. Output shall include `question: <verbatim question text from the acting agent's prose>`.";
 const FIRST_PHASE_RESULT = {
     directCommit: "Coder completed the new coding intent as one direct implementation phase and made its one new commit; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.",
     irCommit: "Coder decomposed the new coding intent into a new IR, implemented no IR task, and made its one new commit; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, and `irNumber` identifying the created IR.",
@@ -467,6 +483,7 @@ export const codeMachine = setup({
                 irTask: undefined,
                 phaseOutcome: undefined,
                 evaluatedRevision: undefined,
+                previousPhaseReview: undefined,
                 reviewError: undefined,
                 reviewEvidence: undefined,
                 lastError: undefined,
@@ -477,6 +494,7 @@ export const codeMachine = setup({
         resetForInterrupt: assign({
             phaseOutcome: undefined,
             evaluatedRevision: undefined,
+            previousPhaseReview: undefined,
             reviewError: undefined,
             reviewEvidence: undefined,
             lastError: undefined,
@@ -516,11 +534,24 @@ export const codeMachine = setup({
             pendingBossQuestion: undefined,
             bossReply: undefined,
         }),
-        rememberReviewPass: assign(({ event }) => {
+        rememberReviewPass: assign(({ context, event }) => {
             const pass = reviewPassOf(event);
-            return pass === undefined
+            return pass === undefined || context.codeCommit === undefined || context.phaseOutcome === undefined
                 ? {}
-                : { evaluatedRevision: pass.evaluatedRevision, lastError: undefined };
+                : {
+                    evaluatedRevision: pass.evaluatedRevision,
+                    previousPhaseReview: {
+                        phaseKind: context.phaseOutcome === 'directCommit'
+                            ? 'direct' : context.phaseOutcome === 'irCommit'
+                            ? 'new-intent' : 'ir-task',
+                        phaseOutcome: context.phaseOutcome,
+                        scopeCommit: context.codeCommit,
+                        evaluatedRevision: pass.evaluatedRevision,
+                        ...(context.irNumber === undefined ? {} : { irNumber: context.irNumber }),
+                        ...(context.irTask === undefined ? {} : { irTask: context.irTask }),
+                    },
+                    lastError: undefined,
+                };
         }),
         rememberReviewNotPassed: assign(({ event }) => {
             const output = doneOutputOf(event);
@@ -703,6 +734,9 @@ export const codeMachine = setup({
                         ? { irNumber: context.irNumber }
                         : {}),
                     runResults: context.runResults,
+                    previousPhaseReview: context.previousPhaseReview === undefined
+                        ? 'No accepted prior-phase review is available.'
+                        : JSON.stringify(context.previousPhaseReview),
                     ...bossReplyFields(context),
                 }),
                 onDone: [

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

@@ -95,6 +95,8 @@ export interface IrTaskPhasePlayerInput extends PlayerInputBase {
   readonly sourceItem: 'CODE-3';
   /** `<ir-number>`: the IR whose next unfinished task this phase implements. */
   readonly irNumber?: string;
+  /** Source-owned relay; historical canonical evidence, not present approval. */
+  readonly previousPhaseReview: string;
 }
 
 export type PlayerInput = FirstPhasePlayerInput | IrTaskPhasePlayerInput;
@@ -194,6 +196,15 @@ export interface CodeInput {
   readonly runResults?: string;
 }
 
+export interface PreviousPhaseReview {
+  readonly phaseKind: 'direct' | 'new-intent' | 'ir-task';
+  readonly phaseOutcome: PhaseOutcome;
+  readonly scopeCommit: string;
+  readonly evaluatedRevision: string;
+  readonly irNumber?: string;
+  readonly irTask?: string;
+}
+
 export interface CodeContext {
   /** `<run-results>`: relevant run results relayed to every phase. */
   readonly runResults: string;
@@ -211,6 +222,8 @@ export interface CodeContext {
   readonly phaseOutcome?: PhaseOutcome;
   /** Revision evaluated by the latest passing review. */
   readonly evaluatedRevision?: string;
+  /** Frozen only by an accepted canonical clean child REVIEW. */
+  readonly previousPhaseReview?: PreviousPhaseReview;
   /** Compact failure CODE reports when review did not pass a phase. */
   readonly reviewError?: CompactError;
   /** Sanitized evidence of the review result that ended CODE. */
@@ -249,13 +262,19 @@ const FIRST_PHASE_PROMPT = [
   'For an existing IR, read the identified IR and implement exactly its next unfinished task, including corresponding tests or specs if any.',
   'Do not implement a later task in this phase.',
   "Mark the IR's progress and deliverables when relevant.",
+  "After implementing an IR task, identify it and state whether any IR task still has unfinished Coder work; if so identify the next unfinished task, otherwise state this was the final IR task's Coder work.",
+  "Report pending independent REVIEW, owner acceptance and later delivery/workshop steps separately; they imply an unfinished IR task only when the IR assigns that work to a remaining task.",
+  "Report only what the IR and completed work establish, in ordinary prose without a required marker.",
   'If the IR will be finished after this phase, double-check that all acceptance criteria are met.',
   '',
   'Consult @specs/map.md for relevant context and @specs/meta.md for spec requirements, if needed.',
   '',
   'Keep to the original intent and follow what it asks.',
   'Do not re-run tests or builds whose inputs have not changed since any previous reported run.',
-  "Make the phase's minimal changes and then one new commit, following @specs/packages/git.md; never amend an existing commit.",
+  "If a required Boss answer prevents completion of the current phase or IR task, ask that question and return without committing.",
+  "Preserve permitted uncommitted work for the deferred continuation; do not create a partial or blocker-only commit to meet the one-commit requirement.",
+  "After the answer allows completion, make exactly one phase-owned commit before REVIEW.",
+  "When the phase is complete, make its minimal changes and then one new commit, following @specs/packages/git.md; never amend an existing commit.",
   'Make the commit message explain concisely what changed and why, including relevant verification.',
   'Identify every new commit you make.',
   'Credit every AI that contributed to this commit: Coder <coder-llm>.',
@@ -268,11 +287,20 @@ const IR_TASK_PHASE_PROMPT = [
   'Read the identified IR and implement exactly its next unfinished task, including corresponding tests or specs if any.',
   'Do not implement a later task in this phase.',
   "Mark the IR's progress and deliverables when relevant.",
+  "After implementing an IR task, identify it and state whether any IR task still has unfinished Coder work; if so identify the next unfinished task, otherwise state this was the final IR task's Coder work.",
+  "Report pending independent REVIEW, owner acceptance and later delivery/workshop steps separately; they imply an unfinished IR task only when the IR assigns that work to a remaining task.",
+  "Report only what the IR and completed work establish, in ordinary prose without a required marker.",
   'If the IR will be finished after this phase, double-check that all acceptance criteria are met.',
+  'Use the quoted previous-phase review only for its exact recorded scope; committed pending-review text may predate that canonical result.',
+  'Before treating it as current review evidence, verify clean current HEAD equals its evaluatedRevision; a mismatch is not approval.',
+  'It does not replace independent review of this task or any new owner or release decision.',
   '',
   'Keep to the original intent and follow what it asks.',
   'Do not re-run tests or builds whose inputs have not changed since any previous reported run.',
-  "Make the phase's minimal changes and then one new commit, following @specs/packages/git.md; never amend an existing commit.",
+  "If a required Boss answer prevents completion of the current phase or IR task, ask that question and return without committing.",
+  "Preserve permitted uncommitted work for the deferred continuation; do not create a partial or blocker-only commit to meet the one-commit requirement.",
+  "After the answer allows completion, make exactly one phase-owned commit before REVIEW.",
+  "When the phase is complete, make its minimal changes and then one new commit, following @specs/packages/git.md; never amend an existing commit.",
   'Make the commit message explain concisely what changed and why, including relevant verification.',
   'Identify every new commit you make.',
   'Credit every AI that contributed to this commit: Coder <coder-llm>.',
@@ -280,6 +308,7 @@ const IR_TASK_PHASE_PROMPT = [
   '> Original request: <caller-input>',
   '> IR number: <ir-number>',
   '> Run results: <run-results>',
+  '> Previous phase review: <previous-phase-review>',
 ].join('\n');
 
 const REVIEW_NEW_INTENT_PHASE_TEMPLATE = [
@@ -297,7 +326,7 @@ const REVIEW_IR_TASK_PHASE_TEMPLATE = [
 ].join('\n');
 
 const NEEDS_BOSS_REPLY_DESCRIPTION =
-  "The acting agent's prose surfaces a clarifying question for Boss that the agent cannot answer alone. Output shall include `question: <verbatim question text from the acting agent's prose>`.";
+  "At the end of this call, Coder has an unanswered clarifying question for Boss whose answer is required to complete the current coding phase. Earlier interim questions resolved or superseded by later affirmative current-phase completion, and prerequisites only for later review, acceptance or release stages, do not establish this outcome. Output shall include `question: <verbatim question text from the acting agent's prose>`.";
 
 const FIRST_PHASE_RESULT = {
   directCommit:
@@ -823,6 +852,7 @@ export const codeMachine = setup({
             irTask: undefined,
             phaseOutcome: undefined,
             evaluatedRevision: undefined,
+            previousPhaseReview: undefined,
             reviewError: undefined,
             reviewEvidence: undefined,
             lastError: undefined,
@@ -834,6 +864,7 @@ export const codeMachine = setup({
     resetForInterrupt: assign({
       phaseOutcome: undefined,
       evaluatedRevision: undefined,
+      previousPhaseReview: undefined,
       reviewError: undefined,
       reviewEvidence: undefined,
       lastError: undefined,
@@ -876,11 +907,24 @@ export const codeMachine = setup({
       pendingBossQuestion: undefined,
       bossReply: undefined,
     }),
-    rememberReviewPass: assign(({ event }) => {
+    rememberReviewPass: assign(({ context, event }) => {
       const pass = reviewPassOf(event);
-      return pass === undefined
+      return pass === undefined || context.codeCommit === undefined || context.phaseOutcome === undefined
         ? {}
-        : { evaluatedRevision: pass.evaluatedRevision, lastError: undefined };
+        : {
+            evaluatedRevision: pass.evaluatedRevision,
+            previousPhaseReview: {
+              phaseKind: context.phaseOutcome === 'directCommit'
+                ? 'direct' as const : context.phaseOutcome === 'irCommit'
+                ? 'new-intent' as const : 'ir-task' as const,
+              phaseOutcome: context.phaseOutcome,
+              scopeCommit: context.codeCommit,
+              evaluatedRevision: pass.evaluatedRevision,
+              ...(context.irNumber === undefined ? {} : { irNumber: context.irNumber }),
+              ...(context.irTask === undefined ? {} : { irTask: context.irTask }),
+            },
+            lastError: undefined,
+          };
     }),
     rememberReviewNotPassed: assign(({ event }) => {
       const output = doneOutputOf(event);
@@ -1086,6 +1130,9 @@ export const codeMachine = setup({
             ? { irNumber: context.irNumber }
             : {}),
           runResults: context.runResults,
+          previousPhaseReview: context.previousPhaseReview === undefined
+            ? 'No accepted prior-phase review is available.'
+            : JSON.stringify(context.previousPhaseReview),
           ...bossReplyFields(context),
         }),
         onDone: [

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

@@ -11,7 +11,7 @@ Roles:
 
 ### CODE-1
 
-Each phase ends with exactly one new Coder commit owned by `code`, and no existing commit is rewritten.
+Each completed phase ends with exactly one new Coder commit owned by `code`, and no existing commit is rewritten.
 Captain uses the repository-effect receipt as the authoritative identity of the phase's new commit.
 When the request may continue an existing IR that it does not identify unambiguously, Coder asks Boss before changing files, and Boss's answer resumes this same phase.
 
@@ -28,13 +28,19 @@ When the first coding phase begins for the caller's coding request and any relev
 > For an existing IR, read the identified IR and implement exactly its next unfinished task, including corresponding tests or specs if any.
 > Do not implement a later task in this phase.
 > Mark the IR's progress and deliverables when relevant.
+> After implementing an IR task, identify it and state whether any IR task still has unfinished Coder work; if so identify the next unfinished task, otherwise state this was the final IR task's Coder work.
+> Report pending independent REVIEW, owner acceptance and later delivery/workshop steps separately; they imply an unfinished IR task only when the IR assigns that work to a remaining task.
+> Report only what the IR and completed work establish, in ordinary prose without a required marker.
 > If the IR will be finished after this phase, double-check that all acceptance criteria are met.
 >
 > Consult @specs/map.md for relevant context and @specs/meta.md for spec requirements, if needed.
 >
 > Keep to the original intent and follow what it asks.
 > Do not re-run tests or builds whose inputs have not changed since any previous reported run.
-> Make the phase's minimal changes and then one new commit, following @specs/packages/git.md; never amend an existing commit.
+> If a required Boss answer prevents completion of the current phase or IR task, ask that question and return without committing.
+> Preserve permitted uncommitted work for the deferred continuation; do not create a partial or blocker-only commit to meet the one-commit requirement.
+> After the answer allows completion, make exactly one phase-owned commit before REVIEW.
+> When the phase is complete, make its minimal changes and then one new commit, following @specs/packages/git.md; never amend an existing commit.
 > Make the commit message explain concisely what changed and why, including relevant verification.
 > Identify every new commit you make.
 > Credit every AI that contributed to this commit: Coder <coder-llm>.
@@ -47,6 +53,7 @@ Results:
 - `irCommit`: Coder decomposed the new coding intent into a new IR, implemented no IR task, and made its one new commit; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, and `irNumber` identifying the created IR.
 - `moreTasks`: Coder continued an existing IR, implemented exactly its next unfinished task, made its one new commit, and at least one IR task remains unfinished; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, `irNumber` identifying the continued IR, and `irTask` naming the implemented task.
 - `finalTask`: Coder continued an existing IR, implemented its final unfinished task, and made its one new commit; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, `irNumber` identifying the continued IR, and `irTask` naming the implemented task.
+- `needsBossReply`: At the end of this call, Coder has an unanswered clarifying question for Boss whose answer is required to complete the current coding phase. Earlier interim questions resolved or superseded by later affirmative current-phase completion, and prerequisites only for later review, acceptance or release stages, do not establish this outcome. Output shall include `question: <verbatim question text from the acting agent's prose>`.
 
 ### CODE-2
 
@@ -59,6 +66,10 @@ When a direct implementation or new-IR phase ends with its one new `code`-owned
 > > Coder output: <coder-output>
 
 A nested `review` passes the phase only when its result applies to that supplied review scope, returns the exact evaluated repository revision, and affirmatively establishes that no unsettled findings remain.
+On each successful nested REVIEW, Captain shall freeze the previous phase review as one record from the canonical child result and the phase's accepted receipt-owned scope: exact phase kind (direct, new intent or IR task), phase outcome, CODE scope commit, REVIEW evaluated revision, and IR/task identity when present.
+CODE scope commit and evaluated revision remain distinct because REVIEW may create fix commits.
+No caller option, player prose or repository status text supplies this record.
+The record survives permitted restoration and the current task's Boss-answer continuation, and a fresh run or explicit Boss interruption clears it.
 When `review` passes a direct implementation phase, `code` is complete and returns to its caller the exact last `code`-owned commit, the exact final evaluated repository revision, and the fact that every phase's review passed with no unsettled findings.
 When `review` passes a new-IR phase, Captain continues with the next unfinished IR-task phase.
 When `review` returns an authored abort or failure, or a terminal result that does not establish that the supplied scope was evaluated with no unsettled findings, `code` starts no further phase and reports the failure and the last `code`-owned commit to its caller.
@@ -66,7 +77,9 @@ When the nested `review` call fails outside that authored result contract, `code
 
 ### CODE-3
 
-Each phase ends with exactly one new Coder commit owned by `code`, and no existing commit is rewritten.
+When absent, the previous phase review reads "No accepted prior-phase review is available.".
+
+Each completed phase ends with exactly one new Coder commit owned by `code`, and no existing commit is rewritten.
 Captain uses the repository-effect receipt as the authoritative identity of the phase's new commit.
 
 When a later IR-task phase begins, Captain shall prompt Coder:
@@ -74,11 +87,20 @@ When a later IR-task phase begins, Captain shall prompt Coder:
 > Read the identified IR and implement exactly its next unfinished task, including corresponding tests or specs if any.
 > Do not implement a later task in this phase.
 > Mark the IR's progress and deliverables when relevant.
+> After implementing an IR task, identify it and state whether any IR task still has unfinished Coder work; if so identify the next unfinished task, otherwise state this was the final IR task's Coder work.
+> Report pending independent REVIEW, owner acceptance and later delivery/workshop steps separately; they imply an unfinished IR task only when the IR assigns that work to a remaining task.
+> Report only what the IR and completed work establish, in ordinary prose without a required marker.
 > If the IR will be finished after this phase, double-check that all acceptance criteria are met.
+> Use the quoted previous-phase review only for its exact recorded scope; committed pending-review text may predate that canonical result.
+> Before treating it as current review evidence, verify clean current HEAD equals its evaluatedRevision; a mismatch is not approval.
+> It does not replace independent review of this task or any new owner or release decision.
 >
 > Keep to the original intent and follow what it asks.
 > Do not re-run tests or builds whose inputs have not changed since any previous reported run.
-> Make the phase's minimal changes and then one new commit, following @specs/packages/git.md; never amend an existing commit.
+> If a required Boss answer prevents completion of the current phase or IR task, ask that question and return without committing.
+> Preserve permitted uncommitted work for the deferred continuation; do not create a partial or blocker-only commit to meet the one-commit requirement.
+> After the answer allows completion, make exactly one phase-owned commit before REVIEW.
+> When the phase is complete, make its minimal changes and then one new commit, following @specs/packages/git.md; never amend an existing commit.
 > Make the commit message explain concisely what changed and why, including relevant verification.
 > Identify every new commit you make.
 > Credit every AI that contributed to this commit: Coder <coder-llm>.
@@ -86,10 +108,12 @@ When a later IR-task phase begins, Captain shall prompt Coder:
 > > Original request: <caller-input>
 > > IR number: <ir-number>
 > > Run results: <run-results>
+> > Previous phase review: <previous-phase-review>
 
 Results:
 - `moreTasks`: Coder implemented exactly the IR's next unfinished task, made its one new commit, and at least one IR task remains unfinished; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, `irNumber` identifying the IR, and `irTask` naming the implemented task.
 - `finalTask`: Coder implemented the IR's final unfinished task and made its one new commit; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, `irNumber` identifying the IR, and `irTask` naming the implemented task.
+- `needsBossReply`: At the end of this call, Coder has an unanswered clarifying question for Boss whose answer is required to complete the current coding phase. Earlier interim questions resolved or superseded by later affirmative current-phase completion, and prerequisites only for later review, acceptance or release stages, do not establish this outcome. Output shall include `question: <verbatim question text from the acting agent's prose>`.
 
 ### CODE-4
 
@@ -104,6 +128,10 @@ When an IR-task phase, including the first phase for an existing IR, ends with i
 > > Current IR task: <ir-task>
 
 A nested `review` passes the phase only when its result applies to that supplied review scope, returns the exact evaluated repository revision, and affirmatively establishes that no unsettled findings remain.
+On each successful nested REVIEW, Captain shall freeze the previous phase review as one record from the canonical child result and the phase's accepted receipt-owned scope: exact phase kind (direct, new intent or IR task), phase outcome, CODE scope commit, REVIEW evaluated revision, and IR/task identity when present.
+CODE scope commit and evaluated revision remain distinct because REVIEW may create fix commits.
+No caller option, player prose or repository status text supplies this record.
+The record survives permitted restoration and the current task's Boss-answer continuation, and a fresh run or explicit Boss interruption clears it.
 When `review` passes a nonfinal IR-task phase, Captain continues with the next unfinished IR-task phase.
 When `review` passes the final IR-task phase, `code` is complete and returns to its caller the exact last `code`-owned commit, the exact final evaluated repository revision, and the fact that every phase's review passed with no unsettled findings.
 When `review` returns an authored abort or failure, or a terminal result that does not establish that the supplied scope was evaluated with no unsettled findings, `code` starts no further phase and reports the failure and the last `code`-owned commit to its caller.

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

@@ -24,6 +24,15 @@ function retainedEffectLedgerCanRebase(checkpoint, current) {
         .slice(checkpoint.boundaries.length)
         .every(({ physicalReceipt }) => physicalReceipt?.classification === 'unchanged');
 }
+function missingPackagedReview(enablementById, playbookId) {
+    const selected = enablementById.get(playbookId);
+    if (selected === undefined ||
+        enablementById.has('review') ||
+        !['code', 'decide'].includes(playbookId) ||
+        selected.configuredFrom !== `@sublang/playbook/${playbookId}/registry`)
+        return undefined;
+    return `/${selected.command} requires enabled playbook "review"; enable REVIEW before starting this packaged workflow`;
+}
 function createRuntimeForEnablement(enablement, hostCapabilitiesById) {
     const hostCapabilities = hostCapabilitiesById.get(enablement.entry.id);
     if (hostCapabilities === undefined) {
@@ -2363,6 +2372,7 @@ async function buildEnablements(options, loadModule, hostCapabilities) {
         hostCapabilitiesById.set(entry.id, hostCapability);
         enablementById.set(entry.id, {
             entry,
+            configuredFrom: from,
             artifactSchema,
             command,
             options: validatedOptions,
@@ -3842,13 +3852,16 @@ export function createPlaybookCaptainShell(options, deps = {}) {
         const sessionId = allocateSessionId();
         const playerBindings = makePlayerBindings(enablement);
         const runtime = createRuntimeForEnablement(enablement, hostCapabilitiesById);
+        // A nested child inherits only its parent's selection, never the turn's
+        // unselected references; only a root reads the turn's selection.
+        const inherited = parent ? parent.frame.attachments : (activeTurn?.selectedAttachments ?? activeTurn?.attachments);
         return {
             entry,
             enablement,
             runtime,
             sessionId,
             rootSessionId: parent?.frame.rootSessionId ?? sessionId,
-            ...((parent?.frame.attachments ?? activeTurn?.selectedAttachments ?? activeTurn?.attachments)?.length ? { attachments: [...(parent?.frame.attachments ?? activeTurn?.selectedAttachments ?? activeTurn.attachments)] } : {}),
+            ...(inherited?.length ? { attachments: [...inherited] } : {}),
             depth: parent ? parent.frame.depth + 1 : 0,
             playerBindings,
             ...(parent ? { parent } : {}),
@@ -4152,8 +4165,6 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             finally {
                 if (leafFrame() === frame) {
                     frames.pop();
-                    if (!frame.parent)
-                        pendingAttachments = [];
                     if (frame.parent) {
                         pendingChildParents.delete(frame.parent.frame);
                     }
@@ -4541,6 +4552,24 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             return;
         }
         assertRetainableResult(frame, result);
+        // A deferred checkpoint refusal changes the runtime's control overlay
+        // without publishing an FSM transition. Refresh its derived question
+        // mirror from an exact safe snapshot before reporting or saving the stop.
+        if (leafFrame() === frame && !frame.disposing &&
+            retainedEffectReconciliation === undefined) {
+            try {
+                const exported = frame.runtime.exportSnapshot?.();
+                if (exported !== undefined) {
+                    const snapshot = assertPlaybookRuntimeSnapshot(exported, frame.entry.id);
+                    if (isDeepStrictEqual(snapshot.state, result.state) &&
+                        isDeepStrictEqual(snapshot.effectLedger, currentEffectLedger())) {
+                        pendingBossQuestions = snapshot.pendingBossQuestions.length === 0 && pendingBossQuestions === undefined
+                            ? undefined : mirroredBossQuestions(snapshot.pendingBossQuestions);
+                    }
+                }
+            }
+            catch { /* An inconsistent runtime must still fail exact capture. */ }
+        }
         if (result.outcome === 'aborted' && runFailureFacts) {
             runFailureFacts.push(`${frameLabel(frame)} was aborted before its outcome could be confirmed; it was not repeated automatically.`);
         }
@@ -4610,6 +4639,9 @@ export function createPlaybookCaptainShell(options, deps = {}) {
                 request.playbookId,
             ].join(' -> ')}`);
         }
+        const reviewRefusal = missingPackagedReview(enablementById, entry.id);
+        if (reviewRefusal !== undefined)
+            throw new Error(reviewRefusal);
         pendingChildParents.add(parent);
         let child;
         try {
@@ -6245,7 +6277,13 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             // selections freeze after their work and before reporting begins.
             if (selection.action === 'respond')
                 freezeControllerEvidence();
-            let settlement = await executeSelection(selection, signal, automaticRecovery);
+            signal.throwIfAborted();
+            const reviewRefusal = selection.action === 'start' || selection.action === 'switch'
+                ? missingPackagedReview(enablementById, selection.playbookId)
+                : undefined;
+            let settlement = reviewRefusal === undefined
+                ? await executeSelection(selection, signal, automaticRecovery)
+                : await rejectSelection(selection, reviewRefusal);
             // One controller action can include bounded prerequisite recovery.
             // Neither the model nor a retry manufactures an unadvertised transition.
             if (turn && abortPreparation && settlement.status !== 'rejected' && !['respond', 'dismiss', 'recover'].includes(selection.action)) {
@@ -6723,6 +6761,9 @@ export function createPlaybookCaptainShell(options, deps = {}) {
             const nextAttachments = mergeAttachments(leaf.attachments ?? [], selected);
             if (nextAttachments.length)
                 leaf.attachments = nextAttachments;
+            // Delivered references now belong to the leaf; the rest stay pending.
+            const delivered = new Set(selected.map((reference) => reference.assetId));
+            pendingAttachments = pendingAttachments.filter((reference) => !delivered.has(reference.assetId));
             // CAPTAIN-8: delivery carries text only, and the shell is authoritative
             // for that text — any text carried on the selection is ignored.
             turn.settled = true;