# Architecture Decision Records (ADRs)

This folder is the home for **individual architectural decisions** — one file per
decision. ADRs record *why* a specific choice was made so it isn't re-litigated.

## Relationship to the governance docs
- **`PRINCIPLES.md`** (substrate root) — standing how/why Sam operates.
- **`ARCHITECTURE.md`** (substrate root) — what the system actually is (built vs planned).
- **ADRs (here)** — the decision trail for individual choices that shaped the above.

Update PRINCIPLES.md / ARCHITECTURE.md **at the moment of decision**, and add an ADR
for the decision itself.

## Convention
- One file per decision: `docs/adr/<NNNN>-<kebab-title>.md` (e.g.
  `docs/adr/0001-per-customer-firestore-isolation.md`). Number monotonically from 0001.
- Keep it short. Suggested structure:
  - **Title + date + status** (Proposed / Accepted / Superseded-by-NNNN).
  - **Context** — what forced the decision.
  - **Decision** — what was chosen, plainly.
  - **Consequences** — trade-offs, what it rules out, follow-ups.
- Supersede, don't delete: mark an old ADR `Superseded by NNNN` rather than removing
  it (preserve the trail).

## Status
Home established 2026-06-02.

- **[0001](0001-per-user-data-isolation.md)** — Per-user data isolation (Firebase Auth invite-only
  + per-owner Firestore docs + admin override). *Accepted 2026-06-02.* Closes the audit's core
  finding (single shared blob + client-side-only scoping). Gated on a passing isolation test.