Architecture Decision Records (ADRs)

This directory holds durable architectural decisions for AletheIA. ADRs are written when a decision is hard to reverse, affects multiple parts of the framework, or settles a recurring ambiguity that has cost time to re-litigate.

What an ADR is — and is not

• Is: a record of why we decided something at a specific date, with the alternatives we rejected and the conditions that would reopen the decision.
• Is not: a tutorial, a roadmap, or a contract spec. Those live in docs/concepts/, docs/roadmaps/, and docs/contracts/ (taxonomy in progress — see the structural improvement plan).

If a document explains how to do something, it is a guide. If it specifies what must be true, it is a contract. ADRs answer why this path and not another.

Convention

• Format: lightweight, repo-native. Not strict MADR — adopted incrementally as needed.
• Filename: ADR-NNN-<kebab-case-title>.md, with NNN zero-padded.
• Numbering: monotonic, never reused. If an ADR is superseded, the new ADR gets the next number and links back via the Supersedes field.
• Status values: Proposed, Accepted, Superseded by ADR-XXX, Rejected, Deprecated.
• Length: prefer ≤2 pages. If an ADR grows past that, the decision is probably mixing two concerns.

Required structure

Every ADR starts with a metadata table:

| Field | Value |
|---|---|
| Status | Accepted |
| Date | YYYY-MM-DD |
| Author | <name> |
| Deciders | <names> |
| Related | ADR-XXX — <title> |
| Supersedes | — or ADR-XXX |

Followed by numbered sections:

1. Context — what is the state of the world and what is the open question.
2. Decision — what we decided, in normative voice.
3. Consequences — positive, negative, and accepted tradeoffs.
4. Alternatives considered — what we rejected and why.
5. Relationship — to other ADRs, phases, or artifacts that depend on this decision.
6. Review — conditions that would reopen the ADR.

See ADR-001 as the canonical example.

When to write an ADR

Write one when:

• A decision will be cited or contested across multiple PRs or sessions.
• A boundary is being drawn (what belongs / what does not belong).
• An autonomy or safety threshold is being fixed.
• A path is being chosen that closes off other paths for a non-trivial period.

Do not write one for:

• Implementation choices that are obvious from the code.
• Decisions that only affect a single PR’s scope.
• Documentation reorganization (use the docs index + migration table instead).

Current ADRs