Skip to content

Architecture Decision Records

Status: verified — ADR index is the load-bearing list

Every accepted ADR in this directory is a first-class architectural commitment. New decisions add an ADR; old decisions are never edited once accepted — they are replaced by new ADRs that reference and supersede them.

What an ADR is, and what it is not

An Architecture Decision Record captures a single decision that has already been made, with enough context that a future reader (or a future version of ourselves with no session memory) can understand why it was made and whether the justification still holds.

ADRs are not:

  • Feature specs. Those live in plans/.
  • Research notes. Those live in research/.
  • API documentation. Those belong next to the code.

ADRs are:

  • A record that a decision was made, by whom, and when.
  • The evidence that was available at the time.
  • The consequences — both the ones we wanted and the ones we accepted as trade-offs.

Filing conventions

  • Filename: NNNN-kebab-case-title.md where NNNN is a zero-padded sequential number assigned at filing time. Numbers are never reused.

  • Every ADR starts with YAML frontmatter:

    ---
status: accepted | superseded | rejected | proposed
date: YYYY-MM-DD
superseded-by: NNNN-...  (only when status == superseded)
---

  • Body follows the Michael Nygard pattern: Title, Status, Context, Decision, Consequences, Evidence, References. See template.md for the exact shape.

  • An accepted ADR is immutable — fixing a typo is allowed, but any change that affects the meaning opens a new ADR that supersedes the old one.

Current ADRs

# Title Status Date
0001 Use pymobiledevice3, not go-ios accepted 2026-03
0002 pymobiledevice3 tunneld runs inside the macOS VM, not on the Linux host accepted 2026-04
0003 pymobiledevice3 changes live as a patch overlay, not a GitHub fork accepted 2026-04-13
0004 Stage 2 uses Option δ (CDS → local shim), not α/β/γ accepted 2026-04-13
0005 Phase D backend is Go only; no new production Python accepted 2026-04-13
0006 Empirical-only discipline: no guessing in research or planning accepted 2026-04-13
0007 Documentation site is MkDocs + Material for MkDocs accepted 2026-04-13
0008 Pin MkDocs 1.x, reevaluate docs engine in October 2026 accepted 2026-04-13

Future ADRs

The list above is the complete set as of the docs reorganization (Phase 4). New ADRs arrive as decisions are made. Backfilling old decisions that predate the ADR framework is allowed as long as the date: field reflects when the decision was originally made, not when it was written down.