mandrel 2.64.0 → 2.66.0

package/docs/CHANGELOG.md

@@ -15,6 +15,63 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.66.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.65.0...mandrel-v2.66.0) (2026-09-26)
+
+
+### Added
+
+* record per-Story retry causes and per-provider review halts at close ([#5435](https://github.com/dsj1984/mandrel/issues/5435)) ([#5441](https://github.com/dsj1984/mandrel/issues/5441)) ([c7bfd5a](https://github.com/dsj1984/mandrel/commit/c7bfd5ab2be417889f45a85f92145704ac580b88))
+
+
+### Fixed
+
+* make the quality instruments fail loudly instead of silently mis-measuring, and reclaim floor slack ([#5444](https://github.com/dsj1984/mandrel/issues/5444)) ([#5452](https://github.com/dsj1984/mandrel/issues/5452)) ([54eb9fd](https://github.com/dsj1984/mandrel/commit/54eb9fd4660a0476740e0f96daae34e7f1fc754f))
+
+
+### Performance
+
+* stop tests and CLI start-up from spending real wall-clock on host state and sleeps ([#5445](https://github.com/dsj1984/mandrel/issues/5445)) ([#5451](https://github.com/dsj1984/mandrel/issues/5451)) ([8f74d51](https://github.com/dsj1984/mandrel/commit/8f74d51da489b3cc96a0c23053338a718a68708c))
+
+
+### Changed
+
+* burn down the bootstrap hotspots across CRAP, cyclomatic and dead exports ([#5447](https://github.com/dsj1984/mandrel/issues/5447)) ([#5455](https://github.com/dsj1984/mandrel/issues/5455)) ([be9e666](https://github.com/dsj1984/mandrel/commit/be9e6665011547be9396670f9a7486951ca1cd81))
+* burn down the orchestration and signals complexity outliers ([#5449](https://github.com/dsj1984/mandrel/issues/5449)) ([#5456](https://github.com/dsj1984/mandrel/issues/5456)) ([208cede](https://github.com/dsj1984/mandrel/commit/208cede77cb8186bf479cb6e190b8e2849347bbf))
+* collapse duplicated CLI plumbing: standard-args flag switches and the sync-agents/sync-commands clone ([#5448](https://github.com/dsj1984/mandrel/issues/5448)) ([#5454](https://github.com/dsj1984/mandrel/issues/5454)) ([5df933b](https://github.com/dsj1984/mandrel/commit/5df933b7c567730eae0ed47b172a8ac670d0831e))
+* decompose the single-story-close and confirm-merge hot path ([#5446](https://github.com/dsj1984/mandrel/issues/5446)) ([#5453](https://github.com/dsj1984/mandrel/issues/5453)) ([3b7a5ae](https://github.com/dsj1984/mandrel/commit/3b7a5ae2b7391e16dddfd18d64e7fe4528bdc48c))
+* trim the always-on closure and document the effort policy ([#5437](https://github.com/dsj1984/mandrel/issues/5437)) ([#5439](https://github.com/dsj1984/mandrel/issues/5439)) ([61d3c66](https://github.com/dsj1984/mandrel/commit/61d3c666637d38144cee7abcc7a50f28c332201a))
+
+## [2.65.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.64.0...mandrel-v2.65.0) (2026-09-24)
+
+
+### ⚠ BREAKING CHANGES
+
+* consumers must run Claude Code >= 2.1.277, which loads a root AGENTS.md; `mandrel update` folds the root CLAUDE.md into AGENTS.md and deletes CLAUDE.md.
+
+### Added
+
+* add a low-effort model bug review to close and pin role-agent effort ([#5426](https://github.com/dsj1984/mandrel/issues/5426)) ([#5431](https://github.com/dsj1984/mandrel/issues/5431)) ([ec39643](https://github.com/dsj1984/mandrel/commit/ec3964390210e140ebaa324bbfe27b67fd470fa4))
+* **audit-quality:** add a property-based coverage dimension (refs [#5425](https://github.com/dsj1984/mandrel/issues/5425)) ([#5428](https://github.com/dsj1984/mandrel/issues/5428)) ([f78fd62](https://github.com/dsj1984/mandrel/commit/f78fd62edda9060580b1cbacaec1cc82875040d1))
+* cut consumers over to AGENTS.md: bootstrap wiring, CLAUDE.md fold migration, uninstall revert, Claude Code version doctor check ([#5410](https://github.com/dsj1984/mandrel/issues/5410)) ([#5411](https://github.com/dsj1984/mandrel/issues/5411)) ([df69d59](https://github.com/dsj1984/mandrel/commit/df69d59e7ced7342f321b8435ab50b317655f7f3))
+* make AGENTS.md mandrel's always-loaded entry doc: host-faithful closure resolver, delete CLAUDE.md, rewrite AGENTS.md ([#5409](https://github.com/dsj1984/mandrel/issues/5409)) ([#5413](https://github.com/dsj1984/mandrel/issues/5413)) ([929e5bb](https://github.com/dsj1984/mandrel/commit/929e5bb6834e1a25152163ac34a87d327034ce05))
+* trim legacy story-author scaffolding and drop two needless workflow stops ([#5427](https://github.com/dsj1984/mandrel/issues/5427)) ([#5429](https://github.com/dsj1984/mandrel/issues/5429)) ([7b39d36](https://github.com/dsj1984/mandrel/commit/7b39d3637b4911ad7122d6cbaef3c19c88704101))
+
+
+### Fixed
+
+* merge wait: fail fast on a red required check without waiting for unrelated jobs ([#5415](https://github.com/dsj1984/mandrel/issues/5415)) ([#5420](https://github.com/dsj1984/mandrel/issues/5420)) ([381d8ff](https://github.com/dsj1984/mandrel/commit/381d8ff4145ec3210d984936904368d51cde426a))
+
+
+### Performance
+
+* close: per-phase timing, faster merge observation, concurrent post-land GitHub steps ([#5417](https://github.com/dsj1984/mandrel/issues/5417)) ([#5423](https://github.com/dsj1984/mandrel/issues/5423)) ([2d3c537](https://github.com/dsj1984/mandrel/commit/2d3c5373402ad0e212951b70ca2880204da3a8f3))
+* epic rollup: stop reading every Epic's sub-issues when a Story has no native parent ([#5414](https://github.com/dsj1984/mandrel/issues/5414)) ([#5419](https://github.com/dsj1984/mandrel/issues/5419)) ([025c650](https://github.com/dsj1984/mandrel/commit/025c650409a757b47be9847a4584e5e45fdef8e8))
+
+
+### Changed
+
+* retire the Story-scope local-lens pass from close ([#5416](https://github.com/dsj1984/mandrel/issues/5416)) ([#5422](https://github.com/dsj1984/mandrel/issues/5422)) ([ecd86da](https://github.com/dsj1984/mandrel/commit/ecd86daa1a9d1ddff7f58e7f832e491a9c58cb68))
+
 ## [2.64.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.63.0...mandrel-v2.64.0) (2026-09-19)
 
 

package/lib/cli/claude-code-version.js

@@ -0,0 +1,73 @@
+// lib/cli/claude-code-version.js
+/**
+ * `mandrel doctor` check `claude-code-version`: an AGENTS.md-only project
+ * needs a Claude Code host that loads AGENTS.md at all. Below the floor the
+ * framework never hydrates, so the check fails. A missing `claude` binary,
+ * unparseable output, or a project still carrying CLAUDE.md skips with
+ * `ok: true` so headless/CI hosts are never blocked. The `claude --version`
+ * spawn is injected by the registry (fixed argv, never user input); with no
+ * runner the check skips.
+ *
+ * @module cli/claude-code-version
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { compareVersions } from './version-helpers.js';
+
+/** Oldest Claude Code release that loads a root AGENTS.md. */
+export const CLAUDE_CODE_AGENTS_MD_FLOOR = '2.1.277';
+
+/**
+ * @param {string} text
+ * @returns {string|null} the leading `x.y.z`, or null
+ */
+export function parseClaudeVersion(text) {
+  const match = /^\s*v?(\d+\.\d+\.\d+)/.exec(text ?? '');
+  return match ? match[1] : null;
+}
+
+/**
+ * @param {{
+ *   projectRoot?: string,
+ *   cwd?: () => string,
+ *   existsSync?: (p: string) => boolean,
+ *   runClaude?: () => { status: number|null, stdout: string, error?: NodeJS.ErrnoException },
+ * }} [opts]
+ * @returns {{ ok: boolean, detail: string, remedy?: string }}
+ */
+export function runClaudeCodeVersion({
+  projectRoot,
+  cwd = () => process.cwd(),
+  existsSync = fs.existsSync,
+  runClaude = () => ({ status: null, stdout: '', error: new Error('none') }),
+} = {}) {
+  const root = projectRoot ?? cwd();
+  if (existsSync(path.join(root, 'CLAUDE.md'))) {
+    return { ok: true, detail: 'skipped: CLAUDE.md present' };
+  }
+  if (!existsSync(path.join(root, 'AGENTS.md'))) {
+    return { ok: true, detail: 'skipped: no AGENTS.md' };
+  }
+  const r = runClaude();
+  if (r.error || r.status !== 0) {
+    return { ok: true, detail: 'skipped: claude not found on PATH' };
+  }
+  const version = parseClaudeVersion(r.stdout);
+  if (!version) {
+    return {
+      ok: true,
+      detail: 'skipped: unparseable `claude --version` output',
+    };
+  }
+  const detail = `Claude Code ${version} (required >=${CLAUDE_CODE_AGENTS_MD_FLOOR} to load AGENTS.md)`;
+  if (compareVersions(version, CLAUDE_CODE_AGENTS_MD_FLOOR) >= 0) {
+    return { ok: true, detail };
+  }
+  return {
+    ok: false,
+    detail,
+    remedy: `Upgrade Claude Code to >=${CLAUDE_CODE_AGENTS_MD_FLOOR} (e.g. \`claude update\`) — older hosts do not load AGENTS.md, so the framework never hydrates.`,
+  };
+}

package/lib/cli/doctor.js

@@ -54,7 +54,7 @@ function formatSummary(passed, total) {
 }
 
 /**
- * Informational line for the `CLAUDE.md` always-loaded closure (file count,
+ * Informational line for the host entry doc's always-loaded closure (file count,
  * KB). Never counted toward the verdict; a resolve failure degrades to a
  * neutral line.
  *
@@ -73,7 +73,7 @@ export function formatClosureReport({
     return `ℹ  ${label}  always-loaded closure unavailable\n`;
   }
   if (files.length === 0) {
-    return `ℹ  ${label}  no CLAUDE.md closure found\n`;
+    return `ℹ  ${label}  no entry-doc closure found (CLAUDE.md or AGENTS.md)\n`;
   }
   const kb = (tierTotalBytes(files) / 1024).toFixed(1);
   return `ℹ  ${label}  ${files.length} file(s), ${kb} KB always-loaded\n`;

package/lib/cli/guarded-sync.js

@@ -0,0 +1,87 @@
+// lib/cli/guarded-sync.js
+/**
+ * Shared body of `mandrel sync-commands` / `mandrel sync-agents`: run a
+ * `.agents/scripts/` projector in a child process, forwarding its exit code.
+ * Refuses first when `.agents/` does not match the running CLI (version
+ * marker, else the `agents-drift` check): `.claude/*` is gitignored, so a
+ * stale projection surfaces only when an agent hits a missing module.
+ * The marker is read from `cwd()`; `PROJECT_ROOT` only names this CLI's version.
+ */
+
+import { spawnSync } from 'node:child_process';
+import nodeFs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { runAgentsDrift } from './registry.js';
+import { readVersionMarker } from './sync.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// lib/cli/ → lib/ → project root
+const PROJECT_ROOT = path.resolve(__dirname, '..', '..');
+
+function resolveOwnPackageVersion(fsImpl) {
+  const parsed = JSON.parse(
+    fsImpl.readFileSync(path.join(PROJECT_ROOT, 'package.json'), 'utf8'),
+  );
+  return String(parsed.version);
+}
+
+function refusalReason(projectRoot, { fs, ownVersion, checkAgentsDrift, cwd }) {
+  const marker = readVersionMarker(projectRoot, fs);
+  if (marker) {
+    const own = ownVersion ?? resolveOwnPackageVersion(fs);
+    if (marker === own) return null;
+    return {
+      what: `the materialized .agents/ tree is v${marker} but the running CLI is v${own}`,
+      fix: 're-materialize .agents/ to the current version',
+    };
+  }
+  const drift = (checkAgentsDrift ?? (() => runAgentsDrift({ cwd })))();
+  if (drift.ok) return null;
+  return {
+    what: `.agents/ appears to have drifted from the installed package payload (${drift.detail})`,
+    fix: 'restore the materialized .agents/ payload',
+  };
+}
+
+/**
+ * @param {{ command: string, target: string, script: string }} spec
+ * @param {string[]} _argv - Unused; reserved for future flags.
+ * @param {object} [opts] - Injectable runner, cwd, fs, version and I/O seams.
+ */
+export function runGuardedSync(
+  { command, target, script },
+  _argv = [],
+  {
+    runner = spawnSync,
+    cwd = () => process.cwd(),
+    fs = nodeFs,
+    ownVersion,
+    checkAgentsDrift,
+    writeErr = (s) => process.stderr.write(s),
+    exit = (code) => process.exit(code),
+  } = {},
+) {
+  const refusal = refusalReason(cwd(), {
+    fs,
+    ownVersion,
+    checkAgentsDrift,
+    cwd,
+  });
+  if (refusal) {
+    writeErr(
+      `mandrel ${command}: ${refusal.what} — refusing to project ${target} from a mismatched tree.\n` +
+        `   → Run \`mandrel sync\` to ${refusal.fix}, then re-run.\n`,
+    );
+    exit(1);
+    return;
+  }
+  const syncScript = path.join(PROJECT_ROOT, '.agents', 'scripts', script);
+  const result = runner(process.execPath, [syncScript], {
+    stdio: 'inherit',
+    env: process.env,
+  });
+  const exitCode = result.status ?? 1;
+  if (exitCode !== 0) exit(exitCode);
+}

package/lib/cli/registry.js

@@ -28,6 +28,7 @@ import { isCommandExcluded } from '../../.agents/scripts/lib/command-header.js';
 import { getDeliveryRouting } from '../../.agents/scripts/lib/config/delivery-routing.js';
 import { isResolvable } from '../../.agents/scripts/lib/runtime-deps/dep-resolution.js';
 import { describeParserMajorError } from '../../.agents/scripts/lib/runtime-deps/parser-major.js';
+import { runClaudeCodeVersion } from './claude-code-version.js';
 import {
   defaultResolvePackageRoot,
   listFiles as listPayloadFiles,
@@ -958,6 +959,14 @@ export const registry = [
     name: 'agents-drift',
     run: (opts) => runAgentsDrift(opts),
   },
+  {
+    name: 'claude-code-version',
+    run: (opts) =>
+      runClaudeCodeVersion({
+        runClaude: () => spawn('claude', ['--version'], { timeout: 10_000 }),
+        ...opts,
+      }),
+  },
   {
     name: 'merge-driver',
     run: (opts) => runMergeDriver(opts),

package/lib/cli/sync-agents.js

@@ -1,97 +1,14 @@
 // lib/cli/sync-agents.js
-/**
- * `mandrel sync-agents`: project `.agents/agents/` into `.claude/agents/` via
- * `.agents/scripts/sync-claude-agents.js`. Exact sibling of
- * `sync-commands.js` — same child-process delegation, same marker-gated
- * refusal and anchor rule (see that module's doc).
- */
+/** `mandrel sync-agents`: project `.agents/agents/` into `.claude/agents/`. */
 
-import { spawnSync } from 'node:child_process';
-import nodeFs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { runGuardedSync } from './guarded-sync.js';
 
-import { runAgentsDrift } from './registry.js';
-import { readVersionMarker } from './sync.js';
+const SPEC = {
+  command: 'sync-agents',
+  target: '.claude/agents/',
+  script: 'sync-claude-agents.js',
+};
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-// lib/cli/ → lib/ → project root
-const PROJECT_ROOT = path.resolve(__dirname, '..', '..');
-const SYNC_SCRIPT = path.join(
-  PROJECT_ROOT,
-  '.agents',
-  'scripts',
-  'sync-claude-agents.js',
-);
-
-/**
- * @param {typeof nodeFs} fsImpl
- * @returns {string}
- */
-function resolveOwnPackageVersion(fsImpl) {
-  const parsed = JSON.parse(
-    fsImpl.readFileSync(path.join(PROJECT_ROOT, 'package.json'), 'utf8'),
-  );
-  return String(parsed.version);
-}
-
-/**
- * @param {string[]} _argv - Unused; reserved for future flags.
- * @param {{
- *   runner?: typeof spawnSync,
- *   cwd?: () => string,
- *   fs?: typeof nodeFs,
- *   ownVersion?: string,
- *   checkAgentsDrift?: () => { ok: boolean, detail: string },
- *   writeErr?: (s: string) => void,
- *   exit?: (code: number) => void,
- * }} [opts]
- * @returns {void}
- */
-export default function run(
-  _argv = [],
-  {
-    runner = spawnSync,
-    cwd = () => process.cwd(),
-    fs = nodeFs,
-    ownVersion,
-    checkAgentsDrift,
-    writeErr = (s) => process.stderr.write(s),
-    exit = (code) => process.exit(code),
-  } = {},
-) {
-  const projectRoot = cwd();
-  const resolvedOwnVersion = ownVersion ?? resolveOwnPackageVersion(fs);
-  const marker = readVersionMarker(projectRoot, fs);
-
-  if (marker) {
-    if (marker !== resolvedOwnVersion) {
-      writeErr(
-        `mandrel sync-agents: the materialized .agents/ tree is v${marker} but the running CLI is v${resolvedOwnVersion} — refusing to project .claude/agents/ from a mismatched tree.\n` +
-          '   → Run `mandrel sync` to re-materialize .agents/ to the current version, then re-run.\n',
-      );
-      exit(1);
-      return;
-    }
-  } else {
-    const drift = (checkAgentsDrift ?? (() => runAgentsDrift({ cwd })))();
-    if (!drift.ok) {
-      writeErr(
-        `mandrel sync-agents: .agents/ appears to have drifted from the installed package payload (${drift.detail}) — refusing to project .claude/agents/ from a mismatched tree.\n` +
-          '   → Run `mandrel sync` to restore the materialized .agents/ payload, then re-run.\n',
-      );
-      exit(1);
-      return;
-    }
-  }
-
-  const result = runner(process.execPath, [SYNC_SCRIPT], {
-    stdio: 'inherit',
-    env: process.env,
-  });
-
-  const exitCode = result.status ?? 1;
-  if (exitCode !== 0) {
-    exit(exitCode);
-  }
+export default function run(argv, opts) {
+  runGuardedSync(SPEC, argv, opts);
 }

package/lib/cli/sync-commands.js

@@ -1,106 +1,14 @@
 // lib/cli/sync-commands.js
-/**
- * `mandrel sync-commands`: delegate to `.agents/scripts/sync-claude-commands.js`
- * in a child process (it has top-level await and no exported main), forwarding
- * output and exit code.
- *
- * Refuses first when `.agents/` does not match the running CLI — otherwise
- * commands are projected from a stale tree, and since `.claude/*` is
- * gitignored nothing surfaces until an agent hits a missing module. With the
- * `.agents/.mandrel-version` marker, compare it to the CLI's own version;
- * without it, fall back to the `agents-drift` content check.
- *
- * `PROJECT_ROOT` (the package root) answers only "what version is this CLI";
- * the marker is read from `cwd()`. Reading both from `PROJECT_ROOT` would
- * compare the package with itself and never fire.
- */
+/** `mandrel sync-commands`: project `.agents/workflows/` into `.claude/commands/`. */
 
-import { spawnSync } from 'node:child_process';
-import nodeFs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
+import { runGuardedSync } from './guarded-sync.js';
 
-import { runAgentsDrift } from './registry.js';
-import { readVersionMarker } from './sync.js';
+const SPEC = {
+  command: 'sync-commands',
+  target: '.claude/commands/',
+  script: 'sync-claude-commands.js',
+};
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-// lib/cli/ → lib/ → project root
-const PROJECT_ROOT = path.resolve(__dirname, '..', '..');
-const SYNC_SCRIPT = path.join(
-  PROJECT_ROOT,
-  '.agents',
-  'scripts',
-  'sync-claude-commands.js',
-);
-
-/**
- * @param {typeof nodeFs} fsImpl
- * @returns {string}
- */
-function resolveOwnPackageVersion(fsImpl) {
-  const parsed = JSON.parse(
-    fsImpl.readFileSync(path.join(PROJECT_ROOT, 'package.json'), 'utf8'),
-  );
-  return String(parsed.version);
-}
-
-/**
- * @param {string[]} _argv - Unused; reserved for future flags.
- * @param {{
- *   runner?: typeof spawnSync,
- *   cwd?: () => string,
- *   fs?: typeof nodeFs,
- *   ownVersion?: string,
- *   checkAgentsDrift?: () => { ok: boolean, detail: string },
- *   writeErr?: (s: string) => void,
- *   exit?: (code: number) => void,
- * }} [opts]
- * @returns {void}
- */
-export default function run(
-  _argv = [],
-  {
-    runner = spawnSync,
-    cwd = () => process.cwd(),
-    fs = nodeFs,
-    ownVersion,
-    checkAgentsDrift,
-    writeErr = (s) => process.stderr.write(s),
-    exit = (code) => process.exit(code),
-  } = {},
-) {
-  const projectRoot = cwd();
-  const resolvedOwnVersion = ownVersion ?? resolveOwnPackageVersion(fs);
-  const marker = readVersionMarker(projectRoot, fs);
-
-  if (marker) {
-    if (marker !== resolvedOwnVersion) {
-      writeErr(
-        `mandrel sync-commands: the materialized .agents/ tree is v${marker} but the running CLI is v${resolvedOwnVersion} — refusing to project .claude/commands/ from a mismatched tree.\n` +
-          '   → Run `mandrel sync` to re-materialize .agents/ to the current version, then re-run.\n',
-      );
-      exit(1);
-      return;
-    }
-  } else {
-    const drift = (checkAgentsDrift ?? (() => runAgentsDrift({ cwd })))();
-    if (!drift.ok) {
-      writeErr(
-        `mandrel sync-commands: .agents/ appears to have drifted from the installed package payload (${drift.detail}) — refusing to project .claude/commands/ from a mismatched tree.\n` +
-          '   → Run `mandrel sync` to restore the materialized .agents/ payload, then re-run.\n',
-      );
-      exit(1);
-      return;
-    }
-  }
-
-  const result = runner(process.execPath, [SYNC_SCRIPT], {
-    stdio: 'inherit',
-    env: process.env,
-  });
-
-  const exitCode = result.status ?? 1;
-  if (exitCode !== 0) {
-    exit(exitCode);
-  }
+export default function run(argv, opts) {
+  runGuardedSync(SPEC, argv, opts);
 }

package/lib/cli/uninstall.js

@@ -21,8 +21,8 @@ import {
   BOOTSTRAP_COMMAND,
   GITIGNORE_BLOCKS,
   SYNC_COMMAND,
+  SYSTEM_PROMPT_AGENTS_MD,
   SYSTEM_PROMPT_BLOCK,
-  SYSTEM_PROMPT_CLAUDE_MD,
   SYSTEM_PROMPT_IMPORT,
 } from '../../.agents/scripts/lib/bootstrap/project-bootstrap.js';
 import {
@@ -60,17 +60,17 @@ const FRAMEWORK_NPM_SCRIPTS = Object.freeze({
  */
 
 /**
- * Strip the system-prompt import block from `CLAUDE.md`. The file is deleted
- * only when byte-identical to the install template — a heading-only heuristic
- * would delete an operator's all-headings file.
+ * Strip the system-prompt import block from a root entry doc. The file is
+ * deleted only when byte-identical to the install template — a heading-only
+ * heuristic would delete an operator's all-headings file.
  *
+ * @param {string} rel - `AGENTS.md`, or a legacy un-migrated `CLAUDE.md`.
  * @param {string} projectRoot
  * @param {typeof fs} fsImpl
  * @returns {ReversalOutcome}
  */
-function revertClaudeMd(projectRoot, fsImpl) {
-  const target = path.join(projectRoot, 'CLAUDE.md');
-  const rel = 'CLAUDE.md';
+function revertEntryDoc(rel, projectRoot, fsImpl) {
+  const target = path.join(projectRoot, rel);
   if (!fsImpl.existsSync(target)) {
     return { kind: 'skipped', target: rel, detail: 'file absent' };
   }
@@ -78,12 +78,12 @@ function revertClaudeMd(projectRoot, fsImpl) {
   if (!original.includes(SYSTEM_PROMPT_IMPORT)) {
     return { kind: 'skipped', target: rel, detail: 'import already absent' };
   }
-  if (original.trim() === SYSTEM_PROMPT_CLAUDE_MD.trim()) {
+  if (original.trim() === SYSTEM_PROMPT_AGENTS_MD.trim()) {
     fsImpl.rmSync(target, { force: true });
     return {
       kind: 'reverted',
       target: rel,
-      detail: 'removed install-created CLAUDE.md',
+      detail: `removed install-created ${rel}`,
     };
   }
   // Full block first, then the bare import line for a hand-edited block.
@@ -109,6 +109,33 @@ function revertClaudeMd(projectRoot, fsImpl) {
   };
 }
 
+/**
+ * @param {string} projectRoot
+ * @param {typeof fs} fsImpl
+ * @returns {ReversalOutcome}
+ */
+function revertAgentsMd(projectRoot, fsImpl) {
+  return revertEntryDoc('AGENTS.md', projectRoot, fsImpl);
+}
+
+/**
+ * Pre-2.65 ledgers name CLAUDE.md. An un-migrated CLAUDE.md reverts as
+ * before; once the update migration folded it away, the wiring lives in
+ * AGENTS.md, so that is reverted instead. CLAUDE.md is never recreated.
+ *
+ * @param {string} projectRoot
+ * @param {typeof fs} fsImpl
+ * @returns {ReversalOutcome}
+ */
+function revertClaudeMd(projectRoot, fsImpl) {
+  const legacy = fsImpl.existsSync(path.join(projectRoot, 'CLAUDE.md'));
+  return revertEntryDoc(
+    legacy ? 'CLAUDE.md' : 'AGENTS.md',
+    projectRoot,
+    fsImpl,
+  );
+}
+
 /**
  * Splice the sync hook and any legacy plugin-enablement keys out of
  * `.claude/settings.json`, keeping everything else; delete the file if empty.
@@ -405,6 +432,7 @@ function revertPreCommitHook(projectRoot, fsImpl) {
  * @type {Readonly<Record<string, (root: string, fsImpl: typeof fs, executedAction?: string) => ReversalOutcome>>}
  */
 const REVERSAL_BY_TARGET = Object.freeze({
+  'AGENTS.md': revertAgentsMd,
   'CLAUDE.md': revertClaudeMd,
   '.claude/settings.json': revertClaudeSettings,
   '.claude/plugins/mandrel': revertClaudeCommands,

package/lib/migrations/index.js

@@ -16,6 +16,7 @@ import { retireDeliveryLimitKnobs } from './steps/2.57.0-retire-delivery-limit-k
 import { retirePlanningLimitKnobs } from './steps/2.57.0-retire-planning-limit-knobs.js';
 import { retireAuditResultsAutoFile } from './steps/2.60.0-retire-audit-results-autofile.js';
 import { baselineMergeQueueShape } from './steps/2.63.0-baseline-merge-queue-shape.js';
+import { foldClaudeMdIntoAgentsMdStep } from './steps/2.65.0-fold-claude-md-into-agents-md.js';
 import { stripRemovedAgentrcKeys } from './steps/strip-removed-agentrc-keys.js';
 
 /**
@@ -40,6 +41,7 @@ export const migrations = [
   retireAuditResultsAutoFile,
   stripRemovedAgentrcKeys,
   baselineMergeQueueShape,
+  foldClaudeMdIntoAgentsMdStep,
 ];
 
 export { compareVersions };

package/lib/migrations/steps/2.65.0-fold-claude-md-into-agents-md.js

@@ -0,0 +1,38 @@
+// lib/migrations/steps/2.65.0-fold-claude-md-into-agents-md.js
+/**
+ * Fold a consumer's root CLAUDE.md into AGENTS.md and delete CLAUDE.md.
+ * The host reads CLAUDE.md exclusively whenever it exists, so a surviving one
+ * would shadow the AGENTS.md wiring. Shares the bootstrap fold contract.
+ */
+
+import nodeFs from 'node:fs';
+import path from 'node:path';
+
+import {
+  foldClaudeMdIntoAgentsMd,
+  LEGACY_ENTRY_DOC,
+} from '../../../.agents/scripts/lib/bootstrap/agents-md-fold.js';
+
+export const foldClaudeMdIntoAgentsMdStep = {
+  version: '2.65.0',
+  description:
+    'fold the root CLAUDE.md into AGENTS.md and delete it — AGENTS.md is ' +
+    'now the entry doc (Story #5410)',
+  /**
+   * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
+   * @param {typeof nodeFs} [fsImpl]
+   * @returns {boolean}
+   */
+  detect(ctx, fsImpl = ctx?.fs ?? nodeFs) {
+    const root = ctx?.projectRoot ?? process.cwd();
+    return fsImpl.existsSync(path.join(root, LEGACY_ENTRY_DOC));
+  },
+  /**
+   * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
+   * @param {typeof nodeFs} [fsImpl]
+   * @returns {void}
+   */
+  apply(ctx, fsImpl = ctx?.fs ?? nodeFs) {
+    foldClaudeMdIntoAgentsMd(ctx?.projectRoot ?? process.cwd(), fsImpl);
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.64.0",
+  "version": "2.66.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",
@@ -102,6 +102,7 @@
     "@cucumber/gherkin": "^42.0.1",
     "c8": "^11.0.0",
     "chokidar": "^5.0.0",
+    "fast-check": "^4.10.2",
     "husky": "^9.1.7",
     "jscpd": "^4.2.5",
     "knip": "^6.17.1",
@@ -126,7 +127,7 @@
   },
   "peerDependencies": {
     "@cucumber/gherkin": ">=32.0.0",
-    "typescript": ">=5.0.0"
+    "typescript": ">=5.0.0 <7"
   },
   "peerDependenciesMeta": {
     "@cucumber/gherkin": {