Governance provenance. A rule fires. An engineer asks "why does this rule exist?" Governance provenance answers that question with a citable lineage — the ADR that authored it, the discussion or incident that motivated it, the rules it superseded, the surfaces it propagates to. Enforcement provenance traces a verdict to a decision; governance provenance traces a decision to its origin.
Concepts 9 min read · May 2026

# Governance provenance

A governance rule blocks a PR. The engineer's first question is not "what did I do wrong?" — it is "why does this rule exist?" Governance provenance is the structural property that gives that question a single, citable answer: this ADR, this author, this discussion, this supersession history. Rules without provenance are folklore; rules with it are engineering.

By Theo Valmis · Published May 2026

Every active governance rule in a serious codebase exists for a reason. Sometimes the reason is an architectural decision captured in an ADR. Sometimes it is a security incident from two years ago. Sometimes it is a compliance requirement that arrived from outside the engineering org. The reason matters, because rules without traceable origins eventually get challenged, weakened, or routed around by engineers who cannot tell the difference between a load-bearing constraint and ancient cargo.

Governance provenance is the engineering property that makes the origin of every rule queryable. It is the substrate that turns "the bot says no" into "ADR-0017 says no — here is the file, the author, the discussion that produced it, and the rules it superseded."

Two grains of provenance. Enforcement is per-verdict; governance is per-rule. The same decision record sits at both endpoints — one chain runs forward to the verdict, the other runs backward to the rule's origin.

## The two provenance questions

There are two related but distinct questions a serious governance system has to answer for any active rule. They live at different grains and serve different audiences.

### Enforcement provenance: "why this verdict?"

Enforcement provenance is per-event. It traces a single verdict back to the precedence rule that selected the decision, back to the compiled record, back to the authoring ADR. Its primary audience is the engineer holding the blocked PR. Its primary question is operational: "what specifically caused this block, and where can I read the rationale?"

### Governance provenance: "why this rule?"

Governance provenance is per-rule. It traces an active decision back to its authoring ADR, the supersession chain that led to it, the discussion or incident that motivated it, and the surfaces it currently propagates to. Its primary audiences are the architect reviewing the corpus, the security reviewer running an audit, the engineer about to challenge a rule's relevance, and the agent reasoning about which rule applies. Its primary question is structural: "what is the lineage of this constraint?"

Both questions need the same substrate — structured records, stable IDs, link integrity — but they query that substrate in opposite directions. Enforcement provenance runs forward from a verdict; governance provenance runs backward from a rule.

## What governance provenance actually contains

For every active rule in the decision corpus, governance provenance maintains four classes of metadata.

### 1. Authoring ADR

The source document that produced the rule. Not just a filename — a stable reference: the file path, the git SHA at which the ADR was committed, the author identity, and the authoring date. If the ADR is renamed or moved, the link still resolves. If the ADR is edited, the rule references the specific revision that produced it.

### 2. Supersession chain

The ordered history of ADRs this rule replaced. Supersession is not a delete — it is a structured transition, with both the prior decision and the rationale for replacing it preserved. A rule's supersession chain is the history of its category: "this is the third iteration of the dependency policy; iterations one and two are recorded with their motivating context."

### 3. Propagation history

The surfaces the rule has been applied to and the scope at which it operates. A single architectural decision may propagate into pre-commit hooks, CI gates, agent context injection, and the policy catalog — each with its own scope. Governance provenance records where the rule has been applied, when, and at what scope, so changes to one surface do not silently leave others stale.

### 4. Originating context

The discussion, RFC, issue, or incident that motivated the decision. ADRs do not appear from nowhere; they answer a question someone asked. The originating context preserves that question. When the rule is later challenged, the original framing is available: "this rule exists because incident I-44 cost us 6 hours of downtime, and the postmortem recommended this constraint."

Provenance is not a metadata afterthought. It is the structural property that determines whether a rule survives organizational turnover. A rule without origin metadata becomes folklore the moment its author leaves.

## The compiler-diagnostics analogy

The most useful mental model for governance provenance is the compiler diagnostic. A C++ compiler that emits "error: type mismatch" without source location is unusable; the same compiler emitting "error at file.cpp:73:11, declared at file.h:42:5, expected `int` got `float`" is a tool you can debug with. The location chain is what turns the error from a verdict into a diagnostic.

Governance provenance plays the same role for architectural rules. A governance system that blocks a PR without provenance emits "error: violation"; the same system with provenance emits "violation: ADR-0017.md @ sha 9f3a, authored 2026-01-14 by Theo, motivated by incident I-44, supersedes ADRs P and Q." The chain converts a refusal into an artifact you can act on.

This analogy matters because compilers earned engineer trust over decades by producing diagnostics, not just verdicts. Governance systems are at the same inflection point. The difference between a governance layer engineers route around and one they actually trust is whether its outputs look like diagnostics or look like a black box saying no.

## How governance provenance differs from enforcement provenance

Axis | Enforcement provenance | Governance provenance
--- | --- | ---
Grain | Per-event (one verdict) | Per-rule (one decision)
Direction | Verdict → decision | Decision → origin
Primary audience | Engineer holding the blocked PR | Architect, security reviewer, agent
Primary question | "Why did this block?" | "Why does this rule exist?"
Stored as | Audit event log | Rule metadata in the corpus
Lifetime | As long as the audit log retains | As long as the rule is active

The two are complementary, not competing. A complete governance system maintains both. Enforcement provenance without governance provenance produces verdicts you can trace but rules you cannot interrogate. Governance provenance without enforcement provenance produces rules you can read but verdicts you cannot debug.

## What governance provenance enables

Several capabilities exist only when governance provenance is in place. None are achievable from freeform documentation.

- Trust through interrogation. Engineers can challenge a rule by reading its origin. Productive disagreement requires citable history.
- Audit and security review. "Show me every active rule and its authoring ADR" is one query. The auditor's job becomes verification, not investigation.
- Change-impact analysis. When an ADR is updated or superseded, the governance layer can identify every rule downstream of it and flag the surfaces that need to be re-evaluated.
- Drift detection in the corpus. Rules whose authoring ADRs have been deleted, rules whose supersession chains break, rules whose originating contexts no longer apply — all surface as actionable signals.
- Cross-rule reasoning by agents. An agent that sees both the active rule and its origin can answer "is this rule still relevant?" with more than pattern-matching; it can read the original motivation and reason about whether it still holds.
- Organizational continuity. When the architect who authored the rule leaves, the rule remains intelligible. Folklore does not survive turnover; provenance does.

Without governance provenance, a rule's authority decays to whoever last touched it. With it, authority traces to the decision that produced it — and the rule's relevance is testable, not inherited.

## Why narrative documentation is not provenance

The common shortcut is to attach a freeform "rationale" field to each rule. This is narrative documentation, and it has the same failure modes as narrative provenance at the enforcement layer:

- It cannot be queried at the structural level — "list rules motivated by incidents" requires natural-language parsing.
- It drifts as the original context fades — the prose stays the same while the system around it changes.
- It cannot be aggregated — you cannot ask "how many rules in this category trace to which authoring authority?"
- It is generated, not stored as relationships — the supersession chain is a graph, not a paragraph.

Structural provenance — IDs, links, dated relationships — is the substrate underneath narrative. Any narrative can be rendered on top of structural provenance at any time. The reverse is not true.

## Where governance provenance sits in the layer model

Governance provenance is a property of the governance infrastructure layer, not a separate layer of its own. It is what every step of the corpus pipeline produces as metadata when the pipeline is built right: the compiler records source links, the supersession resolver records the chain, the propagation system records each application surface, and the corpus query layer can return all of it.

The relationship to adjacent concepts:

- Compiles with architectural compiler — the compiler is what emits the source-link metadata that provenance relies on.
- Resolves through precedence semantics — supersession is a precedence relationship; provenance preserves the resolved chain.
- Stored beside enforcement provenance — same substrate, different grain. The two together form the full provenance surface.
- Read by architectural governance — the discipline that requires citable rules to operate at scale.

## Related concepts

- Enforcement provenance — per-verdict chain. Same substrate, opposite direction.
- Architectural compiler — emits the source-location metadata governance provenance relies on.
- Precedence semantics — the rule set that supersession provenance records the resolution of.
- Governance infrastructure — the layer in which provenance is a structural property, not an add-on.
- Architectural governance — the discipline that depends on citable rules to operate at scale.

## Frequently asked questions

How is governance provenance different from enforcement provenance?
Enforcement provenance traces a single verdict back to the decision that produced it (verdict #9341 cited rule R, which was resolved from candidates X, Y, Z). Governance provenance traces a rule back to its own origin (rule R was authored by ADR-0017, on date D, by author A, supersedes ADRs P and Q, was motivated by incident I). Enforcement provenance is per-event; governance provenance is per-rule. See enforcement provenance for the per-verdict view.
What does governance provenance actually contain?
For every active rule: the source ADR (file, sha, author, date), the supersession chain (which rules it replaces and why), the propagation history (which surfaces and scopes it has been applied to), and the originating context (the discussion, issue, RFC, or incident that motivated the decision). Together these form a queryable lineage for every constraint in the corpus.
Why does governance provenance matter operationally?
It is the substrate for trust, change-impact analysis, audit, and security review. An engineer can ask "why does this rule exist?" and get a citable answer. A security review can show that every governance rule traces to an approved decision. A refactor of the ADR corpus can identify which rules are at risk of regression. None of these capabilities exist if the rules are anonymous or freeform.
How does governance provenance relate to the compiler analogy?
Compilers emit source-location diagnostics for every error: "this variable was declared at line 42 of file X, used at line 73 of file Y, and its type is wrong here." Governance provenance is the same property applied to rules: every active rule carries source-location metadata back to its authoring ADR, and the compiler-style trace is what makes rule changes inspectable rather than mysterious.
Is narrative documentation enough?
No. A freeform "rationale" field cannot be queried structurally, cannot be aggregated, drifts as context fades, and stores chains as paragraphs instead of relationships. Narrative can always be rendered on top of structural provenance, but structural provenance cannot be reconstructed from narrative after the fact.
Related operational essays

- The Emerging AI Agent Infrastructure Stack

  Provenance is its own layer in the agent infrastructure stack — the one that answers why a decision exists.

- AI Coding Governance Should Be Reviewable

  Governance verdicts must be inspectable, citable, and disagreeable — provenance is what makes that possible.

- Why Architectural Governance Needs Precedence Semantics

  Supersession is a precedence relationship; provenance preserves the resolved chain across iterations.

- Why CLAUDE.md Stops Scaling

  Free-form rule files have no structural provenance — which is why they degrade as the team grows.