focus-flow/Codex Documentation/Current Software Plan/V1_BLOCK_06_Task_Actions_State_Transitions.md

V1 Block 06 — Task Actions and State Transitions

Status: Planned

Purpose: Define and implement the safe, low-friction actions available from task cards.

Chunk 6.1 — Flexible task quick actions

Recommended Codex level: medium

Status: Completed

Tasks:

Support these quick actions for flexible task cards:

• Done
• Push
• Backlog
• Break up

Rules:

• Done marks completed.
• Push opens simple push destinations.
• Backlog moves to unified backlog and does not preserve original schedule order.
• Break up starts child task flow; full implementation in Block 07.

Acceptance criteria:

• Tests cover done and backlog state transitions.
• Push destination selection is represented in domain layer.

Execution notes:

• Added FlexibleTaskActionService for flexible card quick actions.
• Added FlexibleTaskQuickAction and PushDestination domain enums.
• Done marks a flexible task completed without changing its schedule placement.
• Backlog uses the scheduling engine backlog transition and clears schedule placement.
• Push returns explicit domain destinations: next available slot, tomorrow/top of queue, and backlog.
• Break up returns an explicit child-task-flow intent without creating children yet.
• Added tests for done, backlog, push destination representation, and break-up flow intent.
• dart format lib test, dart analyze, dart test, and git diff --check passed.

Chunk 6.2 — Push destination behavior

Recommended Codex level: high

Status: Completed

Tasks:

Implement push destinations:

• Next available slot.
• Tomorrow/top of queue.
• Backlog.

Explicitly exclude:

• Later today.

Acceptance criteria:

• Test: next available uses scheduling engine.
• Test: tomorrow sets tomorrow/top-of-queue metadata.
• Test: backlog clears schedule placement.

Execution notes:

• Added PushDestinationResult to carry selected destination metadata with the scheduling result.
• Added FlexibleTaskActionService.applyPushDestination.
• Next available delegates to SchedulingEngine.pushFlexibleTaskToNextAvailableSlot.
• Tomorrow/top-of-queue delegates to SchedulingEngine.pushFlexibleTaskToTomorrowTopOfQueue and reports placesAtTomorrowTopOfQueue.
• Backlog destination updates the task list with SchedulingEngine.moveToBacklog, clears placement, and records a scheduling change.
• PushDestination remains limited to next available slot, tomorrow/top of queue, and backlog; later today is not represented.
• Added tests for next available, tomorrow/top-of-queue metadata, backlog clearing schedule placement, and the excluded later-today destination.
• dart format lib test, dart analyze, dart test, and git diff --check passed.

BREAKPOINT: Stop here. Confirm high mode before integrating push behavior.

Chunk 6.3 — Required task states

Recommended Codex level: medium

Tasks:

Implement required task state meanings:

• Done: completed.
• Missed: did not happen; visible as missed but not aggressively styled.
• Cancel: did not/will not happen; remove from active plan.
• No longer relevant: separate from cancelled.

Rules:

• Critical missed tasks move to backlog.
• Required/inflexible missed tasks remain in place/history and are marked missed.
• Cancelled and noLongerRelevant are distinct statuses.

Acceptance criteria:

• Tests cover critical missed to backlog.
• Tests cover inflexible missed stays in schedule/history.
• Tests cover cancelled vs noLongerRelevant distinction.

Chunk 6.4 — Surprise task logging

Recommended Codex level: high

Tasks:

Implement I did something unplanned behavior:

• Create surprise completed task.
• Optional fields: time used, project, reward, priority.
• Surprise task occupies the time it happened.
• Flexible tasks in that time are pushed using normal rules.
• Inflexible/critical/locked blocks are not moved.
• Inflexible/critical overlaps are reported.
• Locked overlaps remain hidden by default unless reveal mode exists.

Acceptance criteria:

• Test: surprise task creates completed task.
• Test: overlapping flexible task is pushed.
• Test: overlapping inflexible/critical task is reported, not moved.
• Test: locked overlap can be tracked without rendering as task.

Commit suggestion:

feat(tasks): implement core task actions and transitions