mandrel 2.59.0 → 2.61.0

package/lib/cli/version-check.js

@@ -1,57 +1,19 @@
 // lib/cli/version-check.js
 /**
- * Daily-cached version freshness check (Story #3500, Epic #3437 — Auto-Update
- * & Version Lifecycle).
- *
- * Detects a stale install ("f-notify-stale") via a daily on-disk JSON cache so
- * callers learn that a newer version exists **without** issuing a network call
- * on every command. The cache lives under the project's temp root as a small
- * JSON document:
- *
- *   { "latestVersion": "<semver>", "checkedAt": "<ISO-8601 timestamp>" }
- *
- * `isStale` reads that cache and only invokes the injected network `runner`
- * seam when the cached `checkedAt` is older than 24h. A fresh cache short-
- * circuits with zero network I/O; a missing, unreadable, or stale cache
- * triggers exactly one `runner` call and a cache refresh.
- *
- * Security (security-baseline § 5 — Data Leakage & Logging):
- *   - Logs only version strings and filesystem paths. Never logs tokens,
- *     credentials, environment values, or raw file contents.
- *   - Performs no shell-string interpolation; the network probe is delegated
- *     to the injected `runner` seam so the host owns transport and auth.
- *
- * Injectable seams (used by lib/cli/__tests__/version-check.test.js):
- *   - `cachePath` — absolute path to the daily cache JSON file
- *   - `now`       — Date provider (defaults to `new Date()`)
- *   - `runner`    — async network seam returning the latest version string
- *   - `fs`        — node:fs surface (readFileSync / writeFileSync / mkdirSync)
- *   - `log`       — structured logger seam (defaults to a no-op)
- *
- * Following the lib/cli/*.js convention: Node built-ins only, every effectful
- * dependency is an injectable seam, and the default export is the seam-free
- * production wiring.
+ * Daily-cached newest-version check: `{ latestVersion, checkedAt }` JSON under
+ * the temp root, so commands learn of a newer release without a network call
+ * each time. Logs only versions and paths.
  */
 
 import nodeFs from 'node:fs';
 import path from 'node:path';
 
-/** Cache freshness window in milliseconds (24 hours). */
 export const STALE_AFTER_MS = 24 * 60 * 60 * 1000;
 
-/** Default cache filename under the temp root. */
 export const DEFAULT_CACHE_FILENAME = 'version-check.json';
 
 /**
- * Read and parse the daily cache JSON.
- *
- * Returns `null` when the file is absent, unreadable, malformed, or missing
- * the required `checkedAt` / `latestVersion` fields — every one of those is a
- * "treat as no cache" condition for `isStale`, so callers never have to
- * distinguish them.
- *
- * Never throws: a corrupt or missing cache must degrade to a refresh, not a
- * crash.
+ * `null` (never a throw) for any absent, unreadable or malformed cache.
  *
  * @param {{
  *   cachePath: string,
@@ -66,7 +28,6 @@ export function readCache({ cachePath, fs = nodeFs }) {
   try {
     raw = fs.readFileSync(cachePath, 'utf8');
   } catch {
-    // Missing or unreadable file → no cache.
     return null;
   }
 
@@ -74,7 +35,6 @@ export function readCache({ cachePath, fs = nodeFs }) {
   try {
     parsed = JSON.parse(raw);
   } catch {
-    // Malformed JSON → no cache.
     return null;
   }
 
@@ -91,11 +51,6 @@ export function readCache({ cachePath, fs = nodeFs }) {
 }
 
 /**
- * Persist `{ latestVersion, checkedAt }` JSON to the cache path, creating the
- * parent directory (the temp root) when needed.
- *
- * Logs only the version string and the cache path — never the raw payload.
- *
  * @param {{
  *   cachePath: string,
  *   latestVersion: string,
@@ -103,7 +58,7 @@ export function readCache({ cachePath, fs = nodeFs }) {
  *   fs?: typeof import('node:fs'),
  *   log?: (msg: string) => void,
  * }} opts
- * @returns {{ latestVersion: string, checkedAt: string }} The persisted record.
+ * @returns {{ latestVersion: string, checkedAt: string }}
  */
 export function refreshCache({
   cachePath,
@@ -121,32 +76,15 @@ export function refreshCache({
   fs.mkdirSync(dir, { recursive: true });
   fs.writeFileSync(cachePath, `${JSON.stringify(record, null, 2)}\n`, 'utf8');
 
-  // Safe to log: version string + path only (security-baseline § 5).
   log(`version-check: cached latestVersion=${latestVersion} at ${cachePath}`);
 
   return record;
 }
 
 /**
- * Decide whether the cached freshness check is stale and, when it is, refresh
- * it through the network `runner` seam.
- *
- * Behaviour:
- *   - **Fresh cache** (`checkedAt` within 24h): returns immediately with the
- *     cached version. The `runner` seam is **never** invoked — no per-command
- *     network call.
- *   - **Missing / corrupt / stale cache**: invokes `runner` exactly once to
- *     fetch the latest version, persists the result via `refreshCache`, and
- *     returns the refreshed record.
- *
- * The freshness comparison uses `>=` so an exactly-24h-old cache counts as
- * stale (the boundary is treated as "due for refresh").
- *
- * `forceRefresh` skips the freshness read entirely and always probes. It is
- * the supported way to bypass the cache: callers must **not** fake staleness
- * by shifting `now` forward, because `now` is also the clock stamped into the
- * refreshed `checkedAt` — a shifted clock persists a future timestamp and
- * defeats the freshness window for every later reader (Story #4878).
+ * A cache under 24h old returns without calling `runner`; otherwise one probe
+ * refreshes it. Bypass with `forceRefresh`, never by shifting `now`: `now` is
+ * stamped as `checkedAt`, and a future stamp defeats every later reader.
  *
  * @param {{
  *   cachePath: string,
@@ -179,7 +117,6 @@ export async function isStale({
       Number.isFinite(ageMs) && ageMs >= 0 && ageMs < STALE_AFTER_MS;
 
     if (cacheIsFresh) {
-      // Fresh cache → no network call.
       log(
         `version-check: cache fresh latestVersion=${cached.latestVersion} (no network)`,
       );
@@ -192,7 +129,6 @@ export async function isStale({
     }
   }
 
-  // Missing, corrupt, or stale cache → one network probe + refresh.
   if (typeof runner !== 'function') {
     throw new Error(
       'version-check: runner seam is required to refresh a stale cache',

package/lib/cli/version-helpers.js

@@ -1,39 +1,18 @@
 // lib/cli/version-helpers.js
 /**
- * Shared semver-ish parse and compare helpers used by both
- * `lib/cli/update.js` and `lib/cli/registry.js`.
- *
- * Both files previously defined local copies of `parseVersion` and
- * `compareVersions`; this module is the single authoritative
- * implementation (Story #4048 B3 — multiplied helpers).
- *
- * `resolveConsumerPinVersion` (Story #4530) lives here for the same
- * no-mirror-copies reason rather than in either file directly: `update.js`
- * already imports `registry.js` (for the drift-check fallback), so a
- * function needed by both would otherwise force a two-way circular import
- * between them. This module is a dependency-free leaf both already import.
- *
- * Builtins only — this module is imported from both the CLI surface
- * (`lib/cli/`) and the doctor registry which runs before third-party
- * packages are guaranteed to be present.
- *
- * The two filesystem-touching helpers below take the module's injectable
- * seam as their optional final `fsImpl` parameter, defaulting to the real
- * `node:fs` (`.agents/rules/test-seams.md` rules 1-2);
- * `resolveConsumerPinVersion` forwards that seam to
- * `resolveConsumerPinSpec` rather than re-acquiring `fs` itself (rule 4).
- * Every other export here is pure, so it needs no seam of its own.
+ * Version parse/compare and consumer-pin helpers shared by `update.js` and
+ * `registry.js`. A dependency-free, builtins-only leaf: `update.js` imports
+ * `registry.js` (a cycle otherwise), and the doctor registry runs before
+ * third-party packages are guaranteed present.
  */
 
 import nodeFs from 'node:fs';
 import path from 'node:path';
 
-/** The published package whose consumer pin is resolved below. */
 const PACKAGE_NAME = 'mandrel';
 
 /**
- * Parse a dotted semver-ish string into a numeric tuple. Non-numeric or
- * missing segments coerce to 0 so a partial version still compares sanely.
+ * Missing or non-numeric segments coerce to 0.
  *
  * @param {string} version
  * @returns {[number, number, number]}
@@ -48,8 +27,7 @@ export function parseVersion(version) {
 }
 
 /**
- * Compare two version strings. Negative when `a < b`, zero when equal,
- * positive when `a > b` (the standard `Array.sort` comparator contract).
+ * `Array.sort` comparator contract.
  *
  * @param {string} a
  * @param {string} b
@@ -65,10 +43,6 @@ export function compareVersions(a, b) {
 }
 
 /**
- * True when `target`'s major axis is strictly greater than `current`'s —
- * the gated "crosses a major boundary" condition used by the update
- * orchestrator.
- *
  * @param {string} current
  * @param {string} target
  * @returns {boolean}
@@ -78,25 +52,8 @@ export function crossesMajor(current, target) {
 }
 
 /**
- * Does `version` satisfy the range described by `spec` — a
- * `{ operator, version }` pin spec as returned by
- * {@link resolveConsumerPinSpec}?
- *
- * A deliberately minimal caret/tilde/exact implementation rather than a
- * `semver` dependency: `version-helpers.js` is builtins-only (it is imported
- * by the doctor registry, which runs before third-party packages are
- * guaranteed to be present), and the only ranges
- * {@link resolveConsumerPinSpec} ever yields are `^`, `~`, and exact.
- *
- * Semantics match npm's:
- * - `''` (exact)  → `version === spec.version`
- * - `~1.2.3`      → `>=1.2.3 <1.3.0`
- * - `^1.2.3`      → `>=1.2.3 <2.0.0`
- * - `^0.2.3`      → `>=0.2.3 <0.3.0` (0.x: the minor axis is the API axis)
- * - `^0.0.3`      → `>=0.0.3 <0.0.4`
- *
- * Prerelease tags are ignored on both sides, consistent with
- * {@link parseVersion}'s numeric-tuple contract.
+ * npm caret/tilde/exact semantics (incl. 0.x caret), prereleases ignored —
+ * the only ranges {@link resolveConsumerPinSpec} yields, so no `semver` dep.
  *
  * @param {string} version
  * @param {{ operator: '^' | '~' | '', version: string }} spec
@@ -120,20 +77,10 @@ export function satisfiesPinSpec(version, spec) {
 }
 
 /**
- * Read the consumer's declared `mandrel` dependency pin from
- * `<consumerRoot>/package.json` (checking `dependencies` then
- * `devDependencies`), returning both the range `operator` and the base
- * `version` it decorates.
- *
- * Callers that only need to decide whether `npm install mandrel@<target>`
- * would move the declared pin want {@link resolveConsumerPinVersion} (the
- * base version alone). Callers that need to ask whether an installed
- * version is *in range* — `mandrel doctor`'s `pin-current` check — need the
- * operator too, because `^2.1.0` and `2.1.0` make very different claims
- * about an installed 2.4.0.
- *
- * Returns `null` under exactly the same conditions as
- * {@link resolveConsumerPinVersion} — see its contract.
+ * The consumer's declared `mandrel` pin (dependencies, then devDependencies)
+ * as operator + base version; the operator matters for in-range checks.
+ * `null`, never a throw, for no readable manifest, no entry, or anything but
+ * a plain exact/caret/tilde semver (`workspace:`, `latest`, ranges, …).
  *
  * @param {string} consumerRoot
  * @param {typeof nodeFs} [fsImpl]
@@ -165,28 +112,8 @@ export function resolveConsumerPinSpec(consumerRoot, fsImpl = nodeFs) {
 }
 
 /**
- * Read the consumer's declared `mandrel` dependency pin from
- * `<consumerRoot>/package.json` (checking `dependencies` then
- * `devDependencies`), stripping a leading `^`/`~` range operator to
- * recover a base semver for comparison against the registry's newest
- * published version.
- *
- * A base-version compare against the target is the right question here
- * regardless of what the full range technically already matches: the
- * declared pin is exactly what `npm install mandrel@<target>` (the
- * `mandrel update` `npm-update` step) moves, so comparing its base version
- * decides whether that step needs to run.
- *
- * Returns `null` — never throws — when there is no readable `package.json`,
- * no `mandrel` entry in either dependency block, or the declared value
- * isn't a plain exact/caret/tilde semver (a `workspace:`/`file:`/`git+`
- * specifier, `latest`, `*`, or a comparator range). Callers fall back to
- * resolving the actually-installed version in that case — see
- * `lib/cli/update.js#resolveCurrentVersionForUpdate` and
- * `lib/cli/registry.js`'s `pin-current` doctor check (both Story #4530),
- * which is also how a project with no `mandrel` dependency at all —
- * including mandrel's own repo, which carries no self-dependency —
- * degrades to a clean skip rather than a false failure.
+ * The pin's base version: what `npm-update` moves, so comparing it decides
+ * whether that step runs whatever the range already matches.
  *
  * @param {string} consumerRoot
  * @param {typeof nodeFs} [fsImpl]

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

@@ -1,53 +1,20 @@
 // 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.
+ * Scaffold for steps that strip a retired `.agentrc` key (its block is
+ * `additionalProperties: false`, so a surviving key fails validation on
+ * upgrade). The default sweep includes `.agentrc.local.json`: the resolver
+ * merges it before validation. Prune depth is per-key, since pruning a
+ * required block is a gratuitous edit. Builtins only: runs during `mandrel
+ * update` before third-party packages are guaranteed 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,
@@ -64,8 +31,7 @@ function resolveAgentrcPath(ctx, filename) {
 }
 
 /**
- * Read and parse one config surface. An absent or unparseable file is the
- * common case (no overlay, fresh checkout), not an error.
+ * Absent or unparseable is the common case (no overlay), not an error.
  *
  * @param {unknown} ctx
  * @param {string} filename
@@ -82,9 +48,7 @@ function readAgentrcConfig(ctx, filename, fsImpl) {
 }
 
 /**
- * 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.
+ * Every container along the key path; `null` if any level is missing.
  *
  * @param {object | null} config
  * @param {string[]} keyPath
@@ -116,8 +80,7 @@ function hasKey(config, keyPath) {
 }
 
 /**
- * Delete the leaf key, then remove up to `pruneDepth` ancestors that the
- * deletion left empty. `pruneDepth: 0` deletes the key and nothing else.
+ * Delete the leaf, then up to `pruneDepth` ancestors it left empty.
  *
  * @param {object} config
  * @param {{ path: string[], pruneDepth?: number }} key
@@ -142,12 +105,8 @@ function stripKey(config, key) {
 }
 
 /**
- * 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.
+ * `apply` rewrites only surfaces carrying a key, so a repeat pass never
+ * reformats.
  *
  * @param {{
  *   version: string,

package/lib/migrations/index.js

@@ -1,55 +1,8 @@
 // lib/migrations/index.js
 /**
- * Version-keyed migration runner.
- *
- * A migration is a one-time, version-gated transformation of a consumer
- * project's on-disk state (config shape, baseline layout, materialized
- * `.agents/` tree, …). When a consumer upgrades `mandrel` across a
- * version boundary that changed a contract (see
- * `.agents/rules/git-conventions.md` § Contract Cutovers), the upgrade path
- * runs every migration whose `version` falls inside the upgrade range so the
- * consumer's working tree matches the new release.
- *
- * The engine here is deliberately content-free: it owns ordering, version
- * filtering, idempotency enforcement, and the actionable log line. The
- * `migrations` registry is the single source of truth for which steps exist
- * and in what order they run.
- *
- * ## Step shape
- *
- * Each entry in `migrations` is:
- *
- * ```js
- * {
- *   version: '1.4.0',                  // semver the step graduates the tree to
- *   description: 'rename foo to bar',  // short, operator-facing summary
- *   detect(ctx) { return boolean },    // true ⇒ this step still needs applying
- *   apply(ctx) { ... },                // perform the change (mutates ctx state)
- * }
- * ```
- *
- * ## Idempotency contract
- *
- * `detect(ctx)` MUST return `false` once `apply(ctx)` has run against the same
- * context. The runner consults `detect` before every `apply`, so a step whose
- * change is already present is skipped. This makes a second `runMigrations`
- * pass over the same context a no-op — the property the unit test asserts.
- *
- * ## Version filtering
- *
- * `runMigrations({ fromVersion, toVersion, ctx })` applies only steps whose
- * `version` is strictly greater than `fromVersion` and less than or equal to
- * `toVersion`, in ascending version order. A step at exactly `fromVersion` is
- * already in the tree (the consumer was on that version) and is skipped; a
- * step at exactly `toVersion` is the target and runs.
- *
- * v2.0.0's Story-collapse cutover did not register a config migration step
- * (consumers wipe/re-sync `.agents/` and re-seed `.agentrc.json` from the
- * starter). Story #4531 registered the first real step — see
- * `steps/2.1.0-retire-mi-drop-knobs.js` — alongside the fixture steps in
- * `__tests__/index.test.js` that prove the machinery independent of any
- * real step. When the next contract cutover lands, add its step here
- * (ascending by version) with an idempotent `detect`/`apply`.
+ * Version-keyed migration runner. A step is `{ version, description,
+ * detect(ctx), apply(ctx) }`; `detect` MUST return false once `apply` has run
+ * on the same ctx, which makes a repeat pass a no-op.
  */
 
 import { compareVersions } from '../cli/version-helpers.js';
@@ -61,10 +14,11 @@ import { retireCodebaseSnapshot } from './steps/2.20.0-retire-codebase-snapshot.
 import { retireLintBaselineCommand } from './steps/2.32.0-retire-lint-baseline-command.js';
 import { retireDeliveryLimitKnobs } from './steps/2.57.0-retire-delivery-limit-knobs.js';
 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 { stripRemovedAgentrcKeys } from './steps/strip-removed-agentrc-keys.js';
 
 /**
- * Ordered registry of migration steps. MUST stay sorted ascending by
- * `version`.
+ * MUST stay sorted ascending by `version`.
  *
  * @type {Array<{
  *   version: string,
@@ -82,29 +36,15 @@ export const migrations = [
   retireLintBaselineCommand,
   retirePlanningLimitKnobs,
   retireDeliveryLimitKnobs,
+  retireAuditResultsAutoFile,
+  stripRemovedAgentrcKeys,
 ];
 
-/**
- * The version ordering every migration decision uses.
- *
- * 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.
- */
 export { compareVersions };
 
 /**
- * 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.
+ * `fromVersion < step.version <= toVersion`, ascending. Shared with
+ * `mandrel migrate --dry-run` so the preview cannot drift from the run.
  *
  * @param {{ registry?: Array<object>, fromVersion: string, toVersion: string }} params
  * @returns {Array<object>}
@@ -124,35 +64,20 @@ export function selectStepsInRange({
 }
 
 /**
- * Run the version-keyed migrations between two versions.
- *
- * Steps are filtered to `fromVersion < version <= toVersion`, sorted ascending
- * by version, and applied in order. Before each `apply`, the step's `detect`
- * is consulted: a step whose change is already present (detect returns false)
- * is skipped, which is what makes a repeat pass a no-op. Every step that
- * actually applies prints `migrated <version>: <description>` through the
- * injected `log` seam.
+ * Apply each in-range step whose `detect` is true.
  *
  * @param {object} params
- * @param {string} params.fromVersion - Version the tree is currently on
- *   (exclusive lower bound).
- * @param {string} params.toVersion - Version the tree is upgrading to
- *   (inclusive upper bound).
- * @param {unknown} params.ctx - Opaque context threaded to each step's
- *   `detect`/`apply`. Migrations mutate this to record their change.
- * @param {(message: string) => void} [params.log] - Log seam for the
- *   actionable per-step line. Defaults to `console.log`. Injected by tests so
- *   no real stdout write occurs.
+ * @param {string} params.fromVersion - Exclusive.
+ * @param {string} params.toVersion - Inclusive.
+ * @param {unknown} params.ctx
+ * @param {(message: string) => void} [params.log]
  * @param {Array<{
  *   version: string,
  *   description: string,
  *   detect: (ctx: unknown) => boolean,
  *   apply: (ctx: unknown) => void,
- * }>} [params.registry] - Step registry. Defaults to the module `migrations`
- *   array; injected by tests with fixture steps.
- * @returns {{ applied: string[], skipped: string[] }} The versions that
- *   applied and those that were in-range but skipped because `detect` returned
- *   false.
+ * }>} [params.registry]
+ * @returns {{ applied: string[], skipped: string[] }}
  */
 export function runMigrations({
   fromVersion,

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

@@ -1,20 +1,7 @@
 // lib/migrations/steps/2.1.0-retire-mi-drop-knobs.js
 /**
- * Story #4531 — the first real step in the migration registry.
- *
- * `delivery.quality.codingGuardrails.miDropMustRefactor` and
- * `delivery.quality.autoRefresh.miDropCap` were schema-validated, defaulted,
- * and seeded by `apply-quality-bootstrap.js` into a consumer's
- * `.agentrc.json` — but never consumed by the gate they were named for
- * (`maintainability.tolerance` is the knob actually in force; see the
- * Story body for the full diagnosis). Both retired keys lived under
- * 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`.
+ * Strip the never-read MI-drop knobs. Base config only: the bootstrap script
+ * wrote them, never an operator's local overlay.
  */
 
 import {

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

@@ -1,17 +1,5 @@
 // lib/migrations/steps/2.1.0-retire-verify-concurrency-cap.js
-/**
- * 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
- * validates the *merged* result, so a key left in the local file fails the
- * same way a key in the committed file does.
- */
+/** Strip `delivery.deliverRunner.verifyConcurrencyCap`. */
 
 import { createRetireAgentrcKeyStep } from '../helpers/retire-agentrc-key.js';
 

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

@@ -1,20 +1,7 @@
 // lib/migrations/steps/2.11.0-retire-max-seed-words.js
 /**
- * Story #4722 follow-up — strip the retired
- * `planning.complexityGate.maxSeedWords` knob from a consumer's
- * `.agentrc.json`.
- *
- * #4722 (PR #4725) hard-cutover-removed word-count complexity routing:
- * the route derives from the authored Story's shape, never from seed word
- * count, and `maxSeedWords` was dropped from the runtime AJV schema and
- * the published mirror. The `complexityGate` block carries
- * `additionalProperties: false`, so a consumer whose config still sets
- * `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.
+ * Strip `planning.complexityGate.maxSeedWords`, pruning emptied optional
+ * ancestors.
  */
 
 import {