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, 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, 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, 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, and in-memory atomic unit-of-work foundation | V1 command use cases that invoke domain rules and return UI-ready mutation results | 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