{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "River Review Output Schema",
  "description": "Structured output for River Review findings, aggregated per run.",
  "type": "object",
  "required": ["issues", "summary"],
  "additionalProperties": false,
  "properties": {
    "issues": {
      "type": "array",
      "description": "List of individual review issues raised by River Review.",
      "items": {
        "$ref": "#/$defs/issue"
      }
    },
    "summary": {
      "description": "Aggregated counts and optional notes for this review run.",
      "$ref": "#/$defs/summary"
    },
    "decision": {
      "type": "string",
      "enum": ["auto-approve", "human-review-recommended", "human-review-required"],
      "description": "Run-level verdict derived deterministically from findings (same vocabulary as review-artifact decision). Optional; absent when scoring fails."
    },
    "gate": {
      "type": "object",
      "description": "Machine-readable gate signal for loop-running hosts (Epic #1347 S2 / #1349). Same shape and trust-boundary contract as the `gate` object in review-artifact.schema.json (the authoritative definition — see that schema and src/lib/gate-decision.mjs). Additive/optional. Note: the `river run` path performs no plan-text human-approval scan, so inputs.humanApprovalRequired is always false here; the plan-review cliff applies to the `river review` namespace. Additionally, inputs.riskMapDigest is always null on this path (the raw risk map is not available at output formatting time), so inputsHash values are not comparable across the run / review namespaces."
    },
    "timedOutRoles": {
      "type": "array",
      "description": "Reviewer roles cut off by the per-role orchestration timeout (#1689). Additive/optional and emitted only when at least one role timed out, so its absence means no role was cut off. A consumer must read this before treating an empty `issues` list as a clean review: a timed-out role contributed no findings because it never returned. Set the limit via RIVER_REVIEWER_TIMEOUT or review.orchestrator.timeoutMs; it is disabled by default.",
      "items": {
        "type": "string",
        "minLength": 1
      }
    },
    "teamLeadReport": {
      "description": "Tech Lead synthesis of a multi-role run (#1700). Emitted only when the run went through reviewer orchestration (`--reviewers`), so its absence means a single-reviewer run. Produced by synthesizeTeamLeadReport (src/lib/team-lead-synthesizer.mjs) with no LLM call — every field is a deterministic aggregation of the same findings already listed in `issues`. Additive/optional and display-only: it MUST NOT override severity, `decision`, or `gate`.",
      "$ref": "#/$defs/teamLeadReport"
    }
  },
  "$defs": {
    "issue": {
      "type": "object",
      "required": ["id", "ruleId", "title", "message", "severity", "phase", "file"],
      "additionalProperties": false,
      "properties": {
        "id": {
          "type": "string",
          "description": "Unique identifier for the issue within this run.",
          "minLength": 1
        },
        "ruleId": {
          "type": "string",
          "description": "Identifier of the rule or skill that produced the issue.",
          "minLength": 1
        },
        "title": {
          "type": "string",
          "description": "Short human-readable title for the issue.",
          "minLength": 1
        },
        "message": {
          "type": "string",
          "description": "Detailed explanation of the issue and context.",
          "minLength": 1
        },
        "severity": {
          "type": "string",
          "description": "Severity level assigned to the issue.",
          "enum": ["info", "minor", "major", "critical"]
        },
        "phase": {
          "type": "string",
          "description": "SDLC phase where this issue was found.",
          "enum": ["upstream", "midstream", "downstream"]
        },
        "file": {
          "type": "string",
          "description": "File path or logical name relevant to the issue.",
          "minLength": 1
        },
        "line": {
          "type": "integer",
          "description": "Line number related to the issue when applicable.",
          "minimum": 1
        },
        "lineEnd": {
          "type": "integer",
          "description": "End line number for multi-line issues.",
          "minimum": 1
        },
        "confidence": {
          "type": "string",
          "description": "Confidence level of the finding.",
          "enum": ["high", "medium", "low"]
        },
        "status": {
          "type": "string",
          "description": "Current lifecycle status of the finding.",
          "enum": ["open", "suppressed", "verified"]
        },
        "evidence": {
          "type": "array",
          "description": "Evidence snippets supporting this finding.",
          "items": {
            "type": "string"
          }
        },
        "reviewer": {
          "type": "string",
          "description": "Identifier of the skill or agent that produced this finding."
        },
        "suggestion": {
          "type": "string",
          "description": "Optional fix or follow-up hint."
        },
        "scope": {
          "type": "string",
          "enum": ["in-diff", "pre-existing"],
          "description": "Whether the finding is introduced by this diff's added lines ('in-diff') or lives in a changed file but outside the added lines ('pre-existing'). Additive/optional metadata (#1644 Phase 1): derived deterministically by the verifier from the parsed diff, falling back to the reviewer's self-report. Absent or unknown MUST be read as 'in-diff' (fail-safe: never demote). Display-only — MUST NOT override severity or gate decisions."
        },
        "criterionRefs": {
          "type": "array",
          "description": "Optional acceptance-criterion / test-case identifiers this finding is tied to (e.g. AC-4, TC-7). Additive/optional traceability metadata (#1666, #1545 Phase 2) closing the Test/AC -> Finding back-reference. River Review does not own this ID namespace: the values are copied verbatim from the upstream artifact and are neither minted nor validated here. Absent when the artifact is missing. Display-only — MUST NOT override severity or gate decisions.",
          "items": { "type": "string", "minLength": 1 }
        },
        "artifactRefs": {
          "type": "array",
          "description": "Optional artifact anchors this finding is tied to (e.g. plan.md#AC-4, todo.md#TASK-3). Additive/optional traceability metadata (#1666, #1545 Phase 2). River Review does not own this ID namespace: the values are copied verbatim from the upstream artifact and are neither minted nor validated here. Absent when the artifact is missing. Display-only — MUST NOT override severity or gate decisions.",
          "items": { "type": "string", "minLength": 1 }
        },
        "consensusLevel": {
          "type": "string",
          "enum": ["consensus", "multi", "single"],
          "description": "How many reviewer roles independently raised this finding: consensus = 3+, multi = 2, single = 1 (computeConsensusLevel in src/lib/reviewer-orchestrator.mjs). Emitted only by multi-role runs (`--reviewers`); absent otherwise (#1700). Display-only ranking metadata — MUST NOT override severity or gate decisions."
        },
        "reviewerRole": {
          "type": "string",
          "minLength": 1,
          "description": "Reviewer role that first raised this finding (a key of REVIEWER_ROLES in src/lib/reviewer-orchestrator.mjs, e.g. bug-hunter / security-scanner). Emitted only by multi-role runs (`--reviewers`); absent otherwise (#1700). Deliberately not an enum so adding a role does not turn every run's output into a schema violation."
        },
        "actionability": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Optional 0-1 score of how clear/actionable the fix is (derived from the suggestion). Independent of the composite score."
        }
      }
    },
    "teamLeadReport": {
      "type": "object",
      "required": ["top3Findings", "blindSpots", "consensusSummary"],
      "additionalProperties": false,
      "properties": {
        "top3Findings": {
          "type": "array",
          "maxItems": 3,
          "description": "The highest-priority findings, ranked by consensusLevel then severity then scope, and capped at three (sortFindingsByPriority in src/lib/team-lead-synthesizer.mjs). consensusLevel still outranks severity; scope only orders findings that tie on both of the first two keys, placing `in-diff` before `pre-existing` (#1644). Every entry is also present in `issues`; correlate by `id`.",
          "items": { "$ref": "#/$defs/teamLeadFinding" }
        },
        "blindSpots": {
          "type": "array",
          "description": "Reviewer roles that did NOT cover this run — every REVIEWER_ROLES entry that was not selected, timed out, or failed (detectBlindSpots / isRoleCovered in src/lib/team-lead-synthesizer.mjs). Read this before treating a short `issues` list as a clean review: an uncovered role contributed no findings because it never looked.",
          "items": {
            "type": "object",
            "required": ["role", "label"],
            "additionalProperties": false,
            "properties": {
              "role": {
                "type": "string",
                "minLength": 1,
                "description": "Role key, as in `issues[].reviewerRole` (e.g. frontend-reviewer)."
              },
              "label": {
                "type": "string",
                "minLength": 1,
                "description": "Human-readable role name (REVIEWER_ROLES[role].label, e.g. Frontend Reviewer)."
              }
            }
          }
        },
        "consensusSummary": {
          "type": "object",
          "description": "Finding counts bucketed by consensusLevel, plus the total (buildConsensusSummary in src/lib/team-lead-synthesizer.mjs). Counted over ALL findings, not just the three in top3Findings.",
          "required": ["consensus", "multi", "single", "total"],
          "additionalProperties": false,
          "properties": {
            "consensus": { "type": "integer", "minimum": 0 },
            "multi": { "type": "integer", "minimum": 0 },
            "single": { "type": "integer", "minimum": 0 },
            "total": { "type": "integer", "minimum": 0 }
          }
        }
      }
    },
    "teamLeadFinding": {
      "type": "object",
      "description": "A finding echoed verbatim into teamLeadReport.top3Findings. This is the INTERNAL finding object, not the `issues` shape: it carries lineStart/lineEnd rather than line/lineEnd, adds agreement/reviewerRole/chunkLabel, and has no `phase`. Only `id` and `severity` are required — both are set unconditionally on every finding by the orchestrator (id in the allFindings map, severity by mergeFindings via normalizeSeverity/maxSeverity in src/lib/reviewer-orchestrator.mjs). Deliberately NOT `additionalProperties: false`, unlike the rest of this schema: formatJsonOutput copies teamLeadReport through without an allowlist, so the field set is owned by src/lib/review-engine.mjs, and pinning it here would make every future additive finding field reintroduce the permanent stderr warning this declaration removes (#1700). The authoritative per-finding contract stays `$defs/issue`.",
      "required": ["id", "severity"],
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "description": "Matches the `id` of the corresponding entry in `issues`."
        },
        "ruleId": { "type": "string" },
        "file": { "type": "string" },
        "lineStart": {
          "type": ["integer", "null"],
          "description": "Start line, or null when the finding is not line-anchored. Named lineStart here, `line` in `issues`."
        },
        "lineEnd": { "type": ["integer", "null"] },
        "title": { "type": "string" },
        "message": { "type": "string" },
        "severity": {
          "type": "string",
          "enum": ["info", "minor", "major", "critical"]
        },
        "confidence": {
          "type": "string",
          "enum": ["high", "medium", "low"]
        },
        "status": {
          "type": "string",
          "enum": ["open", "suppressed", "verified"]
        },
        "evidence": {
          "type": "array",
          "items": { "type": "string" }
        },
        "suggestion": { "type": ["string", "null"] },
        "scope": {
          "type": "string",
          "enum": ["in-diff", "pre-existing"]
        },
        "criterionRefs": {
          "type": ["array", "null"],
          "items": { "type": "string" }
        },
        "artifactRefs": {
          "type": ["array", "null"],
          "items": { "type": "string" }
        },
        "reviewerRole": { "type": "string" },
        "chunkLabel": {
          "type": ["string", "null"],
          "description": "Diff chunk this finding came from, or null when the diff was not split."
        },
        "agreement": {
          "type": "array",
          "description": "Every reviewer role that raised this finding; its length is what consensusLevel buckets.",
          "items": { "type": "string" }
        },
        "consensusLevel": {
          "type": "string",
          "enum": ["consensus", "multi", "single"]
        }
      }
    },
    "summary": {
      "type": "object",
      "required": ["issueCountBySeverity", "issueCountByPhase"],
      "additionalProperties": false,
      "properties": {
        "issueCountBySeverity": {
          "type": "object",
          "description": "Aggregated counts keyed by severity.",
          "required": ["info", "minor", "major", "critical"],
          "additionalProperties": false,
          "properties": {
            "info": {
              "type": "integer",
              "minimum": 0
            },
            "minor": {
              "type": "integer",
              "minimum": 0
            },
            "major": {
              "type": "integer",
              "minimum": 0
            },
            "critical": {
              "type": "integer",
              "minimum": 0
            }
          }
        },
        "issueCountByPhase": {
          "type": "object",
          "description": "Aggregated counts keyed by SDLC phase.",
          "required": ["upstream", "midstream", "downstream"],
          "additionalProperties": false,
          "properties": {
            "upstream": {
              "type": "integer",
              "minimum": 0
            },
            "midstream": {
              "type": "integer",
              "minimum": 0
            },
            "downstream": {
              "type": "integer",
              "minimum": 0
            }
          }
        },
        "notes": {
          "type": "string",
          "description": "Optional run-level notes or caveats."
        },
        "riskSummary": {
          "type": "object",
          "description": "Risk assessment summary from risk map evaluation.",
          "required": ["aggregateAction", "escalatedFiles", "humanReviewFiles"],
          "additionalProperties": false,
          "properties": {
            "aggregateAction": {
              "type": "string",
              "enum": ["comment_only", "escalate", "require_human_review"]
            },
            "escalatedFiles": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "humanReviewFiles": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        },
        "prioritySummary": {
          "type": "object",
          "description": "Priority rollup derived from severity (P1=critical, P2=major, P3=minor, P4=info). Optional for backward compatibility; always emitted by current river run.",
          "required": ["counts", "requiresImmediateAttention"],
          "additionalProperties": false,
          "properties": {
            "counts": {
              "type": "object",
              "description": "Issue counts keyed by priority bucket.",
              "required": ["P1", "P2", "P3", "P4"],
              "additionalProperties": false,
              "properties": {
                "P1": {
                  "type": "integer",
                  "minimum": 0
                },
                "P2": {
                  "type": "integer",
                  "minimum": 0
                },
                "P3": {
                  "type": "integer",
                  "minimum": 0
                },
                "P4": {
                  "type": "integer",
                  "minimum": 0
                }
              }
            },
            "requiresImmediateAttention": {
              "type": "boolean",
              "description": "True when one or more P1 (critical) issues are present."
            }
          }
        }
      }
    }
  }
}