forked from eva/focus-flow
148 lines
5.1 KiB
Markdown
148 lines
5.1 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 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_
|