mandrel 2.46.0 → 2.48.0

package/.agents/docs/configuration.md

@@ -690,6 +690,7 @@ 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](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/docs/quality-gates.md

@@ -889,6 +889,54 @@ The schemas live under [`.agents/schemas/baselines/`](../schemas/baselines/).
 The shared AJV instance is built by `buildBaselineSchemaAjv()` in
 [`.agents/scripts/lib/baseline-schema-registry.js`](../scripts/lib/baseline-schema-registry.js).
 
+### Concurrent refreshes — the baseline merge driver
+
+`generatedAt` sits on line 4 of every envelope, so two branches that each
+refresh a baseline **always** differ there, even when they moved completely
+disjoint rows. Git merges JSON as text, and whether it can separate that hunk
+from the moved rows is an accident of proximity. Both outcomes are wrong:
+
+- it cannot → a conflict on work that never overlapped (the `coverage.json` /
+  `maintainability.json` "always conflicts" pattern);
+- it can → it splices both sides' row lines into a row set **neither side
+  scored** (the `crap.json` "silently auto-merges" pattern). The ratchet then
+  guards a number no scorer ever produced.
+
+A baseline is a set of rows keyed by identity plus a rollup derived from them,
+so [`merge-baseline.js`](../scripts/merge-baseline.js) merges it as that. Per
+row identity the standard 3-way rule applies; only a genuine double move
+conflicts, and then markers wrap that row alone. The rollup is always
+**recomputed** from the merged rows — merging two rollups is the same splice
+hazard compressed into one number — and `generatedAt` resolves to the later of
+the two stamps rather than conflicting.
+
+Row identity comes from the kind module's `rowIdentity(row)`, which is
+deliberately not `keyField`: CRAP groups by file (`keyField: 'path'`) but
+ships one row per method, so keying on `keyField` would drop every method in a
+file but one. Any `baselines/*.json` whose `$schema` is not a known per-kind
+envelope — `arch-cycles`, `cyclomatic`, `dead-exports`, `audit-ledger`,
+`context-budget`, `workflow-citations` — is handed straight back to
+`git merge-file`, so registering the driver cannot change their behaviour.
+
+Registration has two halves:
+
+```bash
+# 1. tracked, installed by `node .agents/scripts/apply-quality-bootstrap.js`
+#    → .gitattributes:  baselines/*.json merge=mandrel-baseline
+# 2. per clone — git will not run a command chosen by whoever wrote the repo
+git config merge.mandrel-baseline.driver "node .agents/scripts/merge-baseline.js %O %A %B %P"
+```
+
+Only the first ships with the repository, and a clone missing the second
+degrades **silently** back to the text merge. `mandrel doctor`'s
+`merge-driver` check is the guard: it prints the exact `git config` line
+above, and passes as skipped when `.gitattributes` does not declare the
+driver at all.
+
+`MANDREL_BASELINE_GENERATED_AT` pins the stamp for a reproducible build (see
+the environment table in [configuration.md](configuration.md)). It is no
+longer needed to dodge merge conflicts.
+
 ### Per-kind shapes
 
 Each kind contributes a `rows[]` schema and a `rollup` axis set. The

package/.agents/schemas/story-deliver-terminal.schema.json

@@ -88,7 +88,8 @@
         "refCleanup",
         "baseFastForward",
         "tempPurge",
-        "leaseRelease"
+        "leaseRelease",
+        "epicRollup"
       ],
       "properties": {
         "followUps": { "type": "boolean" },
@@ -103,6 +104,10 @@
           "type": "boolean",
           "description": "Story #4860 — the operator's assignee-lease on the Story was released now that the merge is confirmed. The close deliberately no longer releases it at PR creation, so the ticket stays assigned for the whole time its PR is open; every non-merged ending (merge.unlanded block, exhausted wait budget, --no-wait-merge, --no-auto-merge) retains the claim and never reaches this step. A no-op release — the operator is no longer the recorded owner, as on a re-run or a belated manual confirm — reports true: an already-unassigned ticket is the desired end state. Only a throw reports false, and like every tail step that degrades the report, never the land."
         },
+        "epicRollup": {
+          "type": "boolean",
+          "description": "Story #5205 — the container Epic listing this Story was rolled up from its children: Status column derived from their composition, the operator recorded as its owner while any child is in flight, and the Epic closed once every child landed. A Story under no container reports true — there was nothing to roll up, which IS the correct outcome. Only a real failure — an unreadable child, a refused board or issue mutation — reports false, and like every tail step that degrades the report, never the land."
+        },
         "details": {
           "type": "object",
           "description": "Per-step diagnostic detail — the reason a false step reported false.",

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

@@ -35,6 +35,7 @@ import {
   name as bundleSizeName,
   projectRow as bundleSizeProjectRow,
   rollup as bundleSizeRollup,
+  rowIdentity as bundleSizeRowIdentity,
   sortRows as bundleSizeSortRows,
 } from './kinds/bundle-size.js';
 import {
@@ -46,6 +47,7 @@ import {
   name as coverageName,
   projectRow as coverageProjectRow,
   rollup as coverageRollup,
+  rowIdentity as coverageRowIdentity,
   sortRows as coverageSortRows,
 } from './kinds/coverage.js';
 import {
@@ -59,6 +61,7 @@ import {
   name as crapName,
   projectRow as crapProjectRow,
   rollup as crapRollup,
+  rowIdentity as crapRowIdentity,
   sortRows as crapSortRows,
 } from './kinds/crap.js';
 import {
@@ -70,6 +73,7 @@ import {
   name as duplicationName,
   projectRow as duplicationProjectRow,
   rollup as duplicationRollup,
+  rowIdentity as duplicationRowIdentity,
   sortRows as duplicationSortRows,
 } from './kinds/duplication.js';
 import {
@@ -81,6 +85,7 @@ import {
   name as lighthouseName,
   projectRow as lighthouseProjectRow,
   rollup as lighthouseRollup,
+  rowIdentity as lighthouseRowIdentity,
   sortRows as lighthouseSortRows,
 } from './kinds/lighthouse.js';
 import {
@@ -92,6 +97,7 @@ import {
   name as lintName,
   projectRow as lintProjectRow,
   rollup as lintRollup,
+  rowIdentity as lintRowIdentity,
   sortRows as lintSortRows,
 } from './kinds/lint.js';
 import {
@@ -103,6 +109,7 @@ import {
   name as maintainabilityName,
   projectRow as maintainabilityProjectRow,
   rollup as maintainabilityRollup,
+  rowIdentity as maintainabilityRowIdentity,
   sortRows as maintainabilitySortRows,
 } from './kinds/maintainability.js';
 import {
@@ -115,6 +122,7 @@ import {
   name as mutationName,
   projectRow as mutationProjectRow,
   rollup as mutationRollup,
+  rowIdentity as mutationRowIdentity,
   sortRows as mutationSortRows,
 } from './kinds/mutation.js';
 
@@ -135,6 +143,9 @@ function bindKindModule(members) {
   return Object.freeze({
     name: members.name,
     keyField: members.keyField,
+    // Story #5215: the merge identity, distinct from the `keyField`
+    // grouping key above — CRAP groups by file and identifies by method.
+    rowIdentity: members.rowIdentity,
     kernelVersion: members.kernelVersion,
     projectRow: members.projectRow,
     sortRows: members.sortRows,
@@ -159,6 +170,7 @@ const KIND_MODULES = Object.freeze({
   lint: bindKindModule({
     name: lintName,
     keyField: lintKeyField,
+    rowIdentity: lintRowIdentity,
     kernelVersion: lintKernelVersion,
     projectRow: lintProjectRow,
     sortRows: lintSortRows,
@@ -170,6 +182,7 @@ const KIND_MODULES = Object.freeze({
   coverage: bindKindModule({
     name: coverageName,
     keyField: coverageKeyField,
+    rowIdentity: coverageRowIdentity,
     kernelVersion: coverageKernelVersion,
     projectRow: coverageProjectRow,
     sortRows: coverageSortRows,
@@ -181,6 +194,7 @@ const KIND_MODULES = Object.freeze({
   crap: bindKindModule({
     name: crapName,
     keyField: crapKeyField,
+    rowIdentity: crapRowIdentity,
     kernelVersion: crapKernelVersion,
     projectRow: crapProjectRow,
     sortRows: crapSortRows,
@@ -194,6 +208,7 @@ const KIND_MODULES = Object.freeze({
   maintainability: bindKindModule({
     name: maintainabilityName,
     keyField: maintainabilityKeyField,
+    rowIdentity: maintainabilityRowIdentity,
     kernelVersion: maintainabilityKernelVersion,
     projectRow: maintainabilityProjectRow,
     sortRows: maintainabilitySortRows,
@@ -205,6 +220,7 @@ const KIND_MODULES = Object.freeze({
   mutation: bindKindModule({
     name: mutationName,
     keyField: mutationKeyField,
+    rowIdentity: mutationRowIdentity,
     kernelVersion: mutationKernelVersion,
     projectRow: mutationProjectRow,
     sortRows: mutationSortRows,
@@ -217,6 +233,7 @@ const KIND_MODULES = Object.freeze({
   lighthouse: bindKindModule({
     name: lighthouseName,
     keyField: lighthouseKeyField,
+    rowIdentity: lighthouseRowIdentity,
     kernelVersion: lighthouseKernelVersion,
     projectRow: lighthouseProjectRow,
     sortRows: lighthouseSortRows,
@@ -228,6 +245,7 @@ const KIND_MODULES = Object.freeze({
   'bundle-size': bindKindModule({
     name: bundleSizeName,
     keyField: bundleSizeKeyField,
+    rowIdentity: bundleSizeRowIdentity,
     kernelVersion: bundleSizeKernelVersion,
     projectRow: bundleSizeProjectRow,
     sortRows: bundleSizeSortRows,
@@ -239,6 +257,7 @@ const KIND_MODULES = Object.freeze({
   duplication: bindKindModule({
     name: duplicationName,
     keyField: duplicationKeyField,
+    rowIdentity: duplicationRowIdentity,
     kernelVersion: duplicationKernelVersion,
     projectRow: duplicationProjectRow,
     sortRows: duplicationSortRows,

package/.agents/scripts/lib/baselines/kinds/bundle-size.js

@@ -28,6 +28,18 @@ export function projectRow(row) {
   };
 }
 
+/**
+ * Canonical row identity (Story #5215). This kind does not use the shared
+ * factory scaffold, so it declares the protocol member itself; `bundle` is
+ * unique per row here, which a shipped-baseline injectivity test pins.
+ *
+ * @param {{bundle: string, rawKb: number, gzippedKb: number}} row
+ * @returns {string}
+ */
+export function rowIdentity(row) {
+  return row.bundle;
+}
+
 export function sortRows(rows) {
   return [...rows].sort((a, b) => a.bundle.localeCompare(b.bundle));
 }

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

@@ -61,6 +61,7 @@ function perfectCoverageRow(path) {
 
 export const {
   kernelVersion,
+  rowIdentity,
   sortRows,
   rollup,
   compare,

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

@@ -242,14 +242,30 @@ export const rollup = makeRollup({ aggregate });
  * No I/O. No process exit. No friction emission.
  */
 export const compare = makeCompare({
-  identity: crapRowKey,
+  identity: rowIdentity,
   betterIsHigher: false,
   metricField: 'crap',
   // Removed methods whose crap > 0 are improvements (the debt is gone).
   removedIsImprovement: (b) => (b.crap ?? 0) > 0,
 });
 
-function crapRowKey(row) {
+/**
+ * Canonical CRAP row identity (Story #5215) — the composite
+ * `path::method@startLine`, exported under the protocol name every kind
+ * module answers to.
+ *
+ * This kind is the reason identity is a separate concept from `keyField`.
+ * `keyField` is `'path'` because the rollup groups by file, but a file
+ * ships one row per method, so a merge keyed on `keyField` would collapse
+ * every method in a file to one row and drop the rest. `compare`,
+ * `applyEpsilon` and `mergeRows` have always keyed on this composite;
+ * exporting it makes the same identity available to callers that used to
+ * have no choice but to guess from `keyField`.
+ *
+ * @param {{path: string, method: string, startLine: number}} row
+ * @returns {string}
+ */
+export function rowIdentity(row) {
   return `${row.path}::${row.method}@${row.startLine}`;
 }
 
@@ -258,7 +274,7 @@ function crapRowKey(row) {
 // absorbed the per-file queue wiring, both callers are inside it, so the
 // exports — and the re-export that used to live here — were reachable from
 // tests alone. `resolveIncrementalContext` is the production door to the
-// index; `crapRowKey` above is the composite key it halves.
+// index; `rowIdentity` above is the composite key it halves.
 
 /**
  * Pure stabilizer for s-stability-epsilon (Story #1964). CRAP rows match
@@ -271,7 +287,7 @@ function crapRowKey(row) {
  * @returns {Array<object>}
  */
 export const applyEpsilon = makeEpsilon({
-  identity: crapRowKey,
+  identity: rowIdentity,
   metricField: 'crap',
 });
 
@@ -294,7 +310,7 @@ export function mergeRows(prior, regenerated, scope) {
     regenerated,
     scope,
     scopeKey: (row) => row.path,
-    identity: (row) => crapRowKey(row),
+    identity: (row) => rowIdentity(row),
   });
 }
 

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

@@ -89,6 +89,7 @@ function roundTo2(value) {
 
 export const {
   kernelVersion,
+  rowIdentity,
   sortRows,
   rollup,
   compare,

package/.agents/scripts/lib/baselines/kinds/kind-factory.js

@@ -38,7 +38,10 @@ import { mergeRowsByScope } from '../scope.js';
  *     | { kind: 'improvement-when', when: (row: object) => boolean },
  *   perfectRow?: (key: string) => object,
  * }} opts
- *   - `keyField`          — row identity property (`'path'` or `'route'`)
+ *   - `keyField`          — row grouping property (`'path'` or `'route'`):
+ *                           the rollup/scope key. The generated
+ *                           `rowIdentity` derives from it, but the two are
+ *                           distinct concepts — see `rowIdentity` below.
  *   - `kernelVersion`     — static semver, or a thunk for kinds that pin
  *                           to another kind's kernel (MI → CRAP)
  *   - `axes`              — metric property names compared per row
@@ -57,6 +60,7 @@ import { mergeRowsByScope } from '../scope.js';
  *   - `perfectRow`        — builds the perfect row for the policies above
  * @returns {{
  *   kernelVersion: () => string,
+ *   rowIdentity: (row: object) => string,
  *   sortRows: (rows: object[]) => object[],
  *   rollup: (rows: object[], components?: object[]) => Record<string, object>,
  *   compare: (head: object, base: object) => object,
@@ -78,6 +82,26 @@ export function makeBaselineKind({
   const kernelVersionFn =
     typeof kernelVersion === 'function' ? kernelVersion : () => kernelVersion;
 
+  /**
+   * Canonical row identity (Story #5215) — the string a 3-way merge keys a
+   * row on, and the contract every kind module must satisfy.
+   *
+   * Deliberately a separate concept from `keyField`, even though the five
+   * scaffold kinds derive one from the other. `keyField` answers "which
+   * component does this row roll up into", so a kind is free to declare a
+   * grouping key coarser than a row (CRAP declares `'path'` while shipping
+   * one row per method). Identity answers "is this the same row", and a
+   * merge that confuses the two silently drops every sibling sharing a key.
+   * Callers therefore read `rowIdentity` off the kind module and never
+   * rebuild a key from `keyField` themselves.
+   *
+   * @param {object} row
+   * @returns {string}
+   */
+  function rowIdentity(row) {
+    return String(keyOf(row));
+  }
+
   function sortRows(rows) {
     return [...rows].sort((a, b) => keyOf(a).localeCompare(keyOf(b)));
   }
@@ -183,6 +207,7 @@ export function makeBaselineKind({
 
   return {
     kernelVersion: kernelVersionFn,
+    rowIdentity,
     sortRows,
     rollup,
     compare,

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

@@ -69,6 +69,7 @@ function perfectLighthouseRow(route) {
 
 export const {
   kernelVersion,
+  rowIdentity,
   sortRows,
   rollup,
   compare,

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

@@ -67,6 +67,18 @@ export function projectRow(row) {
   };
 }
 
+/**
+ * Canonical row identity (Story #5215). This kind does not use the shared
+ * factory scaffold, so it declares the protocol member itself; `path` is
+ * unique per row here, which a shipped-baseline injectivity test pins.
+ *
+ * @param {{path: string, errorCount: number, warningCount: number}} row
+ * @returns {string}
+ */
+export function rowIdentity(row) {
+  return row.path;
+}
+
 export function sortRows(rows) {
   return [...rows].sort((a, b) => a.path.localeCompare(b.path));
 }

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

@@ -109,6 +109,7 @@ function aggregate(rows) {
 
 export const {
   kernelVersion,
+  rowIdentity,
   sortRows,
   rollup,
   compare,

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

@@ -178,6 +178,7 @@ function aggregate(rows) {
 
 export const {
   kernelVersion,
+  rowIdentity,
   sortRows,
   rollup,
   compare,