forked from eva/focus-flow
128 lines
3.8 KiB
Markdown
128 lines
3.8 KiB
Markdown
<!-- 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 (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.
|
||
|
||
---
|
||
|
||
## 6.1 File Hygiene
|
||
|
||
All future project files must include the relevant SPDX metadata for their file
|
||
format. 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. When adding code, keep large feature surfaces organized
|
||
under descriptive subfolders instead of expanding flat top-level `src` or app
|
||
directories.
|
||
|
||
---
|
||
|
||
## 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_
|