@sublang/playbook 14.1.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/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.1.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/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/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.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/decide.md

@@ -43,7 +43,7 @@ Do not change code or implement the design.
 Commit the result as one new commit, following @specs/packages/git.md.
 Make the commit message explain concisely what changed and why.
 Identify every new commit you make.
-Coder is <coder-llm> and Reviewer is <reviewer-llm>.
+Credit every AI that contributed to this commit: Coder <coder-llm> and Reviewer <reviewer-llm>, whose proposal it carries.
 
 > Original topic: \<caller-topic\>
 > Reviewer's independent proposal: \<reviewer-proposal\>

package/reference/sdlc/decide.playbook/decide.fsm.js

@@ -26,7 +26,7 @@ const SYNTHESIZE_COMMIT_PROMPT = [
     'Commit the result as one new commit, following @specs/packages/git.md.',
     'Make the commit message explain concisely what changed and why.',
     'Identify every new commit you make.',
-    'Coder is <coder-llm> and Reviewer is <reviewer-llm>.',
+    'Credit every AI that contributed to this commit: Coder <coder-llm> and Reviewer <reviewer-llm>, whose proposal it carries.',
     '',
     '> Original topic: <caller-topic>',
     "> Reviewer's independent proposal: <reviewer-proposal>",

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

@@ -168,7 +168,7 @@ const SYNTHESIZE_COMMIT_PROMPT = [
   'Commit the result as one new commit, following @specs/packages/git.md.',
   'Make the commit message explain concisely what changed and why.',
   'Identify every new commit you make.',
-  'Coder is <coder-llm> and Reviewer is <reviewer-llm>.',
+  'Credit every AI that contributed to this commit: Coder <coder-llm> and Reviewer <reviewer-llm>, whose proposal it carries.',
   '',
   '> Original topic: <caller-topic>',
   "> Reviewer's independent proposal: <reviewer-proposal>",

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

@@ -66,7 +66,7 @@ When both independent proposals are complete, Captain shall relay the complete t
 > Commit the result as one new commit, following @specs/packages/git.md.
 > Make the commit message explain concisely what changed and why.
 > Identify every new commit you make.
-> Coder is <coder-llm> and Reviewer is <reviewer-llm>.
+> Credit every AI that contributed to this commit: Coder <coder-llm> and Reviewer <reviewer-llm>, whose proposal it carries.
 >
 > > Original topic: <caller-topic>
 > > Reviewer's independent proposal: <reviewer-proposal>

package/reference/sdlc/review.md

@@ -101,7 +101,7 @@ If you accept any item, make minimal changes and add one new review-fix commit;
 Follow @specs/packages/git.md.
 Make the commit message explain concisely what changed and why, including relevant verification.
 Identify every new commit you make.
-Coder is <coder-llm>; Reviewer is <reviewer-llm>.
+Credit every AI that contributed to this commit: Coder <coder-llm> and Reviewer <reviewer-llm>, whose findings it answers.
 
 If you reject every item, change nothing and make no commit.
 Report every disposition, all relevant run results, and every rebuttal.

package/reference/sdlc/review.playbook/review.fsm.js

@@ -67,7 +67,7 @@ const CODER_DISPOSITION_PROMPT = [
     'Follow @specs/packages/git.md.',
     'Make the commit message explain concisely what changed and why, including relevant verification.',
     'Identify every new commit you make.',
-    'Coder is <coder-llm>; Reviewer is <reviewer-llm>.',
+    'Credit every AI that contributed to this commit: Coder <coder-llm> and Reviewer <reviewer-llm>, whose findings it answers.',
     '',
     'If you reject every item, change nothing and make no commit.',
     'Report every disposition, all relevant run results, and every rebuttal.',

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

@@ -156,7 +156,7 @@ const CODER_DISPOSITION_PROMPT = [
   'Follow @specs/packages/git.md.',
   'Make the commit message explain concisely what changed and why, including relevant verification.',
   'Identify every new commit you make.',
-  'Coder is <coder-llm>; Reviewer is <reviewer-llm>.',
+  'Credit every AI that contributed to this commit: Coder <coder-llm> and Reviewer <reviewer-llm>, whose findings it answers.',
   '',
   'If you reject every item, change nothing and make no commit.',
   'Report every disposition, all relevant run results, and every rebuttal.',

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

@@ -65,7 +65,7 @@ When Reviewer raises or keeps any finding, Captain shall relay the caller input
 > Follow @specs/packages/git.md.
 > Make the commit message explain concisely what changed and why, including relevant verification.
 > Identify every new commit you make.
-> Coder is <coder-llm>; Reviewer is <reviewer-llm>.
+> Credit every AI that contributed to this commit: Coder <coder-llm> and Reviewer <reviewer-llm>, whose findings it answers.
 >
 > If you reject every item, change nothing and make no commit.
 > Report every disposition, all relevant run results, and every rebuttal.