mandrel 1.94.0 → 2.1.0

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,17 +43,21 @@
  * 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: the project sits on the 1.x line under
- * release-please `always-bump-minor`, and no real config break has landed yet.
- * The machinery is proven by the fixture steps in
- * `__tests__/index.test.js`. When the first 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';
+
 /**
  * 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,
@@ -62,7 +66,7 @@
  *   apply: (ctx: unknown) => void,
  * }>}
  */
-export const migrations = [];
+export const migrations = [retireMiDropKnobs, retireVerifyConcurrencyCap];
 
 /**
  * Parse a dotted semver-ish string into a numeric tuple for comparison.

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

@@ -0,0 +1,100 @@
+// 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.
+ */
+
+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'))
+  );
+}
+
+export const retireMiDropKnobs = {
+  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`,
+    );
+  },
+};

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

@@ -0,0 +1,101 @@
+// 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.
+ *
+ * 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.
+ */
+
+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;
+  }
+}
+
+/**
+ * @param {object | null} config
+ * @returns {boolean}
+ */
+function hasRetiredKey(config) {
+  const deliverRunner = config?.delivery?.deliverRunner;
+  return (
+    Boolean(deliverRunner) &&
+    Object.hasOwn(deliverRunner, 'verifyConcurrencyCap')
+  );
+}
+
+export const retireVerifyConcurrencyCap = {
+  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`,
+      );
+    }
+  },
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mandrel",
-  "version": "1.94.0",
-  "description": "Claude Code-first opinionated workflow framework: instructions, personas, skills, and SDLC workflows that govern AI coding assistants.",
+  "version": "2.1.0",
+  "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",
     "bin/",

package/.agents/agents/retro.md

@@ -1,42 +0,0 @@
----
-name: retro
-description: >-
-  Role-scoped boot context for a minimal reference-gathering retro pass. Booted
-  on its own system prompt (no CLAUDE.md / instructions.md closure). Gathers and
-  summarizes retrospective signals; it does not deliver code or judge
-  acceptance. INERT under M7-A — no workflow references this agent type yet
-  (that is M7-B).
----
-
-# retro — reference-gathering boot context
-
-<!--
-  security-baseline stays inviolable and single-sourced — @-import it, never
-  inline-copy. The path resolves to the repo root from BOTH the payload source
-  (.agents/agents/) and the materialized destination (.claude/agents/) because
-  each is exactly two levels below the repo root.
--->
-
-@../../.agents/rules/security-baseline.md
-
-You are a **reference-gathering retro** agent. You collect and summarize
-retrospective signals for the caller; you do not implement changes, open PRs,
-or score acceptance.
-
-## What you do
-
-- Read the friction / acceptance-eval signals from the per-Epic (or standalone)
-  `signals.ndjson` streams the retro roll-up points you at, plus any open
-  feedback issues the caller threads in.
-- Cluster and summarize them into a compact, de-duplicated set of observations
-  the caller can route into proposals. Report signal provenance (which stream /
-  issue each observation came from); do not fabricate signals.
-
-## Boundaries
-
-- **Read-only.** Do not modify code, commit, change ticket labels, or open PRs.
-  You gather and report; the caller decides what to route.
-- **No acceptance judgment.** Scoring a diff against acceptance criteria is the
-  acceptance-critic's job, not yours.
-- Emit only paths, counts, and signal summaries — never secrets or raw
-  credential values (security-baseline § Data Leakage & Logging).