@sublang/playbook 2.0.0 → 3.0.0

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

@@ -17,7 +17,11 @@ import {
 import { homedir, tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { parse as parseYaml, stringify as stringifyYaml } from 'yaml';
+import {
+  parse as parseYaml,
+  parseDocument as parseYamlDocument,
+  stringify as stringifyYaml,
+} from 'yaml';
 
 const here = dirname(fileURLToPath(import.meta.url));
 const templatePath = resolve(here, '..', 'playbook.config.template.yaml');
@@ -25,8 +29,8 @@ const templatePath = resolve(here, '..', 'playbook.config.template.yaml');
 // PBCLI-1/8: the launcher composes a tmux-play config whose Captain is the
 // Playbook Captain shell adapter module.
 export const PLAYBOOK_CAPTAIN_MODULE = '@sublang/playbook/playbook-captain';
-// PBCLI-8/12: known adapter shorthands. A `profiles` id may not collide
-// with one of these, and these are the adapters with readiness predicates.
+// PBCLI-12: known adapter shorthands — the adapters with readiness
+// predicates.
 const ADAPTER_SHORTHANDS = ['claude', 'codex'];
 // PBCLI-8: launcher-owned keys inside a `playbooks.<id>` block; every other
 // key belongs to that playbook's option slice.
@@ -103,6 +107,15 @@ export async function runPlaybookCli(options = {}) {
 
   seedUserConfigIfMissing(userConfigPath, stderr);
 
+  // DR-021 §3: an existing profiles-based config is rewritten in place once,
+  // with the original kept beside it, so the user launches without editing.
+  try {
+    migrateUserConfigIfRetired(userConfigPath, stderr);
+  } catch (error) {
+    stderr.write(`playbook: ${errorMessage(error)}\n`);
+    return { code: COMPOSITION_FAILURE_EXIT_CODE };
+  }
+
   let composed;
   try {
     let top = parseYaml(readFileSync(userConfigPath, 'utf8')) ?? {};
@@ -114,7 +127,7 @@ export async function runPlaybookCli(options = {}) {
     for (const overlayPath of withPaths) {
       top = mergeConfigs(top, loadOverlayFragment(overlayPath));
     }
-    composed = await composeGenericConfig(top, loadModule);
+    composed = await composeGenericConfig(top, loadModule, userConfigPath);
   } catch (error) {
     stderr.write(`playbook: ${errorMessage(error)}\n`);
     return { code: COMPOSITION_FAILURE_EXIT_CODE };
@@ -235,29 +248,213 @@ export function resolveUserConfigPath(env = process.env, home = homedir()) {
   return join(resolveConfigHome(env, home), 'playbook', 'playbook.config.yaml');
 }
 
-// PBCLI-8: resolve a scalar `captain` / `players.<role>` value as a profile
-// id or adapter shorthand, or a full agent block whose optional `profile`
-// key names a `profiles` entry whose settings are the base under the block's
-// own explicit fields. The composed block carries no `profile` key.
-export function resolveAgent(value, profiles, path) {
-  if (typeof value === 'string') {
-    if (hasOwn(profiles, value)) return { ...profiles[value] };
-    return { adapter: value };
+// PBCLI-8 (DR-021): a scalar `captain` / `players.<role>` value is an
+// adapter shorthand; a full block is a self-contained tmux-play agent block
+// carrying its own adapter/model/effort/permissions. There is no profile
+// indirection, so retuning one agent cannot change another.
+export function resolveAgent(value, path) {
+  if (typeof value === 'string') return { adapter: value };
+  if (isObject(value)) return { ...value };
+  throw new Error(`${path} must be an adapter shorthand or an agent block`);
+}
+
+// DR-021 §3: migrate the user's config on disk, once, keeping the original.
+// The backup is written before the rewrite and never overwrites an existing
+// file, so a prior backup — or a user's own .bak — cannot be lost.
+function migrateUserConfigIfRetired(userConfigPath, stderr) {
+  let text;
+  try {
+    text = readFileSync(userConfigPath, 'utf8');
+  } catch {
+    return;
   }
-  if (isObject(value)) {
-    const { profile, ...rest } = value;
-    let base = {};
-    if (profile !== undefined) {
-      if (typeof profile !== 'string' || !hasOwn(profiles, profile)) {
-        throw new Error(`${path}.profile must name a profiles entry`);
+  let migrated;
+  try {
+    migrated = migrateRetiredProfiles(text);
+  } catch (error) {
+    throw new Error(
+      `cannot migrate the retired profiles config at ${userConfigPath}: ` +
+        `${errorMessage(error)} — edit it by hand: each agent takes its own ` +
+        'adapter, model, effort, and permissions',
+    );
+  }
+  if (migrated === undefined) return;
+  const backupPath = freeBackupPath(userConfigPath);
+  writeFileSync(backupPath, text, { mode: 0o600 });
+  writeFileSync(userConfigPath, migrated);
+  stderr.write(
+    `playbook: migrated ${userConfigPath} to inline agent settings ` +
+      `(the top-level "profiles" map was removed in 3.0.0); ` +
+      `the original is at ${backupPath}\n`,
+  );
+}
+
+function freeBackupPath(userConfigPath) {
+  const first = `${userConfigPath}.bak`;
+  if (!existsSync(first)) return first;
+  for (let n = 2; ; n += 1) {
+    const candidate = `${userConfigPath}.bak.${n}`;
+    if (!existsSync(candidate)) return candidate;
+  }
+}
+
+// DR-021 §3: rewrite a config written for the retired profiles model in
+// place, inlining each agent's settings and keeping the original beside it.
+// Edits go through the YAML Document API so the user's comments survive;
+// only the profiles block and its own commentary are removed. Returns the
+// migrated text, or undefined when there is nothing to migrate.
+export function migrateRetiredProfiles(text) {
+  const doc = parseYamlDocument(text);
+  const contents = doc.contents;
+  if (!contents || !Array.isArray(contents.items)) return undefined;
+  const profiles = doc.get('profiles');
+  const agentPaths = [['captain']];
+  const playbooks = doc.get('playbooks');
+  if (playbooks && Array.isArray(playbooks.items)) {
+    for (const entry of playbooks.items) {
+      const id = String(entry.key);
+      const players = doc.getIn(['playbooks', id, 'players']);
+      if (!players || !Array.isArray(players.items)) continue;
+      for (const player of players.items) {
+        agentPaths.push(['playbooks', id, 'players', String(player.key)]);
+      }
+    }
+  }
+
+  const profileSettings = (name) =>
+    profiles && typeof profiles.get === 'function'
+      ? profiles.get(name)
+      : undefined;
+
+  let changed = false;
+  for (const path of agentPaths) {
+    const node = doc.getIn(path, true);
+    if (node && typeof node.value === 'string' && !Array.isArray(node.items)) {
+      // A scalar that named a profile; a bare adapter shorthand stays.
+      const settings = profileSettings(node.value);
+      if (settings === undefined) continue;
+      const inlined = settings.clone();
+      // The scalar carried any comment on that line, and replacing the node
+      // would drop it. Re-attach it above the block that replaces it.
+      carryScalarComment(node, inlined);
+      doc.setIn(path, inlined);
+      changed = true;
+    } else if (node && Array.isArray(node.items)) {
+      const named = node.get?.('profile');
+      if (named === undefined) continue;
+      const settings = profileSettings(named);
+      if (settings === undefined) {
+        throw new Error(
+          `${path.join('.')}.profile names "${String(named)}", which no ` +
+            'profiles entry defines',
+        );
       }
-      base = { ...profiles[profile] };
+      // Fill the block from its profile in place — never rebuild it — so
+      // the user's own keys, ordering, and comments survive untouched. The
+      // block's own fields stay authoritative, so only absent keys are added.
+      node.delete('profile');
+      for (const item of settings.items) {
+        if (node.has(String(item.key))) continue;
+        // Append the whole pair, not a rebuilt key/value: a comment above a
+        // setting rides on that setting's key node, so stringifying the key
+        // would drop it.
+        node.add(item.clone());
+      }
+      changed = true;
+    }
+  }
+
+  if (profiles !== undefined) {
+    // The comment block above `profiles` usually carries the file's own
+    // header, which must outlive the removed section: keep every paragraph
+    // except the last, which documents profiles themselves.
+    const index = contents.items.findIndex(
+      (item) => String(item.key) === 'profiles',
+    );
+    const lead = index === -1 ? undefined : contents.items[index]?.key
+      ?.commentBefore;
+    doc.delete('profiles');
+    const header = keptHeaderComment(lead);
+    const next = contents.items[0];
+    if (header !== undefined && next?.key) {
+      next.key.commentBefore =
+        next.key.commentBefore === undefined
+          ? header
+          : `${header}\n\n${next.key.commentBefore}`;
     }
-    return { ...base, ...rest };
+    changed = true;
   }
-  throw new Error(
-    `${path} must be a profile id, an adapter shorthand, or an agent block`,
+  if (!changed) return undefined;
+  // Say what happened at the top of the file the user will open next:
+  // some of their remaining comments describe the retired model.
+  doc.commentBefore = MIGRATION_NOTE;
+  return doc.toString();
+}
+
+const MIGRATION_NOTE =
+  ' Migrated by playbook 3.0.0: the top-level `profiles` map was removed and\n' +
+  ' each agent now carries its settings inline. The pre-migration file is\n' +
+  ' kept beside this one as a .bak. Comments below may still describe the\n' +
+  ' retired profiles model.';
+
+// Move a scalar agent's own comments onto the block that replaces it, so
+// `captain: base # the judge` keeps its note. The pair's key comments are
+// untouched by the replacement and need no carrying.
+function carryScalarComment(node, inlined) {
+  const parts = [node.commentBefore, node.comment].filter(
+    (part) => typeof part === 'string' && part.trim() !== '',
   );
+  if (parts.length === 0) return;
+  const first = inlined.items?.[0]?.key;
+  if (!first) return;
+  // A flow map carrying a comment renders as a multi-line brace block; the
+  // ordinary block form is what the rest of the config looks like.
+  inlined.flow = false;
+  const carried = parts.join('\n');
+  first.commentBefore =
+    first.commentBefore === undefined
+      ? carried
+      : `${carried}\n${first.commentBefore}`;
+}
+
+// Drop the trailing paragraph — the one describing the profiles block —
+// and keep the rest of the leading comment (SPDX header, file overview).
+function keptHeaderComment(comment) {
+  if (typeof comment !== 'string' || comment.trim() === '') return undefined;
+  const paragraphs = comment.split('\n\n');
+  const kept = paragraphs.slice(0, -1).join('\n\n');
+  return kept.trim() === '' ? undefined : kept;
+}
+
+// A `profile` key that survives migration — introduced by a `--with`
+// overlay rather than the user's own config — is still rejected.
+function assertNoRetiredProfiles(top, configPath) {
+  const where = configPath ? ` in ${configPath}` : '';
+  if (top.profiles !== undefined) {
+    throw new Error(
+      `top-level "profiles" was removed${where}: write each agent's settings ` +
+        'inline under captain and each playbooks.<id>.players.<role> ' +
+        '(adapter, model, effort, permissions)',
+    );
+  }
+  const blocks = [['captain', top.captain]];
+  const playbooksCfg = isObject(top.playbooks) ? top.playbooks : {};
+  for (const [id, block] of Object.entries(playbooksCfg)) {
+    const playersMap = isObject(block) && isObject(block.players)
+      ? block.players
+      : {};
+    for (const [role, agent] of Object.entries(playersMap)) {
+      blocks.push([`playbooks.${id}.players.${role}`, agent]);
+    }
+  }
+  for (const [path, block] of blocks) {
+    if (isObject(block) && block.profile !== undefined) {
+      throw new Error(
+        `${path}.profile was removed${where}: write the agent's settings ` +
+          'inline in that block (adapter, model, effort, permissions)',
+      );
+    }
+  }
 }
 
 function isValidRegistryEntry(value) {
@@ -272,19 +469,12 @@ function isValidRegistryEntry(value) {
   );
 }
 
-// PBCLI-8/9/10: normalize the top-level `profiles` / `playbooks` config into
+// PBCLI-8/9/10: normalize the top-level `playbooks` config into
 // a tmux-play config (Captain = the shell adapter; `captain.options.playbooks`
 // the normalized enablement; a launch-time namespaced `<id>-<role>` roster;
 // launcher-owned `layout.initialVisible`).
-export async function composeGenericConfig(top, loadModule) {
-  const profiles = isObject(top.profiles) ? top.profiles : {};
-  for (const id of Object.keys(profiles)) {
-    if (ADAPTER_SHORTHANDS.includes(id)) {
-      throw new Error(
-        `profiles.${id} collides with the "${id}" adapter shorthand`,
-      );
-    }
-  }
+export async function composeGenericConfig(top, loadModule, configPath) {
+  assertNoRetiredProfiles(top, configPath);
 
   const playbooksCfg = requireObject(top.playbooks, 'playbooks');
   const ids = Object.keys(playbooksCfg);
@@ -294,7 +484,7 @@ export async function composeGenericConfig(top, loadModule) {
 
   const captain = {
     from: PLAYBOOK_CAPTAIN_MODULE,
-    ...resolveAgent(top.captain, profiles, 'captain'),
+    ...resolveAgent(top.captain, 'captain'),
   };
   if (captain.adapter === undefined) {
     throw new Error('captain must resolve an adapter');
@@ -389,7 +579,6 @@ export async function composeGenericConfig(top, loadModule) {
     for (const role of roles) {
       const agent = resolveAgent(
         playersMap[role],
-        profiles,
         `playbooks.${id}.players.${role}`,
       );
       if (agent.adapter === undefined) {
@@ -419,7 +608,16 @@ export async function composeGenericConfig(top, loadModule) {
     listing.push({ id, command, intent: entry.intent });
   }
 
-  captain.options = { playbooks: optionsPlaybooks };
+  // DR-013 A1: the shell cannot see its own captain's adapter through the
+  // tmux-play CaptainContext, so the launcher — which resolved it — passes it
+  // through. The shell needs it to decide whether an explicit empty tool
+  // allowlist can be enforced or must degrade to prompt-level restriction.
+  captain.options = {
+    playbooks: optionsPlaybooks,
+    ...(typeof captain.adapter === 'string' && captain.adapter.length > 0
+      ? { captainAdapter: captain.adapter }
+      : {}),
+  };
   const config = { captain, players: roster };
   // PBCLI-10: carry the user's tmux-play layout window/weight fields through;
   // the launcher owns `layout.initialVisible` (first enabled playbook).
@@ -504,9 +702,9 @@ function helpText({ userConfigPath, failingAdapters = [] }) {
     '  codex: run Codex CLI once or set OPENAI_API_KEY.',
     '',
     'Agent swap recipe:',
-    '  - reuse agent settings under top-level profiles',
-    '  - point each playbooks.<id>.captain / players.<role> at a profile id',
-    '    or an adapter shorthand (claude, codex)',
+    '  - set each agent inline: the top-level captain and every',
+    '    playbooks.<id>.players.<role> takes an adapter shorthand',
+    '    (claude, codex) or a block with adapter/model/effort/permissions',
     '  - the launcher injects captain.from and the namespaced <id>-<role>',
     '    host players',
     '',

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

@@ -28,6 +28,7 @@ import {
   supportedEffortValues,
 } from '@sublang/cligent';
 import { parse as parseYaml } from 'yaml';
+import { hiddenControlEnvelope } from '../../../../src/xstate-runtime.js';
 
 // PBCLI-19: adapter shorthands the run host can construct.
 const ADAPTER_LOADERS = {
@@ -361,9 +362,19 @@ async function driveTurn({ ctx, runtime, store, text, json, verbose, restoreFrom
       };
     },
     async callJudge(prompt, signal) {
-      const result = await captainAgent.run(prompt, {
+      // CAPTAIN-9 / DR-013 A1: wrap every judge prompt in the shared
+      // hidden-control envelope. Runtime judge prompts embed raw Boss text
+      // and quoted player output, so the envelope is what makes them
+      // delimited evidence rather than instructions — and it is the
+      // prompt-level isolation that stands in for provider enforcement
+      // when the tool allowlist below has to be omitted.
+      const result = await captainAgent.run(hiddenControlEnvelope(prompt), {
         resume: false,
-        allowedTools: [],
+        // An empty allowlist means "no tools" and is distinct from omission,
+        // which grants the adapter's full tool surface. Send it only where
+        // the adapter can enforce it; codex rejects any tool list outright,
+        // so requesting one would fail every judge call.
+        ...controlCallToolOptions(store.captain.adapter),
         signal,
       });
       if (result.status !== 'ok' || result.finalText === undefined) {
@@ -577,6 +588,20 @@ function playersFromSpecs(roleSpecs) {
   }));
 }
 
+// DR-013 A1: adapters with no provider-enforced tool-restriction surface.
+// Cligent's codex adapter rejects any allowedTools value — including the
+// empty list that expresses tool-free — so a control call that requests one
+// fails before the model is reached. Omission is the only way such an
+// adapter can run a control call; isolation then rests on the prompt.
+const ADAPTERS_WITHOUT_TOOL_ENFORCEMENT = new Set(['codex']);
+
+// Keep requesting enforcement whenever the adapter is unknown, so the
+// DR-013 guarantee holds by default.
+function controlCallToolOptions(captainAdapter) {
+  if (ADAPTERS_WITHOUT_TOOL_ENFORCEMENT.has(captainAdapter)) return {};
+  return { allowedTools: [] };
+}
+
 // PBCLI-19/26: returns a diagnostic for the first invalid spec — an
 // unknown adapter or an effort the adapter does not support — or
 // undefined when every spec resolves. The caller must compare against

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

@@ -59,18 +59,18 @@ const stateDescriptions = {
     respondToReview: 'CODE-2: Coder addresses or challenges Reviewer findings.',
     continueIr: 'CODE-3: Coder continues an IR after the previous task or IR draft passed review.',
     summarizeSpecs: 'CODE-4: Coder summarizes a completed IR into minimal spec items.',
-    reviewBossCommitSpecs: 'CODE-5: Reviewer reviews a Boss-intent commit whose changes are only in @specs/{user,dev,test}/.',
-    reviewBossCommitCode: 'CODE-6: Reviewer reviews a Boss-intent commit whose changes are only outside @specs/{user,dev,test}/.',
-    reviewBossCommitMixed: 'CODE-7: Reviewer reviews a Boss-intent commit whose changes span both @specs/{user,dev,test}/ and other files.',
-    reviewIrTaskCommitSpecs: 'CODE-8: Reviewer reviews an IR-task commit whose changes are only in @specs/{user,dev,test}/.',
-    reviewIrTaskCommitCode: 'CODE-9: Reviewer reviews an IR-task commit whose changes are only outside @specs/{user,dev,test}/.',
-    reviewIrTaskCommitMixed: 'CODE-10: Reviewer reviews an IR-task commit whose changes span both @specs/{user,dev,test}/ and other files.',
-    reviewChangesSpecs: 'CODE-11: Reviewer reviews uncommitted Coder changes that touch only @specs/{user,dev,test}/ with no accompanying rebuttals.',
-    reviewChangesCode: 'CODE-12: Reviewer reviews uncommitted Coder changes that touch only files outside @specs/{user,dev,test}/ with no accompanying rebuttals.',
-    reviewChangesMixed: 'CODE-13: Reviewer reviews uncommitted Coder changes that touch both @specs/{user,dev,test}/ and other files with no accompanying rebuttals.',
-    reviewChangesAndChallengesSpecs: 'CODE-15: Reviewer reviews uncommitted Coder changes that touch only @specs/{user,dev,test}/ and adjudicates accompanying rebuttals in one round.',
-    reviewChangesAndChallengesCode: 'CODE-16: Reviewer reviews uncommitted Coder changes that touch only files outside @specs/{user,dev,test}/ and adjudicates accompanying rebuttals in one round.',
-    reviewChangesAndChallengesMixed: 'CODE-17: Reviewer reviews uncommitted Coder changes that touch both @specs/{user,dev,test}/ and other files and adjudicates accompanying rebuttals in one round.',
+    reviewBossCommitSpecs: 'CODE-5: Reviewer reviews a Boss-intent commit whose changes are only in spec item files.',
+    reviewBossCommitCode: 'CODE-6: Reviewer reviews a Boss-intent commit whose changes are only outside spec item files.',
+    reviewBossCommitMixed: 'CODE-7: Reviewer reviews a Boss-intent commit whose changes span both spec item files and other files.',
+    reviewIrTaskCommitSpecs: 'CODE-8: Reviewer reviews an IR-task commit whose changes are only in spec item files.',
+    reviewIrTaskCommitCode: 'CODE-9: Reviewer reviews an IR-task commit whose changes are only outside spec item files.',
+    reviewIrTaskCommitMixed: 'CODE-10: Reviewer reviews an IR-task commit whose changes span both spec item files and other files.',
+    reviewChangesSpecs: 'CODE-11: Reviewer reviews uncommitted Coder changes that touch only spec item files with no accompanying rebuttals.',
+    reviewChangesCode: 'CODE-12: Reviewer reviews uncommitted Coder changes that touch only files outside spec item files with no accompanying rebuttals.',
+    reviewChangesMixed: 'CODE-13: Reviewer reviews uncommitted Coder changes that touch both spec item files and other files with no accompanying rebuttals.',
+    reviewChangesAndChallengesSpecs: 'CODE-15: Reviewer reviews uncommitted Coder changes that touch only spec item files and adjudicates accompanying rebuttals in one round.',
+    reviewChangesAndChallengesCode: 'CODE-16: Reviewer reviews uncommitted Coder changes that touch only files outside spec item files and adjudicates accompanying rebuttals in one round.',
+    reviewChangesAndChallengesMixed: 'CODE-17: Reviewer reviews uncommitted Coder changes that touch both spec item files and other files and adjudicates accompanying rebuttals in one round.',
     adjudicateChallenges: 'CODE-14: Reviewer adjudicates Coder rebuttals against the prior review when Coder produced no code edits this round.',
     commitCoderInitial: 'CODE-18: Committer commits Coder Initial Changes when Reviewer has not played since the last commit.',
     commitJoint: 'CODE-19: Committer commits changes when both Coder and Reviewer have played since the last commit.',
@@ -151,7 +151,7 @@ const planAndImplementInput = (context) => ({
     ...bossReplyInputFields(context),
     prompt: [
         'Assess whether this can be completed in a single commit, following best practices.',
-        'If yes, implement and test, updating both code and specs; otherwise, decompose into tasks as a new IR under @specs/iterations and stop without implementing any IR task.',
+        'If yes, implement and test, updating both code and specs; otherwise, decompose into tasks as a new IR under @specs/intents (or @specs/iterations in older scaffolds) and stop without implementing any IR task.',
         'For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.',
         'Ensure @specs/map.md reflects the changes.',
         'Do not commit.',
@@ -188,9 +188,9 @@ const summarizeSpecsInput = (context) => ({
         'Read IR-<#> and corresponding commits.',
         'According to @specs/meta.md, add or update spec items to fully capture:',
         '',
-        '- the user requirements in @specs/user,',
-        '- the system behavior in @specs/dev, and',
-        '- the integration/system test cases in @specs/test.',
+        '- the external behavior users rely on,',
+        '- the internal system behavior, and',
+        '- the integration/system test cases.',
         '',
         'The spec items should be the *minimal* set needed to reimplement code without the IR.',
         'The set should be complete and coherent.',
@@ -200,7 +200,7 @@ const summarizeSpecsInput = (context) => ({
     ].join('\n'),
     result: withNeedsBossReply({
         specsReady: 'Coder produced uncommitted spec updates (Initial Changes).',
-        noSpecChanges: 'Existing specs already capture the iteration.',
+        noSpecChanges: 'Existing specs already capture the realized intent.',
     }),
 });
 const setPendingBossQuestion = (resumeStateId) => assign({
@@ -396,12 +396,12 @@ export const codingMachine = setup({
                         'Stage all current changes that belong in the repo before making any edits, and leave your edits unstaged/untracked.',
                     ].join('\n'),
                     result: {
-                        changesMadeSpecs: 'Coder accepted items and produced unstaged/untracked edits in @specs/{user,dev,test}/ only, without raising any rebuttals.',
-                        changesMadeCode: 'Coder accepted items and produced unstaged/untracked edits outside @specs/{user,dev,test}/ only, without raising any rebuttals.',
-                        changesMadeMixed: 'Coder accepted items and produced unstaged/untracked edits spanning both @specs/{user,dev,test}/ and other files, without raising any rebuttals.',
-                        changesMadeSpecsAndChallenged: 'Coder produced unstaged/untracked edits in @specs/{user,dev,test}/ only AND challenged one or more review items. Output shall include `challenges: <numbered rebuttals, one per challenged item>`.',
-                        changesMadeCodeAndChallenged: 'Coder produced unstaged/untracked edits outside @specs/{user,dev,test}/ only AND challenged one or more review items. Output shall include `challenges: <numbered rebuttals, one per challenged item>`.',
-                        changesMadeMixedAndChallenged: 'Coder produced unstaged/untracked edits spanning both @specs/{user,dev,test}/ and other files AND challenged one or more review items. Output shall include `challenges: <numbered rebuttals, one per challenged item>`.',
+                        changesMadeSpecs: 'Coder accepted items and produced unstaged/untracked edits only in spec item files (@specs/packages/, @specs/compositions/, or legacy @specs/{user,dev,test}/), without raising any rebuttals.',
+                        changesMadeCode: 'Coder accepted items and produced unstaged/untracked edits only outside spec item files (any other files, including @specs/ decision, intent, or legacy iteration records, @specs/map.md, and @specs/meta.md), without raising any rebuttals.',
+                        changesMadeMixed: 'Coder accepted items and produced unstaged/untracked edits spanning both spec item files and other files, without raising any rebuttals.',
+                        changesMadeSpecsAndChallenged: 'Coder produced unstaged/untracked edits only in spec item files (@specs/packages/, @specs/compositions/, or legacy @specs/{user,dev,test}/) AND challenged one or more review items. Output shall include `challenges: <numbered rebuttals, one per challenged item>`.',
+                        changesMadeCodeAndChallenged: 'Coder produced unstaged/untracked edits only outside spec item files AND challenged one or more review items. Output shall include `challenges: <numbered rebuttals, one per challenged item>`.',
+                        changesMadeMixedAndChallenged: 'Coder produced unstaged/untracked edits spanning both spec item files and other files AND challenged one or more review items. Output shall include `challenges: <numbered rebuttals, one per challenged item>`.',
                         challengesRaised: 'Coder challenged one or more review items without producing any code edits. Output shall include `challenges: <numbered rebuttals, one per challenged item>`.',
                         accepted: 'Coder accepted the review outcome without further edits.',
                         needsBossReply: needsBossReplyDescription,
@@ -558,7 +558,7 @@ export const codingMachine = setup({
                         'Verify any affected spec items are:',
                         '',
                         '- Complete & coherent: sufficient for you to reimplement code.',
-                        '- Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+                        '- Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.',
                         '- Minimal: essential and concise; every item earns its place; also check with other items.',
                         '- Well organized: spec packages are finely scoped, with high cohesion and low coupling.',
                         '',
@@ -680,7 +680,7 @@ export const codingMachine = setup({
                         'Verify any affected spec items are:',
                         '',
                         '- Complete & coherent: sufficient for you to reimplement code.',
-                        '- Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+                        '- Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.',
                         '- Minimal: essential and concise; every item earns its place; also check with other items.',
                         '- Well organized: spec packages are finely scoped, with high cohesion and low coupling.',
                         '',
@@ -744,7 +744,7 @@ export const codingMachine = setup({
                         'Verify any affected spec items are:',
                         '',
                         '- Complete & coherent: sufficient for you to reimplement code.',
-                        '- Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+                        '- Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.',
                         '- Minimal: essential and concise; every item earns its place; also check with other items.',
                         '- Well organized: spec packages are finely scoped, with high cohesion and low coupling.',
                         '',
@@ -868,7 +868,7 @@ export const codingMachine = setup({
                         'Verify any affected spec items are:',
                         '',
                         '- Complete & coherent: sufficient for you to reimplement code.',
-                        '- Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+                        '- Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.',
                         '- Minimal: essential and concise; every item earns its place; also check with other items.',
                         '- Well organized: spec packages are finely scoped, with high cohesion and low coupling.',
                         '',
@@ -930,7 +930,7 @@ export const codingMachine = setup({
                         'Verify any affected spec items are:',
                         '',
                         '- Complete & coherent: sufficient for you to reimplement code.',
-                        '- Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+                        '- Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.',
                         '- Minimal: essential and concise; every item earns its place; also check with other items.',
                         '- Well organized: spec packages are finely scoped, with high cohesion and low coupling.',
                         '',
@@ -1030,7 +1030,7 @@ export const codingMachine = setup({
                         'Verify any affected spec items are:',
                         '',
                         '- Complete & coherent: sufficient for you to reimplement code.',
-                        '- Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+                        '- Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.',
                         '- Minimal: essential and concise; every item earns its place; also check with other items.',
                         '- Well organized: spec packages are finely scoped, with high cohesion and low coupling.',
                         '',
@@ -1084,7 +1084,7 @@ export const codingMachine = setup({
                         'Verify any affected spec items are:',
                         '',
                         '- Complete & coherent: sufficient for you to reimplement code.',
-                        '- Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+                        '- Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.',
                         '- Minimal: essential and concise; every item earns its place; also check with other items.',
                         '- Well organized: spec packages are finely scoped, with high cohesion and low coupling.',
                         '',
@@ -1190,7 +1190,7 @@ export const codingMachine = setup({
                         'Verify any affected spec items are:',
                         '',
                         '- Complete & coherent: sufficient for you to reimplement code.',
-                        '- Right level: user requirements (in @specs/user) or system behavior (in @specs/dev), not implementation specifics; integration/system testing (in @specs/test), not unit testing.',
+                        '- Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.',
                         '- Minimal: essential and concise; every item earns its place; also check with other items.',
                         '- Well organized: spec packages are finely scoped, with high cohesion and low coupling.',
                         '',
@@ -1306,15 +1306,16 @@ export const codingMachine = setup({
                     coderPlayer: context.coderPlayer,
                     committerPlayer: context.committerPlayer,
                     prompt: [
-                        'Make a commit of the changes that belong in the repo, following @specs/dev/git.md (reread if necessary).',
+                        'Make a commit of the changes that belong in the repo, following @specs/packages/git.md (reread if necessary).',
+                        "If that spec is absent, follow the legacy @specs/dev/git.md; if neither exists, follow the repository's existing commit conventions and do not search elsewhere.",
                         'Write the commit message concisely.',
                         'Coder is <coder-llm>.',
                         'Format the `Co-authored-by` `<model>` token as the conventional human form of the substituted id (e.g., `claude-opus-4-7` → `Claude-Opus-4.7`, `gpt-5.5` → `GPT-5.5`).',
                     ].join('\n'),
                     result: {
-                        committedSpecs: 'Committed changes that touch only @specs/{user,dev,test}/.',
-                        committedCode: 'Committed changes that touch only files outside @specs/{user,dev,test}/.',
-                        committedMixed: 'Committed changes that span both @specs/{user,dev,test}/ and other files.',
+                        committedSpecs: 'Committed changes that touch only spec item files (@specs/packages/, @specs/compositions/, or legacy @specs/{user,dev,test}/).',
+                        committedCode: 'Committed changes that touch only files that are not spec item files (any other files, including @specs/ decision, intent, or legacy iteration records, @specs/map.md, and @specs/meta.md).',
+                        committedMixed: 'Committed changes that span both spec item files and other files.',
                         noRelevantChanges: 'There are no relevant changes to commit.',
                         needsBossInput: 'Committing requires additional Boss input.',
                         needsBossReply: needsBossReplyDescription,
@@ -1381,7 +1382,8 @@ export const codingMachine = setup({
                     reviewerPlayer: context.reviewerPlayer,
                     committerPlayer: context.committerPlayer,
                     prompt: [
-                        'Make a commit of the changes that belong in the repo, following @specs/dev/git.md (reread if necessary).',
+                        'Make a commit of the changes that belong in the repo, following @specs/packages/git.md (reread if necessary).',
+                        "If that spec is absent, follow the legacy @specs/dev/git.md; if neither exists, follow the repository's existing commit conventions and do not search elsewhere.",
                         'Write the commit message concisely.',
                         'Coder is <coder-llm>; Reviewer is <reviewer-llm>.',
                         'Format the `Co-authored-by` `<model>` token as the conventional human form of the substituted id (e.g., `claude-opus-4-7` → `Claude-Opus-4.7`, `gpt-5.5` → `GPT-5.5`).',