# 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