Architecture Decision Records¶
ADRs record durable architectural decisions and their trade-offs. They describe the decision at the time it was accepted; later decisions supersede rather than silently rewrite earlier context.
| ADR | Decision | Status |
|---|---|---|
| 001 | READ-only production architecture | Accepted |
| 002 | Strongly typed public boundaries | Accepted |
| 003 | GET-only production transport chokepoint | Accepted |
| 004 | Explicit capability profiles | Accepted |
| 005 | Inert Tier 0 WRITE infrastructure | Accepted |
| 006 | Recovery Contract philosophy | Accepted, prerequisites incomplete |
| 007 | Security-first public schemas | Accepted |
| 008 | Fail-closed configuration validation | Accepted |
| 009 | Protected-artifact encryption provider | Accepted |
| 010 | Key lifecycle and delivery | Accepted |
| 011 | Whole-store anti-rollback anchor | Backend decided (2026-08-10, TPM-backed host witness) — design-ready, not yet provisioned |
| 012 | Confirmation authority | Accepted |
| 013 | Reconciliation authority | Accepted |
| 014 | Sealed executor interface | Accepted |
| 015 | Rate and blast-radius defaults | Accepted (mechanism); numeric defaults provisional |
| 016 | Alias-candidate disposable-lab authorization | Accepted |
| 017 | Official pfSense/Netgate documentation guidance layer | Accepted — as of 2026-08-22, one narrowly-scoped MCP guidance tool (pfsense_get_official_guidance) consumes it in production; live retrieval remains deferred |
| 018 | Version-aware Official Guidance resolution | Accepted — architecture and trust boundaries; as of 2026-08-22, resolve_appliance_identity() and version-aware resolution are implemented and wired via pfsense_get_official_guidance; live retrieval, Tier 1/WRITE/Phase 5 activation remain separately gated and not authorized |
| 019 | API Surface, Capability Discovery, and Extension Architecture | Accepted — vocabulary and evaluation only; individual mechanisms remain separately gated, public contract unchanged |
| 020 | Milestone 0 — first WRITE capability candidate authorization | Accepted — candidate naming only; implementation, live lab run, allow-list population, and WRITE activation all remain separately gated |
| 021 | Guided security-posture provisioning (pfsense-mcp-security setup) |
Accepted — architecture/design only; no wizard, posture, WRITE, or fail-closed enforcement authorized |
| 022 | Execution-authorization boundary (Plan → Authorize → Execute → Verify) | Accepted — architecture/design only; no authorization/execution code, no WRITE tool, no schema change authorized |
| 023 | Authorization-verification boundary (ADR-022 Phase D) |
Proposed (architecture) — owner decisions made and Phase D implemented under them; not a full ADR-021/ADR-022-style acceptance |
| 024 | Execution-authorization coordination boundary (ADR-022 Phase E/F/G territory) |
Proposed (architecture) — Slice E1 (freshness primitive) and Slice E2 (coordinator skeleton through one-time consumption) separately authorized and implemented; Slice E3 and full execution wiring still unauthorized, unimplemented |
| 025 | Authorization-to-RecoveryContract binding | Accepted (2026-08-12, owner) — PlanAuthorizationV2-to-provenance-bound-contract architecture; W1 implementation remains separately gated |
| 026 | First WRITE capability adapter semantic unit | Accepted (2026-08-12, owner) — description-only alias semantic unit and scope-specific evidence matrix; W1/W2/W3 remain separately gated |
| 027 | Closed LAB-T1 Stage 3 execution-port composition | Accepted — thin composition design and narrow reconciliation-observation interface; implementation and live authority remain separate |
| 028 | First-WRITE product surface and delivery architecture | Accepted (2026-08-15, owner) — records the delivery seam (W3-D1), capability/profile activation model (W3-D2), and signing-side CLI trust boundary; W3 implementation (Slices 1-5) remains separately gated slice by slice |
| 036 | Tier1 WRITE Safety Contract — architecture gap closure before any second capability | Proposed — no new WRITE capability authorized; names four gaps (risk_class enforcement, duplicate authorization-gate implementations, reconciliation cadence, semantic-postcondition spec) that must close first |
| 037 | WRITE Programme Architecture — capability families, existence-transition executor, risk scaling | Accepted (2026-09-04, owner) — architecture only, no new WRITE capability authorized; re-derives the full 451-operation mutation inventory, classifies every operation (verified three times: an owner acceptance re-review, a narrow amendment pass correcting its findings, then a clean acceptance review confirming 26 stated criteria), and identifies that 148 operations (32.8%, create/delete-shaped) require a not-yet-designed second sealed executor before implementation |
| 038 | Expired/terminal-PREPARED retry semantics — active-scoped idempotency uniqueness, expire_prepared(), composition-layer stale-artifact refusal |
Accepted (2026-09-05, owner). Implemented — idempotency_key uniqueness narrows from whole-table to blocking-RecoveryState scope only; a FAILED/ROLLED_BACK/EXPIRED historical contract no longer permanently blocks a fresh, independently-authorized retry, but never authorizes one on its own. expire_prepared() remains a local-only store primitive with no CLI/MCP/operator exposure. |
New ADRs should use the next sequence number and contain status, context, decision, consequences, alternatives, and references.
ADRs 009–016 resolve the remaining Tier 1 activation blockers identified in
reports-ai/reviews/CLAUDE_TIER1_ARCHITECTURE_REVIEW_v0.3.0.md. Each pairs with an
implementation-ready specification under
docs/tier1/specs/; see
docs/tier1/IMPLEMENTATION_ROADMAP.md
for the sequencing.
ADR-017 is not a Tier 1 subsystem — it is orthogonal, applying eventually
to both the active READ path and the still-inert future WRITE path. Its
companion spec is docs/OFFICIAL_GUIDANCE_LAYER.md,
alongside TIER1_ARCHITECTURE.md rather than under docs/tier1/specs/.
ADR-021 is likewise not a Tier 1 subsystem — its capability-posture
axis (read_only/write_protected) is not a Tier 1 concept at all,
and its anchor-assurance axis spans Tier 0/Tier 1 WRITE and the
Tier-1-adjacent anti-rollback anchor independently of it. Its
companion spec is
docs/SECURITY_POSTURE_PROVISIONING.md,
following the same top-level placement as ADR-017's.
ADR-022 sits above both ADR-021 (the planning layer) and Tier 1's
existing execution architecture (ADR-006/012/013/014/015) — it governs
how an operator's authority reaches that machinery, and covers two
mutation classes (configuration-file changes, physical TPM provisioning)
Tier 1's RecoveryContract was never designed to cover at all. Its
companion spec is
docs/EXECUTION_AUTHORIZATION_BOUNDARY.md,
same top-level placement.