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


# Date Selection 01 Block 04 — Date-Aware Commands and Persistence

**Status:** Complete.
**Goal:** Ensure task commands run against the currently selected date and persist
correctly across multiple days.

---

## Block outcome

After this block, a user can switch days, add/schedule/complete tasks on that
visible day, close the app, reopen it, and see the expected state on the same
selected day.

Implementation notes:

1. `SchedulerCommandController` now reads the selected date at command execution
   time.
2. Persistent and demo compositions create date-aware read and command
   controllers.
3. SQLite lifecycle coverage proves future-day schedule, complete, uncomplete,
   reopen, and unified Backlog behavior.

---

## Chunk 4.1 — Make command controller date-aware

### Tasks

1. Replace fixed `SchedulerCommandController.localDate` construction with a
   current-date provider or recreate command controllers when selected date
   changes.
2. Ensure these commands use the selected date at execution time:
   - schedule backlog item to next available slot,
   - complete flexible task,
   - complete required visible task,
   - uncomplete task.
3. Keep quick capture to backlog date-neutral unless the current capture UI adds
   an explicit schedule-now option.
4. Include the selected date in command read hints when relevant.
5. Preserve stale-revision checks by passing `expectedUpdatedAt` unchanged.

### Acceptance criteria

- Scheduling from Backlog while viewing tomorrow places the task in tomorrow's
  planning window when a valid slot exists.
- Completing a task while viewing a non-current day runs the command against
  that visible day's planning state.
- Command code does not read date labels from widgets.

---

## Chunk 4.2 — Refresh the right read models after date-aware commands

### Tasks

1. After a successful command, reload the currently selected date.
2. If a command's read hint references another affected date, decide whether to:
   - reload only the selected date for V1, or
   - add a small future-proof invalidation hook.
3. For this plan, prefer reloading the selected date only unless tests prove the
   UI needs immediate cross-date refresh.
4. Make sure moving a task into a different day removes it from the current
   selected-day timeline after refresh.

### Acceptance criteria

- After schedule/complete/uncomplete, visible cards match persisted backend
  state for the selected date.
- No stale card stays visible after a successful command that removes it from the
  selected day.

---

## Chunk 4.3 — Persist tasks on previous and future days

### Tasks

1. Add lifecycle tests using a temp SQLite file:
   - open app/runtime on date A,
   - capture a task,
   - schedule it into date A,
   - close database/runtime,
   - reopen with date A selected,
   - assert task placement remains.
2. Repeat for a future date relative to the test clock.
3. Repeat for a previous date if the scheduler permits scheduling into a past
   selected day; otherwise document the validation failure and expected UX.
4. Verify Backlog remains unified across date changes.

### Acceptance criteria

- Future-day scheduled task persists after close/reopen.
- Previous-day task behavior is explicitly tested or explicitly rejected by
  backend validation.
- Backlog tasks are not duplicated across date navigation.

---

## Chunk 4.4 — Persist done/not-done state across selected dates

### Tasks

1. Add lifecycle tests for completing a task while viewing a future date.
2. Add lifecycle tests for completing a task while viewing a previous date if the
   backend allows it.
3. Close and reopen the database/runtime after completion.
4. Assert `TaskStatus.completed`, `completedAt`, actual times where present, and
   updated metadata reload.
5. Uncomplete the same task, close/reopen, and assert planned/not-done state
   reloads.

### Acceptance criteria

- Done state persists per task regardless of which selected date initiated the
  command.
- Uncomplete state persists and returns the card to normal planned state.
- Completion timestamp remains the real command clock instant.

---

## Block acceptance criteria

- Reads and commands use the selected date consistently.
- Date-specific schedule placement persists across app restarts.
- Done/not-done state persists across app restarts.
- Backlog remains unified and durable.

## Validation after block

```sh
cd packages/scheduler_persistence_sqlite
dart test
cd ../../apps/focus_flow_flutter
flutter test
```
