mandrel 1.58.0 → 1.59.0

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

@@ -3,19 +3,22 @@
  * (Story #1891). Row shape: `{ route, performance, accessibility,
  * bestPractices, seo }`. The key field is `route` (a path-like string that
  * still passes the path-canon checks for absolute / `..` rejection).
+ *
+ * Higher score = better. New routes inherit a base of 100 for each axis
+ * (so lower scores register as regressions — a new route must meet the
+ * bar); dropped routes inherit a head of 100 (so a higher base registers
+ * as an improvement). Unlike the file-derived kinds, compare emits no
+ * `additions` bucket. Scaffold is generated by `makeBaselineKind`
+ * (Story #3983).
  */
 
-import { componentMatches } from '../component-matcher.js';
 import { canonicalise } from '../path-canon.js';
-import { mergeRowsByScope } from '../scope.js';
+import { makeBaselineKind } from './kind-factory.js';
 
 export const name = 'lighthouse';
 export const keyField = 'route';
-const KERNEL_VERSION = '1.0.0';
 
-export function kernelVersion() {
-  return KERNEL_VERSION;
-}
+const LH_AXES = ['performance', 'accessibility', 'bestPractices', 'seo'];
 
 function canonRoute(route) {
   // Routes look like `/`, `/dashboard`, or `pricing` — strip the leading
@@ -36,75 +39,24 @@ export function projectRow(row) {
   };
 }
 
-export function sortRows(rows) {
-  return [...rows].sort((a, b) => a.route.localeCompare(b.route));
+function meanOf(rows, axis) {
+  let sum = 0;
+  for (const r of rows) sum += r[axis] ?? 0;
+  return Number((sum / rows.length).toFixed(2));
 }
 
 function aggregate(rows) {
   if (!rows || rows.length === 0) {
     return { performance: 0, accessibility: 0, bestPractices: 0, seo: 0 };
   }
-  const sum = { performance: 0, accessibility: 0, bestPractices: 0, seo: 0 };
-  for (const r of rows) {
-    sum.performance += r.performance ?? 0;
-    sum.accessibility += r.accessibility ?? 0;
-    sum.bestPractices += r.bestPractices ?? 0;
-    sum.seo += r.seo ?? 0;
-  }
   return {
-    performance: Number((sum.performance / rows.length).toFixed(2)),
-    accessibility: Number((sum.accessibility / rows.length).toFixed(2)),
-    bestPractices: Number((sum.bestPractices / rows.length).toFixed(2)),
-    seo: Number((sum.seo / rows.length).toFixed(2)),
+    performance: meanOf(rows, 'performance'),
+    accessibility: meanOf(rows, 'accessibility'),
+    bestPractices: meanOf(rows, 'bestPractices'),
+    seo: meanOf(rows, 'seo'),
   };
 }
 
-export function rollup(rows, components = []) {
-  const out = { '*': aggregate(rows) };
-  for (const c of components ?? []) {
-    const matched = (rows ?? []).filter((r) => componentMatches(c, r.route));
-    out[c.name] = aggregate(matched);
-  }
-  return out;
-}
-
-/**
- * Pure compare(head, base) for the lighthouse kind. Diffs rows by `route`.
- *
- * Higher score = better. A row regresses when any of performance,
- * accessibility, bestPractices, or seo decreases vs the base. An
- * improvement requires at least one score to increase and none to
- * decrease. Otherwise the row is unchanged. New routes inherit a base of
- * 100 for each axis (so lower scores register as regressions); dropped
- * routes inherit a head of 100 (so a higher base registers as an
- * improvement).
- *
- * No I/O. No process exit. No friction emission.
- */
-const LH_AXES = ['performance', 'accessibility', 'bestPractices', 'seo'];
-
-export function compare(head, base) {
-  const headRows = Array.isArray(head?.rows) ? head.rows : [];
-  const baseRows = Array.isArray(base?.rows) ? base.rows : [];
-  const baseByKey = new Map();
-  for (const r of baseRows) baseByKey.set(r.route, r);
-  const seen = new Set();
-  const regressions = [];
-  const improvements = [];
-  const unchanged = [];
-  for (const h of headRows) {
-    seen.add(h.route);
-    const b = baseByKey.get(h.route) ?? perfectLighthouseRow(h.route);
-    classify(regressions, improvements, unchanged, h.route, h, b);
-  }
-  for (const b of baseRows) {
-    if (seen.has(b.route)) continue;
-    const h = perfectLighthouseRow(b.route);
-    classify(regressions, improvements, unchanged, b.route, h, b);
-  }
-  return { regressions, improvements, unchanged };
-}
-
 function perfectLighthouseRow(route) {
   return {
     route,
@@ -115,71 +67,20 @@ function perfectLighthouseRow(route) {
   };
 }
 
-function classify(regressions, improvements, unchanged, key, head, base) {
-  let down = false;
-  let up = false;
-  for (const axis of LH_AXES) {
-    const delta = (head[axis] ?? 0) - (base[axis] ?? 0);
-    if (delta < 0) down = true;
-    else if (delta > 0) up = true;
-  }
-  if (down) regressions.push({ key, head, base });
-  else if (up) improvements.push({ key, head, base });
-  else unchanged.push({ key, head, base });
-}
-
-/**
- * Pure stabilizer for s-stability-epsilon (Story #1964). Lighthouse rows
- * match by `route`. The metric is the maximum absolute delta across the
- * four scoring axes. Sub-epsilon deltas resolve to the prior bytes;
- * missing-prior rows fall through.
- *
- * @param {Array<{route: string, performance: number, accessibility: number, bestPractices: number, seo: number}>} prior
- * @param {Array<{route: string, performance: number, accessibility: number, bestPractices: number, seo: number}>} regenerated
- * @param {number} epsilon non-negative absolute tolerance per axis
- * @returns {Array<object>}
- */
-export function applyEpsilon(prior, regenerated, epsilon) {
-  const priorRows = Array.isArray(prior) ? prior : [];
-  const regenRows = Array.isArray(regenerated) ? regenerated : [];
-  const eps = Number.isFinite(epsilon) && epsilon >= 0 ? epsilon : 0;
-  const priorByKey = new Map();
-  for (const r of priorRows) priorByKey.set(r.route, r);
-  return regenRows.map((row) => {
-    const p = priorByKey.get(row.route);
-    if (!p) return row;
-    let maxAxisDelta = 0;
-    for (const axis of LH_AXES) {
-      const d = Math.abs((row[axis] ?? 0) - (p[axis] ?? 0));
-      if (d > maxAxisDelta) maxAxisDelta = d;
-    }
-    return maxAxisDelta <= eps ? p : row;
-  });
-}
-
-/**
- * Pure scope-aware merge for s-diff-scoped-writes (Story #1974). Lighthouse
- * rows match by `route`. In diff mode, rows whose `route` is OUTSIDE
- * `scope.files` are preserved from `prior` verbatim; in-scope rows come
- * from `regenerated`. In full mode (or no scope), regenerated wins
- * everywhere.
- *
- * Note: lighthouse routes are not file paths, so the scope filter only
- * narrows naturally when callers seed `scope.files` with route strings.
- * Auto-refresh callers using a Story file diff will see no in-scope rows
- * and therefore preserve every prior row — which is the safe default for
- * a baseline that is not file-derived.
- *
- * @param {Array<{route: string, performance: number, accessibility: number, bestPractices: number, seo: number}>} prior
- * @param {Array<{route: string, performance: number, accessibility: number, bestPractices: number, seo: number}>} regenerated
- * @param {{mode: 'full'|'diff', files: Set<string>}|null|undefined} scope
- * @returns {Array<object>}
- */
-export function mergeRows(prior, regenerated, scope) {
-  return mergeRowsByScope({
-    prior,
-    regenerated,
-    scope,
-    scopeKey: (row) => row.route,
-  });
-}
+export const {
+  kernelVersion,
+  sortRows,
+  rollup,
+  compare,
+  applyEpsilon,
+  mergeRows,
+} = makeBaselineKind({
+  keyField,
+  kernelVersion: '1.0.0',
+  axes: LH_AXES,
+  betterWhen: 'higher',
+  aggregate,
+  missingBasePolicy: 'perfect',
+  removedRowPolicy: { kind: 'perfect-head' },
+  perfectRow: perfectLighthouseRow,
+});

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

@@ -9,15 +9,22 @@
  * MI is computed by the in-repo `escomplex-engine` kernel — same upstream
  * dependency family as CRAP — so the kernel version tracks
  * `typhonjs-escomplex` too.
+ *
+ * Higher MI = better. New paths land in the `additions` bucket
+ * (Story #2012 — new files MUST NOT register as regressions); removed
+ * paths count as improvements when their MI was non-perfect — the file is
+ * gone, so its prior debt is gone too. Scaffold (sortRows / rollup /
+ * compare / applyEpsilon / mergeRows) is generated by `makeBaselineKind`
+ * (Story #3983).
  */
 
 import { readBaselineAtRef } from '../../baseline-loader.js';
 import { loadBaseline } from '../../gates/baseline-store.js';
-import { getBaseline } from '../../maintainability-utils.js';
-import { componentMatches } from '../component-matcher.js';
+import { getBaseline } from '../maintainability-baseline-io.js';
 import { canonicalise } from '../path-canon.js';
-import { mergeRowsByScope } from '../scope.js';
+import { percentile } from './_shared-metric.js';
 import { kernelVersion as crapKernelVersion } from './crap.js';
+import { makeBaselineKind } from './kind-factory.js';
 
 export const name = 'maintainability';
 export const keyField = 'path';
@@ -111,12 +118,6 @@ export function filterExcludedRows(rows) {
   );
 }
 
-export function kernelVersion() {
-  // MI and CRAP share the escomplex kernel — pin them together so a drift
-  // in either always invalidates both baselines.
-  return crapKernelVersion();
-}
-
 export function projectRow(row) {
   return {
     path: canonicalise(row.path),
@@ -124,10 +125,6 @@ export function projectRow(row) {
   };
 }
 
-export function sortRows(rows) {
-  return [...rows].sort((a, b) => a.path.localeCompare(b.path));
-}
-
 function aggregate(rows) {
   if (!rows || rows.length === 0) return { min: 0, p50: 0, p95: 0 };
   const sorted = [...rows].map((r) => r.mi).sort((a, b) => a - b);
@@ -138,117 +135,27 @@ function aggregate(rows) {
   };
 }
 
-function percentile(sortedValues, p) {
-  if (sortedValues.length === 0) return 0;
-  const idx = Math.min(
-    sortedValues.length - 1,
-    Math.max(0, Math.ceil((p / 100) * sortedValues.length) - 1),
-  );
-  return sortedValues[idx];
-}
-
-export function rollup(rows, components = []) {
-  const out = { '*': aggregate(rows) };
-  for (const c of components ?? []) {
-    const matched = (rows ?? []).filter((r) => componentMatches(c, r.path));
-    out[c.name] = aggregate(matched);
-  }
-  return out;
-}
-
-/**
- * Pure compare(head, base) for the maintainability kind. Diffs rows by
- * `path`. Higher MI = better — a row regresses when its mi drops vs
- * base, improves when it rises, unchanged when equal. New paths (head
- * has a row that base lacks) land in the `additions` bucket; absolute-
- * floor enforcement is the unified `check-baselines` gate's job and runs
- * independently. Removed paths (base has a row that head dropped) count
- * as improvements when their MI was non-perfect; the file is gone, so
- * its prior debt is gone too.
- *
- * Story #2012 — new files MUST NOT register as regressions. The prior
- * behaviour treated missing-in-base as base.mi = 100 and any real-world
- * MI under 100 (i.e., almost every file) flipped to a regression.
- *
- * No I/O. No process exit. No friction emission.
- */
-export function compare(head, base) {
-  const headRows = Array.isArray(head?.rows) ? head.rows : [];
-  const baseRows = Array.isArray(base?.rows) ? base.rows : [];
-  const baseByKey = new Map();
-  for (const r of baseRows) baseByKey.set(r.path, r);
-  const seen = new Set();
-  const regressions = [];
-  const improvements = [];
-  const unchanged = [];
-  const additions = [];
-  for (const h of headRows) {
-    seen.add(h.path);
-    const b = baseByKey.get(h.path);
-    if (!b) {
-      additions.push({ key: h.path, head: h, base: null });
-      continue;
-    }
-    const delta = (h.mi ?? 0) - (b.mi ?? 0);
-    if (delta < 0) regressions.push({ key: h.path, head: h, base: b });
-    else if (delta > 0) improvements.push({ key: h.path, head: h, base: b });
-    else unchanged.push({ key: h.path, head: h, base: b });
-  }
-  for (const b of baseRows) {
-    if (seen.has(b.path)) continue;
-    if ((b.mi ?? 0) < 100) {
-      improvements.push({ key: b.path, head: null, base: b });
-    } else {
-      unchanged.push({ key: b.path, head: null, base: b });
-    }
-  }
-  return { regressions, improvements, unchanged, additions };
-}
-
-/**
- * Pure stabilizer for s-stability-epsilon (Story #1964). Folds sub-epsilon
- * MI deltas back to the prior bytes so env variance does not rewrite the
- * on-disk baseline. Missing-prior rows fall through to the regenerated
- * row.
- *
- * @param {Array<{path: string, mi: number}>} prior
- * @param {Array<{path: string, mi: number}>} regenerated
- * @param {number} epsilon non-negative absolute tolerance on MI
- * @returns {Array<object>}
- */
-export function applyEpsilon(prior, regenerated, epsilon) {
-  const priorRows = Array.isArray(prior) ? prior : [];
-  const regenRows = Array.isArray(regenerated) ? regenerated : [];
-  const eps = Number.isFinite(epsilon) && epsilon >= 0 ? epsilon : 0;
-  const priorByKey = new Map();
-  for (const r of priorRows) priorByKey.set(r.path, r);
-  return regenRows.map((row) => {
-    const p = priorByKey.get(row.path);
-    if (!p) return row;
-    return Math.abs((row.mi ?? 0) - (p.mi ?? 0)) <= eps ? p : row;
-  });
-}
-
-/**
- * Pure scope-aware merge for s-diff-scoped-writes (Story #1974). MI rows
- * match by `path`. In diff mode, rows whose `path` is OUTSIDE
- * `scope.files` are preserved from `prior` verbatim; in-scope rows come
- * from `regenerated`. In full mode (or no scope), regenerated wins
- * everywhere.
- *
- * @param {Array<{path: string, mi: number}>} prior
- * @param {Array<{path: string, mi: number}>} regenerated
- * @param {{mode: 'full'|'diff', files: Set<string>}|null|undefined} scope
- * @returns {Array<object>}
- */
-export function mergeRows(prior, regenerated, scope) {
-  return mergeRowsByScope({
-    prior,
-    regenerated,
-    scope,
-    scopeKey: (row) => row.path,
-  });
-}
+export const {
+  kernelVersion,
+  sortRows,
+  rollup,
+  compare,
+  applyEpsilon,
+  mergeRows,
+} = makeBaselineKind({
+  keyField,
+  // MI and CRAP share the escomplex kernel — pin them together so a drift
+  // in either always invalidates both baselines.
+  kernelVersion: crapKernelVersion,
+  axes: ['mi'],
+  betterWhen: 'higher',
+  aggregate,
+  missingBasePolicy: 'addition',
+  removedRowPolicy: {
+    kind: 'improvement-when',
+    when: (b) => (b.mi ?? 0) < 100,
+  },
+});
 
 // ---------------------------------------------------------------------------
 // CLI-facing pure helpers (Story #1981, Task #1989).

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

@@ -4,19 +4,18 @@
  * carries score/killed/survived/noCoverage. Stryker is the upstream
  * kernel; we pin a static `1.0.0` until a Mandrel-side retrofit story
  * wires the running Stryker version through (#1908).
+ *
+ * Higher score = better. New paths land in the `additions` bucket
+ * (Story #2012 — any real-world score under 100 must never flip to a
+ * regression); removed paths count as improvements when their score was
+ * non-perfect. Scaffold is generated by `makeBaselineKind` (Story #3983).
  */
 
-import { componentMatches } from '../component-matcher.js';
 import { canonicalise } from '../path-canon.js';
-import { mergeRowsByScope } from '../scope.js';
+import { makeBaselineKind } from './kind-factory.js';
 
 export const name = 'mutation';
 export const keyField = 'path';
-const KERNEL_VERSION = '1.0.0';
-
-export function kernelVersion() {
-  return KERNEL_VERSION;
-}
 
 export function projectRow(row) {
   return {
@@ -27,10 +26,6 @@ export function projectRow(row) {
   };
 }
 
-export function sortRows(rows) {
-  return [...rows].sort((a, b) => a.path.localeCompare(b.path));
-}
-
 function aggregate(rows) {
   if (!rows || rows.length === 0) {
     return { score: 0, killed: 0, survived: 0, noCoverage: 0 };
@@ -51,103 +46,22 @@ function aggregate(rows) {
   };
 }
 
-export function rollup(rows, components = []) {
-  const out = { '*': aggregate(rows) };
-  for (const c of components ?? []) {
-    const matched = (rows ?? []).filter((r) => componentMatches(c, r.path));
-    out[c.name] = aggregate(matched);
-  }
-  return out;
-}
-
-/**
- * Pure compare(head, base) for the mutation kind. Diffs rows by `path`.
- * Higher score = better — a row regresses when its score drops vs base,
- * improves when it rises, unchanged when equal. New paths (head has a
- * row that base lacks) land in the `additions` bucket; absolute-floor
- * enforcement is the unified `check-baselines` gate's job and runs
- * independently. Removed paths (base has a row that head dropped) count
- * as improvements when their score was non-perfect.
- *
- * Story #2012 — sibling fix to maintainability.compare. The prior
- * behaviour treated missing-in-base as base.score = 100 and any real-
- * world mutation score under 100 flipped to a regression.
- *
- * No I/O. No process exit. No friction emission.
- */
-export function compare(head, base) {
-  const headRows = Array.isArray(head?.rows) ? head.rows : [];
-  const baseRows = Array.isArray(base?.rows) ? base.rows : [];
-  const baseByKey = new Map();
-  for (const r of baseRows) baseByKey.set(r.path, r);
-  const seen = new Set();
-  const regressions = [];
-  const improvements = [];
-  const unchanged = [];
-  const additions = [];
-  for (const h of headRows) {
-    seen.add(h.path);
-    const b = baseByKey.get(h.path);
-    if (!b) {
-      additions.push({ key: h.path, head: h, base: null });
-      continue;
-    }
-    const delta = (h.score ?? 0) - (b.score ?? 0);
-    if (delta < 0) regressions.push({ key: h.path, head: h, base: b });
-    else if (delta > 0) improvements.push({ key: h.path, head: h, base: b });
-    else unchanged.push({ key: h.path, head: h, base: b });
-  }
-  for (const b of baseRows) {
-    if (seen.has(b.path)) continue;
-    if ((b.score ?? 0) < 100) {
-      improvements.push({ key: b.path, head: null, base: b });
-    } else {
-      unchanged.push({ key: b.path, head: null, base: b });
-    }
-  }
-  return { regressions, improvements, unchanged, additions };
-}
-
-/**
- * Pure stabilizer for s-stability-epsilon (Story #1964). Folds sub-epsilon
- * mutation-score deltas back to the prior bytes. Missing-prior rows fall
- * through to the regenerated row.
- *
- * @param {Array<{path: string, score: number, killed: number, survived: number}>} prior
- * @param {Array<{path: string, score: number, killed: number, survived: number}>} regenerated
- * @param {number} epsilon non-negative absolute tolerance on mutation score
- * @returns {Array<object>}
- */
-export function applyEpsilon(prior, regenerated, epsilon) {
-  const priorRows = Array.isArray(prior) ? prior : [];
-  const regenRows = Array.isArray(regenerated) ? regenerated : [];
-  const eps = Number.isFinite(epsilon) && epsilon >= 0 ? epsilon : 0;
-  const priorByKey = new Map();
-  for (const r of priorRows) priorByKey.set(r.path, r);
-  return regenRows.map((row) => {
-    const p = priorByKey.get(row.path);
-    if (!p) return row;
-    return Math.abs((row.score ?? 0) - (p.score ?? 0)) <= eps ? p : row;
-  });
-}
-
-/**
- * Pure scope-aware merge for s-diff-scoped-writes (Story #1974). Mutation
- * rows match by `path`. In diff mode, rows whose `path` is OUTSIDE
- * `scope.files` are preserved from `prior` verbatim; in-scope rows come
- * from `regenerated`. In full mode (or no scope), regenerated wins
- * everywhere.
- *
- * @param {Array<{path: string, score: number, killed: number, survived: number}>} prior
- * @param {Array<{path: string, score: number, killed: number, survived: number}>} regenerated
- * @param {{mode: 'full'|'diff', files: Set<string>}|null|undefined} scope
- * @returns {Array<object>}
- */
-export function mergeRows(prior, regenerated, scope) {
-  return mergeRowsByScope({
-    prior,
-    regenerated,
-    scope,
-    scopeKey: (row) => row.path,
-  });
-}
+export const {
+  kernelVersion,
+  sortRows,
+  rollup,
+  compare,
+  applyEpsilon,
+  mergeRows,
+} = makeBaselineKind({
+  keyField,
+  kernelVersion: '1.0.0',
+  axes: ['score'],
+  betterWhen: 'higher',
+  aggregate,
+  missingBasePolicy: 'addition',
+  removedRowPolicy: {
+    kind: 'improvement-when',
+    when: (b) => (b.score ?? 0) < 100,
+  },
+});

package/.agents/scripts/lib/baselines/maintainability-baseline-io.js

@@ -0,0 +1,59 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { Logger } from '../Logger.js';
+
+/**
+ * Story #1895: project the canonical maintainability envelope back to the
+ * legacy flat `{ path: mi }` map so existing gate consumers keep working
+ * without churn — Story #1912 will replace this shim with the shared
+ * reader. Returns the parsed input unchanged when it doesn't look like an
+ * envelope (legacy flat shape stays flat).
+ */
+function projectMaintainabilityEnvelopeToFlat(parsed) {
+  if (
+    !parsed ||
+    typeof parsed !== 'object' ||
+    Array.isArray(parsed) ||
+    !Array.isArray(parsed.rows) ||
+    typeof parsed.$schema !== 'string'
+  ) {
+    return parsed;
+  }
+  const flat = {};
+  for (const row of parsed.rows) {
+    if (row && typeof row.path === 'string' && typeof row.mi === 'number') {
+      flat[row.path] = row.mi;
+    }
+  }
+  return flat;
+}
+
+/**
+ * Loads the current maintainability baseline from disk. The on-disk path is
+ * resolved by the caller via {@link getBaselines}; passing it explicitly
+ * removes the silent-default behaviour the framework dropped in Epic #730
+ * Story 5.5.
+ *
+ * @param {string} baselinePath  Repo-relative or absolute path to the baseline
+ *   JSON. Required.
+ * @returns {Record<string, number>}
+ */
+export function getBaseline(baselinePath) {
+  if (typeof baselinePath !== 'string' || baselinePath.length === 0) {
+    throw new TypeError(
+      'maintainability-utils.getBaseline: baselinePath is required (Epic #730 ' +
+        'Story 5.5 — callers resolve the path via getBaselines(config).maintainability.path).',
+    );
+  }
+  const abs = path.isAbsolute(baselinePath)
+    ? baselinePath
+    : path.resolve(process.cwd(), baselinePath);
+  if (!fs.existsSync(abs)) return {};
+  try {
+    const parsed = JSON.parse(fs.readFileSync(abs, 'utf-8'));
+    return projectMaintainabilityEnvelopeToFlat(parsed);
+  } catch (err) {
+    Logger.warn(`[Maintainability] Failed to parse baseline: ${err.message}`);
+    return {};
+  }
+}

package/.agents/scripts/lib/baselines/maintainability-baseline-save.js

@@ -0,0 +1,37 @@
+import path from 'node:path';
+import {
+  write as writeBaselineEnvelope,
+  writeFile as writeBaselineFile,
+} from './writer.js';
+
+/**
+ * Saves a new maintainability baseline to disk at `baselinePath`.
+ *
+ * Accepts the legacy flat `{ path: mi }` shape for backwards compatibility
+ * with existing callers (`regenerateMainFromTree`, refresh helpers). The
+ * map is transformed into the canonical envelope shape (`$schema`,
+ * `kernelVersion`, `generatedAt`, `rollup`, `rows`) via the shared
+ * `lib/baselines/writer.js` pipeline before being persisted, so every
+ * write produces a file that round-trips through `lib/baselines/reader.js`
+ * without schema errors.
+ *
+ * @param {Record<string, number>} baseline  path→MI flat map.
+ * @param {string} baselinePath  Required — caller supplies via getBaselines().
+ */
+export function saveBaseline(baseline, baselinePath) {
+  if (typeof baselinePath !== 'string' || baselinePath.length === 0) {
+    throw new TypeError(
+      'maintainability-utils.saveBaseline: baselinePath is required.',
+    );
+  }
+  const abs = path.isAbsolute(baselinePath)
+    ? baselinePath
+    : path.resolve(process.cwd(), baselinePath);
+
+  const rows = Object.entries(baseline ?? {}).map(([p, mi]) => ({
+    path: p,
+    mi,
+  }));
+  const envelope = writeBaselineEnvelope({ kind: 'maintainability', rows });
+  writeBaselineFile(abs, envelope);
+}

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

@@ -3,7 +3,7 @@
  *
  * Every legacy baseline-refresh script (`update-crap-baseline.js`,
  * `update-maintainability-baseline.js`, `lib/coverage-baseline.js`,
- * `lib/auto-refresh-baselines.js`) used to assemble its own envelope and
+ * the auto-refresh evaluator, now inside `auto-refresh-runner.js`) used to assemble its own envelope and
  * call `fs.writeFileSync`. That meant the path canonicalisation, rollup
  * math, kernel-version stamping, and JSON-serialisation conventions were
  * duplicated five-ish times, each with subtly different rules. The