Declaration architecture
PAA governance is four linked artifact layers, not one task YAML acting as the whole runtime model: a task declaration, evidence records, decision artifacts, and autonomy events. This page explains how those layers relate. The field-by-field contract for all four and all four validated task examples live at Schema.
For the prior-art basis of this architecture, see Research.
This is the permanent, binding statement of where PAA governance begins. Other pages link back to this block rather than restating a competing definition.
A task enters PAA when its boundary satisfies the instrumentation entry criterion.
Manual is the first on-spectrum position: the boundary is bounded and instrumented, position is governed, and the human performs the governed effect. Automation behind that boundary may be absent, disabled, or producing shadow outputs, none of that changes the position, because deployment is a separate axis.
The former partial-autonomy label that once sat between manual and hitl is retired. It no longer names a position, a display region, or an alias for manual, and nothing on the spectrum sits between those two.
Deployment, active, shadow, or disabled, is orthogonal to autonomy position. It is never an authority, a spectrum position, or a synonym for advisory.
The permanent statement of what moves independently of what. Every page that names a dimension links here; none of them defines its own set.
One governed task, three independent clocks.
The autonomy clock governs authority: how much human oversight the task receives.
The evaluator clock governs judgment: how the work is judged and how mature that judgment is.
The worker clock governs capability: the model, agent, workflow, or code performing the task.
The clocks move independently; no clock's advance implies another's.
The task declaration is static; the other three are produced at runtime against it. Full field contracts for all four are at /reference/schema.
The static contract: boundary, evaluators, deployment, position_policy, one promotion edge, and one demotion edge. Declared once per version; everything else is produced at runtime against it. A workflow that governs another transition publishes another declaration version rather than hiding a transition graph inside one declaration.
One universal envelope per evaluator verdict per subject: task, declaration_version, scope, subject, boundary references, the complete evaluator identity, verdict, producer, timestamps, source references, and a typed payload. Recording evidence does not by itself make it admissible.
An immutable, capped snapshot of exactly which evidence was included or excluded (with reasons) behind one promotion or demotion decision. It produces an eligible or ineligible outcome, not a position change.
The append-only motion stream: motion_proposed, then motion_approved or motion_rejected, and only on approval, position_changed. Each event is bound to a decision artifact by evidence_ref and evidence_sha256. Current position and motion status are projections over this stream, not separate fields.
Six conceptual areas within the task declaration layer. The field contract is at /reference/schema; evaluator identity in full is at /build/evaluators.
task (stable identifier), version (integer), description (governed effect), and boundary (typed input and output). Together these define what the declaration governs and what declaration_version an evidence record was produced against.
A non-empty list of evaluators. Each evaluator declares a complete identity: property, target (input/process/output/outcome), technique (deterministic/classifier/llm_judge/human), evaluation_basis (invariant/reference_label/rubric/human_gold/downstream_result), epistemic_status (proxy/ground_truth), version, and authority (advisory/blocking). A task may have any number of evaluators, including more than one asserting the same property.
deployment (active/shadow/disabled, required with no default) and initial_position (manual/hitl/hotl/autonomous). Deployment is orthogonal to position: a shadow deployment executes candidate automation and evaluation and records evidence without letting the candidate effect take effect, regardless of initial_position. Manual is the first on-spectrum position, not an off-spectrum state.
position_policy maps autonomy positions to placement (blocking/async/offline), which determines when evaluation runs relative to the effect. This is a task-level field, not an evaluator-level field, and is distinct from evaluator authority. When the active placement is blocking, all blocking evaluators must pass for the current governed effect to proceed; async and offline evaluations can affect a later cycle or demotion instead.
promotion declares from, to, report (required evidence artifact), window (typed: cases or duration), and execution (operator_approval or automatic). A passing window produces an eligible decision artifact only. Actual movement requires a motion that resolves via the declared execution mode.
demotion declares from, to, trigger (named condition), and window (typed). A window of kind: cases, size: 1 makes demotion immediate on one confirmed failure. Demotion is intentionally asymmetric: an operator may initiate it immediately without waiting for a metric, not only automatically.
Validated example
The YAML below is sourced directly from
examples/paa-tasks/refund_approval.v1.yaml and passes
npm run schema:check. It is not illustrative; it is a conformance fixture.
For field-by-field semantics and all four validated examples, see
/reference/schema.
task: refund_approval
version: 1
description: Evaluate a refund request and decide to approve or escalate for human review.
boundary:
input: refund_request
output: decision
initial_position: hitl
deployment: active
evaluators:
- property: refund_policy_invariants
target: output
technique: deterministic
evaluation_basis:
kind: invariant
ref: refund_policy_invariants
epistemic_status: ground_truth
version: "1"
authority: blocking
- property: should_escalate
target: output
technique: classifier
evaluation_basis:
kind: reference_label
ref: should_escalate_reference_label
epistemic_status: ground_truth
version: "1"
authority: blocking
position_policy:
manual: offline
hitl: blocking
hotl: async
autonomous: offline
promotion:
from: hitl
to: hotl
report: refund_approval_promotion_report
window:
kind: cases
size: 200
execution: operator_approval
demotion:
from: hotl
to: hitl
trigger: chargebacks_or_complaints_exceed_bound
window:
kind: cases
size: 1
A condensed reference for agents and other automated readers indexing this site. Machine-readable versions of the same map live at /llms.txt and /llms-full.txt.
What PAA is. A vendor-neutral architecture for moving an agentic task from full human review toward monitored autonomy. It turns a task into a bounded declaration: a typed boundary, a non-empty evaluator list with explicit authority, top-level gate policy, and typed evidence-backed promotion and demotion. Autonomy is earned, scoped, and revocable.
Intended use. PAA governs repeated task execution through external evaluation and recorded evidence. A model's self-reported confidence does not serve as a gate. Many tasks should stay partially governed permanently. The goal is the level of autonomy supported by the evidence, risk, and domain.