84 lines
7.2 KiB
Markdown
84 lines
7.2 KiB
Markdown
# 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 and timeline token exist | Creation/update rules, protection from flexible scheduling, reminder suppression policy, overlap tests | 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, and push-before-completion values | Project aggregates, child completion patterns, and atomic persistence | 13, 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 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
|