boma/docs/decisions/013-heritage-v4.md

# 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.

## Related

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