{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://civitas-cerebrum.github.io/element-interactions/schemas/subagent-returns/workflow-reviewer.schema.json",
  "title": "Workflow-reviewer return",
  "description": "Return shape for the workflow-reviewer-phase<N>: / -pass<N>: / -cycle<N>: subagent family. Fires between each onboarding phase / coverage-expansion pass / journey-mapping cycle. Gates the next transition: on approve, the orchestrator advances; on reject (cap 3), the orchestrator surgically fixes per findings + re-dispatches the same reviewer; on the 3rd consecutive reject the reviewer returns escalated-to-user and the run pauses for human triage.",
  "type": "object",
  "additionalProperties": true,
  "required": ["handover", "verdict"],
  "properties": {
    "handover": {
      "allOf": [
        { "$ref": "handover.schema.json" },
        {
          "type": "object",
          "properties": {
            "role": {
              "type": "string",
              "pattern": "^workflow-reviewer-(phase[1-8]|pass[1-5]|cycle[1-5])$"
            },
            "status": {
              "enum": ["approved", "rejected", "escalated-to-user"]
            }
          }
        }
      ]
    },
    "verdict": {
      "type": "string",
      "enum": ["approve", "reject", "escalate"]
    },
    "phase": {
      "type": ["integer", "null"],
      "minimum": 1,
      "maximum": 8,
      "description": "Onboarding phase being reviewed (workflow-reviewer-phase<N> only)."
    },
    "pass": {
      "type": ["integer", "null"],
      "minimum": 1,
      "maximum": 5,
      "description": "Coverage-expansion pass being reviewed (workflow-reviewer-pass<N> only)."
    },
    "cycle": {
      "type": ["integer", "null"],
      "minimum": 1,
      "maximum": 5,
      "description": "Journey-mapping cycle being reviewed (workflow-reviewer-cycle<N> only). Distinct from the handover envelope's cycle field (which records the reviewer's own dispatch cycle, capped at 3)."
    },
    "checklist": {
      "type": "array",
      "description": "Per-item pass/fail of the canonical methodology exit criteria.",
      "items": {
        "type": "object",
        "additionalProperties": true,
        "required": ["item", "satisfied"],
        "properties": {
          "item": { "type": "string" },
          "satisfied": { "type": "boolean" },
          "evidence": { "type": "string" },
          "methodology-ref": { "type": "string" }
        }
      }
    },
    "findings": {
      "type": "array",
      "description": "Surgical fix list. Required when verdict == 'reject'. Empty when verdict == 'approve'.",
      "items": {
        "type": "object",
        "additionalProperties": true,
        "required": ["checklist-item", "what-missing", "fix-instruction"],
        "properties": {
          "checklist-item": { "type": "string" },
          "what-missing": { "type": "string" },
          "methodology-ref": { "type": "string" },
          "fix-instruction": { "type": "string" }
        }
      }
    },
    "attestation": {
      "type": "string",
      "description": "One-line summary of what was verified. Required when verdict == 'approve'."
    },
    "authorizer": {
      "type": "string",
      "description": "Required when the reviewer approves a skip / early-stop transition. Must carry either a verbatim user quote OR a documented structural exception (e.g. 'phase6-redundant-with-phase5: depth Pass 4+5 already provided adversarial coverage; user pre-authorised via args')."
    },
    "reviewerCycle": {
      "type": "integer",
      "minimum": 1,
      "maximum": 3,
      "description": "Which workflow-reviewer dispatch this is for the phase / pass / cycle. The orchestrator increments per reject."
    },
    "summary": { "type": "string" }
  },
  "allOf": [
    {
      "if": {
        "type": "object",
        "properties": { "verdict": { "const": "approve" } }
      },
      "then": {
        "type": "object",
        "required": ["attestation"],
        "properties": {
          "attestation": { "type": "string", "minLength": 1 }
        }
      }
    },
    {
      "if": {
        "type": "object",
        "properties": { "verdict": { "const": "reject" } }
      },
      "then": {
        "type": "object",
        "required": ["findings"],
        "properties": {
          "findings": { "type": "array", "minItems": 1 }
        }
      }
    },
    {
      "if": {
        "type": "object",
        "properties": { "verdict": { "const": "escalate" } }
      },
      "then": {
        "type": "object",
        "required": ["findings"],
        "properties": {
          "findings": { "type": "array", "minItems": 1 }
        }
      }
    }
  ]
}