# Verifier Contracts

Verifier contracts are task metadata that describe how a workflow run proves an
accepted outcome. They are used by agents, QA, and release gates to avoid
treating simulated handoffs or unmapped evidence as proof.

## Fields

Each verifier entry is stored under `task.verifierContract.entries`:

- `id`: stable verifier id, unique within the task.
- `surface`: one of `cli`, `api`, `web`, `mobile`, `desktop`, `db`, `cloud`,
  `workflow`, or `generated-artifact`.
- `setup`: environment or data setup required before verification.
- `action`: command, request, workflow action, or user action to execute.
- `expectedObservable`: observable result that must be proven.
- `assertionType`: `equals`, `contains`, `matches`, `exists`, or `custom`.
- `evidenceArtifact`: expected file, command output, trace, screenshot, log, or
  report reference.
- `ownerRole`: role responsible for producing or reviewing evidence.
- `required`: defaults to `true`; optional verifiers are advisory.
- `acceptanceCriteria`: optional criteria references covered by the verifier.

## CLI

Add a verifier while creating a task:

```bash
orchestra task add --id STORY-001 --title "Generate manifest" --owner developer \
  --verifier-id cli-manifest \
  --verifier-surface cli \
  --verifier-setup "package installed" \
  --verifier-action "run manifest command" \
  --verifier-expected "manifest generated" \
  --verifier-evidence "manifest.json" \
  --verifier-owner qa
```

Add or update an entry later. Updates merge by verifier id:

```bash
orchestra task update --id STORY-001 \
  --verifier-id cli-manifest \
  --verifier-surface cli \
  --verifier-setup "package installed" \
  --verifier-action "orchestra commands manifest --json" \
  --verifier-expected "manifest generated" \
  --verifier-evidence "manifest.json" \
  --verifier-owner qa
```

Inspect with:

```bash
orchestra task show --id STORY-001 --json
orchestra context --task STORY-001 --json
```

## Evidence Mapping

Prefer explicit mapping:

```bash
orchestra evidence add --task STORY-001 --role qa --type command \
  --summary "manifest.json generated" \
  --command "orchestra commands manifest --json" \
  --exit-code 0 \
  --surface cli \
  --assertions "exit code 0; stdout contains manifest generated; stderr empty; artifact manifest.json written; final state manifest generated" \
  --verifier-contract-id cli-manifest
```

Legacy evidence can still match by task, surface, observable assertions, and
artifact reference. Explicit `--verifier-contract-id` is less ambiguous.

## Gate Behavior

Tasks without verifier contracts keep existing behavior.

For tasks with required verifier entries, `qa-release` and `release-readiness`
block when evidence is missing, failed, or lacks observable outcome validation.
Missing keys use stable names such as:

- `verifierContract.<id>.evidence`
- `verifierContract.<id>.observableOutcome`

Optional verifiers are rendered in context and handoffs but do not block gates.