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

# UI Plan 2 Implementation Notes

## Block 01 Baseline Map

1. Sidebar and app shell currently render through
   `apps/focus_flow_flutter/lib/widgets/sidebar.dart`,
   `apps/focus_flow_flutter/lib/widgets/app_shell.dart`, and the
   `FocusFlowHome` parts under `apps/focus_flow_flutter/lib/app/home/`.
2. Navigation state is not implemented yet. `Sidebar` hard-codes Today as
   active, and `FocusFlowHome` owns only Today controllers. UI Plan 2 should add
   app-level section state in the home/composition layer before rendering the
   Backlog board.
3. Backlog board data needs new public scheduler application read models. The
   current `BacklogQueryResult` is list-shaped and returns raw `Task` values via
   `BacklogItemReadModel`, which is not enough for board columns, summary,
   detail drawer metadata, or suggested slot previews.
4. Existing commands include quick capture to backlog, schedule backlog item to
   next available slot, move flexible tasks to backlog, remove task, and break
   up task. Push-to-Someday and non-destructive backlog archive still need
   command-level decisions before the drawer actions can be final.
5. UI Plan 1 components to reuse include `FocusFlowTokens`, the dark shell,
   timeline reward icon, difficulty bars, selected overlay patterns, and the
   top-bar icon/segmented-control styling conventions.

## Block 01 Validation

- `scripts/bootstrap_dev.sh`: passed.
- `dart analyze`: passed.
- `dart test`: passed.
- `flutter analyze` in `apps/focus_flow_flutter`: passed.
- `flutter test` in `apps/focus_flow_flutter`: passed.

## Block 02 Audit

1. `GetBacklogRequest`, `BacklogQueryResult`, and `BacklogItemReadModel` remain
   the compatibility path for the existing simple backlog pane.
2. UI Plan 2 should add board-specific public read models instead of extending
   `BacklogQueryResult`, because the board needs columns, summary
   distributions, child previews, detail rows, and suggested slots while the
   current list result intentionally exposes raw tasks plus staleness markers.
3. The board bucket policy belongs in pure scheduler backlog code under
   `packages/scheduler_core/lib/src/scheduling/backlog/`, with Flutter consuming
   only public `scheduler_core.dart` exports.

## Block 02 Notes/Tags Breakpoint

Adding real V1 task notes and freeform tags is a broad persistence change, not
only a drawer read-model change. It would touch at least:

1. `Task`, `Task.quickCapture`, and `Task.copyWith`.
2. Task document fields and `TaskDocumentMapping`.
3. Persistence contract field sets and document field coverage tests.
4. In-memory application/repository round trips through the full domain object.
5. SQLite Drift task table columns, generated database code, schema versioning,
   migration strategy, migration tests, and both SQLite task mappers.
6. Command/capture surfaces if the UI can create or edit notes/tags.

Per `UI_PLAN_2_BLOCK_02_BACKLOG_READ_MODELS_AND_METADATA.md`, this is the
breakpoint where Ashley needs to choose whether drawer tags should be read-only
placeholders for now or true V1 metadata with a schema migration.
