mandrel 2.35.0 → 2.37.0

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.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 }],
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.35.0",
+  "version": "2.37.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",
@@ -19,7 +19,9 @@
     "test": "node .agents/scripts/run-tests.js",
     "test:quick": "node .agents/scripts/run-tests.js --tier quick",
     "test:integration": "node .agents/scripts/run-tests.js --tier integration",
+    "test:e2e": "node .agents/scripts/run-tests.js --tier e2e",
     "test:profile": "node .agents/scripts/run-test-profile.js",
+    "test:census": "SPAWN_CENSUS_OUT=\"${SPAWN_CENSUS_OUT:-temp/census.json}\" NODE_OPTIONS=\"--require $PWD/tests/fixtures/spawn-census.cjs\" node .agents/scripts/run-tests.js",
     "test:isolate": "node .agents/scripts/test-isolate.js",
     "verify": "node .agents/scripts/run-verify.js",
     "typecheck": "node -e \"process.exit(0)\"",
@@ -31,9 +33,9 @@
     "baselines:scope": "node .agents/scripts/check-baseline-scope.js",
     "baselines:prune": "node .agents/scripts/prune-baseline-orphans.js",
     "lint:md": "markdownlint-cli2 \".agents/**/*.md\" \"*.md\" \"!node_modules/**\" \"!.worktrees/**\"",
-    "lint": "node .agents/scripts/run-lint.js && npm run docs:check",
-    "docs:gen": "node .agents/scripts/generate-config-docs.js && node .agents/scripts/generate-lifecycle-docs.js && node .agents/scripts/generate-workflows-doc.js && node .agents/scripts/generate-lens-checklists.js",
-    "docs:check": "node .agents/scripts/generate-config-docs.js --check && node .agents/scripts/generate-lifecycle-docs.js --check && node .agents/scripts/generate-workflows-doc.js --check && node .agents/scripts/generate-lens-checklists.js --check && node .agents/scripts/check-doc-links.js && npm run skills:check",
+    "lint": "node .agents/scripts/run-lint.js && node .agents/scripts/check-generated-validator.js --check && npm run docs:check",
+    "docs:gen": "node .agents/scripts/generate-config-docs.js && node .agents/scripts/generate-workflows-doc.js && node .agents/scripts/generate-lens-checklists.js",
+    "docs:check": "node .agents/scripts/generate-config-docs.js --check && node .agents/scripts/generate-workflows-doc.js --check && node .agents/scripts/generate-lens-checklists.js --check && node .agents/scripts/check-doc-links.js && npm run skills:check",
     "skills:index": "node .agents/scripts/generate-skills-index.js",
     "skills:check": "node .agents/scripts/generate-skills-index.js --check",
     "format": "biome format --write .",
@@ -47,6 +49,8 @@
     "cyclomatic:update": "node .agents/scripts/check-cyclomatic.js --update",
     "dead-exports:update": "node .agents/scripts/update-dead-exports-baseline.js && node .agents/scripts/update-dead-exports-baseline.js --production",
     "check:knip-entries": "node .agents/scripts/check-knip-entries.js",
+    "validator:gen": "node .agents/scripts/check-generated-validator.js",
+    "validator:check": "node .agents/scripts/check-generated-validator.js --check",
     "check:schema-refs": "node .agents/scripts/check-schema-references.js",
     "check:workflow-citations": "node .agents/scripts/check-workflow-citations.js",
     "crap:check": "node .agents/scripts/check-baselines.js --gate crap",
@@ -101,7 +105,7 @@
     "markdownlint-cli2": "^0.22.1",
     "memfs": "^4.57.7",
     "node-pty": "^1.0.0",
-    "typescript": ">=5.0.0"
+    "typescript": "^6.0.3"
   },
   "dependencies": {
     "ajv": "^8.20.0",