Every software engineering team that adopts AI coding agents eventually confronts the same asymmetry: the team's architectural knowledge lives in ADRs, design documents, style guides, and team wikis — written for humans, describing decisions in narrative form. AI agents don't consume narratives as governance. They need constraint records: scoped, typed, precedence-resolved, machine-evaluable rules that can be checked against code output with a binary verdict.
The architectural compiler is the name for the transformation pipeline that converts the former into the latter. It is a deliberate, auditable compilation step — not an implicit, best-effort retrieval. The same way a code compiler converts source files into executables, the architectural compiler converts decision documentation into enforcement artifacts.
What compilation actually means in this context
Compilation in software engineering is a transformation with guarantees: same source, same output; type errors surface at compile time, not runtime; the compiled artifact is a first-class product that can be versioned, distributed, and deployed. The architectural compiler applies all three guarantees to governance decisions.
The transformation starts with source files — ADRs that include a structured ## Constraints section, governance configuration files, or manually authored decision records. It ends with a compiled governance corpus: project_memory.json. The corpus is not the documentation. It is the enforcement artifact — a separate, schema-validated, scope-assigned, precedence-resolved file that the governance runtime queries at code generation time.
The five stages of the compilation pipeline are sequential and each has a distinct purpose:
- Parse — extract decision records from source files
- Validate — check schema compliance, required fields, scope syntax
- Resolve — compute precedence, apply supersession, detect conflicts
- Emit — write validated, resolved records to the governance corpus
- Enforce — the compiled corpus is queried at generation time by the governance system
Compilation is the step that makes enforcement auditable. Same source files, same compiled output. If a constraint is being enforced that an engineer doesn't recognize, they can trace it to the ADR that produced it. If a decision was superseded, the supersession is recorded in the corpus. The audit trail is structural, not inferred.
Why this problem exists in AI-native development
The gap between documentation and enforcement is not new. In human-only development teams, that gap is bridged by people: engineers who read ADRs, internalize the decisions, and apply them in code review. The gap is tolerable because human review speed is the bottleneck. Reviewers have time to consult documentation, check precedent, and catch violations before they merge.
In AI-native development, the bottleneck shifts. AI agents generate code at 10–100x human pace. The review model that worked for human-speed development saturates immediately. Engineers cannot read every ADR before reviewing every AI-generated PR. The gap between documentation and enforcement — previously bridged by human expertise — becomes a structural liability: agents generate code freely because there is no mechanical mechanism to enforce the decisions that humans have documented.
The architectural compiler closes that gap mechanically. It doesn't require engineers to remember which ADRs apply to which codebase regions. It doesn't require reviewers to cross-reference documentation before approving. The compilation step converts the documentation into enforcement artifacts that the governance system applies automatically, at generation time, before code is ever committed.
Documentation describes decisions. Compilation enforces them. The distance between the two is where architectural drift lives. Every codebase with thorough ADRs and inconsistent AI-generated code has that distance — the documentation was never compiled into enforcement.
The common misread: retrieval as a substitute for compilation
The most common near-miss is treating RAG retrieval of documentation as equivalent to compilation. In this approach, ADR files are embedded in a vector store, and at query time, the most semantically relevant ADR passages are retrieved and injected into the model's context. The model receives prose that describes a decision and is expected to comply.
This is retrieval, not compilation. The distinction is fundamental:
| Property | RAG Retrieval | Architectural Compiler |
|---|---|---|
| Output type | Prose passages | Typed constraint records |
| Evaluation | Model interprets | Evaluator checks binary verdict |
| Determinism | Probabilistic retrieval | Same source = same output |
| Scope awareness | Semantic proximity | Explicit glob patterns |
| Conflict resolution | None — model decides | Precedence rules; compile-time error |
| Auditability | Which passages were retrieved? | Which records were compiled? From which source? |
A model receiving RAG context about a PostgreSQL decision can still choose to write SQLite code. The decision is context, not enforcement. A model evaluated against a compiled constraint record that says services/payments/** must not use SQLite produces a binary verdict: the constraint was respected or violated. The compiled record is not advice — it is enforcement.
The five stages in detail
Stage 1: Parse
The parser reads source files and extracts structured decision records. For ADR files, extraction targets the ## Constraints section — a structured addition to the standard ADR format that lists machine-extractable enforcement rules. Each constraint becomes a candidate decision record with fields populated from the ADR metadata: title, status, date, tags derived from context.
The parser is format-aware. It handles Markdown ADRs, YAML governance config, and directly-authored JSON records. Source format is an input concern; the output is always a normalized record structure before it enters validation.
Stage 2: Validate
The validator checks each parsed record against the governance schema. Required fields (id, title, constraint, type) must be present. Scope patterns, if provided, must be valid glob syntax. Tags must match the allowed taxonomy. Records that fail validation are rejected at compile time — they never enter the corpus.
This is the compile-time error mechanism. Problems in governance sources surface here, before they can produce undefined runtime behavior.
Stage 3: Resolve
The resolver handles precedence and supersession. When a new ADR supersedes an older decision, the resolver updates the older record's status to superseded and links it to the superseding record. When two decisions conflict — when they would produce contradictory verdicts for the same file and query — the resolver surfaces the conflict as a compile-time error rather than allowing the ambiguity to reach the enforcement runtime.
Stage 4: Emit
The emitter writes validated, resolved records to project_memory.json. The emit step is deterministic: same validated records, same JSON output, same file state. The emitted corpus is the governance artifact — it is version-controlled alongside the codebase and constitutes the auditable record of what is currently enforced.
Stage 5: Enforce
Enforcement is not strictly a stage of the compilation pipeline — it is what happens when the compiled corpus is queried. The governance runtime's retrieval layer reads the corpus, selects the relevant constraint records for a given query, and injects them as authoritative constraints. The evaluator checks the model's output against those constraints and emits a verdict. The compiler's work is done; enforcement is downstream.
A concrete before/after example
The clearest way to see what compilation does is to trace a single decision from source to corpus. Here is an ADR with a Constraints section, and the resulting compiled record.
The ADR prose explains the rationale. The compiled record is the enforcement artifact: it has a stable ID for tracking, a scope pattern for file-level targeting, a severity for verdict weighting, and a structured constraint field that the evaluator checks against. The rationale is preserved in the ADR source; the compiled record carries only what enforcement needs.
The ADR is the source file. The project_memory.json record is the compiled output. Modifying the ADR without recompiling doesn't change enforcement. The corpus is the authority — the source files are inputs to the compiler, not the governance artifact itself.
How this fits the AI SDLC
The architectural compiler runs as a developer operation or CI step. In practice: mneme import-adr docs/adr/ triggers a compile pass over all ADR files in the target directory, updates the corpus, and reports any validation or conflict errors. The compiled corpus is then committed to version control alongside the code changes that the ADRs govern.
The compilation step belongs in CI: when an ADR is merged, the CI pipeline runs the compiler, validates the output, and commits the updated corpus. This ensures the corpus is always current with the latest decision sources and that no unresolved conflicts enter the enforcement runtime. Compilation failures block the merge — the same way a build failure blocks a code merge.
This is what makes architectural governance tractable at scale. The enforcement corpus doesn't require human maintenance to stay current — it is produced mechanically from the source of truth (the ADRs) by a deterministic, auditable compilation step. The same guarantees that make code compilation reliable apply to governance compilation: same inputs, same output, errors surface early, the artifact is versioned and deployable.