mandrel 2.64.0 → 2.66.0

package/.agents/scripts/lib/bootstrap/project-bootstrap.js

@@ -11,6 +11,12 @@ import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { isCommandExcluded } from '../command-header.js';
 import { detectPackageManager as detectPm } from '../detect-package-manager.js';
+import {
+  SYSTEM_PROMPT_BLOCK,
+  SYSTEM_PROMPT_ENTRY_DOC,
+  SYSTEM_PROMPT_IMPORT,
+  wireEntryDoc,
+} from './agents-md-fold.js';
 import { LEDGER_RELATIVE_PATH } from './install-ledger.js';
 import { ensureIssueForms } from './issue-forms-template.js';
 import { PHASE_GROUPS } from './manifest.js';
@@ -23,17 +29,10 @@ export const SYNC_AGENTS_COMMAND = 'node .agents/scripts/sync-claude-agents.js';
 
 export const BOOTSTRAP_COMMAND = 'node .agents/scripts/bootstrap.js';
 
-/** `CLAUDE.md` wiring keys idempotence off this exact import path. */
-export const SYSTEM_PROMPT_IMPORT = '@.agents/instructions.md';
+export { SYSTEM_PROMPT_BLOCK, SYSTEM_PROMPT_IMPORT };
 
-export const SYSTEM_PROMPT_BLOCK = `## System Prompt
-
-${SYSTEM_PROMPT_IMPORT}
-`;
-
-export const SYSTEM_PROMPT_CLAUDE_MD = `# Agent Protocols
-
-${SYSTEM_PROMPT_BLOCK}`;
+/** Install template for a fresh AGENTS.md (also the legacy CLAUDE.md one). */
+export const SYSTEM_PROMPT_AGENTS_MD = SYSTEM_PROMPT_ENTRY_DOC;
 
 export const GITIGNORE_BLOCKS = Object.freeze({
   commands: {
@@ -81,6 +80,10 @@ function writeJson(p, obj, fsImpl = fs) {
   fsImpl.writeFileSync(p, `${JSON.stringify(obj, null, 2)}\n`, 'utf8');
 }
 
+function agentRootOf(ctx) {
+  return ctx.agentRoot ?? path.join(ctx.projectRoot, '.agents');
+}
+
 /**
  * Node floor SSOT (`node:sqlite` stabilised at 22.22.1); import it, never
  * duplicate. Matches `package.json` `engines.node` (`>=22.22.1 <25`).
@@ -127,9 +130,36 @@ export function detectPackageManager(projectRoot, fsImpl = fs) {
   return detectPm(projectRoot, (p) => fsImpl.existsSync(p)) ?? 'npm';
 }
 
+/** @returns {'added'|'already-present'} */
+function ensureScript(scripts, key, command) {
+  if (scripts[key]) return 'already-present';
+  scripts[key] = command;
+  return 'added';
+}
+
+/** Append each projection independently so a partial prepare gains the other. */
+function ensurePrepareScript(scripts) {
+  const prepare = scripts.prepare;
+  if (!prepare) {
+    scripts.prepare = `${SYNC_COMMAND} && ${SYNC_AGENTS_COMMAND}`;
+    return 'added';
+  }
+  let next = prepare;
+  if (!next.includes('sync-claude-commands.js')) {
+    next = `${next} && ${SYNC_COMMAND}`;
+  }
+  if (!next.includes('sync-claude-agents.js')) {
+    next = `${next} && ${SYNC_AGENTS_COMMAND}`;
+  }
+  if (next === prepare) return 'already-present';
+  scripts.prepare = next;
+  return 'appended';
+}
+
 /**
  * Ensure `package.json` carries the sync/prepare/bootstrap scripts. Never
  * touches `dependencies` — framework deps arrive transitively via `mandrel`.
+ * An operator-defined `bootstrap` script always wins.
  *
  * @param {object} ctx
  * @param {typeof fs} [ctx.fsImpl]
@@ -137,62 +167,32 @@ export function detectPackageManager(projectRoot, fsImpl = fs) {
 export function ensurePackageJson(ctx) {
   const { fsImpl = fs } = ctx;
   const pkgPath = path.join(ctx.projectRoot, 'package.json');
-  const projectName = path.basename(path.resolve(ctx.projectRoot));
-  const outcomes = {
-    created: false,
-    scriptsSyncCommands: 'already-present',
-    scriptsSyncAgents: 'already-present',
-    scriptsPrepare: 'already-present',
-    scriptsBootstrap: 'already-present',
+  const existing = readJsonIfExists(pkgPath, fsImpl);
+  const pkg = existing || {
+    name: path.basename(path.resolve(ctx.projectRoot)),
+    version: '0.0.0',
+    private: true,
+    type: 'module',
   };
-  let pkg = readJsonIfExists(pkgPath, fsImpl);
-  if (!pkg) {
-    pkg = {
-      name: projectName,
-      version: '0.0.0',
-      private: true,
-      type: 'module',
-    };
-    outcomes.created = true;
-  }
   pkg.scripts = pkg.scripts ?? {};
-  if (!pkg.scripts['sync:commands']) {
-    pkg.scripts['sync:commands'] = SYNC_COMMAND;
-    outcomes.scriptsSyncCommands = 'added';
-  }
-  if (!pkg.scripts['sync:agents']) {
-    pkg.scripts['sync:agents'] = SYNC_AGENTS_COMMAND;
-    outcomes.scriptsSyncAgents = 'added';
-  }
-  const prepare = pkg.scripts.prepare;
-  if (!prepare) {
-    pkg.scripts.prepare = `${SYNC_COMMAND} && ${SYNC_AGENTS_COMMAND}`;
-    outcomes.scriptsPrepare = 'added';
-  } else {
-    // Append each projection independently so a partial prepare gains the other.
-    let next = prepare;
-    if (!next.includes('sync-claude-commands.js')) {
-      next = `${next} && ${SYNC_COMMAND}`;
-    }
-    if (!next.includes('sync-claude-agents.js')) {
-      next = `${next} && ${SYNC_AGENTS_COMMAND}`;
-    }
-    if (next !== prepare) {
-      pkg.scripts.prepare = next;
-      outcomes.scriptsPrepare = 'appended';
-    }
-  }
-  // An operator-defined `bootstrap` script always wins.
-  if (!pkg.scripts.bootstrap) {
-    pkg.scripts.bootstrap = BOOTSTRAP_COMMAND;
-    outcomes.scriptsBootstrap = 'added';
-  }
-  const mutated =
-    outcomes.created ||
-    outcomes.scriptsSyncCommands === 'added' ||
-    outcomes.scriptsSyncAgents === 'added' ||
-    outcomes.scriptsPrepare !== 'already-present' ||
-    outcomes.scriptsBootstrap === 'added';
+  const outcomes = {
+    created: !existing,
+    scriptsSyncCommands: ensureScript(
+      pkg.scripts,
+      'sync:commands',
+      SYNC_COMMAND,
+    ),
+    scriptsSyncAgents: ensureScript(
+      pkg.scripts,
+      'sync:agents',
+      SYNC_AGENTS_COMMAND,
+    ),
+    scriptsPrepare: ensurePrepareScript(pkg.scripts),
+    scriptsBootstrap: ensureScript(pkg.scripts, 'bootstrap', BOOTSTRAP_COMMAND),
+  };
+  const mutated = Object.values(outcomes).some(
+    (v) => v === true || v === 'added' || v === 'appended',
+  );
   if (mutated) writeJson(pkgPath, pkg, fsImpl);
   return { ...outcomes, path: pkgPath, mutated };
 }
@@ -247,10 +247,7 @@ export function ensureAgentrc(ctx) {
   if (fsImpl.existsSync(target)) {
     return { action: 'already-present', path: target };
   }
-  const starter = path.join(
-    ctx.agentRoot ?? path.join(ctx.projectRoot, '.agents'),
-    'starter-agentrc.json',
-  );
+  const starter = path.join(agentRootOf(ctx), 'starter-agentrc.json');
   if (!fsImpl.existsSync(starter)) {
     return { action: 'missing-starter', path: target };
   }
@@ -270,16 +267,28 @@ export function ensureAgentrc(ctx) {
   return { action: 'seeded', path: target, source: 'starter' };
 }
 
+async function loadAgentrcValidator(schemaModule) {
+  // pathToFileURL handles Windows drive letters and percent-encoding.
+  const mod = await import(pathToFileURL(schemaModule).href);
+  return mod.getAgentrcValidator();
+}
+
+function agentrcVerdict(validate, data) {
+  if (!data) return { ok: false, errors: ['.agentrc.json missing'] };
+  const ok = validate(data);
+  return { ok: !!ok, errors: ok ? [] : (validate.errors ?? []) };
+}
+
 /**
  * Validate `.agentrc.json` against the AJV schema; the caller decides whether to abort.
  *
  * @param {object} ctx
  * @param {typeof fs} [ctx.fsImpl]
  */
-export async function validateAgentrc(ctx) {
+async function validateAgentrc(ctx) {
   const { fsImpl = fs } = ctx;
   const schemaModule = path.join(
-    ctx.agentRoot ?? path.join(ctx.projectRoot, '.agents'),
+    agentRootOf(ctx),
     'scripts',
     'lib',
     'config-settings-schema.js',
@@ -287,16 +296,12 @@ export async function validateAgentrc(ctx) {
   if (!fsImpl.existsSync(schemaModule)) {
     return { ok: false, errors: ['config-settings-schema.js not found'] };
   }
-  // pathToFileURL handles Windows drive letters and percent-encoding.
-  const mod = await import(pathToFileURL(schemaModule).href);
-  const validate = mod.getAgentrcValidator();
+  const validate = await loadAgentrcValidator(schemaModule);
   const data = readJsonIfExists(
     path.join(ctx.projectRoot, '.agentrc.json'),
     fsImpl,
   );
-  if (!data) return { ok: false, errors: ['.agentrc.json missing'] };
-  const ok = validate(data);
-  return { ok: !!ok, errors: ok ? [] : (validate.errors ?? []) };
+  return agentrcVerdict(validate, data);
 }
 
 /**
@@ -348,12 +353,9 @@ function ensureIssueFormsPhase(ctx) {
  * @param {object} ctx
  * @param {typeof defaultSpawnSync} [ctx.spawnImpl]
  */
-export function runSyncCommands(ctx) {
+function runSyncCommands(ctx) {
   const { spawnImpl = defaultSpawnSync } = ctx;
-  const scriptsDir = path.join(
-    ctx.agentRoot ?? path.join(ctx.projectRoot, '.agents'),
-    'scripts',
-  );
+  const scriptsDir = path.join(agentRootOf(ctx), 'scripts');
   const projections = [
     { label: 'sync-claude-commands.js', script: 'sync-claude-commands.js' },
     { label: 'sync-claude-agents.js', script: 'sync-claude-agents.js' },
@@ -391,10 +393,7 @@ export function runSyncCommands(ctx) {
  */
 export function checkParity(ctx) {
   const { fsImpl = fs } = ctx;
-  const workflowsDir = path.join(
-    ctx.agentRoot ?? path.join(ctx.projectRoot, '.agents'),
-    'workflows',
-  );
+  const workflowsDir = path.join(agentRootOf(ctx), 'workflows');
   const commandsDir = path.join(ctx.projectRoot, '.claude', 'commands');
   const list = (dir) =>
     fsImpl.existsSync(dir)
@@ -420,30 +419,15 @@ export function checkParity(ctx) {
 }
 
 /**
- * Ensure `CLAUDE.md` imports the system prompt — without it the framework
- * never loads on cold start. Creates, appends, or no-ops.
+ * Ensure `AGENTS.md` imports the system prompt — without it the framework
+ * never loads on cold start. A pre-existing `CLAUDE.md` is folded in first
+ * (the host would otherwise read it instead). Creates, appends, or no-ops.
  *
  * @param {object} ctx
  * @param {typeof fs} [ctx.fsImpl]
  */
 export function ensureSystemPromptWiring(ctx) {
-  const { fsImpl = fs } = ctx;
-  const target = path.join(ctx.projectRoot, 'CLAUDE.md');
-  if (!fsImpl.existsSync(target)) {
-    fsImpl.writeFileSync(target, SYSTEM_PROMPT_CLAUDE_MD, 'utf8');
-    return { action: 'created', path: target };
-  }
-  const existing = fsImpl.readFileSync(target, 'utf8');
-  if (existing.includes(SYSTEM_PROMPT_IMPORT)) {
-    return { action: 'already-present', path: target };
-  }
-  const separator = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
-  fsImpl.writeFileSync(
-    target,
-    `${existing}${separator}\n${SYSTEM_PROMPT_BLOCK}`,
-    'utf8',
-  );
-  return { action: 'appended', path: target };
+  return wireEntryDoc(ctx.projectRoot, ctx.fsImpl);
 }
 
 /**
@@ -453,13 +437,13 @@ export function ensureSystemPromptWiring(ctx) {
  * @param {typeof fs} [ctx.fsImpl]
  * @param {typeof defaultSpawnSync} [ctx.spawnImpl]
  */
-export function checkWindowsGitPerf(ctx) {
+function checkWindowsGitPerf(ctx) {
   const { fsImpl = fs, spawnImpl = defaultSpawnSync } = ctx;
-  if (os.platform() !== 'win32') {
+  if ((ctx.platform ?? os.platform()) !== 'win32') {
     return { platform: process.platform, skipped: true };
   }
   const script = path.join(
-    ctx.agentRoot ?? path.join(ctx.projectRoot, '.agents'),
+    agentRootOf(ctx),
     'scripts',
     'check-windows-git-perf.js',
   );

package/.agents/scripts/lib/cli/standard-args.js

@@ -24,13 +24,26 @@ const SUPPORTED_FLAGS = Object.freeze({
 
 const FLAG_NAMES = Object.keys(SUPPORTED_FLAGS);
 
-const SUPPORTED_EXTRAS_TYPES = new Set([
-  'string',
-  'boolean',
-  'ticket',
-  'integer',
-  'string-multi',
-]);
+const isNullish = (v) => v === null || v === undefined;
+
+/** Per-type rules shared by built-in and extra flags. */
+const FLAG_TYPES = Object.freeze({
+  string: {
+    normalise: (v, orDefault) =>
+      typeof v === 'string' && v.length > 0 ? v : orDefault(null),
+    isAbsent: (v) => isNullish(v) || v === '',
+  },
+  boolean: { normalise: (v) => v === true, isAbsent: (v) => !v },
+  ticket: { normalise: (v) => parseTicketId(v), isAbsent: isNullish },
+  integer: {
+    normalise: (v, orDefault) => (v === undefined ? orDefault(undefined) : v),
+    isAbsent: (v) => v === undefined || Number.isNaN(v),
+  },
+  'string-multi': {
+    normalise: (v, orDefault) => (Array.isArray(v) ? v : orDefault([])),
+    isAbsent: (v) => !Array.isArray(v) || v.length === 0,
+  },
+});
 
 function camelCase(name) {
   return name.replace(/-([a-z])/g, (_m, c) => c.toUpperCase());
@@ -50,16 +63,33 @@ function normaliseCallSignature(opts) {
   return { argv: argv ?? [], schema, extras };
 }
 
-function buildDefineFlagsSpec(extras) {
+function flagEntries(schema, extras) {
+  const entries = Object.entries(SUPPORTED_FLAGS).map(
+    ([flag, { key, type }]) => ({
+      flag,
+      key,
+      type,
+      def: {},
+      required: schema?.[flag]?.required === true,
+    }),
+  );
+  for (const [flag, def] of Object.entries(extras ?? {})) {
+    entries.push({
+      flag,
+      key: def.alias ?? camelCase(flag),
+      type: def.type,
+      def,
+      required: def.required === true,
+    });
+  }
+  return entries;
+}
+
+function buildDefineFlagsSpec(entries) {
   const spec = {};
-  for (const [flag, { key, type }] of Object.entries(SUPPORTED_FLAGS)) {
+  for (const { flag, key, type, def } of entries) {
     spec[flag] = { type, alias: key };
-  }
-  if (!extras) return spec;
-  for (const [flag, def] of Object.entries(extras)) {
-    const entry = { type: def.type, alias: def.alias ?? camelCase(flag) };
-    if ('default' in def) entry.default = def.default;
-    spec[flag] = entry;
+    if ('default' in def) spec[flag].default = def.default;
   }
   return spec;
 }
@@ -119,10 +149,10 @@ function validateExtras(extras) {
         `parseStandardCliArgs: extras["${flag}"] must be an object`,
       );
     }
-    if (!SUPPORTED_EXTRAS_TYPES.has(def.type)) {
+    if (!Object.hasOwn(FLAG_TYPES, def.type)) {
       const err = new Error(
         `parseStandardCliArgs: extras["${flag}"].type "${def.type}" is unsupported. ` +
-          `Supported: ${[...SUPPORTED_EXTRAS_TYPES].join(', ')}.`,
+          `Supported: ${Object.keys(FLAG_TYPES).join(', ')}.`,
       );
       err.code = 'UNKNOWN_EXTRAS_TYPE';
       throw err;
@@ -130,15 +160,6 @@ function validateExtras(extras) {
   }
 }
 
-function isAbsent(type, cur) {
-  if (type === 'ticket') return cur === null || cur === undefined;
-  if (type === 'string') return cur === null || cur === undefined || cur === '';
-  if (type === 'boolean') return !cur;
-  if (type === 'integer') return cur === undefined || Number.isNaN(cur);
-  if (type === 'string-multi') return !Array.isArray(cur) || cur.length === 0;
-  return cur === undefined || cur === null;
-}
-
 function throwMissing(flag) {
   const err = new Error(
     `parseStandardCliArgs: missing required flag --${flag}`,
@@ -148,56 +169,19 @@ function throwMissing(flag) {
   throw err;
 }
 
-function enforceRequired(values, schema) {
-  if (!schema) return;
-  for (const [flag, rule] of Object.entries(schema)) {
-    if (!rule || rule.required !== true) continue;
-    const meta = SUPPORTED_FLAGS[flag];
-    if (isAbsent(meta.type, values[meta.key])) throwMissing(flag);
-  }
-}
-
-function enforceExtrasRequired(values, extras) {
-  if (!extras) return;
-  for (const [flag, def] of Object.entries(extras)) {
-    if (!def || def.required !== true) continue;
-    const key = def.alias ?? camelCase(flag);
-    if (isAbsent(def.type, values[key])) throwMissing(flag);
+function normaliseValues(raw, entries) {
+  const out = {};
+  for (const { key, type, def } of entries) {
+    const orDefault = (empty) => ('default' in def ? def.default : empty);
+    out[key] = FLAG_TYPES[type].normalise(raw[key], orDefault);
   }
+  return out;
 }
 
-/** Absent strings become `null` and booleans strict `false`. */
-function normaliseValues(raw, extras) {
-  const out = {};
-  for (const [, { key, type }] of Object.entries(SUPPORTED_FLAGS)) {
-    let v = raw[key];
-    if (type === 'ticket') {
-      v = parseTicketId(v);
-    } else if (type === 'string') {
-      v = typeof v === 'string' && v.length > 0 ? v : null;
-    } else if (type === 'boolean') {
-      v = v === true;
-    }
-    out[key] = v;
+function enforceRequired(values, entries) {
+  for (const { flag, key, type, required } of entries) {
+    if (required && FLAG_TYPES[type].isAbsent(values[key])) throwMissing(flag);
   }
-  if (!extras) return out;
-  for (const [flag, def] of Object.entries(extras)) {
-    const key = def.alias ?? camelCase(flag);
-    let v = raw[key];
-    if (def.type === 'boolean') {
-      v = v === true;
-    } else if (def.type === 'string') {
-      if (v === undefined) v = 'default' in def ? def.default : null;
-    } else if (def.type === 'ticket') {
-      v = parseTicketId(v);
-    } else if (def.type === 'string-multi') {
-      if (!Array.isArray(v)) v = 'default' in def ? def.default : [];
-    } else if (def.type === 'integer') {
-      if (v === undefined && 'default' in def) v = def.default;
-    }
-    out[key] = v;
-  }
-  return out;
 }
 
 /**
@@ -222,13 +206,13 @@ export function parseStandardCliArgs(opts = {}) {
     err.flag = unknown;
     throw err;
   }
+  const entries = flagEntries(schema, extras);
   const { values: raw, positionals } = defineFlags(
-    buildDefineFlagsSpec(extras),
+    buildDefineFlagsSpec(entries),
     argv,
   );
-  const values = normaliseValues(raw, extras);
-  enforceRequired(values, schema);
-  enforceExtrasRequired(values, extras);
+  const values = normaliseValues(raw, entries);
+  enforceRequired(values, entries);
   return { values, positionals };
 }
 

package/.agents/scripts/lib/cli-args.js

@@ -133,6 +133,30 @@ function tolerantOverrideReviewBlock(value) {
   }
 }
 
+/**
+ * Best-effort: absent or junk is `null` plus a warning, never a throw.
+ *
+ * @param {unknown} value
+ * @returns {{ tokens: number|null, warning: string|null }}
+ */
+export function parseWorkerTokens(value) {
+  if (value == null) {
+    return {
+      tokens: null,
+      warning:
+        '--worker-tokens not supplied; telemetry.workerTokens records null.',
+    };
+  }
+  const raw = String(value).trim();
+  if (/^\d+$/.test(raw) && Number.isSafeInteger(Number(raw))) {
+    return { tokens: Number(raw), warning: null };
+  }
+  return {
+    tokens: null,
+    warning: `--worker-tokens must be a non-negative integer (got ${JSON.stringify(value)}); telemetry.workerTokens records null.`,
+  };
+}
+
 /**
  * Throws when a validating flag parser rejects a value; error handlers use
  * {@link parseSprintArgsTolerant} instead of re-calling this.
@@ -164,6 +188,7 @@ export function parseSprintArgs(
       'merge-watch-mode': { type: 'string' },
       'rerun-advisory': { type: 'string' },
       'override-review-block': { type: 'string' },
+      'worker-tokens': { type: 'string' },
       executor: { type: 'string' },
       cwd: { type: 'string' },
       'recut-of': { type: 'string' },
@@ -194,6 +219,7 @@ export function parseSprintArgs(
     overrideReviewBlock: tolerant
       ? tolerantOverrideReviewBlock(values['override-review-block'])
       : parseOverrideReviewBlock(values['override-review-block']),
+    workerTokens: values['worker-tokens'],
     executor: values.executor ?? null,
     cwd:
       (typeof values.cwd === 'string' && values.cwd.trim()) ||

package/.agents/scripts/lib/config/gates/shared.js

@@ -23,7 +23,7 @@ export const LIST_OR_EXTENDER_OF_STRINGS = {
   ],
 };
 
-export const TOLERANCE_SCHEMA = {
+const TOLERANCE_SCHEMA = {
   type: 'object',
   description:
     'How much a rollup may drift from the committed baseline before the gate reports a regression.',
@@ -47,7 +47,7 @@ export const TOLERANCE_SCHEMA = {
 /**
  * `"*"` is optional: the resolver injects the framework default when absent.
  */
-export const FLOORS_SCHEMA = {
+const FLOORS_SCHEMA = {
   type: 'object',
   description:
     'Workspace-keyed absolute floors: `{ "<workspace>": { "<metric>": number } }`. `"*"` is the project-wide catch-all; the metric keyset is open so per-rollup keys flow through without each gate enumerating them. Floors are absolute — unlike `tolerance`, they are enforced regardless of the baseline.',
@@ -57,7 +57,7 @@ export const FLOORS_SCHEMA = {
   },
 };
 
-export const COMPONENTS_SCHEMA = {
+const COMPONENTS_SCHEMA = {
   type: 'object',
   description:
     'Per-gate component map — component name to the glob list whose files roll up under it. Defaults to `{ "*": ["**"] }` at the resolver layer.',

package/.agents/scripts/lib/config/review-chain-default.js

@@ -0,0 +1,13 @@
+/**
+ * The one default review chain: the factory's unset/empty fallback and the
+ * runtime schema's declared default. `code-review` is `optional` so hosts
+ * without the `claude` CLI close on `native` alone.
+ */
+export const DEFAULT_REVIEW_PROVIDERS = Object.freeze([
+  Object.freeze({ name: 'native' }),
+  Object.freeze({
+    name: 'code-review',
+    scopes: Object.freeze(['story']),
+    optional: true,
+  }),
+]);

package/.agents/scripts/lib/config-settings-schema-delivery.js

@@ -140,7 +140,7 @@ const WORKTREE_ISOLATION_SCHEMA = {
 const MERGE_WATCH_SCHEMA = {
   type: 'object',
   description:
-    "Knobs consumed by the close-and-land merge wait (Story #4543). `mode` (Story #4698) selects the close-time merge posture. `maxWaitSeconds` bounds ONE invocation of the merge wait and its expiry returns a resumable `pending` terminal with no label mutation; `maxBudgetSeconds` bounds the CUMULATIVE wait across resumes (anchored at the PR's createdAt, so a resume does not restart the clock) and exhausting it is the genuine give-up that classifies and blocks. The 30s poll cadence and the cap of 3 behind-the-base updates are fixed.",
+    "Knobs consumed by the close-and-land merge wait (Story #4543). `mode` (Story #4698) selects the close-time merge posture. `maxWaitSeconds` bounds ONE invocation of the merge wait and its expiry returns a resumable `pending` terminal with no label mutation; `maxBudgetSeconds` bounds the CUMULATIVE wait across resumes (anchored at the PR's createdAt, so a resume does not restart the clock) and exhausting it is the genuine give-up that classifies and blocks. The poll cadence is internal (at most 30s while checks run, at most 10s once they are green and the PR is unmerged); it and the cap of 3 behind-the-base updates are not configurable.",
   properties: {
     mode: {
       type: 'string',
@@ -173,7 +173,7 @@ const ROUTING_SCHEMA = {
     roleScopedAgents: {
       type: 'boolean',
       description:
-        'Epic #4478 (M7-B). Kill-switch for the role-scoped boot contexts. When true (default), a converted delivery spawn (`story-worker`, `acceptance-critic`) boots on its own `.claude/agents/<role>.md` system prompt instead of re-paying the full CLAUDE.md @-import closure. When false, every converted spawn falls back to `subagent_type: general-purpose` — the instant, code-rollback-free per-consumer revert, and the universal escape for hosts that ignore `.claude/agents/`. The fallback is the full-closure agent that ran before M7-B, so flipping it off never drops a gate.',
+        'Epic #4478 (M7-B). Kill-switch for the role-scoped boot contexts. When true (default), a converted delivery spawn (`story-worker`, `acceptance-critic`) boots on its own `.claude/agents/<role>.md` system prompt instead of re-paying the full entry-doc (AGENTS.md or CLAUDE.md) @-import closure. When false, every converted spawn falls back to `subagent_type: general-purpose` — the instant, code-rollback-free per-consumer revert, and the universal escape for hosts that ignore `.claude/agents/`. The fallback is the full-closure agent that ran before M7-B, so flipping it off never drops a gate.',
       default: DELIVERY_ROUTING_DEFAULTS.roleScopedAgents,
     },
     ceremonyProfile: {

package/.agents/scripts/lib/config-settings-schema-quality.js

@@ -4,6 +4,7 @@
 // live in `config/gates/`.
 
 import { GATES_SCHEMA } from './config/gates/index.js';
+import { DEFAULT_REVIEW_PROVIDERS } from './config/review-chain-default.js';
 import { DEFAULT_CODE_REVIEW } from './config/runners.js';
 
 const AUTO_REFRESH_SCHEMA = {
@@ -80,9 +81,15 @@ export const CODE_REVIEW_SCHEMA = {
         properties: {
           name: {
             type: 'string',
-            enum: ['native', 'codex', 'security-review', 'ultrareview'],
+            enum: [
+              'native',
+              'code-review',
+              'codex',
+              'security-review',
+              'ultrareview',
+            ],
             description:
-              'Registered provider key. Inline: native, codex, security-review. Manual-prompt: ultrareview.',
+              'Registered provider key. Inline: native, code-review, codex, security-review. Manual-prompt: ultrareview.',
           },
           scopes: {
             type: 'array',
@@ -125,17 +132,8 @@ export const CODE_REVIEW_SCHEMA = {
         additionalProperties: false,
       },
       description:
-        'Review-provider chain (Story #2871). When unset or empty, defaults to [{ name: "native" }]. The orchestrator iterates inline entries in declaration order and merges their Finding[] before posting one structured comment; manual-prompt entries (e.g. ultrareview) contribute a trailing \'Manual review suggestions\' section. Selecting an adapter whose probe fails hard-fails at factory construction unless declared `optional: true` in the chain.',
-      default: [
-        { name: 'native' },
-        { name: 'security-review', scopes: ['story'], optional: true },
-        {
-          name: 'ultrareview',
-          scopes: ['story'],
-          manualPrompt: true,
-          when: { label: 'risk::high' },
-        },
-      ],
+        "Review-provider chain (Story #2871). When unset or empty, falls back to this default: `native` (scoped lint + MI) then an optional story-scoped `code-review` — a low-effort `claude --print` bug review whose every finding is critical and halts close before auto-merge; hosts without the `claude` CLI skip it. `security-review` and `ultrareview` are opt-in. The orchestrator iterates inline entries in declaration order and merges their Finding[] before posting one structured comment; manual-prompt entries (e.g. ultrareview) contribute a trailing 'Manual review suggestions' section. Selecting an adapter whose probe fails hard-fails at factory construction unless declared `optional: true` in the chain.",
+      default: DEFAULT_REVIEW_PROVIDERS,
     },
     autoFixSeverity: {
       type: 'string',