# Receipts

> Verification gate that blocks "done" claims until real evidence exists. Use BEFORE claiming any task is complete — before saying "tests pass", "build works", "fixed", "implemented", "deployed", before committing, and before opening a PR. Runs the actual proof commands, records tamper-evident receipts, and auto-invalidates evidence when the code changes afterward. Stops agents from shipping unverified work.

- Skill: `kaiser0733/receipts` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add kaiser0733/receipts`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kaiser0733/receipts/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: Kaiser0733 (https://skillmd.com/u/kaiser0733)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kaiser0733/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+.

```bash
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:

   ```bash
   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.**

   ```bash
   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:

   ```bash
   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):

```yaml
- 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

| Command | 0 | 1 | 2 |
|---|---|---|---|
| `receipts add` | command passed | command failed | usage error / no ledger |
| `receipts check` | all claims verified | any claim failed/stale/missing | no ledger |
| `receipts verify` | all re-runs pass | any re-run fails | no ledger |
| `receipts report` | verdict PASS | verdict FAIL | no ledger |