Hive uses lightweight Architecture Decision Records (ADRs) to capture decisions that shape the system's security model, operating model, and long-lived APIs. ADRs are intentionally short: enough context to understand the choice, the chosen direction, and consequences for future changes.
Audience and reading route: maintainers use these records for rationale and implementation contracts, not installation steps. Operators should start with Securing your hive or Troubleshooting. Read a record's current-state note before its historical context or amendments. Accepted records document a decision, not proof that a control is enabled on your deployment; Proposed records are not setup instructions. Retroactive/back-filled records explain choices already present when recorded.
Suggested first records: autonomy levels for permission boundaries, network enforcement for the proxy, work ledger for agent coordination, and escalation for human decisions. The numbered list remains the complete chronological index.
- Copy the template below to
NNNN-short-title.mdusing the next number. - Write in present tense for new decisions. For historical decisions, mark the
status as
Accepted (retroactive)orAccepted (back-filled)and cite the existing docs or code. - Keep each ADR focused on one decision. If a later change supersedes it, add a
new ADR and update the older status to
Superseded by ADR-NNNN. - Link ADRs from related documentation when they become operator-facing.
# ADR-NNNN: Title
Status: Proposed | Accepted | Accepted (retroactive) | Accepted (back-filled) | Superseded by ADR-NNNN
## Context
What problem, constraint, or trade-off forced a durable architecture decision?
## Decision
What did we decide?
## Consequences
What becomes easier, harder, safer, or riskier because of this decision?All records below are Accepted (including retroactive/back-filled records) unless explicitly marked Proposed. ADR-0015/0016 preserve historical CSP sequencing; ADR-0019/0025 give their current action/mode contract first.
- ADR-0001: Record architecture decisions
- ADR-0002: MITM proxy network enforcement
- ADR-0003: ACMM autonomy levels
- ADR-0004: Beads work ledger
- ADR-0005: Forge-neutral source control interface
- ADR-0006: Planning intelligence with human review
- ADR-0007: Mint short-lived scoped agent credentials
- ADR-0008: Redact untrusted kick input with visible markers
- ADR-0009: Trajectory review lane
- ADR-0010: Escalation circuit breaker for CI fix loops
- ADR-0011: Knowledge system for durable agent context
- ADR-0012: Skill registry and BYO-agent contract
- ADR-0013: CEL triggers over normalized forge events
- ADR-0014: Hub/spoke fleet over heartbeat callbacks
- ADR-0015: Scope
style-srcas two directives and accept inline style attributes - ADR-0016: Scope
script-srcas two directives, close the element half with hashes - ADR-0017: Quadlet
.container/.podunits as the Podman persistent lifecycle - ADR-0018: Shared dashboard design tokens and component layer
- ADR-0019: Escalate to direction, spec, signal, or meta-issue instead of stalling
- ADR-0020: Spek continuous convergence
- ADR-0022: Opt-in redemption of earned Codex resets
- ADR-0023: Hive may merge PRs whose author could merge them
- ADR-0024: Provider credential lifecycle — Proposed, not a credential-pool or refresh-service setup guide.
- ADR-0025: One stage engine derives and writes every
stage/*label - ADR-0026: Sandbox runtime selection (Accepted — phase 1 implemented, runtime opt-in)