# Architecture Decision Records (ADRs)

Architecture Decision Records document long-lived choices that shape StellaOps architecture, security posture, and operator experience. They complement RFCs by capturing the final call and the context that led to it.

## When to file an ADR
- Decisions that affect cross-module contracts, persistence models, or external interfaces.
- Security or compliance controls with on-going operational ownership.
- Rollout strategies that require coordination across guilds or sprints.
- Reversals or deprecations of previously accepted ADRs.

Small, module-local refactors that do not modify public behaviour can live in commit messages instead.

## Workflow at a glance
1. Copy `docs/adr/0000-template.md` to `docs/adr/NNNN-short-slug.md` with a zero-padded sequence (see **Numbering**).
2. Fill in context, decision, consequences, and alternatives. Include links to RFCs, issues, benchmarks, or experiments.
3. Request async review from the impacted guilds. Capture sign-offs in the **Deciders** field.
4. Merge the ADR with the code/config changes (or in a preparatory PR).
5. Announce the accepted ADR in the Docs Guild channel or sprint notes so downstream teams can consume it.

## Numbering and status
- Use zero-padded integers (e.g., `0001`, `0002`) in file names and the document header. Increment from the highest existing number.
- Valid statuses: `Proposed`, `Accepted`, `Rejected`, `Deprecated`, `Superseded`. Update the status when follow-up work lands.
- When an ADR supersedes another, link them in both documents’ **References** sections.

## Review expectations
- Highlight edge-case handling, trade-offs, and determinism requirements.
- Include operational checklists for any new runtime path (quota updates, schema migrations, credential rotation, etc.).
- Attach diagrams under `docs/adr/assets/` when visuals improve comprehension.
- Add TODO tasks for follow-up work in the relevant module’s `TASKS.md` and link them from the ADR.

## Verification checklist
- [ ] `Status`, `Date`, `Authors`, and `Deciders` populated.
- [ ] Links to code/config PRs or experiments recorded under **References**.
- [ ] Consequences call out migration or rollback steps.
- [ ] Announcement posted to Docs Guild updates (or sprint log).

## Related resources
- [Docs Guild Task Board](../TASKS.md)
- [High-Level Architecture Overview](../07_HIGH_LEVEL_ARCHITECTURE.md)
- [Coding Standards](../18_CODING_STANDARDS.md)
- [Release Engineering Playbook](../13_RELEASE_ENGINEERING_PLAYBOOK.md)