# AGENTS.md — Codex Project Rules (SQLite‑First, July 2026)

This document supersedes all previous agent rule files. Treat it as the single source of truth.

---

## 0. Quick‑start for Codex

* Blocks live in `Codex Documentation/Current Software Plan/`.
* Work strictly in numerical order (Block 19 → 20 … 29).
* Each block contains numbered `XHIGH` / `HIGH` chunks.
* Stop at every `BREAKPOINT` in a chunk; wait for confirmation before continuing.
* Before coding, run `scripts/bootstrap_dev.sh` to set up the local dev DB.

---

## 1. Persistence

| Element | Rule |
|---------|------|
| Local storage | **SQLite via Drift**, schemaVersion 1 |
| Abstraction | Domain‑only repository interfaces (`scheduler_persistence`) |
| Swappable | New adapters must pass repository conformance tests |
| Backup | AES‑256‑GCM encrypted SQLite file (`Backup library`, Block 24) |
| Migrations | Drift migrations with tests (Block 20, Block 26) |

No MongoDB runtime in V1.

---

## 2. Repository & Adapter Rules

1. Interfaces expose domain objects only.
2. Optimistic `revision` on every mutable save.
3. Owner scope parameter now for future multi‑user.
4. Adapters implement compare‑and‑set; core never overwrites stale revision.

---

## 3. Notification Rules

* Use `NotificationAdapter` (Block 21).
* Desktop implementation (Block 22), fake adapter for tests.
* Core never imports platform APIs directly.

---

## 4. Backup / Export Rules

* Backup: encrypted SQLite (`.sqlite.aes`) via Backup library.
* Readable exports: JSON + CSV via `ExportController` (Block 23).

---

## 5. Testing Hierarchy

| Layer | Folder | Purpose |
|-------|--------|---------|
| Unit | `test/unit` | pure domain logic |
| Contract | `test/contract` | repository conformance |
| Migration | `test/migration` | Drift schema upgrades |
| Integration | `test/integration` | full stack InMemory + SQLite + fake notifications |

CI fails below **80 % line coverage**.

---

## 6. Dev Scripts (Block 27)

| Script | Description |
|--------|-------------|
| `bootstrap_dev.sh` | install deps, create dev DB |
| `dev.sh` | hot‑reload desktop run |
| `test.sh` | all tests + coverage |
| `package_release.sh` | build OS binaries |

Flutter UI work starts in Block 29 under `apps/focus_flow_flutter/`. Keep it
out of the root Dart workspace until the Flutter toolchain gate is fully
integrated.

---

## 7. Branch, Commit & CI

* Start each new block from `main` on a block branch named
  `block-XX-simple-name` (for example, `block-20-sqlite-adapter`).
* Keep all chunk work for that block on the block branch.
* Commit every completed chunk before moving to the next chunk or breakpoint.
* Use conventional commits (`feat`, `fix`, `docs`, `test`, `refactor`,
  `chore`, `ci`).
* Do not leave completed chunk work only in the working tree.
* When the block is complete and verified, merge the block branch back into
  `main`.
* CI matrix: ubuntu‑latest, windows‑latest, macos‑latest.
* `dart analyze` and `dart test` must pass.

---

## 8. MVP Boundaries

* Today + Backlog only.
* Task types: flexible, inflexible, critical, locked, surprise, free slot.
* No week/month views, sync, or shield in V1.

---

## 9. UX Language

* Use calm terms: missed, pushed, backlog, archived.
* Avoid blame language.

---

_Last updated: 2026-06-27_