Definition
A build receipt is a structured, machine-verifiable record of what work was performed and what gates passed: commands run, versions used, exit codes, diffs produced, and links to artifacts.
Receipts are how you cross the trust boundary without relying on narration.
What belongs in a receipt
At minimum:
- What changed:
git diff --stat, key files touched, commit SHA - What ran: exact commands (lint/typecheck/tests/build)
- What happened: exit codes + summarized outputs
- What environment: Node/pnpm versions, OS, CI runner metadata
- What artifacts: build output hashes, uploaded test reports, URLs
A minimal example (JSON)
{
"issue": 123,
"git": { "base": "main", "head": "feat/fix-thing", "sha": "abc123" },
"commands": [
{ "cmd": "pnpm lint", "exitCode": 0 },
{ "cmd": "pnpm typecheck", "exitCode": 0 },
{ "cmd": "pnpm test", "exitCode": 0 }
],
"diffstat": "6 files changed, 42 insertions(+), 10 deletions(-)",
"artifacts": [{ "name": "coverage", "sha256": "…" }]
}Why receipts matter
Receipts prevent two expensive failure modes:
- Process confabulation: claiming work happened when it didn’t
- Silent regressions: changes that “look fine” but weren’t actually validated
They also make parallel work mergeable: if every agent produces a receipt, you can integrate with confidence.
Implementation notes
- Make the receipt boring. JSON/YAML, not prose.
- Keep it diff-friendly and greppable.
- Treat missing receipts as a failure in CI (no exceptions).
- Prefer deterministic checks and exact values (mechanical counting).
Practical rule
No receipt, no merge.