# v0.4.0 — Architectural Compiler Foundation

**Mneme is now the architectural compiler for AI-assisted development.**

ADRs become the source of truth; the compiler is the deterministic rule
for turning them into the constraints the runtime injects.

---

## What's new

```
ADR corpus  ->  parse  ->  validate  ->  resolve precedence
            ->  active constraint set  ->  Decision records  ->  runtime
```

- **`mneme/adr_schema.py`** — `ADR` dataclass, `ADRStatus` /
  `ADRPriority` enums, typed errors (`ADRParseError`,
  `ADRValidationError`, `ADRPrecedenceError`).
- **`mneme/adr_parser.py`** — `parse_adr_file`,
  `parse_adr_directory`. YAML frontmatter parser; structural failures
  only (missing / unterminated / malformed frontmatter).
- **`mneme/adr_compiler.py`** — three public stages plus an
  orchestrator and a Decision bridge:
  - `validate_corpus(adrs)` — aggregates required-field, enum, id /
    date / scope grammar, `supersedes` reference resolution, and
    cycle-detection errors into a single `ADRValidationError`. One
    pass, every error.
  - `resolve_precedence(adrs)` — returns the active constraint set:
    status filter → explicit `supersedes` (chain-aware) → same-scope
    priority → newer date → `ADRPrecedenceError` if still ambiguous.
    The compiler never silently picks a winner.
  - `compile_adrs(adr_dir)` — end-to-end: parse → validate →
    precedence; output ordered most-specific-first.
  - `adrs_to_decisions(adrs)` — bridge into the existing `Decision`
    schema so the v0.3.x runtime pipeline (`DecisionRetriever`,
    `ConflictDetector`, `ContextBuilder`) consumes ADR-driven corpora
    without code changes.

### ADR frontmatter

```yaml
---
id: ADR-001
title: Use JSON file storage
status: accepted          # proposed | accepted | deprecated | superseded
priority: foundational    # foundational | normal | exception
date: 2026-01-10
scope: storage            # dotted path; empty string = global
supersedes: []
---

Body markdown follows.
```

### Usage

```python
from mneme.adr_compiler import compile_adrs, adrs_to_decisions
from mneme.decision_retriever import DecisionRetriever

decisions = adrs_to_decisions(compile_adrs("docs/adr"))
retriever = DecisionRetriever(decisions)
```

---

## Why this matters

Until v0.4.0, Mneme was a retrieval + enforcement layer on top of a
hand-edited JSON file. Useful, but not a foundation: nothing told you
what the *correct* set of constraints was at any given point in time.

v0.4.0 makes the corpus declarative and the resolution deterministic.
The same ADR set always compiles to the same active constraint set;
conflicts surface as compile errors rather than as silent drift in
behavior. That is the foundation the rest of the governance roadmap
(retry/remediation, drift detection, cross-project memory) builds on.

---

## Migration

No migration needed. ADR ingestion is opt-in and additive:

- Existing `project_memory.json` workflows are unchanged.
- `MemoryStore`, `Pipeline`, the v0.3.x enforcement modes, and the
  Claude Code hook all keep working as-is.
- Adopt ADRs by wiring `compile_adrs` → `adrs_to_decisions` into your
  retriever construction; mix freely with JSON-backed decisions.

---

## Tests and compatibility

- 47 new tests across parser, validator, precedence, integration.
- Full suite: 217 passed, 2 skipped (same e2e skips as v0.3.2).
- Zero regressions; `MemoryStore` / `Pipeline` / `DecisionRetriever`
  unchanged.

---

## Deferred (not in this release)

- `mneme adr compile <dir>` CLI subcommand (library API is sufficient
  for v1; CLI is a v0.5 candidate).
- `Pipeline.from_adr_dir()` classmethod (callers can wire
  `adrs_to_decisions(compile_adrs(dir))` themselves).
- Structured `constraints:` / `anti_patterns:` frontmatter fields.
- Hyphenated scope segments and multi-scope lists.
- Body-section parsing.
- The formal `docs/adr/ADR-003-architectural-constraint-metadata-schema.md`
  spec doc — schema is described in the README, CHANGELOG, and code;
  authoring the canonical ADR is queued for v0.5.

---

## Strategic framing

| Version | Theme |
|---|---|
| v0.3 | Enforcement / governance checks |
| **v0.4** | **Architectural compiler foundation** |
| v0.5+ | Advanced precedence / drift detection / structured constraint fields |
