{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://civitas-cerebrum.github.io/element-interactions/schemas/subagent-returns/handover.schema.json",
  "title": "Subagent handover envelope",
  "description": "Mandatory envelope at the top of every skill-loading subagent return. Includes optional dispatch-mode + parallel-wave-size fields that the workflow reviewer inspects on cycle-1 (journey-mapping) and pass-1 (coverage-expansion) returns to reject grouped or single-agent-collapsed first-cycle/first-pass work (reviewer-enforced; the dispatch-side half is harness-enforced by hooks/standard-mode-first-pass-guard.sh).",
  "type": "object",
  "additionalProperties": true,
  "required": ["role", "status", "next-action"],
  "properties": {
    "role": {
      "type": "string",
      "minLength": 1,
      "description": "Role slug. Pattern guidance: kebab-case, optionally with journey suffix."
    },
    "cycle": {
      "type": ["integer", "string"],
      "minimum": 1,
      "description": "Cycle number within the role's dispatch loop (accepts integer ≥ 1 or numeric string; the minimum applies to the integer form)."
    },
    "status": {
      "type": "string",
      "description": "Role-specific terminal-or-continuation status."
    },
    "next-action": {
      "type": "string",
      "minLength": 1,
      "description": "One-line directive for the orchestrator."
    },
    "dispatch-mode": {
      "type": "string",
      "enum": ["per-journey", "per-section", "grouped", "single-agent-collapsed"],
      "description": "How the dispatch was structured. REQUIRED on returns for cycle 1 of journey-mapping or Pass 1 of coverage-expansion. Cycle-1 / pass-1 returns whose dispatch-mode is `grouped` or `single-agent-collapsed` violate the strict-per-X contract and are rejected by the workflow reviewer (reviewer-enforced; no hook inspects this field — the dispatch-side half is harness-enforced by hooks/standard-mode-first-pass-guard.sh). `per-journey` applies to coverage-expansion composers/probes; `per-section` applies to journey-mapping section agents; `grouped` covers `[group]` / `[P3-batch]` wrappers; `single-agent-collapsed` is the anti-pattern of a single subagent doing the work of an entire wave."
    },
    "parallel-wave-size": {
      "type": "integer",
      "minimum": 1,
      "description": "Size of the parallel wave this dispatch was part of. When `dispatch-mode == per-journey` or `per-section`, must be ≥ 1. On cycle-1 / pass-1, `parallel-wave-size == 1` violates the contract — rejected by the workflow reviewer — UNLESS the roster genuinely contains only one item (in which case `dispatch-mode: per-journey` with wave-size 1 is correct)."
    }
  }
}