---
summary: A written, versioned account of a choice the team made and the reasoning behind it.
---
# Decision record
A **decision record** is a written, versioned account of a
choice the team made and the reasoning behind it. The kind of
choice — architectural, design, governance — is configured per
workspace; cartulary calls them all *decision records* and
treats them uniformly.
## Concepts it carries
A decision record carries:
- An [id](concept://id) — a TSID, lexicographically time-sortable.
- A **kind** — `adr`, `ddr`, or any other key declared under
`[decisions.<kind>]` in the workspace. The kind is read from
the directory context, not stored in the file.
- A **title** and an optional one-line **description** used by
the generated site for cross-reference previews.
- A [status](concept://status) — its current place in the
configured workflow (`proposed`, `accepted`, `rejected`,
`superseded`, …).
- [tags](concept://tag) — typed structured metadata.
- **Record links** — typed relationships to other decision
records (`supersedes`, `amends`). Cross-kind "see also"
pointers use the separate `relates:` field.
- An [event log](concept://event-log) — append-only history of
status transitions.
- **Aliases** — historical ids kept after the v3→v4 migration so
prior `ADR-NNNN` / `DDR-NNNN` references continue to resolve.
On disk, this is one directory per record named `<id>-<slug>`,
under the kind's directory (e.g. `docs/adr/<id>-<slug>/`),
containing an `index.md` whose YAML frontmatter holds the metadata
above and whose Markdown body holds the prose.
## Configuration
`cartu init` ships one decision-record kind, `adr`, under
`docs/adr/`. Additional kinds are declared by adding entries to
`cartulary.toml`:
- `[decisions]` with `types = ["adr", "ddr", …]` — the list of
configured kinds.
- `[decisions.<kind>]` — one block per kind, declaring at least
its `dir`. The workflow itself is hardcoded and the same for
every kind: `proposed` → `accepted` / `rejected`, then
`accepted` → `deprecated` / `superseded`.
- `[decisions.<kind>.tags.<key>]` *(optional)* — one block per
tag descriptor. None ship by default.
## Validation
`cartu check` enforces:
- The YAML frontmatter parses without errors.
- The `id:` field matches the directory's TSID prefix.
- The `description:` field, when present, fits on a single line.
- Every other rule lives in the concepts the record carries —
see the Validation sections of [status](concept://status),
[tag](concept://tag), and [event-log](concept://event-log).
## Commands
Grouped by intent — `cartu <kind> --help` is the catalogue of
every flag (e.g. `cartu adr --help`, `cartu ddr --help`).
- **Create**: `cartu <kind> new "Title"` (link an antecedent with
`--supersedes` or `--amends`).
- **Inspect**: `cartu <kind> list`, `cartu <kind> show <id>`,
`cartu <kind> link list <id>`.
- **Advance**: `cartu <kind> status update <id> <new>` walks the
workflow; `cartu <kind> tag add|remove <id> <key>:<value>`
mutates tags.
- **Relate**: `cartu <kind> link add <from> --relationship <r>
--target <to>`. The link is recorded inertly on a `proposed`
source; the back-pointer cascade fires when the source
transitions to `accepted`.
- **Validate**: `cartu check` (workspace-wide consistency).