mandrel 1.58.0 → 1.60.0

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

package/.agents/scripts/lib/bdd-runner-detect.js

@@ -13,7 +13,7 @@
  * The verification is **static**: we inspect `package.json` for a known BDD
  * runner dependency, and consult a small lookup table of which runners
  * support which pending/skip tag. We do not boot the runner. This keeps
- * `/epic-plan` Phase 7 hermetic and offline.
+ * `/plan` Phase 7 hermetic and offline.
  *
  * **Workspace awareness (Story #2956).** In a pnpm / npm / yarn monorepo the
  * BDD runner is rarely a root devDependency — it lives in the workspace

package/.agents/scripts/lib/bdd-scenario-scanner.js

@@ -1,5 +1,5 @@
 /**
- * bdd-scenario-scanner.js — Gherkin scenario index for /epic-plan Phase 7.
+ * bdd-scenario-scanner.js — Gherkin scenario index for /plan Phase 7.
  *
  * Story #2637 (sibling to #2634 codebase-snapshot, #2635 spec-freshness,
  * #2636 file-assumption gate). The Acceptance Engineer step of
@@ -7,7 +7,7 @@
  * alone — it never inspects the consumer project's existing `.feature`
  * files. Planned ACs frequently duplicate scenarios that already exist or
  * re-specify behaviour the codebase already proves; the duplication is
- * only discovered (at best) during `/story-deliver` or (at worst) after
+ * only discovered (at best) during `/deliver` or (at worst) after
  * a redundant PR ships.
  *
  * `scanBddScenarios` walks every configured feature root, parses each
@@ -20,7 +20,7 @@
  * have a matching scenario.
  *
  * Determinism is load-bearing: the matcher is keyword-based, not
- * embedding-based, so re-running `/epic-plan` against the same
+ * embedding-based, so re-running `/plan` against the same
  * acceptance spec produces the same disposition annotations.
  */
 

package/.agents/scripts/lib/bootstrap/baselines-layout-migration.js

@@ -15,7 +15,7 @@
  *
  * All three shapes are relocated under `<repoRoot>/temp/epic/<id>/baselines/`,
  * where they inherit the existing per-epic temp-tree cleanup contract:
- * `/epic-deliver` reaps `temp/epic/<id>/` on merge, so the ratchet snapshots
+ * `/deliver` reaps `temp/epic/<id>/` on merge, so the ratchet snapshots
  * are ephemeral scratch state — never committed, no manual prune.
  *
  * The main-tracked `baselines/{maintainability,crap}.json` files are NOT

package/.agents/scripts/lib/bootstrap/branch-protection.js

@@ -7,7 +7,7 @@
  *   - `enforce_admins: true` — admins do not bypass the prGate suite.
  *   - `required_pull_request_reviews.required_approving_review_count: 0` —
  *     CI is the gate; the operator monitors and iterates the open PR
- *     to green via `/epic-deliver`'s Phase 7 watch loop.
+ *     to green via `/deliver`'s Phase 7 watch loop.
  *
  * Behaviour rules
  * ---------------

package/.agents/scripts/lib/bootstrap/ci-workflow-template.js

@@ -14,7 +14,7 @@
  *      `--full-scope` so a self-diff doesn't degrade to "no files in diff".
  *
  *   2. **Pass `--epic-ref` where the firing site is Epic-aware.** Inside
- *      `/story-deliver` the close-validation chain already threads
+ *      `/deliver` the close-validation chain already threads
  *      `--epic-ref epic/<id>`; on CI the equivalent surface is the PR's
  *      base branch. The template wires `--epic-ref ${EPIC_REF}` through an
  *      env var the workflow computes from `github.head_ref` (story-N

package/.agents/scripts/lib/bootstrap/commit-push.js

@@ -112,8 +112,8 @@ export function buildManualInstructions({ stagePaths, baseBranch }) {
     `  git push -u origin ${baseBranch}`,
     '',
     'Story delivery runs in git worktrees that check out tracked files only,',
-    'so the .agents/ wiring MUST be committed before any /story-deliver or',
-    '/epic-deliver run — otherwise the worktree has no scripts and breaks.',
+    'so the .agents/ wiring MUST be committed before any /deliver or',
+    '/deliver run — otherwise the worktree has no scripts and breaks.',
   ].join('\n');
 }