# Decisions

Decision records are the context layer's dated account of *why*: architecture decisions, vendor selections, scope boundaries, intentional non-decisions. They stop re-litigation, and they give agents the reasoning rather than just the rule.

Decision records are the formal **record** subtype (see [content-categories.md](content-categories.md), Intent and records): inherently records, with a uniform schema and lifecycle generic records do not have. Their generated index entries carry `kind: record`; a decision record declares no `kind` key of its own (the schema is closed, so an explicit `kind` fails validation).

## Requirements

1. Decision records are markdown with YAML frontmatter valid against [`decision-record.schema.json`](../schemas/decision-record.schema.json), one record per file. The decision corpus is the union of two manifest-declared surfaces, and a context layer **MAY** use either or both: the declared records path (`machine.decisionRecordsPath`, default `<root>/decisions/`) and the entries the `decisions` category's index files resolve to. A record **MUST** be reachable through at least one of the two.
2. Frontmatter **MUST** carry: `id` (stable), `title`, `status`, and `date`. `status` is one of `proposed`, `accepted`, `superseded`, `deprecated`, `rejected`.
3. The body **MUST** state, in prose: the context (what situation forced a decision), the decision itself, and its consequences. The **RECOMMENDED** section headings are `## Context`, `## Decision`, `## Consequences`; a record **MAY** add `## Alternatives`.
4. Records are **append-only history**: a record **MUST NOT** be edited into a different decision. Two frontmatter fields are **mutable** as a decision ages, `status` (its lifecycle) and `supersededBy` (set when it is superseded); everything else, the `id`, the original `title` and `date`, the declared scope, and the prose body, is **immutable** once published. A reversal or change is a new record whose frontmatter sets `supersedes`, and the old record's `status` becomes `superseded` with `supersededBy` set. The supersession link **MUST** stay consistent in both directions: when record B sets `supersedes: A`, record A carries `status: superseded` and `supersededBy: B`, and a `superseded` record **MUST** name its successor in `supersededBy`. Both records remain. The reference tooling enforces the bidirectional supersession consistency today. It does not yet verify immutability itself (that a published record's frozen fields and body are unchanged against a base revision); that is a reported check on the roadmap, not yet a blocking gate. Until it ships, immutability rides the process-attested review discipline (see [conformance.md](conformance.md)).
5. A record **MAY** declare `affectedPaths` and `affectedCategories`, so tooling can route from a task's scope to the decisions that govern it. How a task's scope selects records (overlap-aware path containment, narrow category match, the `accepted` / `deprecated` bind, and the org-wide treatment of a record that declares neither) is the Task routing algorithm in [machine-readable-surface.md](machine-readable-surface.md).
6. Rejected proposals are records too (`status: rejected`). A decision not taken, written down, is the cheapest re-litigation insurance there is.

## ADR compatibility (non-normative)

Leji decision records are deliberately compatible with Architecture Decision Records: an existing ADR directory satisfies `decisions` by adding the frontmatter fields to each record (or to new records going forward) and mapping the directory in the manifest. No ADR tooling is required, and none is excluded.