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


# Task Pushing 01 Block 05 — Command Wiring and Persistence

**Status:** Complete.
**Goal:** Connect push menu destinations to application commands and prove their
results persist.

---

## Block outcome

After this block, selecting a push destination runs the backend command through
`SchedulerCommandController`, refreshes the selected date, and persists the
result through SQLite.

---

## Chunk 5.1 — Add command-controller push methods

### Tasks

1. Add command-controller methods for:
   - `pushTaskToNextAvailableSlot`,
   - `pushTaskToTomorrow`,
   - `pushTaskToBacklog`.
2. Use current owner-local time from the runtime clock for command context.
3. Pass selected/current planning dates according to Block 01 semantics.
4. Preserve stale-write checks using card metadata where available.
5. Reuse existing `_run` command-state handling and read refresh behavior.

### Acceptance criteria

- Push methods expose no Flutter widget dependencies.
- Push methods call application use cases, not scheduler engine directly.
- Push command failures flow through existing command failure state.

---

## Chunk 5.2 — Wire menu callbacks through the screen tree

### Tasks

1. Thread push callbacks from `FocusFlowHome` or equivalent through
   `_TodayScreenScaffold`, `TimelineView`, and card widgets.
2. Keep callback names destination-specific.
3. Refresh the currently selected date after a successful command.
4. Clear selected card/modal if the pushed task leaves the selected day.
5. Keep Backlog refresh behavior aligned with existing Backlog controller if one
   is visible in this UI slice.

### Acceptance criteria

- Each menu item reaches the correct command-controller method.
- The visible timeline refreshes after success.
- A task pushed out of the current date disappears or moves according to backend
  read state.

---

## Chunk 5.3 — Use existing application use cases where semantics match

### Tasks

1. For Push to next, prefer `pushFlexibleToNextAvailableSlot` if Block 06
   confirms it honors no-before-now semantics.
2. For Push to tomorrow, prefer `pushFlexibleToTomorrowTopOfQueue` if Block 06
   confirms it places into the first valid no-overlap slot on the next day.
3. For Push to backlog, choose one path and document it:
   - use existing `moveFlexibleToBacklog`, or
   - add a command that routes through `PushDestination.backlog` for consistent
     push-destination accounting.
4. Do not add duplicate command implementations if existing use cases already
   satisfy the product behavior.

### Acceptance criteria

- Command wiring uses the smallest backend surface that satisfies the requested
  behavior.
- Any semantic gap is moved to Block 06 or Block 07 rather than patched in UI.

---

## Chunk 5.4 — Add close/reopen persistence tests for destinations

### Required tests

1. Push to next:
   - start with an incomplete past flexible task,
   - push to next,
   - close/reopen,
   - assert the task is planned in the persisted new slot.
2. Push to tomorrow:
   - start with an incomplete past flexible task,
   - push to tomorrow,
   - close/reopen,
   - load tomorrow,
   - assert the task is planned there.
3. Push to backlog:
   - start with an incomplete past flexible task,
   - push to backlog,
   - close/reopen,
   - assert status is Backlog and schedule fields are cleared.
4. Completion after push:
   - push a task,
   - complete it,
   - assert Push button disappears after refresh.

### Acceptance criteria

- Every destination persists through SQLite.
- Tests use on-disk temp SQLite and close handles before reopen assertions.
- UI/controller tests and backend persistence tests agree on destination results.

---

## Block acceptance criteria

- Push menu destinations are wired to backend commands.
- Results persist and reload.
- Selected-date read refresh shows the backend result.
- No widget computes or saves canonical schedule placement.

## Validation after block

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