docs(adr): restructure ADRs 010,011,013 to ADR-023 conformance

010/011: relabel Decisions->Decision + add Status/Consequences.
013: add Status + Decision umbrella (existing Consequences untouched).
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:43:41 +02:00
parent 44dbd4628f
commit b3ca510380
3 changed files with 54 additions and 6 deletions

View file

@ -1,5 +1,9 @@
# ADR-010 — Forgejo integration and CI
## Status
Accepted (2026-05-30)
## Context
boma's git host, container registry, and (planned) CI all run on a self-hosted
@ -20,7 +24,7 @@ held to the same standard as the rest of the repo's secrets.
---
## Decisions
## Decision
### 1. API tokens are managed secrets, least-privilege
@ -75,3 +79,21 @@ later if CI load warrants a separate host. Actions is not yet enabled — see ST
| Terraform Forgejo HTTP state backend | Forgejo's `/raw/` API is read-only; state can't be written there. Local state instead (ADR-006). |
| Admin-scoped automation tokens | Unnecessary privilege; scope to `read:repository` + `read`/`write:package`. |
| Ad-hoc UI/API configuration as the norm | Becomes undocumented drift; codify or document instead. |
---
## Consequences
- The planned CI pipeline (see "CI pipeline (planned)") is trunk-based per ADR-003 /
ADR-008 — `push to main → lint + Molecule → deploy staging → [manual gate] → deploy
production` — running `act_runner` on `ubongo` (or a dedicated runner VM later if CI
load warrants); Actions is not yet enabled, so this remains future work tracked in
STATUS.md.
- Terraform state is not held in Forgejo: its `/raw/` API is read-only and cannot be
written, so local state is used instead (ADR-006) (see "What was ruled out").
- Automation tokens are scoped to `read:repository` + `read`/`write:package` rather
than admin, accepting the limits that least-privilege imposes on what automation can
do (see "What was ruled out").
- Instance/repo configuration must be codified or documented rather than changed
ad-hoc, to avoid the undocumented drift `/review-repo` exists to catch (see "What was
ruled out").

View file

@ -1,5 +1,9 @@
# ADR-011 — Update and upgrade management
## Status
Accepted (2026-06-04)
**Status: Proposed — draft for discussion (not yet accepted).**
## Context
@ -10,7 +14,7 @@ drift over time and must be kept current without breaking the homelab: the **hos
---
## Decisions
## Decision
### 1. Every service is classified stateful or stateless
@ -132,3 +136,19 @@ alert-driven.
| 8-weekly as the only stateful path | Too slow for urgent CVEs — hence the DIUN security fast-path. |
---
## Consequences
- A single uniform update policy is rejected: the stateful/stateless split is
load-bearing, so stateless services roll on rolling tags while stateful services are
pinned `tag@digest`, human-gated, and backup-first (see "What was ruled out").
- The weekly run never touches stateful services and the whole fleet is never updated
at once, accepting the added orchestration of host ordering and an 8-weekly +
fast-path cadence in exchange for bounded blast radius (see "What was ruled out").
- No update automation ships until the health-check verification gate is in order; the
pipeline is deliberately sequenced behind that harness (see Decision 6).
- Several points remain open for discussion (see "Open questions"): where the Proxmox
snapshot is driven from across the TF/Ansible boundary; the exact cadences; where the
health-check harness lives and the minimum bar that counts as "in order"; whether
classification is a per-role `__stateful` flag or a group_vars list; whether the
weekly run hits staging first; and the notification + "skip/pause" control channel.

View file

@ -1,5 +1,9 @@
# ADR-013 — Heritage: learning from AnsibleBaobabV4 without inheriting it
## Status
Accepted (2026-06-04)
## Context
boma is the methodology successor to AnsibleBaobabV4 (and V3 before it) — not a new
@ -10,7 +14,9 @@ structure and assumptions creep back in under the guise of "inspiration." This A
sets the policy for drawing on V4 without inheriting it. (Resolves the questions
previously parked in TODO 3.3 and 10.1.)
## Principle — translate, don't transplant
## Decision
### Principle — translate, don't transplant
V4 is **evidence, never authority.** It can show what was needed or what went wrong;
it can never be the reason boma does something a certain way.
@ -21,7 +27,7 @@ it can never be the reason boma does something a certain way.
- **Acceptance test** for anything V4-derived: *can it be justified purely from
boma's principles, with zero reference to V4?* If not, it does not land.
## What V4 is — and is not — a source of
### What V4 is — and is not — a source of
| Legitimate source of | Never a source of |
|---|---|
@ -33,7 +39,7 @@ it can never be the reason boma does something a certain way.
Only concrete, verifiable, low-level knowledge crosses over — precisely because it is
safe to re-derive, whereas structure and requirements drag assumptions along.
## Provenance — transient only
### Provenance — transient only
When a boma decision was prompted by a V4 lesson, or a config adapted from V4, the
lineage is recorded only in **transient** places: the commit message, the working
@ -42,7 +48,7 @@ extraction warrants one. **Durable artifacts (ADRs, role READMEs, `SECURITY.md`)
stand on boma's own terms with no V4 reference.** Honest about lineage in history;
clean in the living repo.
## AI consultation guardrails
### AI consultation guardrails
The AI is the main consumer of V4 — it is on disk and readable. When consulting it: