Architectural decisions overlap. That is not a flaw — it is how engineering teams accumulate knowledge. A broad standard ("services use the repository pattern") gets carved by a narrower exception ("legacy billing keeps direct DAO access until migrated"). A newer ADR supersedes an older one. A team-wide convention has a service-specific override. The shape of real-world governance is layered, not flat.
The question is not whether overlaps will exist. They will. The question is: when two decisions both apply to the file the agent is about to write, which one wins, and is that answer the same on every run, on every machine, from every consumer? The rules that determine the answer are the precedence semantics.
What precedence semantics actually mean
A precedence semantics is a function from a set of matching decisions to a single winning decision. Given two or more records whose scope patterns both match the same query, the semantics deterministically selects one — and the selection is auditable. Every overlap maps to a single answer, and every answer cites the rule that produced it.
The semantics has three structural properties that distinguish it from ad-hoc conflict handling:
- Total — every conflict resolves to a winner. There is no "tie" that defers to user judgment or model guessing.
- Deterministic — the same set of records always produces the same winner, regardless of which order they were loaded, retrieved, or evaluated.
- Citable — the winner is accompanied by the precedence rule that selected it. "ADR-0042 won by supersession" is a usable audit record; "ADR-0042 was chosen" is not.
The standard precedence ladder
Mneme's precedence ladder uses four rules, evaluated top-to-bottom. The first rule that produces a winner halts the descent. Subsequent rules never re-open a resolved precedence.
1. Supersession
If one decision explicitly supersedes another within the overlapping scope, supersession wins. Supersession is an authored relationship: the newer decision declares supersedes: ADR-0017 in its metadata. This is the strongest precedence rule because it represents an explicit team statement that decision A is replaced — not just refined — by decision B.
2. Scope specificity
If no supersession applies, the more specific scope wins. services/billing/legacy/** beats services/** because the legacy scope explicitly addresses a narrower region. Specificity is computed structurally on the glob: depth, literal segments, and explicit anchors. The rule is mechanical, not semantic — there is no model judgment of "which feels more specific."
3. Recency
If scopes are equally specific, the more recently created decision wins. This rule encodes a soft preference for newer team thinking, but it is intentionally below specificity — a broad new decision should not silently override an older narrow exception. Recency breaks ties, not standards.
4. Severity escalation
If recency ties, the higher-severity decision wins as a final tiebreaker. This rule almost never fires in practice — its existence is mostly to ensure the function is total: every conflict has a defined answer, even pathological ones.
Conflict cases that the ladder cannot resolve are compile-time errors. Two decisions with identical scope, identical severity, identical timestamps, and no supersession link — the compiler refuses to emit the corpus until the team resolves the ambiguity. The runtime never sees an unresolved conflict.
Why precedence has to be at compile time, not runtime
It is tempting to imagine precedence as a runtime concern — let the governance system look at each matching decision and pick one when the query arrives. That model fails for the same reason ambiguous runtime behavior fails generally: it is unauditable and untestable.
Compile-time precedence has three properties runtime precedence cannot match:
- Conflicts surface during build, not during enforcement. If two decisions cannot be reconciled, the compilation step fails. Engineers see the conflict in their PR or in CI, not in production after a violation slipped through.
- The resolved corpus is reviewable. Teams can inspect which decision applies to which scope before any agent queries the corpus. The resolved precedence is itself a versioned artifact.
- Resolution is identical across all consumers. Because precedence resolves at compile time, every consumer reads an already-resolved corpus. No consumer has to re-implement the precedence rules — and therefore no consumer can drift from them.
Runtime precedence, by contrast, leaves each consumer to implement its own resolution. Two consumers can disagree about the winner, and the disagreement is invisible until both produce different verdicts. This is one of the most common failure modes in ad-hoc governance setups: every tool reads the same rules and quietly applies them differently.
The common misread: longest-rule-wins or first-match-wins
Two ad-hoc precedence rules show up often in real systems and are both unsuitable for governance:
| Rule | Where it appears | Why it fails for governance |
|---|---|---|
| First-match-wins | Many config systems, .gitignore-style | Ordering becomes load-order-dependent — non-deterministic across consumers |
| Longest-rule-wins | Routing tables, some linters | Depth ≠specificity for paths; ignores authoring intent like supersession |
| Most-specific-wins (alone) | CSS, some policy engines | Cannot model "this decision replaces that one" — supersession needs explicit precedence |
| Newest-wins (alone) | Document-oriented systems | A new broad rule silently shadows older targeted exceptions |
The right model is a composition: supersession first (because it captures explicit intent), then specificity (because it captures author-known scope narrowing), then recency (because it captures team evolution), with severity as a final tiebreaker. Each rule alone fails in some real-world case; together, they cover the cases teams actually have.
What precedence semantics enable
Precedence semantics are the prerequisite for several other governance properties:
- Deterministic enforcement — without a deterministic conflict-resolution rule, the same query can produce different verdicts. Determinism downstream depends on precedence determinism upstream.
- Auditability — every enforcement event cites both the winning decision and the precedence rule that selected it. "Blocked by ADR-0042, winner by supersession over ADR-0017" is a complete audit record.
- Safe evolution — teams can supersede, narrow, or refine decisions without fearing silent regressions. The compiler surfaces every overlap; the ladder handles every resolution.
- Cross-consumer agreement — Claude Code, Cursor, Copilot, and CI all reach the same verdict because they all read an already-resolved corpus. Propagation depends on precedence resolution happening upstream of distribution.
Related concepts
- Architectural compiler — the pipeline in which precedence resolution happens. The "resolve" stage is precedence semantics applied to the candidate record set.
- Deterministic enforcement — the property that depends on precedence resolution producing the same answer every time.
- Governance propagation — the property that becomes meaningful when every consumer reads an already-resolved corpus. Without precedence, propagation distributes ambiguity.