Skip to content
Orcho Docs

Verification Receipts for Orcho Runs

Verification is only useful when it proves the right thing in the right place. A receipt makes the verification environment inspectable: instead of trusting the sentence “tests passed”, Orcho records where and how each check actually ran, then lets gates and final acceptance read those records.

declared command                  the verification contract names the check
      |
      v
executed in the declared env      interpreter, working directory, overrides
      |
      v
receipt written on disk           runs/<ts>/verification_command_receipts/
      |
      v
gates and final acceptance        read receipts, not the worker's claim

Without receipts, a run can look green while testing the wrong checkout, missing a sibling change, or relying on a check that ran before the last edit.

What a receipt records

Section titled “What a receipt records”

A run directory holds three receipt kinds, each in its own directory under runs/<ts>/:

KindWritten whenLocation
Phase environment receiptafter each implement / repair roundverification_receipts/<phase>_round<N>.json
Env-assertion receiptdeclared environment assertions runverification_env_receipts/verify_env_<env>.json
Command receipta declared verification command runsverification_command_receipts/<command>.json

Phase environment receipts prove the phase worked in the expected tree: phase, round, cwd, the interpreter identity (python), checks[{name, expected, actual, passed}] (for example an import-provenance probe), and commands[{argv, exit_code}].

Env-assertion receipts prove a declared environment resolved as declared: env, subject (checkout and project), cwd, interpreter, env_overrides, assertions[{name, kind, expected, actual, passed, detail}], and an all_passed rollup.

Command receipts are the gating shape — one per declared command:

FieldMeaning
commandThe declared command name from the verification contract.
envThe declared environment the command ran in.
cwdThe working directory the command actually used.
argvThe resolved argument vector that executed.
assertionsDeclared environment assertions with expected / actual / passed.
exit_codeThe real process exit code; only 0 can count as passed.
duration_sWall-clock duration of the command.
stdout_tail / stderr_tailOutput tails for quick inspection; log_path holds the full log.
parityWhether the check is absolute or differential against a baseline.
detailExecution failure detail; any non-empty value means the receipt failed.
gitProvenance: checkout_head, baseline_head, changed_files_fingerprint.
dependenciesPer-declared-dependency provenance for cross-repo staleness.

A receipt passes only when the exit code is 0, every declared assertion passed, and detail is empty. A missing or unreadable receipt can never read as green.

Example

Section titled “Example”

A sanitized command receipt for a lint check:

{
  "schema_version": 2,
  "kind": "verification_command",
  "command": "lint",
  "env": "core",
  "cwd": "/repo/app",
  "argv": ["ruff", "check", "api/"],
  "assertions": [
    {
      "name": "pipeline_import",
      "expected": "/repo/app/pipeline/__init__.py",
      "actual": "/repo/app/pipeline/__init__.py",
      "passed": true
    }
  ],
  "exit_code": 0,
  "duration_s": 4.2,
  "parity": "absolute",
  "detail": "",
  "git": {
    "checkout_head": "9f2c41a",
    "baseline_head": null,
    "changed_files_fingerprint": "b1e6..."
  }
}

The git block is what makes staleness detectable: if the checkout moves after this receipt was written, the proof no longer covers the current tree.

Classification: present, missing, failed, stale

Section titled “Classification: present, missing, failed, stale”

Readiness classifies every required command receipt into exactly one state:

StatusMeaningNext action
presentReceipt exists, passed, and still matches the current tree.Nothing; the check is proven.
missingNo receipt on disk for the required command.Run the check.
failedNon-zero exit, a failed declared assertion, or a non-empty execution detail.Fix the code or the check, then re-run.
staleThe receipt passed, but the checkout HEAD or changed-files fingerprint moved since it ran — or a declared dependency moved.Re-run the check; the code may be fine.

The distinction is load-bearing because each state implies a different action. missing means nothing was proven. failed means something is wrong and needs a fix. stale means the proof expired: the check passed once, but the tree changed afterward, so only a re-run — not a repair — restores readiness. Collapsing these into one “not green” state would hide which action unblocks delivery.

Who reads receipts

Section titled “Who reads receipts”
  • Verification gates read receipts at gate time; a require gate blocks the transition on any missing, failed, or stale required receipt.
  • Final acceptance reads the readiness summary built from receipt classification instead of trusting the worker’s own report.
  • The evidence bundle carries a compact receipts digest per phase round, with the full receipts staying on disk in the run directory.
  • MCP clients read orcho_run_evidence(slice="verification_receipts") for a typed projection — no raw log scraping required.

Deep reference

Section titled “Deep reference”

The canonical engineering doc lives with the code:

Section titled “Related”