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

Interfaces expose domain objects only.
Optimistic revision on every mutable save.
Owner scope parameter now for future multi‑user.
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

3.8 KiB Raw Permalink Blame History Unescape Escape