docs(adr): restructure ADRs 001,002,004,005,012,014,015 to ADR-023 conformance

Add dated Status sections and (where missing) Consequences sections assembled
from each ADR's already-stated implications. No decision substance changed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
sjat 2026-06-10 14:37:52 +02:00
parent 9b1502cf7d
commit 188882449d
7 changed files with 129 additions and 2 deletions

View file

@ -1,5 +1,9 @@
# ADR-001 — Architecture overview
## Status
Accepted (2026-05-30)
## Context
This document describes the overall architecture of the homelab infrastructure
@ -65,3 +69,21 @@ This architecture prioritises:
- **Simplicity**: few moving parts, no orchestration layer (no Kubernetes, no Swarm)
- **Reproducibility**: any host can be rebuilt from scratch via Ansible
- **Legibility**: a human reading the repo can understand what runs where
## Consequences
Drawn from the boundaries this ADR already states:
- The small fleet (25 VMs) is treated as individuals, not cattle (per Infrastructure),
and forgoing an orchestration layer is the cost of the simplicity priority (per
Decision).
- The control node `ubongo` cannot be created by the Terraform it hosts, so it is
provisioned manually — the one documented exception to Terraform-owned VM existence
(per Infrastructure / Host groups; ADR-009, ADR-015).
- Management scope is deliberately bounded: Proxmox configuration itself (storage,
clustering, networking) is out of scope, and the `control` group never runs the
`docker_host` role (per Host groups).
- Compose files are always regenerated by Ansible on deploy; no hand-edited Compose
files exist on hosts (per Service interaction model).
- The "What this repo manages" table describes the *intended* design — STATUS.md
records what is actually built (per that section).

View file

@ -1,5 +1,9 @@
# ADR-002 — Security baseline and strategy
## Status
Accepted (2026-05-30)
## Context
Security here is not a single control but the sum of several combined efforts —
@ -183,3 +187,27 @@ This posture was chosen to be:
Out-of-scope items and conscious trade-offs are recorded in
`docs/security/accepted-risks.md` rather than here, so this decision record stays
stable while the risk posture evolves.
## Consequences
Drawn from the trade-offs, scoping, and follow-on work this ADR already states:
- Targeted/physical adversaries are out of scope at this scale, and supply chain is
consciously deprioritized — active vuln scanning is deferred as an accepted risk
(per Threat model; `docs/security/accepted-risks.md`).
- SELinux is not used (non-native to Debian, redundant with AppArmor), recorded as an
accepted risk (per Mandatory access control).
- Some CIS L2 items require separate partitions with restrictive mount options, which
reaches into VM disk layout — a provisioning concern (Terraform / cloud-init, ADR-006),
not just the `base` role (per Hardening standard). Any impractical CIS item is exempted
into the accepted-risk register with rationale, recording named exceptions rather than a
blanket opt-out.
- Several controls and governance mechanisms are stated as planned, not yet built:
Suricata network IDS, active alerting wiring AIDE/`auditd`/`fail2ban`/Suricata plus
log-source-silence into Grafana, the `/security-review` skill and its aggregation of
every `roles/*/SECURITY.md`, and the periodic security review (per File integrity /
Governance; STATUS.md / `docs/TODO.md`).
- The per-service security bar is enforced manually in review today, pending the planned
`/security-review` automation (per Governance).
- The accepted-risk register is kept out of this ADR so the record stays stable while the
risk posture evolves (per Decision; `docs/security/accepted-risks.md`).

View file

@ -1,5 +1,9 @@
# ADR-004 — Docker and Compose service model
## Status
Accepted (2026-05-30)
## Context
All services run as Docker containers managed via Docker Compose. This document
@ -107,3 +111,22 @@ Docker Compose was chosen over Kubernetes/Swarm because:
- Compose files are human-readable and easily auditable
- No distributed state to manage
- Straightforward to back up and restore
## Consequences
Drawn from the trade-offs and deferred items this ADR already states:
- A shared `compose_service` engine role is intentionally not built: the ~5 standard
tasks are duplicated per role in favour of legible, self-contained roles, with a stated
revisit trigger — extract a shared engine if maintaining the duplicated mechanics
becomes painful (a pattern change touching many roles, or drift this standard alone
isn't preventing) (per "Why not a shared engine").
- Forgoing Kubernetes/Swarm is the deliberate cost of matching complexity to a 25 host
fleet with no distributed state to manage (per Decision).
- User-namespace remapping is not enabled by default — evaluated per use case (per Docker
daemon configuration).
- Bare `latest` is acceptable only on the stateless tier; the stateful tier is always
pinned `tag@digest`, and image updates are a deliberate operation (per Image management;
ADR-011).
- Backup strategy is stated as defined separately, not in scope of this ADR (per Persistent
data).

View file

@ -1,5 +1,9 @@
# ADR-005 — Host bootstrapping
## Status
Accepted (2026-05-30)
## Context
This document defines the **cloud-init template** that managed VMs are cloned
@ -81,3 +85,19 @@ Cloud-init with Proxmox templates provides:
- No manual installer interaction
- A clean handoff point to Ansible
- Easy rebuilds — destroy VM, clone template, run Ansible
## Consequences
Drawn from the trade-offs and special cases this ADR already states:
- The cloud-init image was chosen over a manual Debian installer (slow, error-prone,
not reproducible) and over preseed/netboot (powerful but complex to maintain) (per
Approach).
- Template creation is a one-time manual procedure per Proxmox cluster, and the template
is never booted directly (per Template creation).
- There is no manual `qm clone` path for managed hosts; the full create → inventory →
configure pipeline and the Terraform↔Ansible contract live in ADR-009 (per VM
provisioning / Ansible handoff).
- The control node is the sole documented exception — `ubongo`, a physical machine
installed by hand because it cannot be created by the Terraform it hosts (chicken-and-egg);
its hardware target and recovery model live in ADR-015 (per Control node bootstrapping).

View file

@ -1,5 +1,9 @@
# ADR-012 — Hardware reference & capacity evaluation
## Status
Accepted (2026-06-01)
## Context
The repo modelled the logical/network layer (Terraform VM specs, ADR-007

View file

@ -1,5 +1,9 @@
# ADR-014 — Sourcing technical knowledge (docs and best practices)
## Status
Accepted (2026-06-04)
## Context
Most work in boma is done by AI agents drawing on training memory, which is stale
@ -100,5 +104,27 @@ above keeps the policy working.
- Commit to the principle, not a tool — degrade to `WebFetch`/`WebSearch` when plugins
are absent.
See also: ADR-013 (heritage / translate-don't-transplant), ADR-011 (version pinning),
ADR-008 (testing/verification).
## Consequences
Drawn from the follow-on work and limitations this ADR already states:
- Verified facts carry a durable, greppable stamp; a stamp binds a fact to a pinned
version, so a `requirements` change or image upgrade marks exactly what to re-check
(per Capture / Re-verification).
- Stale-stamp detection — a `/review-repo` or `/security-review` check flagging stamps
whose recorded version no longer matches what is pinned — is a noted enhancement, not
built yet (per Re-verification).
- Any version-specific claim given from memory must be marked "from memory, unverified"
as a transparency backstop, since agent self-assessed certainty is unreliable (per
When consulting is required).
- The policy commits to the principle rather than a specific plugin, so it degrades to
`WebFetch`/`WebSearch` on a bare install; reproducing the plugin toolchain from the
repo is done via `.claude/settings.json` and `docs/runbooks/claude-code-setup.md`,
with the graceful-degradation fallback covering a fresh clone until bootstrap runs
(per Source hierarchy / Reproducibility of the toolchain).
## Related
- ADR-013 — heritage / translate-don't-transplant.
- ADR-011 — version pinning.
- ADR-008 — testing / verification.

View file

@ -1,5 +1,9 @@
# ADR-015 — Control / development / AI-worker host (`ubongo`)
## Status
Accepted (2026-06-05)
## Context
Earlier ADRs framed the control node — the host that runs Terraform and Ansible —