focus-flow/Codex Documentation/Current Software Plan/V1_BACKEND_COMPLETION_GAP_MATRIX.md

V1 Backend Completion Gap Matrix

Status: Planning baseline

Purpose: Record what Blocks 01–10 actually completed, identify the remaining V1 backend gaps found in the current repository, and map each gap to a new active plan block. This file is not a replacement for tests or the block plans.

Review basis

The review used:

• AGENTS.md
• the root README.md
• all archived V1 Block 01–10 plans, including their updated variants
• V1_TEST_COVERAGE_MATRIX.md
• all files under Human Documentation/, including the DOCX design specification
• all production files under lib/
• all tests under test/
• the current repository history and working-tree state

Chunk 11.1 re-established the executable baseline on 2026-06-24 from starting commit 775c2ed406f03a73a9b0ca621dea5b4482468616. dart pub get, dart format lib test, dart analyze, dart test, and git diff --check passed. The current suite has 143 passing tests.

Current state and remaining work

Area	Completed in Blocks 01–10	Remaining V1 backend work	Planned block
Pure Dart foundation	Package layout, exports, lints, tests, documentation structure	Fresh verification, traceability matrix, and current API baseline	11
Core task model	Task types, lifecycle statuses, basic metadata, immutable copy pattern	Strong invariants, explicit nullable clearing, completion metadata, task reminder override, backlog-entered time, typed validation	11, 13
Status semantics	Planned/active/completed/missed/cancelled/no-longer-relevant/backlog	Reconcile the human specification’s pushed and skipped labels with event/stat semantics without importing V2 burnout behavior	11, 13
Time model	DateTime-based schedule intervals and recurring wall-clock helpers	Civil-date/wall-time/time-zone semantics, DST policy, deterministic clocks, and safe date-only persistence	11
Scheduling engine	Flexible insertion, next-slot push, tomorrow push, backlog push, rollover, overlap analysis	One centralized occupancy policy; free-slot protection; surprise/actual occupancy across every operation; structured non-localized result codes	12
Locked time	Recurring blocks, one-day remove/replace/add overrides, hidden overlay mapping	Strong override validation, date/time-zone safety, complete persistence mapping, date-scoped repository queries	11, 15
Free slots	Task type and timeline token exist	Creation/update rules, protection from flexible scheduling, reminder suppression policy, overlap tests	12, 13, 14
Surprise work	Completed surprise logging and immediate flexible-task repair	Persist actual occupancy, prevent later overlap/regression, idempotent replays, completion/locked-hour statistics	12, 13, 14
Task actions	Flexible and required action services	One canonical transition layer, idempotent operation records, completion timestamps/actual intervals, consistent errors	13, 14
Internal task statistics	Baseline counters and increment helpers	Automatic exactly-once updates, late/locked completion calculation, push-before-completion aggregates, child patterns	13
Child tasks	Entry conversion, ownership views, parent completion propagation	Atomic break-up workflow, cycle/direct-child validation, activity/stat updates, application use case	13, 14
Project defaults	Configured static defaults and reminder profile on project	Per-project usage aggregates, deterministic non-blocking learned suggestions, explicit configured-vs-learned resolution	13
Reminder profiles	Gentle/persistent/strict/silent enum on project	Task override, effective-profile resolver, free-slot suppression directive; platform delivery remains outside the pure core	13
Timeline state	UI-independent item mapper, locked overlay state, compact selection	Complete Today query/read model, stable per-occurrence IDs, status metadata, correct “next flexible” exclusion, rollover notices	14
Backlog	Filters, sorts, staleness markers, quick capture	Persist backlog-entered timestamp, settings-backed thresholds, application queries/commands, typed results	11, 14, 15
Application layer	Domain services can be called directly	Coherent use cases that load state, invoke rules, persist all changes atomically, and return UI-ready results	14
Repository contracts	Basic task/project/locked/snapshot interfaces and in-memory fakes	Date/project/parent queries, archive/delete behavior, revisions, activity/settings repositories, unit of work, conformance suite	14, 15
Document mapping	Task and task-statistics map round trips; field-name constants for other entities	Complete codecs for every repository entity, explicit stable codes, schema version, civil-time encoding, migration fixtures	15
MongoDB runtime	Committed target documented; no driver/runtime yet	Trusted runtime decision, actual adapter, indexes, transactions/optimistic concurrency, integration tests, secret handling	16
Backend acceptance	Historical unit test audit and handoff	End-to-end application scenarios, adapter conformance, migration/resilience/performance checks, final backend gate	17
Flutter UI	Intentionally not started	Minimal shell and one vertical slice only after the backend gate; visual design remains open	18

Specification decisions the new plan must make explicit

1. pushed is an activity/movement event, not a durable task lifecycle status.
2. skipped during burnout remains a V2 activity/stat path; V1 may retain a compatible counter/schema field but must not implement the shield/catch-up workflow.
3. A protected Free Slot blocks automatic flexible placement and normal flexible reminder directives. Explicit critical or inflexible commitments may overlap it and must produce a clear conflict/interrupt decision rather than moving it.
4. A surprise task with an actual interval remains occupied historical time for later same-day scheduling operations.
5. Internal activity records may exist for correctness, statistics, migrations, and idempotency, but V1 does not add a visible per-task history panel.
6. Learned project values are suggestions with provenance and confidence; they never silently overwrite configured defaults.
7. Reminder delivery through operating-system/background services is not part of the pure Dart core. V1 backend work provides policy decisions and directives.
8. Production credentials must not be embedded in Flutter. MongoDB access must execute in a trusted runtime selected in Block 16.

Explicitly deferred

• Week and month views
• Weekly reports and dashboards
• Overwhelm shield and burnout catch-up
• Drag-and-drop ordering
• Visible task-history panel
• Dependencies and context tags
• User accounts and production authentication
• Cross-device/full sync and background reconciliation
• Flexible-task overrun behavior
• Advanced assistant/ML behavior