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

# UI Plan 2 Block 09 — Testing, Validation, Polish, and Handoff

**Goal:** Complete tests, final visual polish, validation commands, and handoff notes for the Backlog tab.

---

## Block outcome

After this block, the Backlog board implementation is tested, validated, documented, and ready for Ashley review or the next implementation plan.

---

## Chunk 9.1 — Core/application tests

### Tests

Add or update tests for:

1. Backlog bucket policy:
   - Do Next,
   - Need Time Block,
   - Break Up First,
   - Not Now,
   - precedence/tie-breaking.
2. Backlog board query:
   - empty state,
   - 24-task seed-like board,
   - search,
   - filters,
   - sort,
   - group none/default,
   - summary totals.
3. Backlog detail query:
   - selected task detail,
   - notes/tags/project metadata,
   - suggested slots,
   - missing duration/no-fit.
4. Commands:
   - create backlog task,
   - update metadata,
   - schedule backlog item,
   - push to someday,
   - remove/archive,
   - break up if implemented.

### Acceptance criteria

- Tests are deterministic.
- Tests do not require Flutter.
- Tests do not depend on wall-clock time without injected context.

---

## Chunk 9.2 — Flutter widget tests

### Tests

Add tests under `apps/focus_flow_flutter/test/` that verify:

1. Sidebar renders `Backlog` active on Backlog screen.
2. Default Backlog screen shows:
   - `Backlog`,
   - `24 tasks`,
   - search placeholder,
   - `Filters`,
   - `Sort: Custom`,
   - `Group: None`,
   - `New Task`,
   - all four column names,
   - `Backlog summary`.
3. Visible seed cards render in expected columns.
4. `Review Q3 budget` card opens drawer.
5. Drawer shows:
   - title,
   - notes,
   - Work project,
   - `finance`,
   - `review`,
   - `60 min`,
   - reward/difficulty labels,
   - suggested slots,
   - all action buttons.
6. Close button closes drawer and clears selected styling.
7. Search narrows visible cards and updates state.
8. Filter/sort/group menus open without throwing.
9. New Task opens create drawer; empty title validation works.
10. Command callbacks are invoked for Schedule/Someday/Remove using fakes/mocks.

### Acceptance criteria

- Widget tests avoid brittle pixel assertions.
- Stable keys are used for important controls.
- Tests remain readable and scoped.

---

## Chunk 9.3 — Forbidden import and boundary tests

### Tasks

Update or preserve `test/forbidden_imports_test.dart` so app still cannot import:

- `scheduler_core/src`,
- Drift/SQLite adapters,
- backup/export internals,
- notification platform internals,
- direct OS APIs for this UI slice.

### Acceptance criteria

- Boundary test passes.
- Any new controller/widget files are covered by forbidden import scan.

---

## Chunk 9.4 — Responsive and overflow validation

### Tasks

Manually or via widget tests inspect Backlog layout at widths:

- 1672 px reference width,
- 1440 px,
- 1280 px,
- 1100 px if supported.

Expected behavior:

- desktop reference matches mockup closely,
- narrower widths use horizontal board scroll or reduce column widths without overflow,
- drawer remains anchored right,
- drawer never shifts board elements,
- summary can collapse or be hidden below a sensible width if needed.

### Acceptance criteria

- No RenderFlex overflow in tested widths.
- Drawer overlay behavior remains correct.

---

## Chunk 9.5 — Final visual polish pass

### Tasks

Compare against both mockups and tune:

- sidebar active state,
- main gutters,
- title/count pill,
- controls spacing,
- column widths/heights,
- card density,
- icons,
- difficulty/reward indicators,
- summary panel,
- drawer width/spacing,
- selected card highlight,
- button heights.

Allowed deviations:

- minor font metric differences,
- safe hit target sizing,
- small responsive adjustments,
- platform-specific rendering differences.

Not allowed:

- white backgrounds,
- drawer shifting columns,
- cards not data-driven,
- missing summary panel,
- missing visible action buttons.

### Acceptance criteria

- Backlog default state and drawer state are close enough for Ashley review.

BREAKPOINT: Stop here for visual review if any major visual section is missing.

---

## Chunk 9.6 — Run validation commands

### Commands

From repo root:

```sh
dart format --set-exit-if-changed .
dart analyze
dart test
```

From Flutter app:

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

If supported by environment:

```sh
scripts/test.sh
```

### Acceptance criteria

- Validation passes, or exact environment-related blockers are documented.
- New failures are fixed before handoff unless Ashley approves deferral.

---

## Chunk 9.7 — Update docs and handoff

### Tasks

Update relevant docs:

- `apps/focus_flow_flutter/README.md` current scope.
- `Codex Documentation/Current Software Plan/README.md` if this plan becomes the active plan.
- Optional implementation summary in completed plans if the repo tracks completed plan copies after execution.

Handoff summary must include:

- files changed,
- implementation decisions,
- commands run and results,
- features implemented,
- deferred items,
- known risks,
- next recommended plan.

### Acceptance criteria

- A new developer/Codex run can understand what changed.
- Deferred items are explicit, not hidden.

---

## Final acceptance checklist

- [ ] Backlog navigation works.
- [ ] Default board matches mockup.
- [ ] Drawer state matches mockup.
- [ ] Drawer overlays and does not shift layout.
- [ ] Four board buckets and counts are data-driven.
- [ ] Summary panel is data-driven.
- [ ] Search/filter/sort/group controls are safe.
- [ ] New Task/Add Task create backlog tasks.
- [ ] Schedule uses backend/application command.
- [ ] Push to Someday is non-destructive.
- [ ] Remove is non-destructive unless Ashley explicitly changed this.
- [ ] Break Up works or is explicitly deferred with approval.
- [ ] Notes/tags/project metadata is either implemented end-to-end or explicitly deferred with approval.
- [ ] Flutter app avoids forbidden imports.
- [ ] Tests pass or blockers are documented.
