Files

Gabriel Radureau 3961914613 docs(adr): ADR-0002 — per-application environments via an env coordinate

Records the decision to extend the <app> join key with a second
coordinate <env>, governed by an elision rule (env=prod elides → every
existing app's derived names are byte-identical and its tofu plan is a
no-op; non-prod envs take the <app>-<env> suffix, with the Postgres
owner role staying snake-case <app>_<env>_role).

Motivated by the ERP's incoming write-capable AI-agent skill: it needs
an in-cluster sandbox instance (erp-sandbox) with a prod-like Dolibarr
API + isolated database to rehearse writes before a human promotes them
to prod. The ADR reconciles this against ADR-0001 honestly — ADR-0001
rejected an in-cluster sandbox for INFRA-change rehearsal (shared
fleet-wide control planes); ADR-0002 operates one layer up where the
agent's only reach is the app's HTTP API against an isolated DB, so the
fleet blast radius is not in scope. The two are complementary; ADR-0002
does not supersede ADR-0001.

Also:
- vibe/ADR/README.md: index row for 0002 + Last Updated 2026-06-25
- PRD safe-prod-like-environment README: bidirectional back-link to
  ADR-0002 on the Adjacent line + Last Updated 2026-06-25

Authored via the ADR Scribe persona, validated via the Continuity Warden
checklist (no-tombstone, breadcrumb, MADR-lite sections, dead-link scan,
bidirectional links).

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

2026-06-25 14:55:19 +02:00

3.5 KiB

Raw Blame History

vibe > ADR

Architecture Decision Records

Status: 🟢 Active Last Updated: 2026-06-25 Related: vibe/PRD · vibe/Investigations Historical: doc/adr (foundational infra) · ansible/.../docs/adr (dated infra ADRs)

vibe/ADR/ is the canonical home for Architecture Decision Records going forward. The format is MADR-lite: one short, self-contained Markdown file per decision, focused on the why rather than the how. Use the _template.md skeleton to start a new one.

Where ADRs live

There are three ADR locations in this repo. Only the first accepts new records; the other two are read-only history kept for context.

Location	Role	Accepts new ADRs?
`vibe/ADR/` (this folder)	Canonical, MADR-lite, going forward	✅ Yes
`doc/adr/`	Foundational infrastructure ADRs (DNS, k3s, CI/CD, Vault, telegram-gateway auth)	❌ Historical
`ansible/arcodange/factory/docs/adr/`	Dated infra ADRs (network, CI/CD, Longhorn PVC recovery, internal DNS)	❌ Historical

When a new decision supersedes one of the historical records, write the new ADR here, set the old one's status note to Superseded by ADR-NNNN, and cross-link both ways.

Rules

One file per decision, named NNNN-kebab-title.md (zero-padded sequence, e.g. 0001-safe-prod-like-environment.md).
The body is immutable once Accepted. A decision is a historical fact: do not rewrite the Context/Decision/Consequences after acceptance. The only mutation allowed on an accepted ADR is its status (e.g. flipping Accepted → Superseded).
Statuses: Proposed (under discussion) → Accepted (decided, body frozen) → Superseded (replaced; points to the successor ADR). A Proposed ADR may still be edited freely.
No-tombstone rule. Each file reads as currently true. Never leave "previously X, now Y", changelog lines, or "updated to ..." notes inside an ADR — git history is the audit trail. A superseded ADR keeps its original frozen body; the supersession is recorded only in its status line and the successor's References.
PR cross-link both ways. The ADR References section links the PR that introduced it; the PR description links back to the ADR. Keep links bidirectional.

Index

#	Title	Status	Date
0001	Safe, production-like environment	🟢 Accepted	2026-06-23
0002	Per-application environments	🟢 Accepted	2026-06-25

Rules to contribute

Copy _template.md to NNNN-kebab-title.md using the next free sequence number and delete the top HTML-comment note.
Fill in the blockquote (Status/Date/Deciders), then Context, Decision, Consequences, Alternatives considered, QA & validation, References.
Open the ADR with status Proposed. Flip it to Accepted once the decision is settled — and from that point treat the body as frozen.
Add a row to the Index table above (newest at the bottom to preserve chronological numbering).
In the PR that lands the ADR, link to the ADR file; in the ADR's References, link back to the PR. Bidirectional links are mandatory.
If this ADR supersedes a historical one in doc/adr/ or the Ansible ADR folder, update the old record's status note and cross-reference both directions.

3.5 KiB Raw Blame History