Each file records one architectural decision: its context, the options weighed, the choice and its consequences. The format is MADR, after Michael Nygard. How records are written, reviewed and superseded is described in the design process.
Start a new record from TEMPLATE.md with the next free four-digit number, skipping any number the index reserves. A reservation holds a number for a decision whose record is not written yet. Its row gains its link when its record lands.
| Number | Decision | Status |
|---|---|---|
| 0001 | Record evidence as an append-only, hash-chained event ledger | Accepted |
| 0002 | Use SQLite as the storage engine | Accepted, superseded in part by 0027 |
| 0003 | Keep one ledger database per user, outside any checkout | Accepted, superseded in part by 0023 and 0027 |
| 0004 | Identify projects by a committed project file | Accepted |
| 0005 | Put storage behind a port with engine adapters | Accepted, superseded in part by 0010 |
| 0006 | Keep every operational record in the ledger | Accepted |
| 0007 | Anchor chain heads on the forge | Accepted, superseded in part by 0026 |
| 0008 | Use host sandboxes to keep agents out of the ledger | Accepted, superseded in part by 0020 and 0033 |
| 0009 | Serve instructions from the binary; files on disk are stubs | Accepted, superseded in part by 0038 |
| 0010 | Define the projector and event schema traits in the port | Accepted, superseded in part by 0021 |
| 0011 | Run one shared Baley server per user over stdio and HTTP | Superseded by 0034 |
| 0012 | Use optimistic concurrency in the shared server | Accepted |
| 0013 | Let the host session call outside models, never Baley | Accepted, superseded in part by 0027 and 0039 (credential wrapper, provider login, model detection and typed returns; Baley parses raw responses) |
| 0014 | Have Baley run tests and checks itself and judge by exit code | Accepted |
| 0015 | Keep settings in TOML: one global file, one project file, host sections | Accepted, superseded in part by 0027 |
| 0016 | Store provider API keys encrypted in the ledger with the master key in the OS secret store | Superseded by 0027, and in part by 0023 and 0039 |
| 0017 | Codify Scrum: a requirement is a story that carries its truths, a phase is a sprint | Accepted, superseded in part by 0031 |
| 0018 | Enforce the lease at task close on both hosts, with the guard as an early stop where it sees writes | Accepted, superseded in part by 0033 |
| 0019 | Run every configured reviewer, adjudicate in the host session, and let the owner rule on each finding | Accepted |
| 0020 | State what each host's sandbox denies; reads are the host's policy | Accepted, supersedes 0008 in part, superseded in part by 0027 and 0033 |
| 0021 | Claim liveness and scope rules in the port | Accepted |
| 0022 | Report owner-acknowledged restores behind a remote anchor | Accepted, superseded in part by 0035 |
| 0023 | Keep whole-store backups outside Baley | Accepted, supersedes 0003 and 0016 in part |
| 0024 | Separate port conformance from adapter mechanism tests | Accepted |
| 0025 | Point anchor tags at the empty tree | Accepted |
| 0026 | Anchors are read by Baley, and a missing tag ruleset is reported | Accepted, supersedes 0007 in part |
| 0027 | Keep Baley's files in its own crenshawdev folders, with provider keys in a plain keys.env | Accepted, supersedes 0016, and 0002, 0003, 0013, 0015 and 0020 in part, superseded in part by 0032, 0033 and 0039 |
| 0028 | Use one HTTP stack on tokio and hyper: reqwest for outgoing calls, axum for the MCP server | Accepted, superseded in part by 0034 and 0039 |
| 0029 | Let a host offer more than the floor | Accepted, superseded in part by 0033 |
| 0030 | Put refinement and planning decisions to the owner in dependency-ordered question rounds | Accepted |
| 0031 | Use one term per concept, kept in a glossary: phase, not sprint, and story, not requirement | Accepted, supersedes 0017 in part |
| 0032 | Drop Gemini from the model catalog and detection | Accepted, supersedes 0027 in part, superseded in part by 0039 |
| 0033 | Support only hosts whose sandboxing and execution controls meet Baley's requirements | Accepted, supersedes 0008, 0018, 0020, 0027 and 0029 in part, superseded in part by 0039 |
| 0034 | Run one Baley server per session over stdio | Accepted, supersedes 0011, and 0028 in part |
| 0035 | Report purge uncertainty after restoring a store | Accepted, supersedes 0022 in part |
| 0036 | Keep guard records per user and bound the guard's access | Accepted, superseded in part by 0040 |
| 0037 | Choose plan re-check scope explicitly | Accepted |
| 0038 | Install with one command and update only by choice | Accepted, supersedes 0009 in part |
| 0039 | Leave provider credentials and calls with the session | Accepted, supersedes 0013, 0016, 0027, 0028, 0032 and 0033 in part |
| 0040 | Judge and remember a commit at its target checkout | Accepted, supersedes 0036 in part |
| 0042 | Prove assembled behavior with mocked-boundary integration checks | Accepted |