Architecture Decision Records
This directory contains Architecture Decision Records (ADRs) for agent-assembly. Each ADR documents a significant architectural choice — the context that drove the decision, the alternatives considered, and the consequences accepted.
The format follows a lightweight variant of Michael Nygard’s template. New ADRs are numbered sequentially and never rewritten; superseded decisions are recorded by adding a new ADR that links back.
An ADR records only durable product or system decisions — product and business semantics, user-visible behaviour, security and enforcement semantics, public API and data contracts, OSS-vs-SaaS boundaries, durable architecture and component boundaries, and long-term direction that constrains future implementations. Development-process instructions are not ADR material: CI, review, release and test-execution procedure, merge and branch policy, and contributor workflow conventions belong in CONTRIBUTING.md, .claude/, a runbook, a PR template, or a CI workflow. Being technical is not the test — the test is whether the primary subject is a decision or a procedure.
Numbers are permanent identifiers. A number, once used, is never reassigned — so the gaps below are deliberate and must stay empty: 0005 was used and later retired (created in 90679f35, reframed in 643700e5, its number withdrawn thereafter), and 0028 is retired (its CI trigger-scoping rule moved to CONTRIBUTING.md as development process). There are 32 active ADRs.
Index
| ADR | Title | Status |
|---|---|---|
| 0001 | Storage Architecture — SQLite (local) / PostgreSQL + TimescaleDB (production) | Accepted |
| 0002 | SDK Security Boundary, Shared-Crate Layout & Distribution | Accepted |
| 0003 | Cross-Repo Dependency Pinning on the Core Crates | Accepted |
| 0004 | Governance Enforcement Flow — SDK → aa-sdk-client → core (gRPC / UDS) | Accepted |
| 0006 | Limited-Function Self-Host — Kubernetes (Helm) / Terraform Support | Accepted |
| 0007 | Public Domain & URL Contract | Proposed |
| 0008 | SaaS Host Routing, Auth & Cookie Boundaries | Proposed |
| 0009 | Versioned Base-Image Tags & Reproducible SDK Pinning | Proposed |
| 0010 | Gateway Distribution for Self-Host & Examples | Proposed |
| 0011 | Cross-Process Op-Control Delivery via a NATS Subject (durable JetStream) | Accepted |
| 0012 | WebSocket & Browser Credential Handling (OSS vs SaaS) | Accepted |
| 0013 | Version Metadata Source-of-Truth & Drift Gate | Proposed |
| 0014 | Canonical Metadata Registry & Drift Gate | Proposed |
| 0015 | DLP Trust Boundary, Redaction Fail-Safety & Heuristic Detection Limits | Accepted |
| 0016 | Organization-wide Default Branch — master → main | Accepted |
| 0017 | Dashboard Design-Parity — Ratified Evolutions | Accepted |
| 0018 | Canonical Runtime Verdict & Enriched Decision Record | Accepted |
| 0019 | Agent Trust-Score Derivation | Accepted |
| 0020 | Rolling vs Calendar Monthly Budget Windows — and the Missing Team Tier | Accepted (rolling window still decision-gated) |
| 0021 | Topology Enforcement-Mode Mutation — Authorization, Blast Radius & Reversibility | Accepted |
| 0022 | Agent-Detail Config Projection & Quantified Posture Recommendations | Accepted |
| 0023 | Is aa-api Meant to Carry a Policy Cascade? | Accepted |
| 0024 | Semantics of an Empty or Unavailable Policy Cascade | Accepted |
| 0025 | design/v2/ Is the Authoritative Visual Specification | Proposed |
| 0026 | Seven Open Dashboard Product-Semantics Decisions | Proposed (Decision 2 Accepted) |
| 0027 | The Accessibility Floor Overrides the Visual Specification | Accepted |
| 0029 | Capability Over-Permission Derivation | Proposed |
| 0030 | Developer Integration Boundaries, Capability Model & Local Trust Model | Accepted |
| 0031 | OSS Native Account Authentication | Accepted |
| 0032 | Local-First Sensitive-Data Provider Architecture | Accepted |
| 0033 | Canonical Governance & Enforcement Architecture | Accepted |
| 0034 | One Product Truth & Cross-Repository Documentation Governance | Accepted |