mandrel 2.61.0 → 2.63.0

package/.agents/docs/configuration.md

@@ -593,7 +593,6 @@ Claude Code web environment-variables UI for web sessions.
 | `WEBHOOK_SECRET`           | No        | Shared secret used to sign outbound webhook payloads as `X-Signature-256: sha256=<hmac>`. Unset ships unsigned payloads.                                 |
 | `MANDREL_ALLOW_TEST_WEBHOOKS` | No     | Set to `1` to keep `NOTIFICATION_WEBHOOK_URL` live inside `npm test` / `npm run test:profile`. Default behaviour scrubs the env var from the test child so no URL resolves and the webhook never fires (see below). |
 | `MANDREL_POOL_CONCURRENCY` | No | Upper bound on the width of every `runOnPool` worker pool in the process (the MI and CRAP scan pools). Precedence is: a caller's explicit `concurrency` → this variable → a clamp of 4 under `node:test` → `os.availableParallelism()`. Set it on a constrained or shared runner where one pool per core oversubscribes the host; a non-numeric value is ignored rather than collapsing the pool. |
-| `MANDREL_BASELINE_GENERATED_AT` | No | Pins the `generatedAt` stamp every baseline envelope carries, instead of reading the clock. Set it for a reproducible build, or to make a hand-run refresh diff against a known stamp. It changes only the stamp — rows and rollup are unaffected, and a refresh that moves no row still rewrites nothing. Concurrent refreshes no longer need it to avoid conflicting: `baselines/*.json` merges by row identity (see the baseline merge driver in [quality-gates.md](https://github.com/dsj1984/mandrel/blob/main/docs/quality-gates.md)). |
 | `MANDREL_AGENTRC_VALIDATOR` | No | Set to `dynamic` to compile the `.agentrc.json` AJV validator at runtime instead of loading the committed precompiled one (see below). Costs ~35 ms per process; the escape hatch exists for a hand-edited schema or a host where the generated module will not load. |
 
 ### The `.agentrc` validator is precompiled

package/.agents/schemas/baselines/audit-baselines-envelope.schema.json

@@ -100,7 +100,7 @@
           "generatedAt": { "type": ["string", "null"] },
           "staleDays": {
             "type": ["integer", "null"],
-            "description": "Whole days since generatedAt. Null when the stamp is absent or unparseable — never a fabricated 0. Wall time only: a baseline can read 0 here and still predate the surface it scores, which is what staleCommits catches."
+            "description": "Whole days since generatedAt — the baseline's own stamp where it carries one, else its last-commit date (row-set baselines carry no stamp). Null when neither is available or parseable — never a fabricated 0. Wall time only: a baseline can read 0 here and still predate the surface it scores, which is what staleCommits catches."
           },
           "staleCommits": {
             "type": ["integer", "null"],

package/.agents/schemas/baselines/baseline-envelope.schema.json

@@ -2,9 +2,9 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://mandrel/.agents/schemas/baselines/baseline-envelope.schema.json",
   "title": "BaselineEnvelope",
-  "description": "Shared envelope contract for every committed Mandrel baseline (lint, coverage, crap, maintainability, mutation, lighthouse, bundle-size). Each per-kind schema extends this envelope via allOf to constrain the row and rollup shape. The envelope itself is intentionally agnostic about row contents so the kernel can evolve without churning the shared contract.",
+  "description": "Shared envelope contract for every committed Mandrel baseline (lint, coverage, crap, maintainability, mutation, lighthouse, bundle-size). Each per-kind schema extends this envelope via allOf to constrain the row shape. The committed file carries no run timestamp and no rollup: both were rewritten on every refresh, so two branches refreshing disjoint rows always conflicted textually — and GitHub (PR mergeability, update-branch, the merge queue) never runs the custom merge driver. Readers derive the rollup from rows[]; freshness is the file's git history. The envelope itself is intentionally agnostic about row contents so the kernel can evolve without churning the shared contract.",
   "type": "object",
-  "required": ["$schema", "kernelVersion", "generatedAt", "rollup", "rows"],
+  "required": ["$schema", "kernelVersion", "rows"],
   "additionalProperties": false,
   "properties": {
     "$schema": {
@@ -16,11 +16,6 @@
       "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
       "description": "Semver version of the in-repo kernel that produced this baseline. Bumped when the scoring formula, scan shape, or rollup math changes. Consumers compare against the running kernel and emit drift signals when they mismatch."
     },
-    "generatedAt": {
-      "type": "string",
-      "format": "date-time",
-      "description": "ISO-8601 timestamp of the baseline run. Used for stale-baseline detection and audit trails."
-    },
     "scoringSemantics": {
       "type": "string",
       "description": "Optional per-kind stamp identifying the SCORING SEMANTICS that produced these rows — the dimension kernelVersion cannot express, because a kind's own scoring can change while the upstream package it stamps does not. A baseline whose stamp differs from the running scorer's is incomparable and the gate fails closed with re-baseline guidance rather than comparing across the boundary."
@@ -33,18 +28,6 @@
       "type": "boolean",
       "description": "Optional per-kind POSITIVE assertion that the writer which produced these rows recorded each row's coordinate provenance (Story #4901). Only meaningful for kinds whose rows carry a line coordinate that may be transpiled. Absence is the only evidence a baseline written before provenance existed leaves behind — such a baseline claims by omission that every row is an original-source coordinate — so the kind's compat axis fails it closed with re-seed guidance rather than letting the comparator key rows against a coordinate space they are not in."
     },
-    "rollup": {
-      "type": "object",
-      "description": "Aggregate metrics keyed by component. The '*' key is reserved for the whole-repo rollup and is REQUIRED; additional keys MAY be present, one per declared component.",
-      "required": ["*"],
-      "additionalProperties": true,
-      "properties": {
-        "*": {
-          "type": "object",
-          "description": "Whole-repo rollup. Per-kind schemas tighten the inner shape."
-        }
-      }
-    },
     "rows": {
       "type": "array",
       "description": "Per-row metrics. Order is kind-specific (e.g. CRAP sorts by file+startLine+method); per-kind schemas tighten the item shape.",

package/.agents/schemas/baselines/bundle-size.schema.json

@@ -6,30 +6,6 @@
   "allOf": [{ "$ref": "baseline-envelope.schema.json" }],
   "type": "object",
   "properties": {
-    "rollup": {
-      "type": "object",
-      "required": ["*"],
-      "additionalProperties": {
-        "type": "object",
-        "required": ["totalKb", "gzippedKb"],
-        "additionalProperties": false,
-        "properties": {
-          "totalKb": { "type": "number", "minimum": 0 },
-          "gzippedKb": { "type": "number", "minimum": 0 }
-        }
-      },
-      "properties": {
-        "*": {
-          "type": "object",
-          "required": ["totalKb", "gzippedKb"],
-          "additionalProperties": false,
-          "properties": {
-            "totalKb": { "type": "number", "minimum": 0 },
-            "gzippedKb": { "type": "number", "minimum": 0 }
-          }
-        }
-      }
-    },
     "rows": {
       "type": "array",
       "items": {

package/.agents/schemas/baselines/coverage.schema.json

@@ -6,32 +6,6 @@
   "allOf": [{ "$ref": "baseline-envelope.schema.json" }],
   "type": "object",
   "properties": {
-    "rollup": {
-      "type": "object",
-      "required": ["*"],
-      "additionalProperties": {
-        "type": "object",
-        "required": ["lines", "branches", "functions"],
-        "additionalProperties": false,
-        "properties": {
-          "lines": { "type": "number", "minimum": 0, "maximum": 100 },
-          "branches": { "type": "number", "minimum": 0, "maximum": 100 },
-          "functions": { "type": "number", "minimum": 0, "maximum": 100 }
-        }
-      },
-      "properties": {
-        "*": {
-          "type": "object",
-          "required": ["lines", "branches", "functions"],
-          "additionalProperties": false,
-          "properties": {
-            "lines": { "type": "number", "minimum": 0, "maximum": 100 },
-            "branches": { "type": "number", "minimum": 0, "maximum": 100 },
-            "functions": { "type": "number", "minimum": 0, "maximum": 100 }
-          }
-        }
-      }
-    },
     "rows": {
       "type": "array",
       "items": {

package/.agents/schemas/baselines/crap.schema.json

@@ -14,34 +14,6 @@
       "type": "boolean",
       "description": "Positive assertion that the writer which produced these rows recorded coordinate provenance per row (Story #4901). Absence is the ONLY evidence a pre-Story-#4866 baseline leaves — such a baseline claims by omission that every row is an original-source coordinate while some are transpiled. Deliberately optional and unconstrained here for the same reason as scoringSemantics: an unstamped baseline must reach the `provenance-unstamped` compat axis, which fails it closed with the re-seed command when it also carries transpiled-source rows, rather than dying on a raw schema error. A pure-JavaScript baseline never needs it."
     },
-    "rollup": {
-      "type": "object",
-      "required": ["*"],
-      "additionalProperties": {
-        "type": "object",
-        "required": ["p50", "p95", "max", "methodsAbove20"],
-        "additionalProperties": false,
-        "properties": {
-          "p50": { "type": "number", "minimum": 0 },
-          "p95": { "type": "number", "minimum": 0 },
-          "max": { "type": "number", "minimum": 0 },
-          "methodsAbove20": { "type": "integer", "minimum": 0 }
-        }
-      },
-      "properties": {
-        "*": {
-          "type": "object",
-          "required": ["p50", "p95", "max", "methodsAbove20"],
-          "additionalProperties": false,
-          "properties": {
-            "p50": { "type": "number", "minimum": 0 },
-            "p95": { "type": "number", "minimum": 0 },
-            "max": { "type": "number", "minimum": 0 },
-            "methodsAbove20": { "type": "integer", "minimum": 0 }
-          }
-        }
-      }
-    },
     "rows": {
       "type": "array",
       "items": {

package/.agents/schemas/baselines/duplication.schema.json

@@ -6,44 +6,6 @@
   "allOf": [{ "$ref": "baseline-envelope.schema.json" }],
   "type": "object",
   "properties": {
-    "rollup": {
-      "type": "object",
-      "required": ["*"],
-      "additionalProperties": {
-        "type": "object",
-        "required": [
-          "percentage",
-          "duplicatedLines",
-          "totalLines",
-          "filesWithDuplication"
-        ],
-        "additionalProperties": false,
-        "properties": {
-          "percentage": { "type": "number", "minimum": 0, "maximum": 100 },
-          "duplicatedLines": { "type": "integer", "minimum": 0 },
-          "totalLines": { "type": "integer", "minimum": 0 },
-          "filesWithDuplication": { "type": "integer", "minimum": 0 }
-        }
-      },
-      "properties": {
-        "*": {
-          "type": "object",
-          "required": [
-            "percentage",
-            "duplicatedLines",
-            "totalLines",
-            "filesWithDuplication"
-          ],
-          "additionalProperties": false,
-          "properties": {
-            "percentage": { "type": "number", "minimum": 0, "maximum": 100 },
-            "duplicatedLines": { "type": "integer", "minimum": 0 },
-            "totalLines": { "type": "integer", "minimum": 0 },
-            "filesWithDuplication": { "type": "integer", "minimum": 0 }
-          }
-        }
-      }
-    },
     "rows": {
       "type": "array",
       "items": {

package/.agents/schemas/baselines/maintainability.schema.json

@@ -6,51 +6,6 @@
   "allOf": [{ "$ref": "baseline-envelope.schema.json" }],
   "type": "object",
   "properties": {
-    "rollup": {
-      "type": "object",
-      "description": "Per-component rollup keyed by component name. The catch-all `*` is required. Each component exposes `min` / `p50` / `p95` of the per-row `mi` values — the same axes that configured floors compare against in `check-baselines.js`.",
-      "required": ["*"],
-      "additionalProperties": {
-        "type": "object",
-        "required": ["min", "p50", "p95"],
-        "additionalProperties": false,
-        "properties": {
-          "min": {
-            "type": "number",
-            "description": "Lowest `mi` value across the component's rows. Targeted by the framework-default 70-MI floor."
-          },
-          "p50": {
-            "type": "number",
-            "description": "Median (50th percentile) of the component's `mi` values."
-          },
-          "p95": {
-            "type": "number",
-            "description": "95th-percentile of the component's `mi` values."
-          }
-        }
-      },
-      "properties": {
-        "*": {
-          "type": "object",
-          "required": ["min", "p50", "p95"],
-          "additionalProperties": false,
-          "properties": {
-            "min": {
-              "type": "number",
-              "description": "Whole-repo minimum `mi`. The framework-default floor `{ min: 70 }` enforces against this value."
-            },
-            "p50": {
-              "type": "number",
-              "description": "Whole-repo median `mi`."
-            },
-            "p95": {
-              "type": "number",
-              "description": "Whole-repo 95th-percentile `mi`."
-            }
-          }
-        }
-      }
-    },
     "rows": {
       "type": "array",
       "description": "Per-file rows. The row axis stays `mi` (unchanged by Story #2193 — only the documented floor axis moved to the rollup `min` key).",

package/.agents/schemas/baselines/mutation.schema.json

@@ -6,34 +6,6 @@
   "allOf": [{ "$ref": "baseline-envelope.schema.json" }],
   "type": "object",
   "properties": {
-    "rollup": {
-      "type": "object",
-      "required": ["*"],
-      "additionalProperties": {
-        "type": "object",
-        "required": ["score", "killed", "survived", "noCoverage"],
-        "additionalProperties": false,
-        "properties": {
-          "score": { "type": "number", "minimum": 0, "maximum": 100 },
-          "killed": { "type": "integer", "minimum": 0 },
-          "survived": { "type": "integer", "minimum": 0 },
-          "noCoverage": { "type": "integer", "minimum": 0 }
-        }
-      },
-      "properties": {
-        "*": {
-          "type": "object",
-          "required": ["score", "killed", "survived", "noCoverage"],
-          "additionalProperties": false,
-          "properties": {
-            "score": { "type": "number", "minimum": 0, "maximum": 100 },
-            "killed": { "type": "integer", "minimum": 0 },
-            "survived": { "type": "integer", "minimum": 0 },
-            "noCoverage": { "type": "integer", "minimum": 0 }
-          }
-        }
-      }
-    },
     "rows": {
       "type": "array",
       "items": {

package/.agents/scripts/check-dead-exports.js

@@ -59,7 +59,7 @@ export function parseArgv(argv = []) {
  * `null` when missing or unparseable.
  *
  * @param {string} baselinePath
- * @returns {{ kernelVersion?: string, generatedAt?: string, rows?: Array<{file: string, symbol: string}> } | null}
+ * @returns {{ kernelVersion?: string, rows?: Array<{file: string, symbol: string}> } | null}
  */
 export function loadBaseline(baselinePath) {
   try {

package/.agents/scripts/lib/audit-baselines/headroom.js

@@ -35,7 +35,7 @@ export function buildHeadroom({ kinds, quality, baselines }) {
   for (const kind of kinds) {
     const floors = quality?.gates?.[kind]?.floors?.['*'];
     if (!floors || typeof floors !== 'object') continue;
-    const rollup = rollupOf(baselines.get(kind) ?? null);
+    const rollup = rollupOf(kind, baselines.get(kind) ?? null);
     for (const [axis, floor] of Object.entries(floors)) {
       if (typeof floor !== 'number' || !Number.isFinite(floor)) continue;
       const measured = rollup?.[axis];

package/.agents/scripts/lib/audit-baselines/kinds.js

@@ -5,7 +5,10 @@
  * @module lib/audit-baselines/kinds
  */
 
+import { KNOWN_KINDS } from '../baselines/envelope.js';
+import { getKindModule } from '../baselines/kernel.js';
 import { GATES_SCHEMA } from '../config/gates/index.js';
+import { rollupOfRows } from './rollup.js';
 
 /** Derived from the schema so a new gate kind arrives automatically. */
 export const GATE_KINDS = Object.freeze(
@@ -203,15 +206,17 @@ export const KIND_SPECS = Object.freeze({
 });
 
 /**
- * The `*` rollup, or `null` (ratchets carry none — a zero-cycle `arch-cycles`
- * is a passing gate, not a stub).
+ * The `*` rollup derived from the rows (the committed file carries none), or
+ * `null` for a kind without rollup arithmetic — a zero-cycle `arch-cycles` is
+ * a passing gate, not a stub.
  *
+ * @param {string} kind
  * @param {object | null} baseline
  * @returns {object | null}
  */
-export function rollupOf(baseline) {
-  const rollup = baseline?.rollup?.['*'];
-  return rollup && typeof rollup === 'object' ? rollup : null;
+export function rollupOf(kind, baseline) {
+  const rows = baseline?.rows;
+  return Array.isArray(rows) ? rollupOfRows(kind, rows) : null;
 }
 
 /**
@@ -231,7 +236,7 @@ export function measuredTotalOf(kind, baseline) {
 }
 
 /**
- * Trend comparison rollup: the declared one, else (ratchets) the measured
+ * Trend comparison rollup: the derived one, else (ratchets) the measured
  * total under its unit, so ratchets appear in `trend[]` too.
  *
  * @param {string} kind
@@ -240,7 +245,7 @@ export function measuredTotalOf(kind, baseline) {
  */
 export function trendRollupOf(kind, baseline) {
   if (!baseline) return null;
-  const declared = rollupOf(baseline);
+  const declared = rollupOf(kind, baseline);
   if (declared) return declared;
   const measured = measuredTotalOf(kind, baseline);
   return measured ? { [measured.unit]: measured.value } : null;

package/.agents/scripts/lib/audit-baselines/rollup.js

@@ -0,0 +1,41 @@
+/**
+ * The `*` rollup a baseline's rows imply. Committed row-set baselines carry
+ * none: a rollup rewritten on every refresh conflicted every concurrent merge.
+ *
+ * @module lib/audit-baselines/rollup
+ */
+
+import { KNOWN_KINDS } from '../baselines/envelope.js';
+import { getKindModule } from '../baselines/kernel.js';
+
+/**
+ * @param {Array<object>} rows
+ * @returns {{ filesAboveCeiling: number, methodsAboveCeiling: number, maxCyclomatic: number }}
+ */
+function cyclomaticRollup(rows) {
+  let methods = 0;
+  let max = 0;
+  for (const row of rows) {
+    methods += Number(row?.methodsAboveCeiling ?? 0);
+    const rowMax = Number(row?.maxCyclomatic ?? 0);
+    if (rowMax > max) max = rowMax;
+  }
+  return {
+    filesAboveCeiling: rows.length,
+    methodsAboveCeiling: methods,
+    maxCyclomatic: max,
+  };
+}
+
+/**
+ * `null` for a kind without rollup arithmetic.
+ *
+ * @param {string} kind
+ * @param {Array<object>} rows
+ * @returns {object | null}
+ */
+export function rollupOfRows(kind, rows) {
+  if (KNOWN_KINDS.includes(kind)) return getKindModule(kind).rollup(rows)['*'];
+  if (kind === 'cyclomatic') return cyclomaticRollup(rows);
+  return null;
+}

package/.agents/scripts/lib/audit-baselines/staleness.js

@@ -1,7 +1,10 @@
 /**
  * Baseline staleness on two clocks: wall-clock age, and commits touching the
  * measured surface since the baseline was committed — a baseline behind its
- * surface is stale at zero days. Unknown reports `null`, never a reassuring 0.
+ * surface is stale at zero days. Age is the file's own stamp where it carries
+ * one, else its last-commit date: row-set baselines carry no stamp, since one
+ * rewritten on every refresh conflicted every concurrent merge. Unknown
+ * reports `null`, never a reassuring 0.
  *
  * @module lib/audit-baselines/staleness
  */
@@ -66,6 +69,15 @@ function commitsSinceBaseline({ relPath, surfacePaths, io }) {
   return Number.isInteger(commits) ? commits : null;
 }
 
+/**
+ * @param {{ baseline: object, relPath: string, io: object }} args
+ * @returns {string | null}
+ */
+function writtenAtOf({ baseline, relPath, io }) {
+  if (typeof baseline.generatedAt === 'string') return baseline.generatedAt;
+  return git(['log', '-n1', '--format=%cI', '--', relPath], io);
+}
+
 /**
  * @param {{
  *   kind: string, gateBlock: object | null, rows: Array<{id: string}>,
@@ -86,8 +98,7 @@ export function stalenessOf({
   now,
   io,
 }) {
-  const generatedAt =
-    typeof baseline?.generatedAt === 'string' ? baseline.generatedAt : null;
+  const generatedAt = baseline ? writtenAtOf({ baseline, relPath, io }) : null;
   const staleCommits = baseline
     ? commitsSinceBaseline({
         relPath,

package/.agents/scripts/lib/audit-baselines/surface-entry.js

@@ -68,7 +68,7 @@ export function surfaceEntryFor({
   const gateBlock = quality?.gates?.[kind] ?? null;
   const { exists, parsed: baseline, parseError } = read;
   const rows = baseline ? KIND_SPECS[kind].rows(baseline) : [];
-  const rollup = rollupOf(baseline);
+  const rollup = rollupOf(kind, baseline);
   return {
     kind,
     surface: GATE_KINDS.includes(kind) ? 'gate' : 'ratchet',

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

@@ -24,56 +24,25 @@ function kernelVersionPattern() {
   return /^[0-9]+\.[0-9]+\.[0-9]+$/;
 }
 
-function isoTimestampPattern() {
-  // 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})$/;
-}
-
 /**
- * Explicit value, else `MANDREL_BASELINE_GENERATED_AT` (reproducible builds),
- * else now.
+ * The committed shape carries neither a run timestamp nor a rollup: both were
+ * rewritten on every refresh, so two branches refreshing disjoint rows always
+ * conflicted on a platform that never runs the merge driver. Readers derive
+ * the rollup from `rows`.
  *
- * @param {string|undefined} explicit
- * @returns {string}
- */
-function resolveGeneratedAt(explicit) {
-  const candidate =
-    typeof explicit === 'string' && explicit.length > 0
-      ? explicit
-      : (process.env.MANDREL_BASELINE_GENERATED_AT ?? new Date().toISOString());
-  if (typeof candidate !== 'string' || !isoTimestampPattern().test(candidate)) {
-    throw new Error(
-      `envelope.buildEnvelope: generatedAt must be an ISO-8601 timestamp (got ${JSON.stringify(candidate)})`,
-    );
-  }
-  return candidate;
-}
-
-/**
  * @param {{
  *   kind: string,
- *   rollup: Record<string, object>,
  *   rows: Array<object>,
  *   kernelVersion: string,
- *   generatedAt?: string,
  *   extras?: Record<string, unknown>,
  * }} params
  * @returns {{
  *   $schema: string,
  *   kernelVersion: string,
- *   generatedAt: string,
- *   rollup: Record<string, object>,
  *   rows: Array<object>,
  * }}
  */
-export function buildEnvelope({
-  kind,
-  rollup,
-  rows,
-  kernelVersion,
-  generatedAt,
-  extras,
-} = {}) {
+export function buildEnvelope({ kind, rows, kernelVersion, extras } = {}) {
   if (typeof kind !== 'string' || !KNOWN_KINDS.includes(kind)) {
     throw new TypeError(
       `envelope.buildEnvelope: kind must be one of ${KNOWN_KINDS.join(', ')} (got ${JSON.stringify(kind)})`,
@@ -87,16 +56,6 @@ export function buildEnvelope({
       `envelope.buildEnvelope: kernelVersion must be semver-shaped (got ${JSON.stringify(kernelVersion)})`,
     );
   }
-  if (!rollup || typeof rollup !== 'object' || Array.isArray(rollup)) {
-    throw new TypeError(
-      'envelope.buildEnvelope: rollup must be an object keyed by component',
-    );
-  }
-  if (!Object.hasOwn(rollup, '*')) {
-    throw new Error(
-      'envelope.buildEnvelope: rollup["*"] (whole-repo rollup) is required',
-    );
-  }
   if (!Array.isArray(rows)) {
     throw new TypeError('envelope.buildEnvelope: rows must be an array');
   }
@@ -106,9 +65,7 @@ export function buildEnvelope({
   return {
     $schema: schemaRefFor(kind),
     kernelVersion,
-    generatedAt: resolveGeneratedAt(generatedAt),
     ...(extras && typeof extras === 'object' ? extras : {}),
-    rollup,
     rows,
   };
 }
@@ -137,8 +94,6 @@ function getValidator(kind) {
 const REQUIRED_TOP_LEVEL_KEYS = Object.freeze([
   '$schema',
   'kernelVersion',
-  'generatedAt',
-  'rollup',
   'rows',
 ]);