mandrel 2.0.0 → 2.2.0

package/lib/cli/sync.js

@@ -26,6 +26,16 @@
  *     managed `.agents/` zone (everything except `.agents/local/`) that has
  *     no counterpart in the package payload is deleted. Consumer additions
  *     under `.agents/local/` are never touched.
+ *   - Generated, never-pruned registry (Story #4534). Framework-generated
+ *     `.agents/` files have no payload counterpart by design, so the prune
+ *     pass would delete each one unless it is declared in
+ *     {@link GENERATED_FILES}. That registry — not a per-file special case in
+ *     {@link listDestFiles} — is the single place a generated artifact is
+ *     exempted. Registered today: the version marker (Story #4530) and the
+ *     install ledger the bootstrap writes and `mandrel uninstall` reads.
+ *   - Version marker (Story #4530). After the prune pass, `.agents/.mandrel-
+ *     version` is (re)written with the executing package's own version. See
+ *     {@link readVersionMarker} for how callers consume it.
  *
  * Security (Tech Spec #3459 "Postinstall safety"):
  *   - Does nothing beyond a local file copy: no network, no shell, no writes
@@ -45,8 +55,19 @@ import nodeFs from 'node:fs';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 
+import { LEDGER_RELATIVE_PATH } from '../../.agents/scripts/lib/bootstrap/install-ledger.js';
+
 export const PACKAGE_NAME = 'mandrel';
 
+/**
+ * Name of the managed destination directory, relative to the project root.
+ * Generating modules export their artifact paths relative to the *project
+ * root* (e.g. `install-ledger.js`'s `LEDGER_RELATIVE_PATH`), whereas the
+ * prune pass compares paths relative to this directory — {@link
+ * toManagedZoneRelative} is the one conversion between the two.
+ */
+const AGENTS_DIR = '.agents';
+
 /**
  * Top-level directory name (relative to `.agents/`) reserved as the
  * sync-exempt local-additions zone (Story #3498, f-drift-local-zone).
@@ -70,6 +91,119 @@ export const LOCAL_ZONE_DIR = 'local';
  */
 export const LOCAL_OVERRIDE_RE = /\.local\.[^.]+$/;
 
+/**
+ * Relative path (from `.agents/`) of the version marker `runSync` writes
+ * after every sync, carrying the executing package's own version.
+ */
+export const VERSION_MARKER_RELATIVE_PATH = '.mandrel-version';
+
+/**
+ * Convert a project-root-relative POSIX path — the shape a generating module
+ * exports as its own source of truth (e.g. `install-ledger.js`'s
+ * `LEDGER_RELATIVE_PATH`, `'.agents/.install-manifest.json'`) — into the
+ * `.agents/`-relative, OS-separator form {@link listDestFiles} enumerates and
+ * {@link GENERATED_FILES} is compared against.
+ *
+ * Throws on a path outside `.agents/`: a generated file the sync prune pass
+ * never walks has no business in the registry, and registering one would be a
+ * silent no-op that reads as protection. Failing at module load surfaces the
+ * mistake at the first import rather than as a mystery deletion in a
+ * consumer's tree.
+ *
+ * @param {string} projectRelativePosixPath - e.g. `.agents/.install-manifest.json`.
+ * @returns {string} e.g. `.install-manifest.json` (OS separators).
+ */
+function toManagedZoneRelative(projectRelativePosixPath) {
+  const segments = projectRelativePosixPath.split('/');
+  if (segments[0] !== AGENTS_DIR || segments.length < 2) {
+    throw new Error(
+      `generated-files registry: '${projectRelativePosixPath}' is not inside ${AGENTS_DIR}/ — ` +
+        'only files the sync prune pass walks can be registered as never-pruned.',
+    );
+  }
+  return path.join(...segments.slice(1));
+}
+
+/**
+ * The **generated, never-pruned registry**: every framework-generated
+ * `.agents/` file that has no payload counterpart and must therefore be
+ * exempted from the prune pass. Paths are `.agents/`-relative with OS
+ * separators, matching what {@link listDestFiles} enumerates.
+ *
+ * The prune pass (Story #4046 A3) deletes any managed-zone file absent from
+ * the payload. That is the correct rule for consumer drift, but it is also
+ * exactly the shape of every file the framework itself generates into
+ * `.agents/` outside the payload — so each such artifact is deleted by the very
+ * sync that wrote it unless registered here. Two have hit this already: the
+ * install ledger (`.agents/.install-manifest.json`), whose loss made
+ * `mandrel uninstall` silently reverse nothing and exit 0 (Story #4534), and
+ * the version marker (Story #4530).
+ *
+ * This is deliberately a **registry, not a list of special cases**. Register a
+ * new generated file by adding one entry here — keyed off the generating
+ * module's own exported constant wherever one exists, never a duplicated
+ * string literal — rather than by adding another branch to
+ * {@link listDestFiles}. That keeps the never-prune contract declared in one
+ * place and keeps the registry honest: if the generator renames its artifact,
+ * the exemption moves with it.
+ *
+ * This registry does **not** subsume the `.agents/local/` zone or the
+ * `*.local.*` overrides ({@link LOCAL_ZONE_DIR}, {@link LOCAL_OVERRIDE_RE}).
+ * Those are a different concept — consumer-authored overrides, not
+ * framework-generated artifacts — and stay separate on purpose.
+ */
+export const GENERATED_FILES = Object.freeze([
+  // Version marker (Story #4530) — written by runSync itself, below.
+  VERSION_MARKER_RELATIVE_PATH,
+  // Install ledger (Story #4534) — written by the bootstrap
+  // (`install-ledger.js`), read by `mandrel uninstall` as its single source of
+  // truth. Keyed off the generator's exported constant.
+  toManagedZoneRelative(LEDGER_RELATIVE_PATH),
+]);
+
+/**
+ * Resolve the version of the package whose `.agents/` payload was just
+ * copied — i.e. the version the marker must carry. Reads `package.json` at
+ * the already-resolved `packageRoot`, never the two-directories-up
+ * self-referential pattern `lib/cli/update.js`'s pre-Story-#4530
+ * `defaultCurrentVersion` used (that pattern conflates "the CLI that is
+ * running" with "the payload that was materialized" — the exact confusion
+ * #4525 fixes on the consumer-pin side of this Story).
+ *
+ * @param {string} packageRoot - Absolute path to the resolved package root.
+ * @param {typeof nodeFs} fsImpl
+ * @returns {string}
+ */
+function resolvePackageVersion(packageRoot, fsImpl) {
+  const pkgJsonPath = path.join(packageRoot, 'package.json');
+  const parsed = JSON.parse(fsImpl.readFileSync(pkgJsonPath, 'utf8'));
+  return String(parsed.version);
+}
+
+/**
+ * Read the consumer's `.agents/.mandrel-version` marker. Returns `null` when
+ * absent — a pre-marker install, or a tree that has never been synced —
+ * so callers (the sync-commands mismatch refusal, the doctor pin check) can
+ * degrade to their existing content-hash drift check rather than failing.
+ *
+ * @param {string} consumerRoot - Consumer project root (not `.agents/`).
+ * @param {typeof nodeFs} [fsImpl]
+ * @returns {string | null}
+ */
+export function readVersionMarker(consumerRoot, fsImpl = nodeFs) {
+  const markerPath = path.join(
+    consumerRoot,
+    '.agents',
+    VERSION_MARKER_RELATIVE_PATH,
+  );
+  try {
+    const raw = fsImpl.readFileSync(markerPath, 'utf8').trim();
+    return raw || null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Default resolver: locate the installed `mandrel` package root by
  * resolving its `package.json` and returning the directory that contains it.
@@ -126,12 +260,22 @@ export function listFiles(dir, fsImpl, prefix = '') {
 
 /**
  * Recursively enumerate every regular file under `dir`, returning paths
- * relative to `dir` using OS separators. The top-level `local/` subtree is
- * skipped so consumer additions inside `.agents/local/` are never pruned
- * (Story #3498). Files following the `*.local.*` naming convention (e.g.
- * `.agents/instructions.local.md` — the documented consumer override
- * mechanism, instructions.md § 1.E) are also skipped: they never ship in
- * the payload and must survive every sync.
+ * relative to `dir` using OS separators. Three disjoint classes are skipped,
+ * so a caller diffing this against the payload never treats them as stale:
+ *
+ *   1. The top-level `local/` subtree — consumer additions inside
+ *      `.agents/local/` are never pruned (Story #3498).
+ *   2. Files matching the `*.local.*` convention (e.g.
+ *      `.agents/instructions.local.md`) — the documented consumer override
+ *      mechanism (instructions.md § 1.E); they never ship in the payload and
+ *      must survive every sync.
+ *   3. Everything declared in the {@link GENERATED_FILES} registry —
+ *      framework-generated artifacts with no payload counterpart by design
+ *      (Story #4534). New generated files are registered there, not added as
+ *      a fourth branch here.
+ *
+ * (1) and (2) are consumer-authored; (3) is framework-generated. They are
+ * kept separate deliberately — conflating them would muddy both contracts.
  *
  * Mirrors `listFiles` but operates on the destination tree so we can
  * identify stale files that have no payload counterpart (Story #4046 A3).
@@ -162,6 +306,11 @@ function listDestFiles(dir, fsImpl, prefix = '') {
       continue;
     }
     const rel = prefix ? path.join(prefix, ent.name) : ent.name;
+    // Framework-generated artifacts — declared once in the never-pruned
+    // registry (Story #4534); see GENERATED_FILES.
+    if (!ent.isDirectory() && GENERATED_FILES.includes(rel)) {
+      continue;
+    }
     const abs = path.join(dir, ent.name);
     if (ent.isDirectory()) {
       out.push(...listDestFiles(abs, fsImpl, rel));
@@ -273,6 +422,19 @@ export function runSync({
     fs.unlinkSync(dest);
   }
 
+  // Version marker (Story #4530): written AFTER the prune pass, never
+  // before — the GENERATED_FILES registry already keeps listDestFiles from
+  // ever enumerating it as stale, but ordering the write after prune is a
+  // second, independent safeguard against the same class of bug (see the
+  // GENERATED_FILES doc comment) surviving a future prune-pass reorder. The
+  // install ledger gets no such belt-and-braces: it is written by the
+  // bootstrap, not here, so the registry is its only protection.
+  const packageVersion = resolvePackageVersion(packageRoot, fs);
+  fs.writeFileSync(
+    path.join(destRoot, VERSION_MARKER_RELATIVE_PATH),
+    `${packageVersion}\n`,
+  );
+
   if (staleFiles.length > 0) {
     write(
       `✅  Installed ${payloadFiles.length} file(s) into ./.agents/ (pruned ${staleFiles.length} stale file(s))\n`,

package/lib/cli/update.js

@@ -136,8 +136,12 @@ import { fileURLToPath } from 'node:url';
 import { detectPackageManagerWithWorkspace } from '../../.agents/scripts/lib/detect-package-manager.js';
 import { runInstallCommand } from '../../.agents/scripts/lib/install-cmd-parser.js';
 import { runAgentsDrift } from './registry.js';
+import { defaultResolvePackageRoot } from './sync.js';
 import { isStale } from './version-check.js';
-import { compareVersions } from './version-helpers.js';
+import {
+  compareVersions,
+  resolveConsumerPinVersion,
+} from './version-helpers.js';
 
 /** The published package whose newest version `mandrel update` advances to. */
 const PACKAGE_NAME = 'mandrel';
@@ -163,6 +167,15 @@ const DEFAULT_CACHE_FILENAME = 'version-check.json';
  * `package.json`. The module lives at `<root>/lib/cli/update.js`, so the
  * manifest is two directories up.
  *
+ * Pre-Story-#4525 this was the update decision's `current` — the exact
+ * self-referential confusion #4525 filed: "the version of the mandrel that
+ * is executing" is tautologically `>= target` whenever the installed
+ * package is newest, which made the `npm-update` step unreachable whenever
+ * a consumer's declared pin had fallen behind what happened to be resolved
+ * in `node_modules`. It survives here only as the last-resort fallback
+ * inside {@link resolveCurrentVersionForUpdate}, for the case where even
+ * `node_modules` resolution from the consumer root fails.
+ *
  * @param {typeof nodeFs} [fs]
  * @returns {string}
  */
@@ -173,6 +186,48 @@ function defaultCurrentVersion(fs = nodeFs) {
   return String(parsed.version);
 }
 
+/**
+ * Resolve the "current" version for the `mandrel update` decision
+ * (Story #4525 / #4530): the consumer's declared `mandrel` dependency pin
+ * when it resolves to a plain semver, falling back — in order — to the
+ * version actually resolvable in the consumer's `node_modules` (anchored at
+ * `consumerRoot` via the same resolution `mandrel sync` uses, unlike the
+ * pre-#4525 self-referential `defaultCurrentVersion`), and finally to
+ * `defaultCurrentVersion` itself when neither resolves (a corrupted or
+ * highly unusual install — keeps `mandrel update` from throwing outright
+ * rather than silently misreporting "already current").
+ *
+ * The declared pin is preferred because it is exactly what the `npm-update`
+ * step moves: a consumer whose `package.json` pin lags an inflated
+ * `node_modules` resolution (e.g. an out-of-band symlink or manual
+ * `npm install mandrel@latest --no-save`) must still see `planUpdate`
+ * choose `updated`, not `resynced` — the bug #4525 reported.
+ *
+ * @param {string} consumerRoot
+ * @param {typeof nodeFs} [fs]
+ * @param {{ resolvePackageRoot?: (fromDir: string) => string }} [opts] - test
+ *   seam for the `node_modules` resolution tier; defaults to the real
+ *   `defaultResolvePackageRoot` from `sync.js`.
+ * @returns {string}
+ */
+export function resolveCurrentVersionForUpdate(
+  consumerRoot,
+  fs = nodeFs,
+  { resolvePackageRoot = defaultResolvePackageRoot } = {},
+) {
+  const pinned = resolveConsumerPinVersion(consumerRoot, fs);
+  if (pinned) return pinned;
+  try {
+    const packageRoot = resolvePackageRoot(consumerRoot);
+    const parsed = JSON.parse(
+      fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'),
+    );
+    return String(parsed.version);
+  } catch {
+    return defaultCurrentVersion(fs);
+  }
+}
+
 /**
  * Resolve the project root — the directory two levels up from this module
  * (`<root>/lib/cli/update.js`). Mirrors `lib/cli/registry.js#resolveProjectRoot`.
@@ -685,18 +740,20 @@ export function defaultSpawnPhase(
  * The ordered step names the orchestrator drives on an update. Shared
  * by the live path and the `--dry-run` plan printout so the two never drift.
  *
- * Step ordering (Story #4046 A1c):
+ * Step ordering (Story #4046 A1c; sync-agents added by Story #4528/#4530):
  *   1. npm-update     — install the new version
  *   2. runSync        — re-materialize .agents/ from the new payload
  *   3. sync-commands  — regenerate .claude/commands/ from the new payload
- *   4. runMigrations  — apply version-keyed migrations
- *   5. doctor         — validate the post-upgrade state
- *   6. surface changelog — print the changelog (always last, best-effort)
+ *   4. sync-agents    — regenerate .claude/agents/ from the new payload
+ *   5. runMigrations  — apply version-keyed migrations
+ *   6. doctor         — validate the post-upgrade state
+ *   7. surface changelog — print the changelog (always last, best-effort)
  */
 const STEP_PLAN = [
   'npm-update',
   'runSync',
   'sync-commands',
+  'sync-agents',
   'runMigrations',
   'doctor',
   'surface changelog',
@@ -744,6 +801,20 @@ function fullUpgradeSteps(current, target) {
         'the .claude/commands/ tree may be out of sync. ' +
         'Run `npm run sync:commands` manually to restore.',
     },
+    {
+      // Story #4528/#4530: the CLI update path previously never projected the
+      // role-agent tree at all — only the bootstrap path did. Added alongside
+      // sync-commands so `.claude/agents/` materializes here too, which is
+      // what makes the tightened `agents-in-sync` doctor check satisfiable.
+      kind: 'spawn',
+      phase: 'sync-agents',
+      args: [],
+      label: 'sync-agents',
+      failMessage:
+        'mandrel update: `mandrel sync-agents` from new binary exited non-zero — ' +
+        'the .claude/agents/ tree may be out of sync. ' +
+        'Run `mandrel sync-agents` manually to restore.',
+    },
     {
       kind: 'spawn',
       phase: 'migrate',
@@ -760,8 +831,9 @@ function fullUpgradeSteps(current, target) {
 
 /**
  * The ordered phase descriptors for a drift-heal (version already current, but
- * `.agents/` is stale). No npm-update, no migrations, no doctor — only the two
- * sync phases re-materialize the payload from the already-installed binary.
+ * `.agents/` is stale). No npm-update, no migrations, no doctor — only the
+ * three sync phases re-materialize the payload from the already-installed
+ * binary.
  *
  * @returns {Array<{ kind: 'spawn', phase: string, args: string[], label: string, failMessage: string }>}
  */
@@ -787,6 +859,17 @@ function driftHealSteps() {
         'the .claude/commands/ tree may be out of sync. ' +
         'Run `npm run sync:commands` manually to restore.',
     },
+    {
+      // Story #4528/#4530: see the matching entry in fullUpgradeSteps().
+      kind: 'spawn',
+      phase: 'sync-agents',
+      args: [],
+      label: 'sync-agents',
+      failMessage:
+        'mandrel update: `mandrel sync-agents` from installed binary exited non-zero — ' +
+        'the .claude/agents/ tree may be out of sync. ' +
+        'Run `mandrel sync-agents` manually to restore.',
+    },
   ];
 }
 
@@ -1070,6 +1153,9 @@ export async function runUpdate({
       write(
         '  2. sync-commands  — regenerate .claude/commands/ from .agents/workflows/\n',
       );
+      write(
+        '  3. sync-agents    — regenerate .claude/agents/ from .agents/agents/\n',
+      );
       write('Dry run: no files written.\n');
     } else {
       write(`mandrel update — planned upgrade v${current} → v${target}\n`);
@@ -1202,6 +1288,8 @@ export async function runUpdate({
  *   changelogPath?: string,
  *   fetchChangelog?: (version: string) => Promise<string>,
  *   runUpdate?: typeof runUpdate,
+ *   cwd?: () => string,
+ *   checkDrift?: () => (boolean | Promise<boolean>),
  *   write?: (s: string) => void,
  *   writeErr?: (s: string) => void,
  *   exit?: (code: number) => void,
@@ -1224,9 +1312,16 @@ export default async function run(argv = [], deps = {}) {
     writeErr = (s) => process.stderr.write(s),
     exit = (code) => process.exit(code),
     log,
+    cwd,
+    checkDrift,
   } = deps;
 
-  const current = deps.currentVersion ?? defaultCurrentVersion(fs);
+  const cwdFn = typeof cwd === 'function' ? cwd : () => process.cwd();
+
+  // Story #4525/#4530: prefer the consumer's declared dependency pin over
+  // the pre-#4525 self-referential read — see resolveCurrentVersionForUpdate.
+  const current =
+    deps.currentVersion ?? resolveCurrentVersionForUpdate(cwdFn(), fs);
 
   // The production spawnPhase: spawn each post-install phase from
   // node_modules/.bin/mandrel (the newly-installed binary). This is the sole
@@ -1260,6 +1355,7 @@ export default async function run(argv = [], deps = {}) {
         runInstall: runInstall ?? runInstallCommand,
         fs,
       }),
+    ...(checkDrift ? { checkDrift } : {}),
     spawnPhase: productionSpawnPhase,
     surfaceChangelog: (target) =>
       defaultSurfaceChangelog(target, {
@@ -1273,5 +1369,6 @@ export default async function run(argv = [], deps = {}) {
     write,
     writeErr,
     exit,
+    cwd: cwdFn,
   });
 }

package/lib/cli/version-helpers.js

@@ -7,11 +7,23 @@
  * `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.
  */
 
+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.
@@ -57,3 +69,122 @@ export function compareVersions(a, b) {
 export function crossesMajor(current, target) {
   return parseVersion(target)[0] > parseVersion(current)[0];
 }
+
+/**
+ * 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.
+ *
+ * @param {string} version
+ * @param {{ operator: '^' | '~' | '', version: string }} spec
+ * @returns {boolean}
+ */
+export function satisfiesPinSpec(version, spec) {
+  if (compareVersions(version, spec.version) < 0) return false;
+  const [vMajor, vMinor] = parseVersion(version);
+  const [pMajor, pMinor, pPatch] = parseVersion(spec.version);
+
+  if (spec.operator === '~') {
+    return vMajor === pMajor && vMinor === pMinor;
+  }
+  if (spec.operator === '^') {
+    if (pMajor > 0) return vMajor === pMajor;
+    if (pMinor > 0) return vMajor === 0 && vMinor === pMinor;
+    // ^0.0.x pins the patch axis exactly.
+    return compareVersions(version, `0.0.${pPatch}`) === 0;
+  }
+  return compareVersions(version, spec.version) === 0;
+}
+
+/**
+ * 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.
+ *
+ * @param {string} consumerRoot
+ * @param {typeof nodeFs} [fsImpl]
+ * @returns {{ operator: '^' | '~' | '', version: string } | null}
+ */
+export function resolveConsumerPinSpec(consumerRoot, fsImpl = nodeFs) {
+  let parsed;
+  try {
+    const raw = fsImpl.readFileSync(
+      path.join(consumerRoot, 'package.json'),
+      'utf8',
+    );
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  const declared =
+    parsed?.dependencies?.[PACKAGE_NAME] ??
+    parsed?.devDependencies?.[PACKAGE_NAME];
+  if (typeof declared !== 'string') return null;
+  const match = /^([\^~]?)(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)$/.exec(
+    declared.trim(),
+  );
+  if (!match) return null;
+  return {
+    operator: /** @type {'^' | '~' | ''} */ (match[1]),
+    version: match[2],
+  };
+}
+
+/**
+ * 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.
+ *
+ * @param {string} consumerRoot
+ * @param {typeof nodeFs} [fsImpl]
+ * @returns {string | null}
+ */
+export function resolveConsumerPinVersion(consumerRoot, fsImpl = nodeFs) {
+  return resolveConsumerPinSpec(consumerRoot, fsImpl)?.version ?? null;
+}

package/lib/migrations/README.md

@@ -9,11 +9,13 @@ filtering, idempotency enforcement, and the actionable per-step log line. The
 `migrations` array is the single source of truth for which steps exist and in
 what order they run.
 
-> The registry currently ships **empty**. The project sits on the 1.x line
-> under release-please `always-bump-minor`, and no real contract break has
-> landed yet. The machinery is exercised by fixture steps in
-> [`__tests__/index.test.js`](./__tests__/index.test.js). Add the first real
-> step here when the first contract cutover lands.
+> Story #4531 registered the first real step —
+> [`steps/2.1.0-retire-mi-drop-knobs.js`](./steps/2.1.0-retire-mi-drop-knobs.js),
+> which strips the retired `codingGuardrails.miDropMustRefactor` and
+> `autoRefresh.miDropCap` keys from a consumer's `.agentrc.json`. The
+> machinery itself is still exercised independently by fixture steps in
+> [`__tests__/index.test.js`](./__tests__/index.test.js). Add the next real
+> step here (ascending by version) when the next contract cutover lands.
 
 ## Step shape
 

package/lib/migrations/index.js

@@ -43,18 +43,22 @@
  * already in the tree (the consumer was on that version) and is skipped; a
  * step at exactly `toVersion` is the target and runs.
  *
- * The registry currently ships empty: 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). The machinery is proven
- * by the fixture steps in `__tests__/index.test.js`. When the next real
- * contract cutover lands, add its step here (ascending by version) with
- * an idempotent `detect`/`apply`.
+ * 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`.
  */
 
+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';
+
 /**
  * Ordered registry of migration steps. MUST stay sorted ascending by
- * `version`. Empty until the first real contract cutover graduates a step
- * here.
+ * `version`.
  *
  * @type {Array<{
  *   version: string,
@@ -63,7 +67,11 @@
  *   apply: (ctx: unknown) => void,
  * }>}
  */
-export const migrations = [];
+export const migrations = [
+  retireMiDropKnobs,
+  retireVerifyConcurrencyCap,
+  retireEpicAcTags,
+];
 
 /**
  * Parse a dotted semver-ish string into a numeric tuple for comparison.