HouseHoldKeaper/.planning/phases/11-issue-3-tasks-management-allow-task-checking-anytime-and-pre-populate-recurring-tasks/11-CONTEXT.md

Phase 11: Tasks Management - Context

Gathered: 2026-03-24 Status: Ready for planning

## Phase Boundary

Two behavioral changes to task scheduling: (1) Allow users to mark tasks as done on any day, not just the scheduled due day — removing the current future-date checkbox disable. (2) Pre-populate recurring tasks so they appear on every applicable day within their interval window, not just after completing the previous occurrence. No new screens, no new task types, no changes to the notification system.

## Implementation Decisions

Anytime task completion

• D-01: Remove the isFuture / canComplete restrictions in calendar_day_list.dart, calendar_task_row.dart, and task_row.dart — checkboxes always enabled
• D-02: When completing a task on a non-due day, recalculate nextDueDate from today (not from the original due date) — matches user mental model: "I did it now, schedule next from now"
• D-03: The existing completeTask() in tasks_dao.dart already works for any date — no DAO changes needed for completion logic itself, only ensure calculateNextDueDate uses today as the base when called from a non-due-day completion

Pre-population strategy

• D-04: Use query-time virtual instances in the provider layer — no schema migration, no future DB rows generated
• D-05: In calendarDayProvider, fetch all active recurring tasks and determine which ones "should" appear on the selected date based on their interval pattern and nextDueDate/anchorDay
• D-06: A weekly task shows on every occurrence of its weekday within the calendar range (e.g., every Monday); a monthly task shows on the anchor day of each month; daily tasks show every day
• D-07: Show pre-populated tasks only within the current interval window — a weekly task due Monday shows on all 7 days leading up to that Monday, not indefinitely into the future. Once nextDueDate passes and the task becomes overdue, it follows existing overdue carry-over behavior.

Completion of pre-populated tasks

• D-08: When a user completes a pre-populated (virtual) task instance, it calls the same completeTask() flow — records completion, recalculates nextDueDate from today
• D-09: Hide tasks that have already been completed in the current interval period from the pre-populated view — check task_completions for a completion within the current period window
• D-10: A task that was completed earlier this period should not reappear on remaining days of that period

Visual differentiation

• D-11: Pre-populated tasks that aren't yet due (i.e., nextDueDate is in the future but they appear because of pre-population) should have a subtle visual distinction — lighter opacity or muted text color to indicate "upcoming, not yet due"
• D-12: Tasks on their actual due date appear with full styling (existing behavior)
• D-13: Overdue tasks keep their existing red/orange accent (existing behavior, no change)

Claude's Discretion

• Exact opacity/color values for pre-populated task visual distinction
• Whether to add a new DAO method for period-completion-check or handle it in the provider
• Performance optimization strategy for virtual instance generation
• How to handle edge cases where interval window spans month boundaries with anchor day clamping

<canonical_refs>

Canonical References

Downstream agents MUST read these before planning or implementing.

No external specs — requirements are fully captured in decisions above and in Gitea Issue #3.

Source issue

• Gitea Issue #3: "Tasks Management" — Original requirements: (1) allow task checking all the time, (2) pre-populate tasks not just when completed

Key implementation files

• lib/features/home/data/calendar_dao.dart — Current date-based filtering queries (main modification target)
• lib/features/home/presentation/calendar_providers.dart — Provider orchestration, calendarDayProvider (pre-population logic goes here)
• lib/features/home/presentation/calendar_day_list.dart — UI rendering with canComplete restrictions
• lib/features/home/presentation/calendar_task_row.dart — Task row checkbox disable logic
• lib/features/tasks/data/tasks_dao.dart — completeTask() method, completion recording
• lib/features/tasks/presentation/task_row.dart — Task list view checkbox disable logic
• lib/features/tasks/domain/scheduling.dart — calculateNextDueDate(), interval arithmetic

</canonical_refs>

<code_context>

Existing Code Insights

Reusable Assets

• TasksDao.completeTask(): Already date-agnostic, handles completion recording and next-due-date calculation — no changes needed
• calculateNextDueDate() in scheduling.dart: Handles all interval types with anchor day support — reuse for period window calculation
• catchUpToPresent() in scheduling.dart: Already handles skipping past missed dates — relevant for non-due-day completion
• CalendarDayState model: Already has dayTasks + overdueTasks lists — can add prePopolatedTasks or merge into dayTasks
• isActive filter: Already in all calendar queries from Phase 8 — pre-populated queries must also respect this

Established Patterns

• Riverpod StreamProvider for reactive DAO → UI data flow
• stream.map() for in-memory sorting after DB emit (Phase 7 sort pattern)
• CalendarDayState as combined state object for calendar view
• TaskWithRoom join result type used throughout calendar layer

Integration Points

• calendar_dao.dart: New query needed — watchAllActiveRecurringTasks() to fetch all active tasks for pre-population logic
• calendar_providers.dart: calendarDayProvider needs rewrite to combine due-today tasks + pre-populated virtual tasks + overdue tasks
• calendar_day_list.dart: Remove canComplete: !isFuture (line ~271), add visual distinction for pre-populated tasks
• calendar_task_row.dart: Remove checkbox disable condition, add optional isPrePopulated prop for visual styling
• task_row.dart: Remove isFuture checkbox disable (lines ~60-61)
• daily_plan_dao.dart: Notification count queries may need updating to include pre-populated tasks in the daily summary count

</code_context>

## Specific Ideas

• User wants tasks to be visible and completable regardless of schedule — remove friction
• Weekly tasks should show every week, not just after the last completion — the app should feel like a consistent weekly checklist
• The current behavior where tasks disappear after completion and only reappear on the next due date is confusing for the user
• Keep it simple — Phase 8 and 9 both confirmed user prefers minimal, straightforward UX

## Deferred Ideas

None — discussion stayed within phase scope

---

Phase: 11-issue-3-tasks-management-allow-task-checking-anytime-and-pre-populate-recurring-tasks Context gathered: 2026-03-24