Skip to main content
Every significant engineering decision in Nika Diamond lives as an ADR, a short markdown file in docs/adr/ with status, date, context, decision, consequences. At v: records: accepted, proposed, superseded and rejected. In the 0.124 line, work stays focused on maintenance, security and the media capabilities workflows need, and the proposed records stay as the record of open designs, not as a plan.
Canonical source: docs/adr/index.json (machine-readable) + docs/adr/README.md (human index). One file per ADR. An accepted ADR changes only by an amendment (a later ADR names it in its frontmatter amends: list) or by a superseding ADR.

At a glance

Total

decision records

Accepted

locked

Proposed

in review

Foundation ADRs by theme (001–035)

The first 35 records set the engine’s foundations. The full list follows in Every record.
How Nika runs itself as a project: version cadence, admission, ADRs-on-ADRs.
The six-layer crate discipline + physical workspace layout.
How Nika stays additive across decades without breaking changes.
How NikaError is shaped + how failures surface to users.
Cancellation, streaming, sync primitives, retry / timeout ownership.
How the engine verifies itself beyond unit tests.
The data-driven provider catalog and the workflow envelope convention.
The v0.100 plugin boundary, pre-planted at v0.80.
Cross-cutting idiom adoption.
Late-added Accepted ADRs covering foundational types + kernel expansion.
Seed-level type reservations made ahead of the crates that would use them.

Every record

How ADRs work

1

Propose

Any significant engineering decision starts as a Proposed ADR: a short markdown file in docs/adr/adr-NNN-<slug>.md with frontmatter: id, title, status: Proposed, date, tags, related. Writer describes the context, options considered, and recommended decision.
2

Review

Proposed ADRs are discussed in PRs. Others get related: / supersedes: / requires: links. Status can flip to Accepted or Rejected. The ADR index (docs/adr/index.json) is auto-regenerated.
3

Accept

Once accepted, an ADR changes only in two recorded ways: a later ADR amends it (listed in that ADR’s amends:, with a banner in the amended file), or a new ADR supersedes it. git log tells you when and why a given rule came in.
4

Supersede

Rare, but when a decision proves wrong, a new Accepted ADR supersedes it. The superseded ADR stays in the tree with status: superseded and superseded_by:. Three supersessions exist: ADR-021 (the K8s-style apiVersion envelope) by ADR-082 (a single version marker), ADR-082 by ADR-113 (2026-08-13: the envelope’s identity moves onto nika: itself, the version slot dies), and ADR-116 (the first local-only nika serve) by ADR-117. One ADR is rejected outright (ADR-089) and kept in the tree as the record of a road not taken.

Metadata fields

Every ADR carries rich metadata in both its frontmatter and index.json:

Gate 12 integration

Admission Gate 12 fails when a crate’s commit changes a public API surface without either (a) being purely additive under #[non_exhaustive] rules, or (b) referencing an Accepted ADR that authorizes the break. The ADR trail is how breaking changes earn the right to exist.

See also

Forward-compat invariants

The patterns that keep most ADRs additive.

L0 decisions

The foundation decisions behind ADRs 033, 034 and others.

12-gate admission

Gate 12 requires ADR alignment for breaking change.

ADR directory on GitHub

Browse the full ADR tree, index.json, and README.