Architecture Decision Records (ADRs)¶
ADRs capture significant architectural decisions, the context behind them, and their consequences. Each ADR is a short Markdown document in this folder, numbered sequentially.
When to write an ADR¶
Write an ADR when:
- You make a decision that has architectural weight (affects the wire format, the threading model, deployment, or a public contract).
- You make a decision that future-you will want to remember the reasoning for, beyond what a commit message captures.
- You override a previous decision (write a new ADR; mark the old one as superseded).
Don't write ADRs for routine implementation choices, code-style decisions, or short-lived tactical decisions.
Format¶
Each ADR follows the canonical form:
# ADR-NNNN: <Short title>
## Status
Accepted / Proposed / Superseded by ADR-MMMM / Deprecated
## Context
Why is this decision needed? What's the situation?
## Decision
What did we decide?
## Consequences
What follows from the decision — both intended and accepted
trade-offs.
Index¶
| ADR | Title | Status |
|---|---|---|
| 0001 | RH plugin manifest dependency format | Accepted |
Candidates harvested from the plan archive¶
The following decisions are documented inside individual plan files in the source repo (not part of this consolidation). They have ADR-shaped substance and would benefit from being lifted into this index when there is time:
| Topic | Source plan |
|---|---|
| Single state lock + "never hold across RF I/O" rule | plans/hi-claude-i-am-lively-pancake.md (P1-4) and the project-wide audit (A-series) |
| Exclusive USB ownership of the gateway | plans/hi-claude-i-am-lively-pancake.md (P3-5) |
OPC_OFFSET tagged-union body shape |
plans/der-offset-mode-formula-modes-followup.md |
Strict symmetric OFFSET_MODE acceptance gate |
plans/der-offset-mode-in-szenen-serialized-quilt.md (audit batch — Strategy A scope filter, state-stickiness rule) |
| Continuous-RX firmware default + host-side request matching | plans/der-offset-mode-in-szenen-serialized-quilt.md (Transport Interface Redesign section) |
Synchronous _send_m2n outcome contract (EV_TX_DONE / EV_TX_REJECTED) |
plans/der-offset-mode-in-szenen-serialized-quilt.md (Batch B) |
OPC_PRESET vs OPC_CONTROL rename (Phase D) |
plans/effect-vs-preset-terminology-cleanup.md |
Persistent per-device phase offset on strip.timebase |
plans/seit-den-letzten-nderungen-sleepy-wolf.md |
| State-scope token system | plans/du-hast-f-r-mich-witty-crystal.md |
These plan files are internal to the source repository (under
.claude/plans/); see ../../HARVEST.md for
which content has already been folded into the public docs.