{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://paa.dev/paa-task.schema.json",
  "title": "PAA Task Declaration",
  "description": "Schema for a Progressive Autonomy Architecture task declaration. Five orientation groups: boundary, evidence_log, evaluator, promotion_rule, demotion.",
  "type": "object",
  "required": ["task", "boundary", "evidence_log", "evaluator", "promotion_rule", "demotion"],
  "additionalProperties": false,
  "properties": {
    "task": {
      "type": "string",
      "description": "Unique identifier for this task declaration."
    },
    "boundary": {
      "type": "object",
      "description": "Typed input and typed output that define the observable unit. A task is not eligible for the autonomy spectrum until its boundary is declared.",
      "required": ["input", "output"],
      "additionalProperties": false,
      "properties": {
        "input": {
          "type": "string",
          "description": "The typed input to the task."
        },
        "output": {
          "type": "string",
          "description": "The typed output of the task."
        }
      }
    },
    "evidence_log": {
      "type": "array",
      "description": "Append-only record of inputs, proposals, verdicts, gate decisions, outcomes, and review results. Funds every promotion and demotion decision.",
      "items": {
        "type": "string"
      },
      "minItems": 1
    },
    "evaluator": {
      "type": "object",
      "description": "The verdict-producing mechanism. Defines what gets evaluated, what produces the verdict, what the verdict is checked against, and how the gate behaves at each spectrum region.",
      "required": ["target", "technique", "oracle", "position_policy"],
      "additionalProperties": false,
      "properties": {
        "target": {
          "type": "string",
          "description": "What gets evaluated: input, process, output, or outcome."
        },
        "technique": {
          "type": "string",
          "description": "What produces the verdict: rule, metric, classifier, LLM judge, or human."
        },
        "oracle": {
          "type": "string",
          "description": "What the verdict is checked against: an invariant, a reference, a rubric, human gold, or a downstream result."
        },
        "position_policy": {
          "type": "object",
          "description": "How the gate behaves at each spectrum region. Declared as a policy by region, not as a single current runtime position.",
          "additionalProperties": false,
          "minProperties": 1,
          "properties": {
            "assisted": {
              "type": "string",
              "description": "Gate behavior at the assisted region."
            },
            "hitl": {
              "type": "string",
              "description": "Gate behavior at the human-in-the-loop region."
            },
            "hotl": {
              "type": "string",
              "description": "Gate behavior at the human-on-the-loop region."
            },
            "autonomous": {
              "type": "string",
              "description": "Gate behavior at the autonomous region."
            }
          }
        }
      }
    },
    "promotion_rule": {
      "type": "object",
      "description": "The evidence threshold that moves a task toward more autonomy. Reads the evidence log and raises autonomy when an aggregate signal holds above a threshold across an evidence window.",
      "required": ["metric", "threshold", "window"],
      "additionalProperties": false,
      "properties": {
        "metric": {
          "type": "string",
          "description": "The aggregate signal read from the evidence log."
        },
        "threshold": {
          "type": "string",
          "description": "The threshold the metric must hold above to trigger promotion. Example: '>= 0.97'. Calibrate to your domain."
        },
        "window": {
          "type": "string",
          "description": "The evidence window over which the metric is evaluated. Example: 'rolling_200_cases'. Calibrate to your domain."
        }
      }
    },
    "demotion": {
      "type": "object",
      "description": "The trigger rule and the fallback implementation: what breach causes demotion, and what the task lands on.",
      "required": ["rule", "fallback"],
      "additionalProperties": false,
      "properties": {
        "rule": {
          "type": "object",
          "description": "The condition that fires demotion.",
          "required": ["condition", "window"],
          "additionalProperties": false,
          "properties": {
            "condition": {
              "type": "string",
              "description": "The breach condition that triggers demotion."
            },
            "window": {
              "type": "integer",
              "minimum": 1,
              "description": "The lookback window for evaluating the condition. A value of 1 means point demotion on any single occurrence."
            }
          }
        },
        "fallback": {
          "type": "string",
          "description": "The safe lower-autonomy path the task runs when the gate blocks or demotion fires. The destination of a demotion."
        }
      }
    }
  },
  "examples": [
    {
      "task": "refund_approval",
      "boundary": {
        "input": "refund_request",
        "output": "decision"
      },
      "evidence_log": [
        "request",
        "proposal",
        "verdict",
        "decision",
        "chargeback_signal",
        "complaint_signal",
        "review"
      ],
      "evaluator": {
        "target": "output",
        "technique": "escalation_classifier",
        "oracle": "human_gold",
        "position_policy": {
          "hitl": "blocking",
          "hotl": "async",
          "autonomous": "offline"
        }
      },
      "promotion_rule": {
        "metric": "recall_on_should_escalate",
        "threshold": ">= 0.97",
        "window": "rolling_200_cases"
      },
      "demotion": {
        "rule": {
          "condition": "chargebacks_or_complaints_exceed_bound",
          "window": 1
        },
        "fallback": "human_review"
      }
    }
  ]
}