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


# Task Pushing 01 Block 08 — Validation and Handoff

**Status:** Complete.
**Goal:** Prove task pushing works end to end and close the plan cleanly.

---

## Block outcome

After this block, Task Pushing 01 should be complete. Past incomplete planned
flexible tasks can be pushed to next, tomorrow, or Backlog with durable results.

---

## Chunk 8.1 — Add end-to-end UI flow tests

### Required tests

1. Load a selected date with an incomplete past flexible task.
2. Assert the card shows `Push` and suppresses hover quick actions.
3. Open the Push menu and choose `Push to next`.
4. Assert the selected-date timeline refreshes with the backend result.
5. Repeat for `Push to tomorrow` and assert the task appears when tomorrow is
   selected.
6. Repeat for `Push to backlog` and assert the task leaves the timeline and
   appears in Backlog as fresh where Backlog UI is covered.
7. Complete a past task and assert the Push button disappears.

### Acceptance criteria

- UI flow tests cover all three destinations.
- Tests use command-controller seams or a temp runtime, not widget-side schedule
  mutation.

---

## Chunk 8.2 — Add lifecycle persistence tests

### Required tests

1. Push to next, close/reopen, load destination date, assert task placement.
2. Push to tomorrow, close/reopen, load tomorrow, assert task placement.
3. Push to backlog, close/reopen, load Backlog, assert status, cleared schedule,
   and fresh staleness marker.
4. Attempt no-fit push, close/reopen, assert the original task remains safe and
   unchanged except for any explicitly intended notice/operation record.
5. Attempt duplicate operation id after reopen and assert duplicate behavior is
   safe.

### Acceptance criteria

- Persistence is proven through on-disk temp SQLite files.
- Database/runtime handles are explicitly closed before reopen assertions.
- No destination relies on in-memory-only state.

---

## Chunk 8.3 — Run validation gates

### Commands

Run the strongest available validation set:

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

### Acceptance criteria

- All available gates pass.
- If a command is unavailable in the environment, record the exact command and
  failure reason in the plan handoff notes.

---

## Chunk 8.4 — Update minimal handoff/status docs

### Tasks

1. Update this plan's summary/status when complete.
2. Move the plan folder only if the project's completed-plan workflow calls for
   it.
3. Update `Codex Documentation/Current Software Plan/README.md` to identify the
   next planned implementation area, if known.
4. Do not create a broad overall report.

### Acceptance criteria

- The handoff records changed files, decisions, validation, and unverified gates.
- No unrelated docs are rewritten.

---

## Final plan acceptance criteria

- Past incomplete planned flexible cards show a full Push button.
- Push button suppresses hover quick actions.
- Push menu exposes the three requested destinations.
- Push destinations go through backend commands.
- Push results persist through SQLite.
- Push to Backlog resets freshness without rewriting creation history.
- Validation status is documented.

## Handoff notes

Implemented changes:

1. Added past-task push presentation state, button/menu UI, and command
   callbacks.
2. Routed all three destinations through `SchedulerCommandController` and
   `V1ApplicationCommandUseCases`.
3. Added scheduler/application support for `Push to next` after command time,
   including overdue tasks from previous dates.
4. Added `Task.backlogEnteredAt` and `backlogEnteredAtProvenance`; Backlog age
   filtering and staleness markers now use that freshness anchor with
   `createdAt` fallback.
5. Added on-disk SQLite close/reopen coverage for push-next, push-tomorrow,
   push-backlog, and completion after push.

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
```

Unverified gates:

1. Full `scripts/test.sh`, full package `dart analyze`, and full Flutter
   analyze/test were not rerun for this closeout. Earlier hook/analyzer runs in
   this branch hit the known Dart analysis server `Too many open files` failure.
