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

# UI Plan 2 Block 08 — Commands, New Task, Create/Edit Metadata, and Drawer Actions

**Goal:** Wire the Backlog tab’s visible actions to application commands while preserving backend/domain authority.

---

## Block outcome

After this block, `New Task`, `Add task`, `Schedule`, `Break Up`, `Push to Someday`, `Remove`, and metadata edits are either implemented through application commands or explicitly left as safe non-mutating placeholders with tests and TODO notes.

---

## Chunk 8.1 — Add/update task metadata command

### Tasks

Add an application command/use case such as `updateBacklogTaskDetails` or general `updateTaskDetails`.

Input fields:

- task id,
- expected updated timestamp/revision if available,
- title,
- notes,
- project id,
- duration minutes,
- priority,
- reward,
- difficulty,
- tags,
- backlog tags.

Behavior:

- Validate task exists.
- Validate stale update guard using existing `expectedUpdatedAt` style or repository revision style.
- Preserve schedule/source-of-truth rules.
- For backlog tasks, metadata changes should not schedule the task.
- For planned tasks, do not use this command from Backlog UI.

### Acceptance criteria

- Metadata update command is tested.
- Notes/tags/project edits persist through repository layer.
- Flutter calls command controller, not repositories.

---

## Chunk 8.2 — New Task drawer/create flow

### Tasks

Implement reusable task editor drawer/sheet for Backlog create mode.

Open from:

- top `+ New Task`,
- column header add icon,
- column footer `+ Add task`.

Fields:

- title required,
- notes optional,
- project optional/default Inbox or selected bucket/project default,
- duration optional,
- priority default Medium,
- reward optional/not set,
- difficulty optional/not set,
- tags optional.

Behavior:

- Create through `quickCaptureToBacklog` or a new richer create command if notes/tags are required.
- Do not force scheduling.
- On success:
  - close create drawer,
  - refresh Backlog board,
  - show quiet success text if existing command banner pattern supports it.
- Empty title validation stays inline and preserves input.

### Acceptance criteria

- `New Task` creates a backlog task.
- Column Add Task can preselect or hint bucket defaults without writing a fake bucket field.
- Created task appears in board after refresh according to bucket policy.

---

## Chunk 8.3 — Schedule selected backlog task

### Tasks

Wire drawer `Schedule` to existing command:

```dart
scheduleBacklogItem(
  taskId: selectedTaskId,
  durationMinutes: optionalDurationIfEdited,
  expectedUpdatedAt: selectedUpdatedAt,
)
```

Behavior:

- If duration is missing, focus/show duration requirement instead of discarding task.
- If scheduling succeeds:
  - task leaves Backlog board if its status changes to planned,
  - drawer closes,
  - summary and counts refresh,
  - command status shows calm success.
- If no fit/conflict:
  - keep task in Backlog,
  - show drawer-local or command-banner explanation.

### Acceptance criteria

- UI does not choose canonical time slot by itself.
- Schedule command handles stale updates.
- Tests verify success callback and failure display with fake command controller.

---

## Chunk 8.4 — Break Up flow

### Tasks

Use existing `breakUpTask` command if possible.

Minimum V1 UI:

- Pressing `Break Up` opens a focused child-task drawer/dialog.
- User can add at least two child rows with title and optional duration.
- Saving calls `breakUpTask` with `ApplicationChildTaskDraft` entries.
- On success:
  - refresh board,
  - selected detail updates or drawer closes,
  - child previews appear under parent.

If full child-entry UI is too large for this plan, implement a safe placeholder that opens a drawer-local message: `Break-up flow is coming next` and do not mutate state. Only use placeholder if Ashley approves at breakpoint.

### Acceptance criteria

- No child tasks are created in Flutter-only state.
- Break-up command path is covered by tests if implemented.

BREAKPOINT: Stop before using a placeholder for Break Up. Ask Ashley whether to include full child-entry UI now or defer.

---

## Chunk 8.5 — Push to Someday command

### Tasks

Add/wire application command such as `pushBacklogTaskToSomeday`.

Behavior:

- Task remains backlog.
- Add `BacklogTag.wishlist` or equivalent someday metadata.
- Clear any selected scheduling preview if needed.
- Refresh board so task appears in `Not Now`.
- Record task activity/statistics if existing lifecycle service supports it.

### Acceptance criteria

- Command is tested.
- It is non-destructive.
- It does not schedule or delete the task.
- UI refreshes board and drawer content.

---

## Chunk 8.6 — Remove/archive command

### Tasks

Add/wire application command such as `removeBacklogTask`.

Assumed behavior:

- non-destructive archive from active backlog,
- prefer `TaskStatus.noLongerRelevant` unless repo conventions define `cancelled` or a separate archive flag,
- require confirmation before applying,
- close drawer on success,
- refresh board/summary.

Confirmation copy:

- Title: `Remove from Backlog?`
- Body: `This hides the task from active planning. It will not schedule anything.`
- Actions: `Cancel`, `Remove`.

### Acceptance criteria

- Remove does not physically delete repository data unless Ashley explicitly changed the product decision.
- User can cancel confirmation.
- Success refreshes the board.

---

## Chunk 8.7 — Project and tags inline edits

### Tasks

Once update command exists:

- Project dropdown updates project id.
- Tag add button opens small input or menu.
- Tag chip can be removed if design supports it.
- Use optimistic UI only if command result can reconcile cleanly; otherwise reload after save.

If inline autosave feels too chatty, use a small `Save changes` action inside the drawer only when fields are dirty. The mockup does not show a save button, so prefer careful inline save with visible running/success/failure states.

### Acceptance criteria

- Project/tags update through command controller.
- Stale/failure result is visible and does not lose local input.
- Tests cover project/tag command callback.

---

## Chunk 8.8 — Command state feedback

### Tasks

Add a Backlog command status pattern:

- running state near top controls or drawer action area,
- success state quiet and auto-dismissable if existing app pattern supports it,
- failure state calm and specific.

Messages:

- `Added to Backlog.`
- `Scheduled.`
- `Kept in Backlog — no fitting slot found.`
- `Moved to Someday.`
- `Removed from active Backlog.`

### Acceptance criteria

- Failures do not crash screen.
- User input is not lost on validation failure.
- Command controller reloads board on success.

---

## Block acceptance criteria

- Visible Backlog actions either work through application commands or have explicit Ashley-approved deferral.
- Create/schedule/someday/remove paths are implemented and tested.
- Break Up is implemented or explicitly deferred at its breakpoint.
- No Flutter widget mutates domain state directly.

## Validation after block

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