<!-- SPDX-FileCopyrightText: 2026 FocusFlow contributors -->
<!-- SPDX-License-Identifier: AGPL-3.0-only -->

# 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 unless the active plan explicitly says otherwise.
* Treat each block or named plan as the primary work unit.
* New or updated plan documents must use blocks of work, implementation steps, tasks, or acceptance checks.
* Stop at any explicit `BREAKPOINT` in the active block or plan; 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) |

SQLite is the selected V1 implementation database. Keep Drift and database details inside the SQLite persistence adapter; core/domain code must not import database libraries or depend on row shapes.

---

## 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.

---

## 6.1 Code Documentation & File Hygiene

All future project files must include the relevant SPDX metadata for their file
format.

All new and modified code must be commented or documented in detail while the
work is being done. Update existing comments and docs whenever functionality,
contracts, invariants, side effects, persistence mappings, scheduling rules, or
error behavior change. Stale comments are treated as incorrect code.

New Dart files must include file-level Dartdoc library docs and Dartdoc comments
for every class, enum, enum value, constructor, method, field, and top-level
declaration. Existing Dart declarations touched by a change must have their
Dartdoc added or updated as part of that same change.

Keep files small and focused. If a file grows to cover multiple responsibilities,
split it into smaller files with clear names rather than expanding a broad
catch-all file. Use increasingly specific folder scopes, ordered from broad
package/feature ownership down to concrete responsibility. Prefer descriptive
folder names that explain the domain area or adapter boundary.

Aim for fewer than 10 files per folder. This is a guideline, not a hard rule:
do not create artificial one-file folders merely to satisfy the count, and do
split crowded folders when the files naturally form smaller responsibility
groups.

---

## 7. Branch, Commit & CI

* Start each new block or plan from `main` on a dedicated branch named for the
  work, such as `block-20-sqlite-adapter` or `plan-backlog-tab`.
* Keep all work for the active block or plan on its dedicated branch.
* Commit completed work after it is implemented, documented, and locally
  validated.
* Do not leave completed work only in the working tree.
* Use conventional commits (`feat`, `fix`, `docs`, `test`, `refactor`,
  `chore`, `ci`).
* When a full plan is complete and no work remains for that plan, rerun the
  required validation. If tests still pass, merge the plan 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-07-07_
