# Architecture Decision Records — Trigger Rubric and Policy
Lightweight decision log. Captures **why** architectural choices were made, what alternatives existed, and what tradeoffs were accepted.
## Location
All ADRs live in `docs/adr/` as numbered markdown files: `NNNN-short-slug.md`.
## Numbering
Sequential four-digit prefix: `0001`, `0002`, etc. The template lives at `0000-template.md`.
## Trigger Rubric
Write an ADR when a change does **any** of the following:
| Introduces a new subsystem or domain boundary | Adding `apps/api/src/skills/` domain |
| Changes cross-package contracts in `packages/shared` | New schema, breaking schema change, new shared type |
| Adds or replaces an external dependency | Swapping HTTP client, adding AI SDK provider |
| Changes persistence model or config file format | New JSON store shape, migration from flat file to SQLite |
| Alters runtime architecture or middleware pipeline | New global middleware, SSE transport change |
| Changes build/test/deploy pipeline in a structural way | Switching test runner, adding CI workflow |
| Reverses or materially changes a prior ADR | Superseding an earlier decision |
### Skip ADR when
- Bugfix within existing patterns (no architectural change).
- Isolated UI/API feature inside established boundaries.
- Copy, styling, or polish changes.
- Dependency patch/minor version bumps.
- Refactors that preserve existing architecture (extraction, rename, dead code removal).
**Rule of thumb:** If future-you would ask "why did I do it this way instead of that way?" — write an ADR.
## Lifecycle
| `Accepted` | Active decision, currently in effect |
| `Deprecated` | Decision still in codebase but being phased out |
| `Superseded by ADR-XXXX` | Replaced by a newer decision; old ADR preserved as-is |
Solo workflow — no `Proposed` / approval gate. Decisions are written as `Accepted` at creation time.
## Revision Policy
| Decision materially changed | New ADR; mark old one `Superseded by ADR-XXXX` |
| Clarification, typo, link fix only | Update existing ADR in place |
| Decision no longer relevant | Mark `Deprecated` with date and reason in Status History |
## Linking
Reference ADR IDs in changelog entries for significant changes:
```md
- **Assistant Tool Plugin System** (ADR-0003): Plugin-based architecture with...
```
## Index
Maintain in `docs/adr/README.md`:
| ADR | Title | Status | Date |
| ---- | ------------------------------------------ | -------- | ---------- |
| 0000 | Template | Accepted | 2026-05-13 |
| 0001 | Use Rust for the MVP Runtime | Accepted | 2026-05-13 |
| 0002 | Use `~/.mc` for Configuration and Caches | Accepted | 2026-05-13 |
| 0003 | Separate Providers, Tools, and Subagents | Superseded by ADR-0005 | 2026-05-13 |
| 0004 | Use Token-Aware Context and Local Caching | Accepted | 2026-05-13 |
| 0005 | Subagent Parity and Tool Safety Boundaries | Accepted | 2026-05-13 |
| 0006 | Separate OpenAI API-Key and Codex OAuth Transports | Superseded by ADR-0018 | 2026-05-13 |
| 0007 | Opt-in Ratatui Mission Control TUI | Accepted | 2026-05-15 |
| 0008 | Settings JSON Covers Non-Secret Environment Configuration | Accepted | 2026-05-16 |
| 0009 | Reusable Terminal Markdown and Syntax Highlighting | Accepted | 2026-05-17 |
| 0010 | TUI Mouse Selection, Clipboard, and Toast State | Accepted | 2026-05-18 |
| 0011 | Dynamic Provider Model Catalog Discovery | Accepted | 2026-05-18 |
| 0012 | OpenAI Codex OAuth Callback and Token Lifecycle | Accepted | 2026-05-18 |
| 0013 | Runtime Markdown Prompt Templates | Accepted | 2026-05-19 |
| 0014 | Configurable Custom OpenAI-Compatible Providers | Superseded by ADR-0015 | 2026-05-19 |
| 0015 | Optional Auth for Custom OpenAI-Compatible Providers | Superseded by ADR-0018 | 2026-05-19 |
| 0016 | Subagent Identity Profiles | Accepted | 2026-05-19 |
| 0017 | Primary Agent Profiles and Main Prompt Boundary | Accepted | 2026-05-20 |
| 0018 | Codex OAuth and Custom Chat Completions Provider Boundary | Accepted | 2026-05-20 |
| 0019 | Persist Selected Primary Agent in Settings JSON | Accepted | 2026-05-20 |
| 0020 | Per-Tool Absolute Path Settings Default to Allowed | Accepted | 2026-05-20 |
| 0021 | Configurable Tool-Call Bash Hooks | Accepted | 2026-05-21 |
| 0022 | Session Title Metadata and Generation Boundary | Accepted | 2026-05-21 |
| 0023 | Use Full Structured Conversation Replay for Session Continuity | Accepted | 2026-05-23 |
| 0024 | Use Direct EXA REST for Bounded Search Tools | Accepted | 2026-05-26 |
| 0025 | Config-Controlled TUI Hook Visibility | Superseded by ADR-0026 | 2026-05-26 |
| 0026 | Session-Persisted Hook Activity | Accepted | 2026-05-26 |
| 0027 | Inherited Hooks for Subagent Runs | Accepted | 2026-05-26 |
| 0028 | Versioned Hook Context Envelope and Payload Capture | Accepted | 2026-05-26 |
| 0029 | Use TachyonFX for Configurable Mission Control Effects | Superseded by ADR-0040 | 2026-05-27 |
| 0030 | Session Compaction Checkpoints | Superseded by ADR-0052 | 2026-05-27 |
| 0031 | Custom Provider Endpoint Selection Config | Accepted | 2026-05-28 |
| 0032 | Display-Only Derived Transcript Cards | Accepted; TachyonFX details removed by ADR-0040 | 2026-05-31 |
| 0033 | Tokenizer-Backed Live TUI Context Projection | Accepted | 2026-06-01 |
| 0034 | Accept Deterministic `ffgrep` Contract for FFF Backend | Superseded by ADR-0038 | 2026-06-09 |
| 0035 | Normalize Settings JSON Schema Keys | Accepted | 2026-06-10 |
| 0036 | Add Cargo-Deny Supply-Chain CI Gate | Accepted | 2026-06-13 |
| 0037 | Non-Authoritative Session Metadata Index Sidecar | Accepted | 2026-06-14 |
| 0038 | Use `rg`-First `ffgrep` with Rust Fallback | Accepted | 2026-06-14 |
| 0039 | Defer Cargo-Vet Adoption | Accepted | 2026-06-14 |
| 0040 | Remove TachyonFX from Mission Control | Accepted | 2026-06-14 |
| 0041 | Opt-in Hook Provider Context Injection | Accepted | 2026-06-17 |
| 0042 | after_assistant and after_reasoning Hook Phases | Accepted | 2026-06-14 |
| 0043 | Prompt-Guidance Eval Harness Architecture | Accepted | 2026-06-20 |
| 0044 | View Image Tool Uses Tool-Internal Vision HTTP Requests | Accepted | 2026-06-20 |
| 0045 | MCP Stdio Client Tools | Accepted | 2026-06-21 |
| 0046 | MCP OAuth Token Authentication | Accepted | 2026-06-21 |
| 0047 | Embedded Blocking LSP Client Runtime | Accepted | 2026-07-08 |
| 0048 | Custom Provider Reasoning Protocol | Superseded by ADR-0049 | 2026-07-08 |
| 0049 | Provider-Wide GPT-Like Reasoning Capability | Superseded by ADR-0051 | 2026-07-11 |
| 0050 | Isolate Async Runtime for MCP HTTP GET-SSE Cancellation | Accepted | 2026-07-10 |
| 0051 | Metadata-Gated Custom GPT-Like Reasoning Capability | Accepted | 2026-07-11 |
| 0052 | Physical Session History Rotation | Superseded by ADR-0055 | 2026-07-11 |
| 0053 | Crates.io Distribution and Custom Source-Available License | Superseded by ADR-0054 | 2026-07-11 |
| 0054 | Apache 2.0 with Commons Clause for magi-code | Accepted | 2026-07-18 |
| 0055 | Opt-in Post-Turn Session Auto-Compaction | Accepted | 2026-08-09 |