dds

# `docs/`

Durable non-executable knowledge: business facts, user-goal contracts,
cross-cutting rules, and the principles governing how all of those are
written.

Structured around the [documentation directive](principles.md), which
constrains every artifact to one of three durable forms (conditional,
snapshot, co-maintained current-state). Read [`principles.md`](principles.md)
first, then [`conventions.md`](conventions.md).

## Layout

```
docs/
├── README.md            ← this file
├── principles.md        ← meta-rules every artifact follows
├── conventions.md       ← concrete formats per artifact type
├── registers.md         ← contract with external machine-authoritative registers
├── governance.md        ← the counsel worklist: regime, lawful bases, retention, instruments
├── domain/              ← what is true about the business
├── risks/               ← the spine: the risks the product must hold a strategy for
├── goals/               ← what the system commits to do for users
└── adr/                 ← cross-cutting rules and principles
```

## What this documents

Everything here documents one subject — **the product** — through three
lenses (see [`principles.md` §1, "What these artifacts are about"](principles.md#what-these-artifacts-are-about)):

- **What it is** — purpose and concepts. Start at [`domain/what-the-product-is.md`](domain/what-the-product-is.md).
- **How it is realized** — what the app holds, can do, mints, depends on. The *argument* about its shape is in [`domain/`](domain/); the *enumeration* (assets, dependencies, secrets, with their stakes/flows/terms) is the code and the external register where one exists (see [`registers.md`](registers.md)), not prose in this repo. What neither code nor register can produce — the regime, lawful bases, retention, processor instruments — is the worklist in [`governance.md`](governance.md).
- **How it is guaranteed** — [`risks/`](risks/) (the spine: what must be decided), [`adr/`](adr/) (rules + reasoning), and [`goals/`](goals/) (obligations + source).

The posture an auditor or engineer wants is *composed* from these atoms
by following links (or by the compliance interface), not authored as a
standing overview document.

## Reading order

1. [`principles.md`](principles.md) — directive, the three forms, what-we-document, authority model, vocabulary.
2. [`conventions.md`](conventions.md) — formats for ADRs, goals, domain docs, comments, commits, CODEOWNERS.
3. [`registers.md`](registers.md) — how external machine-authoritative registers join onto artifacts here (read when one applies).
4. [`domain/what-the-product-is.md`](domain/what-the-product-is.md) — the purpose root, then the rest of [`domain/`](domain/).
5. [`risks/`](risks/) — the spine: the risks a strategy must exist for.
6. [`goals/`](goals/) — externally sourced obligations.
7. [`adr/`](adr/) — cross-cutting rules.
8. [`governance.md`](governance.md) — the open governed facts and counsel questions.
9. The code, in light of the above.

## Authority (CODEOWNERS)

| Directory | Owners |
|---|---|
| `docs/domain/` | Product + relevant domain expertise (legal, clinical, financial — whichever applies) |
| `docs/risks/`, `docs/governance.md` | Product + relevant domain expertise (the spine and the governed facts are stake judgments) |
| `docs/goals/` | Product |
| `docs/adr/`, `principles.md`, `conventions.md` | Architecture |

See [`conventions.md` §6](conventions.md#6-codeowners) for the
CODEOWNERS template with placeholder team names.

## Not in `docs/`

Three categories live elsewhere; do not duplicate them here:

- **Implementation** — the application's source tree. Code is authoritative for what the system does.
- **Required behavior** — the test suite. Tests are the structural enforcement linking goals to behavior.
- **Per-change history** — git log and PR history. Original asks, rejected alternatives, and out-of-scope items at the moment of a change are commit-message trailers (see [`conventions.md` §5](conventions.md#5-commits-and-prs)), not standing documents.
- **Register data** — structured claims tracked by an external machine-authoritative system (inventory rows, tiers, owners, due dates, statuses). The register holds the value; an artifact here holds its *why*, joined by pointer (see [`registers.md`](registers.md)).