mandrel 2.24.0 → 2.26.0

package/.agents/rules/ci-remediation.md

@@ -19,8 +19,10 @@ exactly one of two ways, and no others:
    caused by the diff under review — **verify the same check against an
    unmodified `main` checkout**; if it also fails on `main` the defect is
    pre-existing and belongs in a separate change — then fix it at source,
-   commit on `story-<storyId>`, push, and re-run the watcher. Auto-merge stays
-   armed across retries. Route deterministic per-check failures (lint/format,
+   commit on `story-<storyId>`, push, and re-run the watcher. Auto-merge is
+   **disarmed on the first red** and re-armed only by a green on a **new head
+   SHA**, so the fix must be a new commit. Route deterministic per-check
+   failures (lint/format,
    maintainability/CRAP baseline drift, test failure, coverage threshold)
    through the fix table in
    [`deliver-story-reference.md` § Step 4](../workflows/helpers/deliver-story-reference.md#step-4--ci-watch--fix-recovery);
@@ -39,6 +41,51 @@ through the same two options; bisect environment (runner OS, Node version,
 concurrency, a platform-conditional branch, an external service) vs. code (an
 order-dependent test, a race, a shared-state assumption) to decide which.
 
+## Verdicts
+
+Every red check reaches exactly one verdict, and each verdict routes to one of
+the two options above. Name the verdict you reached in the `friction` comment.
+
+| Verdict | Evidence | Routes to |
+| --- | --- | --- |
+| **defect-in-diff** | The failure reproduces on the branch and not on an unmodified `main` | Option 1 — fix at source |
+| **pre-existing** | The same check fails on an unmodified `main` too | Option 2 — file `meta::framework-gap`; remediate here only if it blocks this delivery |
+| **capacity** | Proven exhaustion of a runner resource, not a property of the diff (see below) | Option 2 — file `meta::framework-gap` **and** escalate to the operator |
+
+### The `capacity` verdict
+
+A job can fail because the runner ran out of something, not because the code is
+wrong: no runner could be provisioned, the disk or memory ceiling was hit, a
+process/PTY/file-descriptor limit was exhausted, the job wall-clock timed out
+with no progress, or a self-hosted pool was saturated. Nothing on the branch
+causes it and nothing on the branch can fix it.
+
+This verdict exists because the rule previously offered no landing for that
+case. The honest reading of "a red check is a defect until proven otherwise" is
+that capacity failures are the *otherwise* — but with no verdict for them the
+only shapes on offer were "fix the diff" (impossible) and "it's flaky, re-run
+it" (forbidden), so the rule got broken rather than followed. Naming the verdict
+removes the incentive to launder a capacity failure as a rerun.
+
+**Capacity must be proven, not inferred.** A green on re-run is the single
+weakest form of evidence for it and never establishes it — that is precisely the
+observation a flaky test produces. Cite the resource and the reading: the log
+line naming the exhausted limit (an OOM kill, `ENOSPC`, `EMFILE`,
+`forkpty/sudo: Device not configured`, a provisioning error, a no-output
+timeout), plus the fact that the failure is not specific to this diff. Absent
+that reading the verdict is **flaky, not capacity**, and it routes to Option 1.
+
+On a `capacity` verdict: file the `meta::framework-gap` issue with the run link,
+the failure signature, and the resource reading; flip the Story to
+`agent::blocked` with a `friction` comment naming the verdict; and hand back to
+the operator, who owns the runner pool. Do not sit in a retry loop waiting for
+capacity to return.
+
+**Rerunning a failed job to reach green stays forbidden under every verdict,
+`capacity` included.** The verdict changes who owns the fix and where it is
+filed; it never licenses a re-run, and it is not a route to a green bar. A
+capacity-blocked delivery ends `agent::blocked` — not merged.
+
 ## Verifier
 
 The check is resolved only when it is **green with zero reruns of the failed
@@ -48,6 +95,23 @@ re-run a failed job to "see if it goes green," and you may **not** skip,
 `.only`, or quarantine a flaky test to get a green bar. Both mask the defect
 and are prohibited by this rule.
 
+**The enforcement point is
+[`pr-watch-with-update.js`](../scripts/pr-watch-with-update.js)**, and it acts
+on the **first red** — GitHub's native auto-merge fires server-side, so it
+races any attempt to detect a rerun-green and block it after the fact. On the
+first red the watcher **disarms native auto-merge** (a disarm failure is a
+blocker, not a warning) and records the PR **head SHA** in the digest
+alongside the failing check-run identity. On green it adjudicates:
+
+- **Same head SHA** → the green came from re-running the failed job. The
+  watcher exits non-zero, flips the Story to `agent::blocked` with a
+  `friction` comment, and requires the `meta::framework-gap` issue (run link +
+  failure signature, both already in the digest) before the delivery proceeds.
+- **New head SHA** → fix at source. The digest is retired, auto-merge is
+  re-armed, and the delivery continues unobstructed.
+
+A delivery that never went red has no digest and is untouched.
+
 ## Escalation
 
 Flip the ticket to `agent::blocked`, post a `friction` comment (naming the
@@ -65,4 +129,5 @@ operator under **any** of:
   registry/network outage, a branch-protection or CI misconfiguration, an
   expired credential) — file the `meta::framework-gap` issue (with run link +
   signature) and escalate on the first encounter rather than burning iterations
-  trying to code around it.
+  trying to code around it. A proven-capacity failure is this case: reach the
+  `capacity` verdict above and escalate on the first encounter.

package/.agents/schemas/agentrc.schema.json

@@ -1367,7 +1367,7 @@
           "properties": {
             "watch": {
               "type": "object",
-              "description": "Story #4356 (Epic #4355). Poll-loop tuning for the merge/CI watch. pollIntervalMs is the cadence between check probes; maxPolls caps total probes before the watcher gives up; maxResumes caps how many times the watcher may resume after a transient stall.",
+              "description": "Story #4356 (Epic #4355). Poll-loop tuning for the merge/CI watch. pollIntervalMs is the cadence between check probes; maxPolls caps total probes before the watcher gives up; maxResumes caps how many times the watcher may resume after a transient stall; attachWindowMs bounds the wait for a required context to attach at all.",
               "properties": {
                 "pollIntervalMs": {
                   "type": "integer",
@@ -1380,6 +1380,11 @@
                 "maxResumes": {
                   "type": "integer",
                   "minimum": 0
+                },
+                "attachWindowMs": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "description": "Story #4890. How long (ms) the watch keeps re-resolving an EMPTY `gh pr checks --required` set before it stops waiting for a required context to attach. A ruleset attaches its contexts asynchronously and the arrival latency is set by the slowest one, so a required context that is an aggregator job gated on every other tier is the last to appear — measured at 16m52s on this repository. Default 1200000 (20 minutes). Raise it for a repository whose contexts arrive later still; exhausting the window is never reported as a red check (the watch exits 2, not-yet-started)."
                 }
               },
               "additionalProperties": false

package/.agents/schemas/audit-rules.json

@@ -167,6 +167,21 @@
       "scope": "cumulative",
       "substitutionKeys": []
     },
+    "audit-baselines": {
+      "triggers": {
+        "gates": ["gate3"],
+        "keywords": [
+          "baseline",
+          "ratchet",
+          "floor",
+          "headroom",
+          "quality gate"
+        ],
+        "filePatterns": ["baselines/**", ".agentrc.json"]
+      },
+      "scope": "cumulative",
+      "substitutionKeys": []
+    },
     "audit-documentation": {
       "triggers": {
         "gates": ["gate1", "gate3"],

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

@@ -0,0 +1,242 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mandrel/.agents/schemas/baselines/audit-baselines-envelope.schema.json",
+  "title": "AuditBaselinesEnvelope",
+  "description": "Evidence envelope emitted by `.agents/scripts/audit-baselines.js` (Story #4902). Unlike its siblings in this directory it does NOT describe a committed baseline — it describes an engine's read-only report ABOUT the baseline surface, so it deliberately does not extend baseline-envelope.schema.json. Four sections: gateSurface (instrument health per kind), hotspots (ranked per-file clusters joining top-N outliers across gates), trend (rollup deltas from each baseline file's git history), and headroom (configured floor vs measured rollup).",
+  "type": "object",
+  "required": [
+    "kind",
+    "schemaVersion",
+    "generatedAt",
+    "cwd",
+    "topN",
+    "configError",
+    "degradations",
+    "gateSurface",
+    "hotspots",
+    "trend",
+    "headroom"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "kind": { "const": "audit-baselines-envelope" },
+    "schemaVersion": { "type": "string", "minLength": 1 },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "cwd": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Repository root the engine ran against."
+    },
+    "topN": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Per-gate bound on extracted outlier rows. The envelope never embeds a full baseline; crap.json alone is ~650KB of per-method rows."
+    },
+    "configError": {
+      "type": ["string", "null"],
+      "description": "Message from a failed config resolution. Non-null means floors, targetDirs, and ignoreGlobs were unavailable and the engine fell back to default baseline paths."
+    },
+    "degradations": {
+      "type": "object",
+      "description": "Which optional inputs were unavailable. Each degradation collapses its rank multiplier to exactly 1.0 and never changes the exit code.",
+      "required": ["gitHistory", "importGraph", "frictionLedger"],
+      "additionalProperties": false,
+      "properties": {
+        "gitHistory": { "type": "boolean" },
+        "importGraph": { "type": "boolean" },
+        "frictionLedger": { "type": "boolean" }
+      }
+    },
+    "gateSurface": {
+      "type": "array",
+      "description": "One entry per kind across BOTH halves of the surface: the closed delivery.quality.gates kinds and the out-of-band ratchet baselines the CI baselines job owns.",
+      "items": {
+        "type": "object",
+        "required": [
+          "kind",
+          "surface",
+          "baselinePath",
+          "configured",
+          "baselineExists",
+          "stub",
+          "rowCount",
+          "measured",
+          "generatedAt",
+          "staleDays",
+          "staleCommits",
+          "surfaceStale",
+          "deadIgnoreGlobs",
+          "parseError"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "kind": { "type": "string", "minLength": 1 },
+          "surface": { "enum": ["gate", "ratchet"] },
+          "baselinePath": { "type": "string", "minLength": 1 },
+          "configured": {
+            "type": "boolean",
+            "description": "A gate block for this kind is present in the resolved config."
+          },
+          "baselineExists": { "type": "boolean" },
+          "stub": {
+            "type": "boolean",
+            "description": "Zero rows AND an all-zero rollup — an instrument that passes every run vacuously. Both halves are required, so a ratchet baseline with nothing to report (e.g. zero import cycles) is never mistaken for a dead instrument."
+          },
+          "rowCount": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Rows AFTER the kind's per-file aggregation, so it is a file count for kinds whose on-disk grain is finer (dead exports are one row per {file, symbol}). Read `measured` for the quantity the instrument reports."
+          },
+          "measured": {
+            "type": ["object", "null"],
+            "description": "The whole-repo quantity in the unit the instrument measures — symbols for dead exports, bytes for context budget. Null when the baseline is absent or unreadable. Sits beside rowCount because the two legitimately disagree.",
+            "required": ["unit", "value"],
+            "additionalProperties": false,
+            "properties": {
+              "unit": { "type": "string", "minLength": 1 },
+              "value": { "type": "number" }
+            }
+          },
+          "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."
+          },
+          "staleCommits": {
+            "type": ["integer", "null"],
+            "description": "Commits touching the measured surface (the gate's targetDirs, else the baseline's own row paths) since the baseline was last committed. Null when git cannot answer or the surface is not path-keyed — an unknown count, never a reassuring 0.",
+            "minimum": 0
+          },
+          "surfaceStale": {
+            "type": ["boolean", "null"],
+            "description": "staleCommits > 0 — the baseline is older than the surface it scores, independent of wall-clock age. Null when staleCommits is unknown."
+          },
+          "deadIgnoreGlobs": {
+            "type": "array",
+            "description": "Configured ignoreGlobs matching zero files on disk.",
+            "items": { "type": "string" }
+          },
+          "parseError": { "type": ["string", "null"] }
+        }
+      }
+    },
+    "hotspots": {
+      "type": "array",
+      "description": "Per-file clusters, highest rank first. Severity sums across gate memberships, so a file that is an outlier in two gates outranks a single-gate outlier of equal per-gate severity.",
+      "items": {
+        "type": "object",
+        "required": [
+          "path",
+          "gates",
+          "gateKinds",
+          "gateCount",
+          "severityWeight",
+          "churnWeight",
+          "centralityWeight",
+          "frictionWeight",
+          "rank"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "path": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Cluster key. A repository file path for every kind except lighthouse (route) and bundle-size (bundle name)."
+          },
+          "gates": {
+            "type": "array",
+            "minItems": 1,
+            "items": {
+              "type": "object",
+              "required": [
+                "kind",
+                "metric",
+                "value",
+                "rowCount",
+                "severityWeight"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "kind": { "type": "string", "minLength": 1 },
+                "metric": { "type": "string", "minLength": 1 },
+                "value": { "type": "number" },
+                "rowCount": { "type": "integer", "minimum": 1 },
+                "severityWeight": { "type": "number", "minimum": 0 }
+              }
+            }
+          },
+          "gateKinds": { "type": "array", "items": { "type": "string" } },
+          "gateCount": { "type": "integer", "minimum": 1 },
+          "severityWeight": { "type": "number", "minimum": 0 },
+          "churnWeight": { "type": "number", "minimum": 1 },
+          "centralityWeight": { "type": "number", "minimum": 1 },
+          "frictionWeight": { "type": "number", "minimum": 1 },
+          "rank": { "type": "number", "minimum": 0 }
+        }
+      }
+    },
+    "trend": {
+      "type": "array",
+      "description": "Newest-vs-previous rollup deltas parsed from each baseline file's git history. Empty when no history is readable.",
+      "items": {
+        "type": "object",
+        "required": [
+          "kind",
+          "baselinePath",
+          "sampleCount",
+          "from",
+          "to",
+          "deltas"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "kind": { "type": "string", "minLength": 1 },
+          "baselinePath": { "type": "string", "minLength": 1 },
+          "sampleCount": { "type": "integer", "minimum": 2 },
+          "from": { "$ref": "#/definitions/commitRef" },
+          "to": { "$ref": "#/definitions/commitRef" },
+          "deltas": {
+            "type": "object",
+            "description": "Axis-by-axis `to - from`. Each key NAMES THE UNIT the delta is denominated in — `symbols` for dead exports, `bytes` for context budget, `filesTracked` where the metric is a non-additive score with no honest whole-repo sum. A kind carrying its own rollup keeps that rollup's axes.",
+            "additionalProperties": { "type": "number" }
+          }
+        }
+      }
+    },
+    "headroom": {
+      "type": "array",
+      "description": "Configured floor vs measured rollup per axis. Positive headroom is slack the floor could be tightened into; negative means the floor is already breached.",
+      "items": {
+        "type": "object",
+        "required": [
+          "kind",
+          "axis",
+          "floor",
+          "measured",
+          "direction",
+          "headroom"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "kind": { "type": "string", "minLength": 1 },
+          "axis": { "type": "string", "minLength": 1 },
+          "floor": { "type": "number" },
+          "measured": { "type": ["number", "null"] },
+          "direction": { "enum": ["gte", "lte"] },
+          "headroom": { "type": ["number", "null"] }
+        }
+      }
+    }
+  },
+  "definitions": {
+    "commitRef": {
+      "type": "object",
+      "required": ["sha", "committedAt"],
+      "additionalProperties": false,
+      "properties": {
+        "sha": { "type": "string", "minLength": 7 },
+        "committedAt": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

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

@@ -25,6 +25,14 @@
       "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."
     },
+    "tsTranspilerVersion": {
+      "type": "string",
+      "description": "Optional per-kind stamp identifying the TypeScript transpiler that produced the sourcemap these rows' line coordinates were resolved through (Story #4866). Only meaningful for kinds whose rows carry a line coordinate derived from transpiled sources; a transpiler change can move every such coordinate, and for kinds that key rows on a line that coordinate is half the row identity."
+    },
+    "provenanceStamped": {
+      "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.",

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

@@ -10,6 +10,10 @@
       "type": "string",
       "description": "Identifier for the per-method coverage-join semantics that produced these rows (Story #4775). Deliberately NOT constrained to the current value here: an old-semantics baseline must reach the gate's compat axis, which fails it closed with an explicit re-baseline command, rather than being rejected with a raw schema error."
     },
+    "provenanceStamped": {
+      "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": ["*"],
@@ -48,7 +52,15 @@
           "path": { "type": "string" },
           "method": { "type": "string" },
           "startLine": { "type": "integer", "minimum": 1 },
-          "crap": { "type": "number", "minimum": 0 }
+          "crap": { "type": "number", "minimum": 0 },
+          "anonymous": {
+            "enum": [true],
+            "description": "Marks `method` as a DERIVED identity rather than a name the source carries (Story #4969). escomplex labels an unnamed function `<anon method-N>`, where N is a per-module counter, so inserting one anonymous function renumbers every later one and re-keys 34.6% of this baseline's rows; the derived identity is the method's enclosing-scope path plus its parameter list, which is invariant under edits elsewhere in the file. Written ONLY when true, mirroring `coordinateSystem`: a named row keeps the exact four-key shape it always had. Absence on a row whose `method` still looks anonymous is the signature of a half-migrated baseline — rows preserved verbatim by a diff-scoped refresh under an envelope stamped with the current semantics — which the `anon-identity-unstamped` compat axis fails closed."
+          },
+          "coordinateSystem": {
+            "enum": ["transpiled"],
+            "description": "Coordinate provenance of startLine (Story #4866). Written ONLY when the row kept transpiled coordinates because its sourcemap lookup did not resolve — the absent-means-'original' default keeps a pure-JavaScript baseline byte-identical, since JavaScript coordinates already ARE original-source coordinates. A row carrying this key is not comparable to one without it: the compare refuses to resolve the two through its nearest-line drift heuristic rather than manufacturing a regression from the gap between two coordinate systems."
+          }
         }
       }
     }

package/.agents/schemas/crap-report.schema.json

@@ -23,6 +23,9 @@
         "regressions",
         "newViolations",
         "drifted",
+        "incomparable",
+        "provenanceMismatched",
+        "unscorable",
         "removed",
         "skippedNoCoverage",
         "scope",
@@ -34,6 +37,21 @@
         "regressions": { "type": "integer", "minimum": 0 },
         "newViolations": { "type": "integer", "minimum": 0 },
         "drifted": { "type": "integer", "minimum": 0 },
+        "incomparable": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Story #4866: scanned methods the compare REFUSED to resolve because their line coordinate provenance differs from the matching baseline rows'. Reported, never scored — resolving them through the nearest-line drift heuristic is what manufactures a regression no change can satisfy."
+        },
+        "provenanceMismatched": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Story #4871: scanned methods whose baseline candidates included at least one row expressed in a DIFFERENT line coordinate system, counted BEFORE the compare's provenance filter discards that evidence. This — not the drifted-row count, which by construction only ever counts rows whose coordinates agreed — is the quantity the unsound-basis backstop compares against its threshold."
+        },
+        "unscorable": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Story #4871: methods the scan could not score because no coverage artifact covered them. Reported rather than computed from an assumed zero percent coverage (which would drive CRAP maximal on untouched files), and excluded from the denominator of the unsound-basis ratio."
+        },
         "removed": { "type": "integer", "minimum": 0 },
         "skippedNoCoverage": { "type": "integer", "minimum": 0 },
         "scope": {
@@ -97,6 +115,25 @@
           }
         }
       }
+    },
+    "diagnostics": {
+      "type": "array",
+      "description": "Story #4866: named, gate-level findings emitted INSTEAD of per-method verdicts when the gate has established that no verdict it could produce would be meaningful — an incomparable baseline, or a comparison basis whose drifted-row ratio proves the two sides disagree on line coordinates. Present only in that case; `violations` is then empty and the preview gate exits 0.",
+      "items": {
+        "type": "object",
+        "required": ["name", "message"],
+        "additionalProperties": false,
+        "properties": {
+          "name": {
+            "type": "string",
+            "enum": [
+              "crap-unsound-comparison-basis",
+              "crap-baseline-incompatible"
+            ]
+          },
+          "message": { "type": "string" }
+        }
+      }
     }
   }
 }

package/.agents/schemas/model-attribution.schema.json

@@ -3,6 +3,10 @@
   "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/model-attribution.schema.json",
   "title": "ModelAttribution",
   "description": "Payload of the <!-- structured:model-attribution --> comment upserted onto a Task ticket at the moment it transitions to agent::executing (Story #2813). One entry per Task. Story- and Epic-level breakdowns are derived at query time from the child Tasks' attribution comments — there is no Story/Epic-scope emission.",
+  "x-mandrel-uncompiled": {
+    "reason": "Deliberate: this document is the SSOT for the shape, but no AJV instance compiles it. The framework does not pull AJV into the structured-comment path — that path uses hand-rolled shape guards — so the runtime gate below mirrors this document by hand. Keep the two in step: an edit here is only real once the validator enforces it. Declared in-file per Story #4938 so a reader is never left inferring authority from the file's mere existence.",
+    "runtimeGate": ".agents/scripts/lib/orchestration/model-attribution.js#validateModelAttributionPayload"
+  },
   "type": "object",
   "additionalProperties": false,
   "required": ["kind", "ticketId", "model", "source", "recordedAt"],