Execution Receipt Specification (ERS)¶

Purpose¶

Defines the canonical structure, controlled vocabulary, and quality gates for engineering execution receipts. A receipt is a structured record of work performed, evidence gathered, and state reached — not a narrative summary. Any engineering agent or human emitting a receipt SHALL conform to this specification.

An execution receipt answers five questions:

What was the objective?
What was done?
What evidence was collected?
What is the terminal state?
Who owns whatever remains?

Scope¶

ERS defines the canonical structure for recording completed engineering execution.

ERS does not define:

investigation methodology (see investigation-methodology.md)
evidence evaluation (see evidence-contract.md)
decision vocabulary (see decision-vocabulary.md)
governance policy
implementation practices

Those are governed by their respective companion standards.

ERS governs receipt structure and recording only. It does not redefine evidence evaluation, investigation methodology, or engineering terminology. Those remain the responsibility of the companion standards.

Conformance¶

A document conforms to ERS v1.0 when:

all REQUIRED sections are present in canonical order,
all controlled vocabularies are used without synonymous alternatives,
referenced companion standards (Evidence Contract, Decision Vocabulary) are followed,
all mandatory quality gates pass.

A receipt satisfying these conditions is classified Final. A receipt that fails any condition is classified Draft until corrected or superseded.

Relationship to other standards¶

This specification builds on and references:

evidence-contract.md — the five-section evidence discipline (OBSERVED, INFERRED, DECISION, NOT VERIFIED, BLOCKING). ERS receipts conform to the Evidence Contract; they do not replace it.
decision-vocabulary.md — terminal-state definitions (VERIFIED, BLOCKED_EXTERNAL, DEFERRED, etc.). ERS extends this vocabulary with receipt-specific status values but does not redefine existing terms.
investigation-methodology.md — the gate order for discovery, verification, and mutation. A receipt is the output artifact of this process.

Normative and informative content¶

Normative (mandatory)¶

Canonical section structure (§ Canonical Structure)
Section ordering
Controlled vocabularies (§ Controlled Vocabulary)
Quality gates (§ Quality Gates)
Conformance requirements (§ Conformance)
Immutability rule (§ Immutability)

Informative (guidance)¶

Reference receipt
Rationale and implementation notes within section definitions
Acceptance criteria for promotion

Normative content defines what a receipt MUST follow. Informative content provides examples and guidance. Implementations SHALL NOT treat informative content as requirements.

Canonical Structure¶

Every execution receipt SHALL contain the following sections in order. Sections marked REQUIRED must be present; sections marked CONDITIONAL are included when applicable.

The canonical section order is normative. Sections SHALL appear in this order. Consumers MAY rely upon this ordering. Conditional sections MAY be omitted only when explicitly marked CONDITIONAL by this specification.

 1. Receipt Metadata           REQUIRED
 2. Objective                  REQUIRED
 3. Terminal State             REQUIRED
 4. Verification Matrix        REQUIRED
 5. Timeline                   REQUIRED
 6. Observed                   REQUIRED
 7. Hypotheses                 CONDITIONAL — present when root cause is not established
 8. Not Established            REQUIRED
 9. Decisions                  CONDITIONAL — present when engineering decisions were made
10. Actions Taken              REQUIRED
11. Expected Effect            CONDITIONAL — present when actions have deferred outcomes
12. Evidence                   REQUIRED
13. Results                    REQUIRED
14. Risks                      CONDITIONAL — present when residual risks exist
15. Blocking Authority         CONDITIONAL — present when terminal state is not COMPLETE
16. Disposition                REQUIRED
17. Traceability               REQUIRED

Section definitions¶

Receipt Metadata. Version, date, author, related receipts, measurement boundary, verification boundary.

Objective. The engineering goal. One sentence. What was this receipt meant to prove or accomplish.

Terminal State. One value from the controlled vocabulary (see below). This is the overall receipt status.

Terminal State describes the outcome of the assigned engineering objective. It does not describe the overall health, readiness, or completeness of the system under modification. A receipt may reach COMPLETE even if the system has follow-up work, provided the objective itself was achieved and verified.

Verification Matrix. A YAML block mapping each verification milestone to a status value. This is the traffic-light view — one screen, no prose.

Timeline. A chronological sequence of state transitions observed during execution. Each entry records when behavior changed, not why.

Observed. Facts directly confirmed by inspection, command output, or measurement. Each observation is anchored to the specific evidence that supports it. Conforms to the Evidence Contract's OBSERVED section.

Hypotheses. Candidate explanations for observed behavior that have not been isolated experimentally. Each hypothesis states a basis (what observations support it) and a confidence level. Present only when root cause is not conclusively established.

Not Established. Explicit enumeration of what the investigation did NOT prove, with the reason (not tested, not accessible, not isolated). Conforms to the Evidence Contract's NOT VERIFIED section.

Decisions. Engineering actions taken as a result of the investigation. Stated as actions, not restated evidence.

Actions Taken. The concrete steps executed — commands run, files modified, configurations changed.

Expected Effect. For actions with deferred outcomes, what the action was intended to produce and how to verify it later.

Evidence. The detailed evidence supporting the Observed section — command outputs, checksums, file listings, API responses.

Results. Outcome of each verification step — pass, fail, or not attempted, with the specific output that determined the result.

Risks. Residual risks that survive the receipt. Each risk states what could go wrong and what mitigation exists.

Blocking Authority. When the terminal state is not COMPLETE, identifies: the component blocking completion, the observable symptom, the authority that owns the component, any verified workaround, and the next investigation steps.

Disposition. The handoff state: is the migration complete, is the investigation suspended, what user or vendor action is required, and who owns the next step.

Traceability. Links to related artifacts: conversation IDs, commit SHAs, merge requests, related receipts, bead references.

Controlled Vocabulary¶

Receipt status¶

Used in the Terminal State and Verification Matrix.

Value	Meaning
`VERIFIED`	Directly confirmed by evidence gathered during this execution.
`PARTIAL`	Some milestones verified; others remain unverified or failed.
`NOT_VERIFIED`	No evidence gathered for or against. Not attempted or not accessible.
`PENDING`	Evidence gathering is in progress; no terminal determination yet.
`BLOCKED`	An external dependency prevents further progress.
`FAILED`	Evidence gathered; the milestone did not pass.
`COMPLETE`	All milestones verified; no residual risks or blockers.
`SUSPENDED`	Investigation paused; resumption requires a stated trigger.
`WAITING_EXTERNAL`	Progress depends on an external party (vendor, upstream, credential).

These values extend the terminal states defined in decision-vocabulary.md. The existing vocabulary (VERIFIED, BLOCKED_EXTERNAL, DEFERRED, BLOCKED_BY_POLICY, UNKNOWN, NOT ESTABLISHED) remains canonical for repository and system checks. The values above are specific to receipt milestones and do not redefine existing terms.

Hypothesis confidence¶

Value	Meaning
`HIGH`	Multiple independent observations support this hypothesis; alternative explanations are weak.
`MEDIUM`	Observations are consistent with this hypothesis but do not exclude alternatives.
`LOW`	Plausible but unsupported by strong evidence; requires further investigation.

Evidence strength¶

Value	Meaning
`CONCLUSIVE`	Directly observed; reproducible; no alternative interpretation.
`STRONG`	Directly observed; single plausible interpretation; minor ambiguity possible.
`MODERATE`	Observed but subject to environmental factors or incomplete measurement.
`WEAK`	Indirect; inferred from adjacent evidence; multiple interpretations possible.

Immutability¶

Execution Receipts are immutable historical records.

Corrections SHALL be issued as amendments or superseding receipts, not as edits to the original. Historical evidence SHALL NOT be rewritten. An amendment receipt references the original via its Traceability section and states what changed and why.

Quality Gates¶

Before a receipt is accepted as Final, it SHALL satisfy every gate in this checklist. A receipt that fails any gate is classified as Draft.

receipt_validation:
  objective_defined:           # One-sentence objective present
  terminal_state_present:      # Terminal state uses controlled vocabulary
  observations_supported:      # Every observation cites specific evidence
  hypotheses_labeled:          # Every hypothesis has a confidence level
  unknowns_declared:           # Not Established section is present and non-empty
  decisions_documented:        # If decisions were made, they are stated as actions
  actions_traceable:           # Every action cites a command, file, or commit
  verification_complete:       # Verification matrix covers all milestones
  disposition_present:         # Disposition section assigns next owner
  authority_assigned:          # If not COMPLETE, blocking authority is identified
  chain_of_custody_complete:   # Traceability section links to source artifacts

Gate values: PASS / BLOCKED only, per decision-vocabulary.md.

Receipt Metadata Format¶

receipt:
  version: "ERS/1.0"
  date: "YYYY-MM-DDTHH:MM:SSZ"
  author: "<agent or human identifier>"
  status: "Draft | Final"
  related_receipts: []
  measurement_boundary: "<what was examined>"
  verification_boundary: "<what remains unknown>"

Reference Receipt¶

The LLM Storage Migration receipt (conversation fbf19796-03cf-4889-8ade-de3db19751c2) is the informative reference implementation for ERS v1.0. It was developed iteratively through engineering review and demonstrates the complete section structure, controlled vocabulary, evidence discipline, and disposition format.

This receipt is an informative example, not part of the normative specification.

Acceptance Criteria¶

Before promoting ERS from proposed to accepted, it SHALL be validated against a representative body of work:

Applied to ≥20 real execution receipts across different categories (incident response, infrastructure changes, CI fixes, migrations, investigations)
No recurring structural exceptions required
Independent reviewers consistently interpret receipts the same way
Quality gates are objective enough to be applied consistently by both humans and agents

If those conditions are met, empirical evidence supports promotion to accepted.

Versioning¶

This specification follows semantic versioning. Breaking changes to the section structure or controlled vocabulary increment the major version. Additions to the vocabulary or optional sections increment the minor version.

Version	Date	Change
1.0	2026-07-22	Initial specification, derived from LLM Storage Migration receipt
### Compatibility

ERS v1.x minor versions SHALL remain backwards compatible. A receipt conforming to v1.0 SHALL remain valid under any v1.x revision.

Major versions MAY change required sections, controlled vocabularies, or quality gates. A major version change SHALL document migration guidance for existing receipts.