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

# Persistence Plan 1 Block 06 — Lifecycle Validation and Handoff

**Status:** Complete on 2026-07-02.
**Goal:** Prove the requested close/reopen persistence behavior, run validation,
and document what changed for the next functional plan.

---

## Block outcome

After this block, the repo should have a validated SQLite-backed runtime slice
with clear handoff notes. The next plan can safely build richer task add/edit
flows or wire more modal controls without first solving persistence.

---

## Chunk 6.1 — Add pure Dart lifecycle integration tests

### Required tests

Create or extend package-level integration tests so the persistence proof does
not depend only on Flutter widgets.

1. Open temp-file SQLite database.
2. Bootstrap owner settings and default project.
3. Run `quickCaptureToBacklog` through `V1ApplicationCommandUseCases`.
4. Close DB.
5. Reopen DB.
6. Read Backlog and assert the task exists.
7. Schedule task to next available slot.
8. Close/reopen.
9. Read Today and assert schedule placement exists.
10. Complete task.
11. Close/reopen.
12. Read Today and assert completed state exists.
13. Uncomplete task.
14. Close/reopen.
15. Read Today and assert planned/not-done state exists.

### Acceptance criteria

- Tests exercise the same application use cases used by Flutter.
- Tests do not inspect raw rows except for targeted diagnostics.
- Tests close every database handle before reopen assertions.

---

## Chunk 6.2 — Add Flutter lifecycle smoke tests

### Required tests

1. Pump app with persistent temp-file composition.
2. Verify empty first-run state.
3. Capture a task through the visible quick-capture UI.
4. Dispose app/composition and pump a new app with the same DB path.
5. Verify the task appears.
6. Schedule the task if current UI exposes the action.
7. Dispose/reopen.
8. Verify planned Today card appears.
9. Mark done.
10. Dispose/reopen.
11. Verify done/completed visual state appears.

### Acceptance criteria

- The requested user path is proven at widget level.
- Test names describe the close/reopen behavior explicitly.
- Demo widget tests remain separate from persistent lifecycle tests.

---

## Chunk 6.3 — Manual verification script/checklist

### Tasks

1. Add a short manual checklist to app README or a plan handoff file:

   ```sh
   scripts/bootstrap_dev.sh
   scripts/dev.sh --sqlite /tmp/focus_flow_persistence_plan_1.sqlite
   ```

2. Manual path:
   - start app,
   - capture a task,
   - schedule it if visible,
   - mark it done,
   - close app,
   - restart with the same `--sqlite` path,
   - confirm task and done state persist.
3. Include how to reset the local dev DB safely.
4. Include the actual default DB path used by scripts.

### Acceptance criteria

- A developer can manually verify persistence without reading code.
- Reset instructions distinguish deleting dev data from backup/restore.

---

## Chunk 6.4 — Update documentation to match reality

### Files to review/update

1. `apps/focus_flow_flutter/README.md`
2. Root `README.md` only if commands or behavior changed.
3. `Codex Documentation/Current Software Plan/README.md`
4. This plan's block files after execution, moving completed files if that is the
   current project convention.
5. Any completed-plan index if the project archives completed plans after the
   implementation is done.

### Documentation updates

1. Remove or revise claims that all visible controls are intentionally no-op.
2. Document that normal runtime uses SQLite.
3. Document demo/test seed boundaries.
4. Document current persistence proof and known limits.
5. Document validation commands and results.
6. Keep backup/restore and export/import boundaries unchanged.

### Acceptance criteria

- Docs do not imply demo seed is normal runtime.
- Docs identify exactly what persists now and what still does not.
- Docs do not promise future UI/control behavior that is still unwired.

---

## Chunk 6.5 — Run full validation gates

### Required commands

Run the broadest available set:

```sh
scripts/bootstrap_dev.sh
scripts/test.sh
cd apps/focus_flow_flutter
flutter pub get
flutter analyze
flutter test
```

If Flutter is unavailable in the execution environment, run all available Dart
validation and document Flutter as unverified.

### Extra focused commands

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

If a new runtime package was added:

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

### Acceptance criteria

- Every changed package has package-local analyze/test results.
- Root backend gate passes.
- Flutter gate passes when the Flutter SDK is available.
- Coverage remains above the current project threshold or any gap is documented
  and fixed before handoff.

---

## Chunk 6.6 — Final handoff notes

### Required content

At the end of implementation, add a concise handoff note with:

1. Files changed.
2. New runtime/composition entry points.
3. SQLite schema/migration version decision.
4. What state now persists.
5. What state is still intentionally not in scope.
6. Commands run and results.
7. Known risks or follow-up plan suggestions.
8. Manual close/reopen verification result if it was run.

### Acceptance criteria

- Handoff is specific enough for the next assistant/developer to continue
  without re-discovering the persistence boundary.
- No unverified claim is written as passed validation.

---

## Block acceptance criteria

- Pure Dart lifecycle tests prove add/schedule/done/uncomplete close/reopen.
- Flutter lifecycle tests prove the visible user path.
- Manual verification instructions exist.
- Docs match the new SQLite runtime behavior.
- Validation results are recorded honestly.

## Validation after block

```sh
scripts/test.sh
cd apps/focus_flow_flutter
flutter analyze
flutter test
```

## Completion statement template

Use this shape in the final implementation handoff:

```text
Persistence Plan 1 is complete.

Changed:
- ...

Now persists:
- tasks captured from the UI
- schedule placement
- done/not-done state
- owner settings/default project bootstrap
- application operation/activity/statistics records needed by current commands

Validation:
- scripts/test.sh: passed/failed/unavailable
- flutter analyze: passed/failed/unavailable
- flutter test: passed/failed/unavailable

Not in scope:
- full task editor
- backup/restore UI
- export/import UI
- sync/calendar/notifications
```
