up

docs/adr/0000-template.md

@@ -3,16 +3,32 @@
 ## Status
 Proposed
 
+## Date
+YYYY-MM-DD
+
+## Authors
+- Name (team)
+
+## Deciders
+- Names of approvers / reviewers
+
 ## Context
 - What decision needs to be made?
 - What are the forces (requirements, constraints, stakeholders)?
+- Why now? What triggers the ADR?
 
 ## Decision
 - Summary of the chosen option.
+- Key rationale points.
 
 ## Consequences
 - Positive/negative consequences.
 - Follow-up actions or tasks.
+- Rollback plan or re-evaluation criteria.
+
+## Alternatives Considered
+- Option A — pros/cons.
+- Option B — pros/cons.
 
 ## References
 - Links to related ADRs, issues, documents.

docs/adr/index.md

@@ -0,0 +1,41 @@
+# 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)