mandrel 1.57.0

package/.agents/schemas/lifecycle/epic.plan.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/epic.plan.end.schema.json",
+  "title": "epic.plan.end",
+  "description": "Emitted when the runner finishes building the wave DAG.",
+  "type": "object",
+  "required": ["waves"],
+  "properties": {
+    "waves": {
+      "type": "array",
+      "items": {
+        "type": "array",
+        "items": { "type": "integer", "minimum": 1 }
+      }
+    }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/epic.plan.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.plan.start.schema.json",
+  "title": "epic.plan.start",
+  "description": "Emitted when the runner begins planning waves for an Epic.",
+  "type": "object",
+  "required": ["epicId"],
+  "properties": {
+    "epicId": { "type": "integer", "minimum": 1 }
+  },
+  "additionalProperties": false
+}

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

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/epic.snapshot.end.schema.json",
+  "title": "epic.snapshot.end",
+  "description": "Emitted when the snapshot phase finishes; carries enumerated story IDs the Epic owns.",
+  "type": "object",
+  "required": ["epicId", "storyIds"],
+  "properties": {
+    "epicId": { "type": "integer", "minimum": 1 },
+    "storyIds": {
+      "type": "array",
+      "items": { "type": "integer", "minimum": 1 }
+    }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/epic.snapshot.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.snapshot.start.schema.json",
+  "title": "epic.snapshot.start",
+  "description": "Emitted when the runner enters the snapshot phase for an Epic.",
+  "type": "object",
+  "required": ["epicId"],
+  "properties": {
+    "epicId": { "type": "integer", "minimum": 1 }
+  },
+  "additionalProperties": false
+}

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

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/epic.watch.end.schema.json",
+  "title": "epic.watch.end",
+  "description": "Emitted by Watcher when required checks settle. checkOutcomes maps check-name → terminal state (success | failure | timed_out | skipped). AutomergePredicate subscribes to this event (test-only Watcher path; the production Phase 8.5 boundary is epic.automerge.start).",
+  "type": "object",
+  "required": ["prUrl", "checkOutcomes"],
+  "properties": {
+    "prUrl": { "type": "string", "format": "uri", "minLength": 1 },
+    "checkOutcomes": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string",
+        "enum": [
+          "success",
+          "failure",
+          "neutral",
+          "cancelled",
+          "timed_out",
+          "action_required",
+          "stale",
+          "skipped"
+        ]
+      }
+    }
+  },
+  "additionalProperties": false
+}

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

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/epic.watch.start.schema.json",
+  "title": "epic.watch.start",
+  "description": "Emitted by Watcher when required-check polling begins. Required-check names are resolved from GitHub at runtime via gh pr checks, not from .agentrc.json.",
+  "type": "object",
+  "required": ["prUrl", "requiredChecks"],
+  "properties": {
+    "prUrl": { "type": "string", "format": "uri", "minLength": 1 },
+    "requiredChecks": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/intervention.recorded.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/intervention.recorded.schema.json",
+  "title": "intervention.recorded",
+  "description": "Emitted whenever the host LLM performs an out-of-band manual intervention during an Epic delivery (e.g., AskUserQuestion, manual git restore/reset, --no-ff recovery merge, story-close --skipValidation). The InterventionRecorder listener appends the payload to the epic-run-state-store's manualInterventions array; a non-empty array disqualifies the Epic from auto-merge.",
+  "type": "object",
+  "required": ["epicId", "reason"],
+  "properties": {
+    "epicId": { "type": "integer", "minimum": 1 },
+    "reason": { "type": "string", "minLength": 1 },
+    "source": { "type": "string", "minLength": 1, "default": "host-llm" },
+    "ts": { "type": "string", "format": "date-time" }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/ledger-record.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/ledger-record.schema.json",
+  "title": "Lifecycle ledger record (emitted | completed | failed)",
+  "description": "Append-only NDJSON record shape for temp/epic-<id>/lifecycle.ndjson. Three discriminated kinds; consumers (LedgerWriter, lifecycle-diff CLI, TraceLogger) discriminate on `kind`.",
+  "oneOf": [
+    { "$ref": "#/$defs/emitted" },
+    { "$ref": "#/$defs/completed" },
+    { "$ref": "#/$defs/failed" }
+  ],
+  "$defs": {
+    "emitted": {
+      "type": "object",
+      "required": ["kind", "seqId", "ts", "event", "payload"],
+      "properties": {
+        "kind": { "const": "emitted" },
+        "seqId": { "type": "integer", "minimum": 1 },
+        "ts": { "type": "string", "format": "date-time" },
+        "event": { "type": "string", "minLength": 1 },
+        "payload": { "type": "object" }
+      },
+      "additionalProperties": false
+    },
+    "completed": {
+      "type": "object",
+      "required": ["kind", "seqId", "ts", "event"],
+      "properties": {
+        "kind": { "const": "completed" },
+        "seqId": { "type": "integer", "minimum": 1 },
+        "ts": { "type": "string", "format": "date-time" },
+        "event": { "type": "string", "minLength": 1 },
+        "listener": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    },
+    "failed": {
+      "type": "object",
+      "required": ["kind", "seqId", "ts", "event", "listener", "error"],
+      "properties": {
+        "kind": { "const": "failed" },
+        "seqId": { "type": "integer", "minimum": 1 },
+        "ts": { "type": "string", "format": "date-time" },
+        "event": { "type": "string", "minLength": 1 },
+        "listener": { "type": "string", "minLength": 1 },
+        "error": {
+          "type": "object",
+          "required": ["name", "message"],
+          "properties": {
+            "name": { "type": "string", "minLength": 1 },
+            "message": { "type": "string" },
+            "stack": { "type": "string" }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/.agents/schemas/lifecycle/notification.emitted.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/notification.emitted.schema.json",
+  "title": "notification.emitted",
+  "description": "Self-emitted by NotifyDispatcher after each webhook/comment dispatch. Carries the upstream event name, the channel, the severity, and the ok flag for trace fidelity.",
+  "type": "object",
+  "required": ["event", "channel", "severity", "ok"],
+  "properties": {
+    "event": { "type": "string", "minLength": 1 },
+    "channel": { "type": "string", "enum": ["webhook", "comment"] },
+    "severity": {
+      "type": "string",
+      "enum": ["info", "warn", "error", "critical"]
+    },
+    "ok": { "type": "boolean" }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/pr.created.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/pr.created.schema.json",
+  "title": "pr.created",
+  "description": "Emitted by Finalizer immediately after gh pr create (or short-circuit). Must be preceded by acceptance.reconcile.ok from the same run.",
+  "type": "object",
+  "required": ["prUrl", "head", "base"],
+  "properties": {
+    "prUrl": { "type": "string", "format": "uri", "minLength": 1 },
+    "head": { "type": "string", "minLength": 1 },
+    "base": { "type": "string", "minLength": 1 }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/retro.end.schema.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/retro.end.schema.json",
+  "title": "retro.end",
+  "description": "Emitted at the end of the retro sub-phase. `posted` indicates whether the retro structured comment was upserted onto the Epic; `retroPath` is the local mirror path under temp/epic-<id>/ when written. Story #2252.",
+  "type": "object",
+  "required": ["epicId", "posted"],
+  "properties": {
+    "epicId": { "type": "integer", "minimum": 1 },
+    "posted": { "type": "boolean" },
+    "compact": { "type": "boolean" },
+    "retroPath": { "type": "string", "minLength": 1 },
+    "durationMs": { "type": "integer", "minimum": 0 }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/retro.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/retro.start.schema.json",
+  "title": "retro.start",
+  "description": "Emitted at the start of the retro sub-phase (Phase E of the close-tail). Story #2252.",
+  "type": "object",
+  "required": ["epicId"],
+  "properties": {
+    "epicId": { "type": "integer", "minimum": 1 }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/story.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/story.blocked.schema.json",
+  "title": "story.blocked",
+  "description": "Emitted from the story-close path when a Story transitions to agent::blocked.",
+  "type": "object",
+  "required": ["storyId", "reason"],
+  "properties": {
+    "storyId": { "type": "integer", "minimum": 1 },
+    "reason": { "type": "string", "minLength": 1 }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/story.dispatch.end.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/story.dispatch.end.schema.json",
+  "title": "story.dispatch.end",
+  "description": "Appended to the Epic ledger by emit-story-dispatch-end.js when a child story sub-agent returns, so /epic-deliver's idle watchdog can subtract completed Stories from the in-flight set. Subscribed by CheckpointPointerWriter via SUBSCRIBED_END_EVENTS. Sibling ordering within a wave is not guaranteed; ordering between waves is.",
+  "type": "object",
+  "required": ["storyId", "outcome", "durationMs"],
+  "properties": {
+    "storyId": { "type": "integer", "minimum": 1 },
+    "outcome": {
+      "type": "string",
+      "enum": ["done", "blocked", "failed", "skipped"]
+    },
+    "durationMs": { "type": "integer", "minimum": 0 }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/story.dispatch.start.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/story.dispatch.start.schema.json",
+  "title": "story.dispatch.start",
+  "description": "Emitted before a story is handed to the host-LLM for Agent-tool fanout. lifecycle-emit-story-dispatch.js appends the {storyId, waveIndex, dispatchedAt, attempt} shape to the Epic ledger so /epic-deliver's host loop can durably ledger every dispatch attempt for in-flight reconciliation (Story #2891).",
+  "type": "object",
+  "required": ["storyId", "waveIndex"],
+  "properties": {
+    "storyId": { "type": "integer", "minimum": 1 },
+    "waveIndex": { "type": "integer", "minimum": 0 },
+    "dispatchedAt": { "type": "string", "format": "date-time" },
+    "attempt": { "type": "integer", "minimum": 1 }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/story.heartbeat.schema.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/dsj1984/mandrel/blob/main/.agents/schemas/lifecycle/story.heartbeat.schema.json",
+  "title": "story.heartbeat",
+  "description": "Emitted by story-phase.js inside a Story's implementation loop. Surfaces the in-progress Story as an inspectable ledger event so /epic-deliver's host-loop reconciler can confirm a long Story is still making forward progress between dispatch and merge — distinct from story.dispatch.start (one per Story per attempt) and story.merged (one per Story per close). The 3-tier hierarchy has no child Task tickets, so the heartbeat carries phase info only. The optional operator field (Story #3480) records the handle holding the assignee-as-lease claim on the Story so the ticket-lease primitive can decide claim liveness from the most-recent heartbeat for a given owner.",
+  "type": "object",
+  "required": ["event", "storyId", "epicId", "phase", "timestamp"],
+  "properties": {
+    "event": { "type": "string", "const": "story.heartbeat" },
+    "storyId": { "type": "integer", "minimum": 1 },
+    "epicId": { "type": "integer", "minimum": 1 },
+    "phase": {
+      "type": "string",
+      "enum": ["init", "implementing", "closing", "blocked", "done"]
+    },
+    "timestamp": { "type": "string", "format": "date-time" },
+    "operator": { "type": "string", "minLength": 1 }
+  },
+  "additionalProperties": false
+}

package/.agents/schemas/lifecycle/story.merged.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/story.merged.schema.json",
+  "title": "story.merged",
+  "description": "Emitted from the story-close path after a Story branch successfully merges into epic/<id>.",
+  "type": "object",
+  "required": ["storyId", "sha"],
+  "properties": {
+    "storyId": { "type": "integer", "minimum": 1 },
+    "sha": { "type": "string", "minLength": 7 }
+  },
+  "additionalProperties": false
+}

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

@@ -0,0 +1,58 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mandrel/.agents/schemas/mi-report.schema.json",
+  "title": "MaintainabilityReport",
+  "description": "Structured `--json` output envelope emitted by check-maintainability.js. Parity shape with crap-report (kernelVersion, summary, violations) minus fixGuidance — MI scores don't decompose along the two CRAP axes, so per-violation remediation guidance is intentionally absent.",
+  "type": "object",
+  "required": ["kernelVersion", "summary", "violations"],
+  "additionalProperties": false,
+  "properties": {
+    "kernelVersion": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "description": "MI report envelope version. Bumped when the envelope shape changes."
+    },
+    "summary": {
+      "type": "object",
+      "required": [
+        "total",
+        "regressions",
+        "newFiles",
+        "improvements",
+        "scope",
+        "diffRef"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "total": { "type": "integer", "minimum": 0 },
+        "regressions": { "type": "integer", "minimum": 0 },
+        "newFiles": { "type": "integer", "minimum": 0 },
+        "improvements": { "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", "current", "baseline", "drop", "kind"],
+        "additionalProperties": false,
+        "properties": {
+          "file": { "type": "string" },
+          "current": { "type": "number" },
+          "baseline": { "type": "number" },
+          "drop": { "type": "number" },
+          "kind": { "type": "string", "enum": ["regression"] }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,49 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$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.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["kind", "ticketId", "model", "source", "recordedAt"],
+  "properties": {
+    "kind": { "type": "string", "const": "model-attribution" },
+    "ticketId": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "GitHub Issue number of the Task this attribution is recorded on."
+    },
+    "model": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Canonical model identifier (e.g. 'claude-opus-4-7', 'claude-sonnet-4-6'), or the sentinel 'unknown' when neither SDK metadata nor a runtime env var supplied an identity."
+        },
+        "family": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Coarse model family label for rollup grouping (e.g. 'Opus', 'Sonnet', 'Haiku'). Optional; derived from the id when present."
+        }
+      }
+    },
+    "source": {
+      "type": "string",
+      "enum": ["sdk-metadata", "env", "unknown"],
+      "description": "Provenance of the model identification, in fallback order: 'sdk-metadata' (resolved from the SDK response), 'env' (resolved from a runtime env var), 'unknown' (neither was available)."
+    },
+    "recordedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO-8601 timestamp at which the attribution was recorded."
+    },
+    "sdkMetadata": {
+      "type": "object",
+      "description": "Opaque pass-through fields lifted from the SDK response metadata when available (e.g. response id, usage hints). Never required; never relied upon by the rollup helper.",
+      "additionalProperties": true
+    }
+  }
+}

package/.agents/schemas/qa-finding.schema.json

@@ -0,0 +1,133 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "QaFinding",
+  "description": "Structured `F#` finding emitted by the agent-driven QA harness (`.agents/workflows/qa-run-harness.md`, Epic #3214). One object per genuine problem surfaced while sweeping a consumer's Gherkin scenarios through chrome-devtools MCP: a non-allowlisted console error, a failed/error-status network request, or a gross design-token violation. Findings are validated against this schema before they are bundled by likely root cause into operator-approved follow-up ticket drafts (the harness never files tickets autonomously). The shape mirrors the F# convergence in Tech Spec #3285 and is produced in its console-derived subset by `.agents/scripts/lib/qa/console-allowlist.js`.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "id",
+    "classification",
+    "surface",
+    "symptom",
+    "likelyRootCause",
+    "disposition",
+    "acceptance",
+    "evidence"
+  ],
+  "properties": {
+    "id": {
+      "type": "string",
+      "description": "Stable finding identifier, assigned `F1`, `F2`, … in capture order across a surface.",
+      "pattern": "^F[0-9]+$"
+    },
+    "classification": {
+      "type": "string",
+      "description": "What kind of problem this finding represents. `console-error` and `network-error` are emitted by the instrumentation layer; `design-token` by the visual-inspection layer; `behavior` for a semantic Then-assertion failure.",
+      "enum": ["console-error", "network-error", "design-token", "behavior"]
+    },
+    "surface": {
+      "type": "string",
+      "description": "The surface (route/screen label) the finding was observed on. Falls back to `unknown` when the harness cannot resolve a surface label.",
+      "minLength": 1
+    },
+    "symptom": {
+      "type": "string",
+      "description": "A one-line, user-visible description of the problem. Captured evidence (console/network) MUST already be scrubbed of tokens, session cookies, and PII per `.agents/rules/security-baseline.md` before this is rendered."
+    },
+    "likelyRootCause": {
+      "type": ["string", "null"],
+      "description": "The agent's best assessment of the underlying cause, or `null` when not yet inferred. Used to bundle findings into follow-up tickets in the assisted drafting step."
+    },
+    "disposition": {
+      "type": "string",
+      "description": "Whether the finding blocks the scenario (`blocker`) or is a deferred follow-up (`follow-up`).",
+      "enum": ["blocker", "follow-up"]
+    },
+    "acceptance": {
+      "type": ["string", "null"],
+      "description": "The acceptance condition that would close the follow-up this finding seeds, or `null` when the finding has not yet been promoted to a draft."
+    },
+    "foldsInto": {
+      "type": "string",
+      "description": "Optional. The id of another finding this one is a duplicate of, or folds into during root-cause bundling. Omit for a standalone finding.",
+      "pattern": "^F[0-9]+$"
+    },
+    "security": {
+      "type": "boolean",
+      "description": "Optional. `true` when the finding has a security dimension (e.g. a leaked token, an auth boundary failure, an injection-prone request) and MUST be routed with security baseline scrutiny. Omit or `false` for a non-security finding."
+    },
+    "routedTo": {
+      "type": "object",
+      "description": "Optional finding-to-issue link recording where the finding was routed once it is promoted to a follow-up ticket draft. Omit until the finding has been filed. The same link shape is mirrored on `qa-ledger.schema.json`.",
+      "additionalProperties": false,
+      "required": ["issue", "url", "kind"],
+      "properties": {
+        "issue": {
+          "type": "integer",
+          "description": "The GitHub issue number the finding was routed to.",
+          "minimum": 1
+        },
+        "url": {
+          "type": "string",
+          "description": "The canonical URL of the routed issue.",
+          "minLength": 1
+        },
+        "kind": {
+          "type": "string",
+          "description": "The kind of ticket the finding was routed to: a `story`, an `epic`, or a bare `issue`.",
+          "enum": ["story", "epic", "issue"]
+        }
+      }
+    },
+    "evidence": {
+      "type": "object",
+      "description": "Raw signal supporting the finding. Both arrays are always present (possibly empty) so a console-only or network-only finding still carries a well-formed evidence envelope.",
+      "additionalProperties": false,
+      "required": ["console", "network"],
+      "properties": {
+        "console": {
+          "type": "array",
+          "description": "Captured console messages supporting the finding.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["level", "text"],
+            "properties": {
+              "level": {
+                "type": "string",
+                "description": "Console message level (e.g. `error`, `severe`, `warning`)."
+              },
+              "text": {
+                "type": "string",
+                "description": "Console message text, scrubbed of secrets and PII."
+              }
+            }
+          }
+        },
+        "network": {
+          "type": "array",
+          "description": "Captured network requests supporting the finding.",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["url", "status"],
+            "properties": {
+              "url": {
+                "type": "string",
+                "description": "Request URL, scrubbed of secrets and PII (e.g. query-string tokens)."
+              },
+              "status": {
+                "type": "integer",
+                "description": "HTTP status code of the response (0 when the request never completed)."
+              },
+              "method": {
+                "type": "string",
+                "description": "Optional HTTP method (e.g. `GET`, `POST`)."
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}