@sublang/playbook 18.0.0 → 18.1.0

package/README.md

@@ -32,8 +32,9 @@ 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, **PR** for publishing, checking, and merging that branch through a pull request, and **INSPECT** for explaining supplied material or a running interface without changing the repository.
 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 selects one adapter for the Captain and all players
-from locally visible credentials: Claude first, then Codex. If neither is
+The shared starter config selects the Captain's and players' adapter from
+locally visible credentials: Claude first, then Codex, and where both are
+configured only `dev.reviewer` seeds on 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
@@ -51,7 +52,7 @@ If an SDK is missing or older than cligent supports, Playbook prints the pinned
 Prerequisites:
 
 - Node.js >= 20.6.0
-- 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
+- Credentials for the configured adapter: authenticated [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) or `ANTHROPIC_API_KEY` / `CLAUDE_CODE_OAUTH_TOKEN` for Claude; authenticated [Codex CLI](https://github.com/openai/codex) or `OPENAI_API_KEY` / `CODEX_ACCESS_TOKEN` 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/configuration.md

@@ -64,16 +64,23 @@ one; see [Modules supplied at launch](#modules-supplied-at-launch). Every
 manifest role must be present exactly once. The launcher injects the rest — you do not write host wiring by
 hand.
 
-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.5
-for Claude or GPT-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 launcher seeds the Captain and all stable players from locally visible
+credentials (an API key in the environment, or `~/.claude` / `~/.codex`):
 
-The Claude default is shown below. A Codex seed also adds
-`permissions.writablePaths: ['.git']` to each agent:
+| Credentials | Seeded agents |
+| --- | --- |
+| Claude only, or neither | every agent on Claude Opus 5.5 (with a notice when neither is configured) |
+| Codex only | every agent on GPT-6 Sol |
+| both | `dev.reviewer` on GPT-6 Sol, every other agent on Claude Opus 5.5 |
+
+Captain, Coder, and Inspector run at `high` effort and Reviewer and Analyst at
+`xhigh`. Credentials do not prove SDK availability or remaining quota; launch
+still checks the configured adapter. Existing configs are left unchanged.
+Embedding hosts seed the same agent settings through
+`seedConfigText({ env, homeDir })` from `@sublang/playbook/seed-config`.
+
+The Claude default is shown below. Each Codex agent also carries
+`permissions.writablePaths: ['.git']`:
 
 ```yaml
 captain:
@@ -273,9 +280,12 @@ It may not finish the specialist’s task or invent a decision; discarding work
 Preparation has a 150-second limit.
 
 Adapter readiness is intentionally light: `claude` is ready with local
-Claude Code auth or `ANTHROPIC_API_KEY`; `codex` with local Codex CLI
-auth or `OPENAI_API_KEY`. A known adapter that is not ready blocks the
-launch and prints the help text.
+Claude Code auth, `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, or
+`CLAUDE_CODE_OAUTH_TOKEN`; `codex` with local Codex CLI auth,
+`OPENAI_API_KEY`, `CODEX_API_KEY`, or `CODEX_ACCESS_TOKEN`. Only presence
+counts; no token is checked. A known adapter that is not ready blocks the
+launch and prints the help text. The same check picks the starter config's
+lineup.
 
 ## Skills across agents
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "18.0.0",
+  "version": "18.1.0",
   "type": "module",
   "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, REVIEW, DECIDE, DEV, BRANCH, PR, and INSPECT workflows driven by GEARS specs.",
   "license": "Apache-2.0",
@@ -83,6 +83,8 @@
     "reference/sdlc/code.playbook/host-capabilities.d.ts",
     "reference/sdlc/code.playbook/machine-identity.js",
     "reference/sdlc/code.playbook/machine-identity.d.ts",
+    "reference/sdlc/code.playbook/seed-config.js",
+    "reference/sdlc/code.playbook/seed-config.d.ts",
     "reference/sdlc/code.playbook/code.gears.md",
     "reference/sdlc/code.playbook/playbook.config.template.yaml",
     "reference/sdlc/code.playbook/bin/playbook.js",
@@ -212,6 +214,10 @@
       "types": "./reference/sdlc/code.playbook/machine-identity.d.ts",
       "default": "./reference/sdlc/code.playbook/machine-identity.js"
     },
+    "./seed-config": {
+      "types": "./reference/sdlc/code.playbook/seed-config.d.ts",
+      "default": "./reference/sdlc/code.playbook/seed-config.js"
+    },
     "./slc/*": "./slc/*",
     "./review/playbook": {
       "types": "./reference/sdlc/review.playbook/review.playbook.d.ts",
@@ -276,6 +282,7 @@
     "test:acceptance": "node scripts/run-live-acceptance.mjs",
     "smoke:release": "node scripts/release-smoke.mjs",
     "check:links": "node scripts/check-links.mjs",
+    "prepush": "bash scripts/prepush.sh",
     "playbook": "node reference/sdlc/code.playbook/bin/playbook.js"
   },
   "publishConfig": {
@@ -283,7 +290,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@sublang/cligent": "^0.36.0",
+    "@sublang/cligent": "^0.36.1",
     "@sublang/spex": "^3.0.0",
     "p-queue": "^9.3.1",
     "xstate": "^5.19.4",

package/reference/sdlc/code.md

@@ -10,14 +10,14 @@ Roles:
 
 The caller supplies a coding request together with any relevant context.
 
-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.
+A new change intent, including standalone documentation or status maintenance that does not implement an identified unfinished IR task, 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 completed 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 rewrite any existing commit.
 
-When `review` passes a direct implementation phase, `code` is complete.
+When `review` passes a direct 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 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.
@@ -29,15 +29,18 @@ At the start of the first phase, Captain shall relay to Coder the complete calle
 > Run results: <run-results>
 
 ```markdown
-First determine whether the coding request starts a new coding intent or continues an existing IR with unfinished work.
+First determine whether the request starts a new change 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.
+Treat standalone documentation or status maintenance that does not implement an identified unfinished IR task as a new change intent, even when it refers to an IR with no unfinished task.
+Do not invent or reopen an IR task, claim unperformed work complete, or infer an owner decision not supplied by the caller.
+
+For a new change 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.
+For an existing IR with unfinished work, 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.
 After implementing an IR task, identify it and state whether any IR task still has unfinished Coder work; if so identify the next unfinished task, otherwise state this was the final IR task's Coder work.

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

@@ -1438,23 +1438,36 @@ export function adaptersFromComposedConfig(config) {
   return [...adapters];
 }
 
+// DR-097: each agent's documented environment forms, any one of which, or the
+// agent's sign-in folder, counts it as ready. No value is read.
+const CREDENTIAL_FORMS = {
+  claude: {
+    names: ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "CLAUDE_CODE_OAUTH_TOKEN"],
+    folder: ".claude",
+  },
+  codex: {
+    names: ["OPENAI_API_KEY", "CODEX_API_KEY", "CODEX_ACCESS_TOKEN"],
+    folder: ".codex",
+  },
+};
+
 export function checkReadiness(adapters, env = process.env, home = homedir()) {
   const failingAdapters = [];
   const unknownAdapters = [];
   for (const adapter of adapters) {
-    if (adapter === "claude") {
-      if (!env.ANTHROPIC_API_KEY && !existsSync(join(home, ".claude"))) {
-        failingAdapters.push(adapter);
-      }
+    const forms = Object.hasOwn(CREDENTIAL_FORMS, adapter)
+      ? CREDENTIAL_FORMS[adapter]
+      : undefined;
+    if (!forms) {
+      unknownAdapters.push(adapter);
       continue;
     }
-    if (adapter === "codex") {
-      if (!env.OPENAI_API_KEY && !existsSync(join(home, ".codex"))) {
-        failingAdapters.push(adapter);
-      }
-      continue;
+    if (
+      !forms.names.some((name) => env[name]) &&
+      !existsSync(join(home, forms.folder))
+    ) {
+      failingAdapters.push(adapter);
     }
-    unknownAdapters.push(adapter);
   }
   return { failingAdapters, unknownAdapters };
 }
@@ -1651,9 +1664,14 @@ const SEED_LINEUP = Object.freeze([
   Object.freeze({ adapter: "codex", model: "gpt-6-sol" }),
 ]);
 
+// DR-096: where both adapters are ready, this player alone takes the
+// second row, so review comes from a different provider than the work.
+const SECOND_ADAPTER_PLAYER = "dev.reviewer";
+
 /**
  * PBCLI-11: the lineup a seed would write here, and whether anything
- * actually probed ready.
+ * actually probed ready. `reviewer` is the row `dev.reviewer` takes;
+ * every other agent takes `lineup`.
  *
  * Only the credential check participates. The SDK probe constructs an
  * adapter and awaits `isAvailable()`, which reads whatever happens to
@@ -1666,7 +1684,12 @@ export function selectSeedLineup(env = process.env, home = homedir()) {
     (entry) =>
       checkReadiness([entry.adapter], env, home).failingAdapters.length === 0,
   );
-  return { lineup: ready[0] ?? SEED_LINEUP[0], anyReady: ready.length > 0 };
+  const lineup = ready[0] ?? SEED_LINEUP[0];
+  return {
+    lineup,
+    reviewer: ready.length > 1 ? ready[1] : lineup,
+    anyReady: ready.length > 0,
+  };
 }
 
 /**
@@ -1675,9 +1698,7 @@ export function selectSeedLineup(env = process.env, home = homedir()) {
  * 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;
+function seedTextForLineup(template, { lineup, reviewer }) {
   const doc = parseYamlDocument(template);
   const players = doc.getIn(["players"]);
   const agentPaths = [
@@ -1687,18 +1708,35 @@ function seedTextForLineup(templatePath, lineup) {
       String(pair.key),
     ]),
   ];
+  let changed = false;
   for (const path of agentPaths) {
-    doc.setIn([...path, "adapter"], lineup.adapter);
-    doc.setIn([...path, "model"], lineup.model);
+    const entry = path[1] === SECOND_ADAPTER_PLAYER ? reviewer : lineup;
+    if (entry.adapter === SEED_LINEUP[0].adapter) continue;
+    changed = true;
+    doc.setIn([...path, "adapter"], entry.adapter);
+    doc.setIn([...path, "model"], entry.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"]);
-    }
+    doc.setIn([...path, "permissions", "writablePaths"], [".git"]);
   }
-  return String(doc);
+  return changed ? String(doc) : template;
+}
+
+/**
+ * PBCLI-100: the starter text a seed writes under this environment and
+ * home. The public `seed-config` facade and the launcher both call it,
+ * so every host seeding through it selects the same agent settings.
+ */
+export function seedConfigText(
+  templatePath,
+  env = process.env,
+  homeDir = env.HOME ?? homedir(),
+) {
+  const selection = selectSeedLineup(env, homeDir);
+  return {
+    text: seedTextForLineup(readFileSync(templatePath, "utf8"), selection),
+    anyReady: selection.anyReady,
+  };
 }
 
 function seedUserConfigIfMissing(
@@ -1710,21 +1748,13 @@ function seedUserConfigIfMissing(
 ) {
   if (existsSync(userConfigPath)) return;
   mkdirSync(dirname(userConfigPath), { recursive: true });
-  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",
-    });
-  }
+  const { text, anyReady } = seedConfigText(templatePath, env, homeDir);
+  // One exclusive create, so two seeding calls cannot disagree.
+  writeFileSync(userConfigPath, text, { encoding: "utf8", flag: "wx" });
   onNotice(`playbook: created config at ${userConfigPath}\n`);
   if (!anyReady) {
     onNotice(
-      `playbook: no adapter probed ready; seeded ${lineup.adapter}\n`,
+      `playbook: no adapter probed ready; seeded ${SEED_LINEUP[0].adapter}\n`,
     );
   }
 }

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

@@ -993,9 +993,9 @@ function helpText({
     "",
     "Adapter setup:",
     "  claude: npm install -g @anthropic-ai/claude-agent-sdk, then run",
-    "    Claude Code once or set ANTHROPIC_API_KEY.",
+    "    Claude Code once or set ANTHROPIC_API_KEY (or CLAUDE_CODE_OAUTH_TOKEN).",
     "  codex: npm install -g @openai/codex-sdk, then run Codex CLI once",
-    "    or set OPENAI_API_KEY.",
+    "    or set OPENAI_API_KEY (or CODEX_API_KEY, CODEX_ACCESS_TOKEN).",
     "  Each SDK is an optional peer dependency, so you install only the",
     "  vendors your config actually names.",
     "",

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

@@ -14,15 +14,18 @@ const REVIEW_PLAYBOOK_ID = 'review';
 // Prompts and result contracts (verbatim from code.gears.md)
 // ---------------------------------------------------------------------------
 const FIRST_PHASE_PROMPT = [
-    'First determine whether the coding request starts a new coding intent or continues an existing IR with unfinished work.',
+    'First determine whether the request starts a new change 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.',
+    'Treat standalone documentation or status maintenance that does not implement an identified unfinished IR task as a new change intent, even when it refers to an IR with no unfinished task.',
+    'Do not invent or reopen an IR task, claim unperformed work complete, or infer an owner decision not supplied by the caller.',
+    '',
+    'For a new change 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.',
+    'For an existing IR with unfinished work, 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.",
     "After implementing an IR task, identify it and state whether any IR task still has unfinished Coder work; if so identify the next unfinished task, otherwise state this was the final IR task's Coder work.",
@@ -86,8 +89,8 @@ const REVIEW_IR_TASK_PHASE_TEMPLATE = [
 ].join('\n');
 const NEEDS_BOSS_REPLY_DESCRIPTION = "The acting agent's prose surfaces a clarifying question for Boss that the agent cannot answer alone. Output shall include `question: <verbatim question text from the acting agent's prose>`.";
 const FIRST_PHASE_RESULT = {
-    directCommit: "Coder completed the new coding intent as one direct implementation phase and made its one new commit; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.",
-    irCommit: "Coder decomposed the new coding intent into a new IR, implemented no IR task, and made its one new commit; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, and `irNumber` identifying the created IR.",
+    directCommit: "Coder completed the new change intent, including standalone documentation or status maintenance that does not implement an identified unfinished IR task (even when it refers to an IR with no unfinished task), as one direct implementation phase and made its one new commit; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.",
+    irCommit: "Coder decomposed the new change intent into a new IR, implemented no IR task, and made its one new commit; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, and `irNumber` identifying the created IR.",
     moreTasks: "Coder continued an existing IR, implemented exactly its next unfinished task, made its one new commit, and at least one IR task remains unfinished; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, `irNumber` identifying the continued IR, and `irTask` naming the implemented task.",
     finalTask: "Coder continued an existing IR, implemented its final unfinished task, and made its one new commit; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, `irNumber` identifying the continued IR, and `irTask` naming the implemented task.",
     needsBossReply: NEEDS_BOSS_REPLY_DESCRIPTION,
@@ -99,8 +102,8 @@ const IR_TASK_PHASE_RESULT = {
 };
 const STATE_DESCRIPTIONS = {
     ready: 'Waiting for a coding request.',
-    firstPhase: 'Coder runs the first coding phase: a direct implementation, a new IR, or the next task of an existing IR.',
-    reviewNewIntentPhase: 'REVIEW examines the commit of the direct implementation or new-IR phase.',
+    firstPhase: 'Coder runs the first phase: a direct change, a new IR, or an existing IR\'s next unfinished task.',
+    reviewNewIntentPhase: 'REVIEW examines the commit of the direct or new-IR phase.',
     irTaskPhase: "Coder implements the identified IR's next unfinished task.",
     reviewIrTaskPhase: 'REVIEW examines the commit of the IR-task phase.',
     awaitBossReply: "Waiting for Boss to answer the acting agent's question.",

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

@@ -251,15 +251,18 @@ export type CodeEvent =
 // ---------------------------------------------------------------------------
 
 const FIRST_PHASE_PROMPT = [
-  'First determine whether the coding request starts a new coding intent or continues an existing IR with unfinished work.',
+  'First determine whether the request starts a new change 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.',
+  'Treat standalone documentation or status maintenance that does not implement an identified unfinished IR task as a new change intent, even when it refers to an IR with no unfinished task.',
+  'Do not invent or reopen an IR task, claim unperformed work complete, or infer an owner decision not supplied by the caller.',
+  '',
+  'For a new change 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.',
+  'For an existing IR with unfinished work, 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.",
   "After implementing an IR task, identify it and state whether any IR task still has unfinished Coder work; if so identify the next unfinished task, otherwise state this was the final IR task's Coder work.",
@@ -330,9 +333,9 @@ const NEEDS_BOSS_REPLY_DESCRIPTION =
 
 const FIRST_PHASE_RESULT = {
   directCommit:
-    "Coder completed the new coding intent as one direct implementation phase and made its one new commit; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.",
+    "Coder completed the new change intent, including standalone documentation or status maintenance that does not implement an identified unfinished IR task (even when it refers to an IR with no unfinished task), as one direct implementation phase and made its one new commit; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.",
   irCommit:
-    "Coder decomposed the new coding intent into a new IR, implemented no IR task, and made its one new commit; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, and `irNumber` identifying the created IR.",
+    "Coder decomposed the new change intent into a new IR, implemented no IR task, and made its one new commit; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, and `irNumber` identifying the created IR.",
   moreTasks:
     "Coder continued an existing IR, implemented exactly its next unfinished task, made its one new commit, and at least one IR task remains unfinished; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, `irNumber` identifying the continued IR, and `irTask` naming the implemented task.",
   finalTask:
@@ -351,9 +354,9 @@ const IR_TASK_PHASE_RESULT = {
 const STATE_DESCRIPTIONS = {
   ready: 'Waiting for a coding request.',
   firstPhase:
-    'Coder runs the first coding phase: a direct implementation, a new IR, or the next task of an existing IR.',
+    'Coder runs the first phase: a direct change, a new IR, or an existing IR\'s next unfinished task.',
   reviewNewIntentPhase:
-    'REVIEW examines the commit of the direct implementation or new-IR phase.',
+    'REVIEW examines the commit of the direct or new-IR phase.',
   irTaskPhase: "Coder implements the identified IR's next unfinished task.",
   reviewIrTaskPhase: 'REVIEW examines the commit of the IR-task phase.',
   awaitBossReply: "Waiting for Boss to answer the acting agent's question.",

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

@@ -17,15 +17,18 @@ When the request may continue an existing IR that it does not identify unambiguo
 
 When the first coding phase begins for the caller's coding request and any relevant context, Captain shall prompt Coder:
 
-> First determine whether the coding request starts a new coding intent or continues an existing IR with unfinished work.
+> First determine whether the request starts a new change 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.
+> Treat standalone documentation or status maintenance that does not implement an identified unfinished IR task as a new change intent, even when it refers to an IR with no unfinished task.
+> Do not invent or reopen an IR task, claim unperformed work complete, or infer an owner decision not supplied by the caller.
+>
+> For a new change 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.
+> For an existing IR with unfinished work, 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.
 > After implementing an IR task, identify it and state whether any IR task still has unfinished Coder work; if so identify the next unfinished task, otherwise state this was the final IR task's Coder work.
@@ -49,8 +52,8 @@ When the first coding phase begins for the caller's coding request and any relev
 > > Run results: <run-results>
 
 Results:
-- `directCommit`: Coder completed the new coding intent as one direct implementation phase and made its one new commit; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.
-- `irCommit`: Coder decomposed the new coding intent into a new IR, implemented no IR task, and made its one new commit; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, and `irNumber` identifying the created IR.
+- `directCommit`: Coder completed the new change intent, including standalone documentation or status maintenance that does not implement an identified unfinished IR task (even when it refers to an IR with no unfinished task), as one direct implementation phase and made its one new commit; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.
+- `irCommit`: Coder decomposed the new change intent into a new IR, implemented no IR task, and made its one new commit; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, and `irNumber` identifying the created IR.
 - `moreTasks`: Coder continued an existing IR, implemented exactly its next unfinished task, made its one new commit, and at least one IR task remains unfinished; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, `irNumber` identifying the continued IR, and `irTask` naming the implemented task.
 - `finalTask`: Coder continued an existing IR, implemented its final unfinished task, and made its one new commit; Coder's result affirmatively supports this outcome, and no fixed presentation format of the reply is required. Output shall include `coderOutput: <verbatim final text>`, `latestCommit: <commit identity>`, `irNumber` identifying the continued IR, and `irTask` naming the implemented task.
 
@@ -58,7 +61,7 @@ Results:
 
 Captain waits until `review` passes with no unsettled findings; playbook `review` owns every review round and every review-fix commit, and no existing commit is rewritten.
 
-When a direct implementation or new-IR phase ends with its one new `code`-owned commit, Captain shall call playbook `review`:
+When a direct or new-IR phase ends with its one new `code`-owned commit, Captain shall call playbook `review`:
 
 > > Original intent: <caller-input>
 > > Review scope: the commit <code-commit> from this coding phase and its resulting repository state.
@@ -69,7 +72,7 @@ On each successful nested REVIEW, Captain shall freeze the previous phase review
 CODE scope commit and evaluated revision remain distinct because REVIEW may create fix commits.
 No caller option, player prose or repository status text supplies this record.
 The record survives permitted restoration and the current task's Boss-answer continuation, and a fresh run or explicit Boss interruption clears it.
-When `review` passes a direct implementation phase, `code` is complete and returns to its caller 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.
+When `review` passes a direct phase, `code` is complete and returns to its caller 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.
 When `review` passes a new-IR phase, Captain continues with the next unfinished IR-task phase.
 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` starts no further phase and reports the failure and the last `code`-owned commit to its caller.
 When the nested `review` call fails outside that authored result contract, `code` parks as failed and retains the control-plane error instead of reporting an authored review outcome.

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

@@ -86,7 +86,7 @@ const runtimeSpec = {
         "roleStates": {
             "firstPhase": {
                 "role": "coder",
-                "label": "Coder runs the first coding phase: a direct implementation, a new IR, or the next task of an existing IR."
+                "label": "Coder runs the first phase: a direct change, a new IR, or an existing IR's next unfinished task."
             },
             "irTaskPhase": {
                 "role": "coder",

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

@@ -123,7 +123,7 @@ const runtimeSpec = {
   "roleStates": {
     "firstPhase": {
       "role": "coder",
-      "label": "Coder runs the first coding phase: a direct implementation, a new IR, or the next task of an existing IR."
+      "label": "Coder runs the first phase: a direct change, a new IR, or an existing IR's next unfinished task."
     },
     "irTaskPhase": {
       "role": "coder",

package/reference/sdlc/code.playbook/seed-config.d.ts

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+export interface SeedConfigOptions {
+  readonly env?: NodeJS.ProcessEnv;
+  readonly homeDir?: string;
+}
+export interface SeedConfigText {
+  readonly text: string;
+  readonly anyReady: boolean;
+}
+export declare function seedConfigText(options?: SeedConfigOptions): SeedConfigText;

package/reference/sdlc/code.playbook/seed-config.js

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+// DR-096: the public `@sublang/playbook/seed-config` facade. The text is
+// the launcher's own seed (playbook-cli-11); this module only fixes the
+// bundled template and narrows the accepted options (playbook-cli-100).
+
+import { fileURLToPath } from 'node:url';
+import { seedConfigText as seedText } from './bin/launch-config.js';
+
+const TEMPLATE_PATH = fileURLToPath(
+  new URL('./playbook.config.template.yaml', import.meta.url),
+);
+
+export function seedConfigText(options = {}) {
+  const env = options.env ?? process.env;
+  return seedText(
+    TEMPLATE_PATH,
+    env,
+    ...(options.homeDir !== undefined ? [options.homeDir] : []),
+  );
+}