@sublang/playbook 17.3.0 → 17.4.1

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

@@ -7,6 +7,7 @@
 // complete retained-generation map under guarded source-first publication.
 
 import { createHash, randomUUID } from 'node:crypto';
+import { createAssetStore, parseAssetUri, validateAssetRef, validateAssetRefs } from '../session-assets.js';
 import {
   SESSION_MANIFEST_VERSION, EMPTY_REPLAY_SHA256, sha256,
   validateSessionManifest, recoveryFromManifest, manifestFromRecovery,
@@ -637,6 +638,12 @@ export function createCaptainSessionStore(options = {}) {
   const replayReadCursors = new Map();
   const replayReadQueues = new Map();
   const portableWriters = new Map();
+  const assetStores = new Map();
+  const assetStoreFor = (sessionId) => {
+    assertSessionId(sessionId);
+    if (!assetStores.has(sessionId)) assetStores.set(sessionId, createAssetStore({ directory: join(sessionsDir, `${sessionId}.assets`), ...(options.maxAssetBytes === undefined ? {} : { maxAssetBytes: options.maxAssetBytes }) }));
+    return assetStores.get(sessionId);
+  };
 
   if (!isAbsolute(sessionsDir)) {
     throw new Error('Captain session store path must be absolute');
@@ -758,7 +765,11 @@ export function createCaptainSessionStore(options = {}) {
     if (value.sessionId !== sessionId) throw new Error('session manifest identity does not match its filename');
     return value.schemaVersion === 7 ? validateSessionManifest(value) : value;
   };
-  const prepare = () => prepareSessionPermissions(sessionsDir, fs);
+  const prepare = async () => {
+    await prepareSessionPermissions(sessionsDir, fs);
+    let names; try { names = await fs.readdir(sessionsDir); } catch (cause) { if (cause?.code === 'ENOENT') return; throw cause; }
+    for (const name of names) if (name.endsWith('.assets') && SESSION_ID_PATTERN.test(name.slice(0, -7))) await assetStoreFor(name.slice(0, -7)).prepare();
+  };
   const readHistory = async (sessionId, options = {}) => {
     assertSessionId(sessionId);
     const history = await readSessionHistory({ sessionsDir, path: recordsPathFor(sessionId), fs, afterSeq: options.afterSeq ?? 0 });
@@ -771,6 +782,35 @@ export function createCaptainSessionStore(options = {}) {
     } catch { return history; }
     return legacyJournalHistory(legacy, options.afterSeq ?? 0, history);
   };
+  // Only our typed reference locations participate; opaque tool/text data is history.
+  const assertAssetInventory = (manifest, entries) => {
+    const declared = new Map((manifest.assets?.entries ?? []).map((reference) => [reference.assetId, reference]));
+    const check = (reference) => {
+      const valid = validateAssetRef(reference);
+      if (declared.get(valid.assetId)?.byteLength !== valid.byteLength) throw new Error(`session asset reference is absent from its checkpoint inventory: ${valid.assetId}`);
+    };
+    const checkRefs = (references) => { for (const reference of references ?? []) check(reference); };
+    const snapshot = (value) => {
+      if (!value) return;
+      checkRefs(value.pendingAttachments);
+      for (const frame of value.frames ?? []) checkRefs(frame.attachments);
+      for (const item of value.journal ?? []) if (item.kind === 'boss' && typeof item.payload === 'object' && item.payload !== null) checkRefs(item.payload.attachments);
+    };
+    snapshot(manifest.snapshot); snapshot(manifest.uncertain?.progress?.snapshot);
+    checkRefs(manifest.uncertain?.attachments);
+    for (const generation of Object.values(manifest.retainedGenerations ?? {})) for (const frame of generation.frames ?? []) checkRefs(frame.attachments);
+    for (const { record } of entries) {
+      if (record.type === 'turn_started') checkRefs(record.turn?.attachments);
+      else if (record.type === 'playbook_evidence') check(record.asset);
+      else if (record.type === 'player_event' || record.type === 'captain_event') {
+        const event = record.event;
+        if (event?.type === 'media' && event.payload?.source?.type === 'uri') {
+          const id = parseAssetUri(event.payload.source.uri);
+          if (id && !declared.has(id)) throw new Error(`session media asset is absent from its checkpoint inventory: ${id}`);
+        } else if (event?.type === 'tool_result' && event.payload?.output?.type === 'asset_reference') check(event.payload.output.asset);
+      }
+    }
+  };
   const validate = async (sessionId, context = {}) => {
     const manifest = await readManifest(sessionId);
     const history = await readHistory(sessionId);
@@ -790,6 +830,12 @@ export function createCaptainSessionStore(options = {}) {
         integrityValid = false;
         reasons.push('session replay contains provider continuation fields');
       }
+      try { assertAssetInventory(manifest, history.entries.filter(({ seq }) => seq <= manifest.replay.seq)); }
+      catch (cause) { integrityValid = false; reasons.push(errorMessage(cause)); }
+      for (const reference of manifest.assets?.entries ?? []) {
+        try { const reader = await assetStoreFor(sessionId).openAsset(reference); await reader.close(); }
+        catch (cause) { integrityValid = false; reasons.push(`session asset is unavailable: ${errorMessage(cause)}`); }
+      }
       if (manifest.state === 'history-only') reasons.push(manifest.reason);
       if (manifest.replay.incomplete || history.incomplete) reasons.push('session replay is incomplete');
       if (history.digests[manifest.replay.seq] !== manifest.replay.sha256) { integrityValid = false; reasons.push('session replay checkpoint digest does not match'); }
@@ -1111,6 +1157,24 @@ export function createCaptainSessionStore(options = {}) {
   };
 
   const deleteRecord = async (sessionId) => {
+    const assetsDirectory = join(sessionsDir, `${sessionId}.assets`);
+    try {
+      await assertPrivateDirectory(assetsDirectory, fs);
+      const names = await fs.readdir(assetsDirectory);
+      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; }
+      }
+      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']) {
       const path = join(sessionsDir, `${sessionId}${suffix}`);
       try { await assertPrivateRegularPath(path, 0o600, fs, 'session file'); await fs.unlink(path); await syncDirectory(sessionsDir, fs); }
@@ -1396,6 +1460,7 @@ export function createCaptainSessionStore(options = {}) {
   const acquire = async (sessionId, management = false) => {
     assertSessionId(sessionId);
     await prepareSessionPermissions(sessionsDir, fs, sessionId);
+    await assetStoreFor(sessionId).prepare();
     let stage;
     let stagePublished = false;
     try {
@@ -1451,6 +1516,7 @@ export function createCaptainSessionStore(options = {}) {
         readHistory,
         validateSession: validate,
         portableWriters,
+        assetStore: assetStoreFor(sessionId),
         writeRecord,
         syncRecordDirectory: () => syncDirectory(sessionsDir, fs),
         deleteRecord,
@@ -1684,8 +1750,39 @@ export function createCaptainSessionStore(options = {}) {
     finally { await lease.release(); }
   };
 
+  const exportBundle = async (sessionId) => {
+    assertSessionId(sessionId);
+    for (let attempt = 0; attempt < 3; attempt++) {
+      const manifestText = await readPrivateRegularFile(recordPathFor(sessionId), 0o600, fs, 'record');
+      const manifest = validateSessionManifest(JSON.parse(manifestText));
+      const replayBytes = Buffer.from(await readPrivateRegularFile(recordsPathFor(sessionId), 0o600, fs, 'replay stream'), 'utf8');
+      let end = 0;
+      for (let seq = 0; seq < manifest.replay.seq; seq++) {
+        const next = replayBytes.indexOf(10, end);
+        if (next === -1) throw new Error('session bundle is missing its checkpoint replay prefix');
+        end = next + 1;
+      }
+      const replay = replayBytes.subarray(0, end);
+      if (sha256(replay) !== manifest.replay.sha256 || manifest.replay.incomplete) throw new Error('session bundle replay checkpoint is incomplete or corrupt');
+      assertAssetInventory(manifest, parseSessionHistory(replay).entries);
+      const assets = [];
+      for (const reference of manifest.assets?.entries ?? []) {
+        const reader = await assetStoreFor(sessionId).openAsset(reference); await reader.close();
+        const hash = reference.assetId.slice(7);
+        assets.push(Object.freeze({ assetId: reference.assetId, path: hash, metadataPath: `${hash}.json`, byteLength: reference.byteLength }));
+      }
+      if (manifestText !== await readPrivateRegularFile(recordPathFor(sessionId), 0o600, fs, 'record')) continue;
+      return Object.freeze({ sessionId, manifest: Buffer.from(manifestText, 'utf8'), replay, assets: Object.freeze(assets) });
+    }
+    throw new Error('session changed while exporting its bundle; retry');
+  };
+
   return Object.freeze({
     sessionsDir,
+    readAsset: (sessionId, reference, options) => assetStoreFor(sessionId).readAsset(reference, options),
+    openAsset: (sessionId, reference, options) => assetStoreFor(sessionId).openAsset(reference, options),
+    describeAsset: (sessionId, assetId) => assetStoreFor(sessionId).describeAsset(assetId),
+    exportBundle,
     prepare,
     migrate,
     migrateLegacyDefault,
@@ -2540,6 +2637,7 @@ async function createLease({
   readHistory,
   validateSession,
   portableWriters,
+  assetStore,
   writeRecord,
   syncRecordDirectory,
   deleteRecord,
@@ -2636,7 +2734,9 @@ async function createLease({
     const seq = history.digests[durableSeq] === undefined ? previousManifest?.replay?.seq ?? 0 : durableSeq;
     const digest = history.digests[seq] ?? previousManifest?.replay?.sha256 ?? EMPTY_REPLAY_SHA256;
     const replay = { seq, sha256: digest, incomplete: previousManifest?.replay?.incomplete === true || status.incomplete || history.incomplete || history.digests[seq] === undefined };
-    const manifest = manifestFromRecovery(recovery, replay, contextSeq);
+    const entries = await assetStore.listAssets();
+    const assets = entries.length === 0 ? undefined : { version: 1, entries: await Promise.all(entries.map(({ assetId }) => assetStore.describeAsset(assetId))) };
+    const manifest = manifestFromRecovery(recovery, replay, contextSeq, assets);
     return manifest;
   };
   portableWriters.set(sessionId, { checkpoint, sync: replayWriter.checkpoint, published: (manifest) => { previousManifest = manifest; } });
@@ -2928,6 +3028,8 @@ async function createLease({
             source.effectLedger,
           );
 
+          const inheritedAssets = new Map(Object.values(retainedGenerations).flatMap((generation) => generation.frames.flatMap((frame) => frame.attachments ?? [])).map((reference) => [reference.assetId, reference]));
+          for (const reference of inheritedAssets.values()) await assetStore.copyAsset(sourceLease, reference);
           await sourceLease.assertOwner();
           await assertOwnerUnchecked();
           let sourcePublished = false;
@@ -3026,11 +3128,12 @@ async function createLease({
 
   const beginTurn = ({
     input,
+    attachments,
     attemptId,
     attemptedExecutionProjection,
   } = {}) =>
     runExclusive(async () => {
-      assertAcceptedInput(input);
+      assertAcceptedInput(input, attachments);
       assertUuid(attemptId, 'Captain session attempt id');
       const attempted = validateCaptainSessionExecutionProjection(
         attemptedExecutionProjection,
@@ -3065,6 +3168,7 @@ async function createLease({
         uncertain: {
           baseUpdatedAt: prior.updatedAt,
           input,
+          ...(attachments?.length ? { attachments: validateAssetRefs(attachments) } : {}),
           attemptId,
           attemptNumber: 1,
           markedAt: timestamp,
@@ -3119,6 +3223,7 @@ async function createLease({
           baseUpdatedAt: prior.uncertain.baseUpdatedAt,
           ...(prior.uncertain.progress === undefined ? {} : { progress: prior.uncertain.progress }),
           input: prior.uncertain.input,
+          ...(prior.uncertain.attachments === undefined ? {} : { attachments: prior.uncertain.attachments }),
           attemptId: nextAttemptId,
           attemptNumber: prior.uncertain.attemptNumber + 1,
           markedAt: timestamp,
@@ -3637,11 +3742,11 @@ async function createLease({
         if (Object.hasOwn(step, 'result') && !['completion', 'answer'].includes(step.kind)) throw new Error('A step result requires its saved start');
         progress.steps.push(step);
       } else {
-        const { result, ...start } = step;
+        const { result, workerEvidence, ...start } = step;
         const saved = progress.steps[index];
-        const { result: priorResult, ...priorStart } = saved;
+        const { result: priorResult, workerEvidence: priorEvidence, ...priorStart } = saved;
         if (!isDeepStrictEqual(start, priorStart) ||
-            (priorResult !== undefined && !isDeepStrictEqual(priorResult, result))) {
+            (priorResult !== undefined && (!isDeepStrictEqual(priorResult, result) || !isDeepStrictEqual(priorEvidence, workerEvidence)))) {
           throw new Error('A saved step cannot be replaced');
         }
         progress.steps[index] = step;
@@ -3728,6 +3833,11 @@ async function createLease({
     sessionId,
     ownerToken: owner.ownerToken,
     append,
+    importAsset: (input) => runExclusive(async () => { await assertOwnerUnchecked(); return assetStore.importAsset(input); }),
+    resolveAttachments: (references, options) => runExclusive(async () => { await assertOwnerUnchecked(); if (!Array.isArray(references)) throw new TypeError('attachments must be an array'); return Promise.all(references.map((reference) => assetStore.resolveAttachment(reference, options))); }),
+    readAsset: (reference, options) => assetStore.readAsset(reference, options),
+    openAsset: (reference, options) => assetStore.openAsset(reference, options),
+    describeAsset: (assetId) => assetStore.describeAsset(assetId),
     recordContext,
     consumeHints,
     acknowledgeHint,
@@ -4089,7 +4199,7 @@ function validateCanonicalCaptainSessionRecord(
     exactOptionalKeys(
       uncertain,
       UNCERTAIN_KEYS,
-      ['abandonment', 'progress'],
+      ['abandonment', 'progress', 'attachments'],
       'Captain session record uncertain',
     );
     if (uncertain.baseUpdatedAt !== null) {
@@ -4110,7 +4220,7 @@ function validateCanonicalCaptainSessionRecord(
         );
       }
     }
-    assertAcceptedInput(uncertain.input);
+    assertAcceptedInput(uncertain.input, uncertain.attachments);
     assertUuid(uncertain.attemptId, 'Captain session attempt id');
     if (
       !Number.isSafeInteger(uncertain.attemptNumber) ||
@@ -4172,8 +4282,9 @@ function validateCanonicalCaptainSessionRecord(
       exactOptionalKeys(progress, ['snapshot', 'steps'], ['positionStepId'], 'Captain progress');
       if (!Array.isArray(progress.steps)) throw new Error('Captain steps must be an array');
       const ids = new Set();
+      const workerBoundaryIds = new Set();
       for (const step of progress.steps) {
-        exactOptionalKeys(requireRecord(step, 'Captain step'), ['id', 'kind', 'stateId', 'runtimeSessionId', 'playbookId'], ['result'], 'Captain step');
+        exactOptionalKeys(requireRecord(step, 'Captain step'), ['id', 'kind', 'stateId', 'runtimeSessionId', 'playbookId'], ['result', 'workerEvidence'], 'Captain step');
         assertUuid(step.id, 'Captain step id');
         assertUuid(step.runtimeSessionId, 'Captain step runtime');
         if (ids.has(step.id)) throw new Error('Captain step ids must be unique');
@@ -4209,6 +4320,22 @@ function validateCanonicalCaptainSessionRecord(
         }
         requireCanonicalNonblank(step.stateId, 'Captain step state');
         if (!Object.hasOwn(structural.catalog, step.playbookId)) throw new Error('Captain step names an unknown playbook');
+        if (step.workerEvidence !== undefined) {
+          const evidence = requireRecord(step.workerEvidence, 'Worker evidence');
+          exactOptionalKeys(evidence, ['boundaryId', 'playerId'], [], 'Worker evidence');
+          assertUuid(evidence.boundaryId, 'Worker evidence boundary');
+          requireCanonicalNonblank(evidence.playerId, 'Worker evidence player');
+          const boundary = record.effectLedger.boundaries.find((entry) => entry.boundaryId === evidence.boundaryId);
+          if (step.kind !== 'player' || !step.result || typeof step.result !== 'object' || Array.isArray(step.result) ||
+              !boundary || boundary.playbookId !== step.playbookId || boundary.sourceStateId !== step.stateId ||
+              workerBoundaryIds.has(evidence.boundaryId) || isDeepStrictEqual(boundary, record.snapshot.effectLedger.boundaries[boundary.sequence - 1]) ||
+              !boundary.physicalReceipt || !boundary.finalText?.trim() ||
+              boundary.semanticCandidate?.guard !== step.result.guard || typeof step.result.guard !== 'string' || step.result.guard === 'needsBossReply' ||
+              structural.catalog[step.playbookId]?.roles?.[boundary.roleId]?.playerId !== evidence.playerId) {
+            throw new Error('Worker evidence must name its accepted player boundary');
+          }
+          workerBoundaryIds.add(evidence.boundaryId);
+        }
       }
       if (progress.positionStepId !== undefined && progress.positionStepId !== null && !ids.has(progress.positionStepId)) throw new Error('Captain progress positionStepId must name a recorded step');
       if (progress.snapshot === null && progress.positionStepId != null) throw new Error('Captain progress positionStepId requires a saved position');
@@ -5312,7 +5439,7 @@ function assertReleasedSchema2CaptainSessionRecord(record) {
       );
     }
   }
-  assertAcceptedInput(uncertain.input);
+  assertAcceptedInput(uncertain.input, uncertain.attachments);
   assertUuid(uncertain.attemptId, 'Captain session attempt id');
   if (
     !Number.isSafeInteger(uncertain.attemptNumber) ||
@@ -5408,6 +5535,7 @@ function validateCaptainSessionProjection(
             'fastMode',
             'subagentModel',
             'subagentEffort',
+            'browser',
           ],
       playerPath,
     );
@@ -5578,6 +5706,7 @@ function validateProjectedAgent(value, path, { structural, hasId = false }) {
   const agent = requireRecord(value, path);
   if (!structural) {
     validateProjectedFastMode(agent, `${path}.fastMode`);
+    if (agent.browser !== undefined && typeof agent.browser !== 'boolean') throw new Error(`${path}.browser must be a boolean`);
     validateProjectedSubagentTuning(agent, path);
   }
   if (!hasId) {
@@ -5592,6 +5721,7 @@ function validateProjectedAgent(value, path, { structural, hasId = false }) {
             'fastMode',
             'subagentModel',
             'subagentEffort',
+            'browser',
           ],
       path,
     );
@@ -6144,9 +6274,10 @@ function validateRetainedGenerationFrame(
       'roleBindings',
       'runtime',
     ],
-    ['parentSessionId', 'parentCallId', 'request', 'inputs'],
+    ['parentSessionId', 'parentCallId', 'request', 'inputs', 'attachments'],
     path,
   );
+  if (frame.attachments !== undefined) validateAssetRefs(frame.attachments);
   if (frame.request !== undefined) {
     if (index !== 0) throw new Error(`${path}.request belongs only to the root`);
     requireNonblank(frame.request, `${path}.request`);
@@ -6369,8 +6500,9 @@ async function requireUncertainRecord(record, attemptId) {
   return record;
 }
 
-function assertAcceptedInput(value) {
-  if (typeof value !== 'string' || value.trim().length === 0) {
+function assertAcceptedInput(value, attachments) {
+  if (attachments !== undefined) validateAssetRefs(attachments);
+  if (typeof value !== 'string' || (value.trim().length === 0 && !attachments?.length)) {
     throw new Error('Captain session input must be a non-empty string');
   }
 }

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: [