mandrel 2.16.0 → 2.18.0

package/.agents/scripts/nav-registry-diff.js

@@ -340,12 +340,13 @@ export function computeNavDiff({ routes = [], nav = [], refs = [] } = {}) {
  *
  * @param {string} label human-readable role for the error message
  * @param {string} file
+ * @param {typeof fs} [fsImpl] filesystem seam; defaults to the real `node:fs`.
  * @returns {unknown[]}
  */
-function readJsonArray(label, file) {
+function readJsonArray(label, file, fsImpl = fs) {
   let raw;
   try {
-    raw = fs.readFileSync(file, 'utf8');
+    raw = fsImpl.readFileSync(file, 'utf8');
   } catch (err) {
     throw new Error(
       `nav-registry-diff: cannot read ${label} file '${file}': ${err.message}`,
@@ -400,10 +401,23 @@ export function formatDiffText(diff) {
 }
 
 /**
- * @param {string[]} argv
+ * The reporter core, extracted from the CLI shell so the argv → read → diff →
+ * render → exit-code path is reachable without touching the real filesystem or
+ * the real stdout.
+ *
+ * Both seams on the optional final `deps` parameter default to the real
+ * implementation (`.agents/rules/test-seams.md` rules 1-2, 4 — `readJsonArray`
+ * forwards `fsImpl` rather than re-acquiring `fs`), so `main` and every
+ * production invocation are unchanged.
+ *
+ * @param {string[]} [argv]
+ * @param {{ fsImpl?: typeof fs, stdout?: { write: (s: string) => void } }} [deps]
  * @returns {Promise<number>} process exit code
  */
-async function main(argv = process.argv.slice(2)) {
+export async function runNavRegistryDiff(
+  argv = process.argv.slice(2),
+  { fsImpl = fs, stdout = process.stdout } = {},
+) {
   const { values } = parseArgs({
     args: argv,
     options: {
@@ -423,9 +437,9 @@ async function main(argv = process.argv.slice(2)) {
     );
   }
 
-  const routes = readJsonArray('routes', values.routes);
-  const nav = readJsonArray('nav', values.nav);
-  const refs = values.refs ? readJsonArray('refs', values.refs) : [];
+  const routes = readJsonArray('routes', values.routes, fsImpl);
+  const nav = readJsonArray('nav', values.nav, fsImpl);
+  const refs = values.refs ? readJsonArray('refs', values.refs, fsImpl) : [];
 
   const diff = computeNavDiff({ routes, nav, refs });
 
@@ -434,13 +448,21 @@ async function main(argv = process.argv.slice(2)) {
   const rendered = values.json
     ? JSON.stringify(diff, null, 2)
     : formatDiffText(diff);
-  process.stdout.write(`${rendered}\n`);
+  stdout.write(`${rendered}\n`);
 
   const hasFindings =
     diff.orphanedRoutes.length > 0 || diff.deadHrefs.length > 0;
   return values.strict && hasFindings ? 1 : 0;
 }
 
+/**
+ * @param {string[]} [argv]
+ * @returns {Promise<number>} process exit code
+ */
+async function main(argv = process.argv.slice(2)) {
+  return runNavRegistryDiff(argv);
+}
+
 export { main };
 
 runAsCli(import.meta.url, main, {

package/.agents/scripts/plan-run-epilogue.js

@@ -27,9 +27,23 @@ const CLI_OPTIONS = {
 
 /**
  * @param {string[]} [argv]
+ * @param {{
+ *   resolveConfigImpl?: typeof resolveConfig,
+ *   createProviderImpl?: typeof createProvider,
+ *   runPlanRunEpilogueImpl?: typeof runPlanRunEpilogue,
+ *   logger?: { info: Function, warn: Function },
+ * }} [deps] Injectable seams; every entry defaults to the real
+ *   implementation (`.agents/rules/test-seams.md` rules 1-2), so the CLI path
+ *   and every production caller are unchanged.
  * @returns {Promise<object>}
  */
-export async function main(argv = process.argv.slice(2)) {
+export async function main(argv = process.argv.slice(2), deps = {}) {
+  const {
+    resolveConfigImpl = resolveConfig,
+    createProviderImpl = createProvider,
+    runPlanRunEpilogueImpl = runPlanRunEpilogue,
+    logger = Logger,
+  } = deps;
   const { values } = parseArgs({
     args: argv,
     options: CLI_OPTIONS,
@@ -44,8 +58,8 @@ export async function main(argv = process.argv.slice(2)) {
     typeof values.cwd === 'string' && values.cwd.trim()
       ? values.cwd.trim()
       : process.cwd();
-  const config = resolveConfig({ cwd });
-  const provider = createProvider(config);
+  const config = resolveConfigImpl({ cwd });
+  const provider = createProviderImpl(config);
 
   // Story #4540 retired the `--run <planRunId>` label-resolution branch
   // along with the label itself. The epilogue is keyed on the delivered id
@@ -58,16 +72,16 @@ export async function main(argv = process.argv.slice(2)) {
 
   const planRunId = `adhoc-${[...stories].sort((a, b) => a - b).join('-')}`;
 
-  const result = await runPlanRunEpilogue({
+  const result = await runPlanRunEpilogueImpl({
     planRunId,
     stories,
     provider,
     config,
     cwd,
   });
-  warnOnUnresolvedBase(result);
-  warnOnEmptyRollup(result);
-  Logger.info(JSON.stringify(result));
+  warnOnUnresolvedBase(result, logger);
+  warnOnEmptyRollup(result, logger);
+  logger.info(JSON.stringify(result));
   if (result.errors?.length) {
     process.exitCode = 1;
   }
@@ -84,15 +98,16 @@ export async function main(argv = process.argv.slice(2)) {
  * roster is still useful.
  *
  * @param {object} result - `runPlanRunEpilogue` envelope.
+ * @param {{ warn: Function }} [logger]
  * @returns {void}
  */
-function warnOnUnresolvedBase(result) {
+function warnOnUnresolvedBase(result, logger = Logger) {
   const roster = (result?.results ?? []).find(
     (r) => r?.kind === 'audit-roster',
   );
   const base = roster?.baseResolution;
   if (base?.resolved !== false) return;
-  Logger.warn(
+  logger.warn(
     `⚠️  Combined landed diff unavailable — the pre-run base sha could not be ` +
       `resolved against \`${base.baseRef}\`: ${base.reason}\n` +
       `    changedFiles is null (NOT an empty set). Determine the run diff by ` +
@@ -117,14 +132,15 @@ function warnOnUnresolvedBase(result) {
  * rather than asserting either reading.
  *
  * @param {object} result - `runPlanRunEpilogue` envelope.
+ * @param {{ warn: Function }} [logger]
  * @returns {void}
  */
-function warnOnEmptyRollup(result) {
+function warnOnEmptyRollup(result, logger = Logger) {
   const rollup = (result?.results ?? []).find(
     (r) => r?.kind === 'follow-up-rollup',
   );
   if (!rollup?.emptyRollupSuspect) return;
-  Logger.warn(
+  logger.warn(
     `⚠️  0 friction signals across ${rollup.storyCount} Stories — telemetry may not ` +
       `have fired.\n` +
       `    An empty roll-up is NOT evidence of a clean run: it is the same output a ` +

package/.agents/scripts/resolve-doc-tiers.js

@@ -50,24 +50,34 @@ export function parseArgv(argv = []) {
  * Top-level CLI entry. Exported so tests can drive it against a fixture root
  * with an injected sink and config.
  *
+ * The optional final `deps` parameter is the module's injectable seam
+ * (`.agents/rules/test-seams.md` rules 1-2): every entry defaults to the real
+ * implementation, so the CLI path below — and any production caller — needs no
+ * configuration change.
+ *
  * @param {{
  *   argv?: string[],
  *   config?: object,
  *   root?: string,
  *   stdout?: { write: (s: string) => void },
  * }} [opts]
+ * @param {{
+ *   resolveConfigImpl?: typeof resolveConfig,
+ *   resolveDocTiersImpl?: typeof resolveDocTiers,
+ * }} [deps]
  * @returns {Promise<number>} always 0
  */
-export async function runCli({
-  argv = process.argv.slice(2),
-  config,
-  root,
-  stdout = process.stdout,
-} = {}) {
+export async function runCli(
+  { argv = process.argv.slice(2), config, root, stdout = process.stdout } = {},
+  {
+    resolveConfigImpl = resolveConfig,
+    resolveDocTiersImpl = resolveDocTiers,
+  } = {},
+) {
   const { rootPath } = parseArgv(argv);
-  const resolvedConfig = config ?? resolveConfig();
+  const resolvedConfig = config ?? resolveConfigImpl();
   const resolvedRoot = root ?? rootPath ?? PROJECT_ROOT;
-  const result = resolveDocTiers(resolvedConfig, { root: resolvedRoot });
+  const result = resolveDocTiersImpl(resolvedConfig, { root: resolvedRoot });
   stdout.write(`${JSON.stringify(result, null, 2)}\n`);
   return 0;
 }

package/.agents/scripts/single-story-close.js

@@ -90,6 +90,10 @@ import { runAsCli } from './lib/cli-utils.js';
 import { formatCliError } from './lib/error-redactor.js';
 import { Logger } from './lib/Logger.js';
 import { emitTerminalFriction } from './lib/observability/runtime-friction.js';
+import {
+  failedTerminalFor,
+  gatesForFailedPhase,
+} from './lib/orchestration/single-story-close/failed-terminal.js';
 import { enableAutoMergeWith } from './lib/orchestration/single-story-close/phases/auto-merge.js';
 import {
   buildSyncFailureCommentBody,
@@ -102,10 +106,8 @@ import {
 } from './lib/orchestration/single-story-close/phases/code-review.js';
 import { ensurePullRequestWith } from './lib/orchestration/single-story-close/phases/pull-request.js';
 import {
-  buildTerminalEnvelope,
   emitTerminalEnvelope,
   exitCodeForTerminal,
-  NEXT_COMMANDS,
 } from './lib/orchestration/story-deliver-terminal.js';
 
 // Story #2990 moved the `gh`-spawn boundary into the `lib/gh-exec.js`
@@ -118,9 +120,13 @@ export const enableAutoMerge = enableAutoMergeWith;
 
 // Re-export pure helpers verbatim — they don't touch `execFileSync`
 // or any URL-mocked module, so the phase exports work unmodified.
+// `gatesForFailedPhase` now lives beside the envelope it feeds
+// (`single-story-close/failed-terminal.js`); it is re-exported here so the
+// CLI's public surface is unchanged by that move.
 export {
   buildStoryReviewCrossRefBody,
   buildSyncFailureCommentBody,
+  gatesForFailedPhase,
   handleSyncFailure,
   parsePrNumber,
   runStoryScopeReview,
@@ -134,95 +140,6 @@ export async function runSingleStoryClose(opts) {
   return mod.runSingleStoryClose(opts);
 }
 
-/**
- * The close pipeline's phase order, as `setPhase` walks it. Only used to
- * decide whether a gate had already run when a later phase died.
- */
-const PHASE_ORDER = Object.freeze([
-  'init',
-  'wrong-tree-guard',
-  'close-validation',
-  'base-sync',
-  'push',
-  'pull-request',
-  'code-review',
-  'auto-merge',
-  'confirm-merge',
-  'post-land',
-  'done',
-]);
-
-/** Each reported gate and the pipeline phase that decides it. */
-const GATE_PHASES = Object.freeze([
-  ['validation', 'close-validation'],
-  ['baseSync', 'base-sync'],
-  ['codeReview', 'code-review'],
-]);
-
-/**
- * Report every gate's outcome for a run that died at `phase`.
- *
- * The schema's contract: "A gate the run skipped … reports `skipped` rather
- * than being omitted, so a missing gate is never mistaken for a passing one."
- * The previous shape named only the gate that died and omitted the rest
- * entirely — exactly the ambiguity the contract forbids.
- *
- * Reconstructed from the phase order, which is sound because the pipeline is
- * strictly sequential: reaching phase N means every gate before it completed.
- * A gate whose phase the run never reached is `skipped`; one the operator
- * turned off via `--skip-validation` / `--skip-sync` is `skipped` too (it did
- * not pass — it never ran).
- *
- * @param {string} phase The phase the run died in.
- * @param {{ skipValidation?: boolean, skipSync?: boolean }} args Parsed CLI args.
- * @returns {Record<string, 'passed'|'failed'|'skipped'>}
- */
-export function gatesForFailedPhase(phase, args = {}) {
-  const skipped = { validation: args.skipValidation, baseSync: args.skipSync };
-  const failedAt = PHASE_ORDER.indexOf(phase);
-  const gates = {};
-  for (const [gate, gatePhase] of GATE_PHASES) {
-    const at = PHASE_ORDER.indexOf(gatePhase);
-    if (gatePhase === phase) gates[gate] = 'failed';
-    else if (failedAt < 0 || at > failedAt) gates[gate] = 'skipped';
-    else gates[gate] = skipped[gate] ? 'skipped' : 'passed';
-  }
-  return gates;
-}
-
-/**
- * Build the `failed` terminal for a phase that crashed.
- *
- * The runner deliberately throws rather than returning a failure (a red gate
- * must not look like a return value), so without this the most common
- * non-happy ending — a failing close-validation gate — would emit **no
- * envelope at all**, exiting 1 with only a stderr line while the workflow
- * docs promise the agent a `failed` envelope naming the phase. Every close
- * invocation emits exactly one envelope; this is the path that keeps that
- * true when a phase dies.
- *
- * `err.closePhase` is tagged by the runner's phase tracker.
- *
- * @param {unknown} err
- * @returns {object|null} A validated envelope, or null when even the story id
- *   is unknown (a usage error — there is nothing to report an envelope about).
- */
-function failedTerminalFor(err) {
-  const phase = err?.closePhase ?? 'init';
-  const args = parseSprintArgs();
-  const storyId = Number(args.storyId);
-  if (!Number.isInteger(storyId) || storyId <= 0) return null;
-  return buildTerminalEnvelope({
-    storyId,
-    status: 'failed',
-    phase,
-    gates: gatesForFailedPhase(phase, args),
-    failure: { reason: String(err?.message ?? err) },
-    nextCommand: NEXT_COMMANDS.recover(storyId),
-    elapsedSeconds: 0,
-  });
-}
-
 /**
  * CLI entry — resolves the process exit code from the terminal envelope's
  * status rather than from a thrown/not-thrown distinction, so `pending`
@@ -234,7 +151,7 @@ async function main() {
     const outcome = await runSingleStoryClose();
     return exitCodeForTerminal(outcome?.terminal ?? { status: 'failed' });
   } catch (err) {
-    const terminal = failedTerminalFor(err);
+    const terminal = failedTerminalFor(err, parseSprintArgs());
     if (!terminal) throw err;
     // Mirror runAsCli's default error line (which this catch pre-empts) so the
     // human-facing failure text is unchanged, then emit the envelope.

package/.agents/scripts/single-story-init.js

@@ -777,7 +777,7 @@ export async function runSingleStoryInit({
     label: 'STORY INIT RESULT',
     result,
     scope: storyId,
-    logDir: path.join(cwd, 'temp', 'orchestration'),
+    config,
     summary: {
       storyId,
       storyBranch,

package/.agents/scripts/sync-branch-from-base.js

@@ -31,6 +31,7 @@
 import path from 'node:path';
 import { parseArgs } from 'node:util';
 import { runAsCli } from './lib/cli-utils.js';
+import { resolveConfig } from './lib/config-resolver.js';
 import { syncBranchFromBase } from './lib/git/sync-from-base.js';
 import { gitSpawn, gitSync } from './lib/git-utils.js';
 import { Logger } from './lib/Logger.js';
@@ -95,11 +96,15 @@ export async function runSyncBranchFromBase(opts = {}) {
   });
 
   // Story #4685 — full detail to a temp log; emit a single summary line.
+  // Story #4794 — resolve the config so the log honours `project.paths.tempRoot`
+  // instead of the hardcoded `<cwd>/temp` this used to join. `resolveConfig`
+  // degrades to the framework defaults when no `.agentrc.json` is present, so
+  // a zero-config invocation needs no guard here.
   emitTerseResult({
     label: 'SYNC RESULT',
     result,
     scope: branch,
-    logDir: path.join(cwd, 'temp', 'orchestration'),
+    config: resolveConfig({ cwd }),
     summary: { branch, base, synced: result.synced, kind: result.kind },
   });
 

package/.agents/scripts/update-crap-baseline.js

@@ -13,6 +13,7 @@ import {
 } from './lib/config-resolver.js';
 import { loadCoverage } from './lib/coverage-utils.js';
 import {
+  checkResolutionFloor,
   resolveEscomplexVersion,
   resolveTsTranspilerVersion,
   scanAndScore,
@@ -71,6 +72,7 @@ async function main() {
   const crap = getQuality(config).crap;
   const targetDirs = Array.isArray(crap.targetDirs) ? crap.targetDirs : [];
   const requireCoverage = crap.requireCoverage !== false;
+  const minMethodResolutionRate = crap.minMethodResolutionRate ?? 0.75;
   const coveragePath =
     args.coveragePath ?? crap.coveragePath ?? 'coverage/coverage-final.json';
   const baselinePath = args.baselinePath ?? getBaselines(config).crap.path;
@@ -117,6 +119,7 @@ async function main() {
       scannedFiles,
       skippedFilesNoCoverage,
       skippedMethodsNoCoverage,
+      resolution,
     } = await scanAndScore({
       targetDirs,
       coverage,
@@ -137,6 +140,16 @@ async function main() {
         `[CRAP] Skipped ${skippedMethodsNoCoverage} method(s) whose per-method coverage was unresolved.`,
       );
     }
+    if (resolution) {
+      Logger.info(
+        `[CRAP] Method resolution: ${resolution.resolvedMethods}/${resolution.joinableMethods} ` +
+          `(${(resolution.rate * 100).toFixed(1)}%) in files with coverage.`,
+      );
+    }
+    // Fail closed BEFORE the service persists anything — a thin baseline is
+    // never written and then apologised for.
+    const refusal = checkResolutionFloor(resolution, minMethodResolutionRate);
+    if (refusal) throw new Error(refusal);
 
     return (rows ?? []).filter(
       (r) => typeof r?.crap === 'number' && Number.isFinite(r.crap),

package/README.md

@@ -181,10 +181,14 @@ dimensions, run model, and how to benchmark a new version.
 
 ## Contributors
 
-Only `.agents/` is distributed to consumers — it ships inside the
-`mandrel` npm package and is materialized into a consumer's
-`./.agents/` directory by `mandrel sync`. Everything else in this
-repository is internal development tooling.
+The published `mandrel` package ships three directories — `.agents/`, `bin/`,
+and `lib/` (see the `files` array in [`package.json`](package.json)).
+`.agents/` is the payload `mandrel sync` materializes into a consumer's
+`./.agents/` directory; `bin/mandrel.js` and its `lib/` implementation stay
+inside `node_modules/mandrel/` and back the `npx mandrel …` CLI used
+throughout this README. Everything else in this repository — `docs/`,
+`tests/`, `.github/`, the root tooling configs — is internal development
+tooling and is not published.
 
 Common commands while developing the framework itself:
 
@@ -204,8 +208,12 @@ Deeper reference material lives in `docs/` rather than inline here:
 - [`.agents/docs/workflows.md`](.agents/docs/workflows.md) — slash-command
   index (auto-generated from the workflow set).
 - [`docs/CHANGELOG.md`](docs/CHANGELOG.md) — release history.
-- [`AGENTS.md`](AGENTS.md) — repository onboarding, the single-package release
-  topology, PAT / npm-token setup, and major-version policy. Releases are
+- [`AGENTS.md`](AGENTS.md) — the repository-level orientation pointer; it
+  links on to [`docs/onboarding.md`](docs/onboarding.md) for the layout,
+  commands, and development standards.
+- [`docs/release-operations.md`](docs/release-operations.md) — the Release
+  Checklist, the Install Matrix release gate, the single-package release
+  topology, PAT / npm-token setup, and the major-version policy. Releases are
   automated by `release-please`: land Conventional Commits on `main` and it
   opens a combined `chore: release main` PR that squash-merges itself once
   CI is green, tags `main`, and publishes `mandrel` to npm.

package/docs/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.18.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.17.0...mandrel-v2.18.0) (2026-07-26)
+
+
+### Added
+
+* **temp:** auto-purge merged Stories' spent temp artifacts behind an allowlist, keeping signals ([#4794](https://github.com/dsj1984/mandrel/issues/4794)) ([#4795](https://github.com/dsj1984/mandrel/issues/4795)) ([d69d985](https://github.com/dsj1984/mandrel/commit/d69d9858511658e0ec0336db0cf8aa65d725637b))
+
+
+### Chores
+
+* **release:** cut the 2.18.0 release missed by an unparseable squash subject ([#4796](https://github.com/dsj1984/mandrel/issues/4796)) ([8ccff57](https://github.com/dsj1984/mandrel/commit/8ccff574d44519595e04fc0f3597cb4dcd005436))
+
+## [2.17.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.16.0...mandrel-v2.17.0) (2026-07-26)
+
+
+### Added
+
+* **crap:** wire the baseline-refresh projection layer and add CRAP freshness + full-scope drift detection ([#4776](https://github.com/dsj1984/mandrel/issues/4776)) ([#4778](https://github.com/dsj1984/mandrel/issues/4778)) ([8c49a12](https://github.com/dsj1984/mandrel/commit/8c49a12be6ca5ecaca60d8f0bc868f47c9a02534))
+
+
+### Fixed
+
+* **audit-to-stories:** anchor findings to their real primary file (refs [#4781](https://github.com/dsj1984/mandrel/issues/4781)) ([#4782](https://github.com/dsj1984/mandrel/issues/4782)) ([a5794c0](https://github.com/dsj1984/mandrel/commit/a5794c02c3443c39ce116699c311b4cdd8001788))
+* **cli:** drain stdio before exit and settle the audit fan-out per dimension (refs [#4783](https://github.com/dsj1984/mandrel/issues/4783)) ([#4787](https://github.com/dsj1984/mandrel/issues/4787)) ([3422fd5](https://github.com/dsj1984/mandrel/commit/3422fd564773d0e79ac4d16af5bbc5414d06c65b))
+* **crap:** join per-method coverage in original-source coordinates — TS scoring resolves ~5% of methods ([#4775](https://github.com/dsj1984/mandrel/issues/4775)) ([#4777](https://github.com/dsj1984/mandrel/issues/4777)) ([1464c75](https://github.com/dsj1984/mandrel/commit/1464c75c061960aaa9ee1af88175d9706b044c26))
+* **deliver:** keep the terminal envelope alive after the worktree reap (refs [#4784](https://github.com/dsj1984/mandrel/issues/4784)) ([#4791](https://github.com/dsj1984/mandrel/issues/4791)) ([907b7bd](https://github.com/dsj1984/mandrel/commit/907b7bdb951a70a7155e5a9a50afdbea7a81d6a6))
+* **deps:** decouple the js-yaml override from markdownlint-cli2, close Node-engine drift, and re-enable knip dependency rules ([#4784](https://github.com/dsj1984/mandrel/issues/4784)) ([#4788](https://github.com/dsj1984/mandrel/issues/4788)) ([9ed687b](https://github.com/dsj1984/mandrel/commit/9ed687bead90d3e0edf76e7d0e700b0f51e8cb5d))
+* **docs:** re-sync the reference docs to the contracts the code actually implements ([#4785](https://github.com/dsj1984/mandrel/issues/4785)) ([#4790](https://github.com/dsj1984/mandrel/issues/4790)) ([00d9270](https://github.com/dsj1984/mandrel/commit/00d92708b3d3ac0978c073c5a31fd6a80a25767e))
+* **docs:** supersede the stale ADR chain in place and archive the retired pattern history ([#4786](https://github.com/dsj1984/mandrel/issues/4786)) ([#4789](https://github.com/dsj1984/mandrel/issues/4789)) ([5ba2e34](https://github.com/dsj1984/mandrel/commit/5ba2e3486973b87603fd3f2f23f750f18e75e240))
+* **git-cleanup:** report the refs the prune phase actually dropped (refs [#4772](https://github.com/dsj1984/mandrel/issues/4772)) ([#4773](https://github.com/dsj1984/mandrel/issues/4773)) ([16424d5](https://github.com/dsj1984/mandrel/commit/16424d53305549841b6294ceb1d7651baf1f98e7))
+
+
+### Changed
+
+* **quality:** floor CRAP on methodsAbove20 instead of a fitted max ceiling ([#4779](https://github.com/dsj1984/mandrel/issues/4779)) ([647130b](https://github.com/dsj1984/mandrel/commit/647130b313a85add64978205d4bb300e90e3c9a3)), closes [#4775](https://github.com/dsj1984/mandrel/issues/4775)
+
 ## [2.16.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.15.0...mandrel-v2.16.0) (2026-07-25)
 
 

package/lib/cli/version-helpers.js

@@ -16,6 +16,13 @@
  * 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.
  */
 
 import nodeFs from 'node:fs';

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

@@ -40,10 +40,11 @@ const TAG_LINE_RE = /^(\s*)(@\S+(?:\s+@\S+)*)\s*$/;
  * Recursively collect `.feature` file paths under `root`.
  *
  * @param {string} root
- * @param {typeof nodeFs} fsImpl
+ * @param {typeof nodeFs} [fsImpl] Filesystem seam; defaults to the real
+ *   `node:fs` per `.agents/rules/test-seams.md` rule 1.
  * @returns {string[]}
  */
-function collectFeatureFiles(root, fsImpl) {
+function collectFeatureFiles(root, fsImpl = nodeFs) {
   /** @type {string[]} */
   const found = [];
   /** @type {string[]} */
@@ -71,11 +72,13 @@ function collectFeatureFiles(root, fsImpl) {
 
 /**
  * @param {unknown} ctx
- * @param {typeof nodeFs} fsImpl
+ * @param {typeof nodeFs} [fsImpl] Filesystem seam; forwarded to
+ *   {@link collectFeatureFiles} rather than re-acquired there
+ *   (`.agents/rules/test-seams.md` rule 4).
  * @returns {string[]} Absolute paths of every `.feature` file under the
  *   canonical feature roots that exist in the consumer tree.
  */
-function resolveFeatureFiles(ctx, fsImpl) {
+function resolveFeatureFiles(ctx, fsImpl = nodeFs) {
   const projectRoot = ctx?.projectRoot ?? process.cwd();
   return CANONICAL_FEATURE_ROOTS.flatMap((root) =>
     collectFeatureFiles(path.join(projectRoot, root), fsImpl),
@@ -119,10 +122,12 @@ export const retireEpicAcTags = {
     '(their reconciler consumer was deleted in the v2 Epic removal)',
   /**
    * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
+   * @param {typeof nodeFs} [fsImpl] Optional final filesystem seam; defaults
+   *   to `ctx.fs` when the migration runner threads one, else the real
+   *   `node:fs` (`.agents/rules/test-seams.md` rule 1).
    * @returns {boolean}
    */
-  detect(ctx) {
-    const fsImpl = ctx?.fs ?? nodeFs;
+  detect(ctx, fsImpl = ctx?.fs ?? nodeFs) {
     return resolveFeatureFiles(ctx, fsImpl).some((file) => {
       try {
         return EPIC_AC_TAG_RE.test(fsImpl.readFileSync(file, 'utf8'));
@@ -133,10 +138,12 @@ export const retireEpicAcTags = {
   },
   /**
    * @param {{ projectRoot?: string, fs?: typeof nodeFs }} [ctx]
+   * @param {typeof nodeFs} [fsImpl] Optional final filesystem seam; defaults
+   *   to `ctx.fs` when the migration runner threads one, else the real
+   *   `node:fs` (`.agents/rules/test-seams.md` rule 1).
    * @returns {void}
    */
-  apply(ctx) {
-    const fsImpl = ctx?.fs ?? nodeFs;
+  apply(ctx, fsImpl = ctx?.fs ?? nodeFs) {
     for (const file of resolveFeatureFiles(ctx, fsImpl)) {
       /** @type {string} */
       let content;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.16.0",
+  "version": "2.18.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",
@@ -110,6 +110,10 @@
       "optional": true
     }
   },
+  "//": {
+    "overrides.js-yaml": "COUPLED to devDependencies.markdownlint-cli2 — do not bump either alone, and do NOT drop this override. It is load-bearing: markdownlint-cli2 0.22.x pulls js-yaml 4.1.1, which carries GHSA-52cp-r559-cp3m (high) and GHSA-h67p-54hq-rp68 (moderate); removing the override was measured to reintroduce both (1 high + 1 moderate), while with it in place `npm audit` is clean. An npm override also wins over a transitive package's own pin, so this tree-wide ^4.2.0 is imposed on every js-yaml consumer regardless of what they declare — and markdownlint-cli2 0.23.x declares an exact js-yaml 5.2.1. A dry-run bump confirmed the trap: markdownlint-cli2 0.23.1 resolves against js-yaml 4.3.0, two majors off what it declares, silently. The only safe move is to raise this override and bump markdownlint-cli2 in ONE reviewed commit (first confirming cosmiconfig, under @commitlint/cli, tolerates the same major). renovate.json excludes markdownlint-cli2 from devDependency auto-merge so that pair cannot drift apart unattended.",
+    "dependencies.js-yaml": "States the SAME range as overrides.js-yaml above. The two are deliberate duplicates — npm has no way to reference the direct range from the overrides block — so they MUST move in lockstep; changing one without the other silently splits the direct and transitive resolutions."
+  },
   "overrides": {
     "js-yaml": "^4.2.0",
     "markdown-it": "^14.2.0"