# AEGIS — Architecture Decision Record (ADR) Process - **Document ID:** ARCH-35 - **Phase:** E.1 — Governance Foundation - **Status:** Draft for review (post four-reviewer discipline) - **Version:** 0.1 - **Date:** 2026-07-10 - **Owner:** Chief Security Architect --- ## 1. Purpose Codify how AEGIS records important architectural decisions so architecture evolves intentionally, transparently, and reversibly. Implements mandate #46 (ADR Process). **Design intent.** An ADR is not a documentation artifact — it is the *decision act*. Recording an ADR is how a decision becomes real. Without an ADR, there is no decision; only informal opinion. ## 2. ADR Template (mandatory) ``` # ADR-: - Decision ID: ADR-<N> - Status: Proposed | Under Review | Approved | Superseded by ADR-<M> | Deprecated - Author: <DID> - Date: <ISO 8601> - Review Date: <ISO 8601> (next mandatory review, per §7 cadence) - Principles cited: [P-01..P-12] (from ARCH-33) - Depends on: [ADR-*, ARCH-*] ## Context [Why this decision is needed. What forces are in play. What constraints apply.] ## Risks Mitigated [Specific risks (threat-model refs, incident refs, debt refs) this decision reduces. Each risk cited by ID.] ## Alternatives Considered - Alternative A: [description; advantages; disadvantages; why not] - Alternative B: [...] - Alternative C: [...] - Do-nothing: [what happens if no decision made] ## Decision [The decision itself, unambiguously stated.] ## Consequences ### Positive [What this improves.] ### Negative / Costs [What this makes harder. New debt this creates (with Debt Register refs).] ### Follow-ups required [Concrete actions and owners.] ## Dependent Documents [Which ARCH-* docs, ADRs, standards, or runbooks depend on this decision. Cross-references maintained bidirectionally.] ## Verification [How we will know this decision worked. Test IDs, property tests, integration tests, canary drills, red-team scenarios.] ## Validating Metrics [Named metric IDs (from ARCH-24 catalog) that indicate the decision is healthy. Baseline + target + alarm thresholds.] ## Future Work [Known evolution paths: what replaces this decision, what extends it, target release, owner. If none foreseen, state so explicitly.] ## Threat-model diff [What changes in ARCH-03 as a result. New attack surface, new mitigations, residual risks.] ## Change Log - v0.1 <date> — Author — Initial proposal - v0.2 <date> — Reviewer — Revised on feedback - v1.0 <date> — Approver — Approved ``` Every field is mandatory. Omission blocks approval. ## 3. When to Write an ADR - Any design decision that affects a public interface, security posture, verification story, or operational surface. - Any decision that references or amends a Platform Design Principle (ARCH-33). - Any decision that modifies an approved ARCH-* document beyond typo-level fixes. - Any acceptance of debt (Debt Register entry additionally required per ARCH-29). - Any change to a governance role or process (per ARCH-34). *When NOT to write an ADR:* small code refactors, dependency version bumps within a compatible range, UI copy changes, obvious bug fixes. ## 4. Numbering and Location - ADRs live in `docs/adr/ADR-<NNNN>-<slug>.md`. - Numbering is monotonic and global across AEGIS; never reused. - Superseded ADRs remain in the repo; they are not deleted. ## 5. Lifecycle | Status | Meaning | Next transitions | |---|---|---| | **Proposed** | Author has submitted a draft | Under Review, Withdrawn | | **Under Review** | In Design Review Board queue | Approved, Rejected, Withdrawn | | **Approved** | Passed Review; binding | Superseded, Deprecated | | **Superseded by ADR-M** | Later ADR replaced this decision | (terminal; preserved for history) | | **Deprecated** | No longer applies; not necessarily replaced | (terminal) | | **Rejected** | Reviewers rejected the proposal | (terminal) | | **Withdrawn** | Author withdrew before decision | (terminal) | Transitions to Approved / Superseded / Deprecated require the approver defined in ARCH-34 §5. ## 6. Review Workflow 1. **Author drafts.** Uses the template. Cites principles. References dependencies. 2. **Automated checks** (CI on PR): - Template completeness. - Principle citations present and valid. - Dependency references resolve. - Threat-model diff section non-empty. 3. **Reviewer(s) assigned** per ARCH-34 §5 matrix. Reviewer applies the principles-as-lens check (ARCH-33 §3.2) and the four-reviewer discipline where the decision is architecturally consequential. 4. **Design Review Board** verdict per ARCH-36 gates. 5. **Approver** records signature (Layer-A audit event). 6. **Post-approval propagation:** related ARCH-* docs updated in the same or a follow-up PR (Docs-as-Code mandate #43); Debt Register updated if applicable; threat model updated. ## 7. Review Cadence (mandate #49) Every Approved ADR has a `Review Date` set by category: | Category | Default review interval | |---|---| | Kernel-critical | 1 year | | Cryptographic Identity, Audit, Evidence, Watchdogs | 1 year | | AI, Plugin | 1 year (faster if provider landscape shifts) | | Deployment, Recovery, Standards | 2 years | | Other | 2 years | | Principle-touching | Reviewed on principle amendment cycles | At Review Date, PA (or delegate) checks: - Is the decision still correct? - Have inputs changed (threat model, providers, regulation)? - Should the ADR be Superseded, Deprecated, or renewed? Result: an ADR either passes review (Review Date advanced) or transitions to Superseded/Deprecated. ## 8. Reversal, Supersession, and Amendment - Direct edits to Approved ADR content are forbidden (Docs-as-Code integrity). - A new ADR can Supersede an old one; the old one gets a note pointing forward and its status becomes Superseded. - Deprecation is used when the decision no longer applies but no replacement exists. - Amendments to procedural aspects (typo fixes, section clarifications not changing meaning) are permitted as versioned edits with change-log entries. ## 9. Interaction with ARCH-* Docs - ADRs record *decisions*; ARCH-* docs describe *architecture*. - When an ADR is Approved, the affected ARCH-* docs are updated to reflect it (or a new ARCH-* doc is added). - Every Design Decision in existing ARCH-* docs (Phase A–D) is effectively an ADR-in-source; going forward, new decisions are recorded as first-class ADRs and cross-referenced from the ARCH-* docs they affect. ## 10. Retroactive ADRs The existing ARCH-01..ARCH-32 corpus contains many Decisions (D-01-1..D-32-2). As part of the Architecture Freeze (ARCH-50), each significant Decision is retro-fitted into a numbered ADR to bring the corpus fully under the ADR process. Trivial or absorbed decisions may be batch-recorded. ## 11. Independent Architecture Review - **F-1.** *Template overhead may discourage recording.* Template is short; automated CI checks help; template evolves per feedback. - **F-2.** *ADR proliferation.* Guidance §3 restricts writing to architectural decisions; not every code choice. - **F-3.** *Retroactive ADRs* is a one-time effort.* Batched at Architecture Freeze; sustained by discipline afterward. ## 12. Adversarial Architect Review - **A-1.** *Attacker forges an "Approved" ADR.* Approvals produce Layer-A audit events; signature verifiable; drift monitor between repo state and audit chain. - **A-2.** *Insider slips a bad decision into an Approved ADR via post-approval "clarification."* Post-approval edits are versioned + change-logged; auditor visibility; significant edits require re-approval. - **A-3.** *Attacker exploits an old, forgotten ADR that permits weak behavior.* Review Date discipline catches; superseded ADRs cannot be resurrected without a new ADR. ## 13. Operational Reliability Review - **O-1.** ADRs discoverable via a searchable in-repo index. - **O-2.** Review Date reminders automated; expired reviews are metric-tracked. - **O-3.** Onboarding materials include reading key ADRs. - **O-4.** 15-year sustainability: ADR corpus grows manageably because most decisions are one-time. ## 14. Self-Critique - **S-1.** *"Retroactive ADRs" is real work.* Yes; scheduled at Architecture Freeze; PA leads. - **S-2.** *Some decisions blur the "architectural vs. implementation" line.* Rule of thumb: if a decision could bind future contributors' choices, it's architectural. - **S-3.** *ADR quality varies by author.* Reviewer role catches; templates + examples reduce variance. ## 15. First-Target Analysis and Redesign **Target:** silent post-approval editing of Approved ADRs. If an attacker or well-meaning insider edits an approved decision (e.g., "clarifying" it in a way that shifts its meaning), the audit chain of ADR history erodes. **Response:** 1. **Immutable Approved state.** File-integrity hash of the ADR at approval is recorded in Layer-A audit and re-verified on read (CI enforces). 2. **Version-controlled amendments.** Any modification produces a new version; change-log entry; "significant edit" (per checklist) requires re-approval. 3. **Drift monitor** compares repo-state ADR hashes against audit-chain-anchored hashes. 4. **External transparency** — significant ADRs published to transparency log. **Second target:** Review Date drift — ADRs never revisited. Response: metrics (ARCH-24) track review-currency; expired reviews are SEV-3 by default. ## 16. Decisions ### D-35-1. Mandatory template with automated completeness checks - **Reason.** Consistency + reviewability + mandate #46. ### D-35-2. ADR immutability at Approval, amendment via new version - **Reason.** §15 first-target response. ## 17. Change Log - **0.1 (2026-07-10)** — Initial draft.