The architectural compiler. The pipeline that converts documentation-form decisions — ADRs, design docs, style guides — into machine-evaluable constraint records. Parse → validate → resolve → emit → enforce. Compilation is the discrete, auditable step that closes the gap between what teams document and what AI agents are governed by.
Concepts 12 min read · May 2026

# Architectural Compiler

There is a gap between what engineering teams document and what AI coding agents are governed by. Documentation describes decisions in prose. Governance requires decisions in structured, scope-assigned, precedence-aware constraint records. The architectural compiler is the pipeline that crosses that gap.

By Theo Valmis · Published May 2026

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.

Compilation is a transformation with guarantees. Five sequential stages turn documentation into a typed, versioned, scope-aware decision corpus. Schema and conflict errors fail at compile time — not at enforcement time, not in production.

## 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:

1. Parse — extract decision records from source files
2. Validate — check schema compliance, required fields, scope syntax
3. Resolve — compute precedence, apply supersession, detect conflicts
4. Emit — write validated, resolved records to the governance corpus
5. 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.

Source: ADR-007.md (Constraints section)
## Constraints rule: The payments service must not use SQLite as a primary or fallback database. Use PostgreSQL only.
Compiled: project_memory.json record
{ "id": "pay-db-001", "type": "decision", "title": "Payments DB: no SQLite", "constraint": "services/payments/** must not use SQLite", "scope": "services/payments/**", "severity": "blocking", "tags": ["database", "payments", "sqlite"], "source_adr": "ADR-007", "status": "active" }

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.

## Frequently asked questions

What is an architectural compiler?
An architectural compiler is the pipeline that transforms documentation-form decisions — ADRs, design docs, style guides — into machine-evaluable constraint records. It performs five stages: parse (extract decision records from source files), validate (check schema and required fields), resolve (compute precedence and detect conflicts), emit (write validated records to the governance corpus), and enforce (the compiled corpus is queried at generation time). Compilation is the discrete, auditable step that closes the gap between what teams document and what AI agents are governed by.
What does the architectural compiler do with existing ADRs?
The compiler reads ADR files that contain a structured Constraints section, extracts each constraint as a typed decision record, validates it against the governance schema, resolves any precedence or supersession relationships with existing records, and emits the validated records to project_memory.json. The ADR itself remains unchanged — the compiler produces a separate compiled artifact that the governance runtime uses for enforcement.
Why is compilation necessary — why not just use documentation directly?
Documentation and enforcement are different artifacts. An ADR explaining why PostgreSQL was chosen is documentation — it describes a decision and its rationale. A constraint record that says "services/payments/** must not use SQLite" is enforcement — it is a machine-evaluable rule with scope, precedence, and a structured field for evaluation. Documentation cannot be evaluated against code output without first being compiled into constraint records. Retrieving ADR prose and injecting it into a prompt is context retrieval, not compilation — and it doesn't provide the scope assignment, precedence resolution, or schema validation that enforcement requires.
What are the five stages of architectural compilation?
The five stages are: (1) Parse — extract decision records from source files such as ADRs with a Constraints section; (2) Validate — check schema compliance, required fields, and scope syntax; (3) Resolve — compute precedence, apply supersession relationships, and detect conflicts between decisions; (4) Emit — write validated, resolved records to project_memory.json as the compiled governance corpus; (5) Enforce — the compiled corpus is queried at code generation time by the governance system's retrieval layer.
How is the architectural compiler different from RAG over documentation?
RAG over documentation retrieves prose passages that describe decisions. The architectural compiler produces structured constraint records that enforce them. RAG retrieval is probabilistic and outputs natural language context; the compiled corpus is deterministic and outputs machine-evaluable constraints. A model receiving RAG context about a decision can still choose to violate it — the decision is advice, not enforcement. A model evaluated against a compiled constraint record produces a binary verdict: the constraint was respected or it was not.
Operational implications

- Why RAG Fails for Architectural Governance

  Semantic retrieval finds related text. Governance requires scoped, precedence-resolved constraint records.

- Why CLAUDE.md Stops Scaling

  Prompt files document standards but cannot deterministically enforce them across sessions and agents.

- Why Architectural Governance Needs Precedence Semantics

  When ADRs overlap, the system needs deterministic resolution — not best-effort guessing from a model.

- Prompt Engineering Is Not Governance

  Prompt templates nudge output. They cannot enforce architectural invariants across sessions and agents.

Enforcement surfaces

- ADR Import

  Ingests existing ADR corpora and compiles them into enforcement-ready constraint records.

Related demos

- ADR Compiler

  Compiles a versioned ADR corpus into machine-evaluable constraint records.

Related concepts

- Verification Contracts

  Pre-registered, machine-evaluable claims a generated artifact must satisfy before it is allowed to land.

- Precedence Semantics

  Explicit resolution rules for how overlapping or superseding decisions combine into a single verdict.

- Governance Infrastructure

  The engineering platform layer that encodes, distributes, versions, and enforces architectural decisions across agents and CI.