{
  "uas": {
    "version": "1.0"
  },
  "agent": {
    "id": "[unique, stable, kebab-case id]",
    "name": "[display name]",
    "version": "[semver, e.g. 0.1.0]",
    "status": "[draft | pilot | production | deprecated | retired]",
    "summary": "[one sentence: what this agent does]",
    "categories": [
      "[e.g. inventory | replenishment | procurement | demand-planning | ...]"
    ],
    "kind": "[single | orchestrator | member]",
    "owner": {
      "organization": "[org]",
      "contact": "[reachable mailbox/URI, not a person's name]"
    },
    "operating_regions": [
      "[ISO 3166-1 alpha-2 codes, optional]"
    ],
    "context": {
      "excluded": [
        {
          "id": "[exc-id]",
          "statement": "[something this agent will NEVER do -- at least one required]"
        }
      ],
      "assumptions": [
        {
          "id": "[asm-id]",
          "statement": "[a precondition the agent relies on]",
          "criticality": "[high | medium | low]"
        }
      ],
      "constraints": [
        {
          "id": "[con-id]",
          "statement": "[an operating constraint]",
          "source": "[where this comes from, optional]"
        }
      ],
      "dependencies": [
        {
          "id": "[dep-id]",
          "statement": "[a non-system precondition]"
        }
      ]
    }
  },
  "capabilities": [
    {
      "id": "[cap-id]",
      "name": "[capability name]",
      "kind": "[sense | analyze | predict | recommend | execute | converse | orchestrate]",
      "statement": "[the business outcome this capability produces, not the mechanism]",
      "metrics": [
        "[metric id, e.g. fill-rate, forecast-mape -- see uas-1.0.schema.json #/$defs/metric for the controlled vocabulary]"
      ],
      "locator": {
        "file": "[relative path from the source root]",
        "symbol": "[function/class/route name -- NOT a line number, which drifts]"
      }
    }
  ],
  "decisions": [
    {
      "id": "[dec-id]",
      "name": "[decision name]",
      "capability": "[id of a capability above]",
      "statement": "[exactly what is being decided]",
      "authority": "[observe | recommend | act-with-approval | act-with-oversight | act-autonomous]",
      "trigger": {
        "kind": "[event | schedule | threshold | request]",
        "detail": "[what triggers this decision]"
      },
      "inputs": [
        "[id of an interfaces.consumes entry]"
      ],
      "executes_via": [
        "[id of an interfaces.produces entry, required if this decision has a side effect]"
      ],
      "reversibility": "[reversible | compensable | irreversible]",
      "reversal": "[how to reverse/compensate -- required unless reversibility is 'reversible']",
      "blast_radius": {
        "scope": "[item | order | shipment | site | network | enterprise]",
        "max_exposure": {
          "value": 0,
          "currency": "USD"
        }
      },
      "guardrails": [
        {
          "id": "[gr-id]",
          "parameter": "[what is being bounded]",
          "operator": "[eq | neq | lt | lte | gt | gte | in | not-in]",
          "threshold": "[a number, {value,unit}, or {value,currency}]",
          "on_breach": "[block | require-approval | escalate | degrade]",
          "locator": {
            "file": "[path]",
            "symbol": "[the enforcement code, if any]"
          }
        }
      ],
      "escalation": {
        "to": "[a role id from oversight.roles]",
        "when": "[trigger condition]",
        "within": "[ISO 8601 duration, e.g. PT4H]"
      },
      "policy_refs": [
        "[id of a policy below]"
      ],
      "risk_refs": [
        "[id of a governance.risks entry]"
      ],
      "locator": {
        "file": "[path]",
        "symbol": "[the decision function/method]"
      }
    }
  ],
  "policies": [
    {
      "id": "[pol-id]",
      "class": "[invariant | constraint | preference]",
      "statement": "[the rule, one sentence]",
      "exceptions": {
        "statement": "[required if class: constraint]",
        "approver": "[role]"
      },
      "source": {
        "owner": "[team/person]"
      },
      "verification": "[scenario | static | runtime | attestation]",
      "locator": {
        "file": "[path]",
        "symbol": "[enforcement code, if any]"
      }
    }
  ],
  "interfaces": {
    "consumes": [
      {
        "id": "[input id]",
        "name": "[input name]",
        "kind": "[api | event | file | database | stream | ui | document]",
        "system": "[id of a systems entry]",
        "json_schema": {
          "//": "inline JSON Schema for this input's payload shape -- required"
        },
        "examples": [
          "[at least one concrete valid payload -- needed for behavioral grounding and test data generation]"
        ],
        "boundary_values": [],
        "adversarial_hints": [
          "[known attack-relevant input shapes for this interface, optional]"
        ],
        "semantics": "[meaning a schema can't express]",
        "freshness": "[ISO 8601 duration, max acceptable data age]",
        "classification": "[public | internal | confidential | restricted]",
        "pii": false,
        "if_unavailable": "[halt | degrade | use-stale | substitute]",
        "locator": {
          "file": "[path]",
          "symbol": "[where this is read]"
        }
      }
    ],
    "produces": [
      {
        "id": "[output id]",
        "name": "[output name]",
        "kind": "[api | event | file | database | stream | ui | document]",
        "system": "[id of a systems entry]",
        "json_schema": {
          "//": "inline JSON Schema for this output's payload shape -- required"
        },
        "side_effect": false,
        "classification": "[public | internal | confidential | restricted]",
        "pii": false,
        "consumers": [
          "[role id, optional]"
        ],
        "locator": {
          "file": "[path]",
          "symbol": "[where this is written]"
        }
      }
    ],
    "systems": [
      {
        "id": "[system id]",
        "name": "[business system name, not a vendor SKU]",
        "role": "[system-of-record | execution | data-source | notification | model-service | other]",
        "direction": "[read | write | read-write]",
        "criticality": "[required | degradable | optional]"
      }
    ]
  },
  "operations": {
    "failure_modes": [
      {
        "id": "[fm-id]",
        "condition": "[what triggers this failure mode]",
        "affects": [
          "[interface/system/decision id]"
        ],
        "detection": "[how it's detected]",
        "response": "[halt | degrade | fallback | queue | escalate | retry-bounded]",
        "safe_state": "[id of a safe_states entry]",
        "notify": [
          "[role id, optional]"
        ]
      }
    ],
    "safe_states": [
      {
        "id": "[ss-id]",
        "statement": "[what the agent does in this state]",
        "entry": "[automatic | manual]",
        "exit": "[automatic | manual]"
      }
    ],
    "slos": [
      {
        "metric": "[metric id]",
        "objective": "[lt|lte|gte|gt|eq]",
        "value": 0,
        "unit": "[unit]",
        "window": "[ISO 8601 duration]"
      }
    ]
  },
  "oversight": {
    "posture": "[human-in-the-loop | human-on-the-loop | human-out-of-the-loop]",
    "roles": [
      {
        "id": "[role id]",
        "title": "[role title -- never an individual's name]",
        "duties": [
          "[approve | monitor | override | audit | configure]"
        ],
        "decisions": [
          "[decision id]"
        ]
      }
    ],
    "controls": {
      "pause": {
        "available": false,
        "method": "[how, if available]",
        "actor": "[who]"
      },
      "override": {
        "available": false,
        "method": "[how, if available]",
        "actor": "[who]"
      },
      "rollback": {
        "available": false,
        "method": "[how, if available]",
        "actor": "[who]"
      }
    },
    "escalations": [
      {
        "id": "[esc-id]",
        "when": "[trigger]",
        "to": "[role id]",
        "within": "[ISO 8601 duration]"
      }
    ]
  },
  "acceptance_criteria": [
    {
      "id": "[acc-id]",
      "metric": "[metric id]",
      "objective": "[lt|lte|gte|gt|eq]",
      "value": 0,
      "unit": "[unit]",
      "basis": "[population/window measured over]",
      "gate": "[pre-production | continuous | both]"
    }
  ],
  "scenarios": [
    {
      "id": "[scn-id]",
      "name": "[scenario name]",
      "category": "[e.g. inventory, demand, supplier, runtime, security, stress, concurrency]",
      "priority": "[critical | high | medium | low]",
      "verifies": [
        "[decision/policy/capability/failure_mode id this scenario proves]"
      ],
      "given": {
        "initial_state": {},
        "inputs": {
          "[an interfaces.consumes id]": "[concrete payload matching its json_schema]"
        }
      },
      "when": {
        "trigger": "[what triggers this]",
        "action": "[what the harness does to invoke the agent]"
      },
      "then": {
        "expected_behaviour": "[human-readable pass condition]",
        "expected_outputs": [
          {
            "output_id": "[an interfaces.produces id]",
            "assert": [
              {
                "subject": "[field path]",
                "operator": "[eq|neq|lt|lte|gt|gte|in|not-in|exists|absent|matches]",
                "value": null
              }
            ]
          }
        ],
        "expected_decision": [
          {
            "decision_id": "[a decisions id]",
            "assert": [
              {
                "subject": "[field]",
                "operator": "eq",
                "value": null
              }
            ]
          }
        ]
      },
      "severity_if_failed": "[critical | high | medium | low]",
      "traceability": {
        "requirement_ids": [
          "[decision/policy/capability id]"
        ],
        "standard_refs": []
      }
    }
  ],
  "failure_mode_tests": [
    {
      "id": "[fmt-id]",
      "verifies_failure_mode": "[an operations.failure_modes id]",
      "simulate": {
        "target": "[id of the affected interface/system]",
        "fault": "[unavailable | latency | error-5xx | corrupt-data | stale | partial]",
        "detail": ""
      },
      "expected_response": "[halt | degrade | fallback | queue | escalate | retry-bounded]",
      "expected_safe_state": "[an operations.safe_states id]"
    }
  ],
  "combinatorial": {
    "axes": [
      {
        "variable": "[e.g. sku.perishable]",
        "values": []
      }
    ],
    "exclusions": [
      {
        "without": [
          {
            "variable": "",
            "value": null
          }
        ],
        "reason": "[usually a policy id]"
      }
    ],
    "strategy": "pairwise",
    "n": 2,
    "target_coverage": 0.4
  },
  "limitations": [
    {
      "id": "[lim-id]",
      "statement": "[an honest, disclosed limitation]",
      "impact": "[what it means for users]",
      "workaround": "[optional]"
    }
  ],
  "execution": {
    "candidate_ref": "[CLI command, function import path, or API endpoint that invokes the agent]",
    "invocation_kind": "[cli | http | grpc | function | queue-consumer]",
    "sandbox": true,
    "isolated_state": "per-scenario",
    "idempotency_check": true,
    "timeout_s": 30,
    "retry_policy": {
      "max_attempts": 1,
      "backoff_s": 0
    },
    "env": [
      {
        "name": "[ENV_VAR_NAME]",
        "secret": false
      }
    ],
    "service_mocks": [
      {
        "system_id": "[a systems id]",
        "protocol": "http",
        "base_path": "[e.g. /mock/sys-erp]"
      }
    ],
    "resource_limits": {
      "cpu": "1",
      "memory": "512Mi",
      "network_egress_allowlist": [
        "[systems id]"
      ]
    },
    "observability_hooks": {
      "decision_log_location": "[path/URI, optional]",
      "trace_location": "[path/URI, optional]"
    }
  },
  "governance": {
    "accountability": {
      "executive_owner": {
        "role": "[role]",
        "contact": "[reachable mailbox/URI]"
      },
      "operational_owner": {
        "role": "[role]",
        "contact": "[reachable mailbox/URI]"
      }
    },
    "risk_class": {
      "framework": "[eu-ai-act | nist-ai-rmf | internal]",
      "class": "[risk class]",
      "rationale": "[why]"
    },
    "risks": [
      {
        "id": "[risk-id]",
        "category": "[operational | financial | safety | security | privacy | compliance | reputational | model-behavior]",
        "statement": "[the risk]",
        "likelihood": "[rare | unlikely | possible | likely | almost-certain]",
        "severity": "[negligible | minor | moderate | major | severe]",
        "mitigations": [
          "[id of a REAL control elsewhere in this document -- a guardrail, control, or failure_mode]"
        ]
      }
    ],
    "security": {
      "identity": "[service-account | delegated-user | hybrid]",
      "authorization": "[what this agent is authorized to do/touch]",
      "secrets": "[vault-managed | platform-managed | environment | none]",
      "data_protection": {
        "in_transit": "[e.g. tls]",
        "at_rest": "[e.g. encrypted | unencrypted]"
      },
      "threats_considered": [
        "[e.g. owasp-llm01-prompt-injection]"
      ]
    },
    "privacy": {
      "processes_pii": false
    },
    "compliance": [
      {
        "id": "[cmp-id]",
        "framework": "[iso-42001 | soc2 | gdpr | eu-ai-act | ...]",
        "requirement": "[requirement]",
        "status": "[claimed | assessed | certified | not-applicable]"
      }
    ],
    "audit": {
      "immutability": "[append-only | worm | mutable]",
      "access": [
        "[role id]"
      ],
      "regulator_access": false
    }
  },
  "lifecycle": {
    "change_log": [
      {
        "version": "[x.y.z]",
        "date": "[ISO date]",
        "type": [
          "added"
        ],
        "breaking": false,
        "revalidation": "required",
        "summary": "[what changed]"
      }
    ],
    "model_dependencies": [
      {
        "id": "[model-id]",
        "role": "[what this model does for the agent]",
        "update_policy": "[pinned | managed-upgrade | provider-continuous]",
        "revalidation": "[full | affected | none]"
      }
    ],
    "reviews": {
      "cadence": "[ISO 8601 duration, e.g. P6M]",
      "last": "[ISO date]"
    }
  },
  "references": [
    {
      "id": "[ref-id]",
      "kind": "[repository | api-spec | data-schema | model-card | runbook | dashboard | policy-document | risk-assessment | audit-report | dataset | agent-spec | other]",
      "title": "[title]",
      "location": "[URI/path -- never embed credentials]",
      "access": "[public | credentialed | on-request]"
    }
  ],
  "extensions": {}
}