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 timestamp, task reminder override, typed validation	Backlog-entered time and remaining persistence/query support	14, 15
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, centralized occupancy, free-slot protection, surprise/actual occupancy, structured non-localized result codes, invariant coverage	Application-facing orchestration and final backend acceptance scenarios	14, 17
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, timeline token, creation/update rules, protection from flexible scheduling, reminder suppression policy, and overlap tests	Application use cases that persist resulting changes atomically	12, 13, 14
Surprise work	Completed surprise logging, immediate flexible-task repair, actual occupancy, idempotent replay protection, and completion/locked-hour accounting	Application use cases that persist all resulting changes atomically	12, 13, 14
Task actions	Flexible and required action services, canonical transition service, internal activity records, idempotent operation handling, completion timestamps/actual intervals, and exactly-once task-stat accounting	Atomic application use cases and persisted activity/stat transaction boundaries	13, 14
Internal task statistics	Baseline counters, increment helpers, activity-derived counter updates, late/locked completion calculation, push-before-completion values, project aggregates, and learned suggestion inputs	Atomic persistence	14
Child tasks	Entry conversion, ownership views, deterministic break-up mutation results, direct-child validation, parent/child completion propagation, lifecycle activities, and idempotent force completion	Application use cases that persist all child-task mutations atomically	13, 14
Project defaults	Configured static defaults, reminder profile on project, per-project usage aggregates, deterministic non-blocking learned suggestions, explicit configured-vs-learned resolution, and effective reminder-profile resolver	Application-layer persistence/query orchestration	13, 14
Reminder profiles	Gentle/persistent/strict/silent enum on project, task override, effective-profile resolver, typed reminder directives, and Free Slot suppression policy	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, task-statistics, and project-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