@sublang/playbook 9.0.0 → 11.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,19 +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.
-Report it as exactly one final-response line beginning `Commit: `, followed only by the exact commit identity.
-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

@@ -8,7 +8,7 @@
 
 import { randomUUID } from 'node:crypto';
 import { constants, realpathSync } from 'node:fs';
-import { lstat, open, readFile, realpath, unlink } from 'node:fs/promises';
+import { lstat, open, realpath, unlink } from 'node:fs/promises';
 import {
   basename,
   dirname,
@@ -30,9 +30,15 @@ import {
   CaptainSessionHostCleanupError,
   captainOptionsFromConfig,
   createCaptainSessionHost,
+  installRetainedGenerationsForLaunch,
+  reportSkippedCaptainSession,
   validateFrozenExecutionConfig,
 } from './run.js';
 import { prepareConfiguredRegistries } from './provision.js';
+import {
+  createReplayRecordObserver,
+  replayIncompleteMessage,
+} from './replay-observer.js';
 import {
   assertCaptainSessionExecutionCompatible,
   createCaptainSessionStore,
@@ -47,6 +53,8 @@ export const MANAGED_INTERACTIVE_PAYLOAD_FILE =
 export const MANAGED_INTERACTIVE_PAYLOAD_SCHEMA_VERSION = 1;
 export const MANAGED_INTERACTIVE_PAYLOAD_KIND =
   'playbook-managed-interactive-launch';
+export const MANAGED_INTERACTIVE_READINESS_WITNESS_FILE =
+  'playbook-managed-readiness';
 
 const PAYLOAD_KEYS = [
   'schemaVersion',
@@ -82,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');
   }
@@ -156,6 +161,18 @@ export async function writeManagedInteractivePayload(workDir, value) {
   return path;
 }
 
+export async function publishManagedInteractiveReadinessWitness(
+  workDir,
+  sessionId,
+) {
+  return writeManagedInteractiveReadinessClaim({
+    workDir,
+    sessionId,
+    claim: 'ready',
+    rejectExisting: true,
+  });
+}
+
 export async function readManagedInteractivePayload(path) {
   assertCanonicalAbsolutePath(path, 'managed interactive launch descriptor');
   assertManagedDescriptorPath(path);
@@ -300,15 +317,48 @@ export function createManagedInteractiveLifecycle(payloadValue, options = {}) {
   let leaseQuarantined = false;
   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;
   };
 
+  const abandonFreshLaunchRecord = async ({ claim = false } = {}) => {
+    const record = freshLaunchRecord;
+    if (
+      record === undefined ||
+      lease === undefined ||
+      Object.keys(record.retainedGenerations ?? {}).length !== 0
+    ) {
+      return;
+    }
+    if (
+      claim &&
+      !(await writeManagedInteractiveReadinessClaim({
+        workDir: payload.workDir,
+        sessionId: payload.sessionId,
+        claim: 'abandon',
+        rejectExisting: false,
+      }))
+    ) {
+      return;
+    }
+    freshLaunchRecord = undefined;
+    await lease.abandonFreshSettled({ expected: record });
+  };
+
   return Object.freeze({
     async initializeRuntime(context) {
       if (initialized || lease !== undefined || released) {
@@ -328,7 +378,16 @@ export function createManagedInteractiveLifecycle(payloadValue, options = {}) {
       let host;
       try {
         lease = await store.acquire(payload.sessionId);
-        const authoritative = await lease.read();
+        replayChannel = createManagedReplayChannel({
+          lease,
+          sessionId: payload.sessionId,
+          presentationGate: context.observers[0],
+        });
+        const authoritative =
+          typeof lease.recoverUnresolvedEffectAbandonment === 'function'
+            ? await lease.recoverUnresolvedEffectAbandonment()
+            : await lease.read();
+        let retainedGenerations = {};
         let restoreSnapshot;
         const prepareRegistryModule =
           options.prepareRegistryModule ??
@@ -381,14 +440,21 @@ export function createManagedInteractiveLifecycle(payloadValue, options = {}) {
             { loadModule, prepareRegistryModule },
           );
           restoreSnapshot = record.snapshot;
+          retainedGenerations = record.retainedGenerations ?? {};
         }
 
         const created = await createSessionHost({
           config: executionProjection,
           sessionId: payload.sessionId,
           cwd: payload.cwd,
+          sessionLease: lease,
           loadModule,
-          observers: context.observers,
+          observers: [
+            ...context.observers,
+            ...(replayChannel === undefined
+              ? []
+              : [replayChannel.observer]),
+          ],
           ...(options.adapterImports
             ? { adapterImports: options.adapterImports }
             : {}),
@@ -401,18 +467,50 @@ export function createManagedInteractiveLifecycle(payloadValue, options = {}) {
           ...(options.createHostRuntime
             ? { createHostRuntime: options.createHostRuntime }
             : {}),
+          ...(options.createEffectLedgerWriteAhead
+            ? {
+                createEffectLedgerWriteAhead:
+                  options.createEffectLedgerWriteAhead,
+              }
+            : {}),
           ...(restoreSnapshot !== undefined ? { restoreSnapshot } : {}),
         });
         ({ host, shell } = created);
-        if (payload.mode === 'fresh') {
-          await lease.initializeSettled({
-            cwd: payload.cwd,
-            structuralProjection:
-              projectCaptainSessionStructure(executionProjection),
-            executionProjection,
-            snapshot: created.snapshot,
-          });
-        }
+        await installRetainedGenerationsForLaunch({
+          lease,
+          shell,
+          ...(payload.mode === 'fresh'
+            ? {
+                freshBoundary: {
+                  cwd: payload.cwd,
+                  structuralProjection:
+                    projectCaptainSessionStructure(executionProjection),
+                  executionProjection,
+                  snapshot: created.snapshot,
+                },
+                onFreshRecord(record) {
+                  freshLaunchRecord = record;
+                },
+                onLegacyRecord: (record) =>
+                  reportSkippedCaptainSession(
+                    options.stderr ?? process.stderr,
+                    'playbook',
+                    'legacy',
+                    record,
+                  ),
+                onInvalidRecord: (record) =>
+                  reportSkippedCaptainSession(
+                    options.stderr ?? process.stderr,
+                    'playbook',
+                    'invalid',
+                    record,
+                  ),
+              }
+            : {}),
+          retainedGenerations,
+          reconcileRepositoryEffects: created.reconcileRepositoryEffects,
+        });
+        await replayChannel?.reportIfIncomplete();
         initialized = true;
         return {
           abortActiveTurn: (...args) => host.abortActiveTurn(...args),
@@ -445,6 +543,13 @@ export function createManagedInteractiveLifecycle(payloadValue, options = {}) {
             failures.push(disposeError);
           }
         }
+        if (!leaseQuarantined) {
+          try {
+            await abandonFreshLaunchRecord();
+          } catch (abandonmentError) {
+            failures.push(abandonmentError);
+          }
+        }
         shell = undefined;
         if (!leaseQuarantined) {
           try {
@@ -503,25 +608,119 @@ export function createManagedInteractiveLifecycle(payloadValue, options = {}) {
           `managed interactive Captain turn produced ${replies.length} usable Boss-visible replies; expected exactly one`,
         );
       }
-      const snapshot = shell?.exportSnapshot();
-      if (snapshot === undefined) {
+      const settlement = shell?.exportSettlement();
+      if (settlement === undefined) {
         throw new Error(
-          'managed interactive Captain turn settled without an exportable session snapshot',
+          'managed interactive Captain turn settled without an exportable session settlement',
         );
       }
-      await lease.settle({ attemptId: activeTurn.attemptId, snapshot });
+      await lease.settle({
+        attemptId: activeTurn.attemptId,
+        snapshot: settlement.snapshot,
+        unresolvedEffects: settlement.unresolvedEffects,
+        retentionUpdates: settlement.retentionUpdates,
+      });
+      await replayChannel?.reportIfIncomplete();
       activeTurn = undefined;
     },
 
-    async shutdown() {
+    async shutdown(context) {
       // Cligent invokes lifecycle shutdown only after runtime disposal and the
       // complete turn transaction, so ownership retirement cannot race either.
       if (leaseQuarantined) return;
-      await release();
+      const failures = [];
+      if (context !== undefined) {
+        try {
+          await abandonFreshLaunchRecord({ claim: true });
+        } catch (error) {
+          failures.push(error);
+        }
+      }
+      try {
+        await release();
+      } catch (error) {
+        failures.push(error);
+      }
+      if (failures.length === 1) throw failures[0];
+      if (failures.length > 1) {
+        throw new AggregateError(
+          failures,
+          'managed interactive shutdown could not retract its unused fresh session and retire its lease',
+        );
+      }
     },
   });
 }
 
+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,
+  claim,
+  rejectExisting,
+}) {
+  assertCanonicalAbsolutePath(
+    workDir,
+    'managed interactive readiness work directory',
+  );
+  assertUuid(sessionId, 'managed interactive readiness session id');
+  const path = join(workDir, MANAGED_INTERACTIVE_READINESS_WITNESS_FILE);
+  let handle;
+  try {
+    handle = await open(path, 'wx', 0o600);
+  } catch (cause) {
+    if (cause?.code === 'EEXIST' && !rejectExisting) return false;
+    throw new Error(
+      `managed interactive readiness claim could not be created: ${message(cause)}`,
+      { cause },
+    );
+  }
+  try {
+    await handle.chmod(0o600);
+    const stat = await handle.stat();
+    if (!stat.isFile() || (stat.mode & 0o7777) !== 0o600) {
+      throw new Error(
+        'managed interactive readiness claim is not a private regular file',
+      );
+    }
+    if (
+      typeof process.getuid === 'function' &&
+      stat.uid !== process.getuid()
+    ) {
+      throw new Error('managed interactive readiness claim has a foreign owner');
+    }
+    await handle.writeFile(`${claim} ${sessionId}\n`, 'utf8');
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  return true;
+}
+
 export function parseManagedInteractiveChildArgs(argv) {
   if (argv.length !== 1) {
     throw new Error(
@@ -759,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(