sjat/boma

sjat 9e0c264658 docs: reconcile lower-severity review findings (O9-O24)

- ADR-007: document ubongo on the legacy V4 net at 10.20.10.151 (transitional,
  outside the planned srv /24 until the LAN is re-cut) (O10); single authoritative
  boma.baobab.band -> boma.wingu.me transition note already added earlier
- terraform tfvars.example + variables.tf (both envs): pve01 -> pve0 and
  <host>.boma.baobab.band per ADR-007 naming (O11)
- ADR-012/013/015/016/017/018: convert "See also:" prose to `## Related` sections
  placed after Consequences, matching ADR-014/019-023 (O13)
- docs/README + inventories/README: list the missing subdirs / offsite_hosts +
  offsite.yml merge behaviour (O14, O29 note)
- ADR-009: drop the retired `nyumbani` example; use vaultwarden.wingu.me split-horizon (O19)
- ROADMAP M2: askari shipped as cx23/x86 (CAX11/ARM out of stock) (O20)
- ADR-020: 80/443/3478 opened in M4a (past tense); coordinator role is M4b (O21)
- netbird -> netbird_coordinator across ROADMAP M4b, the M4b plan, ADR-024 (O23)
- ADR-024: align the M1 DNS-01 wildcard scope wording with ROADMAP (O24)
- capacity-scan.py: read the inventory directory so offsite.yml (askari) is seen (O28)
- tf_to_inventory.py: generated header now warns it overwrites the manual control node (O9)
- tests/tags.yml: proxy concern comment Traefik -> Caddy (missed in the O3 sweep)

O9's existing stub hosts.yml header stays as-is (generator-owned, hook-protected);
the fix lives in the generator for the next regeneration. make lint + pytest (57) green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-14 19:31:40 +02:00

3.7 KiB

Raw Blame History

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 version of the same project, but a deliberate restart on different principles. V4 (a ~100+ role project) still exists on disk and is a genuine reservoir of hard-won, real-world knowledge. The standing risk is that referencing it lets V4's old structure and assumptions creep back in under the guise of "inspiration." This ADR sets the policy for drawing on V4 without inheriting it. (Resolves the questions previously parked in TODO 3.3 and 10.1.)

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.

Banned: justifying a choice by V4 precedent — "we do X because V4 did X."
Required: decide on boma's own terms; V4 may simply be where a need or a pitfall was first noticed.
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

Legitimate source of	Never a source of
Operational lessons / gotchas — evidence of a pitfall that informs a boma decision (not the decision itself)	Requirements & scope — boma decides what it runs, from scratch
Working config snippets — adapted and re-templated on boma's terms, never copied wholesale	Domain facts / values — ntfy topics, IPs, hostnames, etc. are decided fresh; no reuse
	Structure, role design, layout, naming, conventions
	Methodology, assumptions, and authority / justification

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

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 conversation, or a clearly-temporary migration-notes scratch doc if a structured 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

The AI is the main consumer of V4 — it is on disk and readable. When consulting it:

May read V4 when building something V4 also did — but only to mine gotchas and working config snippets, nothing else.
Must announce it is consulting V4 ("checking how V4 handled X").
Must re-derive the result on boma's terms and pass the acceptance test before it lands.
Must flag any V4 ↔ boma conflict (an approach that assumes something boma rejects) rather than absorbing it.
Must never import V4's requirements, scope, domain values, structure, or conventions, and never cite V4 as justification.

V4 is a searchable field-notes archive consulted under a leash — not a template to copy.

Consequences

V4's real value (what broke, what worked at the config level) stays accessible; its structure and assumptions do not follow.
Some things V4 already "solved" get re-decided from scratch (e.g. ntfy topics — ADR-011 defines boma's own rather than reusing V4's). That re-work is the intended cost of a clean methodological break.
The policy is enforceable in review and by the AI guardrails above.

ADR-001 (architecture / legibility), ADR-004 (service-role model), ADR-011 (update management — ntfy topics decided fresh per this policy).

3.7 KiB Raw Blame History