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 # ADR-010 — Forgejo integration and CI
## Status
Accepted (2026-05-30)
## Context ## Context
boma's git host, container registry, and (planned) CI all run on a self-hosted 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 ### 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). | | 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`. | | 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. | | 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 # ADR-011 — Update and upgrade management
## Status
Accepted (2026-06-04)
**Status: Proposed — draft for discussion (not yet accepted).** **Status: Proposed — draft for discussion (not yet accepted).**
## Context ## 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 ### 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. | | 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 # ADR-013 — Heritage: learning from AnsibleBaobabV4 without inheriting it
## Status
Accepted (2026-06-04)
## Context ## Context
boma is the methodology successor to AnsibleBaobabV4 (and V3 before it) — not a new 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 sets the policy for drawing on V4 without inheriting it. (Resolves the questions
previously parked in TODO 3.3 and 10.1.) 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; 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. 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 - **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. 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 | | 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 Only concrete, verifiable, low-level knowledge crosses over — precisely because it is
safe to re-derive, whereas structure and requirements drag assumptions along. 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 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 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; stand on boma's own terms with no V4 reference.** Honest about lineage in history;
clean in the living repo. 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: The AI is the main consumer of V4 — it is on disk and readable. When consulting it: