{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://dsolisp.github.io/gavel/schemas/result-envelope.schema.json",
  "title": "Gavel result envelope",
  "description": "Source of truth for gavel-result-envelope machine output (gavel analyze --json-envelope, gavel audit --json-envelope). templates/result-envelope.md embeds the examples below; verify-docs.js checks drift.",
  "type": "object",
  "additionalProperties": false,
  "required": ["schema", "generatedAt", "status", "project"],
  "properties": {
    "schema": { "type": "string", "pattern": "^gavel-result-envelope/1\\.[0-9]+\\.[0-9]+$" },
    "generatedAt": { "type": "string" },
    "status": { "enum": ["DONE", "INCOMPLETE", "BLOCKED", "APP BUG", "ENV ISSUE", "FLAKY"] },
    "project": { "type": "string" },
    "date": { "type": "string" },
    "leadSummary": {
      "type": "object",
      "additionalProperties": false,
      "required": ["passRate", "failed", "total", "format", "rootCause", "nextAction"],
      "properties": {
        "passRate": { "type": "number", "minimum": 0 },
        "failed": { "type": "integer", "minimum": 0 },
        "total": { "type": "integer", "minimum": 0 },
        "format": { "type": "string" },
        "rootCause": { "type": "string" },
        "nextAction": { "type": "string" }
      }
    },
    "clusters": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["area", "pattern", "count", "classification", "nextAction"],
        "properties": {
          "area": { "type": "string" },
          "pattern": { "type": "string" },
          "count": { "type": "integer", "minimum": 1 },
          "classification": { "type": "string" },
          "nextAction": { "type": "string" },
          "suspectCommits": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": ["hash", "message", "searchPath"],
              "properties": {
                "hash": { "type": "string" },
                "message": { "type": "string" },
                "searchPath": { "type": "string" }
              }
            }
          }
        }
      }
    },
    "findings": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["tag", "severity", "file"],
        "properties": {
          "tag": { "type": "string" },
          "severity": { "enum": ["blocker", "fix", "cleanup", "delete", "report"] },
          "file": { "type": "string" },
          "line": { "type": "integer", "minimum": 1 },
          "message": { "type": "string" },
          "snippet": { "type": "string" },
          "confidence": { "enum": ["high", "medium", "low"] }
        }
      }
    },
    "note": { "type": "string" }
  },
  "examples": [
    {
      "schema": "gavel-result-envelope/1.1.0",
      "generatedAt": "2026-07-09T12:00:00.000Z",
      "status": "DONE",
      "project": "example-suite",
      "date": "2026-07-09",
      "leadSummary": {
        "passRate": 92.5,
        "failed": 3,
        "total": 40,
        "format": "playwright",
        "rootCause": "test-maintenance-drift",
        "nextAction": "gavel-impact → gavel-healer"
      },
      "clusters": [
        {
          "area": "catalog",
          "pattern": "locator-timeout",
          "count": 3,
          "classification": "test-maintenance-drift",
          "nextAction": "gavel-impact → gavel-healer",
          "suspectCommits": [
            {
              "hash": "a1b2c3d",
              "message": "renamed toolbar actions",
              "searchPath": "src/catalog"
            }
          ]
        }
      ],
      "note": "Suspect commits auto-correlated per cluster using area-map paths."
    },
    {
      "schema": "gavel-result-envelope/1.1.0",
      "generatedAt": "2026-07-09T12:00:00.000Z",
      "status": "DONE",
      "project": "example-suite",
      "findings": [
        {
          "tag": "manual-wait",
          "severity": "blocker",
          "file": "tests/e2e/checkout.spec.ts",
          "line": 42,
          "message": "Manual sleeps or arbitrary polling"
        },
        {
          "tag": "dead-pom",
          "severity": "delete",
          "file": "pages/UnusedPage.ts",
          "message": "page object never imported"
        },
        {
          "tag": "skip-marker",
          "severity": "fix",
          "file": "tests/e2e/checkout.spec.ts",
          "line": 57,
          "message": "Skip, quarantine, or WIP marker without reason"
        }
      ],
      "note": "confidence appears only when the RULES registry defines it (heuristic rules)."
    }
  ]
}