mandrel 2.59.0 → 2.61.0

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

@@ -1,82 +1,23 @@
-// .agents/scripts/lib/baselines/git-base.js
+// The one loader for base-ref baseline reads: `git show <ref>:<file>` via
+// argv tokens (no shell), with a `(ref, file)` LRU that also caches `null`.
 //
-// Story #1962 / Task #1969 — Single safe loader for base-ref baseline
-// reads. Every per-kind regression CLI in Epic #1943 needs to read the
-// committed baseline from a base ref (typically the Epic branch tip or
-// `origin/main`) and diff it against the head's working-tree baseline.
-// Routing every read through `readBaseFromGit(ref, file)` guarantees:
-//
-//   - One implementation of "spawn `git show <ref>:<file>`", with
-//     identical argv shape, identical env scrubbing, and identical
-//     error semantics. Per-kind CLIs do not get to invent their own
-//     git invocations and drift apart.
-//   - One LRU cache keyed by `(ref, file)`. Within a single dispatcher
-//     run, the same `(ref, file)` tuple is read at most once even when
-//     multiple gates need it (e.g. when scope resolution and the
-//     regression compare both touch the same baseline file). The cache
-//     stores the full result — including `null` for "no such file at
-//     ref" — so a missing baseline does not re-spawn git on every
-//     subsequent lookup.
-//   - `child_process.spawn`-based execution (no shell), which is the
-//     security baseline (`security-baseline.md` § Output & Rendering):
-//     `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.
-//   - Exit 128: git's "path does not exist in this revision" — the
-//     loader treats this as a normal "no baseline at base ref" case
-//     and returns `null`. Callers branch on `result === null` rather
-//     than catching an error.
-//   - Any other outcome (bad ref, corrupted repo, git binary missing, or
-//     the child killed by signal so `status` is `null`): thrown so the
-//     dispatcher can surface a config-error exit code rather than
-//     silently treating the failure as "no baseline". A bad ref is a
-//     config bug, not a missing file.
-//
-// That two-way split is load-bearing (Story #4914): `null` means and only
-// means "path absent at ref". Callers may therefore treat a throw as a
-// hard failure without having to re-diagnose it.
+// Exit semantics: 0 → contents; 128 → `null` ("path absent at ref", and only
+// that); anything else (bad ref, signal-killed child) throws, so callers may
+// treat a throw as a hard config failure, never as "no baseline".
 
 import { formatChildFailure, spawnChild } from '../child-exec.js';
 
-// ---------------------------------------------------------------------------
-// LRU cache. Small footprint — even a fan-out across all seven baseline
-// kinds against two refs (head + base) is 14 entries. Capping at 64 keeps
-// long-lived dispatcher runs (e.g. orchestrators that loop across
-// multiple stories) bounded without ever evicting a hot entry in normal
-// use. The cache stores `null` as a real value so missing-file lookups
-// also hit on the second call.
-// ---------------------------------------------------------------------------
-
+// Seven kinds × two refs is 14 entries; 64 bounds long-lived runs without
+// evicting hot entries.
 const DEFAULT_MAX_ENTRIES = 64;
 
-/**
- * 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`.
- *
- * @type {Function | undefined}
- */
+/** @type {Function | undefined} */
 let _spawnRunner;
 let _cache = new Map();
 let _maxEntries = DEFAULT_MAX_ENTRIES;
 
 /**
- * Test-only seam. Lets the unit test inject a mock `spawnSync` (to
- * count invocations and assert "spawn, not exec") and a fresh cache (so
- * test order does not leak through the module-global LRU).
- *
- * Production code MUST NOT call this. The double-underscore prefix is
- * the contract.
+ * Test-only.
  *
  * @param {object} [opts]
  * @param {Function} [opts.spawn]    - Mock spawnSync.
@@ -92,10 +33,6 @@ export function __setSpawnRunner(opts = {}) {
   _cache = new Map();
 }
 
-/**
- * Reset the loader to factory defaults. Tests call this in `afterEach`
- * to keep state from leaking across files.
- */
 export function __resetForTests() {
   _spawnRunner = undefined;
   _maxEntries = DEFAULT_MAX_ENTRIES;
@@ -103,8 +40,7 @@ export function __resetForTests() {
 }
 
 /**
- * Internal: build the cache key. Joining with a NUL byte is cheap and
- * collision-free — neither git refs nor POSIX paths may contain NUL.
+ * NUL-joined: neither refs nor paths may contain NUL.
  *
  * @param {string} ref
  * @param {string} file
@@ -115,9 +51,7 @@ function cacheKey(ref, file) {
 }
 
 /**
- * Internal: bump an entry to the most-recently-used end of the LRU. Map
- * iteration order is insertion order, so deleting and re-setting moves
- * the entry to the back.
+ * Move to the MRU end (Map iteration is insertion order) and evict the LRU.
  *
  * @param {string} key
  * @param {string | null} value
@@ -126,18 +60,14 @@ function touch(key, value) {
   _cache.delete(key);
   _cache.set(key, value);
   while (_cache.size > _maxEntries) {
-    // Evict the least-recently-used entry (first key in iteration).
     const oldest = _cache.keys().next().value;
     _cache.delete(oldest);
   }
 }
 
 /**
- * Build a child-process env that drops every `GIT_*` variable inherited
- * from the parent. Mirrors `git-utils.js#cleanGitEnv` — see that file for
- * the long-form explanation. Without this, husky-driven invocations
- * inherit the parent's `GIT_DIR` / `GIT_WORK_TREE` and end up reading
- * from the wrong worktree.
+ * Drop inherited `GIT_*` vars: under husky, `GIT_DIR`/`GIT_WORK_TREE` would
+ * point git at the wrong worktree.
  */
 function cleanGitEnv() {
   return Object.fromEntries(
@@ -145,21 +75,15 @@ function cleanGitEnv() {
   );
 }
 
-/** Both reads reject the same way on a missing or non-string argument. */
 function isNonEmptyString(value) {
   return typeof value === 'string' && value.length > 0;
 }
 
-/** Both reads coerce a missing stdout to the empty string rather than throwing. */
 function stdoutOf(result) {
   return typeof result?.stdout === 'string' ? result.stdout : '';
 }
 
 /**
- * Run a git subprocess through the shared child surface. Both reads below need
- * the identical shape — injected runner, resolved cwd, `GIT_*`-scrubbed env,
- * argv tokens rather than a shell string — so it lives here once.
- *
  * @param {string[]} args
  * @param {{ cwd?: string }} opts
  */
@@ -172,18 +96,9 @@ function runGit(args, opts) {
 }
 
 /**
- * Read `<file>` at the given git ref. Returns the file contents as a
- * UTF-8 string when the path exists, or `null` when git reports the
- * path does not exist at the ref.
- *
- * Cached: subsequent calls with the same `(ref, file)` skip the
- * subprocess and return the cached value (including a cached `null`).
- *
- * @param {string} ref     - Any ref git understands (`HEAD`, `epic/1943`,
- *                           `origin/main`, a SHA, …).
- * @param {string} file    - Repo-relative path to the file.
- * @param {{ cwd?: string }} [opts] - Optional cwd override; defaults to
- *                                    `process.cwd()`.
+ * @param {string} ref
+ * @param {string} file    - Repo-relative path.
+ * @param {{ cwd?: string }} [opts]
  * @returns {string | null}
  */
 export function readBaseFromGit(ref, file, opts = {}) {
@@ -196,7 +111,6 @@ export function readBaseFromGit(ref, file, opts = {}) {
 
   const key = cacheKey(ref, file);
   if (_cache.has(key)) {
-    // Hot path — re-touch to refresh LRU position, but no spawn.
     const cached = _cache.get(key);
     touch(key, cached);
     return cached;
@@ -205,8 +119,7 @@ export function readBaseFromGit(ref, file, opts = {}) {
   const spec = `${ref}:${file}`;
   const result = runGit(['show', spec], opts);
 
-  // `child_process.spawnSync` returns `status: null` when the child died
-  // by signal. Treat that as a hard failure rather than "no file".
+  // `status: null` (signal-killed) falls through to the throw.
   const status = result.status;
   if (status === 0) {
     const out = stdoutOf(result);
@@ -214,10 +127,7 @@ export function readBaseFromGit(ref, file, opts = {}) {
     return out;
   }
 
-  // Git uses exit 128 for "path does not exist in this revision" and a
-  // handful of other "ref/path not found" cases. The stderr message
-  // varies across git versions; matching on the exit code keeps us
-  // version-independent and i18n-safe.
+  // Match the exit code, not stderr: stable across git versions and locales.
   if (status === 128) {
     touch(key, null);
     return null;
@@ -233,39 +143,11 @@ export function readBaseFromGit(ref, file, opts = {}) {
 }
 
 /**
- * Read the commits, within the range `<baseRef>..HEAD`, that touched `<file>`
- * (Story #4731; widened to carry SHAs by Story #5179). Powers the baseline
- * refresh-acknowledgment trigger: a `baseline-refresh:`-tagged commit in the
- * compared range that touches a kind's baseline acknowledges that run's
- * head-vs-base regressions.
- *
- * Story #5179 — this returned SUBJECTS ONLY, and that omission was load-bearing
- * in the wrong direction. With no commit handle, the acknowledgment could not
- * ask what the tagged commit actually rewrote, so it could only be a whole-run
- * blanket: every regression in the range demoted, including rows that commit
- * never touched and drift that landed after it. Carrying `sha` alongside
- * `subject` is what lets the caller read the baseline blob AT the refresh
- * commit and scope the acknowledgment to it.
- *
- * Restricting the log to `-- <file>` means the returned commits 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 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`).
- *
- * A NUL separator between the two fields is what makes this parse safely: a
- * commit subject may contain anything except a newline, so any printable
- * delimiter could appear inside one, but neither field may contain NUL.
- *
- * Returns an empty array whenever the range cannot be walked (missing base ref,
- * git failure, empty range) — the acknowledgment path treats "no matching
- * commit" and "could not determine" identically: the ratchet stays at full
- * strength. Not cached: the range result depends on live HEAD, which the
- * `(ref, file)` LRU key does not capture.
+ * Commits in `<baseRef>..HEAD` touching `<file>`; `sha` lets the refresh
+ * acknowledgment scope to what that commit rewrote. `[]` on failure keeps the
+ * ratchet strict. Uncached: depends on live HEAD.
  *
- * @param {string} baseRef - Range base (e.g. `main`, `origin/main`, a SHA).
+ * @param {string} baseRef
  * @param {string} file    - Repo-relative path to the baseline file.
  * @param {{ cwd?: string }} [opts]
  * @returns {{ sha: string, subject: string }[]} newest first; `[]` on any failure.
@@ -298,8 +180,7 @@ export function readRangeCommitsTouchingFile(baseRef, file, opts = {}) {
 }
 
 /**
- * Inspect the current cache size. Test-only — production code should
- * not reason about cache state.
+ * Test-only.
  *
  * @returns {number}
  */

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

@@ -1,27 +1,7 @@
 /**
- * kernel.js — per-kind kernel-version resolution (Story #1891, Epic #1786).
- *
- * Every committed baseline stamps a `kernelVersion` semver string in its
- * envelope. The version tracks the in-repo (or upstream) kernel that
- * produced the rows — a bump invalidates every committed baseline of
- * that kind, signalling consumers to regenerate. The version source is
- * **per-kind**:
- *
- *   - CRAP and Maintainability share the `typhonjs-escomplex` upstream
- *     package version; both modules' `kernelVersion()` read it from the
- *     nearest `node_modules/typhonjs-escomplex/package.json`.
- *   - Lint, Coverage, Mutation, Lighthouse, Bundle-Size carry a static
- *     in-repo semver bumped by hand whenever the scoring/rollup math
- *     changes. Their `kernelVersion()` just returns the constant.
- *
- * This module is the public surface: callers ask
- * `currentKernelVersion(kind)` and get a single string back, no matter
- * which strategy the kind uses internally.
- *
- * `checkKernelVersion(kind, baselineVersion)` is the drift-detection
- * helper. It returns `{ match, current }` so a CI gate can compare the
- * baseline's stamp against the running kernel and decide whether to
- * regenerate or fail.
+ * Kind-module registry and kernel-version resolution. CRAP and MI stamp the
+ * installed scorer package version; the other kinds stamp a static semver
+ * bumped by hand when their scoring or rollup math changes.
  *
  * @module lib/baselines/kernel
  */
@@ -76,30 +56,6 @@ import {
   rowIdentity as duplicationRowIdentity,
   sortRows as duplicationSortRows,
 } from './kinds/duplication.js';
-import {
-  applyEpsilon as lighthouseApplyEpsilon,
-  compare as lighthouseCompare,
-  kernelVersion as lighthouseKernelVersion,
-  keyField as lighthouseKeyField,
-  mergeRows as lighthouseMergeRows,
-  name as lighthouseName,
-  projectRow as lighthouseProjectRow,
-  rollup as lighthouseRollup,
-  rowIdentity as lighthouseRowIdentity,
-  sortRows as lighthouseSortRows,
-} from './kinds/lighthouse.js';
-import {
-  applyEpsilon as lintApplyEpsilon,
-  compare as lintCompare,
-  kernelVersion as lintKernelVersion,
-  keyField as lintKeyField,
-  mergeRows as lintMergeRows,
-  name as lintName,
-  projectRow as lintProjectRow,
-  rollup as lintRollup,
-  rowIdentity as lintRowIdentity,
-  sortRows as lintSortRows,
-} from './kinds/lint.js';
 import {
   applyEpsilon as maintainabilityApplyEpsilon,
   compare as maintainabilityCompare,
@@ -127,14 +83,8 @@ import {
 } from './kinds/mutation.js';
 
 /**
- * Assemble the kind-module protocol from named imports.
- *
- * Prefer named imports over `import * as kind` here: knip (and the
- * dead-exports ratchet) cannot see members reached only through
- * `getKindModule(kind).projectRow(...)` after a namespace import, so
- * star-imports of `kinds/*.js` produced systematic false-positive dead
- * exports for the protocol surface (`name`, `keyField`, `kernelVersion`,
- * `projectRow`, `sortRows`, `rollup`, …).
+ * Named imports, not `import * as`: knip cannot see members reached through
+ * a namespace, which reports the protocol surface as dead exports.
  *
  * @param {object} members
  * @returns {object}
@@ -143,8 +93,7 @@ function bindKindModule(members) {
   return Object.freeze({
     name: members.name,
     keyField: members.keyField,
-    // Story #5215: the merge identity, distinct from the `keyField`
-    // grouping key above — CRAP groups by file and identifies by method.
+    // Merge identity; distinct from the `keyField` grouping key.
     rowIdentity: members.rowIdentity,
     kernelVersion: members.kernelVersion,
     projectRow: members.projectRow,
@@ -153,32 +102,14 @@ function bindKindModule(members) {
     compare: members.compare,
     applyEpsilon: members.applyEpsilon,
     mergeRows: members.mergeRows,
-    // Optional per-kind hooks (Story #4775). `envelopeExtras` contributes
-    // envelope-level stamps the shared writer would not otherwise know about;
-    // `assertBaselineCompatible` lets a kind refuse a loaded baseline whose
-    // scoring semantics predate the running scorer.
+    // Optional hooks: extra envelope stamps; refusal of an incompatible baseline.
     envelopeExtras: members.envelopeExtras,
     assertBaselineCompatible: members.assertBaselineCompatible,
   });
 }
 
-/**
- * Registry of every shipped kind module. Keys mirror the per-kind schema
- * filenames so a future "list all kinds" iterator can stay declarative.
- */
+/** Keys mirror the per-kind schema filenames. */
 const KIND_MODULES = Object.freeze({
-  lint: bindKindModule({
-    name: lintName,
-    keyField: lintKeyField,
-    rowIdentity: lintRowIdentity,
-    kernelVersion: lintKernelVersion,
-    projectRow: lintProjectRow,
-    sortRows: lintSortRows,
-    rollup: lintRollup,
-    compare: lintCompare,
-    applyEpsilon: lintApplyEpsilon,
-    mergeRows: lintMergeRows,
-  }),
   coverage: bindKindModule({
     name: coverageName,
     keyField: coverageKeyField,
@@ -230,18 +161,6 @@ const KIND_MODULES = Object.freeze({
     mergeRows: mutationMergeRows,
     assertBaselineCompatible: mutationAssertBaselineCompatible,
   }),
-  lighthouse: bindKindModule({
-    name: lighthouseName,
-    keyField: lighthouseKeyField,
-    rowIdentity: lighthouseRowIdentity,
-    kernelVersion: lighthouseKernelVersion,
-    projectRow: lighthouseProjectRow,
-    sortRows: lighthouseSortRows,
-    rollup: lighthouseRollup,
-    compare: lighthouseCompare,
-    applyEpsilon: lighthouseApplyEpsilon,
-    mergeRows: lighthouseMergeRows,
-  }),
   'bundle-size': bindKindModule({
     name: bundleSizeName,
     keyField: bundleSizeKeyField,
@@ -269,8 +188,7 @@ const KIND_MODULES = Object.freeze({
 });
 
 /**
- * Look up a kind module by name. Throws when the kind isn't registered so
- * callers can't silently fall through to undefined behaviour.
+ * Throws on an unregistered kind.
  *
  * @param {string} kind
  * @returns {{ name: string, keyField: string, kernelVersion: () => string,
@@ -290,10 +208,6 @@ export function getKindModule(kind) {
 }
 
 /**
- * Resolve the running kernel version for `kind`. Delegates to the per-kind
- * module's `kernelVersion()` — see the module preamble for which strategy
- * each kind uses.
- *
  * @param {string} kind
  * @returns {string}
  */
@@ -302,10 +216,6 @@ export function currentKernelVersion(kind) {
 }
 
 /**
- * Resolve a kind module, or null when the kind is not registered. Lets the
- * optional-hook callers below stay expression-shaped instead of threading a
- * mutable binding through a try/catch.
- *
  * @param {string} kind
  * @returns {object|null}
  */
@@ -318,10 +228,8 @@ function tryGetKindModule(kind) {
 }
 
 /**
- * Ask a kind whether a loaded baseline is compatible with the running
- * scorer's SEMANTICS — a dimension `kernelVersion` cannot express, because a
- * kind's scoring can change while the upstream package it stamps does not
- * (Story #4775). Kinds without the hook always answer "compatible".
+ * Semantic compatibility, which `kernelVersion` cannot express: scoring can
+ * change while the stamped package does not. Kinds without the hook pass.
  *
  * @param {string} kind
  * @param {object|null} baseline
@@ -334,10 +242,6 @@ export function checkBaselineSemantics(kind, baseline) {
 }
 
 /**
- * Compare a baseline's stamped version against the currently running
- * kernel for the same kind. Returns `{ match, current }` so callers can
- * format a drift signal or trigger a regenerate.
- *
  * @param {string} kind
  * @param {string} baselineVersion
  * @returns {{ match: boolean, current: string }}
@@ -351,10 +255,6 @@ export function checkKernelVersion(kind, baselineVersion) {
 }
 
 /**
- * List every kind registered with the kernel. Useful for the writer's
- * envelope sanity check and for tests that want to iterate all shipped
- * kinds.
- *
  * @returns {string[]}
  */
 export function listKinds() {

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

@@ -1,26 +1,8 @@
-/**
- * _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 gate `compareCrap` applies to a method with no baseline row. A leaf. */
 
 /**
- * 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.
+ * Files whose every measured method is at 0% coverage (no test loads them).
+ * `coverage: null` rows do not vote: unmeasured is not zero.
  *
  * @param {Array<{file: string, coverage?: number|null}>} currentRows
  * @returns {Set<string>}
@@ -40,24 +22,10 @@ export function deriveUncoveredFiles(currentRows) {
 }
 
 /**
- * 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.
+ * The score a new method meets the ceiling with: measured CRAP, or complexity
+ * `c` alone in a wholly uncovered file. At zero coverage CRAP is `c² + c`,
+ * which caps untestable wiring (argv, spawn, `main()`) at `c ≈ 5` and forces
+ * fragmentation. Gate-only: the persisted row keeps the measured CRAP.
  *
  * @param {{file: string, crap: number, cyclomatic?: number}} row
  * @param {Set<string>} uncoveredFiles
@@ -69,12 +37,8 @@ export function newMethodGateScore(row, uncoveredFiles) {
 }
 
 /**
- * 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.
+ * `gateScore` is set only when it differs from `crap`, so the printer names
+ * the number that actually failed.
  *
  * @param {object} row
  * @param {number} ceiling
@@ -92,8 +56,6 @@ export function buildNewViolation(row, ceiling, gateScore) {
 }
 
 /**
- * Render the measured-vs-gated half of a new-method violation line.
- *
  * @param {{crap: number, gateScore?: number}} v
  * @returns {string}
  */

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

@@ -1,23 +1,6 @@
 /**
- * _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.
+ * The single CRAP baseline read path, built on `baselines/reader.js` so every
+ * gate feeds the compat axes the same stamps. Re-exported by `kinds/crap.js`.
  */
 
 import path from 'node:path';
@@ -29,19 +12,8 @@ import {
 } 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.
- *
- * 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.
+ * Read the working-tree baseline, projected onto the `file`-keyed comparator
+ * shape. `null` on any failure; the preview gate then fails open.
  *
  * @param {{baselinePath?: string, projectRoot?: string}} [opts]
  * @returns {object|null}
@@ -74,14 +46,8 @@ function readCrapBaselineFromTree({ baselinePath, projectRoot } = {}) {
 }
 
 /**
- * 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).
+ * Re-key `path` to `file`, carrying `coordinateSystem` and `anonymous`
+ * verbatim: dropping either breaks a compat axis or the comparator.
  *
  * @param {{path: string, method: string, startLine: number, crap: number,
  *   coordinateSystem?: string, anonymous?: boolean}} row
@@ -101,14 +67,8 @@ function projectBaselineRow(row) {
 }
 
 /**
- * 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.
+ * From the working tree, or from `<epicRef>:<baselinePath>` when `epicRef` is
+ * set; only the ref path needs the shape-check and transpiler back-fill.
  */
 export function loadCrapBaseline({
   baselinePath,
@@ -125,9 +85,6 @@ export function loadCrapBaseline({
     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
   if (!epicRef) return parsed;
   if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
     return null;