adr

Architecture Decision Records

This directory tracks the non-trivial design decisions of the project. Each ADR follows Michael Nygard's template:

# N. Short title

Date: YYYY-MM-DD

## Status
Proposed | Accepted | Deprecated | Superseded by ADR-NNNN

## Context
What's the situation that's forcing a decision?

## Decision
What's the decision we made?

## Consequences
What becomes easier? What becomes harder?

Index

• ADR-0001 — Single-prompt sh -c chain for safe-flash pipeline
• ADR-0002 — 1 MiB padded image with 0xFF for W25Q80 writes
• ADR-0003 — pkexec/sudo escalation over a setuid helper
• ADR-0004 — CH341A USB vendor:product hardcoded, not configurable
• ADR-0005 — Firmware trust root is hdzero.go-next.co (provisional)
• ADR-0006 — Hard-coded __version__ in main.py
• ADR-0007 — MIT source / GPL-v3 binary distribution position

When to write a new ADR

A decision warrants an ADR when:

• It's not derivable from reading the code
• A reasonable engineer would want to know why in addition to what
• Changing the decision would have non-trivial blast radius

The PR template (.forgejo/PULL_REQUEST_TEMPLATE.md) has an "ADR added or referenced" checkbox in the Test plan section; tick it when the PR introduces a non-trivial decision.