@sublang/playbook 14.0.0 → 15.0.0

package/README.md

@@ -65,7 +65,7 @@ playbook
 Type a task, enter `/code <task>` for implementation, or enter
 `/decide <question>` for an independently proposed and reviewed decision.
 
-On first launch, Playbook writes its config to `${SPEX_HOME:-$HOME/.spex}/playbook/playbook.config.yaml`. A config left at the former `${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml` is moved there on the next launch, unless a relative primary locator would change targets; that case is rejected unchanged with absolute replacements.
+On first launch, Playbook writes its config to `${SPEX_HOME:-$HOME/.spex}/config/playbook.config.yaml`. A config left at either former location — the root's `playbook/playbook.config.yaml` or `${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml` — is moved there once on the next launch, unless a relative primary locator would change targets; that case is rejected unchanged with absolute replacements.
 
 The same config, compiled Captain, enabled playbooks, stable players, and
 nested calls power headless turns. Both front ends create the same durable

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

@@ -4,24 +4,30 @@
 # Configuring agents
 
 Fresh launches and ordinary reopens read one config at
-`${SPEX_HOME:-$HOME/.spex}/playbook/playbook.config.yaml`. The
+`${SPEX_HOME:-$HOME/.spex}/config/playbook.config.yaml`. The
 first launch seeds it from the bundled starter and prints the path;
 later launches reuse it untouched.
 
-On the first launching command after upgrading Playbook, it moves a config from the
-former `${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml` path
-when the canonical path is absent. The one-time move preserves bytes and
-permissions and leaves no compatibility alias, so running an older Spex host
-afterward could seed a second file at the former path.
+On the first launching command after upgrading Playbook, it moves a config from
+either former location when the canonical path is absent — the root's
+`playbook/playbook.config.yaml` first, then
+`${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml`. Exactly one
+file moves; the one-time move preserves bytes and permissions, takes the former
+file's directory with it when that leaves it empty, and leaves no compatibility
+alias, so running an older Spex host afterward could seed a second file at the
+path it still resolves.
 
-The current guard rejects relocation when a legacy relative `sessions` value
+The current guard rejects relocation when a former relative `sessions` value
 or relative filesystem `playbooks.<id>.from` would resolve differently below
 the new directory. It leaves the former file unchanged and names every
 target-preserving absolute replacement. Apply those replacements and retry;
-Playbook does not rewrite the user-authored file.
+Playbook does not rewrite the user-authored file. `config/` sits at the depth
+the root's `playbook/` did, so a relative locator reaching outside the directory
+keeps its target across that move; only one pointing into the directory is
+refused as above.
 
 ```sh
-$EDITOR "${SPEX_HOME:-$HOME/.spex}/playbook/playbook.config.yaml"
+$EDITOR "${SPEX_HOME:-$HOME/.spex}/config/playbook.config.yaml"
 ```
 
 ## Anatomy

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "14.0.0",
+  "version": "15.0.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",

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.md

@@ -66,7 +66,7 @@ Do not re-run tests or builds whose inputs have not changed since any previous r
 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.
 Identify every new commit you make.
-Coder is <coder-llm>.
+Credit every AI that contributed to this commit: Coder <coder-llm>.
 ```
 
 Every new-intent phase has two semantic outcomes: direct implementation and new IR; the new-IR outcome identifies the created IR.

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

@@ -15,6 +15,7 @@ import {
   mkdirSync,
   mkdtempSync,
   readFileSync,
+  rmdirSync,
   rmSync,
   writeFileSync,
 } from "node:fs";
@@ -133,9 +134,11 @@ export function mergeSelectedConfigs(base, overlay, selectedMembers) {
   );
 }
 
-// DR-043: the config lives under the shared Spex root, resolved exactly as
-// Spex's own shells resolve it so both hosts open one file. The singular
-// `playbook/` namespace is ours; Spex owns the plural `playbooks/` library.
+// DR-043/DR-064: the config lives under the shared Spex root, resolved exactly
+// as Spex's own shells resolve it so both hosts open one file. `config/` is the
+// root's directory of human-authored configuration files, each named for the
+// format it follows; the rest of the root is laid out the same way, by what a
+// directory holds.
 export function resolveSpexHome(env = process.env, home = homedir()) {
   const explicit = env.SPEX_HOME;
   if (typeof explicit === "string" && explicit.trim().length > 0) {
@@ -148,7 +151,7 @@ export function resolveSpexHome(env = process.env, home = homedir()) {
 }
 
 export function resolveUserConfigPath(env = process.env, home = homedir()) {
-  return join(resolveSpexHome(env, home), "playbook", "playbook.config.yaml");
+  return join(resolveSpexHome(env, home), "config", "playbook.config.yaml");
 }
 
 // The pre-DR-043 location, kept only to relocate a config written there.
@@ -160,6 +163,18 @@ export function resolveLegacyUserConfigPath(
   return join(configHome, "playbook", "playbook.config.yaml");
 }
 
+// DR-064: the locations a launch relocates from, the nearer first — the root's
+// pre-DR-064 `playbook/` namespace, then the pre-DR-043 XDG path.
+export function resolveFormerUserConfigPaths(
+  env = process.env,
+  home = homedir(),
+) {
+  return [
+    join(resolveSpexHome(env, home), "playbook", "playbook.config.yaml"),
+    resolveLegacyUserConfigPath(env, home),
+  ];
+}
+
 // PBCLI-46/78: session selection needs this one root locator before the
 // complete launch plan can be selected and normalized. Read only that scalar
 // from each layer so an ordinary reopen does not inspect unrelated current
@@ -1203,22 +1218,24 @@ export function deriveLaunchReadiness(
   return { adapters, ...checkReadiness(adapters, env, home) };
 }
 
-// DR-043: a user-authored config cannot be regenerated, so the one-time move
-// to the canonical path is the deliberate exception to this project's
+// DR-043/DR-064: a user-authored config cannot be regenerated, so the one-time
+// move to the canonical path is the deliberate exception to this project's
 // reject-don't-migrate posture. It runs before seeding, never clobbers a
-// canonical file, and is a no-op once the legacy file is gone.
+// canonical file, and is a no-op once the former file is gone. It answers
+// whether it published, so a caller walking the ordered former locations stops
+// at the one that moved.
 export function relocateLegacyUserConfig(
   userConfigPath,
   legacyUserConfigPath,
   onNotice,
 ) {
-  if (legacyUserConfigPath === undefined) return;
+  if (legacyUserConfigPath === undefined) return false;
   // Any canonical filesystem entry wins, including a dangling symlink. The
   // relocation is considered only when that exact pathname is absent; this
   // keeps an obsolete or malformed legacy entry from blocking a valid config.
   try {
     lstatSync(userConfigPath);
-    return;
+    return false;
   } catch (error) {
     if (error?.code !== "ENOENT") throw error;
   }
@@ -1226,7 +1243,7 @@ export function relocateLegacyUserConfig(
   try {
     source = lstatSync(legacyUserConfigPath);
   } catch (error) {
-    if (error?.code === "ENOENT") return;
+    if (error?.code === "ENOENT") return false;
     throw error;
   }
   if (!source.isFile()) {
@@ -1246,11 +1263,18 @@ export function relocateLegacyUserConfig(
   const stagedPath = join(stagingDir, "playbook.config.yaml");
   let published = false;
   try {
-    copyFileSync(
-      legacyUserConfigPath,
-      stagedPath,
-      constants.COPYFILE_EXCL,
-    );
+    try {
+      copyFileSync(
+        legacyUserConfigPath,
+        stagedPath,
+        constants.COPYFILE_EXCL,
+      );
+    } catch (error) {
+      // The former file went between inspection and staging: there is
+      // nothing left to move, and nothing to report.
+      if (error?.code === "ENOENT") return false;
+      throw error;
+    }
     chmodSync(stagedPath, source.mode & 0o7777);
     assertLegacyRelocationLocatorsSafe(
       readFileSync(stagedPath, "utf8"),
@@ -1268,12 +1292,27 @@ export function relocateLegacyUserConfig(
   } finally {
     rmSync(stagingDir, { recursive: true, force: true });
   }
-  if (!published) return;
+  if (!published) return false;
 
   rmSync(legacyUserConfigPath, { force: true });
+  // The former file's directory went with it when it held nothing else. A
+  // plain rmdir is the whole removal: it refuses a directory with any other
+  // entry, so nothing the user put beside the config is ever swept away.
+  try {
+    rmdirSync(dirname(legacyUserConfigPath));
+  } catch (error) {
+    if (
+      error?.code !== "ENOTEMPTY" &&
+      error?.code !== "EEXIST" &&
+      error?.code !== "ENOENT"
+    ) {
+      throw error;
+    }
+  }
   onNotice(
     `playbook: moved config from ${legacyUserConfigPath} to ${userConfigPath}\n`,
   );
+  return true;
 }
 
 function assertLegacyRelocationLocatorsSafe(

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

@@ -24,7 +24,7 @@ import {
   projectTmuxConfig,
   resolveLaunchSessionsDir,
   relocateLegacyUserConfig,
-  resolveLegacyUserConfigPath,
+  resolveFormerUserConfigPaths,
   resolveUserConfigPath,
   checkReadiness,
 } from "./launch-config.js";
@@ -233,16 +233,21 @@ export async function runPlaybookCli(options = {}) {
     return { code: COMPOSITION_FAILURE_EXIT_CODE };
   }
 
-  // DR-043: only a validated managed launch may relocate the legacy config.
-  // Help and raw --config return above without changing either config path;
-  // the delegated `run` front end applies the same boundary independently.
+  // DR-043/DR-064: only a validated managed launch may relocate a config left
+  // at a former location. Help and raw --config return above without changing
+  // any config path; the delegated `run` front end applies the same boundary
+  // independently. The nearer former location goes first, and the one that
+  // moves ends the walk.
   if (options.userConfigPath === undefined) {
     try {
-      relocateLegacyUserConfig(
-        userConfigPath,
-        resolveLegacyUserConfigPath(env, home),
-        (line) => stderr.write(line),
-      );
+      for (const formerPath of resolveFormerUserConfigPaths(env, home)) {
+        const moved = relocateLegacyUserConfig(
+          userConfigPath,
+          formerPath,
+          (line) => stderr.write(line),
+        );
+        if (moved) break;
+      }
     } catch (error) {
       stderr.write(`playbook: ${errorMessage(error)}\n`);
       return { code: COMPOSITION_FAILURE_EXIT_CODE };

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,
@@ -788,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 }),
   });
 }
 
@@ -821,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
@@ -847,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

@@ -35,7 +35,7 @@ import {
   projectHostAgent,
   resolveLaunchSessionsDir,
   relocateLegacyUserConfig,
-  resolveLegacyUserConfigPath,
+  resolveFormerUserConfigPaths,
   resolveUserConfigPath,
   snapshotRegistryEntry,
 } from "./launch-config.js";
@@ -127,15 +127,19 @@ export async function runPlaybookRun(options = {}) {
 
   const userConfigPath =
     options.userConfigPath ?? resolveUserConfigPath(env, home);
-  // DR-043: move a pre-relocation config to the canonical path before any
-  // read, seed, or plan work observes its absence.
+  // DR-043/DR-064: move a config left at a former location to the canonical
+  // path before any read, seed, or plan work observes its absence. The nearer
+  // former location goes first, and the one that moves ends the walk.
   if (options.userConfigPath === undefined) {
     try {
-      relocateLegacyUserConfig(
-        userConfigPath,
-        resolveLegacyUserConfigPath(env, home),
-        (line) => stderr.write(line),
-      );
+      for (const formerPath of resolveFormerUserConfigPaths(env, home)) {
+        const moved = relocateLegacyUserConfig(
+          userConfigPath,
+          formerPath,
+          (line) => stderr.write(line),
+        );
+        if (moved) break;
+      }
     } catch (error) {
       await writeStream(stderr, `playbook run: ${message(error)}\n`);
       return { code: EXIT.argument };

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/code.fsm.js

@@ -9,7 +9,7 @@ const APPENDED_PHASE_PROMPT = [
     "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.',
     'Identify every new commit you make.',
-    'Coder is <coder-llm>.',
+    'Credit every AI that contributed to this commit: Coder <coder-llm>.',
 ];
 const FIRST_PHASE_PROMPT = [
     '> Original request: <caller-input>',

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

@@ -152,7 +152,7 @@ const APPENDED_PHASE_PROMPT = [
   "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.',
   'Identify every new commit you make.',
-  'Coder is <coder-llm>.',
+  'Credit every AI that contributed to this commit: Coder <coder-llm>.',
 ];
 
 const FIRST_PHASE_PROMPT = [

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

@@ -36,7 +36,7 @@ When the first coding phase begins, Captain shall prompt Coder:
 > 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.
 > Identify every new commit you make.
-> Coder is <coder-llm>.
+> Credit every AI that contributed to this commit: Coder <coder-llm>.
 
 Results:
 - `directCommit`: Coder completed and committed the direct implementation phase. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.
@@ -77,7 +77,7 @@ When a later IR-task phase begins, Captain shall prompt Coder:
 > 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.
 > Identify every new commit you make.
-> Coder is <coder-llm>.
+> Credit every AI that contributed to this commit: Coder <coder-llm>.
 
 Results:
 - `moreTasks`: Coder completed and committed exactly the IR's next unfinished task and at least one task remains. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, `irNumber` identifying the continued IR, and `irTask` naming the implemented task.

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[];