# Decision records

Prose in this tree is only for **why** — why we chose a shape, what we rejected, what constraint
bound us. It never describes current implementation and never claims to be current. Code (and
generated refs) are the only truth about *what is*.

## One file per decision

`docs/decisions/YYYY-MM-DD-<slug>.md`

- **Date** in the filename is the day the decision was recorded (UTC calendar date).
- **Slug** is a short kebab-case label for the subject (`single-aws-account`, `cowork-plugin-boundary`).

## Frontmatter

```yaml
---
date: YYYY-MM-DD
sha: <git commit sha at which this was true>
status: decided | superseded
subjects:
  - <topic or path this decision binds>
---
```

| Field | Meaning |
| --- | --- |
| `date` | Same calendar day as the filename prefix. |
| `sha` | The commit that embodies or records the decision — a pin in history, not a claim that the tree still looks like that. |
| `status` | `decided` (in force) or `superseded` (replaced by a later record; leave the old file in place). |
| `subjects` | Short list of topics, paths, or surfaces the decision constrains. |

## Body

1. `# <Title>` — the decision in one line (what was chosen, not how it works today).
2. `## Why` — the rationale and the binding constraints.
3. `## Rejected alternatives` — each alternative as a bullet: what it was, why it lost.

Do not narrate live topology, versions, box coordinates, or "how to run it." If a reader needs
current state, they read the code or a generated ref — not this file.

## Ownership

Bootstrap seeds this README once (`ownership: repo`) and never clobbers it. Individual decision
files are authored in the same PR as the change and merged by a human. There is no scheduled docs-janitor backstop (Hub#4119/#4164).