<!-- SPDX-FileCopyrightText: 2026 FocusFlow contributors -->
<!-- SPDX-License-Identifier: AGPL-3.0-only -->


# Date Selection 01 Block 01 — Scope and Baseline

**Status:** Complete.
**Goal:** Verify the persistence-backed app baseline and lock the exact semantics
for date selection before implementing UI callbacks.

---

## Block outcome

After this block, the repo state and product behavior for date navigation should
be explicit. Later blocks should be able to implement date switching without
reopening architectural decisions.

---

## Chunk 1.1 — Confirm persistence prerequisite

### Tasks

1. Confirm Persistence Plan 1 is complete in the current branch.
2. Verify normal app startup no longer inserts arbitrary demo timeline tasks.
3. Verify app startup opens an on-disk SQLite database through the approved
   runtime composition.
4. Verify quick capture, schedule-from-backlog, complete, uncomplete, close, and
   reopen already work for the default selected date.
5. Record any missing persistence behavior as a blocker before continuing.

### Acceptance criteria

- Date Selection 01 does not start from demo seed runtime.
- The app has one durable persistence path for normal startup.
- Any missing Persistence Plan 1 behavior is documented and fixed before Block 02.

---

## Chunk 1.2 — Reconcile current composition and controller boundaries

### Tasks

1. Inspect the current post-persistence composition root.
2. Identify the object that owns:
   - `GetTodayStateQuery`,
   - `V1ApplicationCommandUseCases`,
   - `V1ApplicationManagementUseCases`,
   - owner id,
   - owner timezone,
   - runtime clock,
   - SQLite lifecycle/disposal.
3. Identify whether `DemoSchedulerComposition` still exists only for tests or
   explicit demo mode.
4. Decide whether selected date should live in:
   - a dedicated `SelectedDateController`,
   - an expanded `TodayScreenController`, or
   - parent `FocusFlowHome` state that reconfigures date-aware controllers.
5. Prefer the smallest design that keeps date behavior testable and does not
   force widgets to know scheduler internals.

### Acceptance criteria

- The selected-date owner is named in the implementation notes for this block.
- Composition APIs can create reads/commands for arbitrary `CivilDate` values.
- No widget is planned to instantiate repositories, Drift classes, or scheduler
  engine objects.

---

## Chunk 1.3 — Lock selected-date semantics

### Tasks

1. Define selected date as the currently visible planning day in the owner's
   timezone.
2. Confirm selected date changes are read-only until the user runs a command.
3. Confirm arrows move exactly one civil day at a time.
4. Confirm the date picker jumps directly to the chosen civil date.
5. Confirm command timestamps use the real runtime clock, not the selected date
   as a fake `now`.
6. Confirm scheduling a backlog task while viewing a selected day targets that
   selected day's planning window.
7. Confirm completing a future/past selected-day task records the actual
   completion instant from the runtime clock.

### Acceptance criteria

- Date navigation cannot itself create, move, complete, or delete tasks.
- Date navigation uses `CivilDate` at app boundaries.
- Instant/date conversion happens through existing owner timezone utilities.

---

## Chunk 1.4 — Identify tests to preserve before edits

### Tasks

1. Locate existing Flutter widget tests for the top bar, timeline, modal, and
   Today screen controller.
2. Locate persistence lifecycle tests added by Persistence Plan 1.
3. Locate scheduler-core tests for `GetTodayStateQuery` and command use cases.
4. Add a small checklist of tests that must still pass after this plan.

### Acceptance criteria

- The validation targets for later blocks are known before code changes begin.
- Existing tests are not deleted or weakened to make date selection pass.

---

## Block acceptance criteria

- Persistence prerequisite is verified.
- Selected-date state ownership is decided.
- Selected-date behavior is documented.
- Tests and validation commands for the plan are known.

## Implementation notes

- Persistence Plan 1 has been fast-forward merged into `main` before this branch
  was created. Normal Flutter startup uses `PersistentSchedulerComposition.open`
  and `SqliteApplicationRuntime.open`; seeded demo data remains isolated to
  `DemoSchedulerComposition.seeded` for tests and explicit demo construction.
- The existing composition root owns `GetTodayStateQuery`,
  `V1ApplicationCommandUseCases`, `V1ApplicationManagementUseCases`, owner id,
  owner timezone, operation clocks, and SQLite lifecycle/disposal.
- Selected date will live in a dedicated `SelectedDateController`. `FocusFlowHome`
  owns that controller and wires it to Today reads and command execution. Widgets
  will receive callbacks and display-ready labels only; they will not instantiate
  repositories, Drift types, scheduler use cases, or engine objects.
- Selected date is the visible owner-local `CivilDate`. Changing it is read-only:
  previous/next move one civil day, picker selection jumps directly to the chosen
  civil date, command timestamps use the runtime clock, backlog scheduling targets
  the selected planning day, and completion records the real completion instant.
- Validation targets to preserve: `scripts/test.sh`; `flutter test` in
  `apps/focus_flow_flutter`; controller, app, widget, model, and persistent
  lifecycle Flutter tests added by this plan; core query and command tests under
  `packages/scheduler_core`; SQLite lifecycle tests under
  `packages/scheduler_persistence_sqlite`.
- Baseline validation on this branch: `flutter test` in
  `apps/focus_flow_flutter` passed with 24 tests. `scripts/test.sh` did not reach
  package tests because `dart analyze` failed in the Dart analysis server with
  `OS Error: Too many open files, errno = 24` while setting analysis roots.

## Validation after block

```sh
scripts/test.sh
cd apps/focus_flow_flutter
flutter test
```

If Flutter tooling is unavailable, run all non-Flutter package tests and document
that Flutter validation is blocked by environment setup.
