Receipts

receipts — no claim without evidence

You are an agent about to claim work is done. Stop. A claim without a receipt is a guess, and guesses do not ship.

This skill enforces one rule: every verification claim ("tests pass", "build is green", "the bug is fixed", "the endpoint responds") must be backed by a receipt — a captured record of the command you actually ran, its real exit code, its real output, and a fingerprint of the source tree at that moment. If the code changes after you captured the evidence, the receipt goes stale and the gate fails until you re-run the proof.

Setup (once per project)

The CLI is bundled with this skill at bin/receipts. Zero dependencies, Python 3.8+.

python3 <path-to-this-skill>/bin/receipts init

Or symlink it onto PATH once: ln -s <path-to-this-skill>/bin/receipts ~/.local/bin/receipts, then just use receipts.

The workflow — every time you finish a task

1. Do the work. Write the code, fix the bug, add the feature.

2. List your claims. Before saying "done", write down every verifiable claim you are about to make. Typical claims:

   • "the test suite passes" → python3 -m pytest -q or npm test
   • "the build succeeds" → npm run build, cargo build, go build ./...
   • "lint is clean" → ruff check ., eslint .
   • "the script runs" → python3 main.py --smoke
   • "the endpoint responds" → curl -sf http://127.0.0.1:8000/health

3. Record a receipt for each claim. Run the proof through receipts — never run it bare and remember the result:

   receipts add "the test suite passes" -- python3 -m pytest -q
   receipts add "the build succeeds" -- npm run build
   

   receipts runs the command, captures stdout/stderr, the exit code, the duration, a SHA-256 of the output, and the tree fingerprint. If the command fails, the receipt is recorded as FAIL — do not claim success. Fix the problem and record again.

4. Pass the gate.

   receipts check
   

   • VERDICT PASS → every claim has fresh, passing evidence. You may now say "done".
   • VERDICT FAIL → something is unverified, failed, or STALE (code changed after the evidence was captured). Fix it and re-record. Do not claim completion.

5. Show the receipts. Include the report in your final message so the human can audit you:

   receipts report
   

   Paste the verdict line and the table. If the human asks for evidence for a specific claim, run receipts show rcpt-0001.

Hard rules

• Never claim "tests pass" from memory. Run it through receipts add now.
• Never edit .receipts/ledger.json by hand. Evidence you can tamper with is not evidence.
• Never mark a failing command as success. A FAIL receipt means the claim is false. Fix the code, re-run.
• Stale means re-run. If receipts check reports STALE, the tree changed after your evidence was captured. Your old proof says nothing about the current code. Re-record.
• "It should work" is not a claim you are allowed to make. Only claims with receipts.
• Refresh before handoff. If significant time or many edits passed since you recorded, run receipts verify to re-execute every recorded command and refresh the evidence in one pass.

CI integration

Gate merges on receipts in CI (see README for the full GitHub Actions example):

- name: Verification gate
  run: |
    python3 bin/receipts check

receipts check exits 0 only when every recorded claim has fresh, passing evidence — making it a merge gate the agent cannot talk its way past.

Exit-code contract