docs: define repository pattern boundary

docs/DECISIONS.md

@@ -25,6 +25,7 @@ For project constraints, see [PROJECT.md](PROJECT.md).
 | ADR-001 | Example: Start with a modular monolith | Example | 2026-06-28 |
 | ADR-002 | Example: Keep project documentation in the repository | Example | 2026-06-28 |
 | ADR-003 | Example: Require explicit validation evidence before merge | Example | 2026-06-28 |
+| ADR-004 | Example: Use repository pattern for persistence boundaries | Example | 2026-06-28 |
 
 ## ADR-000: ADR Template
 
@@ -245,3 +246,62 @@ manual checks, or reasons validation could not be run.
 - PR templates should include validation.
 - Reviewers can block merges when risk is high and evidence is missing.
 - Failed or skipped validation must be explained.
+
+## ADR-004: Example: Use Repository Pattern For Persistence Boundaries
+
+### Title
+
+Use repository pattern for persistence boundaries.
+
+### Status
+
+Example
+
+### Date
+
+2026-06-28
+
+### Context
+
+The project needs domain and application logic to remain independent from the
+database engine, ORM, and storage implementation details.
+
+### Problem
+
+Without an explicit persistence boundary, database concerns can leak into
+business logic and make testing, refactoring, and future storage changes harder.
+
+### Alternatives
+
+| Alternative | Summary |
+| --- | --- |
+| Direct ORM access everywhere | Fast initially, but couples business logic to persistence details. |
+| Generic repository | Reduces ORM exposure, but often becomes a thin CRUD wrapper. |
+| Domain-specific repository pattern | Keeps persistence behind intention-revealing interfaces. |
+
+### Pros
+
+- Keeps application and domain logic focused on use cases and rules.
+- Makes persistence behavior easier to test and replace.
+- Creates a clear place for query intent and transaction expectations.
+- Reduces accidental coupling to ORM-specific APIs.
+
+### Cons
+
+- Adds interfaces and implementation classes.
+- Poorly designed repositories can hide important query or transaction costs.
+- Generic repositories can obscure domain behavior if used mechanically.
+
+### Decision
+
+Use domain-specific repositories as the default persistence boundary.
+
+### Consequences
+
+- Repository interfaces should live at the application or domain boundary.
+- Repository implementations should live in infrastructure or persistence
+  modules.
+- Generic CRUD repositories should be avoided unless the project records a clear
+  reason.
+- Transaction boundaries must be documented where writes span multiple
+  repositories.