mandrel 2.15.0 → 2.17.0

package/.agents/scripts/lib/close-validation/projections/advisories.js

@@ -0,0 +1,184 @@
+// .agents/scripts/lib/close-validation/projections/advisories.js
+/**
+ * advisories.js — the projection layer's single call site (Story #4776).
+ *
+ * `projections/maintainability.js` shipped fully written, fully unit-tested
+ * and imported by nothing: the v2 Epic-tier collapse removed its caller and
+ * left the module behind. The practical consequence was that the advisory
+ * telling an operator to run `npm run maintainability:update` and commit a
+ * `baseline-refresh:` subject had never fired in v2 — consumers refreshed
+ * their baselines by hand or not at all.
+ *
+ * This module is that caller, for both projections. It is deliberately the
+ * only door: `close-validation/runner.js` invokes `runProjectionAdvisories`
+ * once, after the gate chain has passed, and every per-kind concern (gate
+ * enablement, baseline path resolution, scorer construction, formatting)
+ * lives here rather than being re-derived at the runner boundary.
+ *
+ * **Advisory, always.** Nothing in here can fail a close. `check-baselines`
+ * already fails closed on a real regression; the projections add the refresh
+ * half of the loop, not a second gate. Every projection is wrapped so a
+ * throw becomes a logged skip.
+ */
+
+import path from 'node:path';
+import { getQuality } from '../../config/quality.js';
+import {
+  createCrapScorer,
+  formatCrapProjection,
+  projectCrapBreaches,
+} from './crap.js';
+import {
+  formatMaintainabilityProjection,
+  projectMaintainabilityRegressions,
+} from './maintainability.js';
+
+/** Default on-disk baseline locations, mirroring the per-gate defaults. */
+const DEFAULT_BASELINE_PATHS = Object.freeze({
+  maintainability: 'baselines/maintainability.json',
+  crap: 'baselines/crap.json',
+});
+
+/**
+ * Resolve a gate's baseline file to an absolute path.
+ *
+ * @param {string} kind
+ * @param {object} gate resolved `delivery.quality.gates.<kind>` block
+ * @param {string} cwd
+ * @returns {string}
+ */
+function resolveBaselinePath(kind, gate, cwd) {
+  const rel =
+    typeof gate?.baselinePath === 'string' && gate.baselinePath.length > 0
+      ? gate.baselinePath
+      : DEFAULT_BASELINE_PATHS[kind];
+  return path.isAbsolute(rel) ? rel : path.resolve(cwd, rel);
+}
+
+/**
+ * A gate is projected unless it is explicitly disabled. An absent gate
+ * block means "framework defaults", which enable it — the same reading
+ * `buildDefaultGates` applies.
+ *
+ * @param {object|undefined} gate
+ * @returns {boolean}
+ */
+function isEnabled(gate) {
+  return gate?.enabled !== false;
+}
+
+/**
+ * Run one projection with its formatter, swallowing every failure into a
+ * logged skip. Returns the projection result (or `null` when it threw) so
+ * callers and tests can inspect what happened without parsing log lines.
+ *
+ * @param {{ kind: string, log: (m: string) => void, run: () => Promise<object>|object, format: (r: object) => string|null }} opts
+ * @returns {Promise<object|null>}
+ */
+async function runOne({ kind, log, run, format }) {
+  let result;
+  try {
+    result = await run();
+  } catch (err) {
+    log(
+      `[close-validation]   ⚠ ${kind} projection skipped (errored): ${err?.message ?? err}`,
+    );
+    return null;
+  }
+  if (result?.skipped) {
+    log(
+      `[close-validation] ⏭ ${kind} projection skipped (${result.skipped}${
+        result.detail ? `: ${result.detail}` : ''
+      })`,
+    );
+    return result;
+  }
+  const advisory = format(result);
+  if (advisory) log(advisory);
+  return result;
+}
+
+/**
+ * Run the maintainability and CRAP pre-merge projections and log their
+ * advisories. Never throws; never affects the close verdict.
+ *
+ * @param {{
+ *   cwd: string,
+ *   baseBranch: string,
+ *   storyBranch: string,
+ *   config?: object,
+ *   quality?: object,
+ *   log?: (m: string) => void,
+ *   projectMaintainability?: typeof projectMaintainabilityRegressions,
+ *   formatMaintainability?: typeof formatMaintainabilityProjection,
+ *   projectCrap?: typeof projectCrapBreaches,
+ *   formatCrap?: typeof formatCrapProjection,
+ * }} opts
+ * @returns {Promise<{ maintainability: object|null, crap: object|null }>}
+ */
+export async function runProjectionAdvisories({
+  cwd,
+  baseBranch,
+  storyBranch,
+  config,
+  quality,
+  log = () => {},
+  projectMaintainability = projectMaintainabilityRegressions,
+  formatMaintainability = formatMaintainabilityProjection,
+  projectCrap = projectCrapBreaches,
+  formatCrap = formatCrapProjection,
+} = {}) {
+  const out = { maintainability: null, crap: null };
+  let gates;
+  try {
+    gates = quality ?? getQuality(config) ?? {};
+  } catch {
+    gates = {};
+  }
+
+  const miGate = gates.maintainability;
+  if (isEnabled(miGate)) {
+    out.maintainability = await runOne({
+      kind: 'maintainability',
+      log,
+      format: formatMaintainability,
+      run: () =>
+        projectMaintainability({
+          cwd,
+          baseBranch,
+          storyBranch,
+          baselinePath: resolveBaselinePath('maintainability', miGate, cwd),
+        }),
+    });
+  } else {
+    log('[close-validation] ⏭ maintainability projection skipped (disabled)');
+  }
+
+  const crapGate = gates.crap;
+  if (isEnabled(crapGate)) {
+    out.crap = await runOne({
+      kind: 'crap',
+      log,
+      format: formatCrap,
+      run: () =>
+        projectCrap({
+          cwd,
+          baseBranch,
+          storyBranch,
+          baselinePath: resolveBaselinePath('crap', crapGate, cwd),
+          newMethodCeiling: crapGate?.newMethodCeiling,
+          scoreFiles: createCrapScorer({
+            cwd,
+            targetDirs: crapGate?.targetDirs,
+            ignoreGlobs: crapGate?.ignoreGlobs,
+            requireCoverage: crapGate?.requireCoverage,
+            coveragePath: crapGate?.coveragePath,
+          }),
+        }),
+    });
+  } else {
+    log('[close-validation] ⏭ crap projection skipped (disabled)');
+  }
+
+  return out;
+}

package/.agents/scripts/lib/close-validation/projections/crap.js

@@ -0,0 +1,303 @@
+// .agents/scripts/lib/close-validation/projections/crap.js
+/**
+ * crap.js — pre-merge CRAP ceiling projection helper (Story #4776).
+ *
+ * The CRAP analogue of `projections/maintainability.js`. Both answer the
+ * same operator question before the merge runs: *given what this branch
+ * changed, which committed baseline rows would the post-merge tree breach,
+ * and what is the exact remedy?*
+ *
+ * Advisory only. `check-baselines` already fails close-validation closed on
+ * a real regression; duplicating that here would double-gate the same
+ * defect. What this projection adds is the **refresh** half of the loop —
+ * naming the breaching methods and the `npm run crap:update` +
+ * `baseline-refresh:` remedy while the operator still has the branch in
+ * hand, so a corrected baseline does not rot back into staleness.
+ *
+ * The helper never throws and never mutates anything. Every failure path
+ * resolves to `{ ok: true, breaches: [], skipped: '<reason>' }` so the
+ * caller can treat the advisory as best-effort.
+ *
+ * Post-merge approximation: CRAP needs a coverage join, so — unlike the MI
+ * projection, which scores a `git show` blob — the scorer reads the working
+ * tree. Close-validation runs inside the Story worktree at the branch tip,
+ * which is exactly the content a squash-merge lands, so the approximation is
+ * exact whenever the merge applies cleanly.
+ */
+
+import path from 'node:path';
+import {
+  compareCrap,
+  filterRowsByFileScope,
+} from '../../baselines/kinds/crap.js';
+import { loadFile as loadBaselineFile } from '../../baselines/reader.js';
+import { diffNameOnly } from '../../changed-files.js';
+import { loadCoverage } from '../../coverage-utils.js';
+import { scanAndScore } from '../../crap-utils.js';
+import { cachedGitFetchSync } from '../../git/cached-fetch.js';
+import { gitSpawn as defaultGitSpawn } from '../../git-utils.js';
+import { MISSING_ARG_REASONS, validateProjectionInputs } from './inputs.js';
+
+/**
+ * Default absolute tolerance on a projected CRAP score, shared with
+ * `check-crap`'s regression arm: floating-point noise must not register as
+ * a breach.
+ */
+export const DEFAULT_CRAP_TOLERANCE = 0.001;
+
+/** Framework default for the new-method ceiling (`gates.crap.newMethodCeiling`). */
+export const DEFAULT_NEW_METHOD_CEILING = 30;
+
+/** Extensions the CRAP scanner can score. */
+const SCORABLE = /\.(?:js|mjs|cjs|ts|tsx)$/;
+
+/**
+ * Map the shared predicate's fine-grained `missing-*` reason onto the
+ * `missing-args` skipped-reason the sibling MI projection reports, so both
+ * projections speak one vocabulary at the advisory boundary.
+ *
+ * @param {string} reason
+ * @returns {string}
+ */
+function normaliseSkipReason(reason) {
+  return MISSING_ARG_REASONS.has(reason) ? 'missing-args' : reason;
+}
+
+/**
+ * Read the committed CRAP baseline and re-key its rows onto the `file`
+ * field `compareCrap` matches on (the on-disk v2 envelope keys on `path`).
+ * Returns `[]` when the baseline is absent or unreadable — the caller maps
+ * that to the `no-baseline` skip.
+ *
+ * Deliberately module-local: `projectCrapBreaches`'s `loadBaseline` default
+ * is the single production door to it, and tests inject their own loader.
+ * Exporting it would add a second entry point nothing in production reaches
+ * — which is precisely the orphaning this Story exists to stop.
+ *
+ * @param {string} baselinePath absolute path to `baselines/crap.json`
+ * @returns {Array<{file: string, method: string, startLine: number, crap: number}>}
+ */
+function loadCrapBaselineRows(baselinePath) {
+  let envelope;
+  try {
+    envelope = loadBaselineFile(baselinePath, { kind: 'crap' });
+  } catch {
+    return [];
+  }
+  const rows = Array.isArray(envelope?.rows) ? envelope.rows : [];
+  return rows.map((row) => ({
+    file: row.path,
+    method: row.method,
+    startLine: row.startLine,
+    crap: row.crap,
+  }));
+}
+
+/**
+ * Build the default working-tree CRAP scorer. Returns an async callable
+ * `(files) => rows | null`; `null` signals "coverage artifact missing under
+ * `requireCoverage`", which the projection reports as the `no-coverage`
+ * skip rather than as a clean run.
+ *
+ * @param {{
+ *   cwd: string,
+ *   targetDirs?: string[],
+ *   ignoreGlobs?: string[],
+ *   requireCoverage?: boolean,
+ *   coveragePath?: string,
+ * }} opts
+ * @returns {(files: string[]) => Promise<Array<object>|null>}
+ */
+export function createCrapScorer({
+  cwd,
+  targetDirs = [],
+  ignoreGlobs = [],
+  requireCoverage = true,
+  coveragePath = 'coverage/coverage-final.json',
+} = {}) {
+  return async (files) => {
+    const abs = path.isAbsolute(coveragePath)
+      ? coveragePath
+      : path.resolve(cwd, coveragePath);
+    const coverage = loadCoverage(abs);
+    if (!coverage && requireCoverage) return null;
+    const { rows } = await scanAndScore({
+      targetDirs,
+      coverage,
+      requireCoverage,
+      cwd,
+      ignoreGlobs,
+      scopeFiles: files,
+    });
+    return rows ?? [];
+  };
+}
+
+/**
+ * Refresh `origin/<baseBranch>` so the diff range resolves even when close
+ * has not reached its own base-sync step. Routed through the shared fetch
+ * cache so a story-init fetch in the same run satisfies it for free.
+ *
+ * @param {string} cwd
+ * @param {string} baseBranch
+ * @param {{ gitSpawn: typeof defaultGitSpawn }} git
+ * @returns {{ ok: true } | { ok: false, detail: string }}
+ */
+function refreshBaseRef(cwd, baseBranch, git) {
+  const res = cachedGitFetchSync(cwd, baseBranch, { gitSpawn: git.gitSpawn });
+  if (res.status !== 0) {
+    return {
+      ok: false,
+      detail: res.stderr || res.stdout || `exit ${res.status}`,
+    };
+  }
+  return { ok: true };
+}
+
+/**
+ * Enumerate the Story branch's changed files, narrowed to the extensions
+ * the CRAP scanner can score.
+ *
+ * @param {{ cwd: string, baseBranch: string, storyBranch: string, git: { gitSpawn: typeof defaultGitSpawn } }} opts
+ * @returns {{ ok: true, files: string[] } | { ok: false, detail: string }}
+ */
+function diffScorableFiles({ cwd, baseBranch, storyBranch, git }) {
+  try {
+    const files = diffNameOnly({
+      range: `origin/${baseBranch}...${storyBranch}`,
+      cwd,
+      gitSpawn: git.gitSpawn,
+    });
+    return { ok: true, files: files.filter((f) => SCORABLE.test(f)) };
+  } catch (err) {
+    return { ok: false, detail: err.message };
+  }
+}
+
+/**
+ * Project the post-merge CRAP scores for every file changed on the Story
+ * branch and return the subset of methods that would breach either their
+ * committed baseline row or, for methods with no baseline row, the
+ * configured `newMethodCeiling`.
+ *
+ * Baseline rows are narrowed to the changed-file set before the compare so
+ * every untouched file's rows are not spuriously reported as removed.
+ *
+ * @param {{
+ *   cwd: string,
+ *   baseBranch: string,
+ *   storyBranch: string,
+ *   baselinePath: string,
+ *   newMethodCeiling?: number,
+ *   tolerance?: number,
+ *   git?: { gitSpawn: typeof defaultGitSpawn },
+ *   loadBaseline?: (path: string) => Array<object>,
+ *   scoreFiles?: (files: string[]) => Promise<Array<object>|null>|Array<object>|null,
+ * }} opts
+ * @returns {Promise<{
+ *   ok: boolean,
+ *   breaches: Array<object>,
+ *   skipped?: string,
+ *   detail?: string,
+ * }>}
+ */
+export async function projectCrapBreaches({
+  cwd,
+  baseBranch,
+  storyBranch,
+  baselinePath,
+  newMethodCeiling = DEFAULT_NEW_METHOD_CEILING,
+  tolerance = DEFAULT_CRAP_TOLERANCE,
+  git = { gitSpawn: defaultGitSpawn },
+  loadBaseline = loadCrapBaselineRows,
+  scoreFiles,
+} = {}) {
+  const skip = (reason, detail) => ({
+    ok: true,
+    breaches: [],
+    skipped: reason,
+    ...(detail === undefined ? {} : { detail }),
+  });
+
+  const validation = validateProjectionInputs({
+    cwd,
+    baseBranch,
+    storyBranch,
+    baselinePath,
+  });
+  if (!validation.ok) return skip(normaliseSkipReason(validation.reason));
+
+  const baselineRows = loadBaseline(baselinePath);
+  if (!Array.isArray(baselineRows) || baselineRows.length === 0) {
+    return skip('no-baseline');
+  }
+
+  const fetched = refreshBaseRef(cwd, baseBranch, git);
+  if (!fetched.ok) return skip('fetch-failed', fetched.detail);
+
+  const diffed = diffScorableFiles({ cwd, baseBranch, storyBranch, git });
+  if (!diffed.ok) return skip('diff-failed', diffed.detail);
+  if (diffed.files.length === 0) return skip('no-scorable-files');
+
+  const scorer =
+    typeof scoreFiles === 'function' ? scoreFiles : createCrapScorer({ cwd });
+  let currentRows;
+  try {
+    currentRows = await scorer(diffed.files);
+  } catch (err) {
+    return skip('score-failed', err?.message ?? String(err));
+  }
+  if (currentRows === null || currentRows === undefined) {
+    return skip('no-coverage');
+  }
+  if (currentRows.length === 0) return skip('no-scored-methods');
+
+  const scopeSet = new Set(diffed.files);
+  const result = compareCrap({
+    currentRows,
+    baselineRows: filterRowsByFileScope(baselineRows, scopeSet),
+    newMethodCeiling,
+    tolerance,
+  });
+  const breaches = result.violations ?? [];
+  return { ok: breaches.length === 0, breaches };
+}
+
+/**
+ * Render one breach as an advisory bullet. New-method breaches name the
+ * ceiling they cleared; regressions name the baseline row they exceeded.
+ *
+ * @param {object} b
+ * @returns {string}
+ */
+function formatBreach(b) {
+  const where = `${b.file}::${b.method} (line ${b.startLine})`;
+  const projected = Number(b.crap ?? 0).toFixed(2);
+  if (b.kind === 'new') {
+    return `  • ${where}  projected=${projected}  ceiling=${b.ceiling}  [new method]`;
+  }
+  const baseline = Number(b.baseline ?? 0).toFixed(2);
+  return `  • ${where}  projected=${projected}  baseline=${baseline}  [${b.kind}]`;
+}
+
+/**
+ * Render the pre-merge CRAP advisory as a human-readable multi-line log
+ * block, naming every breaching method and the exact refresh remedy.
+ * Returns `null` when there is nothing to surface so callers can `if` past
+ * the log call without a string-empty check.
+ *
+ * @param {Awaited<ReturnType<typeof projectCrapBreaches>>} result
+ * @returns {string | null}
+ */
+export function formatCrapProjection(result) {
+  if (!result || !Array.isArray(result.breaches)) return null;
+  if (result.breaches.length === 0) return null;
+  const lines = [
+    `[close-validation] ⚠ Pre-merge CRAP projection: ${result.breaches.length} method(s) would breach post-merge:`,
+  ];
+  for (const b of result.breaches) lines.push(formatBreach(b));
+  lines.push(
+    '[close-validation]   To land cleanly, run `npm run crap:update` and commit the refreshed baseline with a `baseline-refresh:` tagged subject (non-empty body) on the story branch before re-running close.',
+  );
+  return lines.join('\n');
+}

package/.agents/scripts/lib/close-validation/runner.js

@@ -19,6 +19,7 @@ import {
 } from './commands.js';
 import { DEFAULT_GATES, partitionGates } from './gates.js';
 import { defaultGateRunner } from './process.js';
+import { runProjectionAdvisories as defaultRunProjections } from './projections/advisories.js';
 import { defaultGetHeadSha } from './projections/head-sha.js';
 
 /** @typedef {import('./gates.js').Gate} Gate */
@@ -90,10 +91,23 @@ function applyChangedFileScope({ gate, spawnCwd, log }) {
  * story-close uses it to drive `phaseTimer.mark(...)` for per-gate
  * wall-clock telemetry. Errors thrown from the hook propagate.
  *
+ * Projection advisories (Story #4776): when `baseBranch` and `storyBranch`
+ * are both supplied and every gate passed, the maintainability and CRAP
+ * pre-merge projections run through `projections/advisories.js` and log
+ * their advisories to the same `log` sink the gates use. They are advisory
+ * by construction — the returned `ok` is decided entirely by the gates, so
+ * a projected breach never fails a close. They are skipped after a gate
+ * failure, where the operator needs the failing gate's evidence, not a
+ * baseline-refresh nudge.
+ *
  * @param {{
  *   cwd: string,
  *   worktreePath?: string,
  *   gates?: Gate[],
+ *   baseBranch?: string|null,
+ *   storyBranch?: string|null,
+ *   config?: object|null,
+ *   runProjections?: typeof defaultRunProjections,
  *   runner?: (cmd: string, args: string[], opts: { cwd: string, signal?: AbortSignal, gateName?: string, log?: (m: string) => void }) => Promise<{ status: number }> | { status: number },
  *   log?: (m: string) => void,
  *   onGateStart?: (gate: Gate) => void,
@@ -114,6 +128,10 @@ export async function runCloseValidation({
   runner = defaultGateRunner,
   log = () => {},
   onGateStart,
+  baseBranch = null,
+  storyBranch = null,
+  config = null,
+  runProjections = defaultRunProjections,
   storyId = null,
   standalone = false,
   useEvidence = true,
@@ -346,5 +364,55 @@ export async function runCloseValidation({
     );
   }
 
+  // ── Phase 3: advisory projections ───────────────────────────────────
+  // Story #4776 — the projection layer's live call site. Deliberately
+  // outside the `ok` computation: a projected breach informs, it never
+  // fails a close.
+  if (failed.length === 0) {
+    await runAdvisoryProjections({
+      runProjections,
+      cwd: spawnCwd,
+      baseBranch,
+      storyBranch,
+      config,
+      log,
+    });
+  }
+
   return { ok: failed.length === 0, failed, skipped };
 }
+
+/**
+ * Phase 3 helper — run the advisory projections, absorbing every failure.
+ *
+ * No-ops without a branch pair to diff (resume / legacy callers), and can
+ * never influence the close verdict: the caller has already decided `ok`
+ * before this runs, and a throw here is logged, not propagated.
+ *
+ * @param {{
+ *   runProjections: typeof defaultRunProjections,
+ *   cwd: string,
+ *   baseBranch: string|null,
+ *   storyBranch: string|null,
+ *   config: object|null,
+ *   log: (m: string) => void,
+ * }} opts
+ * @returns {Promise<void>}
+ */
+async function runAdvisoryProjections({
+  runProjections,
+  cwd,
+  baseBranch,
+  storyBranch,
+  config,
+  log,
+}) {
+  if (!(baseBranch && storyBranch)) return;
+  try {
+    await runProjections({ cwd, baseBranch, storyBranch, config, log });
+  } catch (err) {
+    log(
+      `[close-validation]   ⚠ projection advisories skipped: ${err?.message ?? err}`,
+    );
+  }
+}

package/.agents/scripts/lib/config/gates/crap.schema.js

@@ -13,6 +13,13 @@ export const CRAP_GATE = {
     targetDirs: LIST_OR_EXTENDER_OF_STRINGS,
     newMethodCeiling: { type: 'integer', minimum: 1 },
     requireCoverage: { type: 'boolean' },
+    // Story #4775 — fail-closed floor on the per-method coverage JOIN: the
+    // fraction of methods that must resolve a coverage entry, counted only
+    // over files that HAVE one, before `update-crap-baseline.js` will
+    // persist. A broken join is silent by construction (unresolved methods
+    // are simply absent), so the updater refuses rather than writing a thin
+    // baseline and logging it as success. Default 0.75.
+    minMethodResolutionRate: { type: 'number', minimum: 0, maximum: 1 },
     friction: {
       type: 'object',
       properties: { markerKey: { type: 'string', minLength: 1 } },

package/.agents/scripts/lib/config/quality.js

@@ -88,6 +88,15 @@ export const CRAP_GATE_DEFAULTS = Object.freeze({
   // semantics.
   refreshTimeoutMs: 60_000,
   ignoreGlobs: Object.freeze([]),
+  // Story #4775 — fail-closed floor on the per-method coverage JOIN. The
+  // fraction of methods that must resolve a coverage entry, counted only over
+  // files that HAVE one, before `update-crap-baseline.js` will persist. A
+  // broken join is silent by construction (unresolved methods are simply
+  // absent from the baseline), so the updater refuses rather than writing a
+  // thin baseline and logging it as success. 0.75 sits far above a healthy
+  // run (a repo with fresh coverage resolves ~98%) and far below the 4–6%
+  // signature of a coordinate-system mismatch.
+  minMethodResolutionRate: 0.75,
 });
 
 /** Framework defaults for the coverage gate. */
@@ -121,6 +130,15 @@ export const MAINTAINABILITY_GATE_DEFAULTS = Object.freeze({
   // spawned by the baseline-attribution refresh path. Defaults to 60 s.
   refreshTimeoutMs: 60_000,
   ignoreGlobs: Object.freeze([]),
+  // Story #4775 — fail-closed floor on the per-method coverage JOIN. The
+  // fraction of methods that must resolve a coverage entry, counted only over
+  // files that HAVE one, before `update-crap-baseline.js` will persist. A
+  // broken join is silent by construction (unresolved methods are simply
+  // absent from the baseline), so the updater refuses rather than writing a
+  // thin baseline and logging it as success. 0.75 sits far above a healthy
+  // run (a repo with fresh coverage resolves ~98%) and far below the 4–6%
+  // signature of a coordinate-system mismatch.
+  minMethodResolutionRate: 0.75,
 });
 
 /**
@@ -144,6 +162,7 @@ const CRAP_GATE_KEYS = new Set([
   'refreshTag',
   'refreshTimeoutMs',
   'ignoreGlobs',
+  'minMethodResolutionRate',
 ]);
 
 const COVERAGE_GATE_KEYS = new Set([
@@ -205,6 +224,22 @@ function warnUnknownKeys(userBlock, knownKeys, blockLabel) {
  * @param {{ coveragePath: string }} coverageGate resolved coverage gate
  * @returns {object} flattened legacy-bag view that existing callers read
  */
+/**
+ * Clamp a user-supplied method-resolution floor into `[0, 1]`. A
+ * non-numeric, non-finite, or out-of-range value falls back to the framework
+ * default rather than silently disabling the guard (a floor of `NaN` would
+ * compare false against every rate and never fire).
+ *
+ * @param {unknown} value
+ * @param {number} fallback
+ * @returns {number}
+ */
+function resolveResolutionRate(value, fallback) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback;
+  if (value < 0 || value > 1) return fallback;
+  return value;
+}
+
 export function resolveMaintainabilityCrap(
   userCrap,
   gateScoping,
@@ -227,6 +262,7 @@ export function resolveMaintainabilityCrap(
         DEFAULT_CRAP_TOLERANCE.value,
       ),
       requireCoverage: defaults.requireCoverage,
+      minMethodResolutionRate: defaults.minMethodResolutionRate,
       friction: { ...defaults.friction },
       refreshTag: defaults.refreshTag,
       refreshTimeoutMs: defaults.refreshTimeoutMs,
@@ -248,6 +284,10 @@ export function resolveMaintainabilityCrap(
       toleranceScalar(defaults.tolerance, DEFAULT_CRAP_TOLERANCE.value),
     ),
     requireCoverage: userCrap.requireCoverage ?? defaults.requireCoverage,
+    minMethodResolutionRate: resolveResolutionRate(
+      userCrap.minMethodResolutionRate,
+      defaults.minMethodResolutionRate,
+    ),
     friction: { ...defaults.friction, ...(userCrap.friction ?? {}) },
     refreshTag: userCrap.refreshTag ?? defaults.refreshTag,
     refreshTimeoutMs: resolvePositiveIntegerMs(