mandrel 1.57.0

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

@@ -0,0 +1,71 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mandrel/.agents/schemas/baselines/maintainability.schema.json",
+  "title": "MaintainabilityBaseline",
+  "description": "Per-kind baseline schema for the Maintainability Index (MI) gate. Extends the shared baseline-envelope contract. Story #2193: the row axis stays `mi`; rollups expose `min` / `p50` / `p95` axes, and configured floors under `delivery.quality.gates.maintainability.floors[*]` target those rollup axes (the framework default is `{ min: 70 }`).",
+  "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).",
+      "items": {
+        "type": "object",
+        "required": ["path", "mi"],
+        "additionalProperties": false,
+        "properties": {
+          "path": { "type": "string" },
+          "mi": {
+            "type": "number",
+            "description": "Maintainability Index for the file at `path`. Rollup `min` / `p50` / `p95` axes are computed from these per-row `mi` values."
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,52 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mandrel/.agents/schemas/baselines/mutation.schema.json",
+  "title": "MutationBaseline",
+  "description": "Per-kind baseline schema for the mutation-testing gate. Extends the shared baseline-envelope contract.",
+  "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": {
+        "type": "object",
+        "required": ["path", "score", "killed", "survived"],
+        "additionalProperties": false,
+        "properties": {
+          "path": { "type": "string" },
+          "score": { "type": "number", "minimum": 0, "maximum": 100 },
+          "killed": { "type": "integer", "minimum": 0 },
+          "survived": { "type": "integer", "minimum": 0 }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,57 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mandrel/.agents/schemas/crap-baseline.schema.json",
+  "title": "CrapBaseline",
+  "description": "Committed baseline envelope for the CRAP (c^2 * (1 - cov)^3 + c) gate. Rows are deterministically ordered by (file, startLine, method). Kernel and escomplex versions pin the scoring environment so consumers detect silent drift.",
+  "type": "object",
+  "required": ["kernelVersion", "escomplexVersion", "rows"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Optional pointer back to this schema for editor tooling."
+    },
+    "kernelVersion": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "description": "Version of the in-repo CRAP scoring kernel. Bumped when the formula or scan shape changes. From 1.1.0 onward, a mismatch against the running kernel emits a warning and the gate continues — consumers refresh on their own cadence."
+    },
+    "escomplexVersion": {
+      "type": "string",
+      "description": "Version of the typhonjs-escomplex dependency used to produce this baseline. A mismatch against the installed dependency fails the gate closed (different kernel semantics are not negotiable)."
+    },
+    "tsTranspilerVersion": {
+      "type": "string",
+      "description": "Version of the `typescript` package used to strip TS/TSX sources before scoring. Optional for envelopes produced by kernel 1.0.0; required for 1.1.0+. A mismatch against the running typescript dependency emits a warning and the gate continues."
+    },
+    "rows": {
+      "type": "array",
+      "description": "Per-method CRAP scores, sorted by (file, startLine, method).",
+      "items": {
+        "type": "object",
+        "required": ["file", "method", "startLine", "crap"],
+        "additionalProperties": false,
+        "properties": {
+          "file": {
+            "type": "string",
+            "description": "Repo-relative POSIX path of the source file."
+          },
+          "method": {
+            "type": "string",
+            "description": "escomplex method name. Anonymous functions surface as '<anonymous>'."
+          },
+          "startLine": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "1-based escomplex lineStart used for drift-tolerant matching."
+          },
+          "crap": {
+            "type": "number",
+            "minimum": 0,
+            "description": "CRAP score: c^2 * (1 - cov)^3 + c."
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,102 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mandrel/.agents/schemas/crap-report.schema.json",
+  "title": "CrapReport",
+  "description": "Structured `--json` output envelope emitted by check-crap.js. Mirrors the shape consumed by agent workflows — a kernel/escomplex version pair, aggregate counters, and per-offender violations with deterministic single-axis fixGuidance.",
+  "type": "object",
+  "required": ["kernelVersion", "escomplexVersion", "summary", "violations"],
+  "additionalProperties": false,
+  "properties": {
+    "kernelVersion": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "description": "CRAP scoring kernel version in effect when the report was produced."
+    },
+    "escomplexVersion": {
+      "type": "string",
+      "description": "typhonjs-escomplex version used for the scan."
+    },
+    "summary": {
+      "type": "object",
+      "required": [
+        "total",
+        "regressions",
+        "newViolations",
+        "drifted",
+        "removed",
+        "skippedNoCoverage",
+        "scope",
+        "diffRef"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "total": { "type": "integer", "minimum": 0 },
+        "regressions": { "type": "integer", "minimum": 0 },
+        "newViolations": { "type": "integer", "minimum": 0 },
+        "drifted": { "type": "integer", "minimum": 0 },
+        "removed": { "type": "integer", "minimum": 0 },
+        "skippedNoCoverage": { "type": "integer", "minimum": 0 },
+        "scope": {
+          "type": "string",
+          "enum": ["diff", "full"],
+          "description": "Story #1394: which scope produced this envelope. `diff` (default) = filter scan + baseline against the resolved git ref; `full` = full-repo scan via the `--full-scope` opt-out."
+        },
+        "diffRef": {
+          "type": ["string", "null"],
+          "description": "Story #1394: the git ref the diff was scoped against (e.g. `main`, `epic/1386`), or null when `scope === 'full'`."
+        }
+      }
+    },
+    "violations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "file",
+          "method",
+          "startLine",
+          "cyclomatic",
+          "coverage",
+          "crap",
+          "baseline",
+          "ceiling",
+          "kind",
+          "fixGuidance"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "file": { "type": "string" },
+          "method": { "type": "string" },
+          "startLine": { "type": "integer", "minimum": 1 },
+          "cyclomatic": { "type": "number", "minimum": 0 },
+          "coverage": { "type": "number", "minimum": 0, "maximum": 1 },
+          "crap": { "type": "number", "minimum": 0 },
+          "baseline": { "type": ["number", "null"], "minimum": 0 },
+          "ceiling": { "type": "number", "minimum": 0 },
+          "kind": {
+            "type": "string",
+            "enum": ["regression", "drifted-regression", "new"]
+          },
+          "fixGuidance": {
+            "type": ["object", "null"],
+            "required": [
+              "crapCeiling",
+              "minComplexityAt100Cov",
+              "minCoverageAtCurrentComplexity"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "crapCeiling": { "type": "number", "minimum": 0 },
+              "minComplexityAt100Cov": { "type": "integer", "minimum": 0 },
+              "minCoverageAtCurrentComplexity": {
+                "type": ["number", "null"],
+                "minimum": 0,
+                "maximum": 1
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/.agents/schemas/dispatch-manifest.json

@@ -0,0 +1,232 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "dispatch-manifest",
+  "title": "Dispatch Manifest",
+  "description": "Output of dispatcher.js (epic-dispatch variant) and orchestration/story-executor.js (story-execution variant). Written to temp/dispatch-manifest-<epicId>.json for the epic-dispatch variant. The two variants are discriminated by the `type` field. 3-tier shape only (Epic #3078): manifests are Story-only — there is no Task-level fan-out. Open-root by design — the AJV fixture drift test is the enforcement boundary; see docs/decisions.md ADR 20260427-868a.",
+  "type": "object",
+  "required": ["generatedAt", "dryRun"],
+  "properties": {
+    "type": {
+      "type": "string",
+      "enum": ["epic-dispatch", "story-execution"],
+      "description": "Discriminator for the manifest variant."
+    },
+    "schemaVersion": {
+      "type": "string",
+      "description": "Schema version for forward-compatibility checks. Emitted by the epic-dispatch variant.",
+      "examples": ["2.0.0"]
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 timestamp when this manifest was produced."
+    },
+    "epicId": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "GitHub Issue number of the Epic."
+    },
+    "epicTitle": {
+      "type": "string",
+      "description": "Title of the Epic issue."
+    },
+    "executor": {
+      "type": "string",
+      "description": "The executor identifier used for this dispatch cycle (e.g., 'claude-code').",
+      "examples": ["claude-code"]
+    },
+    "dryRun": {
+      "type": "boolean",
+      "description": "If true, no branches were created and no Stories were dispatched."
+    },
+    "protocolVersionMismatch": {
+      "type": "boolean",
+      "description": "True if any Story's generation-time protocol version differs from the current runtime version."
+    },
+    "agentTelemetry": {
+      "type": ["object", "null"],
+      "description": "Optional runtime telemetry attached by the executor. Open-shape: any executor-defined fields are allowed.",
+      "additionalProperties": true
+    },
+    "hierarchy": {
+      "type": "string",
+      "const": "3-tier",
+      "description": "Hierarchy identifier. 3-tier is the only supported shape (Epic #3078)."
+    },
+    "summary": {
+      "type": "object",
+      "required": [
+        "totalStories",
+        "doneStories",
+        "progressPercent",
+        "totalWaves",
+        "dispatched"
+      ],
+      "properties": {
+        "totalStories": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Story-centric count for the 3-tier shape (Epic #3078)."
+        },
+        "doneStories": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Number of Stories that have reached agent::done."
+        },
+        "progressPercent": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100
+        },
+        "totalWaves": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "dispatched": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Number of Stories dispatched in this invocation."
+        }
+      },
+      "additionalProperties": false
+    },
+    "waves": {
+      "type": "array",
+      "description": "Ordered list of execution waves computed from the Story DAG.",
+      "items": {
+        "type": "object",
+        "required": ["waveIndex", "stories"],
+        "properties": {
+          "waveIndex": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "stories": {
+            "type": "array",
+            "description": "Story-centric wave entries. Each entry describes one Story dispatched in this wave, with inline acceptance/verify so the wave can run without re-fetching Story tickets.",
+            "items": {
+              "type": "object",
+              "required": [
+                "storyId",
+                "title",
+                "persona",
+                "acceptance",
+                "verify",
+                "dependsOn"
+              ],
+              "properties": {
+                "storyId": { "type": "integer", "minimum": 1 },
+                "title": { "type": "string" },
+                "persona": { "type": "string" },
+                "acceptance": {
+                  "type": "array",
+                  "description": "Inline acceptance criteria for the Story (markdown checklist lines).",
+                  "items": { "type": "string" }
+                },
+                "verify": {
+                  "type": "array",
+                  "description": "Inline verify commands or shell snippets executed at close to prove the Story.",
+                  "items": { "type": "string" }
+                },
+                "dependsOn": {
+                  "type": "array",
+                  "description": "Story-level dependencies (Story IDs that must reach agent::done before this Story dispatches).",
+                  "items": { "type": "integer" }
+                },
+                "branch": {
+                  "type": "string",
+                  "description": "Optional Story branch name (e.g., story-3098). Omitted when the runtime derives it from storyId."
+                },
+                "status": {
+                  "type": "string",
+                  "enum": [
+                    "agent::ready",
+                    "agent::executing",
+                    "agent::done",
+                    "status::blocked"
+                  ]
+                }
+              },
+              "additionalProperties": false
+            }
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "dispatched": {
+      "type": "array",
+      "description": "Stories dispatched during this invocation.",
+      "items": {
+        "type": "object",
+        "required": ["storyId", "dispatchId", "status"],
+        "properties": {
+          "storyId": { "type": "integer", "minimum": 1 },
+          "dispatchId": { "type": "string" },
+          "status": {
+            "type": "string",
+            "enum": ["dispatched", "queued"]
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "stories": {
+      "type": "array",
+      "description": "Story-execution variant payload — one entry per Story this manifest covers.",
+      "items": {
+        "type": "object",
+        "required": ["storyId", "storyTitle", "branchName"],
+        "properties": {
+          "storyId": { "type": "integer", "minimum": 1 },
+          "storyTitle": { "type": "string" },
+          "epicId": {
+            "type": ["integer", "null"],
+            "minimum": 1
+          },
+          "epicBranch": { "type": ["string", "null"] },
+          "branchName": { "type": "string" },
+          "status": {
+            "type": "string",
+            "enum": [
+              "agent::ready",
+              "agent::executing",
+              "agent::done",
+              "status::blocked"
+            ]
+          }
+        },
+        "additionalProperties": false
+      }
+    }
+  },
+  "oneOf": [
+    {
+      "title": "epic-dispatch variant",
+      "description": "Output of dispatcher.js / buildManifest(). The `type` field may be absent for back-compat; presence is restricted to 'epic-dispatch'. The 4-tier `storyManifest[]` collection is explicitly forbidden (Epic #3078 cutover).",
+      "properties": {
+        "type": { "const": "epic-dispatch" },
+        "storyManifest": false
+      },
+      "required": [
+        "schemaVersion",
+        "epicId",
+        "epicTitle",
+        "executor",
+        "summary",
+        "waves",
+        "dispatched"
+      ],
+      "not": { "required": ["stories"] }
+    },
+    {
+      "title": "story-execution variant",
+      "description": "Output of orchestration/story-executor.js / executeStory(). The 4-tier `storyManifest[]` collection is explicitly forbidden (Epic #3078 cutover).",
+      "properties": {
+        "type": { "const": "story-execution" },
+        "storyManifest": false
+      },
+      "required": ["type", "stories"]
+    }
+  ]
+}

package/.agents/schemas/epic-perf-report.schema.json

@@ -0,0 +1,89 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/epic-perf-report.schema.json",
+  "title": "EpicPerfReport",
+  "description": "Payload of the <!-- structured:epic-perf-report --> comment posted once per Epic at close, alongside the retro (Epic #1030; waveParallelism utilisation rows added under Epic #3019 / Story #3025).",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "kind",
+    "epicId",
+    "generatedAt",
+    "signalCounts",
+    "waveParallelism",
+    "topHotspots",
+    "mostFrictionStories"
+  ],
+  "properties": {
+    "kind": { "type": "string", "const": "epic-perf-report" },
+    "epicId": { "type": "integer", "minimum": 1 },
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "signalCounts": {
+      "type": "object",
+      "description": "Rolled-up signal counts by kind for the entire Epic.",
+      "additionalProperties": false,
+      "properties": {
+        "friction": { "type": "integer", "minimum": 0 },
+        "hotspot": { "type": "integer", "minimum": 0 },
+        "rework": { "type": "integer", "minimum": 0 },
+        "churn": { "type": "integer", "minimum": 0 },
+        "idle": { "type": "integer", "minimum": 0 },
+        "retry": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "waveParallelism": {
+      "type": "array",
+      "description": "Per-wave parallelism utilisation. utilisation = summedStoryMs / (wallClockMs * min(storyCount, concurrencyCap)), clamped to [0,1] (Epic #3019 / Story #3025; effective-cap denominator Story #3850).",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "waveIndex",
+          "wallClockMs",
+          "summedStoryMs",
+          "utilisation",
+          "capBinding",
+          "verifyConcurrencyCap"
+        ],
+        "properties": {
+          "waveIndex": { "type": "integer", "minimum": 0 },
+          "storyCount": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "Number of Stories in the wave (from wave-start.stories). Added Story #3850."
+          },
+          "wallClockMs": { "type": "integer", "minimum": 0 },
+          "summedStoryMs": { "type": "integer", "minimum": 0 },
+          "utilisation": { "type": "number", "minimum": 0, "maximum": 1 },
+          "capBinding": { "type": "boolean" },
+          "verifyConcurrencyCap": { "type": "integer", "minimum": 1 }
+        }
+      }
+    },
+    "topHotspots": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["phase", "occurrences", "avgRatio"],
+        "properties": {
+          "phase": { "type": "string", "minLength": 1 },
+          "occurrences": { "type": "integer", "minimum": 0 },
+          "avgRatio": { "type": "number", "minimum": 0 }
+        }
+      }
+    },
+    "mostFrictionStories": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["storyId", "frictionCount"],
+        "properties": {
+          "storyId": { "type": "integer", "minimum": 1 },
+          "frictionCount": { "type": "integer", "minimum": 0 }
+        }
+      }
+    }
+  }
+}