Receipts

Receipts are JSON artifacts that gate state transitions.

Implementation review receipts include:

• Verdict: SHIP, NEEDS_WORK, or MAJOR_RETHINK
• Confidence anchors
• Introduced vs pre-existing findings
• Suppressed finding counts
• Deferred finding counts
• Validation state

Ralph reads receipts before moving forward. This prevents fake “done” status and open-loop drift.

.flow/review-receipts/<branch>.json

Receipts are not decoration. They are the machine-checkable handover between work and next action.

Why receipts matter

Agentic work needs evidence that survives the chat. A receipt records the verdict, what was reviewed, which findings were introduced by the diff, and what remains unresolved.

flowchart LR
  Diff["Diff"] --> Review["Review backend"]
  Review --> Receipt["Receipt JSON"]
  Receipt --> Ralph["Optional Ralph gate"]
  Receipt --> PR["PR cognitive aid"]

Verdicts

Verdict	Meaning
SHIP	No blocking introduced findings remain.
NEEDS_WORK	Fixable issues block handoff.
MAJOR_RETHINK	The plan or approach is wrong enough to revisit the spec or architecture.

Only introduced findings should block the current change. Pre-existing issues should be reported, but not silently converted into scope.

NEEDS_WORK is not a terminal state. It sends the work back through the fix loop, then review runs again. The receipt chain is the evidence that the loop kept pressure on the change until the introduced issues were resolved or explicitly deferred.

Receipt hygiene

• Keep receipts in repo-local .flow/ state.
• Do not hide suppressed findings; record suppression count and reason.
• Defer findings only when the PR body names them.
• Re-run review after meaningful fixes.
• Treat missing receipts as an unknown state, not a pass.

Human reading order

When a receipt exists, read:

1. Verdict.
2. Introduced findings.
3. Suppressed or deferred findings.
4. Validation state.
5. Confidence anchors.

That order prevents reviewers from over-weighting low-confidence commentary while still seeing real risk.