Task contract schema

Task Schema

The PAA task declaration is five orientation groups: boundary, evidence log, evaluator, promotion rule, and demotion. The schema below captures that structure as a downloadable JSON Schema artifact.

Download the schema

Download paa-task.schema.json — JSON Schema draft-07 covering all five orientation groups. Use it to validate task declarations in CI or tooling. The schema is hand-authored to match the canonical example below exactly and checked by npm run check; no runtime validation dependency is required to use this site.

Schema structure

A valid PAA task declaration is an object with six required keys: task, boundary, evidence_log, evaluator, promotion_rule, and demotion.

boundary — typed input and output keys. The boundary defines the observable unit; nothing is a PAA task without one.
evidence_log — an array of string identifiers naming the fields appended to the log on every execution.
evaluator — four keys: target, technique, oracle, and position_policy. Oracle and position policy are nested inside the evaluator because they are properties of the verdict producer.
promotion_rule — three keys: metric, threshold, and window. Threshold and window are strings to allow domain-calibrated expressions; illustrative values in the example below are not normative.
demotion — two keys: rule (an object with condition and window) and fallback (the safe lower-autonomy path the task lands on).

Canonical example

refund_approval validates against the schema

The declaration below is the canonical PAA example. Its shape is the schema in concrete form. The threshold (>= 0.97) and window (rolling_200_cases) are illustrative figures for a refund classifier — calibrate both to your domain before use.

Boundary

Typed input: refund_request. Typed 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 — approve each decision before it executes
hotl: async — review batch after execution
autonomous: offline — periodic spot checks

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

refund_approval YAML example

task: refund_approval
boundary:
  input: refund_request
  output: decision            # approve | escalate
evidence_log:
  - request
  - proposal
  - verdict
  - decision
  - chargeback_signal
  - complaint_signal
  - review
evaluator:
  target: output
  technique: escalation_classifier
  oracle: human_gold          # labeled escalation decisions
  position_policy:
    hitl: blocking            # approve each decision before it executes
    hotl: async               # review batch after execution
    autonomous: offline       # periodic spot checks
promotion_rule:
  metric: recall_on_should_escalate
  threshold: ">= 0.97"       # illustrative — calibrate to your domain
  window: rolling_200_cases   # illustrative — calibrate to your domain
demotion:
  rule:
    condition: chargebacks_or_complaints_exceed_bound
    window: 1                 # point demotion
  fallback: human_review

Conformance

Conformance to the PAA task model means meeting the eight commitments — typed boundary (input and output), evidence log, evaluator target, evaluator technique, evaluator oracle, position policy, promotion rule, and demotion with fallback — not matching the exact field names in this schema. The schema is one serialization of the model. Teams may adapt field names to their tooling as long as each commitment is present and correctly owned.

The full model definition and the shared canonical rendering live on Framework.