mandrel 2.36.0 → 2.38.0

package/lib/migrations/index.js

@@ -52,6 +52,7 @@
  * (ascending by version) with an idempotent `detect`/`apply`.
  */
 
+import { compareVersions } from '../cli/version-helpers.js';
 import { retireMiDropKnobs } from './steps/2.1.0-retire-mi-drop-knobs.js';
 import { retireVerifyConcurrencyCap } from './steps/2.1.0-retire-verify-concurrency-cap.js';
 import { retireEpicAcTags } from './steps/2.2.0-retire-epic-ac-tags.js';
@@ -80,38 +81,42 @@ export const migrations = [
 ];
 
 /**
- * Parse a dotted semver-ish string into a numeric tuple for comparison.
- * Non-numeric or missing segments coerce to 0 so a partial version
- * (`'1.4'`) still compares sanely against a full one (`'1.4.0'`).
+ * The version ordering every migration decision uses.
  *
- * @param {string} version
- * @returns {[number, number, number]}
+ * Re-exported from `lib/cli/version-helpers.js` — the dependency-free leaf
+ * that owns the canonical `parseVersion` / `compareVersions` pair (Story
+ * #4048 B3). The runner previously carried its own copy, so an ordering fix
+ * had to be made in three places or the copies drifted apart. Re-exporting
+ * rather than moving keeps this module's public surface intact for the
+ * callers that import `compareVersions` from here.
  */
-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,
-  ];
-}
+export { compareVersions };
 
 /**
- * Compare two version strings. Returns a negative number when `a < b`, zero
- * when equal, and a positive number when `a > b` — the standard `Array.sort`
- * comparator contract.
+ * The steps that apply for an upgrade, in the order they must run:
+ * `fromVersion < step.version <= toVersion`, ascending.
+ *
+ * Exported because `mandrel migrate --dry-run` has to preview exactly what the
+ * live run would do. That preview previously re-implemented this filter and
+ * carried a comment promising it "mirrors the runner's own comparator" — a
+ * sync obligation nothing enforced, and the reason a third `compareVersions`
+ * copy existed. One selector means the preview cannot drift from the run.
  *
- * @param {string} a
- * @param {string} b
- * @returns {number}
+ * @param {{ registry?: Array<object>, fromVersion: string, toVersion: string }} params
+ * @returns {Array<object>}
  */
-export 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];
-  }
-  return 0;
+export function selectStepsInRange({
+  registry = migrations,
+  fromVersion,
+  toVersion,
+}) {
+  return registry
+    .filter(
+      (step) =>
+        compareVersions(step.version, fromVersion) > 0 &&
+        compareVersions(step.version, toVersion) <= 0,
+    )
+    .sort((a, b) => compareVersions(a.version, b.version));
 }
 
 /**
@@ -152,13 +157,7 @@ export function runMigrations({
   log = console.log,
   registry = migrations,
 } = {}) {
-  const inRange = registry
-    .filter(
-      (step) =>
-        compareVersions(step.version, fromVersion) > 0 &&
-        compareVersions(step.version, toVersion) <= 0,
-    )
-    .sort((a, b) => compareVersions(a.version, b.version));
+  const inRange = selectStepsInRange({ registry, fromVersion, toVersion });
 
   const applied = [];
   const skipped = [];

package/lib/migrations/steps/2.1.0-retire-mi-drop-knobs.js

@@ -11,90 +11,31 @@
  * sub-schemas with `additionalProperties: false`, so a consumer whose
  * config still carries either key hits a hard AJV validation failure on
  * upgrade, not a warning. This step strips them before that check runs.
+ *
+ * Unlike the later retire-steps this one sweeps the committed config only:
+ * the knobs were written by the bootstrap script, never hand-pinned in an
+ * operator's `.agentrc.local.json`.
  */
 
-import nodeFs from 'node:fs';
-import path from 'node:path';
-
-const AGENTRC_FILENAME = '.agentrc.json';
-
-/**
- * @param {unknown} ctx
- * @returns {string}
- */
-function resolveAgentrcPath(ctx) {
-  const projectRoot = ctx?.projectRoot ?? process.cwd();
-  return path.join(projectRoot, AGENTRC_FILENAME);
-}
-
-/**
- * @param {unknown} ctx
- * @param {typeof nodeFs} fsImpl
- * @returns {object | null}
- */
-function readAgentrcConfig(ctx, fsImpl) {
-  try {
-    const raw = fsImpl.readFileSync(resolveAgentrcPath(ctx), 'utf8');
-    return JSON.parse(raw);
-  } catch {
-    return null;
-  }
-}
-
-/**
- * @param {object | null} config
- * @returns {boolean}
- */
-function hasRetiredKey(config) {
-  const guardrails = config?.delivery?.quality?.codingGuardrails;
-  const autoRefresh = config?.delivery?.quality?.autoRefresh;
-  return (
-    (Boolean(guardrails) && Object.hasOwn(guardrails, 'miDropMustRefactor')) ||
-    (Boolean(autoRefresh) && Object.hasOwn(autoRefresh, 'miDropCap'))
-  );
-}
+import {
+  AGENTRC_BASE_FILENAME,
+  createRetireAgentrcKeyStep,
+} from '../helpers/retire-agentrc-key.js';
 
-export const retireMiDropKnobs = {
+export const retireMiDropKnobs = createRetireAgentrcKeyStep({
   version: '2.1.0',
   description:
     'strip retired delivery.quality.codingGuardrails.miDropMustRefactor ' +
     'and delivery.quality.autoRefresh.miDropCap from .agentrc.json',
-  /**
-   * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
-   * @returns {boolean}
-   */
-  detect(ctx) {
-    const fsImpl = ctx?.fs ?? nodeFs;
-    return hasRetiredKey(readAgentrcConfig(ctx, fsImpl));
-  },
-  /**
-   * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
-   * @returns {void}
-   */
-  apply(ctx) {
-    const fsImpl = ctx?.fs ?? nodeFs;
-    const config = readAgentrcConfig(ctx, fsImpl);
-    if (!config) return;
-
-    const guardrails = config.delivery?.quality?.codingGuardrails;
-    if (guardrails && Object.hasOwn(guardrails, 'miDropMustRefactor')) {
-      delete guardrails.miDropMustRefactor;
-      if (Object.keys(guardrails).length === 0) {
-        delete config.delivery.quality.codingGuardrails;
-      }
-    }
-
-    const autoRefresh = config.delivery?.quality?.autoRefresh;
-    if (autoRefresh && Object.hasOwn(autoRefresh, 'miDropCap')) {
-      delete autoRefresh.miDropCap;
-      if (Object.keys(autoRefresh).length === 0) {
-        delete config.delivery.quality.autoRefresh;
-      }
-    }
-
-    fsImpl.writeFileSync(
-      resolveAgentrcPath(ctx),
-      `${JSON.stringify(config, null, 2)}\n`,
-    );
-  },
-};
+  filenames: [AGENTRC_BASE_FILENAME],
+  keys: [
+    {
+      path: ['delivery', 'quality', 'codingGuardrails', 'miDropMustRefactor'],
+      pruneDepth: 1,
+    },
+    {
+      path: ['delivery', 'quality', 'autoRefresh', 'miDropCap'],
+      pruneDepth: 1,
+    },
+  ],
+});

package/lib/migrations/steps/2.1.0-retire-verify-concurrency-cap.js

@@ -1,18 +1,11 @@
 // lib/migrations/steps/2.1.0-retire-verify-concurrency-cap.js
 /**
- * Story #4545 — retire `delivery.deliverRunner.verifyConcurrencyCap`.
- *
- * The knob was schema-validated, defaulted to 4, resolved by `getRunners`,
- * and documented as bounding "the per-wave verifyWaveResults loop" — a loop
- * that does not exist anywhere in the tree. Its only reader was
- * `analyze-execution.js`, which echoed the number into a perf report rather
- * than bounding anything; that CLI is deleted in the same Story. Setting the
- * knob to any value only ever changed a number printed in a report.
- *
- * `delivery.deliverRunner` declares `additionalProperties: false`, so a
- * consumer whose config still carries the key hits a hard AJV validation
- * failure on upgrade — every script that resolves config, not just the one
- * that read it. This step strips it before that check runs.
+ * Story #4531 — `delivery.deliverRunner.verifyConcurrencyCap` was retired
+ * when verification stopped being separately capped, but it stayed
+ * schema-validated in consumers' configs under a block carrying
+ * `additionalProperties: false`, so a config still setting it fails AJV
+ * validation on upgrade rather than warning. This step strips it before
+ * that check runs.
  *
  * Unlike the 2.1.0 mi-drop step, this one also sweeps `.agentrc.local.json`:
  * the resolver deep-merges the local override over `.agentrc.json` and
@@ -20,82 +13,17 @@
  * same way a key in the committed file does.
  */
 
-import nodeFs from 'node:fs';
-import path from 'node:path';
-
-const AGENTRC_FILENAMES = ['.agentrc.json', '.agentrc.local.json'];
-
-/**
- * @param {unknown} ctx
- * @param {string} filename
- * @returns {string}
- */
-function resolveAgentrcPath(ctx, filename) {
-  const projectRoot = ctx?.projectRoot ?? process.cwd();
-  return path.join(projectRoot, filename);
-}
-
-/**
- * @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;
-  }
-}
+import { createRetireAgentrcKeyStep } from '../helpers/retire-agentrc-key.js';
 
-/**
- * @param {object | null} config
- * @returns {boolean}
- */
-function hasRetiredKey(config) {
-  const deliverRunner = config?.delivery?.deliverRunner;
-  return (
-    Boolean(deliverRunner) &&
-    Object.hasOwn(deliverRunner, 'verifyConcurrencyCap')
-  );
-}
-
-export const retireVerifyConcurrencyCap = {
+export const retireVerifyConcurrencyCap = createRetireAgentrcKeyStep({
   version: '2.1.0',
   description:
     'strip retired delivery.deliverRunner.verifyConcurrencyCap from ' +
     '.agentrc.json and .agentrc.local.json',
-  /**
-   * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
-   * @returns {boolean}
-   */
-  detect(ctx) {
-    const fsImpl = ctx?.fs ?? nodeFs;
-    return AGENTRC_FILENAMES.some((filename) =>
-      hasRetiredKey(readAgentrcConfig(ctx, filename, fsImpl)),
-    );
-  },
-  /**
-   * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
-   * @returns {void}
-   */
-  apply(ctx) {
-    const fsImpl = ctx?.fs ?? nodeFs;
-    for (const filename of AGENTRC_FILENAMES) {
-      const config = readAgentrcConfig(ctx, filename, fsImpl);
-      if (!hasRetiredKey(config)) continue;
-
-      delete config.delivery.deliverRunner.verifyConcurrencyCap;
-      if (Object.keys(config.delivery.deliverRunner).length === 0) {
-        delete config.delivery.deliverRunner;
-      }
-
-      fsImpl.writeFileSync(
-        resolveAgentrcPath(ctx, filename),
-        `${JSON.stringify(config, null, 2)}\n`,
-      );
-    }
-  },
-};
+  keys: [
+    {
+      path: ['delivery', 'deliverRunner', 'verifyConcurrencyCap'],
+      pruneDepth: 1,
+    },
+  ],
+});

package/lib/migrations/steps/2.11.0-retire-max-seed-words.js

@@ -12,81 +12,23 @@
  * `maxSeedWords` hits a hard validation failure on upgrade, not a
  * warning. This step strips the key before that check runs — the same
  * contract-cutover pattern as `2.1.0-retire-mi-drop-knobs.js`.
+ *
+ * `planning` is an optional block, so an emptied `complexityGate` and an
+ * emptied `planning` are both pruned rather than left as orphan objects.
  */
 
-import nodeFs from 'node:fs';
-import path from 'node:path';
-
-const AGENTRC_FILENAME = '.agentrc.json';
-
-/**
- * @param {unknown} ctx
- * @returns {string}
- */
-function resolveAgentrcPath(ctx) {
-  const projectRoot = ctx?.projectRoot ?? process.cwd();
-  return path.join(projectRoot, AGENTRC_FILENAME);
-}
-
-/**
- * @param {unknown} ctx
- * @param {typeof nodeFs} fsImpl
- * @returns {object | null}
- */
-function readAgentrcConfig(ctx, fsImpl) {
-  try {
-    const raw = fsImpl.readFileSync(resolveAgentrcPath(ctx), 'utf8');
-    return JSON.parse(raw);
-  } catch {
-    return null;
-  }
-}
-
-/**
- * @param {object | null} config
- * @returns {boolean}
- */
-function hasRetiredKey(config) {
-  const gate = config?.planning?.complexityGate;
-  return Boolean(gate) && Object.hasOwn(gate, 'maxSeedWords');
-}
+import {
+  AGENTRC_BASE_FILENAME,
+  createRetireAgentrcKeyStep,
+} from '../helpers/retire-agentrc-key.js';
 
-export const retireMaxSeedWords = {
+export const retireMaxSeedWords = createRetireAgentrcKeyStep({
   version: '2.11.0',
   description:
     'strip retired planning.complexityGate.maxSeedWords from .agentrc.json ' +
     '(complexity routes on Story shape, never seed word count — Story #4722)',
-  /**
-   * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
-   * @returns {boolean}
-   */
-  detect(ctx) {
-    const fsImpl = ctx?.fs ?? nodeFs;
-    return hasRetiredKey(readAgentrcConfig(ctx, fsImpl));
-  },
-  /**
-   * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
-   * @returns {void}
-   */
-  apply(ctx) {
-    const fsImpl = ctx?.fs ?? nodeFs;
-    const config = readAgentrcConfig(ctx, fsImpl);
-    if (!config) return;
-
-    const gate = config.planning?.complexityGate;
-    if (gate && Object.hasOwn(gate, 'maxSeedWords')) {
-      delete gate.maxSeedWords;
-      if (Object.keys(gate).length === 0) {
-        delete config.planning.complexityGate;
-        if (Object.keys(config.planning).length === 0) {
-          delete config.planning;
-        }
-      }
-    }
-
-    fsImpl.writeFileSync(
-      resolveAgentrcPath(ctx),
-      `${JSON.stringify(config, null, 2)}\n`,
-    );
-  },
-};
+  filenames: [AGENTRC_BASE_FILENAME],
+  keys: [
+    { path: ['planning', 'complexityGate', 'maxSeedWords'], pruneDepth: 2 },
+  ],
+});

package/lib/migrations/steps/2.2.0-retire-epic-ac-tags.js

@@ -4,7 +4,7 @@
  * from consumer feature files.
  *
  * The v2 Epic removal deleted `acceptance-spec-reconciler.js`, the only
- * consumer of the namespaced per-Epic AC tags, and the `/plan` authoring
+ * consumer of the namespaced per-Epic AC tags, and the `/mandrel-plan` authoring
  * prompt no longer mandates them. Surviving tags in consumer `.feature`
  * files are inert and violate the gherkin-standards tag taxonomy's
  * no-ad-hoc-tags rule, so this step removes them: each `@epic-<digits>-ac-<digits>`

package/lib/migrations/steps/2.20.0-retire-codebase-snapshot.js

@@ -1,113 +1,25 @@
 // lib/migrations/steps/2.20.0-retire-codebase-snapshot.js
 /**
  * Story #4811 — strip the retired `planning.codebaseSnapshot` block from a
- * consumer's `.agentrc.json` / `.agentrc.local.json`.
- *
- * #4811 hard-cutover-removed the `/plan` codebase snapshot: the pre-computed
- * structural view grounded nothing it promised (its default include globs
- * missed the standard monorepo layout, and its knobs only re-filtered the same
- * matched set), and spec authoring is grounded instead by the author's own
- * targeted repo retrieval plus the Phase 8 `validateStoryFileAssumptions`
- * gate. The whole block was dropped from the runtime AJV schema and the
- * published mirror. `planning` carries `additionalProperties: false`, so a
- * consumer whose config still sets `codebaseSnapshot` hits a hard validation
- * failure on upgrade, not a warning. This step strips the key before that
- * check runs — the same contract-cutover pattern as
- * `2.11.0-retire-max-seed-words.js`, widened to the local override file
- * because a snapshot narrowed for one checkout is exactly the kind of knob an
+ * consumer's `.agentrc.json` and from the `.agentrc.local.json` overlay an
  * operator pins in `.agentrc.local.json`.
- */
-
-import nodeFs from 'node:fs';
-import path from 'node:path';
-
-/**
- * Both config files the resolver deep-merges. A key surviving in either one
- * fails validation, so both are stripped.
- */
-const AGENTRC_FILENAMES = ['.agentrc.json', '.agentrc.local.json'];
-
-const RETIRED_KEY = 'codebaseSnapshot';
-
-/**
- * @param {unknown} ctx
- * @param {string} filename
- * @returns {string}
- */
-function resolveAgentrcPath(ctx, filename) {
-  const projectRoot = ctx?.projectRoot ?? process.cwd();
-  return path.join(projectRoot, filename);
-}
-
-/**
- * @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;
-  }
-}
-
-/**
- * @param {object | null} config
- * @returns {boolean}
- */
-function hasRetiredKey(config) {
-  const planning = config?.planning;
-  return Boolean(planning) && Object.hasOwn(planning, RETIRED_KEY);
-}
-
-/**
- * Strip the key and prune the containers it emptied, so a config that carried
- * nothing but the snapshot does not keep an orphan `planning: {}`.
  *
- * @param {object} config
- * @returns {void}
+ * Spec authoring is grounded by targeted retrieval plus the Phase 8
+ * file-assumption gate, so the snapshot block has no consumer; the block
+ * carries `additionalProperties: false`, so a config still setting it fails
+ * validation on upgrade rather than warning.
+ *
+ * `planning` is optional, so a config that carried nothing but the snapshot
+ * does not keep an orphan `planning: {}`.
  */
-function stripRetiredKey(config) {
-  delete config.planning[RETIRED_KEY];
-  if (Object.keys(config.planning).length === 0) {
-    delete config.planning;
-  }
-}
 
-export const retireCodebaseSnapshot = {
+import { createRetireAgentrcKeyStep } from '../helpers/retire-agentrc-key.js';
+
+export const retireCodebaseSnapshot = createRetireAgentrcKeyStep({
   version: '2.20.0',
   description:
     'strip retired planning.codebaseSnapshot from .agentrc.json / ' +
     '.agentrc.local.json (spec authoring is grounded by targeted retrieval ' +
     'plus the Phase 8 file-assumption gate — Story #4811)',
-  /**
-   * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
-   * @returns {boolean}
-   */
-  detect(ctx) {
-    const fsImpl = ctx?.fs ?? nodeFs;
-    return AGENTRC_FILENAMES.some((filename) =>
-      hasRetiredKey(readAgentrcConfig(ctx, filename, fsImpl)),
-    );
-  },
-  /**
-   * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
-   * @returns {void}
-   */
-  apply(ctx) {
-    const fsImpl = ctx?.fs ?? nodeFs;
-    for (const filename of AGENTRC_FILENAMES) {
-      const config = readAgentrcConfig(ctx, filename, fsImpl);
-      if (!hasRetiredKey(config)) continue;
-
-      stripRetiredKey(config);
-      fsImpl.writeFileSync(
-        resolveAgentrcPath(ctx, filename),
-        `${JSON.stringify(config, null, 2)}\n`,
-      );
-    }
-  },
-};
+  keys: [{ path: ['planning', 'codebaseSnapshot'], pruneDepth: 1 }],
+});

package/lib/migrations/steps/2.32.0-retire-lint-baseline-command.js

@@ -1,19 +1,9 @@
 // lib/migrations/steps/2.32.0-retire-lint-baseline-command.js
 /**
- * Story #5004 follow-up — strip the retired `project.commands.lintBaseline`
- * key from a consumer's `.agentrc.json`.
- *
- * #5004 (PR #5019) deleted `lint-baseline.js` and
- * `lib/orchestration/lint-baseline-service.js`: the CLI spawned the configured
- * command and parsed ESLint-shaped JSON, a shape this repo's own `npm run
- * lint` (Biome + markdownlint fan-out) never produced, and nothing invoked the
- * service. The key left the runtime AJV schema, the published mirror,
- * `.agentrc.json` and `agentrc-reference.json` in the same change.
- *
- * `project.commands` carries `additionalProperties: false`, so a consumer
- * whose config still sets `lintBaseline` hits a hard validation failure on
- * upgrade, not a warning. This step strips the key before that check runs —
- * the same contract-cutover pattern as `2.11.0-retire-max-seed-words.js`.
+ * Story #5004 — strip the retired `project.commands.lintBaseline` from a
+ * consumer's config. The framework-owned lint-baseline capture CLI is gone,
+ * and the `commands` block carries `additionalProperties: false`, so a
+ * config still naming the command fails validation on upgrade.
  *
  * It sweeps **both** config surfaces. `config-resolver.js` deep-merges
  * `.agentrc.local.json` over `.agentrc.json` and validates the result, so a
@@ -27,6 +17,11 @@
  * `baselines/lint.json`; only the framework-owned capture shell is gone, so
  * nothing here touches the baseline file or the gate config.
  *
+ * An emptied `commands` block is deliberately left in place (`pruneDepth: 0`):
+ * unlike `planning.complexityGate`, `project` is a required block and an empty
+ * `commands` object is valid against the schema, so pruning it would be a
+ * cosmetic edit to a config the consumer owns.
+ *
  * This step is also the carrier for the release note #5004 never emitted: its
  * commit ships the `BREAKING CHANGE:` footer that the squash subject on `main`
  * (`227e1af4`) lacks, and which release-please therefore could not surface.
@@ -34,94 +29,12 @@
  * fix that stops the next one being lost.
  */
 
-import nodeFs from 'node:fs';
-import path from 'node:path';
-
-/**
- * Both config surfaces the resolver reads. `.agentrc.local.json` is deep-merged
- * over the base *before* the AJV gate runs
- * (`.agents/scripts/lib/config-resolver.js`), so a `lintBaseline` surviving in
- * the overlay fails validation exactly as one in the base would — and a step
- * that swept only the base would leave that consumer hard-broken with no
- * self-service remedy, since re-running `mandrel update` would keep reporting
- * clean. The overlay is operator-owned and gitignored, which is why it is easy
- * to forget and why the sweep has to name it explicitly.
- */
-const AGENTRC_FILENAMES = Object.freeze([
-  '.agentrc.json',
-  '.agentrc.local.json',
-]);
-
-/**
- * @param {unknown} ctx
- * @param {string} filename
- * @returns {string}
- */
-function resolveAgentrcPath(ctx, filename) {
-  const projectRoot = ctx?.projectRoot ?? process.cwd();
-  return path.join(projectRoot, filename);
-}
+import { createRetireAgentrcKeyStep } from '../helpers/retire-agentrc-key.js';
 
-/**
- * @param {unknown} ctx
- * @param {typeof nodeFs} fsImpl
- * @param {string} filename
- * @returns {object | null}
- */
-function readAgentrcConfig(ctx, fsImpl, filename) {
-  try {
-    const raw = fsImpl.readFileSync(resolveAgentrcPath(ctx, filename), 'utf8');
-    return JSON.parse(raw);
-  } catch {
-    return null;
-  }
-}
-
-/**
- * @param {object | null} config
- * @returns {boolean}
- */
-function hasRetiredKey(config) {
-  const commands = config?.project?.commands;
-  return Boolean(commands) && Object.hasOwn(commands, 'lintBaseline');
-}
-
-export const retireLintBaselineCommand = {
+export const retireLintBaselineCommand = createRetireAgentrcKeyStep({
   version: '2.32.0',
   description:
     'strip retired project.commands.lintBaseline from .agentrc.json ' +
     '(the framework lint-baseline capture CLI is gone — Story #5004)',
-  /**
-   * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
-   * @returns {boolean}
-   */
-  detect(ctx) {
-    const fsImpl = ctx?.fs ?? nodeFs;
-    return AGENTRC_FILENAMES.some((filename) =>
-      hasRetiredKey(readAgentrcConfig(ctx, fsImpl, filename)),
-    );
-  },
-  /**
-   * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
-   * @returns {void}
-   */
-  apply(ctx) {
-    const fsImpl = ctx?.fs ?? nodeFs;
-    for (const filename of AGENTRC_FILENAMES) {
-      const config = readAgentrcConfig(ctx, fsImpl, filename);
-      // An absent overlay is the common case, not an error.
-      if (!config || !hasRetiredKey(config)) continue;
-
-      delete config.project.commands.lintBaseline;
-      // An emptied `commands` block is left in place: unlike
-      // `planning.complexityGate`, `project` is a required block and an empty
-      // `commands` object is valid against the schema, so pruning it would be
-      // a cosmetic edit to a config the consumer owns.
-
-      fsImpl.writeFileSync(
-        resolveAgentrcPath(ctx, filename),
-        `${JSON.stringify(config, null, 2)}\n`,
-      );
-    }
-  },
-};
+  keys: [{ path: ['project', 'commands', 'lintBaseline'], pruneDepth: 0 }],
+});