dds

# Architecture Decision Records

Cross-cutting conditional rules and principles. Format and authority
specified in
[`docs/conventions.md` §1](../conventions.md#1-adrs-docsadr); meta-rules
in [`docs/principles.md`](../principles.md).

ADRs in this directory take the form:

- **Rule** — a conditional ("when X, do Y").
- **Premises** — co-maintained current-state assertions motivating the rule.
- **Reasoning** — chain from premises to rule.
- **Application** — concrete code or UI examples.
- **When this does not apply** — conditional exceptions.
- **Entailments** — what follows from the rule, framed as conditionals.

See [`docs/conventions.md` §1](../conventions.md#1-adrs-docsadr).

## Naming

Content-named, kebab-case. No leading numbers; no dates in the
filename. The acceptance date lives in the file's `Status:` line.

```md
See: docs/adr/authorize-via-policies.md
```

## Authority

Architecture team via `.github/CODEOWNERS`.

## Status

`Proposed` → `Accepted (YYYY-MM-DD)`. The date reflects the most recent
material change; git carries finer history.

## Versioning

Identical to other standing artifacts (see
[`docs/conventions.md` §7](../conventions.md#7-snapshots-and-versioning)):

- **Refinement** preserving identity — edit at the same path; the
  prior form moves into the Reasoning section of the new text, with
  the premise that drove the change named explicitly. *"Always do X"*
  → *"do X except when Y"* is the canonical case.
- **Identity change** — rename (content-naming rule); `git log --follow`
  traces history; inbound references updated as part of the change.
- **Full retraction** — file is deleted; deletion commit carries the
  rationale. Rare in practice.

## Adding an ADR

1. Identify the cross-cutting conditional.
2. Confirm it is not better expressed as a goal (system-mediated user
   contract) or a domain entry (a business fact). ADRs are for rules
   spanning many code sites.
3. Create `docs/adr/<rule-as-kebab-case>.md` using the format in
   [`docs/conventions.md` §1](../conventions.md#1-adrs-docsadr).
4. Set status to `Proposed`; promote to `Accepted (YYYY-MM-DD)` on merge.

## Index

| File | Topic |
|---|---|
| _(empty — add ADRs here as they land)_ | |