0001. Record architecture decisions
- Status: Accepted
- Date: 2026-11-14
- Decided by: Mik (Build plan, rule 5)
Context
The framework is built by agents that start cold. Without a written record, a future session cannot tell a deliberate choice from an accident, and will either re-argue it or break it.
Decision
Every significant choice gets a numbered record in docs/decisions/, using 0000-template.md: context, decision, alternatives and consequences. Records are never edited after acceptance except to change their status; a new record supersedes an old one and links to it.
"Accepted (provisional)" marks a decision taken on a recommendation while Mik's answer is pending. It is binding for implementation and reversible by Mik with a superseding record.
Alternatives considered
| Option | Why not |
|---|---|
| Decisions in pull request descriptions | Not findable by an agent in a fresh workspace |
| A single decisions log file | Grows into a wall; individual records can be linked and superseded |
Consequences
Agents must check docs/decisions/ before changing anything a record covers, and write a record for any choice a future reader would question (definition of done).