Receipts Standard¶
Parent contract: Bluefly Engineering Execution Contract Version: 1.0 Applies to: All roles. Every execution produces receipts.
1. What Is a Receipt¶
A receipt is a durable, append-only record of an action taken during an execution. It records what was done, by whom, when, and with what result.
Receipts are facts. They must never contain speculation, recommendations, or design decisions.
2. Storage¶
Durable work state and receipt metadata belong in the authoritative Bead. Build and deployment evidence is published through GitLab pipeline and job artifacts, then referenced from that Bead.
Temporary local captures belong only under Scratch/ and are disposable. Receipts must not be stored as untracked files in implementation worktrees.
3. Required Fields¶
Every receipt includes these fields:
| Field | Description | Required |
|---|---|---|
id |
Unique receipt identifier | Yes |
timestamp |
ISO 8601 UTC timestamp | Yes |
role |
Evidence, Implementation, or Architecture | Yes |
agent |
Identifier of the agent that produced the receipt | Yes |
action |
What was done (verb + object) | Yes |
scope |
Which artifacts, systems, or boundaries were involved | Yes |
result |
Outcome: what changed, what was found, or what was decided | Yes |
evidence_state |
For Evidence role: configuration-exists, runtime-exercised, or runtime-verified | Evidence role only |
confidence |
For Evidence role: VERIFIED_RUNTIME through UNPROVEN | Evidence role only |
terminal_state |
For Implementation role: COMMITTED or BLOCKED | Implementation role only |
approval_ref |
For Implementation role: which decision authorized the work | Implementation role only |
boundary_crossings |
For Implementation role: which ownership boundaries were crossed | Implementation role only |
claim_classification |
OBSERVED, REPORTED, INFERRED, or NOT VERIFIED — see evidence-contract.md |
For any receipt asserting a fact about state elsewhere in the system |
coverage_complete |
YES or NO — whether the population this receipt speaks to was fully examined |
For any receipt making a claim about a population (a repo set, a project set, an estate-wide check) |
certification |
PASS, FAIL, REFUSED_UNKNOWN_COVERAGE, or NOT_ESTABLISHED |
For any receipt that certifies a population-level result — see § 8 |
4. Receipt Format¶
Receipts are Markdown files with YAML front matter:
---
id: receipt-2024-06-30-001
timestamp: 2024-06-30T14:30:00Z
role: evidence
agent: cowork-session-abc123
action: "Surveyed Gas City formula files in inspected workspace"
scope: "worktrees/blucity-packs/"
result: "21 formula files found across 4 directories"
confidence: VERIFIED_SOURCE
evidence_state: configuration-exists
---
## Details
[Free-form details, file listings, observations — facts only]
5. When Receipts Are Required¶
| Trigger | Receipt Type |
|---|---|
| Any file read during evidence gathering | Evidence receipt |
| Any search that returns no results (negative evidence) | Evidence receipt |
| Any file write, config change, or deployment | Implementation receipt |
| Any architecture decision | Architecture receipt |
| Reaching a terminal state (COMMITTED or BLOCKED) | Summary receipt |
The rule is simple: if you did something, receipt it. If in doubt, receipt it.
6. Receipt Integrity¶
- Receipts are append-only. Once written, a receipt is never modified or deleted.
- If a receipt contains an error, write a correction receipt that references the original.
- Receipts must be written before the next action in the same execution begins.
- A receipt that references another receipt uses the
idfield, not file paths.
7. Summary Receipts¶
At the end of every execution, a summary receipt is produced that:
- Lists all receipts generated during the execution.
- States the terminal condition (for Implementation: COMMITTED or BLOCKED; for Evidence: investigation complete or scope exhausted).
- Notes any items that require follow-up by a different role.
8. Certification and Unknown Coverage¶
A receipt that certifies a result about a population (every project in a group, every open
MR, every file in a repo) must state whether the population was fully examined
(coverage_complete: YES) or only partially examined (coverage_complete: NO).
If coverage is incomplete and the missing portion could change the conclusion, the receipt's
certification field is REFUSED_UNKNOWN_COVERAGE — not PASS. The individual, bounded
findings the receipt does contain remain valid; only the population-level certification is
withheld. Do not manufacture a percentage or a completion claim for an unknown denominator.
A receipt whose method was later superseded (a better enumeration primitive, a corrected
sort, a fixed pagination bug) does not become false — it carries a method_status note
(e.g. RETIRED_FOR_DENOMINATOR_CERTIFICATION) alongside its original certification, scoped
to what that method can actually support. It is never silently rewritten and never cited
later as though produced by the superseding method.
See standards/platforms/runtime/gas-city-deployment-wiring.md (Provenance-or-Refusal) for
the underlying principle this section implements for receipts specifically.
This standard governs receipt production. It does not govern what actions are permissible — see the role-specific standards for that.