mandrel 2.25.0 → 2.26.0

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

@@ -315,17 +315,79 @@ export async function runCloseValidation({
   }
 
   // ── Phase 2: serial gates in declared order ─────────────────────────
+  await runSerialGates(serial, {
+    spawnCwd,
+    log,
+    failed,
+    skipped,
+    evidenceActive,
+    evidenceClock,
+    evidenceVerdict,
+    recordIfActive,
+    dispatchGate,
+  });
+
+  // ── 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 2 helper — run the serial gates in declared order, stopping at the
+ * first failure. Extracted from `runCloseValidation` (Story #4926); the
+ * evidence bookkeeping stays bit-identical to the parallel pass because both
+ * call the same injected `evidenceVerdict` / `recordIfActive` closures.
+ *
+ * Mutates the caller's `failed` / `skipped` accumulators — the same arrays
+ * Phase 1 already wrote into, so the returned verdict stays one list.
+ *
+ * @param {Array<object>} serial
+ * @param {object} deps
+ * @returns {Promise<void>}
+ */
+async function runSerialGates(
+  serial,
+  {
+    spawnCwd,
+    log,
+    failed,
+    skipped,
+    evidenceActive,
+    evidenceClock,
+    evidenceVerdict,
+    recordIfActive,
+    dispatchGate,
+  },
+) {
+  const failGate = (gate, status, message) => {
+    failed.push({ gate, status, cwd: spawnCwd });
+    log(message);
+    if (gate.hint) log(`[close-validation]   hint: ${gate.hint}`);
+  };
   for (const gate of serial) {
     let execution;
     try {
       execution = applyChangedFileScope({ gate, spawnCwd, log });
     } catch (err) {
-      failed.push({ gate, status: 1, cwd: spawnCwd });
-      log(
+      failGate(
+        gate,
+        1,
         `[close-validation] ✖ ${gate.name} failed to resolve changed-file scope: ${err?.message ?? err}`,
       );
-      if (gate.hint) log(`[close-validation]   hint: ${gate.hint}`);
-      break;
+      return;
     }
     if (execution.skip) {
       skipped.push({ gate, reason: 'no-changed-files' });
@@ -349,12 +411,12 @@ export async function runCloseValidation({
       tolerateNoFilesProcessed: execution.tolerateNoFilesProcessed,
     });
     if (result.status !== 0) {
-      failed.push({ gate, status: result.status, cwd: spawnCwd });
-      log(
+      failGate(
+        gate,
+        result.status,
         `[close-validation] ✖ ${gate.name} failed (exit ${result.status}) in ${spawnCwd}`,
       );
-      if (gate.hint) log(`[close-validation]   hint: ${gate.hint}`);
-      break;
+      return;
     }
     log(`[close-validation] ✓ ${gate.name}`);
     recordIfActive(
@@ -363,23 +425,6 @@ export async function runCloseValidation({
       evidenceActive ? evidenceClock() - startedAt : 0,
     );
   }
-
-  // ── 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 };
 }
 
 /**

package/.agents/scripts/lib/crap-engine.js

@@ -1,5 +1,6 @@
 import escomplex from 'typhonjs-escomplex';
 import { coverageForMethodInEntry } from './coverage-utils.js';
+import { deriveMethodIdentities } from './crap-method-identity.js';
 
 /**
  * The two line coordinate systems a CRAP row's `startLine` can be expressed
@@ -47,6 +48,7 @@ export const COORDINATE_TRANSPILED = 'transpiled';
  * @param {((line: number) => number|null)|null} [mapLine]
  * @returns {Array<{
  *   method: string,
+ *   anonymous: boolean,
  *   startLine: number,
  *   cyclomatic: number,
  *   coverage: number|null,
@@ -78,8 +80,14 @@ function resolveCoordinate(rawStartLine, mapLine) {
 
 export function methodRowsFromReport(report, coverageForFile, mapLine = null) {
   const methods = report?.methods ?? [];
+  // Identities are derived over the WHOLE method list, before any row is
+  // skipped, and read back by index (Story #4969). Deriving them from the
+  // surviving rows instead would let an unscorable method's absence shift its
+  // siblings' ordinals — reintroducing, through the back door, exactly the
+  // position dependence this replaces.
+  const identities = deriveMethodIdentities(methods);
   const rows = [];
-  for (const m of methods) {
+  for (const [i, m] of methods.entries()) {
     const rawStartLine = m?.lineStart;
     if (typeof rawStartLine !== 'number') continue;
     const { startLine, coordinateSystem } = resolveCoordinate(
@@ -93,7 +101,7 @@ export function methodRowsFromReport(report, coverageForFile, mapLine = null) {
         : null;
     const crap = coverage === null ? null : crapFormula(cyclomatic, coverage);
     rows.push({
-      method: m.name,
+      ...identities[i],
       startLine,
       cyclomatic,
       coverage,
@@ -132,10 +140,16 @@ export function methodRowsFromReport(report, coverageForFile, mapLine = null) {
  * so `requireCoverage: false` keeps meaning "score untested code" whenever a
  * real coverage run stands behind the verdict.
  *
- * `resolvedMethods` / `totalMethods` count the *join*, not the fill: a
- * method scored 0% because its coverage was unresolved counts as
- * unresolved. That is what makes them usable as a health signal for the
- * updater's fail-closed resolution-rate floor.
+ * **Unjoinable is not untested (Story #4901).** Both policies above are about
+ * a method whose coverage is *absent*; neither is about one whose coverage
+ * could not be **joined**. A transpiled `startLine` is the latter — not in
+ * the coordinate space the `fnMap` or the baseline is keyed against — so 0%
+ * is not a measurement but a number invented for it, and `crapFormula(c, 0)`
+ * is the maximal `c² + c`. Excluded under **either** policy, and counted.
+ *
+ * `resolvedMethods` / `totalMethods` count the *join*, not the fill, which is
+ * what makes them a health signal for the updater's fail-closed
+ * resolution-rate floor — so the exclusion is applied *after* both counters.
  *
  * @param {Array<object>} rawRows Rows from `methodRowsFromReport`.
  * @param {{requireCoverage?: boolean, coverageAvailable?: boolean}} [opts]
@@ -158,21 +172,25 @@ export function finalizeMethodRows(
     totalMethods += 1;
     const unresolved = mr.crap === null || mr.coverage === null;
     if (!unresolved) resolvedMethods += 1;
-    if (unresolved && (requireCoverage || !coverageAvailable)) {
+    // Unjoinable is not untested (Story #4901) — see the block comment above.
+    if (
+      mr.coordinateSystem === COORDINATE_TRANSPILED ||
+      (unresolved && (requireCoverage || !coverageAvailable))
+    ) {
       skippedMethodsNoCoverage += 1;
       continue;
     }
     const coverage = unresolved ? 0 : mr.coverage;
     const crap = unresolved ? crapFormula(mr.cyclomatic, 0) : mr.crap;
+    // Everything the scan decided is carried forward; this step overrides only
+    // what its own policy resolves. Spreading rather than re-listing each field
+    // is why the row's identity marker (Story #4969) and its provenance
+    // (Story #4866) survive the step without a line each to remember them —
+    // a hand-rebuilt row is how a marker silently stops reaching the baseline.
     rows.push({
-      method: mr.method,
-      startLine: mr.startLine,
-      cyclomatic: mr.cyclomatic,
+      ...mr,
       coverage,
       crap,
-      // Provenance survives the policy step (Story #4866): a row scored 0%
-      // under `requireCoverage: false` may still be carrying a transpiled
-      // coordinate, and the compare needs to know that before it keys on it.
       coordinateSystem: mr.coordinateSystem ?? COORDINATE_ORIGINAL,
     });
   }
@@ -203,6 +221,7 @@ export function finalizeMethodRows(
  *   original line resolver; see `methodRowsFromReport`.
  * @returns {Array<{
  *   method: string,
+ *   anonymous: boolean,
  *   startLine: number,
  *   cyclomatic: number,
  *   coverage: number|null,

package/.agents/scripts/lib/crap-method-identity.js

@@ -0,0 +1,153 @@
+/**
+ * crap-method-identity.js — order-independent identity for the methods an
+ * escomplex report describes (Story #4969).
+ *
+ * Split out of `crap-engine.js` deliberately. That module is the CRAP scoring
+ * kernel — parse, remap a line, join coverage, apply the formula — and naming
+ * a method is a different question from scoring one: it reads the shape of the
+ * scope tree and nothing about coverage or complexity. Keeping the walker here
+ * leaves the kernel's contract ("pure, no I/O, one method in, one score out")
+ * legible instead of half-buried under a tree traversal.
+ */
+
+/**
+ * The label `typhonjs-escomplex-commons` gives a function it cannot name
+ * (Story #4969).
+ *
+ * The `N` is a per-module counter incremented during the AST walk, so it
+ * numbers a function by its *position among its anonymous siblings* rather
+ * than by anything about the function itself. Inserting or deleting one
+ * anonymous function renumbers every later one in the file — and 34.6% of this
+ * repository's CRAP rows were keyed on exactly that. See
+ * `deriveMethodIdentities` for what replaces it.
+ */
+const ESCOMPLEX_ANON_LABEL_RE = /^<anon method-\d+>$/;
+
+/**
+ * True for a `method` value that is a derived anonymous identity rather than a
+ * name the source actually carries — either this module's `<anon …>` identity
+ * or escomplex's superseded ordinal label.
+ *
+ * @param {unknown} method
+ * @returns {boolean}
+ */
+export function isAnonymousMethodLabel(method) {
+  return typeof method === 'string' && method.startsWith('<anon ');
+}
+
+/**
+ * Coerce a method's escomplex line span into a usable numeric pair. A method
+ * missing either bound still has to take a deterministic place in the scope
+ * tree, so it collapses to a zero-width span rather than being dropped: an
+ * identity that varies with how the parser failed would be worse than one that
+ * is merely coarse.
+ *
+ * @param {{lineStart?: unknown, lineEnd?: unknown}} m
+ * @returns {{lineStart: number, lineEnd: number}}
+ */
+function spanOf(m) {
+  const lineStart = Number.isFinite(m?.lineStart) ? m.lineStart : 0;
+  const lineEnd = Number.isFinite(m?.lineEnd) ? m.lineEnd : lineStart;
+  return { lineStart, lineEnd: Math.max(lineStart, lineEnd) };
+}
+
+/**
+ * Give every method in an escomplex report an identity that does not depend on
+ * how many anonymous functions happen to precede it (Story #4969).
+ *
+ * **Named methods are untouched** — their identity is the name escomplex
+ * reported, exactly as before, so no named row is re-keyed by this change.
+ *
+ * **An anonymous method is identified by where it sits, not by when it was
+ * counted.** The identity is `<anon {scope path}>`, where the path is the
+ * chain of enclosing methods from the module down to the method itself. Each
+ * link contributes a name if it has one, otherwise its parameter list plus an
+ * ordinal among the siblings that share *that exact parent and that exact
+ * parameter list*:
+ *
+ * ```text
+ *   <anon (p)#0>                                        module-scope, first (p) arrow
+ *   <anon buildDefaultCrapScorer/(files,opts)#0>        inside a named function
+ *   <anon buildDefaultCrapScorer/(files,opts)#0/(r)#0>  inside that one
+ * ```
+ *
+ * **Why the parameter list and not the body.** The identity has to survive an
+ * edit *to* the method — a method that gains a branch must still be recognised
+ * as the same method, or a genuine complexity regression would read as a brand
+ * new function and score against the new-method ceiling instead of its own
+ * baseline. That rules out anything derived from the body: a source or
+ * normalized-AST hash re-keys the row on the very edit the gate exists to
+ * catch. A parameter list is stable across the edits CRAP measures, and it
+ * partitions same-scope siblings finely enough that the residual ordinal is
+ * almost always `#0`.
+ *
+ * **The residual.** Within one parent *and* one parameter list, siblings are
+ * still told apart by source order, so inserting a same-signature sibling
+ * *before* an existing one still shifts it. That residual is irreducible:
+ * anything that distinguishes two same-scope, same-signature functions has to
+ * read their bodies, and reading their bodies re-keys them on every edit. The
+ * blast radius drops from "every anonymous function in the file" to "the
+ * same-signature siblings of one scope".
+ *
+ * Emission order is load-bearing and guaranteed: escomplex walks the AST
+ * pre-order, so a method's ancestors are always emitted before it. That lets a
+ * single forward pass with an open-ancestor stack resolve every parent in
+ * O(n), and it makes the innermost enclosing method the most recent one still
+ * open.
+ *
+ * @param {Array<object>} methods `report.methods` from escomplex.
+ * @returns {Array<{method: string, anonymous: boolean}>} One entry per input
+ *   method, index-aligned with `methods` and spreadable straight onto a row.
+ *   The scope path itself stays internal — only the identity leaves.
+ */
+export function deriveMethodIdentities(methods) {
+  const identities = [];
+  /** @type {Array<{lineEnd: number, scopePath: string}>} */
+  const openAncestors = [];
+  /** Sibling counts keyed by `parent scope path` + `parameter list`. */
+  const ordinals = new Map();
+
+  for (const m of methods ?? []) {
+    const { lineStart, lineEnd } = spanOf(m);
+    // Close every ancestor whose span has ended before this method begins.
+    while (
+      openAncestors.length > 0 &&
+      openAncestors[openAncestors.length - 1].lineEnd < lineStart
+    ) {
+      openAncestors.pop();
+    }
+    const parentPath =
+      openAncestors.length > 0
+        ? openAncestors[openAncestors.length - 1].scopePath
+        : '';
+
+    const name = typeof m?.name === 'string' ? m.name : '';
+    let segment;
+    let anonymous;
+    if (name === '' || ESCOMPLEX_ANON_LABEL_RE.test(name)) {
+      const params = Array.isArray(m?.paramNames) ? m.paramNames : [];
+      const signature = `(${params.join(',')})`;
+      // NUL separates the two halves because it is the one character a scope
+      // path can never contain — a printable delimiter could be produced by a
+      // parameter name and silently merge two distinct buckets. Spelled as an
+      // escape: a literal NUL byte would make this file binary to git and grep.
+      const bucket = `${parentPath}\u0000${signature}`;
+      const ordinal = ordinals.get(bucket) ?? 0;
+      ordinals.set(bucket, ordinal + 1);
+      segment = `${signature}#${ordinal}`;
+      anonymous = true;
+    } else {
+      segment = name;
+      anonymous = false;
+    }
+
+    const scopePath = parentPath === '' ? segment : `${parentPath}/${segment}`;
+    identities.push({
+      method: anonymous ? `<anon ${scopePath}>` : name,
+      anonymous,
+    });
+    openAncestors.push({ lineEnd, scopePath });
+  }
+
+  return identities;
+}

package/.agents/scripts/lib/crap-utils.js

@@ -139,6 +139,12 @@ function projectCrapEnvelopeToLegacy(parsed) {
       ...(row.coordinateSystem === undefined
         ? {}
         : { coordinateSystem: row.coordinateSystem }),
+      // Story #4969, same reason as the stamps above: `anonymous` is a
+      // BASELINE fact. Dropping it here left every re-keyed row looking like
+      // an unmarked anonymous one, which is precisely the shape the
+      // `anon-identity-unstamped` axis fails closed — the projection would
+      // have manufactured the very defect the axis exists to catch.
+      ...(row.anonymous === undefined ? {} : { anonymous: row.anonymous }),
     })),
   };
 }
@@ -215,6 +221,7 @@ export function buildBaselineEnvelope({
       file: r.file,
       method: r.method,
       startLine: r.startLine,
+      ...(r.anonymous === undefined ? {} : { anonymous: r.anonymous }),
     })),
     tsTranspilerVersion,
   };
@@ -501,6 +508,9 @@ export async function scanAndScore({
       rows.push({
         file: item.relPath,
         method: mr.method,
+        // Story #4969: `method` may be a derived anonymous identity; the flag
+        // is what lets the persisted row say so.
+        anonymous: mr.anonymous === true,
         startLine: mr.startLine,
         cyclomatic: mr.cyclomatic,
         coverage: mr.coverage,
@@ -844,6 +854,9 @@ export async function scanAndScoreCombined({
       crapRows.push({
         file: item.relPath,
         method: mr.method,
+        // Story #4969: `method` may be a derived anonymous identity; the flag
+        // is what lets the persisted row say so.
+        anonymous: mr.anonymous === true,
         startLine: mr.startLine,
         cyclomatic: mr.cyclomatic,
         coverage: mr.coverage,

package/.agents/scripts/lib/cyclomatic-ceiling.js

@@ -0,0 +1,265 @@
+/**
+ * cyclomatic-ceiling.js — the enforcing core behind
+ * `delivery.quality.codingGuardrails.cyclomaticMustFix` (Story #4923).
+ *
+ * The two `codingGuardrails` cyclomatic knobs shipped schema-validated,
+ * bootstrap-defaulted and resolver-resolved, and were then read by nothing:
+ * `cyclomaticMustFix` had no consumer at all, and `cyclomaticFlag` was
+ * shadowed by a hardcoded `8` in a `quality-preview` display column. A ceiling
+ * nothing enforces is worse than no ceiling, because the workflow docs promise
+ * the merge will be refused.
+ *
+ * This module is that enforcement, shaped as a **ratchet** rather than a
+ * cliff. The repository already carries dozens of functions above the
+ * must-fix ceiling; failing every one of them at once would have made the
+ * gate un-landable and it would have been disabled the same day. So the
+ * committed `baselines/cyclomatic.json` records the existing breaches per
+ * file, and the gate fails only when a change **adds** an over-ceiling
+ * function to a file that had none, adds one **beyond** that file's recorded
+ * count, or pushes a file's worst function **higher** than recorded. Burning
+ * the recorded breaches down is a separate, always-permitted motion — a
+ * shrinking baseline is the success signal.
+ *
+ * Scope: the module walks the `maintainability` gate's `targetDirs` /
+ * `ignoreGlobs`. Both instruments read the same coverage-free escomplex
+ * surface, so re-declaring the scope under `codingGuardrails` would have
+ * added two config keys whose only correct value is "whatever maintainability
+ * says".
+ *
+ * @module lib/cyclomatic-ceiling
+ */
+
+import path from 'node:path';
+import { calculateReportForFile } from './maintainability-engine.js';
+import { isIgnoredByGlobs, scanDirectory } from './maintainability-utils.js';
+
+/** Default location of the committed breach baseline. */
+export const DEFAULT_CYCLOMATIC_BASELINE = 'baselines/cyclomatic.json';
+
+/** Baseline `$schema` marker, matching the sibling ratchet baselines. */
+const CYCLOMATIC_BASELINE_SCHEMA =
+  'https://mandrel.dev/baselines/cyclomatic.schema.json';
+
+/**
+ * Resolve the enforcement policy from a resolved `delivery.quality` block.
+ *
+ * `mustFix` and `flag` come straight from `resolveCodingGuardrails`, so a
+ * consumer that tunes either knob tunes this gate — which is the whole point
+ * of the Story. `targetDirs` / `ignoreGlobs` are borrowed from the
+ * maintainability gate (see the module note).
+ *
+ * @param {object | null | undefined} quality resolved `delivery.quality`
+ * @returns {{ mustFix: number, flag: number, targetDirs: string[], ignoreGlobs: string[] }}
+ */
+export function resolveCyclomaticPolicy(quality) {
+  const guardrails = quality?.codingGuardrails ?? {};
+  const mi = quality?.maintainability ?? {};
+  return {
+    mustFix: Number(guardrails.cyclomaticMustFix ?? 12),
+    flag: Number(guardrails.cyclomaticFlag ?? 8),
+    targetDirs: Array.isArray(mi.targetDirs) ? mi.targetDirs : [],
+    ignoreGlobs: Array.isArray(mi.ignoreGlobs) ? mi.ignoreGlobs : [],
+  };
+}
+
+/**
+ * Reduce one file's escomplex method list to a breach row, or `null` when the
+ * file carries no function above `ceiling`.
+ *
+ * Pure. Module-private: tests reach it through `scanCyclomatic`'s `scoreFile`
+ * seam, which keeps the row math exercised without adding an export whose only
+ * importer is a test (the `--production` dead-export pass discounts those).
+ *
+ * @param {string} file repo-relative POSIX path
+ * @param {Array<{ cyclomatic?: number }>} methods
+ * @param {number} ceiling
+ * @returns {{ file: string, methodsAboveCeiling: number, maxCyclomatic: number } | null}
+ */
+function breachRowFor(file, methods, ceiling) {
+  let count = 0;
+  let max = 0;
+  for (const method of methods ?? []) {
+    const c = Number(method?.cyclomatic ?? 0);
+    if (!Number.isFinite(c)) continue;
+    if (c > ceiling) count += 1;
+    if (c > max) max = c;
+  }
+  return count === 0
+    ? null
+    : { file, methodsAboveCeiling: count, maxCyclomatic: max };
+}
+
+/**
+ * Walk the configured scope and score every file, returning the breach rows
+ * sorted by path.
+ *
+ * `scoreFile` is a seam so tests can drive the reduction without the kernel;
+ * production callers omit it.
+ *
+ * @param {{
+ *   targetDirs: string[],
+ *   ignoreGlobs?: string[],
+ *   ceiling: number,
+ *   cwd?: string,
+ *   scoreFile?: (absPath: string) => { methods?: Array<{ cyclomatic?: number }>, parseError?: boolean },
+ * }} args
+ * @returns {{ rows: Array<object>, scannedFiles: number, parseErrors: number }}
+ */
+export function scanCyclomatic({
+  targetDirs,
+  ignoreGlobs = [],
+  ceiling,
+  cwd = process.cwd(),
+  scoreFile = calculateReportForFile,
+}) {
+  const files = [];
+  for (const dir of targetDirs ?? []) {
+    const abs = path.isAbsolute(dir) ? dir : path.resolve(cwd, dir);
+    scanDirectory(abs, files, { cwd, ignoreGlobs });
+  }
+  files.sort();
+  const rows = [];
+  let parseErrors = 0;
+  for (const abs of files) {
+    if (isIgnoredByGlobs(abs, ignoreGlobs, cwd)) continue;
+    const report = scoreFile(abs);
+    if (!report || report.parseError) {
+      parseErrors += 1;
+      continue;
+    }
+    const rel = path.relative(cwd, abs).split(path.sep).join('/');
+    const row = breachRowFor(rel, report.methods, ceiling);
+    if (row) rows.push(row);
+  }
+  rows.sort((a, b) => a.file.localeCompare(b.file));
+  return { rows, scannedFiles: files.length, parseErrors };
+}
+
+/**
+ * Diff current breach rows against the committed baseline.
+ *
+ * Four buckets, only the first two of which fail the gate:
+ *
+ *   - `added`    — a file whose over-ceiling function count rose (including
+ *                  0 → 1, i.e. a brand-new breach in new or changed code).
+ *   - `worsened` — a file whose worst function got worse than recorded.
+ *   - `removed`  — a file that no longer breaches at all.
+ *   - `improved` — a file that breaches less than recorded.
+ *
+ * Pure; identity is the repo-relative file path.
+ *
+ * @param {Array<{file: string, methodsAboveCeiling: number, maxCyclomatic: number}>} baselineRows
+ * @param {Array<{file: string, methodsAboveCeiling: number, maxCyclomatic: number}>} currentRows
+ * @returns {{ added: Array<object>, worsened: Array<object>, removed: Array<object>, improved: Array<object> }}
+ */
+export function diffCyclomaticRows(baselineRows, currentRows) {
+  const base = new Map(
+    (baselineRows ?? [])
+      .filter((r) => typeof r?.file === 'string')
+      .map((r) => [r.file, r]),
+  );
+  const added = [];
+  const worsened = [];
+  const improved = [];
+  const seen = new Set();
+  for (const row of currentRows ?? []) {
+    if (typeof row?.file !== 'string') continue;
+    seen.add(row.file);
+    const prior = base.get(row.file);
+    const priorCount = Number(prior?.methodsAboveCeiling ?? 0);
+    const priorMax = Number(prior?.maxCyclomatic ?? 0);
+    if (row.methodsAboveCeiling > priorCount) {
+      added.push({ ...row, baselineCount: priorCount });
+      continue;
+    }
+    if (row.maxCyclomatic > priorMax) {
+      worsened.push({ ...row, baselineMax: priorMax });
+      continue;
+    }
+    if (row.methodsAboveCeiling < priorCount || row.maxCyclomatic < priorMax) {
+      improved.push({
+        ...row,
+        baselineCount: priorCount,
+        baselineMax: priorMax,
+      });
+    }
+  }
+  const removed = (baselineRows ?? []).filter(
+    (r) => typeof r?.file === 'string' && !seen.has(r.file),
+  );
+  const byFile = (a, b) => a.file.localeCompare(b.file);
+  return {
+    added: added.sort(byFile),
+    worsened: worsened.sort(byFile),
+    removed: removed.sort(byFile),
+    improved: improved.sort(byFile),
+  };
+}
+
+/**
+ * Assemble the committed baseline envelope. The rollup is deliberately
+ * derived, never hand-written: a zero-row baseline here reports zero breaches
+ * because the repository has none, not because nobody produced it.
+ *
+ * @param {{ rows: Array<object>, ceiling: number, generatedAt?: string }} args
+ * @returns {object}
+ */
+export function buildCyclomaticEnvelope({ rows, ceiling, generatedAt }) {
+  const safeRows = rows ?? [];
+  let methods = 0;
+  let max = 0;
+  for (const row of safeRows) {
+    methods += Number(row.methodsAboveCeiling ?? 0);
+    if (Number(row.maxCyclomatic ?? 0) > max) max = Number(row.maxCyclomatic);
+  }
+  return {
+    $schema: CYCLOMATIC_BASELINE_SCHEMA,
+    generatedAt: generatedAt ?? new Date().toISOString(),
+    ceiling,
+    rollup: {
+      '*': {
+        filesAboveCeiling: safeRows.length,
+        methodsAboveCeiling: methods,
+        maxCyclomatic: max,
+      },
+    },
+    rows: safeRows,
+  };
+}
+
+/**
+ * Render the human-readable diff. Emits a summary line even on a clean run so
+ * operators see the "no drift" signal rather than silence.
+ *
+ * @param {{ added: Array, worsened: Array, removed: Array, improved: Array }} diff
+ * @param {number} ceiling
+ * @returns {string}
+ */
+export function renderCyclomaticDiff(diff, ceiling) {
+  const lines = [];
+  for (const r of diff.added) {
+    lines.push(
+      `+ ${r.file}: ${r.methodsAboveCeiling} function(s) over c=${ceiling} (recorded ${r.baselineCount}), worst c=${r.maxCyclomatic}`,
+    );
+  }
+  for (const r of diff.worsened) {
+    lines.push(
+      `! ${r.file}: worst function c=${r.maxCyclomatic} (recorded ${r.baselineMax})`,
+    );
+  }
+  for (const r of diff.improved) {
+    lines.push(
+      `~ ${r.file}: ${r.methodsAboveCeiling} over c=${ceiling} (recorded ${r.baselineCount}), worst c=${r.maxCyclomatic} (recorded ${r.baselineMax})`,
+    );
+  }
+  for (const r of diff.removed) {
+    lines.push(`- ${r.file}: no longer over c=${ceiling}`);
+  }
+  const failing = diff.added.length + diff.worsened.length;
+  lines.push(
+    `[cyclomatic] ceiling=${ceiling} added=${diff.added.length} worsened=${diff.worsened.length} improved=${diff.improved.length} removed=${diff.removed.length} ${
+      failing > 0 ? '(gate fail)' : '(ok)'
+    }`,
+  );
+  return lines.join('\n');
+}

package/.agents/scripts/lib/feedback-loop/audit-results-graduator.js

@@ -333,5 +333,3 @@ export async function graduateAuditResults(opts = {}) {
     },
   });
 }
-
-export default graduateAuditResults;