{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://example.com/pipeline/clarify-output.schema.json",
  "title": "Clarification Output",
  "description": "Schema for Phase 0 Step 9 task-clarifier sub-agent output. Source: pipeline/agents/task-clarifier.md. A clarifying-question loop that runs before planning.",
  "type": "object",
  "additionalProperties": false,
  "required": ["clarityScore", "questions", "stopAndAsk"],
  "properties": {
    "clarityScore": {
      "type": "integer",
      "minimum": 0,
      "maximum": 10,
      "description": "How clearly the task is specified  -  10 = crystal clear, 0 = title-only. Rubric in task-clarifier.md."
    },
    "rationale": {
      "type": "string",
      "description": "One-sentence justification for the score, citing the line of the issue body that drove it."
    },
    "stopAndAsk": {
      "type": "boolean",
      "description": "Orchestrator-facing flag. true → Phase 0 pauses and asks the user (interactive) or follows autopilotMode (autopilot). false → proceed silently to Phase 1."
    },
    "questions": {
      "type": "array",
      "maxItems": 5,
      "description": "Clarifying questions to ask. Empty array when stopAndAsk is false.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["id", "text"],
        "properties": {
          "id": {
            "type": "string",
            "pattern": "^q[0-9]+$",
            "description": "Stable identifier within this clarification round (q1, q2, ...)."
          },
          "text": {
            "type": "string",
            "description": "Question to display to the user. One sentence, ends with a question mark."
          },
          "options": {
            "type": "array",
            "minItems": 2,
            "maxItems": 4,
            "description": "Discrete answer choices. Omit when the answer is genuinely free-text (an identifier, URL, number).",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": ["label"],
              "properties": {
                "label": {
                  "type": "string",
                  "description": "The choice text (≤ 60 chars; longer wraps awkwardly in AskUserQuestion)."
                },
                "recommended": {
                  "type": "boolean",
                  "default": false,
                  "description": "True for the conventional default. At most one option per question carries this flag."
                },
                "reason": {
                  "type": "string",
                  "description": "One-line tradeoff hint  -  why this choice would or would not be the right pick."
                }
              }
            }
          },
          "reason": {
            "type": "string",
            "description": "Why this question is being asked  -  cite the source of ambiguity, ideally quoting the issue line."
          }
        }
      }
    },
    "userAnswers": {
      "type": "object",
      "description": "Filled in AFTER the orchestrator runs AskUserQuestion. Keys are question IDs (q1, q2, ...) and values are the selected label or free-text response. Empty during the agent's own emission.",
      "additionalProperties": { "type": "string" }
    },
    "tokens_in": { "type": "integer", "minimum": 0 },
    "tokens_out": { "type": "integer", "minimum": 0 },
    "duration_ms": { "type": "integer", "minimum": 0 }
  }
}