Governance provenance

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."

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."

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

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.

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.