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

V1 Block 04 — Backlog and Quick Capture

Status: Planned

Purpose: Support low-friction task capture and a unified backlog/wishlist model.

Chunk 4.1 — Backlog model and filters

Recommended Codex level: medium

Status: Completed

Tasks:

Implement backlog-friendly task metadata:

• unified backlog storage/state
• filter tags or derived filters for inbox, pushed, critical missed, wishlist, stale, no reward set
• sorting keys for priority, reward vs effort, age, project, times pushed

Rules:

• Do not create separate hard backlog sections.
• Use unified backlog with filters/sorts.
• Do not preserve original schedule/order metadata when moved to backlog.

Acceptance criteria:

• Backlog tasks can be filtered by derived category.
• Moving to backlog clears active schedule placement.
• Tests verify original schedule order is not used to restore backlog items.

Execution notes:

• Added BacklogView as a read-only projection over the unified task list.
• Added derived backlog filters for inbox, pushed, critical missed, wishlist, stale, and no reward set.
• Added backlog sort keys for priority, reward vs effort, age, project, and times pushed.
• Added BacklogTag.wishlist metadata without creating separate hard backlog sections.
• Verified moving to backlog clears active schedule placement and backlog age sorting does not use original schedule order.
• dart analyze and dart test passed.

Chunk 4.2 — Quick capture defaults

Recommended Codex level: medium

Status: Completed

Tasks:

Implement quick capture creation rules:

• Title is required.
• Default destination is backlog.
• Priority defaults to medium.
• Reward defaults to notSet.
• Difficulty may default to notSet or medium depending on model decision.
• Project defaults to Inbox/Unsorted.
• Time can remain unset.

Acceptance criteria:

• Test: minimal quick capture creates backlog task.
• Test: neutral defaults are applied.
• Test: reward notSet is preserved distinctly.

Execution notes:

• Updated Task.quickCapture to require a non-empty title.
• Default quick capture destination remains backlog.
• Priority now defaults to PriorityLevel.medium.
• Reward defaults to RewardLevel.notSet and remains distinct from low reward.
• Difficulty defaults to DifficultyLevel.notSet.
• Project defaults to inbox, and time remains unset.
• Added tests for title validation and neutral defaults.
• dart analyze and dart test passed.

Chunk 4.3 — Quick capture schedule checkbox behavior

Recommended Codex level: high

Status: Completed

Tasks:

Implement behavior for Add to next available schedule slot:

• When unchecked, task enters backlog.
• When checked, optional scheduling fields become relevant:
  • duration
  • priority
  • reward
  • project
  • flexibility
• If duration is missing, return a validation result or use a documented default.
• Insert into soonest flexible slot using the scheduling engine.

Acceptance criteria:

• Test: unchecked quick capture goes to backlog.
• Test: checked quick capture with duration schedules into next available slot.
• Test: checked quick capture without required scheduling fields is handled predictably.

Execution notes:

• Added QuickCaptureRequest, QuickCaptureResult, QuickCaptureStatus, and QuickCaptureService.
• Unchecked quick capture creates a backlog task and does not invoke scheduling.
• Checked quick capture validates duration and flexibility before scheduling.
• Missing duration returns a validation result while preserving the captured backlog task.
• Checked quick capture with duration inserts into the next available flexible slot through SchedulingEngine.insertBacklogTaskIntoNextAvailableSlot.
• Added tests for unchecked backlog capture, checked scheduling, and checked validation behavior.
• dart analyze and dart test passed.

BREAKPOINT: Stop here. Confirm high mode before implementing scheduling integration.

Chunk 4.4 — Backlog staleness marker calculation

Recommended Codex level: low

Tasks:

Implement age/staleness calculation for backlog display:

• Green: 0–7 days by default.
• Blue: 8–30 days by default.
• Purple: 31+ days by default.
• Thresholds must be configurable constants/settings model, not hardcoded everywhere.
• No automatic prompts per stale task.

Acceptance criteria:

• Tests cover fresh, aging, stale, and configurable thresholds.

Commit suggestion:

feat(backlog): add unified backlog and quick capture rules