mandrel 2.36.0 → 2.38.0

package/.agents/workflows/qa-explore.md

@@ -31,7 +31,7 @@ workflow states only the `/qa-explore`-specific phases (Plan / Capture) plus a
 Constraints delta.
 
 > **When to run**: ad-hoc agent-driven exploration of a freshly delivered Story
-> or Feature, a regression sweep over a risky surface before `/deliver`, or a
+> or Feature, a regression sweep over a risky surface before `/mandrel-deliver`, or a
 > structured agent-driven bug-hunt captured into a triageable ledger.
 >
 > **Skills**: `core/qa-coverage-mapping`, `stack/qa/qa-explore-driving`
@@ -198,14 +198,14 @@ For each observation the agent makes while driving:
 Route the captured ledger through the shared classify → route → disposition →
 promote procedure in [`helpers/qa-core.md`](helpers/qa-core.md), with the
 operator deciding each `file` / `defer` / `dismiss` and every write
-operator-gated. `file` findings are promoted through `/plan` (never a raw
+operator-gated. `file` findings are promoted through `/mandrel-plan` (never a raw
 Issue); `defer` carries an item forward as backlog; `dismiss` marks it
 non-actionable.
 
 After triage, write the updated dispositions back to the ledger (still under
 `temp/qa/`), and summarize: items captured, the driving method used, classes,
 routes (`new`/`update-existing`/`duplicate`/`regression-of-closed`), the
-Stories (`/plan --seed-file`) promoted, and the deferred rolling backlog a
+Stories (`/mandrel-plan --seed-file`) promoted, and the deferred rolling backlog a
 resumed session will pick up.
 
 ---
@@ -238,11 +238,11 @@ the `/qa-explore`-specific deltas are:
 
 ## See also
 
-- [`/plan`](plan.md) — the planning pipeline Triage chains into for a
+- [`/mandrel-plan`](mandrel-plan.md) — the planning pipeline Triage chains into for a
   `file`-dispositioned finding. The plan→deliver hard stop is preserved.
 - [`/qa-assist`](qa-assist.md) — the human-led sibling that enriches a single
-  operator observation and triages through the same `/plan` handoff.
+  operator observation and triages through the same `/mandrel-plan` handoff.
 - [`/audit-to-stories`](audit-to-stories.md) — the precedent for the
-  findings → `/plan` handoff and the shared fingerprint-footer dedup contract.
+  findings → `/mandrel-plan` handoff and the shared fingerprint-footer dedup contract.
 - [`helpers/qa-core.md`](helpers/qa-core.md) — the shared contract/session/
   redaction/QaLedgerItem/triage/HITL core.

package/.agents/workflows/qa-run.md

@@ -26,7 +26,7 @@ the agent never invents those decisions in prose.
 
 > **When to run**: during sprint testing to exercise a targeted slice of the
 > acceptance suite (a feature, a tag expression, or a domain), for regression
-> passes before `/deliver`, or on demand while debugging a Story's
+> passes before `/mandrel-deliver`, or on demand while debugging a Story's
 > user-visible behavior in a live browser.
 >
 > **Skills**: `stack/qa/gherkin-authoring`, `stack/qa/playwright-bdd`

package/README.md

@@ -30,26 +30,26 @@ provisions both as part of a cold start (`git init` → `gh repo create --push`
 The canonical cold-start path is one command, then one slash command:
 
 ```bash
-npx mandrel init        # install mandrel → sync → prompt → bootstrap → onboarding tail → /plan handoff
+npx mandrel init        # install mandrel → sync → prompt → bootstrap → onboarding tail → /mandrel-plan handoff
 ```
 
 ```text
 # then, inside Claude Code (commands load from .claude/commands/):
-/plan --seed "…"   # interrogate → author one Story (default) → persist
-/deliver <id>      # story-<id> → PR → main
+/mandrel-plan --seed "…"   # interrogate → author one Story (default) → persist
+/mandrel-deliver <id>      # story-<id> → PR → main
 ```
 
 `npx mandrel init` installs `mandrel` (when `./.agents/` is absent),
 materializes it via `mandrel sync`, then asks whether to **configure now**
 (option 1 → runs `bootstrap.js`, then the onboarding tail: stack detection,
-docs scaffolding offer, `mandrel doctor` readiness gate, and a `/plan`
+docs scaffolding offer, `mandrel doctor` readiness gate, and a `/mandrel-plan`
 handoff) or stop at **just the files** (option 2 → re-run `mandrel init`
 any time to configure). Pass `--assume-yes` for a non-interactive run that
 proceeds straight to configure (and forwards the flag to bootstrap). When
 `./.agents/` is already present (you ran `npm install mandrel` first), `init`
 skips the install/sync and goes straight to the prompt. Once `mandrel init`
-completes, you land at the `/plan` handoff — run `/plan --seed "<idea>"` to
-author your first Story, then deliver it with `/deliver <storyId>`
+completes, you land at the `/mandrel-plan` handoff — run `/mandrel-plan --seed "<idea>"` to
+author your first Story, then deliver it with `/mandrel-deliver <storyId>`
 (`story-<id>` → PR → `main`).
 
 ### Manual equivalent
@@ -164,7 +164,7 @@ npx mandrel doctor                      # verify the install
 Mandrel's effectiveness is measured by a separate companion repo,
 **[mandrel-bench](https://github.com/dsj1984/mandrel-bench)** — a *consumer* of
 the published `mandrel` package. It pins a specific framework version,
-materializes it via `mandrel sync`, and drives Mandrel's own `/plan`→`/deliver`
+materializes it via `mandrel sync`, and drives Mandrel's own `/mandrel-plan`→`/mandrel-deliver`
 pipeline (plus a bare-model control) over a scenario corpus. Each run is scored
 across five dimensions — Quality, Planning fidelity, and Autonomy (what the
 scaffolding *buys*) versus Efficiency and Overhead ratio (what it *costs*) —

package/docs/CHANGELOG.md

@@ -15,6 +15,49 @@ All notable changes to this project will be documented in this file.
 -->
 <!-- markdownlint-disable-file MD004 MD012 MD037 -->
 
+## [2.38.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.37.0...mandrel-v2.38.0) (2026-09-04)
+
+
+### ⚠ BREAKING CHANGES
+
+* the `/plan` and `/deliver` slash commands are renamed to `/mandrel-plan` and `/mandrel-deliver`. Run `mandrel sync` (or `npm run sync:commands`) to reap the old command files and project the new ones. No `/plan` or `/deliver` alias remains.
+
+### Added
+
+* rename /plan and /deliver to /mandrel-plan and /mandrel-deliver ([#5126](https://github.com/dsj1984/mandrel/issues/5126)) ([#5127](https://github.com/dsj1984/mandrel/issues/5127)) ([945d8de](https://github.com/dsj1984/mandrel/commit/945d8de4a41aeca7adc89c009a0252f5bb5387b4))
+
+## [2.37.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.36.0...mandrel-v2.37.0) (2026-09-03)
+
+
+### ⚠ BREAKING CHANGES
+
+* `single-story-close.js` now exits non-zero on `--dry-run` or `--no-evidence` instead of silently ignoring them. Neither flag ever had an effect; a caller passing one was getting a full real close.
+
+### Added
+
+* cut the test suite's child-process budget: seed the e2e consumer once and move tests/e2e to its own tier, replace CLI cold-start spawns with in-process calls, and settle the isolation trade-off ([#5111](https://github.com/dsj1984/mandrel/issues/5111)) ([#5122](https://github.com/dsj1984/mandrel/issues/5122)) ([a4fbd56](https://github.com/dsj1984/mandrel/commit/a4fbd5628b8bc11c918e0ff658fe62baf078a17f))
+* detect high-severity advisories on main between PRs, and bound the TypeScript devDependency range ([#5104](https://github.com/dsj1984/mandrel/issues/5104)) ([#5107](https://github.com/dsj1984/mandrel/issues/5107)) ([af8f1b8](https://github.com/dsj1984/mandrel/commit/af8f1b8ee28300391a3a43cca1d43ece5851ce83))
+
+
+### Fixed
+
+* close five concurrency holes: sweep-lock steal and heartbeat, one lock for the merged-branch reap, atomic pending-cleanup manifest, idempotent createIssue retry, additive lease claim ([#5112](https://github.com/dsj1984/mandrel/issues/5112)) ([#5119](https://github.com/dsj1984/mandrel/issues/5119)) ([8651514](https://github.com/dsj1984/mandrel/commit/86515147381cf653c1e41c01f6405f5333826253))
+* **deps:** bump fast-uri to 3.1.7 for four high-severity advisories ([#5103](https://github.com/dsj1984/mandrel/issues/5103)) ([06c37b1](https://github.com/dsj1984/mandrel/commit/06c37b11952fb8079027c0beceef831bed677485))
+* **drain-pending-cleanup:** honour --no-escalate and guard advertised --no-* flags (refs [#5101](https://github.com/dsj1984/mandrel/issues/5101)) ([#5106](https://github.com/dsj1984/mandrel/issues/5106)) ([52ef3cb](https://github.com/dsj1984/mandrel/commit/52ef3cb0c546714900474c0613d78b23bc40a068))
+* restore the suite profiler, make run-tests --help print usage, and stop three tests burning worker slots on real backoff and a live-repo scan ([#5110](https://github.com/dsj1984/mandrel/issues/5110)) ([#5115](https://github.com/dsj1984/mandrel/issues/5115)) ([dbe0742](https://github.com/dsj1984/mandrel/commit/dbe07420a7d8d3c99016968d9c15e45da64d0de2))
+* single-story-close advertises --dry-run and --no-evidence but never wired either: retire both and reject them loudly ([#5100](https://github.com/dsj1984/mandrel/issues/5100)) ([#5102](https://github.com/dsj1984/mandrel/issues/5102)) ([2f4dd52](https://github.com/dsj1984/mandrel/commit/2f4dd52c682bcc3697f67124d6dc574e209ab204))
+
+
+### Performance
+
+* stop the baseline gates doing pointless heavy work: lazy TypeScript, small-batch in-process scoring, precompiled globs, diff-scoped cyclomatic, precompiled .agentrc validator ([#5109](https://github.com/dsj1984/mandrel/issues/5109)) ([#5117](https://github.com/dsj1984/mandrel/issues/5117)) ([6b04d5e](https://github.com/dsj1984/mandrel/commit/6b04d5e7c014b4bc052afbef8fd88d85c7a6b00f))
+
+
+### Changed
+
+* collapse the tripled semver comparator and the copy-pasted migration-step scaffold in the published lib/ payload ([#5113](https://github.com/dsj1984/mandrel/issues/5113)) ([#5116](https://github.com/dsj1984/mandrel/issues/5116)) ([ae2b6d6](https://github.com/dsj1984/mandrel/commit/ae2b6d6c40b26ea6d2f94b07698867863011a659))
+* extract one JavaScript comment stripper, bring two cyclomatic-20 CLI mains under the ceiling, and delete the orchestration payload’s dead code ([#5114](https://github.com/dsj1984/mandrel/issues/5114)) ([#5118](https://github.com/dsj1984/mandrel/issues/5118)) ([747d9a5](https://github.com/dsj1984/mandrel/commit/747d9a5bce66a6230fe6f46d132b3e8aacbc5a09))
+
 ## [2.36.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.35.0...mandrel-v2.36.0) (2026-08-29)
 
 

package/lib/cli/doctor.js

@@ -122,7 +122,7 @@ export function formatClosureReport({
 
 /**
  * Best-effort write of the doctor verdict to `temp/doctor-result.json` under
- * the consumer root so downstream workflows (e.g. the `/plan` first-run
+ * the consumer root so downstream workflows (e.g. the `/mandrel-plan` first-run
  * preflight) can read the last recorded verdict without re-running doctor.
  * `temp/` is the gitignored scratch root, so neither git nor the sync prune
  * pass ever sees the cache. Any write failure is swallowed — the cache is

package/lib/cli/init.js

@@ -299,7 +299,7 @@ export async function planInit({
     }
 
     // Bootstrap succeeded — run the onboarding tail: stack detection, docs
-    // scaffolding offer, doctor gate, and /plan handoff. A tail that reports
+    // scaffolding offer, doctor gate, and /mandrel-plan handoff. A tail that reports
     // `ok: false` (the doctor gate failed) makes the whole init exit
     // non-zero; the tail already printed its own remediation message, and the
     // earlier install/sync/bootstrap phases' results stand as completed.

package/lib/cli/migrate.js

@@ -54,6 +54,7 @@
 import {
   migrations as defaultRegistry,
   runMigrations as defaultRunMigrations,
+  selectStepsInRange,
 } from '../migrations/index.js';
 
 /**
@@ -77,36 +78,97 @@ function parseOption(argv, flag) {
 }
 
 /**
- * Parse a dotted semver-ish string into a numeric tuple. Mirrors the runner's
- * own comparator so the dry-run in-range filter matches the live filter
- * exactly.
+ * The envelope shape every `runMigrate` exit returns. Centralised so the four
+ * exits cannot drift in which fields they populate.
  *
- * @param {string} version
- * @returns {[number, number, number]}
+ * @param {object} fields
+ * @returns {object}
  */
-function parseVersion(version) {
-  const [major, minor, patch] = String(version).split('.');
-  return [
-    Number.parseInt(major, 10) || 0,
-    Number.parseInt(minor, 10) || 0,
-    Number.parseInt(patch, 10) || 0,
-  ];
+function migrateResult(fields) {
+  return {
+    ok: false,
+    action: 'usage-error',
+    fromVersion: null,
+    toVersion: null,
+    dryRun: false,
+    applied: [],
+    skipped: [],
+    wouldApply: [],
+    wouldSkip: [],
+    ...fields,
+  };
+}
+
+/**
+ * Both bounds are required: the runner filters `fromVersion < v <= toVersion`,
+ * so an absent bound is ambiguous rather than a sensible default.
+ *
+ * @param {{ writeErr: (s: string) => void, exit: (code: number) => void }} io
+ * @returns {void}
+ */
+function reportUsageError({ writeErr, exit }) {
+  writeErr(
+    'mandrel migrate: both --from <version> and --to <version> are required.\n' +
+      '   → Usage: mandrel migrate --from <version> --to <version> [--dry-run]\n',
+  );
+  exit(1);
 }
 
 /**
- * Compare two version strings (standard `Array.sort` comparator contract).
+ * Report the in-range steps and whether each WOULD apply or be skipped,
+ * probing a throwaway context so no step's `apply` runs and nothing on disk
+ * changes. The ordering comes from `selectStepsInRange`, the same selector the
+ * live run uses, so the preview cannot disagree with what would happen.
  *
- * @param {string} a
- * @param {string} b
- * @returns {number}
+ * @param {{
+ *   registry: Array<object>,
+ *   fromVersion: string,
+ *   toVersion: string,
+ *   write: (s: string) => void,
+ * }} params
+ * @returns {{ wouldApply: string[], wouldSkip: string[] }}
  */
-function compareVersions(a, b) {
-  const pa = parseVersion(a);
-  const pb = parseVersion(b);
-  for (let i = 0; i < 3; i += 1) {
-    if (pa[i] !== pb[i]) return pa[i] - pb[i];
+function previewMigrations({ registry, fromVersion, toVersion, write }) {
+  const inRange = selectStepsInRange({ registry, fromVersion, toVersion });
+  const wouldApply = [];
+  const wouldSkip = [];
+  const probeCtx = {};
+
+  write(`mandrel migrate — dry run v${fromVersion} → v${toVersion}\n`);
+  if (inRange.length === 0) {
+    write('  (no migration steps in range)\n');
   }
-  return 0;
+  for (const step of inRange) {
+    const bucket = step.detect(probeCtx) ? wouldApply : wouldSkip;
+    const verb = bucket === wouldApply ? 'would apply ' : 'would skip  ';
+    bucket.push(step.version);
+    write(`  ${verb} ${step.version}: ${step.description}\n`);
+  }
+  write('Dry run: no migrations applied, nothing written.\n');
+
+  return { wouldApply, wouldSkip };
+}
+
+/**
+ * @param {{
+ *   applied: string[],
+ *   fromVersion: string,
+ *   toVersion: string,
+ *   write: (s: string) => void,
+ * }} params
+ * @returns {void}
+ */
+function reportApplied({ applied, fromVersion, toVersion, write }) {
+  if (applied.length === 0) {
+    write(
+      `mandrel migrate: no migrations to apply for v${fromVersion} → v${toVersion}.\n`,
+    );
+    return;
+  }
+  const plural = applied.length === 1 ? '' : 's';
+  write(
+    `✅  Applied ${applied.length} migration${plural} (v${fromVersion} → v${toVersion}).\n`,
+  );
 }
 
 /**
@@ -146,107 +208,51 @@ export function runMigrate({
   const fromVersion = parseOption(argv, '--from');
   const toVersion = parseOption(argv, '--to');
 
-  // --- Usage validation -----------------------------------------------------
-  // Both bounds are required: the runner filters fromVersion < v <= toVersion,
-  // so an absent bound is ambiguous rather than a sensible default.
   if (!fromVersion || !toVersion) {
-    writeErr(
-      'mandrel migrate: both --from <version> and --to <version> are required.\n' +
-        '   → Usage: mandrel migrate --from <version> --to <version> [--dry-run]\n',
-    );
-    exit(1);
-    return {
-      ok: false,
-      action: 'usage-error',
+    reportUsageError({ writeErr, exit });
+    return migrateResult({
       fromVersion: fromVersion ?? null,
       toVersion: toVersion ?? null,
       dryRun,
-      applied: [],
-      skipped: [],
-      wouldApply: [],
-      wouldSkip: [],
-    };
+    });
   }
 
-  // --- Dry run --------------------------------------------------------------
-  // Report the in-range steps and whether each WOULD apply or be skipped,
-  // probing a throwaway context so no step's apply runs and nothing on disk
-  // changes.
   if (dryRun) {
-    const inRange = registry
-      .filter(
-        (step) =>
-          compareVersions(step.version, fromVersion) > 0 &&
-          compareVersions(step.version, toVersion) <= 0,
-      )
-      .sort((a, b) => compareVersions(a.version, b.version));
-
-    const wouldApply = [];
-    const wouldSkip = [];
-    const probeCtx = {};
-
-    write(`mandrel migrate — dry run v${fromVersion} → v${toVersion}\n`);
-    if (inRange.length === 0) {
-      write('  (no migration steps in range)\n');
-    }
-    for (const step of inRange) {
-      const willApply = step.detect(probeCtx);
-      if (willApply) {
-        wouldApply.push(step.version);
-        write(`  would apply  ${step.version}: ${step.description}\n`);
-      } else {
-        wouldSkip.push(step.version);
-        write(`  would skip   ${step.version}: ${step.description}\n`);
-      }
-    }
-    write('Dry run: no migrations applied, nothing written.\n');
-
-    return {
+    const { wouldApply, wouldSkip } = previewMigrations({
+      registry,
+      fromVersion,
+      toVersion,
+      write,
+    });
+    return migrateResult({
       ok: true,
       action: 'dry-run',
       fromVersion,
       toVersion,
       dryRun: true,
-      applied: [],
-      skipped: [],
       wouldApply,
       wouldSkip,
-    };
+    });
   }
 
-  // --- Live run -------------------------------------------------------------
-  // Delegate to the runner, which owns ordering, range filtering, idempotency,
-  // and the per-step `migrated …` log line.
+  // The runner owns ordering, range filtering, idempotency, and the per-step
+  // `migrated …` log line.
   const { applied, skipped } = runMigrations({
     fromVersion,
     toVersion,
     ctx,
     registry,
   });
+  reportApplied({ applied, fromVersion, toVersion, write });
 
-  if (applied.length === 0) {
-    write(
-      `mandrel migrate: no migrations to apply for v${fromVersion} → v${toVersion}.\n`,
-    );
-  } else {
-    write(
-      `✅  Applied ${applied.length} migration${
-        applied.length === 1 ? '' : 's'
-      } (v${fromVersion} → v${toVersion}).\n`,
-    );
-  }
-
-  return {
+  return migrateResult({
     ok: true,
     action: 'migrated',
     fromVersion,
     toVersion,
-    dryRun: false,
     applied,
     skipped,
-    wouldApply: [],
-    wouldSkip: [],
-  };
+  });
 }
 
 /**

package/lib/migrations/helpers/retire-agentrc-key.js

@@ -0,0 +1,200 @@
+// lib/migrations/helpers/retire-agentrc-key.js
+/**
+ * The shared scaffold behind every "strip a retired `.agentrc.json` key"
+ * migration step.
+ *
+ * Retiring a config key is the framework's most common migration: a key is
+ * dropped from the runtime AJV schema, the block it lived under carries
+ * `additionalProperties: false`, and a consumer whose config still sets it
+ * hits a hard validation failure on upgrade rather than a warning. Every such
+ * step reads the config, decides whether the key is present, deletes it,
+ * prunes whatever containers that emptied, and writes the file back — the
+ * same mechanics each time, previously copy-pasted per step (jscpd recorded
+ * five of them between 48 and 58 percent duplicated).
+ *
+ * Only three things actually vary between steps, so only those three are
+ * declared:
+ *
+ *   - **which config surfaces to sweep** — `.agentrc.json` alone, or that plus
+ *     the gitignored `.agentrc.local.json`. `config-resolver.js` deep-merges
+ *     the overlay over the base *before* the AJV gate runs, so a key surviving
+ *     in the overlay fails exactly as a base one would. A step that swept only
+ *     the base would report "nothing to migrate" and leave that consumer hard
+ *     broken with no self-service remedy.
+ *   - **which key paths are retired** — a step may retire more than one.
+ *   - **how far to prune emptied ancestors** — this is deliberately per-key
+ *     and not a global policy. `planning` is optional, so an emptied
+ *     `planning` block is removed; `project` is required and an empty
+ *     `commands` object is valid against the schema, so pruning it would be a
+ *     cosmetic edit to a config the consumer owns.
+ *
+ * Builtins only, and the `fs` seam stays injectable via `ctx.fs`, because
+ * these steps run during `mandrel update` before third-party packages are
+ * guaranteed to be present.
+ */
+
+import nodeFs from 'node:fs';
+import path from 'node:path';
+
+/** The committed config every consumer has. */
+export const AGENTRC_BASE_FILENAME = '.agentrc.json';
+
+/** The operator-owned, gitignored overlay the resolver merges over the base. */
+const AGENTRC_LOCAL_FILENAME = '.agentrc.local.json';
+
+/**
+ * Both surfaces the resolver reads — the default sweep for a retired key.
+ *
+ * Module-local: a step that wants both surfaces takes the default and names
+ * nothing, so exporting this would ship a symbol with no importer.
+ */
+const AGENTRC_FILENAMES = Object.freeze([
+  AGENTRC_BASE_FILENAME,
+  AGENTRC_LOCAL_FILENAME,
+]);
+
+/**
+ * @param {unknown} ctx
+ * @param {string} filename
+ * @returns {string}
+ */
+function resolveAgentrcPath(ctx, filename) {
+  const projectRoot = ctx?.projectRoot ?? process.cwd();
+  return path.join(projectRoot, filename);
+}
+
+/**
+ * Read and parse one config surface. An absent or unparseable file is the
+ * common case (no overlay, fresh checkout), not an error.
+ *
+ * @param {unknown} ctx
+ * @param {string} filename
+ * @param {typeof nodeFs} fsImpl
+ * @returns {object | null}
+ */
+function readAgentrcConfig(ctx, filename, fsImpl) {
+  try {
+    const raw = fsImpl.readFileSync(resolveAgentrcPath(ctx, filename), 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Walk the container chain for a key path, returning every object along it.
+ * Returns `null` as soon as a level is missing or is not a plain object, which
+ * is what makes `hasKey` false for a config that never had the block.
+ *
+ * @param {object | null} config
+ * @param {string[]} keyPath
+ * @returns {object[] | null}
+ */
+function resolveContainers(config, keyPath) {
+  if (!config || typeof config !== 'object') return null;
+  const containers = [config];
+  let cursor = config;
+  for (const segment of keyPath.slice(0, -1)) {
+    const next = cursor[segment];
+    if (!next || typeof next !== 'object') return null;
+    containers.push(next);
+    cursor = next;
+  }
+  return containers;
+}
+
+/**
+ * @param {object | null} config
+ * @param {string[]} keyPath
+ * @returns {boolean}
+ */
+function hasKey(config, keyPath) {
+  const containers = resolveContainers(config, keyPath);
+  if (!containers) return false;
+  const leafOwner = containers[containers.length - 1];
+  return Object.hasOwn(leafOwner, keyPath[keyPath.length - 1]);
+}
+
+/**
+ * Delete the leaf key, then remove up to `pruneDepth` ancestors that the
+ * deletion left empty. `pruneDepth: 0` deletes the key and nothing else.
+ *
+ * @param {object} config
+ * @param {{ path: string[], pruneDepth?: number }} key
+ * @returns {void}
+ */
+function stripKey(config, key) {
+  const keyPath = key.path;
+  const containers = resolveContainers(config, keyPath);
+  if (!containers) return;
+
+  const leafOwner = containers[containers.length - 1];
+  delete leafOwner[keyPath[keyPath.length - 1]];
+
+  const pruneDepth = key.pruneDepth ?? 0;
+  for (let level = 0; level < pruneDepth; level += 1) {
+    const index = containers.length - 1 - level;
+    const emptied = containers[index];
+    const parent = containers[index - 1];
+    if (!parent || Object.keys(emptied).length > 0) break;
+    delete parent[keyPath[index - 1]];
+  }
+}
+
+/**
+ * Build a migration step that strips one or more retired keys from the
+ * consumer's config surfaces.
+ *
+ * `detect` is true when any declared key is present in any swept surface;
+ * `apply` rewrites only the surfaces that actually carry one, which is what
+ * makes a repeat pass a genuine no-op rather than a reformat.
+ *
+ * @param {{
+ *   version: string,
+ *   description: string,
+ *   filenames?: readonly string[],
+ *   keys: Array<{ path: string[], pruneDepth?: number }>,
+ * }} spec
+ * @returns {{
+ *   version: string,
+ *   description: string,
+ *   detect: (ctx?: { projectRoot?: string, fs?: typeof nodeFs }) => boolean,
+ *   apply: (ctx?: { projectRoot?: string, fs?: typeof nodeFs }) => void,
+ * }}
+ */
+export function createRetireAgentrcKeyStep({
+  version,
+  description,
+  filenames = AGENTRC_FILENAMES,
+  keys,
+}) {
+  const carriesRetiredKey = (config) =>
+    keys.some((key) => hasKey(config, key.path));
+
+  return {
+    version,
+    description,
+    detect(ctx) {
+      const fsImpl = ctx?.fs ?? nodeFs;
+      return filenames.some((filename) =>
+        carriesRetiredKey(readAgentrcConfig(ctx, filename, fsImpl)),
+      );
+    },
+    apply(ctx) {
+      const fsImpl = ctx?.fs ?? nodeFs;
+      for (const filename of filenames) {
+        const config = readAgentrcConfig(ctx, filename, fsImpl);
+        if (!carriesRetiredKey(config)) continue;
+
+        for (const key of keys) {
+          if (hasKey(config, key.path)) stripKey(config, key);
+        }
+
+        fsImpl.writeFileSync(
+          resolveAgentrcPath(ctx, filename),
+          `${JSON.stringify(config, null, 2)}\n`,
+        );
+      }
+    },
+  };
+}