@sublang/playbook 10.0.0 → 12.0.0

package/reference/sdlc/code.md

@@ -8,35 +8,44 @@ Roles:
 
 - Coder
 
-The caller supplies the coding intent including any specific context.
+The caller supplies a coding request together with any relevant context.
 
-A coding intent follows either one direct implementation phase or an IR sequence consisting of a new-IR phase and one phase for each IR task.
+A new coding intent follows either one direct implementation phase or an IR sequence consisting of a new-IR phase followed by one phase for each IR task.
+An existing IR follows one IR-task phase for each remaining unfinished task, starting with its next unfinished task.
 Each phase ends with one new Coder commit (owned by `code`).
 After each `code`-owned commit, Captain shall call the `review` playbook and wait until it passes with no unsettled findings.
 Playbook `review` owns every review round and every review-fix commit.
-Do not amend any reviewed commit.
+Do not rewrite any existing commit.
 
 When `review` passes a direct implementation phase, `code` is complete.
 When `review` passes a new IR or a nonfinal IR-task phase, Captain shall continue with the next unfinished IR-task phase.
 When `review` passes the final IR-task phase, `code` is complete.
-When `review` returns an authored abort or failure, or a terminal result that does not prove exact approval, `code` shall start no further phase and shall report the failure and the last `code`-owned commit to its caller.
+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` shall start no further phase and shall report the failure and the last `code`-owned commit to its caller.
 When the nested `review` call fails outside that authored result contract, `code` shall park as failed and retain the control-plane error instead of reporting an authored review outcome.
 
 At the start of the first phase, Captain shall relay to Coder the complete caller input and any relevant run results in quotes (`>`), along with the following instruction:
 
 ```markdown
-Assess whether the coding intent can be completed well in one commit.
-If yes, implement and test it, update the affected specs, and ensure @specs/map.md remains accurate.
-Otherwise, decompose it into tasks sized to exactly one commit each, add a new IR under @specs/intents, and do not implement any IR task in this phase.
+First determine whether the coding request starts a new coding intent or continues an existing IR with unfinished work.
+If the request may continue an existing IR but does not identify it unambiguously, ask Boss before changing files.
+
+For a new coding intent, assess whether it can be completed well in one commit.
+If it can, implement and test it, update the affected specs, and ensure @specs/map.md remains accurate.
+If it cannot, decompose it into tasks sized to exactly one commit each, add a new IR under @specs/intents, and do not implement any IR task in this phase.
 Plan affected spec updates before, with, or after their corresponding code changes, either as standalone IR tasks or as explicit work within related tasks.
 
+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.
+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.
 ```
 
-At the start of every IR-task phase, Captain shall relay to Coder the exact next task and any relevant run results in quotes (`>`), along with the following instruction:
+At the start of every later IR-task phase, Captain shall relay to Coder the original caller input, the IR identity, and any relevant run results in quotes (`>`), along with the following instruction:
 
 ```markdown
-Read IR-<#> and implement exactly the next unfinished task, including corresponding tests or specs if any.
+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.
 If the IR will be finished after this phase, double-check that all acceptance criteria are met.
@@ -45,18 +54,29 @@ If the IR will be finished after this phase, double-check that all acceptance cr
 At the start of *every* phase, Captain shall append the following instruction:
 
 ```markdown
+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.
 Make the commit message explain concisely what changed and why, including relevant verification.
-Coder is <coder-llm>; format the model token in conventional human form.
+Identify every new commit you make.
+Coder is <coder-llm>.
 ```
 
-After the first phase (either direct implementation or a new-IR phase), Captain shall call playbook `review` and input the following in quotes (`>`):
+Every new-intent phase has two semantic outcomes: direct implementation and new IR; the new-IR outcome identifies the created IR.
+Every IR-task phase, including the first phase for an existing IR, identifies the IR and the implemented task, and has two semantic outcomes: more tasks and final task.
+The first phase therefore has four semantic outcomes — direct implementation, new IR, more tasks, and final task — plus the Boss question when the continued IR is ambiguous.
+Each semantic outcome requires affirmative support in Coder's result, but no phase transition shall depend on a fixed presentation format of Coder's reply.
+Captain shall use the repository-effect receipt as the authoritative identity of the phase's new commit.
+
+At the end of every phase, Captain shall call playbook `review` and input the following in quotes (`>`):
 
-> Initial intent: \<caller-input\>
+> Original intent: \<caller-input\>
+> Review scope: the commit \<code-commit\> from this coding phase and its resulting repository state.
 > Coder output: \<coder-output\>
 
-After every IR-task phase, Captain shall call playbook `review` and input the following in quotes (`>`):
+For an IR-task phase, Captain shall additionally input the following in quotes (`>`):
 
-> IR task: \<ir-task\>
-> Coder output: \<coder-output\>
+> 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 successful completion, `code` returns 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.

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

@@ -35,6 +35,10 @@ import {
   validateFrozenExecutionConfig,
 } from './run.js';
 import { prepareConfiguredRegistries } from './provision.js';
+import {
+  createReplayRecordObserver,
+  replayIncompleteMessage,
+} from './replay-observer.js';
 import {
   assertCaptainSessionExecutionCompatible,
   createCaptainSessionStore,
@@ -86,10 +90,7 @@ export function validateManagedInteractivePayload(value) {
   }
   assertUuid(value.sessionId, 'managed interactive session id');
   assertCanonicalAbsolutePath(value.cwd, 'managed interactive working directory');
-  assertCanonicalAbsolutePath(
-    value.sessionsDir,
-    'managed interactive sessions directory',
-  );
+  assertAbsolutePath(value.sessionsDir, 'managed interactive sessions directory');
   if (typeof value.noProvision !== 'boolean') {
     throw new Error('managed interactive noProvision must be a boolean');
   }
@@ -317,11 +318,19 @@ export function createManagedInteractiveLifecycle(payloadValue, options = {}) {
   let activeTurn;
   let executionProjection;
   let freshLaunchRecord;
+  let replayChannel;
 
   const release = async () => {
     if (released || lease === undefined) return;
     const owned = lease;
-    await owned.release();
+    let status;
+    try {
+      status = await owned.release();
+    } catch (error) {
+      await replayChannel?.reportIfIncomplete();
+      throw error;
+    }
+    await replayChannel?.reportIfIncomplete(status);
     if (lease === owned) lease = undefined;
     released = true;
   };
@@ -369,6 +378,11 @@ export function createManagedInteractiveLifecycle(payloadValue, options = {}) {
       let host;
       try {
         lease = await store.acquire(payload.sessionId);
+        replayChannel = createManagedReplayChannel({
+          lease,
+          sessionId: payload.sessionId,
+          presentationGate: context.observers[0],
+        });
         const authoritative =
           typeof lease.recoverUnresolvedEffectAbandonment === 'function'
             ? await lease.recoverUnresolvedEffectAbandonment()
@@ -435,7 +449,12 @@ export function createManagedInteractiveLifecycle(payloadValue, options = {}) {
           cwd: payload.cwd,
           sessionLease: lease,
           loadModule,
-          observers: context.observers,
+          observers: [
+            ...context.observers,
+            ...(replayChannel === undefined
+              ? []
+              : [replayChannel.observer]),
+          ],
           ...(options.adapterImports
             ? { adapterImports: options.adapterImports }
             : {}),
@@ -491,6 +510,7 @@ export function createManagedInteractiveLifecycle(payloadValue, options = {}) {
           retainedGenerations,
           reconcileRepositoryEffects: created.reconcileRepositoryEffects,
         });
+        await replayChannel?.reportIfIncomplete();
         initialized = true;
         return {
           abortActiveTurn: (...args) => host.abortActiveTurn(...args),
@@ -600,6 +620,7 @@ export function createManagedInteractiveLifecycle(payloadValue, options = {}) {
         unresolvedEffects: settlement.unresolvedEffects,
         retentionUpdates: settlement.retentionUpdates,
       });
+      await replayChannel?.reportIfIncomplete();
       activeTurn = undefined;
     },
 
@@ -631,6 +652,31 @@ export function createManagedInteractiveLifecycle(payloadValue, options = {}) {
   });
 }
 
+function createManagedReplayChannel({
+  lease,
+  sessionId,
+  presentationGate,
+}) {
+  if (
+    typeof lease?.append !== 'function' ||
+    typeof lease?.streamStatus !== 'function'
+  ) {
+    return undefined;
+  }
+  return createReplayRecordObserver({
+    lease,
+    async onIncomplete() {
+      if (typeof presentationGate?.onRecord !== 'function') return;
+      await presentationGate.onRecord({
+        type: 'captain_status',
+        turnId: null,
+        timestamp: Date.now(),
+        message: replayIncompleteMessage(sessionId),
+      });
+    },
+  });
+}
+
 async function writeManagedInteractiveReadinessClaim({
   workDir,
   sessionId,
@@ -912,6 +958,12 @@ function assertCanonicalAbsolutePath(value, path) {
   }
 }
 
+function assertAbsolutePath(value, path) {
+  if (typeof value !== 'string' || !isAbsolute(value)) {
+    throw new Error(`${path} must be an absolute path`);
+  }
+}
+
 function assertManagedDescriptorPath(path) {
   if (basename(path) !== MANAGED_INTERACTIVE_PAYLOAD_FILE) {
     throw new Error(