mandrel 2.31.0 → 2.33.0

package/.agents/scripts/lib/baselines/envelope.js

@@ -40,46 +40,26 @@
  * @module lib/baselines/envelope
  */
 
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import Ajv from 'ajv';
-import addFormats from 'ajv-formats';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
+import {
+  BASELINE_KIND_SCHEMA_FILES,
+  buildBaselineSchemaAjv,
+} from '../baseline-schema-registry.js';
 
 /**
- * Repo-relative `.agents/schemas/baselines/` directory. Resolved off the
- * module URL so the envelope works the same in the main checkout, in a
- * worktree, and inside CI's bare clone — none of those have a stable
- * `process.cwd()` relative to the schemas.
+ * Canonical list of kinds the shared envelope supports, **derived** from the
+ * schema registry rather than restated (Story #5002).
+ *
+ * It used to be a hand-kept literal that happened to mirror
+ * `BASELINE_KIND_SCHEMA_FILES` name for name. Deriving it makes
+ * "`kind` is known" and "`kind`'s schema is registered" the same fact, so
+ * `getValidator` below cannot be handed a kind the AJV instance never
+ * compiled — the not-registered branch is gone because the state is
+ * unreachable, not because it was hidden.
  */
-const SCHEMAS_DIR = path.resolve(
-  __dirname,
-  '..',
-  '..',
-  '..',
-  'schemas',
-  'baselines',
+export const KNOWN_KINDS = Object.freeze(
+  BASELINE_KIND_SCHEMA_FILES.map((file) => file.replace(/\.schema\.json$/, '')),
 );
 
-/**
- * Canonical list of kinds the shared envelope supports. The writer's
- * per-kind module list lives in `kinds/index.js`; this constant is the
- * envelope's view of the same set, kept here to break the import cycle
- * (`kinds/<kind>` imports envelope; envelope only needs the names).
- */
-export const KNOWN_KINDS = Object.freeze([
-  'lint',
-  'coverage',
-  'crap',
-  'maintainability',
-  'mutation',
-  'lighthouse',
-  'bundle-size',
-  'duplication',
-]);
-
 function schemaRefFor(kind) {
   return `.agents/schemas/baselines/${kind}.schema.json`;
 }
@@ -193,36 +173,37 @@ export function buildEnvelope({
 }
 
 /**
- * Lazy AJV instance — compiled schemas are memoised so successive writes
- * during a single Node process don't re-compile the seven schemas.
+ * Lazy AJV instance, built by the canonical
+ * [`baseline-schema-registry`](../baseline-schema-registry.js) — the ONE
+ * place a baselines-directory schema is read off disk and compiled
+ * (Story #5002). This module used to keep its own `SCHEMAS_DIR` + AJV +
+ * per-kind compile cache alongside the registry's, so the writer and
+ * `baselines/reader.js` validated the same envelope through two independently
+ * configured instances; a registration added to one was invisible to the
+ * other. One builder means the writer and the reader cannot disagree about
+ * what a valid envelope is.
+ *
+ * Memoised: building it reads eleven schema files, and a single baseline
+ * regeneration calls `assertEnvelope` once per write plus once per re-read.
  */
 let _ajv = null;
-const _validators = new Map();
-
-function getAjv() {
-  if (_ajv) return _ajv;
-  const ajv = new Ajv({ allErrors: true, strict: false });
-  addFormats(ajv);
-  const envelopeSchema = JSON.parse(
-    fs.readFileSync(
-      path.join(SCHEMAS_DIR, 'baseline-envelope.schema.json'),
-      'utf8',
-    ),
-  );
-  ajv.addSchema(envelopeSchema, 'baseline-envelope.schema.json');
-  _ajv = ajv;
-  return ajv;
+function ajv() {
+  if (_ajv === null) {
+    _ajv = buildBaselineSchemaAjv();
+  }
+  return _ajv;
 }
 
+/**
+ * Look up the pre-registered validator for a per-kind schema. Total over
+ * `KNOWN_KINDS` — that list is derived from the registry's own filenames, so
+ * every kind reaching here has a compiled schema.
+ *
+ * @param {string} kind
+ * @returns {import('ajv').ValidateFunction}
+ */
 function getValidator(kind) {
-  if (_validators.has(kind)) return _validators.get(kind);
-  const ajv = getAjv();
-  const schema = JSON.parse(
-    fs.readFileSync(path.join(SCHEMAS_DIR, `${kind}.schema.json`), 'utf8'),
-  );
-  const validate = ajv.compile(schema);
-  _validators.set(kind, validate);
-  return validate;
+  return ajv().getSchema(`${kind}.schema.json`);
 }
 
 /**

package/.agents/scripts/lib/baselines/git-base.js

@@ -22,6 +22,13 @@
 //     `ref` and `file` are passed as separate argv tokens, never
 //     interpolated into a shell command.
 //
+// Story #5009 moved the spawn itself, the stdout ceiling and the
+// failure-message shape out to `lib/child-exec.js` — the one child-process
+// surface — so this module now owns only what is genuinely its own: the
+// `(ref, file)` LRU, the exit-code semantics below, and the test seam. The
+// `__setSpawnRunner` seam still injects a mock runner; it is threaded through
+// the shared wrapper as `run` rather than calling `spawnSync` directly.
+//
 // Exit semantics are intentionally narrow:
 //
 //   - Exit 0: stdout is the file contents, returned as a UTF-8 string.
@@ -39,7 +46,7 @@
 // means "path absent at ref". Callers may therefore treat a throw as a
 // hard failure without having to re-diagnose it.
 
-import { spawnSync } from 'node:child_process';
+import { formatChildFailure, spawnChild } from '../child-exec.js';
 
 // ---------------------------------------------------------------------------
 // LRU cache. Small footprint — even a fan-out across all seven baseline
@@ -53,21 +60,13 @@ import { spawnSync } from 'node:child_process';
 const DEFAULT_MAX_ENTRIES = 64;
 
 /**
- * Story #4914 — explicit stdout ceiling for every git read in this module.
- *
- * `child_process.spawnSync` defaults `maxBuffer` to 1 MB. A committed
- * baseline legitimately grows past that (a real consumer's crap baseline
- * measured 1,178,910 bytes), at which point the child is killed —
- * `status: null`, `signal: 'SIGTERM'`, `error.code: 'ENOBUFS'` — and the
- * read fails for a reason that has nothing to do with the repository.
+ * Injected spawn runner, or `undefined` to use the shared surface's real one.
+ * Story #4914's explicit 64 MB ceiling still applies to both git reads below —
+ * it is now `child-exec.js`'s `MAX_BUFFER_BYTES`, applied by `spawnChild`.
  *
- * 64 MB is not a new number: it is the bound already used at
- * `run-test-profile.js:87`, `audit-baselines/trend.js:61` and
- * `audit-baselines/weights.js:65`. This module was the outlier.
+ * @type {Function | undefined}
  */
-const MAX_BUFFER_BYTES = 64 * 1024 * 1024;
-
-let _spawnSync = spawnSync;
+let _spawnRunner;
 let _cache = new Map();
 let _maxEntries = DEFAULT_MAX_ENTRIES;
 
@@ -80,12 +79,12 @@ let _maxEntries = DEFAULT_MAX_ENTRIES;
  * the contract.
  *
  * @param {object} [opts]
- * @param {typeof spawnSync} [opts.spawn] - Mock spawnSync.
- * @param {number} [opts.maxEntries]      - Override LRU capacity.
+ * @param {Function} [opts.spawn]    - Mock spawnSync.
+ * @param {number} [opts.maxEntries] - Override LRU capacity.
  */
 export function __setSpawnRunner(opts = {}) {
   if (opts.spawn) {
-    _spawnSync = opts.spawn;
+    _spawnRunner = opts.spawn;
   }
   if (typeof opts.maxEntries === 'number') {
     _maxEntries = opts.maxEntries;
@@ -98,7 +97,7 @@ export function __setSpawnRunner(opts = {}) {
  * to keep state from leaking across files.
  */
 export function __resetForTests() {
-  _spawnSync = spawnSync;
+  _spawnRunner = undefined;
   _maxEntries = DEFAULT_MAX_ENTRIES;
   _cache = new Map();
 }
@@ -179,13 +178,10 @@ export function readBaseFromGit(ref, file, opts = {}) {
 
   const cwd = opts.cwd ?? process.cwd();
   const spec = `${ref}:${file}`;
-  const result = _spawnSync('git', ['show', spec], {
+  const result = spawnChild('git', ['show', spec], {
+    run: _spawnRunner,
     cwd,
-    stdio: 'pipe',
-    encoding: 'utf-8',
-    shell: false,
     env: cleanGitEnv(),
-    maxBuffer: MAX_BUFFER_BYTES,
   });
 
   // `child_process.spawnSync` returns `status: null` when the child died
@@ -206,9 +202,12 @@ export function readBaseFromGit(ref, file, opts = {}) {
     return null;
   }
 
-  const stderr = (result.stderr || '').toString().trim();
   throw new Error(
-    `readBaseFromGit: git show ${spec} failed (status=${status}): ${stderr}`,
+    formatChildFailure({
+      label: `readBaseFromGit: git show ${spec}`,
+      status,
+      stderr: result.stderr,
+    }),
   );
 }
 
@@ -222,9 +221,10 @@ export function readBaseFromGit(ref, file, opts = {}) {
  * Restricting the log to `-- <file>` means the returned subjects already
  * satisfy the "commit whose diff touches the baseline file" half of the
  * predicate; the caller only has to match the tag substring against each
- * subject. Runs through the same `spawnSync` seam as `readBaseFromGit`, so
- * it inherits the identical env scrubbing (drop inherited `GIT_*`) and the
- * spawn-not-exec security posture (argv tokens, `shell: false`).
+ * subject. Runs through the same shared `spawnChild` surface and injected
+ * runner as `readBaseFromGit`, so it inherits the identical env scrubbing
+ * (drop inherited `GIT_*`), the same stdout ceiling, and the spawn-not-exec
+ * security posture (argv tokens, `shell: false`).
  *
  * Returns an empty array whenever the range cannot be walked (missing base
  * ref, git failure, empty range) — the acknowledgment path treats "no
@@ -244,17 +244,10 @@ export function readRangeSubjectsTouchingFile(baseRef, file, opts = {}) {
   const cwd = opts.cwd ?? process.cwd();
   let result;
   try {
-    result = _spawnSync(
+    result = spawnChild(
       'git',
       ['log', `${baseRef}..HEAD`, '--format=%s', '--', file],
-      {
-        cwd,
-        stdio: 'pipe',
-        encoding: 'utf-8',
-        shell: false,
-        env: cleanGitEnv(),
-        maxBuffer: MAX_BUFFER_BYTES,
-      },
+      { run: _spawnRunner, cwd, env: cleanGitEnv() },
     );
   } catch {
     return [];

package/.agents/scripts/lib/baselines/kinds/_crap-new-method-gate.js

@@ -0,0 +1,103 @@
+/**
+ * _crap-new-method-gate.js — the policy `kinds/crap.js#compareCrap` applies to
+ * a method that has no baseline row (Story #5002).
+ *
+ * Underscore-prefixed like `_shared-metric.js`: this is a helper for the
+ * per-kind modules in this directory, not a kind of its own.
+ *
+ * A leaf — it imports nothing, so `kinds/crap.js` can consume it without
+ * adding an edge to anything the comparator does not already reach.
+ */
+
+/**
+ * The set of scanned files in which **every** measured method resolved 0%
+ * coverage — the observable signature of a source no test loads at all.
+ *
+ * Deliberately derived from the scan rows rather than plumbed down from the
+ * coverage artifact: the rows are the only thing both the preview gate and the
+ * close-validation projection hand the comparator, and "the whole file is at
+ * zero" is exactly what an all-zero istanbul entry produces here.
+ *
+ * A row carrying `coverage: null` is skipped, not counted as a zero — an
+ * absent observation is not a measured one, and letting it vote would hand the
+ * relief below to a file nothing measured at all.
+ *
+ * @param {Array<{file: string, coverage?: number|null}>} currentRows
+ * @returns {Set<string>}
+ */
+export function deriveUncoveredFiles(currentRows) {
+  const allZeroByFile = new Map();
+  for (const row of currentRows ?? []) {
+    if (typeof row?.coverage !== 'number') continue;
+    const soFar = allZeroByFile.get(row.file);
+    allZeroByFile.set(row.file, (soFar ?? true) && row.coverage === 0);
+  }
+  const uncovered = new Set();
+  for (const [file, allZero] of allZeroByFile) {
+    if (allZero) uncovered.add(file);
+  }
+  return uncovered;
+}
+
+/**
+ * The score a **new** method is judged against `newMethodCeiling` with.
+ *
+ * Normally the measured CRAP. In a file whose every method scored 0%, the
+ * complexity term `c` alone.
+ *
+ * **Why.** `crap = c²·(1 − cov)³ + c` collapses to `c² + c` at zero coverage,
+ * so the default ceiling of 30 caps a *brand-new* method in an untested file
+ * at `c ≈ 5`. For the code that is untestable by construction — argv parsing,
+ * `spawn` wiring, a CLI's top-level `main()` — that is not a quality signal
+ * but a fragmentation tax: the only way past it is to shatter cohesive wiring
+ * into sub-five-branch fragments, which raises the file's method count and its
+ * reader's cost while measuring nothing. The coverage term still governs every
+ * method in a file the tests *do* reach, and a genuinely sprawling function is
+ * still refused — `c` alone must clear the ceiling.
+ *
+ * This is a **gate** decision, not a scoring one: the persisted baseline row
+ * keeps its measured `c² + c`, so the regression arm on the next run compares
+ * like with like.
+ *
+ * @param {{file: string, crap: number, cyclomatic?: number}} row
+ * @param {Set<string>} uncoveredFiles
+ * @returns {number}
+ */
+export function newMethodGateScore(row, uncoveredFiles) {
+  if (!uncoveredFiles.has(row.file)) return row.crap;
+  return Number.isFinite(row.cyclomatic) ? row.cyclomatic : row.crap;
+}
+
+/**
+ * Assemble a new-method violation.
+ *
+ * `gateScore` is written **only** when the ceiling was judged against
+ * something other than the measured `crap` — the same write-only-when-
+ * non-default idiom `projectRow` uses for its row markers — so the printer can
+ * name the number that actually failed instead of one nothing tested.
+ *
+ * @param {object} row
+ * @param {number} ceiling
+ * @param {number} gateScore
+ * @returns {object}
+ */
+export function buildNewViolation(row, ceiling, gateScore) {
+  return {
+    ...row,
+    kind: 'new',
+    baseline: null,
+    ceiling,
+    ...(gateScore === row.crap ? {} : { gateScore }),
+  };
+}
+
+/**
+ * Render the measured-vs-gated half of a new-method violation line.
+ *
+ * @param {{crap: number, gateScore?: number}} v
+ * @returns {string}
+ */
+export function formatNewViolationMeasure(v) {
+  if (v.gateScore === undefined) return `crap=${v.crap.toFixed(2)}`;
+  return `complexity=${v.gateScore} (file has no coverage; crap=${v.crap.toFixed(2)})`;
+}

package/.agents/scripts/lib/baselines/kinds/_crap-read.js

@@ -0,0 +1,150 @@
+/**
+ * _crap-read.js — the CRAP baseline read path (Story #5002).
+ *
+ * Underscore-prefixed like `_shared-metric.js`: a helper for the per-kind
+ * modules in this directory, not a kind of its own. `kinds/crap.js` re-exports
+ * `loadCrapBaseline` so existing importers keep one door.
+ *
+ * **This module is the whole read path, and there is only one.** `crap-utils.js`
+ * used to carry a second one — `projectCrapEnvelopeToLegacy` plus its
+ * `COMPAT_STAMP_*` allow-lists — so `check-baselines` (through
+ * `baselines/reader.js`) and the `quality-preview` pre-commit arm (through that
+ * projection) fed the same compat axes from two hand-maintained field lists. A
+ * stamp added to one and not the other yielded two opposite verdicts on one
+ * envelope, three times over: Story #4866 (`scoringSemantics`,
+ * `tsTranspilerVersion`), #4969 (`rows[].anonymous`), #4986
+ * (`provenanceStamped`). Every one of those axes keys on a POSITIVE marker, so
+ * a dropped field read `undefined` and failed the baseline closed with a remedy
+ * that could not work — re-deriving it wrote the stamp the read path then
+ * discarded. With one reader that drift class is structurally impossible, so no
+ * allow-list needs maintaining.
+ */
+
+import path from 'node:path';
+import { readBaselineAtRef } from '../../baseline-loader.js';
+import { resolveEscomplexVersion } from '../../crap-utils.js';
+import { loadBaseline } from '../../gates/baseline-store.js';
+import {
+  loadFile as loadBaselineFile,
+  load as loadBaselineKind,
+} from '../reader.js';
+
+/**
+ * Read the committed CRAP baseline off the working tree through
+ * `baselines/reader.js` and project it onto the `file`-keyed shape the
+ * comparator and the compat axes consume.
+ *
+ * `baselinePath` selects the explicit-path reader variant (the worktree /
+ * epic-ref callers always know their own path); without one the reader
+ * resolves the configured location for the `crap` kind itself.
+ *
+ * `escomplexVersion` is back-filled from the running scorer exactly as the
+ * deleted projection stamped it — the v2 envelope does not carry the field, and
+ * `escomplex-mismatch` is a fatal axis, so omitting it would fail every
+ * baseline closed on a value that was never on disk.
+ *
+ * Returns `null` on any read/parse/schema failure; the preview gate maps that
+ * to "no baseline" and fails open, as it always did.
+ *
+ * Deliberately module-local: `loadCrapBaseline`'s `readFromTree` default is the
+ * single production door to it, and tests inject their own loader.
+ *
+ * @param {{baselinePath?: string, projectRoot?: string}} [opts]
+ * @returns {object|null}
+ */
+function readCrapBaselineFromTree({ baselinePath, projectRoot } = {}) {
+  const cwd = projectRoot ?? process.cwd();
+  let envelope;
+  try {
+    envelope = baselinePath
+      ? loadBaselineFile(
+          path.isAbsolute(baselinePath)
+            ? baselinePath
+            : path.resolve(cwd, baselinePath),
+          { kind: 'crap' },
+        )
+      : loadBaselineKind('crap', { cwd });
+  } catch {
+    return null;
+  }
+  return {
+    kernelVersion: envelope.kernelVersion,
+    escomplexVersion: resolveEscomplexVersion(),
+    scoringSemantics: envelope.scoringSemantics ?? null,
+    tsTranspilerVersion:
+      typeof envelope.tsTranspilerVersion === 'string'
+        ? envelope.tsTranspilerVersion
+        : null,
+    provenanceStamped: envelope.provenanceStamped,
+    rows: (envelope.rows ?? []).map(projectBaselineRow),
+  };
+}
+
+/**
+ * Re-key one on-disk row (`path`) onto the `file` field `compareCrap` matches
+ * on, carrying the two write-only-when-non-default row markers verbatim.
+ *
+ * Both markers are BASELINE facts. Dropping `anonymous` would leave every
+ * re-keyed row looking like an unmarked anonymous one — precisely the shape the
+ * `anon-identity-unstamped` axis fails closed (Story #4969) — and dropping
+ * `coordinateSystem` would let the comparator drift-resolve across two
+ * coordinate systems (Story #4866).
+ *
+ * @param {{path: string, method: string, startLine: number, crap: number,
+ *   coordinateSystem?: string, anonymous?: boolean}} row
+ * @returns {object}
+ */
+function projectBaselineRow(row) {
+  return {
+    crap: row.crap,
+    file: row.path,
+    method: row.method,
+    startLine: row.startLine,
+    ...(row.coordinateSystem === undefined
+      ? {}
+      : { coordinateSystem: row.coordinateSystem }),
+    ...(row.anonymous === undefined ? {} : { anonymous: row.anonymous }),
+  };
+}
+
+/**
+ * Pure helper: resolve the CRAP baseline either from the working tree (via
+ * `readCrapBaselineFromTree`) or, when `epicRef` is supplied, from
+ * `git show <epicRef>:<baselinePath>` via `readBaselineAtRef`.
+ *
+ * Story #1120 threads `epic/<id>` into close-validation so the comparison runs
+ * against the Epic-branch HEAD's committed baseline. This helper delegates the
+ * read to baseline-store and applies the CRAP shape-check +
+ * `tsTranspilerVersion` back-fill on top.
+ */
+export function loadCrapBaseline({
+  baselinePath,
+  epicRef,
+  readAtRef = readBaselineAtRef,
+  readFromTree = readCrapBaselineFromTree,
+  logger = console,
+}) {
+  const parsed = loadBaseline({
+    baselinePath,
+    epicRef,
+    readAtRef,
+    readFromTree,
+    logger,
+    label: 'CRAP',
+  });
+  // No-epicRef path delegates to readFromTree which already applies the
+  // shape-check + tsTranspilerVersion back-fill, so a tree read returns either
+  // a valid envelope or null. Epic-ref path bypasses that helper — shape-check
+  // + back-fill happens here.
+  if (!epicRef) return parsed;
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return null;
+  }
+  if (typeof parsed.kernelVersion !== 'string') return null;
+  if (typeof parsed.escomplexVersion !== 'string') return null;
+  if (!Array.isArray(parsed.rows)) return null;
+  if (typeof parsed.tsTranspilerVersion !== 'string') {
+    parsed.tsTranspilerVersion = '0.0.0';
+  }
+  return parsed;
+}

package/.agents/scripts/lib/baselines/kinds/crap.js

@@ -13,15 +13,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { readBaselineAtRef } from '../../baseline-loader.js';
 import {
   COORDINATE_ORIGINAL,
   COORDINATE_TRANSPILED,
   deriveFixGuidance,
 } from '../../crap-engine.js';
 import { isAnonymousMethodLabel } from '../../crap-method-identity.js';
-import { getCrapBaseline } from '../../crap-utils.js';
-import { loadBaseline } from '../../gates/baseline-store.js';
 import { Logger } from '../../Logger.js';
 import { resolveTsTranspilerVersion } from '../../transpile.js';
 import {
@@ -31,6 +28,12 @@ import {
 } from '../envelope.js';
 import { canonicalise } from '../path-canon.js';
 import { mergeRowsByScope } from '../scope.js';
+import {
+  buildNewViolation,
+  deriveUncoveredFiles,
+  formatNewViolationMeasure,
+  newMethodGateScore,
+} from './_crap-new-method-gate.js';
 import {
   makeAggregate,
   makeCompare,
@@ -42,6 +45,11 @@ import {
 export const name = 'crap';
 export const keyField = 'path';
 
+// The CRAP baseline read path (Story #5002) lives in `_crap-read.js` — the ONE
+// door, re-exported here so `preview-gates.js` and every existing importer keep
+// reaching it through this module.
+export { loadCrapBaseline } from './_crap-read.js';
+
 const __filename = fileURLToPath(import.meta.url);
 
 /**
@@ -245,18 +253,12 @@ function crapRowKey(row) {
   return `${row.path}::${row.method}@${row.startLine}`;
 }
 
-// `methodIdentityKey` / `indexBaselineRowsByFile` (Story #4981) live in
-// crap-baseline-index.js, not here — `crap-utils.js#scanAndScore` needs them
-// to build the incremental join's per-file baseline lookup, and crap-utils.js
-// already imports `getCrapBaseline` FROM this module. Defining them here and
-// importing them into crap-utils.js would close that edge into a cycle
-// (kinds/crap.js → crap-utils.js → kinds/crap.js). Re-exported here so
-// existing importers of this module keep a single door to the identity key
-// `crapRowKey` composes with the file path.
-export {
-  indexBaselineRowsByFile,
-  methodIdentityKey,
-} from '../../crap-baseline-index.js';
+// `methodIdentityKey` / `indexBaselineRowsByFile` (Story #4981) are now
+// module-local to `crap-baseline-join.js` (Story #5002): after that module
+// absorbed the per-file queue wiring, both callers are inside it, so the
+// exports — and the re-export that used to live here — were reachable from
+// tests alone. `resolveIncrementalContext` is the production door to the
+// index; `crapRowKey` above is the composite key it halves.
 
 /**
  * Pure stabilizer for s-stability-epsilon (Story #1964). CRAP rows match
@@ -395,6 +397,9 @@ export function checkCrapRegression(row, baseline, tolerance, kind) {
  * (`crap: null` / `coverage: null`, or an explicit `unscorable: true`) carries
  * no measurement to compare. It is bucketed and counted, and it is excluded
  * from `comparable` so it cannot dilute any ratio derived from this result.
+ *
+ * **A new method in a wholly-uncovered file is gated on complexity alone**
+ * (Story #5002) — see `newMethodGateScore`.
  */
 export function compareCrap({
   currentRows,
@@ -402,6 +407,7 @@ export function compareCrap({
   newMethodCeiling,
   tolerance,
 }) {
+  const uncoveredFiles = deriveUncoveredFiles(currentRows);
   const exactIndex = new Map();
   const methodIndex = new Map();
   for (const b of baselineRows ?? []) {
@@ -475,14 +481,10 @@ export function compareCrap({
       continue;
     }
 
-    if (row.crap > newMethodCeiling + tolerance) {
+    const gateScore = newMethodGateScore(row, uncoveredFiles);
+    if (gateScore > newMethodCeiling + tolerance) {
       newViolations += 1;
-      violations.push({
-        ...row,
-        kind: 'new',
-        baseline: null,
-        ceiling: newMethodCeiling,
-      });
+      violations.push(buildNewViolation(row, newMethodCeiling, gateScore));
     }
   }
 
@@ -892,48 +894,6 @@ export function assertBaselineCompatible(baseline, ctx = {}) {
   return null;
 }
 
-/**
- * Pure helper: resolve the CRAP baseline either from the working tree
- * (via `getCrapBaseline`) or, when `epicRef` is supplied, from
- * `git show <epicRef>:<baselinePath>` via `readBaselineAtRef`.
- *
- * Story #1120 threads `epic/<id>` into close-validation so the
- * comparison runs against the Epic-branch HEAD's committed baseline.
- * This helper delegates the read to baseline-store and applies the CRAP
- * shape-check + `tsTranspilerVersion` back-fill on top.
- */
-export function loadCrapBaseline({
-  baselinePath,
-  epicRef,
-  readAtRef = readBaselineAtRef,
-  readFromTree = getCrapBaseline,
-  logger = console,
-}) {
-  const parsed = loadBaseline({
-    baselinePath,
-    epicRef,
-    readAtRef,
-    readFromTree,
-    logger,
-    label: 'CRAP',
-  });
-  // No-epicRef path delegates to readFromTree which already applies the
-  // shape-check + tsTranspilerVersion back-fill, so a tree read returns
-  // either a valid envelope or null. Epic-ref path bypasses that helper
-  // — shape-check + back-fill happens here.
-  if (!epicRef) return parsed;
-  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
-    return null;
-  }
-  if (typeof parsed.kernelVersion !== 'string') return null;
-  if (typeof parsed.escomplexVersion !== 'string') return null;
-  if (!Array.isArray(parsed.rows)) return null;
-  if (typeof parsed.tsTranspilerVersion !== 'string') {
-    parsed.tsTranspilerVersion = '0.0.0';
-  }
-  return parsed;
-}
-
 /**
  * Build the structured `--json` report envelope.
  *
@@ -1061,7 +1021,7 @@ export function printViolation(v) {
       `[CRAP] ❌ NEW-METHOD over ceiling: ${v.file}::${v.method} (line ${v.startLine})`,
     );
     Logger.error(
-      `       crap=${v.crap.toFixed(2)} > ceiling=${v.ceiling} (c=${v.cyclomatic}, cov=${v.coverage.toFixed(2)})`,
+      `       ${formatNewViolationMeasure(v)} > ceiling=${v.ceiling} (c=${v.cyclomatic}, cov=${v.coverage.toFixed(2)})`,
     );
     return;
   }