Decision records

The design decisions behind Sponson and why they were made.

Each record states one decision: the context that forced it, what was decided, and what follows from it (Michael Nygard’s format). They explain why the code is the way it is; ARCHITECTURE.md explains where it is.

#	Decision	Status
0001	The plan file is YAML, not a DSL	Accepted
0002	Three commands	Accepted
0003	Receipts live on an orphan git branch, behind a ReceiptStore interface	Accepted; amended by 0016
0004	Apply phases are inferred from output availability	Accepted
0005	Receipts are a ledger keyed by resource identity, with write-ahead intents	Accepted
0006	Four kinds of drift, and apply refuses changed values	Accepted
0007	{ keep: true } for adopting existing values	Accepted
0008	Scopes, pull request succession, and leases	Accepted
0009	Single-point redaction	Accepted
0010	One JSON envelope and an ERROR_CODES table	Accepted
0011	Testing against a local fake cloud with chaos, scenarios, journeys and property invariants	Accepted
0012	One flat plan with per-line environment filters; production is never inferred	Accepted
0013	Rollback undoes only what this run created	Accepted
0014	Secrets are references, never values	Accepted
0015	Adapters and secret sources describe themselves	Accepted
0016	One receipts branch per environment and scope	Accepted
0017	A generic, declarative http adapter	Proposed
0018	Once-only outputs resolve to { keep: true } after the run that revealed them, when fingerprints prove it	Proposed
0019	Locks on shared parent objects	Accepted
0020	Recipes: verified http specs as one-line building blocks	Proposed
0021	Manual steps for state no API can manage	Proposed
0022	One-off actions: http.action	Proposed
0023	Cloud Run revisions: cloud_run.revision	Proposed

Writing a new record

Write one when a change alters something a record describes, or makes a choice a future contributor would otherwise have to rediscover: a new command, a change to the plan format or the receipt shape, a new invariant, a new dependency between packages.

1. Copy the structure of an existing record: a numbered title, Date, Status, Context, Decision, Consequences.
2. Use the next free number: NNNN-short-title.md.
3. Status is Proposed in the pull request and Accepted when it merges. Records are not rewritten later; a decision that changes gets a new record, and the old one’s status becomes Superseded by NNNN (or Amended by NNNN when the new record changes only part of it).
4. Add it to the table above.