focus-flow/Codex Documentation/Archived plans/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, Today pending-notice read model	Application-facing command 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, overlap tests, and atomic create/update/remove application commands	Management/settings queries and future UI rendering	12, 13, 14, 18
Surprise work	Completed surprise logging, immediate flexible-task repair, actual occupancy, idempotent replay protection, completion/locked-hour accounting, and atomic application command persistence	Final backend acceptance scenarios	12, 13, 14, 17
Task actions	Flexible and required action services, canonical transition service, internal activity records, idempotent operation handling, completion timestamps/actual intervals, exactly-once task-stat accounting, and atomic V1 application commands	Management queries and final backend acceptance scenarios	13, 14, 17
Internal task statistics	Baseline counters, increment helpers, activity-derived counter updates, late/locked completion calculation, push-before-completion values, project aggregates, learned suggestion inputs, and atomic command persistence	MongoDB adapter persistence and final backend acceptance scenarios	14, 15, 16, 17
Child tasks	Entry conversion, ownership views, deterministic break-up mutation results, direct-child validation, parent/child completion propagation, lifecycle activities, idempotent force completion, and atomic application commands	Final backend acceptance scenarios	13, 14, 17
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, and pending notice projection	Flutter rendering and later management/read-model queries	14, 18
Backlog	Filters, sorts, staleness markers, quick capture	Persist backlog-entered timestamp, settings-backed thresholds, application queries/commands, typed results	11, 14, 15
Application layer	Application operation context, typed result/failure contracts, centralized scheduler input loader, side-effect-free read boundary, complete Today query/read model, V1 atomic command use cases, and in-memory atomic unit-of-work foundation	Management queries/settings commands and explicit rollover/startup orchestration	14
Repository contracts	Basic task/project/locked/snapshot interfaces, activity/settings/project-statistics/operation repository contracts, and in-memory staged unit of work	Date/project/parent queries, archive/delete behavior, revisions, complete persistence codecs, and adapter 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