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


# Task Pushing 01 Summary — Past Task Push Controls

**Status:** Complete.
**Scope level:** XHIGH implementation plan.
**Primary outcome:** Past, incomplete scheduled tasks expose a persistent push
control that can move the task to the next available slot, tomorrow's first open
slot, or Backlog.

---

## Current repo facts this plan is based on

1. Scheduler core already has flexible-task push destinations:
   `nextAvailableSlot`, `tomorrowTopOfQueue`, and `backlog`.
2. `V1ApplicationCommandUseCases` already exposes push-related commands for
   planned flexible tasks:
   - `pushFlexibleToNextAvailableSlot`,
   - `pushFlexibleToTomorrowTopOfQueue`,
   - `moveFlexibleToBacklog`.
3. The Flutter command controller currently wires completion and scheduling, but
   push methods are not exposed to card widgets.
4. Timeline cards already have reward and difficulty controls in the trailing
   area.
5. Timeline cards already have `showsQuickActions`, but the new past-task push
   state must suppress hover actions while the full push button is visible.
6. Current backlog staleness uses task creation age; this does not satisfy the
   requested behavior that pushing to Backlog resets the backlog freshness timer.
7. Date Selection 01 should make selected-day reloads and cross-date persistence
   reliable before this plan starts.

---

## Product behavior

1. A task that is scheduled in the past and not complete still uses its normal
   card styling.
2. While in this past/incomplete state, the card shows a right-side `Push`
   button next to reward and difficulty icons.
3. The push button has visual priority over the card time text and sits on a
   higher layer if layout overlaps.
4. Hover quick-action buttons do not show while the full `Push` button is shown.
5. Marking the task complete removes the push button and returns the card to
   normal completed behavior.
6. Clicking `Push` opens a menu with:
   - `Push to next`,
   - `Push to tomorrow`,
   - `Push to backlog`.
7. Push to next moves the task to the next available no-overlap slot after the
   current owner-local time. If a valid slot exists later today, use that.
8. Push to tomorrow moves the task to the first valid no-overlap slot on the next
   owner-local day.
9. Push to backlog removes schedule placement and marks the backlog freshness
   timer as fresh regardless of the task's original age.
10. All push results persist and survive close/reopen.

---

## Scope assumption to verify in Block 01

V1 core push commands are currently flexible-task oriented. This plan should
apply the push button to planned flexible tasks first. Required, locked,
surprise, and free-slot cards must not receive unsupported push commands unless
Block 01 deliberately expands backend support with tests.

---

## Definition of done

Task Pushing 01 is complete when all of the following are true:

1. The read/presentation model can identify a past, incomplete, planned flexible
   task.
2. Past incomplete planned flexible cards show a full `Push` button beside the
   reward/difficulty icons.
3. The full push button suppresses hover quick actions.
4. Completed cards never show the full push button.
5. Clicking the push button opens a menu with exactly the three requested
   destinations.
6. Push to next uses backend scheduling and never places the task before current
   owner-local time.
7. Push to next uses a same-day slot when one is available later today.
8. Push to tomorrow uses the next owner-local day and places into the first valid
   no-overlap slot.
9. Push to backlog clears scheduled start/end and resets backlog freshness to
   fresh without rewriting original task creation truth.
10. Push commands are persisted through SQLite and survive close/reopen.
11. UI widgets do not contain scheduling, Drift, SQL, or repository logic.
12. Validation gates pass, or unavailable commands are documented.

## Completion notes

Implemented on branch `task-pushing-01-past-task-controls`.

Key decisions:

1. Push support remains limited to planned flexible tasks in V1.
2. `Push to next` uses the real current owner-local date/time, not the selected
   review date, and never schedules before that instant.
3. `Push to tomorrow` targets the next owner-local civil day relative to command
   time.
4. `Push to backlog` records `backlogEnteredAt` and provenance while preserving
   original `createdAt`.

Validation completed:

```sh
cd packages/scheduler_core
dart test test/document_mapping_test.dart test/scheduling_engine_test.dart test/application_commands_test.dart test/persistence_edge_cases_test.dart test/edge_case_regression_test.dart test/task_lifecycle_test.dart
cd ../../apps/focus_flow_flutter
flutter test test/models/past_task_push_presentation_test.dart test/widget_test.dart test/persistent_composition_test.dart
flutter test test/persistent_composition_test.dart
```

---

## Non-goals

1. No drag-and-drop push behavior.
2. No schedule review modal unless existing backend result UX already requires
   it.
3. No week/month views.
4. No Shield/Recovery flow.
5. No recurring task rollover.
6. No calendar sync.
7. No redesign of reward/difficulty icons beyond layout needed for the Push
   button.
8. No frontend-only task movement.

---

## Architecture rule

The push flow must be command-driven:

```text
Past-task presentation flag
  -> card Push button
  -> push destination menu
  -> SchedulerCommandController method
  -> V1ApplicationCommandUseCases
  -> scheduling core / ApplicationUnitOfWork
  -> SQLite persistence
  -> selected-date read refresh
```

The card may decide whether to show a button from presentation flags. It must not
calculate canonical new slots or mutate task times.