> ## Documentation Index
> Fetch the complete documentation index at: https://sponson.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/contributing/architecture) explains
*where* it is.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.