Skip to main content
The documentation is the single source of truth for Orbit’s current architecture, components, behavior, and boundaries. An architecture decision record (ADR) holds a decision only while the decision is being built. The pull request that completes the decision writes it into the owning documentation page and retires the record. The ADR guide describes the steps. Records lists the decisions in progress. Retired decisions lists every retired number and the page that now holds the decision.

​
Decision lifecycle

The docs-first subtask writes an ADR when a feature needs an architectural decision, alongside the documentation that describes the intended behavior. A new ADR says In progress. in its Status section and names the mission principle it serves. If the decision needs an exception to a principle, its Principle line names that principle and explains the exception and its reason. The ADR and documentation are the contract for implementation. The pull request that completes a decision writes its behavior into the owning page and its lasting reasons and rejected alternatives into that page’s “Why it works this way” section. It deletes the ADR, removes it from Records, redirects the exact ADR path to the absorbing section, adds a Retired decisions row, and updates inbound links. A decision completed in one pull request never leaves an ADR on main; a record stays only while a decision spans multiple pull requests. Numbers are never reused. The retired table and redirects resolve old numbers and links, including those in code comments. composer docs-lint enforces this lifecycle: retired slugs have no matching file and each has a redirect from its exact path. Live ADRs numbered 0180 or later must say In progress. in their Status section and include a Principle: line. A lower number follows those same two rules only when Retired decisions does not list it. The open gaps are 0007 and 0020. The committed allowlist for older live records can only shrink as those records retire. The docs-impact check and covers: frontmatter keep pages in step with code between decisions.

​
Why it works this way

Permanent ADRs made the current rule hard to find: amendments spread it across historical records, and built decisions still marked Proposed. misled readers. Domain pages now own the present behavior, while Git keeps the full history. Keeping superseded records would leave the same growing list and link chains; retiring them in periodic batches would leave documentation behind the code. Absorbing each decision in the completing pull request lets reviewers check the behavior, rationale, and redirect together. Keeping only the reasons that still matter in the owning page makes the documentation useful without requiring readers to reconstruct an ADR chain. An exact retired slug, rather than just its number, preserves the identity of older paths even when historical records share a number.

​
Records

​
Retired decisions

These decisions are built, superseded, or withdrawn, and the documentation holds what still applies. The link goes to the page that holds each one.