mandrel 1.57.0

package/.agents/schemas/epic-spec.schema.json

@@ -0,0 +1,183 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/epic-spec.schema.json",
+  "version": "3.0.0",
+  "title": "Epic Spec (declarative structural SSOT)",
+  "description": "Canonical structural specification for an Epic and its children (Features, Stories), consumed by the epic-spec-reconciler. Lives on disk as .agents/epics/<epic-id>.yaml. The reconciler diffs this spec against live GitHub state and applies structural mutations (Create/Update/Close/Relink) behind a dry-run default. Slugs are stable, GH-incarnation-independent identifiers used for intra-spec dependency edges (dependsOn) and the spec ↔ GH-issue mapping persisted in the sibling .agents/epics/<epic-id>.state.json. This schema describes the 3-tier structural shape only (Epic → Feature → Story with inline Story-level acceptance[]/verify[]); agent-execution state (agent::* labels) is intentionally not modelled — that surface belongs to the wave-runner, not the reconciler.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["epic", "features"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Relative or absolute reference to this schema file. Allowed at the top level so YAML editors with $schema-aware autocomplete (e.g. the Red Hat YAML extension) can resolve the schema from the spec file itself."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Optional schema-shape identifier. Identification-only — readers MUST NOT branch behavior on this value. Bumped to 3.0.0 when Task-level decomposition was removed under the 3-tier collapse (Epic #3078)."
+    },
+    "epic": {
+      "$ref": "#/$defs/epic",
+      "description": "The Epic this spec describes. Carries the GH issue number, human title, and structural labels (type::epic plus any project-specific structural tags). Execution-state labels (agent::*) MUST NOT appear here."
+    },
+    "features": {
+      "type": "array",
+      "description": "Ordered list of Features under this Epic. Order is preserved for human readability but is not load-bearing — wave ordering is driven by stories[].wave + dependsOn, not by feature position.",
+      "items": { "$ref": "#/$defs/feature" }
+    },
+    "gates": {
+      "$ref": "#/$defs/gates",
+      "description": "Optional references to baseline + gate-config slugs resolved by the baseline subsystem. Carried in the spec so structural changes can be reviewed alongside the quality-gate config that will run against them."
+    }
+  },
+  "$defs": {
+    "slug": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[a-z0-9][a-z0-9-]*$",
+      "description": "Stable kebab-case identifier used for intra-spec dependency edges (dependsOn) and the spec ↔ GH-issue mapping. Slugs must be unique within their scope (features within an epic, stories within a feature). Slugs are not GH issue numbers — they survive Epic re-incarnations and ticket renumbering. Pattern: lowercase alphanumeric + hyphens, must start with [a-z0-9]."
+    },
+    "label": {
+      "type": "string",
+      "minLength": 1,
+      "description": "A GitHub label name. Structural labels only (e.g. type::epic, type::feature, type::story, persona::*, area::*). Execution-state labels in the AGENT_LABELS allow-list (agent::*) MUST NOT appear in the spec — they are owned by the wave-runner and the reconciler refuses to write them."
+    },
+    "labels": {
+      "type": "array",
+      "description": "Structural labels attached to this entity. The reconciler enforces an allow-list (STRUCTURAL_LABELS) and rejects any plan that attempts to update AGENT_LABELS via the structural path.",
+      "items": { "$ref": "#/$defs/label" },
+      "uniqueItems": true
+    },
+    "epic": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title"],
+      "description": "Top-level Epic descriptor. Unlike Features/Stories (which are slug-keyed and may not exist in GH yet), the Epic always has a real GH issue number — the spec lives at .agents/epics/<id>.yaml and that <id> is the same number used here.",
+      "properties": {
+        "id": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "GitHub issue number for the Epic. Authoritative — the spec file's filename derives from this value (.agents/epics/<id>.yaml) and the sibling state file (<id>.state.json) is keyed against it."
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Human-readable Epic title. Reconciler updates the GH issue title to match this value on every apply (subject to mayUpdate gating)."
+        },
+        "body": {
+          "type": "string",
+          "description": "Optional Epic body. When present, the reconciler updates the GH issue body to match. When omitted, the GH issue body is left untouched (allowing operator-curated bodies to coexist with structural reconciliation). Multi-line markdown is fully supported."
+        },
+        "labels": {
+          "$ref": "#/$defs/labels",
+          "description": "Structural labels attached to the Epic (e.g. type::epic plus any project-specific structural tags). agent::* labels are forbidden — they are owned by the wave-runner."
+        }
+      }
+    },
+    "feature": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["slug", "title", "stories"],
+      "description": "A Feature groups Stories under a common product/architectural theme. Features themselves are GitHub issues (type::feature) when materialised by the reconciler — they carry no execution state, only structure.",
+      "properties": {
+        "slug": {
+          "$ref": "#/$defs/slug",
+          "description": "Stable kebab-case identifier for this Feature. Must be unique within the parent Epic's features[] array."
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Human-readable Feature title."
+        },
+        "body": {
+          "type": "string",
+          "description": "Optional Feature body. Same semantics as epic.body — written by the reconciler when present, left untouched when omitted."
+        },
+        "labels": {
+          "$ref": "#/$defs/labels",
+          "description": "Structural labels attached to this Feature (e.g. type::feature plus any project-specific structural tags)."
+        },
+        "stories": {
+          "type": "array",
+          "description": "Ordered list of Stories under this Feature. Order is for readability; execution order is driven by stories[].wave + dependsOn.",
+          "items": { "$ref": "#/$defs/story" }
+        }
+      }
+    },
+    "story": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["slug", "title", "wave"],
+      "description": "A Story is the unit of agent execution — exactly one Story branch (story-<id>) and exactly one Story sub-agent per Story per wave. Stories declare their wave assignment and inter-Story dependencies via slug references; the wave-runner consumes these to schedule the parallel fan-out. Under the 3-tier collapse (Epic #3078), Stories carry inline acceptance[] + verify[] arrays that the Story sub-agent treats as the Goal/Changes/Acceptance/Verify surface; there is no child-Task decomposition.",
+      "properties": {
+        "slug": {
+          "$ref": "#/$defs/slug",
+          "description": "Stable kebab-case identifier for this Story. Must be unique within the parent Feature's stories[] array, and is the value referenced by sibling Stories' dependsOn arrays."
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Human-readable Story title. Becomes the GH issue title."
+        },
+        "body": {
+          "type": "string",
+          "description": "Optional Story body. Written by the reconciler when present; left untouched when omitted. Used to carry Story-level acceptance criteria / context that the decomposer authored."
+        },
+        "wave": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Zero-indexed wave number. The wave-runner groups Stories with the same wave value into a single parallel batch and waits for every Story in wave N to close before dispatching wave N+1. Wave 0 typically contains Stories with no inbound dependsOn edges."
+        },
+        "dependsOn": {
+          "type": "array",
+          "description": "Slugs of Stories (within this Epic) that must close before this Story may dispatch. Slugs reference stories[].slug values — not GH issue numbers — so the spec survives GH re-incarnations. The reconciler resolves slugs to issue numbers via the sibling state file when writing GH-side `blocked by` references.",
+          "items": {
+            "$ref": "#/$defs/slug",
+            "description": "Slug of a sibling Story that must close before this Story may dispatch."
+          },
+          "uniqueItems": true
+        },
+        "labels": {
+          "$ref": "#/$defs/labels",
+          "description": "Structural labels attached to this Story (e.g. type::story, persona::*). agent::* labels are forbidden — they are owned by the wave-runner at dispatch time."
+        },
+        "acceptance": {
+          "type": "array",
+          "description": "Inline acceptance criteria for this Story (Epic #3078 — 3-tier collapse). Each entry is a single user-visible acceptance statement that the Story-level agent must satisfy. Acts as the Story-level outcome contract that the Story sub-agent treats as the Goal/Changes/Acceptance/Verify surface.",
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "description": "A single acceptance criterion expressed as a user-visible outcome (e.g. 'A Story object containing inline acceptance[] validates against the schema')."
+          }
+        },
+        "verify": {
+          "type": "array",
+          "description": "Inline verification commands for this Story (Epic #3078 — 3-tier collapse). Each entry is a shell-runnable command (typically a contract test invocation) that proves the corresponding acceptance[] entries hold.",
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "description": "A single verification command (e.g. 'node --test tests/scripts/epic-spec-schema.test.js')."
+          }
+        }
+      }
+    },
+    "gates": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional references to baseline + gate-config slugs. Carried in the spec so structural changes can be reviewed alongside the quality-gate config that will run against them. Resolved to baseline-service inputs by the existing baseline subsystem; opaque to the reconciler itself.",
+      "properties": {
+        "baseline": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Slug naming the baseline ratchet snapshot this Epic targets (e.g. ratchet-baseline-2026-05-12). The baseline subsystem resolves this to concrete lint/mi/crap baseline files at close-validation time."
+        },
+        "config": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Slug naming the gate-config version this Epic uses (e.g. gate-config-v6). Allows different Epics to opt into different gate configurations during long-lived migrations."
+        }
+      }
+    }
+  }
+}

package/.agents/schemas/friction-event.schema.json

@@ -0,0 +1,56 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "FrictionEvent",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "eventId": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "timestamp": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "sprintId": {
+      "type": "string"
+    },
+    "category": {
+      "type": "string",
+      "enum": [
+        "Prompt Ambiguity",
+        "Missing Skill",
+        "Incorrect Persona",
+        "Tool Limitation",
+        "Execution Error"
+      ]
+    },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "tool": {
+          "type": "string"
+        },
+        "command": {
+          "type": "string"
+        }
+      }
+    },
+    "details": {
+      "type": "string",
+      "description": "Specific error message or observation."
+    },
+    "context": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "protocolFile": {
+          "type": "string",
+          "description": "Path to relevant protocol file, e.g., '.agents/skills/core/tdd.md'"
+        }
+      }
+    }
+  },
+  "required": ["eventId", "timestamp", "sprintId", "category", "details"]
+}

package/.agents/schemas/lifecycle/README.md

@@ -0,0 +1,18 @@
+# Lifecycle event schemas
+
+JSON Schemas for the lifecycle event taxonomy consumed by the
+`/epic-deliver` lifecycle bus
+(`lib/orchestration/lifecycle/bus.js`). The bus validates every
+emit payload against one of these schemas before invoking
+listeners; a schema mismatch fails the emit and propagates the
+throw.
+
+Each event in the Tech Spec taxonomy has a `<event>.schema.json`
+file. The ledger record (`emitted | completed | failed` union)
+lives in `ledger-record.schema.json` and is consumed by
+`ledger-writer.js` and the `lifecycle-diff` CLI.
+
+Schemas are intentionally permissive (`additionalProperties: true`)
+on inner objects whose shape is dictated by upstream tooling (e.g.
+`gh pr view` JSON, `checkOutcomes`). The required-key set is the
+contract.

package/.agents/schemas/lifecycle/acceptance.reconcile.failed.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/acceptance.reconcile.failed.schema.json",
+  "title": "acceptance.reconcile.failed",
+  "description": "Emitted by AcceptanceReconciler when reconciliation fails. Routes to epic.blocked; no PR is created.",
+  "type": "object",
+  "required": ["baseRead", "reason"],
+  "properties": {
+    "baseRead": { "type": "boolean" },
+    "reason": { "type": "string", "minLength": 1 }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/acceptance.reconcile.ok.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/acceptance.reconcile.ok.schema.json",
+  "title": "acceptance.reconcile.ok",
+  "description": "Emitted by AcceptanceReconciler when reconciliation passes. Finalizer subscribes only to this event to gate the push and PR create.",
+  "type": "object",
+  "required": ["baseRead"],
+  "properties": {
+    "baseRead": { "type": "boolean" },
+    "reason": { "type": "string" }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/acceptance.reconcile.skipped.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/acceptance.reconcile.skipped.schema.json",
+  "title": "acceptance.reconcile.skipped",
+  "description": "Emitted by AcceptanceReconciler when reconciliation is skipped because the linked Acceptance Spec declares zero AC IDs ('empty-spec'). Story #2893 split the `acceptance::n-a` waiver path out to `acceptance.reconcile.waived` so the Finalizer can route waived Epics through to PR creation while empty-spec Epics still terminate without a PR. The reason field is required so the listener never silently no-ops.",
+  "type": "object",
+  "required": ["baseRead", "reason"],
+  "properties": {
+    "baseRead": { "type": "boolean" },
+    "reason": { "type": "string", "minLength": 1 }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/acceptance.reconcile.start.schema.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/acceptance.reconcile.start.schema.json",
+  "title": "acceptance.reconcile.start",
+  "description": "Emitted by AcceptanceReconciler at the start of acceptance-spec reconciliation. Must precede pr.created in every healthy run (reconciliation ordering invariant).",
+  "type": "object",
+  "required": ["epicId"],
+  "properties": {
+    "epicId": { "type": "integer", "minimum": 1 }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/acceptance.reconcile.waived.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/acceptance.reconcile.waived.schema.json",
+  "title": "acceptance.reconcile.waived",
+  "description": "Emitted by AcceptanceReconciler when reconciliation is waived by the acceptance::n-a label. Distinct from acceptance.reconcile.skipped (which now means 'empty-spec' only) so the Finalizer can subscribe to .waived and route waived Epics through to PR creation while empty-spec Epics still terminate without a PR. The reason field is required and pinned to 'waiver'.",
+  "type": "object",
+  "required": ["baseRead", "reason"],
+  "properties": {
+    "baseRead": { "type": "boolean" },
+    "reason": { "type": "string", "const": "waiver" }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/checkpoint.written.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/checkpoint.written.schema.json",
+  "title": "checkpoint.written",
+  "description": "Self-emitted by CheckpointPointerWriter after the pointer file is updated. Carries the phase header for tracing and the last-completed seqId for the resume contract.",
+  "type": "object",
+  "required": ["phase", "lastCompletedSeqId"],
+  "properties": {
+    "phase": { "type": "string", "minLength": 1 },
+    "lastCompletedSeqId": { "type": "integer", "minimum": 0 }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/close-validate.end.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/close-validate.end.schema.json",
+  "title": "close-validate.end",
+  "description": "Emitted at the end of the close-validate sub-phase. ok=true => every gate passed; ok=false => failedGate identifies the first failed gate. durationMs is wall-clock time spent in the gate chain. Story #2250.",
+  "type": "object",
+  "required": ["epicId", "storyId", "ok"],
+  "properties": {
+    "epicId": { "type": "integer", "minimum": 1 },
+    "storyId": { "type": "integer", "minimum": 1 },
+    "ok": { "type": "boolean" },
+    "gateCount": { "type": "integer", "minimum": 0 },
+    "failedGate": { "type": "string", "minLength": 1 },
+    "exitCode": { "type": "integer" },
+    "durationMs": { "type": "integer", "minimum": 0 }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/close-validate.start.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/close-validate.start.schema.json",
+  "title": "close-validate.start",
+  "description": "Emitted at the start of the close-validate sub-phase (pre-merge gate chain typecheck/lint/test/format/maintainability/crap). Story #2250.",
+  "type": "object",
+  "required": ["epicId", "storyId"],
+  "properties": {
+    "epicId": { "type": "integer", "minimum": 1 },
+    "storyId": { "type": "integer", "minimum": 1 }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/code-review.end.schema.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/code-review.end.schema.json",
+  "title": "code-review.end",
+  "description": "Emitted at the end of the code-review sub-phase. Carries a review-finding severity summary so the lifecycle ledger surfaces critical/high/medium/suggestion counts directly. The payload MUST NOT carry any secret-key-denylist fields (token, password, secret, apiKey, webhookUrl) — the LedgerWriter enforces this, but the schema's `additionalProperties: false` keeps the surface tight. Story #2252.",
+  "type": "object",
+  "required": ["epicId", "status"],
+  "properties": {
+    "epicId": { "type": "integer", "minimum": 1 },
+    "status": {
+      "type": "string",
+      "enum": ["ok", "no-changes", "invalid"]
+    },
+    "severity": {
+      "type": "object",
+      "required": ["critical", "high", "medium", "suggestion"],
+      "properties": {
+        "critical": { "type": "integer", "minimum": 0 },
+        "high": { "type": "integer", "minimum": 0 },
+        "medium": { "type": "integer", "minimum": 0 },
+        "suggestion": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": false
+    },
+    "halted": { "type": "boolean" },
+    "posted": { "type": "boolean" },
+    "durationMs": { "type": "integer", "minimum": 0 }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/code-review.start.schema.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/code-review.start.schema.json",
+  "title": "code-review.start",
+  "description": "Emitted at the start of the code-review sub-phase (Phase D of the close-tail). Story #2252.",
+  "type": "object",
+  "required": ["epicId"],
+  "properties": {
+    "epicId": { "type": "integer", "minimum": 1 }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/epic.automerge.end.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/epic.automerge.end.schema.json",
+  "title": "epic.automerge.end",
+  "description": "Emitted at the end of the automerge phase wrapper. merged=true means GitHub completed the squash; merged=false with a reason captures predicate-blocked or armed-but-pending outcomes.",
+  "type": "object",
+  "required": ["prUrl", "merged"],
+  "properties": {
+    "prUrl": { "type": "string", "format": "uri", "minLength": 1 },
+    "merged": { "type": "boolean" },
+    "reason": { "type": "string" }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/epic.automerge.start.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/epic.automerge.start.schema.json",
+  "title": "epic.automerge.start",
+  "description": "Emitted at the start of the automerge phase wrapper (Phase 8.5, via lifecycle-emit.js). AutomergePredicate subscribes to this event (Story #3901) and evaluates the structured-signal verdict; it carries no checkOutcomes because Phase 8 already polled CI to green. Distinct from epic.merge.ready (predicate outcome) and epic.merge.armed (arm outcome).",
+  "type": "object",
+  "required": ["prUrl"],
+  "properties": {
+    "prUrl": { "type": "string", "format": "uri", "minLength": 1 },
+    "epicId": { "type": "integer", "minimum": 1 }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/epic.blocked.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/epic.blocked.schema.json",
+  "title": "epic.blocked",
+  "description": "Emitted by AcceptanceReconciler (on a failed acceptance reconciliation) and MergeWatcher (on a merge-watch timeout) when the Epic transitions to agent::blocked. Subscribed by NotifyDispatcher, which fans the blocker out to the curated webhook channel. The reason field carries either a typed marker (timeout:<event>, waiver, …) or a free-form summary; sourceStoryId scopes the blocker to a child Story when applicable.",
+  "type": "object",
+  "required": ["reason"],
+  "properties": {
+    "reason": { "type": "string", "minLength": 1 },
+    "sourceStoryId": { "type": "integer", "minimum": 1 }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/epic.cleanup.end.schema.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/epic.cleanup.end.schema.json",
+  "title": "epic.cleanup.end",
+  "description": "Emitted by Cleaner when branch cleanup and temp archive complete.",
+  "type": "object",
+  "required": ["epicId"],
+  "properties": {
+    "epicId": { "type": "integer", "minimum": 1 }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/epic.cleanup.start.schema.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/epic.cleanup.start.schema.json",
+  "title": "epic.cleanup.start",
+  "description": "Emitted by Cleaner at the start of branch cleanup + temp archive.",
+  "type": "object",
+  "required": ["epicId"],
+  "properties": {
+    "epicId": { "type": "integer", "minimum": 1 }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/epic.close.end.schema.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/epic.close.end.schema.json",
+  "title": "epic.close.end",
+  "description": "Emitted when the close-tail phase finishes; AcceptanceReconciler subscribes to this event to gate finalize.",
+  "type": "object",
+  "required": ["epicId"],
+  "properties": {
+    "epicId": { "type": "integer", "minimum": 1 }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/epic.complete.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/epic.complete.schema.json",
+  "title": "epic.complete",
+  "description": "Terminal event for a successful Epic run, emitted by Cleaner once the temp archive + branch reap complete. NotifyDispatcher subscribes to this event to fan the completion out to the curated webhook channel; the agent::done label flip is driven by the post-merge close path.",
+  "type": "object",
+  "required": ["epicId", "prUrl"],
+  "properties": {
+    "epicId": { "type": "integer", "minimum": 1 },
+    "prUrl": { "type": "string", "format": "uri", "minLength": 1 }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/epic.finalize.end.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/epic.finalize.end.schema.json",
+  "title": "epic.finalize.end",
+  "description": "Emitted by Finalizer after the PR is opened (or short-circuited by gh pr list --head idempotency check).",
+  "type": "object",
+  "required": ["epicId", "prUrl"],
+  "properties": {
+    "epicId": { "type": "integer", "minimum": 1 },
+    "prUrl": { "type": "string", "format": "uri", "minLength": 1 }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/epic.finalize.start.schema.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/epic.finalize.start.schema.json",
+  "title": "epic.finalize.start",
+  "description": "Emitted by Finalizer at the start of the finalize phase (fast-forward / hotspot / baseline / push / gh pr create).",
+  "type": "object",
+  "required": ["epicId"],
+  "properties": {
+    "epicId": { "type": "integer", "minimum": 1 }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/epic.merge.armed.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/epic.merge.armed.schema.json",
+  "title": "epic.merge.armed",
+  "description": "Emitted by AutomergeArmer after gh pr merge --auto --squash --delete-branch succeeds. Must be preceded by epic.merge.ready from the same run (merge-gate ordering invariant).",
+  "type": "object",
+  "required": ["prUrl"],
+  "properties": {
+    "prUrl": { "type": "string", "format": "uri", "minLength": 1 },
+    "epicId": { "type": "integer", "minimum": 1 }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/epic.merge.blocked.schema.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/epic.merge.blocked.schema.json",
+  "title": "epic.merge.blocked",
+  "description": "Emitted by AutomergePredicate when the Epic is NOT safe to auto-merge. AutomergeArmer never sees this event; PR stays disarmed.",
+  "type": "object",
+  "required": ["prUrl", "reason"],
+  "properties": {
+    "prUrl": { "type": "string", "format": "uri", "minLength": 1 },
+    "reason": { "type": "string", "minLength": 1 },
+    "epicId": { "type": "integer", "minimum": 1 }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/epic.merge.confirmed.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/epic.merge.confirmed.schema.json",
+  "title": "epic.merge.confirmed",
+  "description": "Emitted by MergeWatcher after gh pr view --json mergeCommit,mergedAt returns a non-null mergeCommit for the armed Epic PR. Strictly downstream of epic.merge.armed; carries the observed mergeCommit SHA, mergedAt timestamp, and the cumulative poll count (Story #2896, Epic #2880).",
+  "type": "object",
+  "required": ["epicId", "prUrl", "mergeCommitSha", "pollAttempts"],
+  "properties": {
+    "epicId": { "type": "integer", "minimum": 1 },
+    "prUrl": { "type": "string", "format": "uri", "minLength": 1 },
+    "prNumber": { "type": ["integer", "null"], "minimum": 1 },
+    "mergeCommitSha": { "type": "string", "minLength": 1 },
+    "mergedAt": { "type": ["string", "null"] },
+    "pollAttempts": { "type": "integer", "minimum": 1 }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/epic.merge.ready.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/epic.merge.ready.schema.json",
+  "title": "epic.merge.ready",
+  "description": "Emitted SOLELY by AutomergePredicate (on epic.automerge.start in production, or epic.watch.end on the test-only Watcher path) once CI is confirmed green and the disqualification gate passes. The ONLY event AutomergeArmer subscribes to. Story #3367: the Finalizer no longer emits this event — emitting it from finalize cascaded epic.close.end synchronously into the auto-merge arm + branch reap, bypassing the predicate gate and deleting the epic branch before the PR merged.",
+  "type": "object",
+  "required": ["prUrl"],
+  "properties": {
+    "prUrl": { "type": "string", "format": "uri", "minLength": 1 },
+    "reason": { "type": "string" },
+    "epicId": { "type": "integer", "minimum": 1 },
+    "prNumber": { "type": "integer", "minimum": 1 }
+  },
+  "additionalProperties": false
+}