Architecture Decisions¶
Records of the decisions that shape this project, and — more usefully — the reasons behind them. An ADR is written when a choice is hard to reverse or likely to be re-proposed.
The point is not the decision; it is the alternatives that were rejected and why. A record that only states the outcome saves nobody the argument.
A decision is changed by writing a new ADR that supersedes the old one, never by editing the old one. The history is the value.
Format¶
NNN-kebab-case-title.md, numbered in the order written, with the sections:
- Status — Proposed, Accepted, or Superseded by ADR-NNN
- Context — the forces in play, before any decision
- Decision — what was decided
- Consequences — what this costs, including what it makes harder
Index¶
| # | Decision |
|---|---|
| 001 | Two binaries, one crate |
| 002 | An overlay is a directory and a cascading descriptor chain, not a git repository |
| 003 | Overlay descriptors tolerate any format on read; format only governs what over new writes |
| 004 | Install configuration is declarative package sets with an explicit shell escape hatch |
| 005 | Async is scoped to I/O concurrency, not a scheduled execution plan |
| 006 | Symlink-first apply, with two explicit widening escape hatches |
| 007 | git2 is a direct dependency of the CLI layer, not confined to actions::git |
| 008 | uses composition is a flat union of independent trees, not a layered override |
| 009 | over lint is a separate, tolerant, pre-deserialization static-analysis pass |
| 010 | Templating is scoped to path-resolution strings, not file content |
| 011 | Plan-then-execute reconciliation, amending ADR-005 and ADR-006 |
| 012 | Materializer backend registry, amending ADR-011 |
| 013 | diff has its own taxonomy and uses similar for content diffs, amending ADR-011 |
| 014 | Bidirectional checkout synchronization is over sync, scoped to an overlay's root git entry |
| 015 | unapply reuses Plan's classification and only ever removes safely reversible state |
| 016 | Partial files are managed blocks injected via a sidecar, not a stem-plus-sidecar pair |
| 017 | Materialization rules generalize link_dirs into path/subtree overrides, amending ADR-006 |
| 018 | Root-declared overlays: paths extend descriptor-glob discovery, amending ADR-002 |
| 019 | default_overlay extends templating to overlay selection, amending ADR-010 |
| 020 | File permissions are hierarchical rules scoped to PartialFile entries |
| 021 | Declared (non-root) git repositories report provisioning status, not content status, amending ADR-014 |
| 022 | Virtual checkout materialization, distinct from overlay.git's Checkout, amending ADR-017 |
| 023 | Merge git-over into over as a nested git subcommand, superseding ADR-001 |
| 024 | over doctor aggregates existing diagnostics and repairs only its own corruption |