Architecture Decision Records

An ADR records a decision that was expensive to make and would be expensive to reverse. It captures the forces, the choice, and — most importantly — the alternatives that were rejected and why.

Index

ADR Title Status
0001 Monorepo with independently released artifacts accepted
0002 A single local daemon, reached over Streamable HTTP accepted
0003 Ports and adapters as the top-level structure accepted
0004 SQLite is a derived artifact, never a Git-tracked one accepted
0005 Knowledge migrations are YAML domain operations, not SQL accepted
0006 Immutable revisions with optimistic concurrency accepted
0007 State-hash-partitioned databases for Git branches and worktrees accepted
0008 A RAPTOR forest, not a single tree accepted
0009 No vendor lock-in for LLM, embedding, or cloud providers accepted
0010 Source, Canonical, and Index are three distinct layers accepted
0011 Local MCP authentication and token handling accepted
0012 The plugin does not declare an MCP server; setup installs the connection accepted
0013 AI writes produce proposals, never approved state accepted
0014 Exact dependency pinning and pre-1.0 isolation accepted
0015 Developer Certificate of Origin, not a Contributor License Agreement accepted
0016 The state hash covers the working tree, not just committed migrations accepted
0017 SQLite schema version participates in the state hash accepted
0018 One writer, expressed as a lock in Milestone 1 and a queue later accepted
0019 Front matter is data, not governance metadata accepted
0020 Text projection of structured sources is a deterministic pure function accepted
0021 Fuse retrievers by rank, not by normalised score accepted
0022 The retrieval index lives in its own database file accepted
0023 A trigram index beside the word index, not instead of it accepted
0024 A purge is a build; a published index is never written accepted
0025 Sensitivity is enforced before 0.1.0 stable accepted
0026 Theurian is an evidence plane, not a control plane accepted
0027 Accept validates before it moves, and every revision pins its body accepted
0028 Proposals stay committable; a local proposal is a different directory accepted
0029 Review findings are governed knowledge, ingested from commit trailers accepted
0030 Review ingestion spawns gh, over public allowlisted repositories only proposed
0031 MCP tool input is validated against its published schema, in middleware accepted
0032 The write-intent MCP tool surface, and when writeTools flips proposed
0033 Candidate generation: the caller is the model; Theurian verifies the gate accepted
0034 migrate apply enforces the merge proposed
0035 Interactive curation of sources is agent-mediated and does not relax the approval gate proposed
0036 Golden judgements are committed regression fixtures, never a ranking input accepted

Writing a new ADR

  1. Copy 0000-adr-template.md to NNNN-kebab-case-title.md, using the next free number.
  2. Open it with status proposed.
  3. Reference requirement IDs from ../architecture/requirements-analysis.md.
  4. Fill in Alternatives considered. An ADR with no rejected alternatives is not recording a decision; it is recording a preference.
  5. Fill in Compliance. A decision with no enforcement mechanism will be violated within a quarter.
  6. Add a row to the table above.

Changing a decision

Do not edit an accepted ADR beyond typo fixes. Write a new one, set the old one's status to superseded by NNNN, and set the new one's Supersedes field. The history of the decision is the point.