A governance system that blocks a merge but cannot explain why is indistinguishable from a flaky test. The block becomes noise to be worked around — disabled in CI, ignored in review, treated as a hostile gate rather than an architectural signal. Provenance is the property that converts an enforcement event from "the system said no" into "this specific team decision, written on this date, by this person, applies because of this precedence rule, and the rationale is at this URL."
What enforcement provenance actually means
Provenance is not a feature added on top of governance. It is what every step of the governance pipeline produces as a byproduct, when the pipeline is built right. The components are:
1. Decision identity
Every compiled decision has a stable identifier — not just a filename. The ID survives ADR renames, supersessions, and refactors of the source documentation. When a verdict cites d-17, that identifier resolves to a specific record in the corpus regardless of how the underlying ADR file has moved or been edited.
2. Compilation traceability
The compiler records which source file produced which decision record, at which git SHA, with which author. The compiled corpus is not just data; it is data with origin. Anyone reading the corpus can answer "where did this constraint come from?" by following the link back to the source ADR.
3. Retrieval explanation
When the governance retriever returns a set of candidate decisions for a query, it records the query, the scope match, the rank, and the candidates. The set of decisions that could have applied is itself a queryable record — not just the one that did apply.
4. Precedence citation
When two or more candidates match, the precedence resolution names the winner and the rule that selected it. "ADR-0042 wins by supersession over ADR-0017" is a complete precedence citation; "ADR-0042 was chosen" is not.
5. Evaluation record
The evaluator records the predicate it ran, the input it ran against, the agent or CI run that triggered it, and the timestamp. Two evaluations with the same input and corpus produce identical records (deterministic enforcement), but each evaluation is its own audit event.
6. Verdict link
The enforcement output links to all five upstream artifacts. Reading the verdict tells you which evaluator, which precedence rule, which retrieval, which compiled record, and which authoring ADR. There is no hidden step.
Why provenance has to be structural, not narrative
A common shortcut is to attach a freeform message to each block: "Blocked because of the repository pattern rule." This is narrative provenance — a human-readable explanation generated by the system at the time of the block. It is useful for humans, but it is not enough.
Narrative provenance fails in three ways: it cannot be programmatically queried (so you cannot ask "how often does this decision block PRs?"); it cannot be aggregated (so you cannot graph drift by decision); and it is generated, not stored (so the rationale text might change run-to-run as templates evolve, breaking auditability over time).
Structural provenance — IDs, links, timestamps, versions — is the substrate underneath narrative. The system can render any narrative on top of structural provenance at any time; the system cannot derive structural provenance from narrative after the fact.
If the verdict cannot be programmatically traced to a specific record, the enforcement is opaque. Opaque enforcement is what turns governance into noise — engineers stop trusting it because they cannot interrogate it.
What provenance enables
Several capabilities are downstream of having a provenance chain. None of them are achievable without it.
| Capability | Without provenance | With provenance |
|---|---|---|
| Why did this block? | Read the message; guess at the rationale | Follow the chain to the authoring ADR |
| Drift telemetry | Aggregate text matches | Aggregate by decision_id · per-agent · per-path |
| Decision impact analysis | None — guesses based on tickets | "This ADR blocked 14 PRs this quarter" |
| Regression after refactor | Manual code review of the corpus | Diff the resolved chain across compilations |
| Compliance evidence | Argue the system worked | Show the chain to an auditor |
| Dispute resolution | "The bot said no" | "ADR-0017 says no; here is the file and the author" |
The fifth row matters in regulated environments specifically. A security or compliance review of an AI-coded codebase needs to demonstrate not just "we have rules" but "this PR was evaluated against these specific encoded constraints at this version of the corpus, and this verdict was recorded." Provenance is what makes that demonstration possible.
The common misread: logs as provenance
Many teams treat application logs of governance events ("INFO: block_pr called at 14:32, reason='repository pattern'") as provenance. They are not. A log line is an artifact of execution; it is not a citable link.
Real provenance has three properties that logs alone do not:
- Stable references — the decision ID in the verdict still resolves to a record six months later, even if the ADR was renamed.
- Versioned context — the corpus version at the time of the verdict is part of the record. Reproducing the verdict means knowing which corpus state produced it.
- Bidirectional links — given a decision, you can list the verdicts that cited it. Given a verdict, you can list the decisions it cited. Logs are one-directional and unindexed.
Logs tell you what happened. Provenance tells you why it happened, and lets you follow why all the way back to the team's authoring intent. The difference is unobservable in any single event and decisive across thousands.
Provenance as the foundation of trust
Governance systems live or die on engineer trust. An engineer who has been blocked once by an opaque rule will, the next time, look for a way around the gate. A governance system that gets routed around does not have governance — it has theater. Provenance is the mechanism by which engineers can interrogate the system, disagree with it productively, and either update the decision or accept the block on its merits.
This is why provenance is not a "nice to have" property attached to a working governance system. It is a precondition for governance being adopted at all. Without it, the system is a black box that says no. With it, the system is a colleague that cites its sources.
Related concepts
- Governance provenance — the companion concept at a different grain. Enforcement provenance traces a verdict back to its decision; governance provenance traces a decision back to its origin.
- Verification contracts — what provenance proves at the system level. Contracts pre-register expected verdicts; provenance records observed verdicts with citable lineage.
- Deterministic enforcement — what makes provenance reproducible. Without determinism, the chain reconstructs different verdicts on different runs.
- Architectural compiler — the source of compilation traceability, which is link 02 of the chain. Compilation produces the decision IDs and source links that provenance relies on.
- Precedence semantics — what makes link 04 citable. Without ordered precedence rules, "the winner was chosen" is not a usable provenance step.