mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/baselines/env-overrides.js

@@ -1,29 +1,15 @@
 /**
- * env-overrides.js — pure resolvers for the per-kind baseline env overrides.
- *
- * Hoisted from `check-crap.js` and `check-maintainability.js` (Story #1981,
- * Task #1989) so the env-precedence behavior — config → env → default,
- * malformed values warn-and-fall-through — lives in a lib module the
- * per-kind callers (and tests) can share without spawning a CLI.
- *
- * No I/O. No side effects beyond logger warnings.
+ * Pure resolvers for per-kind baseline env overrides: config → env → default,
+ * with malformed env values warning and falling through.
  */
 
 import { Logger } from '../Logger.js';
 
-// Framework default MI tolerance. Raised from 0.001 to 0.5 because real-world
-// noise (Node-version churn, escomplex internal updates, typhonjs-escomplex
-// rounding) routinely drifts +/- 0.05 to 0.3 on otherwise-unchanged files —
-// well below the threshold of "actually less maintainable." A 0.5 floor
-// stops the pre-push hook from auto-ratcheting the baseline on noise.
+// Escomplex/Node churn drifts MI by ±0.05–0.3 on unchanged files; 0.5 keeps
+// the pre-push hook from ratcheting on noise.
 const MI_DEFAULT_TOLERANCE = 0.5;
 
 /**
- * Pure helper: resolve the effective CRAP config by layering env-var
- * overrides on top of the resolved `.agentrc.json` values. Exported so
- * tests can assert the precedence + malformed-value behavior without
- * spawning the CLI.
- *
  * @param {{ newMethodCeiling?: unknown, tolerance?: unknown, refreshTag?: unknown }} crapConfig
  * @param {NodeJS.ProcessEnv} env
  * @returns {{ newMethodCeiling: number, tolerance: number, refreshTag: string, overrides: string[] }}
@@ -33,12 +19,8 @@ export function resolveCrapEnvOverrides(crapConfig, env) {
   let newMethodCeiling = Number.isFinite(crapConfig?.newMethodCeiling)
     ? crapConfig.newMethodCeiling
     : 30;
-  // Default 0.05 (raised from 0.001 in 5.36.1). CRAP scores are
-  // `c² · (1 − cov)³ + c`, so a sub-percent per-method coverage rounding
-  // shift across CI environments — same code, different escomplex /
-  // coverage build — moves the score by ~0.01 on its own. A 0.001
-  // tolerance flagged that as a regression; real regressions cross
-  // whole-integer thresholds (e.g. 8 → 12) and clear 0.05 trivially.
+  // Coverage rounding across CI environments shifts a CRAP score by ~0.01;
+  // real regressions cross whole integers and clear 0.05 trivially.
   let tolerance = Number.isFinite(crapConfig?.tolerance)
     ? crapConfig.tolerance
     : 0.05;
@@ -83,15 +65,7 @@ export function resolveCrapEnvOverrides(crapConfig, env) {
 }
 
 /**
- * The env var that acknowledges a deliberate baseline refresh for `kind`.
- * Upper-snakes the kind name, so `bundle-size` → `BUNDLE_SIZE_REFRESH` and
- * `coverage` → `COVERAGE_REFRESH`. The two names that predate the generic
- * mechanism (`BUNDLE_SIZE_REFRESH`, Story #151; `MAINTAINABILITY_REFRESH`,
- * Story #4731) are exactly what this rule produces, so generalizing kept
- * both working unchanged.
- *
- * Module-local: `resolveKindRefreshOverrides` is the public surface, and the
- * naming rule is pinned through it rather than exported for its own sake.
+ * `bundle-size` → `BUNDLE_SIZE_REFRESH`.
  *
  * @param {string} kind
  * @returns {string|null} null when `kind` is not a usable kind name
@@ -102,29 +76,9 @@ function kindRefreshEnvVar(kind) {
 }
 
 /**
- * Pure helper: resolve the one-shot baseline refresh/acknowledge flag for any
- * ratcheted kind (Story #4802, generalizing Story #151 / Story #4731).
- *
- * `<KIND>_REFRESH=1` tells `check-baselines --gate <kind>` to demote this
- * run's head-vs-base regressions to `unchanged` for this invocation only.
- * Floors still apply — an acknowledged run can still fail on an absolute
- * floor breach; only the ratchet-vs-base comparison is suspended.
- *
- * Why every kind needs this: a diff-scope baseline is an accretion of many
- * partial runs, not one measurement. Replacing it with a single full-scope
- * measurement necessarily produces row deltas in both directions that are
- * arithmetic, not behavioural — so without an acknowledgment path the gate
- * blocks precisely the correction it should encourage.
- *
- * The flag is **not persisted** anywhere (no config write, no committed tag):
- * the very next invocation without the env var reverts to full strict
- * enforcement automatically, so there is no lingering loosened tolerance to
- * remember to reset. The evaluate phase pairs this with a commit-tagged
- * trigger that is likewise one-shot by construction.
- *
- * Accepted truthy values: `1`, `true` (case-insensitive), with surrounding
- * whitespace trimmed. Anything else — including unset, empty, `0`, `false`,
- * and non-string values — resolves to `acknowledged: false`.
+ * `<KIND>_REFRESH=1|true` demotes this run's regressions to `unchanged`
+ * (floors still apply), so a full-scope re-measure is not blocked. Never
+ * persisted.
  *
  * @param {string} kind
  * @param {NodeJS.ProcessEnv} env
@@ -143,15 +97,8 @@ export function resolveKindRefreshOverrides(kind, env) {
 }
 
 /**
- * Pure helper: resolve the effective MI tolerance by layering precedence:
- *   1. `CRAP_TOLERANCE` env-var (CI override — the baseline-refresh-
- *      guardrail uses this to force base-branch values on both gates).
- *   2. `delivery.quality.gates.maintainability.tolerance` from the config.
- *   3. `MI_DEFAULT_TOLERANCE` (0.5).
- *
- * Malformed env values warn and fall through to the next layer — a typo
- * in CI must never silently relax the gate, but it also must not skip the
- * configured project value.
+ * `CRAP_TOLERANCE` env (CI forces base values on both gates) → configured
+ * tolerance → 0.5. A malformed env value warns and keeps the config value.
  *
  * @param {NodeJS.ProcessEnv} env
  * @param {{ tolerance?: number }} [maintainabilityConfig]
@@ -160,7 +107,6 @@ export function resolveKindRefreshOverrides(kind, env) {
 export function resolveMaintainabilityEnvOverrides(env, maintainabilityConfig) {
   const overrides = [];
   let tolerance = MI_DEFAULT_TOLERANCE;
-  // Layer 2: config value (lower precedence than env, higher than default).
   const configured = maintainabilityConfig?.tolerance;
   if (
     typeof configured === 'number' &&
@@ -172,7 +118,6 @@ export function resolveMaintainabilityEnvOverrides(env, maintainabilityConfig) {
       `tolerance=${configured} (quality.maintainability.tolerance)`,
     );
   }
-  // Layer 1: env override (highest precedence).
   const raw = env?.CRAP_TOLERANCE;
   if (raw !== undefined && raw !== '') {
     const parsed = Number(raw);

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

@@ -1,41 +1,5 @@
 /**
- * envelope.js — assemble and validate baseline envelopes (Story #1891,
- * Epic #1786).
- *
- * Every committed Mandrel baseline ships an envelope-shaped JSON with five
- * top-level keys:
- *
- *   {
- *     "$schema": ".agents/schemas/baselines/<kind>.schema.json",
- *     "kernelVersion": "<semver>",
- *     "generatedAt": "<ISO-8601>",
- *     "rollup":  { "*": { ... }, [component]: { ... } },
- *     "rows":    [ ... ]
- *   }
- *
- * The envelope contract is declared in
- * `.agents/schemas/baselines/baseline-envelope.schema.json` and the
- * per-kind schemas extend it via `allOf` (Story #1888).
- *
- * This module exposes:
- *
- *   buildEnvelope({ kind, rollup, rows, kernelVersion, generatedAt? })
- *     Stamps `$schema`, `kernelVersion`, and `generatedAt` onto a freshly
- *     constructed envelope. When `generatedAt` is omitted, the
- *     `MANDREL_BASELINE_GENERATED_AT` env var overrides any other clock
- *     reading — this lets reproducible-build tests pin the timestamp
- *     without monkey-patching `Date`. When neither is provided, the
- *     envelope stamps `new Date().toISOString()`.
- *
- *   assertEnvelope(envelope)
- *     Compiles every per-kind schema once (AJV) and validates the envelope
- *     against the schema named in its `$schema`. Throws on schema
- *     mismatch, missing top-level keys, or a `$schema` that doesn't
- *     correspond to one of the seven known per-kind schemas.
- *
- * The writer (`writer.js`) calls `buildEnvelope` then `assertEnvelope`
- * before serialising — so every baseline written through the shared
- * pipeline is schema-valid by construction.
+ * Build and validate baseline envelopes.
  *
  * @module lib/baselines/envelope
  */
@@ -46,15 +10,7 @@ import {
 } from '../baseline-schema-registry.js';
 
 /**
- * Canonical list of kinds the shared envelope supports, **derived** from the
- * schema registry rather than restated (Story #5002).
- *
- * It used to be a hand-kept literal that happened to mirror
- * `BASELINE_KIND_SCHEMA_FILES` name for name. Deriving it makes
- * "`kind` is known" and "`kind`'s schema is registered" the same fact, so
- * `getValidator` below cannot be handed a kind the AJV instance never
- * compiled — the not-registered branch is gone because the state is
- * unreachable, not because it was hidden.
+ * Derived from the schema registry, so every known kind has a compiled schema.
  */
 export const KNOWN_KINDS = Object.freeze(
   BASELINE_KIND_SCHEMA_FILES.map((file) => file.replace(/\.schema\.json$/, '')),
@@ -69,23 +25,13 @@ function kernelVersionPattern() {
 }
 
 function isoTimestampPattern() {
-  // RFC 3339 / ISO 8601 with optional fractional seconds and a `Z` or
-  // `±HH:MM` offset. AJV's `date-time` format does the heavy validation;
-  // this is a cheap pre-check so we can throw a friendlier error before
-  // AJV ever runs.
+  // Cheap pre-check for a friendlier error; AJV's `date-time` is authoritative.
   return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
 }
 
 /**
- * Resolve the effective `generatedAt` for an envelope. Priority:
- *
- *   1. Caller-supplied `generatedAt`.
- *   2. `MANDREL_BASELINE_GENERATED_AT` env var (reproducible-build hook).
- *   3. `new Date().toISOString()`.
- *
- * Validates the resulting string against an ISO-8601 shape and throws a
- * clear error if it doesn't match — operators get the failure at write
- * time, not when AJV runs.
+ * Explicit value, else `MANDREL_BASELINE_GENERATED_AT` (reproducible builds),
+ * else now.
  *
  * @param {string|undefined} explicit
  * @returns {string}
@@ -104,9 +50,6 @@ function resolveGeneratedAt(explicit) {
 }
 
 /**
- * Construct an envelope. The caller supplies the per-kind row + rollup
- * shape; this module stamps the envelope-level keys.
- *
  * @param {{
  *   kind: string,
  *   rollup: Record<string, object>,
@@ -158,10 +101,8 @@ export function buildEnvelope({
     throw new TypeError('envelope.buildEnvelope: rows must be an array');
   }
 
-  // Per-kind envelope-level stamps (Story #4775). A kind whose SCORING
-  // SEMANTICS can change independently of its kernel version contributes them
-  // here; `assertEnvelope` still validates the result against the kind's
-  // schema, so an unrecognised extra fails closed rather than being persisted.
+  // `extras` carries per-kind stamps (scoring semantics that change
+  // independently of the kernel); unknown extras fail `assertEnvelope`.
   return {
     $schema: schemaRefFor(kind),
     kernelVersion,
@@ -173,18 +114,8 @@ export function buildEnvelope({
 }
 
 /**
- * Lazy AJV instance, built by the canonical
- * [`baseline-schema-registry`](../baseline-schema-registry.js) — the ONE
- * place a baselines-directory schema is read off disk and compiled
- * (Story #5002). This module used to keep its own `SCHEMAS_DIR` + AJV +
- * per-kind compile cache alongside the registry's, so the writer and
- * `baselines/reader.js` validated the same envelope through two independently
- * configured instances; a registration added to one was invisible to the
- * other. One builder means the writer and the reader cannot disagree about
- * what a valid envelope is.
- *
- * Memoised: building it reads eleven schema files, and a single baseline
- * regeneration calls `assertEnvelope` once per write plus once per re-read.
+ * Memoised registry-built AJV — one builder, so writer and reader cannot
+ * disagree about what a valid envelope is.
  */
 let _ajv = null;
 function ajv() {
@@ -195,10 +126,6 @@ function ajv() {
 }
 
 /**
- * Look up the pre-registered validator for a per-kind schema. Total over
- * `KNOWN_KINDS` — that list is derived from the registry's own filenames, so
- * every kind reaching here has a compiled schema.
- *
  * @param {string} kind
  * @returns {import('ajv').ValidateFunction}
  */
@@ -206,11 +133,7 @@ function getValidator(kind) {
   return ajv().getSchema(`${kind}.schema.json`);
 }
 
-/**
- * The five top-level keys every envelope MUST carry. Pre-checked before
- * AJV runs so the error names the missing key directly instead of
- * surfacing as an AJV "required" violation.
- */
+/** Pre-checked so the error names the missing key directly. */
 const REQUIRED_TOP_LEVEL_KEYS = Object.freeze([
   '$schema',
   'kernelVersion',
@@ -219,30 +142,7 @@ const REQUIRED_TOP_LEVEL_KEYS = Object.freeze([
   'rows',
 ]);
 
-// ---------------------------------------------------------------------------
-// Shared baseline compatibility axes (Story #2467, Task #2492).
-//
-// Every baseline-kind compatibility check shares the same universal
-// invariants: the envelope must exist, its kernelVersion must match the
-// running scorer, and (when published) its `generatedAt` must be monotonic
-// vs the running clock. Per-kind axis tables (e.g. `CRAP_COMPAT_AXES`)
-// compose these into their kind-specific axis list so the hoisted axes
-// live in exactly one place.
-//
-// Each axis exposes `{ name, severity, check }`:
-//   - `name`     — stable label used as `kind` in the failure envelope.
-//   - `severity` — `'fatal'` (short-circuit, exitCode 1) or `'warn'`
-//                  (accumulate into `warnings`).
-//   - `check`    — pure function over the compat context. Returns `null`
-//                  when the axis passes, or a string message describing
-//                  the failure.
-// ---------------------------------------------------------------------------
-
 /**
- * Universal "missing baseline" axis. Fires when the loader returned `null`
- * / `undefined`. The operator message is parametrised by the kind label
- * supplied at composition time so each kind keeps its own bootstrap hint.
- *
  * @param {string} kindLabel — operator-facing label (e.g. `CRAP`, `MI`).
  * @returns {{name: string, severity: 'fatal', check: (ctx: {baseline: unknown}) => string|null}}
  */
@@ -258,10 +158,7 @@ export function missingBaselineAxis(kindLabel) {
 }
 
 /**
- * Universal "kernel-version drift" axis. Fires when the baseline's
- * recorded `kernelVersion` differs from the running scorer's
- * `kernelVersion`. Warn-only by default — kernel drift surfaces as a
- * baseline-refresh nudge, not a close-validation failure.
+ * Warn-only: kernel drift is a refresh nudge, not a validation failure.
  *
  * @param {string} kindLabel
  * @returns {{name: string, severity: 'warn', check: (ctx: {baseline: {kernelVersion?: string}|null|undefined, runningKernelVersion: string}) => string|null}}
@@ -279,13 +176,7 @@ export function kernelDriftAxis(kindLabel) {
 }
 
 /**
- * Reduce an axis list against a compat context, emitting either a fatal
- * envelope `{ ok: false, exitCode: 1, kind, message }` (on the first
- * 'fatal' match) or an accumulating `{ ok: true, warnings }` envelope.
- *
- * Shared by every per-kind `evaluateBaselineCompatibility` caller so the
- * reduce body lives in one place and stays well below the project's
- * cyclomatic-complexity ceiling.
+ * First fatal axis short-circuits; warn axes accumulate.
  *
  * @template {object} Ctx
  * @param {Array<{name: string, severity: 'fatal'|'warn', check: (ctx: Ctx) => string|null}>} axes
@@ -309,14 +200,7 @@ export function reduceCompatAxes(axes, ctx) {
 }
 
 /**
- * Validate an envelope against its per-kind schema.
- *
- * Two-phase check:
- *   1. Cheap structural pre-check — every top-level key present, `$schema`
- *      points at one of the seven known kinds. Throws with a clear
- *      message when violated.
- *   2. AJV schema validation against the per-kind schema named in `$schema`.
- *      Throws with the AJV error list serialised as JSON.
+ * Structural pre-check, then AJV against the schema named in `$schema`.
  *
  * @param {object} envelope
  * @returns {void}

package/.agents/scripts/lib/baselines/exit-codes.js

@@ -1,34 +1,7 @@
-// .agents/scripts/lib/baselines/exit-codes.js
-//
-// Story #1962 / Task #1968 — Unified exit-code contract for the baseline
-// dispatcher (`check-baselines.js`) and every per-kind regression CLI that
-// will land in Epic #1943.
-//
-// One shared source of truth keeps the dispatcher, the per-kind CLIs, and
-// the test suites in lock-step. Numeric precedence is intentional: a
-// higher number is a strictly worse outcome, so `aggregate(...)` collapses
-// per-gate exit codes by taking the maximum. That contract lets the
-// dispatcher fan out per-kind work in any order (parallel, sequential,
-// streamed) and still produce a single deterministic process exit code.
-//
-// Precedence (lowest → highest severity):
-//
-//   0 EXIT_PASS        — every enabled gate is green.
-//   1 EXIT_FLOOR       — at least one gate breached its floor / tolerance.
-//   2 EXIT_SCHEMA      — at least one baseline file failed schema
-//                        validation (JSON shape / required fields wrong).
-//   3 EXIT_CONFIG      — config could not be resolved (missing
-//                        `.agentrc.json`, unknown gate kind, malformed
-//                        scope, etc). The gate could not even start.
-//   4 EXIT_REGRESSION  — head-vs-base regression detected on at least one
-//                        gate. Highest severity because regression
-//                        signals new debt being introduced rather than
-//                        pre-existing debt failing a static floor.
-//
-// `aggregate(...codes)` takes the highest code in the input list and
-// returns 0 (`EXIT_PASS`) for an empty input. It never throws — invalid
-// codes are silently treated as 0 because the only sane response to a
-// caller passing a garbage code is "do not regress the exit signal".
+// Exit-code contract for `check-baselines.js` and the per-kind CLIs. Higher is
+// strictly worse, so per-gate codes collapse by maximum in any order:
+// 0 pass, 1 floor breach, 2 schema-invalid baseline, 3 config unresolvable,
+// 4 head-vs-base regression (new debt outranks pre-existing floor debt).
 
 export const EXIT_PASS = 0;
 export const EXIT_FLOOR = 1;
@@ -36,10 +9,6 @@ export const EXIT_SCHEMA = 2;
 export const EXIT_CONFIG = 3;
 export const EXIT_REGRESSION = 4;
 
-/**
- * The full set of valid exit codes, frozen so callers can use it as a
- * lookup without worrying about mutation.
- */
 export const EXIT_CODES = Object.freeze({
   EXIT_PASS,
   EXIT_FLOOR,
@@ -57,20 +26,8 @@ const VALID = new Set([
 ]);
 
 /**
- * Collapse any number of per-gate exit codes into a single dispatcher
- * exit code. The contract:
- *
- *   - With no arguments, returns `EXIT_PASS` (0). An empty dispatcher run
- *     is success — there was nothing to fail.
- *   - With one or more arguments, returns the maximum of the valid codes.
- *     Higher numbers are strictly worse outcomes (see precedence table at
- *     the top of this file).
- *   - Unknown / non-numeric / negative codes are dropped from the input
- *     so a single garbage caller cannot lower the dispatcher's exit code
- *     past a real failure. If every input is invalid, the result is
- *     `EXIT_PASS` (the caller signalled nothing to report).
- *
- * Pure. No I/O. Cheap to call from a hot loop.
+ * Maximum of the valid codes; invalid codes are dropped so garbage can never
+ * lower the signal. No input → `EXIT_PASS`.
  *
  * @param {...number} codes - Per-gate exit codes to collapse.
  * @returns {number} The most severe code in the input, or `EXIT_PASS`.