Gabriel Radureau
3961914613
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>
47 lines
3.5 KiB
Markdown
47 lines
3.5 KiB
Markdown
[vibe](../README.md) > **ADR**
|
|
|
|
# Architecture Decision Records
|
|
|
|
> **Status**: 🟢 Active
|
|
> **Last Updated**: 2026-06-25
|
|
> **Related**: [vibe/PRD](../PRD/README.md) · [vibe/Investigations](../investigations/README.md)
|
|
> **Historical**: [doc/adr](../../doc/adr/README.md) (foundational infra) · [ansible/.../docs/adr](../../ansible/arcodange/factory/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`](_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/`](../../doc/adr/README.md) | Foundational infrastructure ADRs (DNS, k3s, CI/CD, Vault, telegram-gateway auth) | ❌ Historical |
|
|
| [`ansible/arcodange/factory/docs/adr/`](../../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](0001-safe-prod-like-environment.md) | Safe, production-like environment | 🟢 Accepted | 2026-06-23 |
|
|
| [0002](0002-per-application-environments.md) | Per-application environments | 🟢 Accepted | 2026-06-25 |
|
|
|
|
## Rules to contribute
|
|
|
|
1. Copy [`_template.md`](_template.md) to `NNNN-kebab-title.md` using the next free sequence number and delete the top HTML-comment note.
|
|
2. Fill in the blockquote (Status/Date/Deciders), then Context, Decision, Consequences, Alternatives considered, QA & validation, References.
|
|
3. Open the ADR with status `Proposed`. Flip it to `Accepted` once the decision is settled — and from that point treat the body as frozen.
|
|
4. Add a row to the Index table above (newest at the bottom to preserve chronological numbering).
|
|
5. 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.
|
|
6. 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.
|