# UI Plan 1 Block 01 — Repo Orientation and Scope Guardrails

**Status:** Complete on 2026-06-30.  
**Goal:** Establish the Flutter app workspace and guardrails before replacing/building the UI slice.

---

## Block outcome

After this block, Codex should know whether `apps/focus_flow_flutter/` exists in the actual working repo, should have a safe Flutter app target available, and should have basic guardrails preventing UI code from leaking into core or persistence internals.

No visual polish is required in this block beyond a runnable empty shell if a new app must be created.

---

## Chunk 1.1 — Read project rules and verify repo state

### Tasks

1. Read `AGENTS.md` completely.
2. Read `Codex Documentation/README.md`.
3. Read this plan summary and all mockup references.
4. Check whether `apps/focus_flow_flutter/` exists.
5. Check whether root `pubspec.yaml` includes the Flutter app in the Dart workspace. It should not unless repo instructions have changed.
6. Check whether completed plan docs claim prior UI work exists. Treat those docs as historical unless files actually exist.
7. Record a short implementation note in the block completion summary:
   - app directory existed/missing,
   - any existing Flutter files preserved/replaced,
   - validation commands available in the environment.

### Design decisions

- Repo files win over historical planning docs for code truth.
- If the app directory is missing, create it under `apps/focus_flow_flutter/`.
- If the app directory exists, preserve package names and existing test harness where reasonable, but replace the provisional UI with this plan's UI.
- Do not touch backend package code unless the app cannot compile due to a public API issue. If that happens, stop and report the mismatch rather than silently changing domain contracts.

### Acceptance criteria

- Codex can state exactly where the Flutter app lives.
- No backend/core files are modified in this chunk.
- No current plan docs are moved or archived.

BREAKPOINT: Stop after repo orientation if the app directory state is unclear or conflicts with `AGENTS.md`.

---

## Chunk 1.2 — Create or reconcile the Flutter app target

### Tasks when the app is missing

1. Create `apps/focus_flow_flutter/` as a Flutter desktop app.
2. Keep it outside the root Dart workspace.
3. Add local path dependencies needed for this slice:
   - `scheduler_core` via `../../packages/scheduler_core`.
4. Do not add SQLite, Drift, notification, backup, export, or platform-specific adapter dependencies.
5. Remove/replace the counter-template UI.
6. Keep generated platform folders only as required by Flutter desktop creation.

Suggested command if creating from scratch:

```sh
flutter create --platforms=macos,windows,linux apps/focus_flow_flutter
```

If Codex cannot run `flutter create`, manually create the minimal Flutter app structure only if the repository already contains enough Flutter scaffolding conventions. Otherwise stop and report the missing toolchain.

### Tasks when the app exists

1. Inspect existing `pubspec.yaml`, `lib/`, and `test/`.
2. Preserve useful app-local package configuration.
3. Replace only provisional UI code needed by this plan.
4. Keep any existing app-local lint/analysis configuration unless it conflicts with repo rules.

### Acceptance criteria

- `apps/focus_flow_flutter/pubspec.yaml` exists.
- The app can depend on scheduler public API packages through path dependencies.
- Root `pubspec.yaml` remains a Dart package workspace and does not list the Flutter app.

BREAKPOINT: Stop if creating the app would require changing root workspace semantics.

---

## Chunk 1.3 — Establish package-boundary guardrails

### Tasks

1. Add a small test or scriptable check in the Flutter app test suite that scans app `lib/` and `test/` files for forbidden imports.
2. Forbidden app imports include:
   - `package:scheduler_core/src/`
   - `package:scheduler_persistence_sqlite/`
   - `package:drift/`
   - `dart:io` for UI/runtime code in this slice,
   - notification desktop/platform implementation imports,
   - backup/export implementation imports.
3. Allow `package:scheduler_core/scheduler_core.dart`.
4. Document this check in the app README or implementation handoff.

### Acceptance criteria

- A failing forbidden import produces a clear test failure.
- The check does not require external tools beyond Flutter/Dart test execution.
- UI Plan 1 can proceed without touching core package internals.

---

## Chunk 1.4 — Create the high-level app file layout

### Suggested files

Create or reconcile this structure:

```text
apps/focus_flow_flutter/lib/
  main.dart
  app/focus_flow_app.dart
  app/demo_scheduler_composition.dart
  controllers/today_screen_controller.dart
  models/today_screen_models.dart
  theme/focus_flow_theme.dart
  theme/focus_flow_tokens.dart
  widgets/app_shell.dart
  widgets/sidebar.dart
  widgets/top_bar.dart
  widgets/required_banner.dart
  widgets/timeline/timeline_geometry.dart
  widgets/timeline/timeline_axis.dart
  widgets/timeline/timeline_view.dart
  widgets/timeline/task_timeline_card.dart
  widgets/timeline/reward_icon.dart
  widgets/timeline/difficulty_bars.dart
  widgets/task_selection_modal.dart
```

Exact names may differ if existing conventions are stronger, but preserve the architectural separation:

- composition/controller code outside widgets,
- theme/tokens centralized,
- timeline geometry isolated,
- reward/difficulty icons isolated,
- modal isolated.

### Acceptance criteria

- The file layout is understandable without opening every file.
- The widget tree does not own seed data.
- The controller/composition layer is the only place that knows how to query scheduler application state.

---

## Block acceptance criteria

- Flutter app target exists or is reconciled.
- App is outside the root Dart workspace.
- App dependency boundary is public and minimal.
- Forbidden-import check exists or is planned in a concrete test file.
- No backend package code is changed.
- Any inability to run Flutter tooling is explicitly noted.

## Validation after block

Run what is available:

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

If app code is not visual yet, tests may be minimal but should pass.

---

## Completed implementation

1. Read `AGENTS.md`, `Codex Documentation/README.md`, the full UI Plan 1
   summary/execution order, Blocks 01-06, and all clean/annotated mockups.
2. Verified `apps/focus_flow_flutter/` already exists in the working repo with
   Linux, macOS, and Windows desktop scaffolding.
3. Verified the root Dart workspace does not include the Flutter app.
4. Preserved the existing Flutter app package, local `scheduler_core` path
   dependency, lint setup, platform folders, and provisional test harness.
5. Routed the app entry through `lib/app/` facade files and added the
   UI Plan 1 high-level folders/files for app, controller, model, theme, shell,
   timeline, icon, and modal responsibilities.
6. Added `test/forbidden_imports_test.dart` to fail clearly on scheduler `src/`,
   SQLite/Drift, desktop notification, backup/export, and direct OS imports.
7. Replaced the app README starter text with Block 1 scope, boundary, and
   validation notes.

Implementation note:

- App directory state: `apps/focus_flow_flutter/` existed.
- Existing Flutter files preserved/replaced: package configuration, platform
  scaffolding, existing controllers/widgets, and tests were preserved; app entry
  imports were reconciled through the new `lib/app/` facade, and plan-oriented
  placeholder files were added for later blocks.
- Validation commands available: `scripts/bootstrap_dev.sh`, `flutter pub get`,
  `flutter analyze`, and `flutter test`.

## Verification

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