Compose a PRView SourceOpen Issue

Synced from Hive. This page is pulled from hivecommons/hive@v5 during the docs build. Edit the canonical source in the Hive repository.

Architecture Decision Records

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.

Process

  1. Copy the template below to NNNN-short-title.md using the next number.
  2. Write in present tense for new decisions. For historical decisions, mark the status as Accepted (retroactive) or Accepted (back-filled) and cite the existing docs or code.
  3. 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.
  4. Link ADRs from related documentation when they become operator-facing.

Template

# 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?

Records

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.