Record durable decisions
Keep architecture rationale discoverable without turning changing implementation notes into duplicate truth.
Lumen records a durable decision only when its rejected alternative is likely to be reopened or when a release gate requires an explicit, reviewable exception. The goal is not an archive of every choice. The goal is enough context for a future contributor to avoid repeating a costly argument or silently weakening a proven boundary.
Sources and ownership
Use the narrowest owning source:
| Information | Owning source |
|---|---|
| Architecture, trust boundaries, invariants, dependency direction, and slice proof | BLUEPRINT.md |
| User-facing interaction and accessibility requirements | DESIGN.md |
| Durable repository execution rules | AGENTS.md |
| Current progress, measured evidence, deferred gates, and next action | EXECUTION_LEDGER.md |
| API, settings, states, events, IDs, limits, and CLI behavior | Generated reference from code |
| Dependency identity, license, integrity, and provenance | Lockfiles, source manifest, notices, SBOM, and release evidence |
Do not create a handwritten decision page that restates a generated contract. Do not put transient status, test output, or rollout progress into an architecture record. Link to the owning source and record only the rationale that would otherwise be lost.
When a separate record is justified
A decision record is warranted when changing a security or ownership boundary, choosing between credible long-lived alternatives, changing a committed performance threshold, accepting a dependency or license exception, or altering the compatibility and migration policy. A routine implementation choice, package patch update within an existing upgrade gate, or short-lived investigation belongs in the change and execution evidence instead.
The repository does not need a general record directory before the first justified record. When one is added, keep one index, stable identifiers, and direct links from the affected controlling section. Do not create parallel architecture indexes or a decision database.
Minimum record
State the decision and status, the user or operator outcome, constraints and evidence, credible options considered, why the chosen option is the smallest coherent fit, consequences and rejected overlapping surfaces, proof required before activation, rollback or replacement trigger, and links to the owning contracts. Include exact dependency versions or measured thresholds only when they are part of the decision itself.
Comparative investigation, copied source material, private notes, credentials, and provider-native secrets stay outside the public repository. Public rationale names only the selected dependency or boundary, its role, evidence, upgrade gate, and any rejected surface needed to prevent unsafe use.
Change and review
Before the durability promise, replace obsolete internal design atomically and update every controlling reference in the same change. After that promise, preserve data through expand, compatible deploy, resumable backfill, switch, and later contract. Neither epoch requires preserving obsolete product behavior.
Review a decision against the code path, current primary documentation, tests, and saved measurements. If evidence later contradicts it, update or supersede the record explicitly; do not leave two active answers or introduce a hidden fallback. The execution ledger records the transition and proof, while the controlling source retains the resulting durable rule.
For day-to-day changes, follow local development and the test strategy.