# UI Plan 1 Block 06 — Testing, Validation, and Handoff

**Status:** Complete on 2026-06-30.
**Goal:** Harden UI Plan 1 with tests, validation commands, and handoff notes for the next functional component plans.

---

## Block outcome

After this block, Codex should have a validated UI slice with clear documentation of what was implemented, what is intentionally no-op, what remains for later plans, and what commands passed or could not be run.

---

## Chunk 6.1 — Complete widget and unit test coverage for this slice

### Required tests

1. **App shell render test**
   - Finds `FocusFlow`, `Today`, `Backlog`, `Projects`, `Reports`, `Settings`.
   - Finds `Compact`, `Normal`, and top settings button.

2. **Seeded Today render test**
   - Uses fixed clock/date.
   - Finds all seeded task titles.
   - Finds required banner text for `Pay bill`.
   - Verifies `Free Slot` and `Intentional rest` appear.

3. **Visual token mapping test**
   - Verifies task type/status maps to expected visual kinds.
   - Verifies completed surprise maps to completed gray style model.

4. **Difficulty bars test**
   - Verifies notSet=0, veryEasy=1, easy=2, medium=3, hard=4, veryHard=5.
   - Specifically verifies medium effort uses three filled bars.

5. **Modal behavior test**
   - Opens from task click.
   - Closes by X.
   - Closes by outside click.
   - Modal buttons no-op without exceptions.

6. **Forbidden import test**
   - Scans `lib/` and `test/` for forbidden imports.

### Acceptance criteria

- Tests are deterministic.
- Tests do not use sleeps or random values.
- Tests do not require real SQLite or OS notification APIs.

---

## Chunk 6.2 — Add optional visual snapshot guidance without fragile gates

### Tasks

1. Add a README note explaining how to manually run the app at mockup-like size.
2. If golden tests are added, keep them opt-in or very carefully controlled.
3. Do not block core CI on platform-specific font pixel differences unless the repo already has golden conventions.

### Suggested local visual command

```sh
cd apps/focus_flow_flutter
flutter run -d macos
```

or the appropriate desktop device.

### Acceptance criteria

- There is a clear way for Ashley/Codex to visually compare the screen to the mockups.
- No brittle golden requirement is introduced unless explicitly accepted.

---

## Chunk 6.3 — Run validation commands

### Commands

Run from app:

```sh
cd apps/focus_flow_flutter
flutter pub get
dart format lib test
flutter analyze
flutter test
```

Run from repo root:

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

Optional if available:

```sh
scripts/bootstrap_dev.sh
```

### Reporting requirements

In the final implementation report, include:

- files changed,
- commands run,
- passed/failed/unverified status,
- any Flutter toolchain limitations,
- screenshots/manual visual comparison notes if available,
- any intentional deviations from mockups.

### Acceptance criteria

- Flutter analyze/test pass.
- Root Dart tests pass, or any failure is reported with exact failing command/output summary.
- No formatting drift remains.

---

## Chunk 6.4 — Update app README/handoff notes

### Tasks

Update or create `apps/focus_flow_flutter/README.md` with:

1. Scope of current UI.
2. How to run.
3. How to test.
4. What is intentionally no-op.
5. Where seed data lives.
6. How the UI consumes backend/application state.
7. Known next plans:
   - wire functional Done/Push/Backlog/Break up,
   - backlog screen,
   - quick capture,
   - persistent SQLite composition,
   - settings/navigation,
   - Shield/Recovery later.

### Acceptance criteria

- A future Codex session can understand the UI slice without rereading all implementation code.
- README states that scheduler core remains the source of truth.
- README lists no-op controls explicitly to avoid accidental bug reports.

---

## Chunk 6.5 — Final scope audit

### Audit checklist

- [ ] App launches into compact Today screen.
- [ ] Source mockups are copied into this plan folder.
- [ ] Clean visual state matches `main_screen_compact.png` closely.
- [ ] Selected modal state matches `task_selected_modal.png` closely.
- [ ] No white app background.
- [ ] Buttons look enabled but are no-op except task click/close behavior.
- [ ] Task click opens modal.
- [ ] Outside click closes modal.
- [ ] Close button closes modal.
- [ ] Difficulty icon has five bars.
- [ ] Medium effort fills three bars.
- [ ] Reward icon uses solid sparkle/star symbol.
- [ ] Seed data is static and deterministic.
- [ ] Seed data is represented as backend/domain/application state.
- [ ] UI does not duplicate scheduling rules.
- [ ] UI does not import scheduler `src/` files.
- [ ] UI does not import SQLite/Drift/platform notification APIs.
- [ ] Root backend packages remain unchanged unless explicitly justified.
- [ ] Tests and validations are reported.

BREAKPOINT: Stop at this final audit and report results before starting any functional wiring plan.

---

## Block acceptance criteria

- All UI Plan 1 validation is complete or honestly marked unverified.
- Documentation captures scope and next steps.
- No unrelated functionality was pulled in.
- The zip/repo is ready for the next plan: functional component wiring.

---

## Completed implementation

1. Added widget/unit coverage for shell labels, seeded Today state, visual kind
   mapping, difficulty fill counts, modal behavior, and forbidden imports.
2. Updated `apps/focus_flow_flutter/README.md` with scope, run/test commands,
   seed-data location, backend-state ownership, no-op controls, and next-plan
   notes.
3. Kept golden/snapshot testing out of CI; mockup comparison remains manual to
   avoid brittle platform font pixel gates.

## Final audit

- [x] App launches into compact Today screen.
- [x] Source mockups are copied into this plan folder.
- [x] Clean visual state follows `main_screen_compact.png` structure.
- [x] Selected modal state follows `task_selected_modal.png` structure.
- [x] No white app background.
- [x] Buttons look enabled but are no-op except task click/close behavior.
- [x] Task click opens modal.
- [x] Outside click closes modal.
- [x] Close button closes modal.
- [x] Difficulty icon has five bars.
- [x] Medium effort fills three bars.
- [x] Reward icon uses solid sparkle/star symbol.
- [x] Seed data is static and deterministic.
- [x] Seed data is represented as backend/domain/application state.
- [x] UI does not duplicate scheduling rules.
- [x] UI does not import scheduler `src/` files.
- [x] UI does not import SQLite/Drift/platform notification APIs.
- [x] Root backend packages remain unchanged.
- [x] Tests and validations are reported.

## Verification

1. `scripts/bootstrap_dev.sh`: passed.
2. `flutter pub get`: passed.
3. `dart format lib test`: passed.
4. `flutter analyze`: passed, no issues found.
5. `flutter test`: passed, 6 tests.
6. `scripts/test.sh`: passed, including root `dart analyze`, 338 Dart tests,
   83.27% package coverage, documentation checks, and API doc generation.
