focus-flow/Codex Documentation/Current Software Plan/Task Pushing 01 - Past Task Push Controls/TASK_PUSHING_01_SUMMARY.md

Task Pushing 01 Summary — Past Task Push Controls

Status: Planned. 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.

---

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:

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.