spec 1.0 · normative

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, 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, 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).
  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.
  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.