# Machine-readable receipt contract

Use JSON only when the user, CI, or another tool needs a structured artifact. Keep the normal final answer human-readable.

## Required fields

- `version`: integer `2` for new receipts. Version `1` remains accepted for compatibility.
- `status`: `verified`, `partial`, or `blocked`.
- `evidenceSource`: `executed-now`, `supplied`, or `mixed` (required in version `2`).
- `problem`: concise defect and intended behavior.
- `baseline`: object with `command`, `result`, and `evidence`.
- `rootCause`: object with `summary` and at least one evidence item for `verified`.
- `changes`: array of `{ "file", "summary" }` objects.
- `verification`: array of `{ "command", "result", "evidence" }` objects.
- `gaps`: array of explicit missing proof statements.

Baseline results are `failed`, `observed`, or `not-run`. Verification results are `passed`, `failed`, or `not-run`.

## Status invariants

For `verified`:

- Require an observed baseline: `failed` or `observed`, never `not-run`.
- Require at least one concrete root-cause evidence item with `location` and `observation`.
- Require at least one changed file or artifact.
- Require at least one verification item.
- Require every verification result to be `passed`.
- Require `gaps` to be empty.

For `partial`:

- Preserve all evidence obtained.
- Put every missing or inconclusive proof layer in `gaps`.
- Never convert an unrun check into `passed`.

For `blocked`:

- Require at least one gap naming the external blocking condition.
- Leave unperformed work empty or mark it `not-run`; do not speculate about the result.

Validate against [receipt.schema.json](receipt.schema.json), run `node scripts/validate-receipt.mjs <file>` from the skill directory, pipe JSON to `node scripts/validate-receipt.mjs - --json`, or use `bug-receipt check <file>` when the package CLI is installed.