@sublang/playbook 2.0.0 → 3.1.0

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

@@ -21,13 +21,15 @@ import {
 } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { isAbsolute, join, resolve } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 import {
   Cligent,
   isEffortSupported,
   supportedEffortValues,
 } from '@sublang/cligent';
 import { parse as parseYaml } from 'yaml';
+import { hiddenControlEnvelope } from '../../../../src/xstate-runtime.js';
+import { provisionEngine } from './provision.js';
 
 // PBCLI-19: adapter shorthands the run host can construct.
 const ADAPTER_LOADERS = {
@@ -75,6 +77,9 @@ export async function runPlaybookRun(options = {}) {
     readStdin,
     sessionsDir,
     userConfigPath,
+    // PBCLI-37: injected host package roots let tests provision against
+    // synthetic trees, like the injected session store.
+    hostRoots: options.hostRoots,
   };
 
   let args;
@@ -100,6 +105,11 @@ async function runFirst(args, ctx) {
     return { code: EXIT.arg };
   }
 
+  // PBCLI-36/37 (DR-024): provision engine links for a filesystem module
+  // before importing it; a resolvable engine is never touched.
+  const provisioned = await maybeProvision(args.from, args, ctx);
+  if (provisioned.code !== undefined) return provisioned;
+
   const loaded = await loadRegistryEntry(args.from, ctx);
   if (loaded.code !== undefined) return loaded;
   const { entry } = loaded;
@@ -245,6 +255,11 @@ async function runResume(args, ctx) {
     return { code: EXIT.arg };
   }
 
+  // PBCLI-37: a stored filesystem `from` (a file: URL) is probed and
+  // provisioned on resume exactly as on a first run.
+  const provisioned = await maybeProvision(record.from, args, ctx);
+  if (provisioned.code !== undefined) return provisioned;
+
   const loaded = await loadRegistryEntry(record.from, ctx);
   if (loaded.code !== undefined) return loaded;
   const { entry } = loaded;
@@ -361,9 +376,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 +602,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
@@ -851,6 +890,7 @@ export function parseRunArgs(argv) {
     cwd: undefined,
     json: false,
     verbose: false,
+    noProvision: false,
     help: false,
   };
   const positionals = [];
@@ -859,6 +899,7 @@ export function parseRunArgs(argv) {
     if (arg === '--help' || arg === '-h') args.help = true;
     else if (arg === '--json') args.json = true;
     else if (arg === '--verbose') args.verbose = true;
+    else if (arg === '--no-provision') args.noProvision = true;
     else if (arg === '--last') args.last = true;
     else if (arg === '--cwd') args.cwd = takeValue(argv, (i += 1), '--cwd');
     else if (arg === '--captain')
@@ -936,6 +977,36 @@ function registryImportSpecifier(specifier, cwd) {
   return specifier;
 }
 
+// PBCLI-37: the absolute file path of a filesystem `<from>` (path or
+// file: URL), or undefined for a bare package specifier — those resolve
+// from the host's own module tree and are neither probed nor provisioned.
+function moduleFilePath(specifier, cwd) {
+  if (specifier.startsWith('file:')) return fileURLToPath(specifier);
+  if (
+    isAbsolute(specifier) ||
+    specifier.startsWith('./') ||
+    specifier.startsWith('../') ||
+    specifier.startsWith('.\\') ||
+    specifier.startsWith('..\\')
+  ) {
+    return resolve(cwd, specifier);
+  }
+  return undefined;
+}
+
+// PBCLI-36/37: probe-and-provision for a filesystem registry module.
+// Returns {} to proceed or { code } after a reported provisioning fault.
+async function maybeProvision(specifier, args, ctx) {
+  const modulePath = moduleFilePath(specifier, ctx.cwdDefault);
+  if (modulePath === undefined) return {};
+  return provisionEngine({
+    modulePath,
+    stderr: ctx.stderr,
+    enabled: !args.noProvision,
+    hostRoots: ctx.hostRoots,
+  });
+}
+
 function isValidRegistryEntry(value) {
   return (
     typeof value === 'object' &&
@@ -975,6 +1046,8 @@ function runHelpText() {
     '                            output or questions) instead of plain text',
     '  --last                    resume the most recently parked session',
     '  --verbose                 forward telemetry topics to stderr',
+    '  --no-provision            never create engine links beside a',
+    '                            filesystem <from> module',
     '  -h, --help                print this help',
     '',
     '  <agent> is <adapter>[:<model>][@<effort>] over the shorthands',

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`).',

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

@@ -191,29 +191,29 @@ const stateDescriptions = {
   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}/.',
+    '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 @specs/{user,dev,test}/.',
+    '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 @specs/{user,dev,test}/ and other files.',
+    '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 @specs/{user,dev,test}/.',
+    '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 @specs/{user,dev,test}/.',
+    '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 @specs/{user,dev,test}/ and other files.',
+    '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 @specs/{user,dev,test}/ with no accompanying rebuttals.',
+    '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 @specs/{user,dev,test}/ with no accompanying rebuttals.',
+    '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 @specs/{user,dev,test}/ and other files with no accompanying rebuttals.',
+    '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 @specs/{user,dev,test}/ and adjudicates accompanying rebuttals in one round.',
+    '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 @specs/{user,dev,test}/ and adjudicates accompanying rebuttals in one round.',
+    '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 @specs/{user,dev,test}/ and other files and adjudicates accompanying rebuttals in one round.',
+    '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:
@@ -354,7 +354,7 @@ const planAndImplementInput: PlayerInputFactory = (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.',
@@ -396,9 +396,9 @@ const summarizeSpecsInput: PlayerInputFactory = (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.',
@@ -408,7 +408,7 @@ const summarizeSpecsInput: PlayerInputFactory = (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.',
   }),
 });
 
@@ -656,17 +656,17 @@ export const codingMachine = setup({
           ].join('\n'),
           result: {
             changesMadeSpecs:
-              'Coder accepted items and produced unstaged/untracked edits in @specs/{user,dev,test}/ only, without raising any rebuttals.',
+              '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 outside @specs/{user,dev,test}/ only, without raising any rebuttals.',
+              '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 @specs/{user,dev,test}/ and other files, without raising any rebuttals.',
+              '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 in @specs/{user,dev,test}/ only AND challenged one or more review items. Output shall include `challenges: <numbered rebuttals, one per challenged item>`.',
+              '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 outside @specs/{user,dev,test}/ only AND challenged one or more review items. Output shall include `challenges: <numbered rebuttals, one per challenged item>`.',
+              '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 @specs/{user,dev,test}/ and other files AND challenged one or more review items. Output shall include `challenges: <numbered rebuttals, one per challenged item>`.',
+              '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:
@@ -831,7 +831,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.',
             '',
@@ -957,7 +957,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.',
             '',
@@ -1023,7 +1023,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.',
             '',
@@ -1151,7 +1151,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.',
             '',
@@ -1215,7 +1215,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.',
             '',
@@ -1321,7 +1321,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.',
             '',
@@ -1377,7 +1377,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.',
             '',
@@ -1492,7 +1492,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.',
             '',
@@ -1621,18 +1621,19 @@ 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}/.',
+              '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 outside @specs/{user,dev,test}/.',
+              '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 @specs/{user,dev,test}/ and other files.',
+              '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,
@@ -1700,7 +1701,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`).',