Architecture Decision Records
Significant technical decisions in Margin are recorded here, with the context and alternatives at the time they were made. The code says what; ADRs say why — so future contributors (and future us) don’t relitigate settled questions or, worse, silently unsettle them.
Process
- A decision is significant if reversing it later would cost more than a day, or if a reviewer could reasonably ask “why is it done this way?” Dependency choices, crate boundaries, file formats, user-facing contracts, and policies (errors, MSRV, releases) all qualify. Naming a variable does not.
- Copy
template.mdtoNNNN-short-slug.md(next number), open a PR. The PR discussion is the decision review. - Statuses:
Proposed→Accepted→ (Deprecated|Superseded by ADR-NNNN). Never edit an accepted ADR’s decision — write a new one that supersedes it. History is the point. - PRs that contradict an accepted ADR must include the superseding ADR.
Index
Relationships (amended/superseded clauses) are noted here so no one trusts a stale sentence: the linked ADRs themselves are never rewritten.
| ADR | Title | Status | Notes |
|---|---|---|---|
| 0001 | Implementation language: Rust | Accepted | |
| 0002 | TUI stack: ratatui + crossterm | Accepted | |
| 0003 | App pattern: Elm architecture with a pure core | Accepted | |
| 0004 | Four-crate workspace with one I/O seam | Accepted | I/O seam widened by 0019 |
| 0005 | Git access via git2, quarantined behind DiffSource | Accepted | DiffSource is the read-only seam; writes joined it via 0019 |
| 0006 | Highlighting via syntect; intra-line diff via similar | Accepted | Warming clause superseded by 0026 |
| 0007 | CLI mirrors Git verbs; pager passthrough guarantee | Accepted | Exit-code wording superseded by 0022 |
| 0008 | Configuration: TOML, XDG + repo-local | Accepted | Parity rule exempted for safety hatches by 0017 |
| 0009 | Errors: thiserror in libs, anyhow at the edge, no panics | Accepted | |
| 0010 | Testing: snapshots, temp repos, corpus, fuzz, benches | Accepted | |
| 0011 | Releases: cargo-dist, Conventional Commits, MSRV policy | Accepted | Package identity amended by 0025 |
| 0012 | License: MIT OR Apache-2.0 | Accepted | |
| 0013 | Hunk staging: index-only, dry-run first, exact bytes | Accepted | |
| 0014 | Discard: trash before destroy, worktree-only, typed confirm | Accepted | Persistent opt-out superseded by 0017 |
| 0015 | Forge access through the user’s gh CLI, quarantined in margin-vcs | Accepted | |
| 0016 | Completions and the man page generate at runtime from the binary | Accepted | |
| 0017 | Unbacked discard is an explicit, per-invocation escape hatch | Accepted | |
| 0018 | No implicit network access or telemetry | Accepted | |
| 0019 | Explicit read, write, and runtime effect seams | Accepted | |
| 0020 | Persist review state as one versioned, atomic record | Accepted | |
| 0021 | Selective user-facing compatibility before 1.0 | Accepted | |
| 0022 | Distinguish clean, operational, and invocation outcomes | Accepted | |
| 0023 | Tool-neutral human review boundary through 1.0 | Accepted | |
| 0024 | SHA-pinned, least-privilege CI supply chain | Accepted | |
| 0025 | Publish the Margin binary as the margin-review package | Accepted | |
| 0026 | Highlight warming is per-frame budgeted fill-in, not a background thread | Accepted | |
| 0027 | Refuse invocations that would review something other than what was given | Proposed | Applies 0007’s “refuse loudly” to piped stdin and misplaced root flags |