@sublang/playbook 13.3.0 → 14.1.0

package/README.md

@@ -32,9 +32,10 @@ Run `playbook` for an interactive tmux UI powered by [cligent](https://github.co
 Out of the box, Playbook includes **CODE** for implementation, **REVIEW** for commit-based review and fixes, **DECIDE** for independently proposed and reviewed specification decisions, **DEV** for repository-aware planning of a development request, **BRANCH** for checking out a new branch for a GitHub issue, and **PR** for publishing, checking, and merging that branch through a pull request.
 CODE and DECIDE call REVIEW as a nested playbook; DEV calls CODE, or DECIDE and then CODE, and wraps them in BRANCH and PR when the request names a GitHub issue or asks for a pull request.
 
-The shared starter config uses Claude as both Captain and the `dev.coder`
-player, and Codex as `dev.reviewer`. CODE, REVIEW, DECIDE, BRANCH, and PR bind
-their local roles explicitly to those two stable players, so nested and later
+The shared starter config selects one adapter for the Captain and all players
+from locally visible credentials: Claude first, then Codex. If neither is
+configured, it seeds Claude and prints a notice. CODE, REVIEW, DECIDE, BRANCH, and PR bind
+their local roles explicitly to `dev.coder` and `dev.reviewer`, so nested and later
 engagements share a conversation only where their bindings name the same
 player ID; DEV's Analyst binds a distinct `dev.analyst` player.
 
@@ -49,8 +50,7 @@ If an SDK is missing or older than cligent supports, Playbook prints the pinned
 Prerequisites:
 
 - Node.js >= 20.6.0
-- Authenticated [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) or `ANTHROPIC_API_KEY`
-- Authenticated [Codex CLI](https://github.com/openai/codex) or `OPENAI_API_KEY`
+- Credentials for the configured adapter: authenticated [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) or `ANTHROPIC_API_KEY` for Claude; authenticated [Codex CLI](https://github.com/openai/codex) or `OPENAI_API_KEY` for Codex
 - [GitHub CLI](https://cli.github.com/) (`gh`) authenticated for the repository's GitHub remote, for `/branch`, `/pr`, and `/dev` requests that name an issue or ask for a pull request
 
 Interactive `playbook` additionally needs tmux 3.3 or newer and [`glow`](https://github.com/charmbracelet/glow#installation) on `PATH`; headless `playbook run` does not.

package/docs/cli.md

@@ -124,20 +124,20 @@ untouched
 The current CODE, REVIEW, DECIDE, DEV, BRANCH, and PR workflows take their
 deterministic initial event from the selecting Boss turn. CODE and DECIDE then
 call REVIEW as a nested playbook, while DEV — the repository-aware planner
-behind `/dev` — analyzes a development request and itself calls CODE, or
-DECIDE and then CODE, as nested playbooks. When the request names a GitHub
-issue or asks for pull-request delivery, DEV reads the issue and its comments
-while planning, calls BRANCH before that path and PR after CODE succeeds, and
-ends with a merged pull request and a closed issue — or with a named failure
-that leaves the pull request open for a later `/pr`. Both are usable on their
-own: `/branch <issue or request>` creates and checks out `issue-N-slug` (or a
-request slug) at the current commit, changing nothing else; `/pr` pushes the
-checked-out branch, opens or reuses its pull request against the default
-branch, waits for the checks, fixes red checks through one nested CODE call,
-merges with a merge commit, and fast-forwards the local default branch. A
-repository without checks merges on CODE's nested review alone. BRANCH, PR,
-and issue-aware DEV planning require the GitHub CLI `gh`, authenticated for
-the repository's GitHub remote
+behind `/dev` — chooses the development path for a request and itself calls
+CODE, or DECIDE and then CODE, as nested playbooks. When the request names a
+GitHub issue or asks for pull-request delivery, DEV reads the issue and its
+comments while planning, calls BRANCH before that path and PR after CODE
+succeeds, and ends with a merged pull request and a closed issue — or with a
+named failure that leaves the pull request open for a later `/pr`. Both are
+usable on their own: `/branch <issue or request>` creates and checks out
+`issue-N-slug` (or a request slug) at the current commit, changing nothing
+else; `/pr` pushes the checked-out branch, opens or reuses its pull request
+against the default branch, waits for the checks, fixes red checks through one
+nested CODE call, merges with a merge commit, and fast-forwards the local
+default branch. A repository without checks merges on CODE's nested review
+alone. BRANCH, PR, and issue-aware DEV planning require the GitHub CLI `gh`,
+authenticated for the repository's GitHub remote
 ([DR-050](https://github.com/sublang-ai/playbook/blob/main/specs/decisions/050-pull-request-delivery.md)).
 Local role names do not imply continuity: each frame
 uses the exact stable player IDs configured under its `roles` map. Equal IDs

package/docs/configuration.md

@@ -55,8 +55,16 @@ key is that playbook's option slice. Every manifest role must be present
 exactly once. The launcher injects the rest — you do not write host wiring by
 hand.
 
-The seeded config runs every stable player on Claude Opus 5 — the Coder at
-`high` effort, the Reviewer and Analyst at `xhigh`:
+The launcher seeds one adapter for the Captain and all stable players from
+locally visible credentials: Claude first, then Codex. It uses Claude Opus 5
+for Claude or GPT-5.6 Sol for Codex, with Captain and Coder at `high` effort
+and Reviewer and Analyst at `xhigh`. If neither adapter is configured, it
+seeds Claude and prints a notice. Credentials do not prove SDK availability
+or remaining quota; launch still checks the configured adapter. Existing
+configs are left unchanged.
+
+The Claude default is shown below. A Codex seed also adds
+`permissions.writablePaths: ['.git']` to each agent:
 
 ```yaml
 captain:

package/docs/embedding.md

@@ -433,7 +433,7 @@ defines the files, versions and compatibility rules.
 
 ## Reading the published spec contracts
 
-The authored compiler-phase specs ship in the package and are exposed
+The compiler definitions and supporting assets ship in the package and are exposed
 as a public, semver-stable surface under `@sublang/playbook/slc/*`.
 Resolve and read one with `import.meta.resolve` plus `fs`:
 
@@ -450,3 +450,22 @@ The four specs are [`slc/text2gears.md`](../slc/text2gears.md),
 [`slc/link.md`](../slc/link.md) — the FSM-to-runtime contract that
 `@sublang/playbook/runtime` projects into TypeScript — and
 [`slc/optimize.md`](../slc/optimize.md).
+
+Five supporting assets use the same resolution mechanism:
+
+| Asset | Purpose |
+| --- | --- |
+| [`slc/workflow-contracts.json`](../slc/workflow-contracts.json) | Public output schemas and default literal target bindings for the builtin REVIEW, DECIDE, CODE, BRANCH, and PR workflows; compilers and embedders can read them without importing workflow implementations. |
+| [`slc/materialize-link.mjs`](../slc/materialize-link.mjs) | Optional CLI that emits a thin linked module from a supported FSM and JSON descriptor; see the profiles and invocation in `slc/link.md`. |
+| [`slc/scaffold-fsm.mjs`](../slc/scaffold-fsm.mjs) | Optional CLI that initializes an incomplete typed FSM from supported GEARS source. |
+| [`slc/experiments/fsm-scaffold-guidance.md`](../slc/experiments/fsm-scaffold-guidance.md) | Opt-in compiler guidance for the initializer, outside ordinary phase discovery. |
+| [`slc/slc.pin-inputs.json`](../slc/slc.pin-inputs.json) | SLC semantic-input closures for `gears2fsm` and `link`, including the workflow catalog and, for `link`, the materializer. Other phases use SLC's inline-input discovery. |
+
+For example, resolve `@sublang/playbook/slc/workflow-contracts.json`, read it
+with `readFile`, and parse the result as JSON to inspect the published workflow
+interfaces. Execute the `.mjs` helpers with Node and their documented CLI
+arguments: their supported public interfaces are their resolvable paths and CLI
+contracts. Their JavaScript module exports are internal implementation details
+and carry no SemVer compatibility guarantee.
+The initializer requires further semantic compilation and verification
+before its output is runnable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "13.3.0",
+  "version": "14.1.0",
   "type": "module",
   "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, REVIEW, DECIDE, DEV, BRANCH, and PR workflows driven by GEARS specs.",
   "license": "Apache-2.0",
@@ -38,6 +38,11 @@
     "src/xstate-playbook-runtime.js",
     "src/xstate-playbook-runtime.d.ts",
     "slc/link.md",
+    "slc/materialize-link.mjs",
+    "slc/scaffold-fsm.mjs",
+    "slc/experiments/fsm-scaffold-guidance.md",
+    "slc/slc.pin-inputs.json",
+    "slc/workflow-contracts.json",
     "slc/gears2fsm.md",
     "slc/text2gears.md",
     "slc/optimize.md",

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

@@ -131,7 +131,7 @@ export declare const branchMachine: import("xstate").StateMachine<BranchContext,
 } | {
     type: "resumesCreateBranch";
     params: unknown;
-}, never, "failed" | "awaitBossReply" | "ready" | "refused" | "createBranch" | "branched", string, Readonly<Record<string, never>>, {
+}, never, "failed" | "ready" | "awaitBossReply" | "refused" | "createBranch" | "branched", string, Readonly<Record<string, never>>, {
     readonly status: "branched";
     /** Exact name of the new branch now checked out. */
     readonly branch: string;

package/reference/sdlc/code.playbook/bin/launch-config.js

@@ -180,7 +180,7 @@ export function resolveLaunchSessionsDir({
   if (sessionsDir !== undefined) return sessionsDir;
 
   if (preparePrimary) {
-    seedUserConfigIfMissing(userConfigPath, templatePath, onNotice);
+    seedUserConfigIfMissing(userConfigPath, templatePath, onNotice, env, homeDir);
     migrateUserConfigIfRetired(userConfigPath, onNotice);
   }
 
@@ -248,8 +248,10 @@ export async function loadLaunchPlan({
   templatePath = DEFAULT_TEMPLATE_PATH,
   onNotice = () => {},
   selectedMembers,
+  env = process.env,
+  homeDir = env.HOME ?? homedir(),
 }) {
-  seedUserConfigIfMissing(userConfigPath, templatePath, onNotice);
+  seedUserConfigIfMissing(userConfigPath, templatePath, onNotice, env, homeDir);
   // PBCLI-22/46: a reopen must not rewrite, validate, or otherwise inspect
   // config members outside the stored projection.
   if (selectedMembers === undefined) {
@@ -288,10 +290,12 @@ export async function loadSelectedLaunchPlanDataOnly({
   structuralProjection,
   templatePath = DEFAULT_TEMPLATE_PATH,
   onNotice = () => {},
+  env = process.env,
+  homeDir = env.HOME ?? homedir(),
 }) {
   const stored = validateStoredStructuralProjection(structuralProjection);
   const selectedMembers = selectedMembersFromStoredStructure(stored);
-  seedUserConfigIfMissing(userConfigPath, templatePath, onNotice);
+  seedUserConfigIfMissing(userConfigPath, templatePath, onNotice, env, homeDir);
 
   let top = parseYaml(readFileSync(userConfigPath, "utf8")) ?? {};
   if (overlayPaths.length > 0 && !isObject(top)) {
@@ -1335,11 +1339,90 @@ function assertLegacyRelocationLocatorsSafe(
   );
 }
 
-function seedUserConfigIfMissing(userConfigPath, templatePath, onNotice) {
+// PBCLI-11 / DR-053: the adapters a seeded lineup may take, highest
+// precedence first. A fixed order — not whichever the probe answers
+// first — is what makes one machine seed one file twice.
+const SEED_LINEUP = Object.freeze([
+  Object.freeze({ adapter: "claude", model: "claude-opus-5" }),
+  Object.freeze({ adapter: "codex", model: "gpt-5.6-sol" }),
+]);
+
+/**
+ * PBCLI-11: the lineup a seed would write here, and whether anything
+ * actually probed ready.
+ *
+ * Only the credential check participates. The SDK probe constructs an
+ * adapter and awaits `isAvailable()`, which reads whatever happens to
+ * be installed and spawns a subprocess for CLI-backed adapters: a seed
+ * consulting it would differ between a developer's machine and a clean
+ * one, and would make creating a file asynchronous.
+ */
+export function selectSeedLineup(env = process.env, home = homedir()) {
+  const ready = SEED_LINEUP.filter(
+    (entry) =>
+      checkReadiness([entry.adapter], env, home).failingAdapters.length === 0,
+  );
+  return { lineup: ready[0] ?? SEED_LINEUP[0], anyReady: ready.length > 0 };
+}
+
+/**
+ * The template is the documented default and the only source of the
+ * starter's structure and comments, so the default choice is still the
+ * byte copy it always was. A different adapter rewrites the agent
+ * scalars in place, which the Document API carries comments through.
+ */
+function seedTextForLineup(templatePath, lineup) {
+  const template = readFileSync(templatePath, "utf8");
+  if (lineup.adapter === SEED_LINEUP[0].adapter) return template;
+  const doc = parseYamlDocument(template);
+  const players = doc.getIn(["players"]);
+  const agentPaths = [
+    ["captain"],
+    ...[...(players?.items ?? [])].map((pair) => [
+      "players",
+      String(pair.key),
+    ]),
+  ];
+  for (const path of agentPaths) {
+    doc.setIn([...path, "adapter"], lineup.adapter);
+    doc.setIn([...path, "model"], lineup.model);
+    // A codex agent writes git metadata under its sandbox; claude's
+    // auto mode needs no grant, so the key exists for one adapter only.
+    if (lineup.adapter === "codex") {
+      doc.setIn([...path, "permissions", "writablePaths"], [".git"]);
+    } else {
+      doc.deleteIn([...path, "permissions", "writablePaths"]);
+    }
+  }
+  return String(doc);
+}
+
+function seedUserConfigIfMissing(
+  userConfigPath,
+  templatePath,
+  onNotice,
+  env = process.env,
+  homeDir = env.HOME ?? homedir(),
+) {
   if (existsSync(userConfigPath)) return;
   mkdirSync(dirname(userConfigPath), { recursive: true });
-  copyFileSync(templatePath, userConfigPath, constants.COPYFILE_EXCL);
+  const { lineup, anyReady } = selectSeedLineup(env, homeDir);
+  if (lineup.adapter === SEED_LINEUP[0].adapter && anyReady) {
+    // Unchanged default path: one exclusive create of the template bytes.
+    copyFileSync(templatePath, userConfigPath, constants.COPYFILE_EXCL);
+  } else {
+    // Still one exclusive create, so two seeding calls cannot disagree.
+    writeFileSync(userConfigPath, seedTextForLineup(templatePath, lineup), {
+      encoding: "utf8",
+      flag: "wx",
+    });
+  }
   onNotice(`playbook: created config at ${userConfigPath}\n`);
+  if (!anyReady) {
+    onNotice(
+      `playbook: no adapter probed ready; seeded ${lineup.adapter}\n`,
+    );
+  }
 }
 
 // DR-021 §3: migrate once, keeping the original before any rewrite.

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

@@ -346,10 +346,14 @@ export async function runPlaybookCli(options = {}) {
           overlayPaths: withPaths,
           structuralProjection: selectedRecord.structuralProjection,
           onNotice: (line) => stderr.write(line),
+          env,
+          homeDir: home,
         })
       : await loadLaunchPlan({
           userConfigPath,
           overlayPaths: withPaths,
+          env,
+          homeDir: home,
           loadModule,
           prepareRegistryModule:
             options.prepareRegistryModule ??

package/reference/sdlc/code.playbook/bin/repository-effects.js

@@ -520,14 +520,169 @@ function projectionText(projection) {
   return JSON.stringify(projection);
 }
 
-function projectionPreservesBaseline(baseline, after) {
-  return Object.entries(baseline).every(
-    ([path, entry]) =>
-      Object.prototype.hasOwnProperty.call(after, path) &&
-      JSON.stringify(after[path]) === JSON.stringify(entry),
+const MISSING_CONTENT_IDENTITY = Object.freeze({ kind: 'missing' });
+
+function hasPath(projection, path) {
+  return Object.prototype.hasOwnProperty.call(projection, path);
+}
+
+// DR-062 §1: a rename, an unmerged path, a submodule, or a nested worktree is
+// preserved when byte-equal and otherwise lost, because no content matching is
+// attempted for them.
+function nonComparableBaselineEntry(entry) {
+  return (
+    entry.kind === 'rename-or-copy' ||
+    entry.kind === 'unmerged' ||
+    (entry.submodule !== undefined && entry.submodule !== 'N...') ||
+    entry.worktree?.kind === 'directory'
+  );
+}
+
+// The entry the baseline HEAD tree held for a path: an ordinary porcelain-v2
+// record carries its HEAD mode and OID, `000000` means the path did not exist
+// there, an untracked path never did, and an unborn baseline HEAD holds none.
+function baselineHeadEntry(baseline, entry) {
+  if (baseline.head === NULL_GIT_OID) return undefined;
+  if (entry.kind !== 'ordinary') return undefined;
+  if (entry.headMode === undefined || entry.headMode === '000000') {
+    return undefined;
+  }
+  return { mode: entry.headMode, oid: entry.headOid };
+}
+
+function sameTreeEntry(left, right) {
+  if (left === undefined || right === undefined) return left === right;
+  return left.mode === right.mode && left.oid === right.oid;
+}
+
+// The baseline recorded nothing at the path: a deleted worktree entry, or a
+// staged deletion whose index holds no object.
+function baselineEntryIsDeletion(entry) {
+  return entry.worktree === undefined
+    ? entry.indexMode === '000000'
+    : entry.worktree.kind === 'missing';
+}
+
+// The entry one commit's tree holds for an exact path, or undefined when that
+// tree holds none.
+async function afterTreeEntry(worktree, head, path) {
+  const raw = await runGitText(worktree, [
+    'ls-tree',
+    '-z',
+    '--full-tree',
+    head,
+    '--',
+    path,
+  ]);
+  for (const record of raw.split('\0')) {
+    if (record.length === 0) continue;
+    const tab = record.indexOf('\t');
+    const fields = tab < 0 ? [] : record.slice(0, tab).split(' ');
+    if (fields.length !== 3) {
+      throw new RepositoryObservationAmbiguousError(
+        'Git returned a malformed tree record',
+      );
+    }
+    if (record.slice(tab + 1) !== path) continue;
+    return { mode: fields[0], oid: fields[2] };
+  }
+  return undefined;
+}
+
+// A blob addressed exactly as `worktreePathIdentity` addresses the same bytes
+// in the working tree, so a committed object and the Boss's own content are
+// comparable by the projection's content addressing rather than by Git OID.
+async function blobContentIdentity(worktree, mode, oid) {
+  const bytes = await runGit(worktree, ['cat-file', 'blob', oid]);
+  return {
+    kind: mode === '120000' ? 'symlink' : 'file',
+    mode,
+    content: `sha256:${sha256(bytes)}`,
+  };
+}
+
+function baselineContentIdentity(worktree, entry) {
+  return entry.worktree === undefined
+    ? blobContentIdentity(worktree, entry.indexMode, entry.indexOid)
+    : entry.worktree;
+}
+
+function sameContentIdentity(left, right) {
+  return (
+    left.kind === right.kind &&
+    left.mode === right.mode &&
+    left.content === right.content
   );
 }
 
+// DR-062 §1: the fate of one baseline projection entry at the end of a
+// governed call — `preserved`, `altered-uncommitted`, `altered-committed`,
+// `absorbed`, or `lost`.
+async function baselineEntryFate(baseline, after, path, entry) {
+  if (hasPath(after.projection, path)) {
+    return JSON.stringify(after.projection[path]) === JSON.stringify(entry)
+      ? 'preserved'
+      : 'altered-uncommitted';
+  }
+  // The entry left the working tree, so only a commit this call made can hold
+  // the Boss's content; a call that moved no HEAD made none.
+  if (baseline.head === after.head) return 'lost';
+  if (nonComparableBaselineEntry(entry)) return 'lost';
+  try {
+    const treeEntry = await afterTreeEntry(after.worktree, after.head, path);
+    if (sameTreeEntry(treeEntry, baselineHeadEntry(baseline, entry))) {
+      // The commit left the path exactly as the baseline HEAD held it, so it
+      // carried no change of the Boss's and his content is nowhere.
+      return 'lost';
+    }
+    if (baselineEntryIsDeletion(entry)) {
+      return treeEntry === undefined ? 'absorbed' : 'lost';
+    }
+    if (treeEntry?.mode === '160000') return 'lost';
+    const [baselineIdentity, treeIdentity] = await Promise.all([
+      baselineContentIdentity(after.worktree, entry),
+      treeEntry === undefined
+        ? MISSING_CONTENT_IDENTITY
+        : blobContentIdentity(after.worktree, treeEntry.mode, treeEntry.oid),
+    ]);
+    return sameContentIdentity(baselineIdentity, treeIdentity)
+      ? 'absorbed'
+      : 'altered-committed';
+  } catch {
+    // Content the after HEAD cannot produce leaves the baseline entry
+    // unaccounted for, which fails closed exactly as a lost entry does.
+    return 'lost';
+  }
+}
+
+async function baselineEntryFates(baseline, after) {
+  const fates = [];
+  for (const [path, entry] of Object.entries(baseline.projection)) {
+    fates.push([path, await baselineEntryFate(baseline, after, path, entry)]);
+  }
+  return fates;
+}
+
+// DR-062 §3: the accounting a receipt records, present exactly when one list
+// is nonempty so that an all-preserved call keeps today's receipt shape.
+function preExistingFromFates(fates) {
+  const absorbed = [];
+  const altered = [];
+  const lost = [];
+  for (const [path, fate] of fates) {
+    if (fate === 'absorbed') absorbed.push(path);
+    else if (fate === 'altered-uncommitted' || fate === 'altered-committed') {
+      altered.push(path);
+    } else if (fate === 'lost') lost.push(path);
+  }
+  if (absorbed.length + altered.length + lost.length === 0) return undefined;
+  return {
+    absorbed: absorbed.sort(),
+    altered: altered.sort(),
+    lost: lost.sort(),
+  };
+}
+
 async function rawRepositoryStatus(worktree, env) {
   return runGit(
     worktree,
@@ -659,10 +814,18 @@ export async function resolveCanonicalGitWorktree(cwd) {
 }
 
 async function sampleWorktree(worktree, env) {
-  const head = await resolveHead(worktree, env);
-  const indexVisibility = await rawIndexVisibility(worktree, env);
+  const [headResult, visibilityResult, statusResult] = await Promise.allSettled([
+    resolveHead(worktree, env),
+    rawIndexVisibility(worktree, env),
+    rawRepositoryStatus(worktree, env),
+  ]);
+  if (headResult.status === 'rejected') throw headResult.reason;
+  if (visibilityResult.status === 'rejected') throw visibilityResult.reason;
+  const head = headResult.value;
+  const indexVisibility = visibilityResult.value;
   assertIndexVisibility(indexVisibility);
-  const status = await rawRepositoryStatus(worktree, env);
+  if (statusResult.status === 'rejected') throw statusResult.reason;
+  const status = statusResult.value;
   const projection = await projectionFromStatus(worktree, status);
   return { head, indexVisibility, status, projection };
 }
@@ -780,12 +943,13 @@ async function descendantCount(worktree, baselineHead, afterHead) {
   return count;
 }
 
-function receipt(classification, baseline, after, commitOid) {
+function receipt(classification, baseline, after, commitOid, preExisting) {
   return deepFreeze({
     classification,
     baseline,
     ...(after === undefined ? {} : { after }),
     ...(commitOid === undefined ? {} : { commitOid }),
+    ...(preExisting === undefined ? {} : { preExisting }),
   });
 }
 
@@ -813,16 +977,19 @@ export async function classifyRepositoryReceipt(
   if (allowed.every((value) => value === 'unchanged')) {
     return receipt('concurrent-or-foreign-change', baseline, after);
   }
+  // DR-062 §2: a same-HEAD delta admits altered pre-existing entries beside
+  // new ones; only an entry whose change is nowhere keeps it ambiguous.
   if (sameHead) {
-    if (!projectionPreservesBaseline(baseline.projection, after.projection)) {
-      return receipt('observation-ambiguous', baseline, after);
-    }
+    const fates = await baselineEntryFates(baseline, after);
+    const lost = fates.some(([, fate]) => fate === 'lost');
     return receipt(
-      allowed.includes('one-descendant-commit')
+      !lost && allowed.includes('one-descendant-commit')
         ? 'worktree-only-change'
         : 'observation-ambiguous',
       baseline,
       after,
+      undefined,
+      preExistingFromFates(fates),
     );
   }
   // A HEAD that stopped naming a commit lost its history; every commit
@@ -839,10 +1006,24 @@ export async function classifyRepositoryReceipt(
   if (count !== 1) {
     return receipt('rewritten-or-non-descendant', baseline, after);
   }
-  if (!sameProjection) {
-    return receipt('observation-ambiguous', baseline, after);
-  }
-  return receipt('one-descendant-commit', baseline, after, after.head);
+  // DR-062 §2: the one commit proves itself when every baseline entry is
+  // preserved, absorbed, or altered and carried by it, and the after
+  // projection holds nothing else.
+  const fates = await baselineEntryFates(baseline, after);
+  const unattributable =
+    fates.some(
+      ([, fate]) => fate === 'lost' || fate === 'altered-uncommitted',
+    ) ||
+    Object.keys(after.projection).some(
+      (path) => !hasPath(baseline.projection, path),
+    );
+  return receipt(
+    unattributable ? 'observation-ambiguous' : 'one-descendant-commit',
+    baseline,
+    after,
+    unattributable ? undefined : after.head,
+    preExistingFromFates(fates),
+  );
 }
 
 export async function captureRepositoryReceipt(baseline, options = {}) {

package/reference/sdlc/code.playbook/bin/run.js

@@ -359,10 +359,14 @@ export async function runPlaybookRun(options = {}) {
             overlayPaths: args.withPaths,
             structuralProjection: priorRecord.structuralProjection,
             onNotice: (line) => configNotices.push(line),
+            env,
+            homeDir: home,
           })
         : await loadLaunchPlan({
             userConfigPath,
             overlayPaths: args.withPaths,
+            env,
+            homeDir: home,
             loadModule,
             prepareRegistryModule,
             onNotice: (line) => configNotices.push(line),

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

@@ -3163,7 +3163,7 @@ async function createLease({
     }
     if (
       snapshot.mode !== 'chat' ||
-      snapshot.lastAction !== 'runtime' ||
+      (snapshot.lastAction !== 'runtime' && snapshot.lastAction !== 'dismiss') ||
       snapshot.lastSettlementStatus !== 'ok'
     ) {
       throw new Error(
@@ -4221,7 +4221,7 @@ function validateCanonicalCaptainSessionRecord(
     }
     if (
       snapshot.mode !== 'chat' ||
-      snapshot.lastAction !== 'runtime' ||
+      (snapshot.lastAction !== 'runtime' && snapshot.lastAction !== 'dismiss') ||
       snapshot.lastSettlementStatus !== 'ok' ||
       Object.hasOwn(record.retainedGenerations ?? {}, rootPlaybookId)
     ) {

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

@@ -212,7 +212,7 @@ export declare const codingMachine: import("xstate").StateMachine<CodingContext,
 } | {
     type: "resumesIrTask";
     params: unknown;
-}, never, "done" | "failed" | "awaitBossReply" | "ready" | "runFirstPhase" | "reviewFirstCommit" | "runIrTask" | "reviewIrTask" | "reportedReviewFailure", string, CodingInput, {
+}, never, "done" | "failed" | "ready" | "awaitBossReply" | "runFirstPhase" | "reviewFirstCommit" | "runIrTask" | "reviewIrTask" | "reportedReviewFailure", string, CodingInput, {
     readonly status: "complete";
     /** Exact identity of the last CODE-owned commit. */
     readonly lastCodeCommit: string;

package/reference/sdlc/code.playbook/host-capabilities.d.ts

@@ -32,11 +32,17 @@ export interface PlaybookRepositoryObservation extends RepositoryIdentity {
   readonly projection: Readonly<Record<string, JsonValue>>;
   readonly projectionDigest: string;
 }
+export interface PlaybookRepositoryPreExistingChanges {
+  readonly absorbed: readonly string[];
+  readonly altered: readonly string[];
+  readonly lost: readonly string[];
+}
 export interface PlaybookRepositoryReceipt {
   readonly classification: RepositoryReceiptClassification;
   readonly baseline: PlaybookRepositoryObservation;
   readonly after?: PlaybookRepositoryObservation;
   readonly commitOid?: string;
+  readonly preExisting?: PlaybookRepositoryPreExistingChanges;
 }
 export interface RepositoryReceiptOptions {
   readonly allowedDispositions: readonly PlaybookRepositoryDisposition[];

package/reference/sdlc/code.playbook/playbook-captain.d.ts

@@ -1,6 +1,6 @@
 import { type Captain, type CaptainSession, type TuningSelection } from '@sublang/cligent/tmux-play';
 import type { Effort, PermissionPolicy } from '@sublang/cligent';
-import type { JsonValue, PlaybookEffectLedger, PlaybookEffectLedgerCommandBatch, PlaybookControlAction, PlaybookRuntime, PlaybookRuntimeSnapshot } from '@sublang/playbook/runtime';
+import type { JsonValue, PlaybookEffectLedger, PlaybookEffectLedgerCommandBatch, PlaybookControlAction, PlaybookFailureCause, PlaybookRuntime, PlaybookRuntimeSnapshot } from '@sublang/playbook/runtime';
 import { type CaptainControllerPort } from '../captain.playbook/captain.playbook.js';
 import type { PlaybookSummaryPolicy } from './code.registry.js';
 interface SessionAgent {
@@ -176,9 +176,11 @@ type PlaybookCaptainShellSnapshotValue = PlaybookCaptainShellSnapshotFields & ({
     readonly frames: readonly PlaybookCaptainFrameSnapshot[];
     readonly retainedEffectReconciliation?: PlaybookCaptainRetainedEffectReconciliation;
     readonly pendingBossQuestions?: JsonValue;
+    /** DR-063 §2: the parked failure's cause travels with its error. */
     readonly lastError?: {
         readonly name: string;
         readonly message: string;
+        readonly cause?: PlaybookFailureCause;
     };
 });
 export type PlaybookCaptainShellSnapshot = DeepReadonly<PlaybookCaptainShellSnapshotValue>;