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


# Task Pushing 01 Block 01 — Scope and Domain Semantics

**Status:** Complete.
**Goal:** Confirm the exact pushable task scope and lock destination semantics
before adding visible controls.

---

## Block outcome

After this block, the implementation should know which cards can show `Push`,
what `past` means, and what each destination must do.

## Implementation notes

1. Task Pushing 01 keeps V1 support limited to planned flexible tasks. Required,
   locked, surprise, and free-slot cards must not show the full Push button.
2. `past incomplete` is evaluated against owner-local current time. Historical
   selected dates can make an incomplete scheduled task pushable, but future
   selected dates do not make tasks pushable before their scheduled end.
3. `Push to next` targets the next valid no-overlap slot after real current
   owner-local time. Later-today placement is preferred when a fit exists.
4. `Push to tomorrow` targets the owner-local day after real current time, not
   the day after the selected review date.
5. `Push to backlog` preserves `createdAt` and resets freshness through the
   existing `backlogEnteredAt` persistence field, promoted into domain/read
   behavior by this plan.

---

## Chunk 1.1 — Confirm prerequisites

### Tasks

1. Confirm Persistence Plan 1 is complete.
2. Confirm Date Selection 01 is complete.
3. Verify the app can load arbitrary selected dates from persisted SQLite state.
4. Verify command controllers refresh the selected date after mutations.
5. Verify task completion and uncompletion persist across close/reopen.

### Acceptance criteria

- Task Pushing 01 starts from a date-aware, persistence-backed UI.
- Any missing prerequisite behavior is fixed before continuing.

---

## Chunk 1.2 — Verify pushable task types

### Tasks

1. Inspect current scheduler-core command support for push destinations.
2. Confirm that V1 push support is planned flexible tasks only unless explicitly
   expanded in this block.
3. Decide how to present past incomplete non-flexible tasks for this plan:
   - preferred V1: keep normal non-push UI and do not show the Push button,
   - alternative: add backend-supported required-task push semantics with tests
     before exposing UI.
4. Document the decision in the block handoff notes.

### Acceptance criteria

- The UI never calls a flexible-task-only command for non-flexible tasks.
- Unsupported task types do not show the Push button.
- Any expanded support is backed by scheduler-core tests first.

---

## Chunk 1.3 — Define `past incomplete` precisely

### Tasks

1. Use owner-local current time as the clock reference.
2. A planned flexible task is past/incomplete when:
   - it is not completed,
   - it has scheduled placement,
   - its scheduled end is before the current owner-local instant, or the selected
     date is before the current owner-local date and the scheduled task remains
     incomplete.
3. Future selected-day tasks are not past unless the real current time is already
   after their scheduled end.
4. A completed task is never in push-button state.
5. A backlog task is never in push-button state because it is not on the
   timeline.

### Acceptance criteria

- Detection works for earlier-today tasks.
- Detection works for previous-day incomplete tasks.
- Detection does not trigger for future tasks.
- Detection clears immediately after completion refresh.

---

## Chunk 1.4 — Lock push destination semantics

### Tasks

1. Define Push to next:
   - schedule the task into the next valid no-overlap slot after current
     owner-local time,
   - use later today when a valid slot exists,
   - otherwise move to the next future valid slot allowed by backend rules.
2. Define Push to tomorrow:
   - target the next owner-local civil day relative to current owner-local date,
   - schedule into the first valid no-overlap slot for that day.
3. Define Push to backlog:
   - set task status to Backlog,
   - clear scheduled start/end,
   - reset backlog freshness anchor to current time,
   - preserve original creation timestamp.
4. Confirm no destination uses widget-side slot calculation.

### Acceptance criteria

- Destination semantics are testable in core/application tests.
- Current selected date does not override the meaning of current time.
- Push to tomorrow is relative to the real owner-local current date, not the
  historical selected date being reviewed.

---

## Block acceptance criteria

- Pushable scope is explicit.
- Past/incomplete detection rules are explicit.
- Destination semantics are explicit.
- Any required core behavior changes are identified before UI work.

## Validation after block

```sh
cd packages/scheduler_core
dart analyze
dart test
```
