diff --git a/.planning/MILESTONES.md b/.planning/MILESTONES.md new file mode 100644 index 0000000..1f4f502 --- /dev/null +++ b/.planning/MILESTONES.md @@ -0,0 +1,20 @@ +# Milestones + +## v1.0 MVP (Shipped: 2026-03-16) + +**Phases completed:** 4 phases, 13 plans +**Codebase:** 10,588 LOC Dart (7,773 lib + 2,815 test), 89 tests, 76 commits +**Timeline:** 2 days (2026-03-15 to 2026-03-16) + +**Key accomplishments:** +1. Flutter project with Drift SQLite, Riverpod 3 state management, ARB localization, and calm sage & stone Material 3 theme +2. Full room CRUD with drag-and-drop reorder, icon picker, and cleanliness indicator per room card +3. Task CRUD with 11 frequency presets + custom intervals, calendar-anchored scheduling with anchor memory, and auto-calculated next due dates +4. Bundled German-language task templates for 14 room types with post-creation template picker +5. Daily plan home screen with overdue/today/tomorrow sections, animated checkbox completion, and progress tracking +6. Daily summary notification with configurable time, POST_NOTIFICATIONS permission handling, and boot receiver rescheduling + +**Archive:** See `milestones/v1.0-ROADMAP.md` and `milestones/v1.0-REQUIREMENTS.md` + +--- + diff --git a/.planning/PROJECT.md b/.planning/PROJECT.md index 100d4c5..c266ca5 100644 --- a/.planning/PROJECT.md +++ b/.planning/PROJECT.md @@ -2,7 +2,7 @@ ## What This Is -A local-first Flutter app for organizing household chores and one-time projects, built for personal/couple use on Android. Takes the room-based task scheduling model (inspired by BeTidy), strips cloud/account/social features, and wraps it in a calm, minimal Material 3 UI. Fully offline, free, privacy-respecting — all data stays on-device. +A local-first Flutter app for organizing household chores, built for personal/couple use on Android. Uses a room-based task scheduling model where users create rooms, add recurring tasks with frequency intervals, and the app auto-calculates the next due date after each completion. Features a daily plan home screen, bundled German-language task templates, room cleanliness indicators, and daily summary notifications. Fully offline, free, privacy-respecting — all data stays on-device. ## Core Value @@ -12,20 +12,22 @@ Users can see what needs doing today, mark it done, and trust the app to schedul ### Validated -(None yet — ship to validate) +- Room CRUD with icons and drag-and-drop reorder — v1.0 +- Task CRUD with frequency intervals and due date calculation — v1.0 +- Daily plan view with overdue/today/upcoming sections — v1.0 +- Task completion with auto-scheduling of next due date — v1.0 +- Bundled task templates per room type (German only, 14 room types) — v1.0 +- Daily summary notification with configurable time — v1.0 +- Light/dark theme with calm Material 3 palette — v1.0 +- Cleanliness indicator per room (based on overdue vs on-time) — v1.0 ### Active -- [ ] Room CRUD with icons and optional photos -- [ ] Task CRUD with frequency intervals and due date calculation -- [ ] Daily plan view with overdue/today/upcoming sections -- [ ] Task completion with auto-scheduling of next due date -- [ ] Bundled task templates per room type (German only) -- [ ] Daily summary notification -- [ ] Light/dark theme with calm Material 3 palette -- [ ] Cleanliness indicator per room (based on overdue vs on-time) -- [ ] Task sorting (due date, alphabetical, interval, effort) -- [ ] Task history (completion log per task) +- [ ] Data export/import (JSON) +- [ ] English localization +- [ ] Room cover photos from camera or gallery +- [ ] Task completion history log +- [ ] Additional task sorting (alphabetical, interval, effort) ### Out of Scope @@ -34,8 +36,9 @@ Users can see what needs doing today, mark it done, and trust the app to schedul - Subscription model / in-app purchases — free forever - Family profile sharing across devices — single-device app - Server-side infrastructure — zero backend -- Data export/import (JSON) — deferred to v1.1 -- English localization — deferred to v1.1 (ship German-only MVP) +- AI-powered task suggestions — overkill for curated templates +- Per-task push notifications — daily summary is more effective +- Firebase or any Google cloud services — contradicts local-first design - Real-time cross-device sync — potential future self-hosted feature - Tablet-optimized layout — future enhancement - Statistics & insights dashboard — v2.0 @@ -44,11 +47,11 @@ Users can see what needs doing today, mark it done, and trust the app to schedul ## Context -- Inspired by BeTidy (iOS/Android household cleaning app) — taking the proven room-based model, removing cloud/social, refining the UI +- Shipped v1.0 MVP with 10,588 LOC Dart (7,773 lib + 2,815 test), 89 tests +- Tech stack: Flutter + Dart, Riverpod 3 + code generation, Drift 2.31 SQLite, GoRouter, flutter_local_notifications +- Inspired by BeTidy (iOS/Android household cleaning app) — room-based model, no cloud/social - Built for personal use with partner on a shared Android device; may publish publicly later -- Code and comments in English; UI strings German-only for MVP -- Room photos are nice-to-have for MVP — icon-only rooms are sufficient initially -- Developer is new to Drift (SQLite ORM) — plan should account for learning curve +- Code and comments in English; UI strings German-only for v1.0 - Gitea (self-hosted on Hetzner) for version control; no CI/CD pipeline yet ## Constraints @@ -57,20 +60,23 @@ Users can see what needs doing today, mark it done, and trust the app to schedul - **Platform**: Android-first (iOS later) - **Offline**: 100% offline-capable, zero network dependencies - **Privacy**: No data leaves the device, no analytics, no tracking -- **Language**: German-only UI for MVP, English code/comments +- **Language**: German-only UI for v1.0, English code/comments - **No CI**: No automated build pipeline initially ## Key Decisions | Decision | Rationale | Outcome | |----------|-----------|---------| -| Riverpod over Bloc | Modern, compile-safe, less boilerplate, Dart-native | — Pending | -| Drift over raw sqflite | Type-safe queries, compile-time validation, migration support | — Pending | -| Android-first | Primary device is Android; iOS follows | — Pending | -| German-only MVP | Primary user language; defer localization infrastructure | — Pending | -| No CI initially | Keep scope focused on the app itself | — Pending | -| Calm Material 3 palette | Muted greens, warm grays, gentle blues — calm productivity, not playful | — Pending | -| Clean Architecture | Feature-based folder structure with data/domain/presentation layers | — Pending | +| Riverpod 3 over Bloc | Modern, compile-safe, less boilerplate, Dart-native | Good — code generation works well, @riverpod annotation reduces boilerplate | +| Drift over raw sqflite | Type-safe queries, compile-time validation, migration support | Good — DAOs with stream queries provide reactive UI, migration workflow established | +| Android-first | Primary device is Android; iOS follows | Good — no iOS-specific issues encountered | +| German-only MVP | Primary user language; defer localization infrastructure | Good — ARB localization infrastructure in place from Phase 1, ready for English | +| No CI initially | Keep scope focused on the app itself | Good — manual dart analyze + flutter test sufficient for solo dev | +| Calm Material 3 palette | Muted greens, warm grays, gentle blues — calm productivity | Good — sage & stone theme (seed 0xFF7A9A6D) with warm charcoal dark mode | +| Clean Architecture | Feature-based folder structure with data/domain/presentation layers | Good — clear separation, easy to navigate | +| Calendar-anchored scheduling | Monthly/quarterly/yearly tasks anchor to original day-of-month with clamping | Good — handles Feb 28/31 edge cases correctly with anchor memory | +| flutter_local_notifications v21 | Standard Flutter notification package, TZ-aware scheduling | Good — inexactAllowWhileIdle avoids SCHEDULE_EXACT_ALARM complexity | +| Manual StreamProvider for drift types | riverpod_generator throws InvalidTypeException with drift Task type | Revisit — may be fixed in future riverpod_generator versions | --- -*Last updated: 2026-03-15 after initialization* +*Last updated: 2026-03-16 after v1.0 milestone* diff --git a/.planning/RETROSPECTIVE.md b/.planning/RETROSPECTIVE.md new file mode 100644 index 0000000..f440648 --- /dev/null +++ b/.planning/RETROSPECTIVE.md @@ -0,0 +1,65 @@ +# Project Retrospective + +*A living document updated after each milestone. Lessons feed forward into future planning.* + +## Milestone: v1.0 — MVP + +**Shipped:** 2026-03-16 +**Phases:** 4 | **Plans:** 13 + +### What Was Built +- Complete room-based household chore app with auto-scheduling task management +- Daily plan home screen with overdue/today/tomorrow sections and progress tracking +- Bundled German task templates for 14 room types +- Daily summary notifications with configurable time and Android permission handling +- 89 tests covering DAOs, scheduling logic, providers, and widget behavior + +### What Worked +- Bottom-up phase structure (foundation -> data -> UI -> polish) kept each phase clean with minimal rework +- TDD approach for providers and services caught several issues early (async race conditions, API mismatches) +- Verification gates at the end of Phase 2, 3, and 4 confirmed all requirements before moving on +- Calendar-anchored scheduling with anchor memory was designed right the first time — no rework needed +- ARB localization from Phase 1 meant adding German strings was frictionless throughout + +### What Was Inefficient +- riverpod_generator InvalidTypeException with drift Task type required workaround (manual StreamProvider) in 3 separate plans — should have been caught in Phase 1 research +- Some plan specifications referenced outdated API patterns (flutter_local_notifications positional parameters removed in v20+) — research needs to verify exact current API signatures +- Phase 4 plan checkboxes in ROADMAP.md weren't updated to [x] by executor — minor bookkeeping gap + +### Patterns Established +- `@Riverpod(keepAlive: true)` AsyncNotifier with SharedPreferences for persistent settings (ThemeNotifier, NotificationSettingsNotifier) +- Manual StreamProvider.family/autoDispose for drift type compatibility +- DailyPlanDao innerJoin pattern for cross-table queries +- ConsumerStatefulWidget for screens with async callbacks requiring `mounted` guards +- Provider override pattern in widget tests for database isolation + +### Key Lessons +1. Research phase should verify exact current package API signatures — breaking changes between major versions cause plan deviations +2. Drift + riverpod_generator type incompatibility is a known issue — plan for manual providers from the start when using drift +3. Verification gates add minimal time (~2 min) but catch integration issues — keep them for all phases +4. Progressive disclosure (AnimatedSize) is a clean pattern for conditional settings UI + +### Cost Observations +- Model mix: orchestrator on opus, researchers/planners/executors/checkers on sonnet +- Total execution: ~1.3 hours for 13 plans across 4 phases +- Notable: Verification gates averaged 2 min — very efficient for the confidence they provide + +--- + +## Cross-Milestone Trends + +### Process Evolution + +| Milestone | Phases | Plans | Key Change | +|-----------|--------|-------|------------| +| v1.0 | 4 | 13 | Initial project — established all patterns | + +### Cumulative Quality + +| Milestone | Tests | Key Metric | +|-----------|-------|------------| +| v1.0 | 89 | dart analyze clean, 0 issues | + +### Top Lessons (Verified Across Milestones) + +1. (Single milestone — lessons above will be cross-validated as more milestones ship) diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index e2620a3..8aa747c 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -1,100 +1,28 @@ # Roadmap: HouseHoldKeaper -## Overview +## Milestones -Four phases build the app bottom-up along its natural dependency chain. Phase 1 lays the technical foundation every subsequent phase relies on. Phase 2 delivers complete room and task management — the core scheduling loop. Phase 3 surfaces that data as the daily plan view (the primary user experience) and adds the cleanliness indicator. Phase 4 adds notifications and completes the v1 feature set. After Phase 3, the app is usable daily. After Phase 4, it is releasable. +- **v1.0 MVP** — Phases 1-4 (shipped 2026-03-16) ## Phases -**Phase Numbering:** -- Integer phases (1, 2, 3): Planned milestone work -- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED) +
+v1.0 MVP (Phases 1-4) — SHIPPED 2026-03-16 -Decimal phases appear between their surrounding integers in numeric order. +- [x] Phase 1: Foundation (2/2 plans) — completed 2026-03-15 +- [x] Phase 2: Rooms and Tasks (5/5 plans) — completed 2026-03-15 +- [x] Phase 3: Daily Plan and Cleanliness (3/3 plans) — completed 2026-03-16 +- [x] Phase 4: Notifications (3/3 plans) — completed 2026-03-16 -- [x] **Phase 1: Foundation** - Project scaffold, database, state management, theme, and localization infrastructure (completed 2026-03-15) -- [x] **Phase 2: Rooms and Tasks** - Complete room CRUD, task CRUD with auto-scheduling, and bundled templates (completed 2026-03-15) -- [x] **Phase 3: Daily Plan and Cleanliness** - Primary daily plan screen with overdue/today/upcoming, cleanliness indicators per room (completed 2026-03-16) -- [x] **Phase 4: Notifications** - Daily summary notification with configurable time and Android permission handling (completed 2026-03-16) +See `milestones/v1.0-ROADMAP.md` for full phase details. -## Phase Details - -### Phase 1: Foundation -**Goal**: The app compiles, opens, and enforces correct architecture patterns — ready to receive features without accumulating technical debt -**Depends on**: Nothing (first phase) -**Requirements**: FOUND-01, FOUND-02, FOUND-03, FOUND-04, THEME-01, THEME-02 -**Success Criteria** (what must be TRUE): - 1. App launches on Android without errors and shows a bottom navigation bar with Home, Rooms, and Settings tabs - 2. Light and dark themes work correctly and follow the system setting by default, using the calm Material 3 palette (muted greens, warm grays, gentle blues) - 3. All UI strings are loaded from ARB localization files — no hardcoded German text in Dart code - 4. The Drift database opens on first launch with schemaVersion 1 and the migration workflow is established (drift_dev make-migrations runs without errors) - 5. riverpod_lint is active and flags ref.watch usage outside build() as an analysis error -**Plans**: 2 plans -Plans: -- [x] 01-01-PLAN.md — Scaffold Flutter project and build core infrastructure (database, providers, theme, localization) -- [x] 01-02-PLAN.md — Navigation shell, placeholder screens, Settings, and full app wiring - -### Phase 2: Rooms and Tasks -**Goal**: Users can create and manage rooms and tasks, mark tasks done, and trust the app to schedule the next occurrence automatically -**Depends on**: Phase 1 -**Requirements**: ROOM-01, ROOM-02, ROOM-03, ROOM-04, ROOM-05, TASK-01, TASK-02, TASK-03, TASK-04, TASK-05, TASK-06, TASK-07, TASK-08, TMPL-01, TMPL-02 -**Success Criteria** (what must be TRUE): - 1. User can create a room with a name and icon, edit it, reorder rooms via drag-and-drop, and delete it (with confirmation that removes all associated tasks) - 2. User can create a task in a room with name, description, frequency interval (daily through yearly and custom), and effort level; tasks can be edited and deleted with confirmation - 3. When creating a room, user can select from bundled German-language task templates for the chosen room type (all 14 room types covered) and they are added to the room as tasks - 4. User can mark a task done (tap or swipe), which records the completion and sets the next due date correctly based on the interval - 5. Overdue tasks are visually highlighted with a distinct color or badge on room cards and in task lists; tasks within a room are sorted by due date by default - 6. Each room card shows its name, icon, count of due tasks, and cleanliness indicator -**Plans**: 5 plans -Plans: -- [x] 02-01-PLAN.md — Data layer: Drift tables, migration v1->v2, DAOs, scheduling utility, domain models, templates, tests -- [x] 02-02-PLAN.md — Room CRUD UI: 2-column card grid, room form, icon picker, drag-and-drop reorder, providers -- [x] 02-03-PLAN.md — Task CRUD UI: task list, task row with completion, task form, overdue highlighting, providers -- [x] 02-04-PLAN.md — Template selection: template picker bottom sheet, room type detection, integration with room creation -- [x] 02-05-PLAN.md — Visual and functional verification checkpoint - -### Phase 3: Daily Plan and Cleanliness -**Goal**: Users can open the app and immediately see what needs doing today, act on tasks directly from the plan view, and see a room-level health indicator -**Depends on**: Phase 2 -**Requirements**: PLAN-01, PLAN-02, PLAN-03, PLAN-04, PLAN-05, PLAN-06, CLEAN-01 -**Success Criteria** (what must be TRUE): - 1. The Home tab shows today's tasks grouped by room, with a separate highlighted section at the top for overdue tasks - 2. User can mark a task done directly from the daily plan view via swipe or checkbox without navigating to the room - 3. User can see upcoming tasks (tomorrow and this week) from the daily plan screen - 4. A progress indicator shows completed vs total tasks for today (e.g., "5 von 12 erledigt") - 5. When no tasks are due, an encouraging "all clear" empty state is shown instead of an empty list - 6. Each room card displays a cleanliness indicator derived from the ratio of overdue tasks to total tasks in that room -**Plans**: 3 plans -Plans: -- [x] 03-01-PLAN.md — Data layer: DailyPlanDao with cross-room join query, providers, and localization keys -- [x] 03-02-PLAN.md — Daily plan UI: HomeScreen rewrite with progress card, task sections, animated completion, empty state -- [x] 03-03-PLAN.md — Visual and functional verification checkpoint - -### Phase 4: Notifications -**Goal**: Users receive a daily summary notification reminding them of today's task count, and can control notification behavior from settings -**Depends on**: Phase 2 -**Requirements**: NOTF-01, NOTF-02 -**Success Criteria** (what must be TRUE): - 1. User receives one daily notification showing the count of tasks due today, scheduled at a configurable time - 2. User can enable or disable notifications from the Settings tab, and the change takes effect immediately - 3. Notifications are correctly rescheduled after device reboot (RECEIVE_BOOT_COMPLETED receiver active) - 4. On Android API 33+, the app requests POST_NOTIFICATIONS permission at the appropriate moment and degrades gracefully if denied -**Plans**: 3 plans -Plans: -- [ ] 04-01-PLAN.md — Infrastructure: packages, Android config, NotificationService, NotificationSettingsNotifier, DAO queries, timezone init, tests -- [ ] 04-02-PLAN.md — Settings UI: Benachrichtigungen section with toggle, time picker, permission flow, scheduling wiring, tests -- [ ] 04-03-PLAN.md — Verification gate: dart analyze + full test suite + requirement confirmation +
## Progress -**Execution Order:** -Phases execute in numeric order: 1 -> 2 -> 3 -> 4 - -Note: Phase 4 depends on Phase 2 (needs scheduling data) but can be developed in parallel with Phase 3. - -| Phase | Plans Complete | Status | Completed | -|-------|----------------|--------|-----------| -| 1. Foundation | 2/2 | Complete | 2026-03-15 | -| 2. Rooms and Tasks | 5/5 | Complete | 2026-03-15 | -| 3. Daily Plan and Cleanliness | 3/3 | Complete | 2026-03-16 | -| 4. Notifications | 3/3 | Complete | 2026-03-16 | +| Phase | Milestone | Plans Complete | Status | Completed | +|-------|-----------|----------------|--------|-----------| +| 1. Foundation | v1.0 | 2/2 | Complete | 2026-03-15 | +| 2. Rooms and Tasks | v1.0 | 5/5 | Complete | 2026-03-15 | +| 3. Daily Plan and Cleanliness | v1.0 | 3/3 | Complete | 2026-03-16 | +| 4. Notifications | v1.0 | 3/3 | Complete | 2026-03-16 | diff --git a/.planning/STATE.md b/.planning/STATE.md index dafc589..dc8e83f 100644 --- a/.planning/STATE.md +++ b/.planning/STATE.md @@ -1,11 +1,11 @@ --- gsd_state_version: 1.0 milestone: v1.0 -milestone_name: milestone -status: executing -stopped_at: Completed 04-03-PLAN.md (Phase 4 Verification Gate) -last_updated: "2026-03-16T14:20:25.850Z" -last_activity: 2026-03-16 — Completed 04-01-PLAN.md (Notification infrastructure) +milestone_name: MVP +status: shipped +stopped_at: v1.0 milestone complete +last_updated: "2026-03-16T20:00:00.000Z" +last_activity: 2026-03-16 — v1.0 MVP milestone shipped progress: total_phases: 4 completed_phases: 4 @@ -18,26 +18,25 @@ progress: ## Project Reference -See: .planning/PROJECT.md (updated 2026-03-15) +See: .planning/PROJECT.md (updated 2026-03-16) **Core value:** Users can see what needs doing today, mark it done, and trust the app to schedule the next occurrence — without thinking about it. -**Current focus:** Phase 4: Notifications (Phase 3 complete) +**Current focus:** v1.0 shipped — planning next milestone ## Current Position -Phase: 4 of 4 (Notifications) -Plan: 1 of 2 in current phase -- COMPLETE -Status: Phase 4 in progress — plan 1 complete, plan 2 (Settings UI) pending -Last activity: 2026-03-16 — Completed 04-01-PLAN.md (Notification infrastructure) +Milestone: v1.0 MVP — SHIPPED 2026-03-16 +Status: All 4 phases complete, 13/13 plans executed, 89 tests passing +Next: `/gsd:new-milestone` for v1.1 -Progress: [██████████] 100% +Progress: [##########] 100% ## Performance Metrics **Velocity:** -- Total plans completed: 10 -- Average duration: 6.1 min -- Total execution time: 1.0 hours +- Total plans completed: 13 +- Total execution time: ~1.3 hours +- Average duration: ~6 min/plan **By Phase:** @@ -46,85 +45,24 @@ Progress: [██████████] 100% | 1 - Foundation | 2 | 15 min | 7.5 min | | 2 - Rooms and Tasks | 5 | 35 min | 7.0 min | | 3 - Daily Plan and Cleanliness | 3 | 11 min | 3.7 min | - -**Recent Trend:** -- Last 5 plans: 02-04 (3 min), 02-05 (1 min), 03-01 (5 min), 03-02 (4 min), 03-03 (2 min) -- Trend: Verification gates consistently fast (1-2 min) - -*Updated after each plan completion* -| Phase 02 P01 | 8 | 2 tasks | 16 files | -| Phase 02 P02 | 11 | 2 tasks | 14 files | -| Phase 02 P03 | 12 | 2 tasks | 8 files | -| Phase 02 P04 | 3 | 2 tasks | 5 files | -| Phase 02 P05 | 1 | 1 task | 0 files | -| Phase 03 P01 | 5 | 2 tasks | 10 files | -| Phase 03 P02 | 4 | 2 tasks | 5 files | -| Phase 03 P03 | 2 | 2 tasks | 0 files | -| Phase 04-notifications P01 | 9 | 2 tasks | 11 files | -| Phase 04-notifications P02 | 5 | 2 tasks | 5 files | -| Phase 04-notifications P03 | 2 | 1 tasks | 0 files | +| 4 - Notifications | 3 | 16 min | 5.3 min | ## Accumulated Context ### Decisions -Decisions are logged in PROJECT.md Key Decisions table. -Recent decisions affecting current work: - -- [Pre-phase]: Riverpod 3.3 requires Flutter 3.41+ — verify before scaffolding -- [Pre-phase]: All due dates stored as date-only (calendar day), not DateTime — enforce from first migration -- [Pre-phase]: German-only UI for MVP; localization infrastructure (ARB + AppLocalizations) required from Phase 1 even with one locale -- [Pre-phase]: riverpod_lint must be active before any feature code — catches ref.watch outside build() at analysis time -- [Pre-phase]: drift_dev make-migrations workflow must be established in Phase 1 — recovery cost is data loss -- [01-01]: Pinned drift/drift_dev to 2.31.0 for analyzer ^9.0.0 compatibility with riverpod_generator 4.0.3 -- [01-01]: Generated Riverpod 3 provider named themeProvider (not themeNotifierProvider) per new naming convention -- [Phase 01-02]: Used themeProvider (Riverpod 3 naming) instead of themeNotifierProvider referenced in plan -- [02-01]: Scheduling functions are top-level pure functions with DateTime today parameter for testability -- [02-01]: Calendar-anchored intervals use anchorDay nullable field for month-clamping memory -- [02-01]: RoomWithStats computed via asyncMap on watchAllRooms stream, not a custom SQL join -- [02-01]: Templates stored as Dart const map for type safety, not JSON assets -- [02-01]: detectRoomType uses contains-based matching with alias map -- [Phase 02]: Scheduling functions are top-level pure functions with DateTime today parameter for testability -- [Phase 02]: Calendar-anchored intervals use anchorDay nullable field for month-clamping memory -- [Phase 02]: Templates stored as Dart const map for type safety, not JSON assets -- [02-02]: ReorderableBuilder with typed onReorder callback for drag-and-drop grid -- [02-02]: Long-press context menu (bottom sheet) for edit/delete on room cards -- [02-02]: Provider override pattern in tests to decouple from database dependency -- [02-03]: tasksInRoomProvider defined as manual StreamProvider.family due to riverpod_generator InvalidTypeException with drift Task type -- [02-03]: Frequency selector uses ChoiceChip Wrap layout for 10 presets plus custom option -- [02-03]: TaskRow uses ListTile with middle-dot separator between relative date and frequency label -- [02-04]: Template picker uses StatefulWidget (not Consumer) receiving data via constructor -- [02-04]: Room creation navigates to /rooms/$roomId (context.go) instead of context.pop to show new room -- [02-04]: Calendar-anchored intervals set anchorDay to today's day-of-month; day-count intervals set null -- [02-05]: Auto-approved verification checkpoint: dart analyze clean, 59/59 tests passing, all Phase 2 code integrated -- [03-01]: DailyPlanDao uses innerJoin (not leftOuterJoin) since tasks always have a room -- [03-01]: watchCompletionsToday uses customSelect with readsFrom for proper stream invalidation -- [03-01]: dailyPlanProvider uses manual StreamProvider.autoDispose (not @riverpod) due to drift Task type issue -- [03-01]: Progress total = remaining overdue + remaining today + completedTodayCount for stable denominator -- [03-02]: Used stream-driven completion with local _completingTaskIds Set for animation instead of AnimatedList -- [03-02]: DailyPlanTaskRow is StatelessWidget (not ConsumerWidget) -- completion callback passed in from parent -- [03-02]: No-tasks empty state uses dailyPlanNoTasks key for clearer daily plan context messaging -- [03-03]: Phase 3 verification gate passed: dart analyze clean, 72/72 tests, all 7 requirements confirmed functional -- [Phase 04-01]: timezone constraint upgraded to ^0.11.0 — flutter_local_notifications v21 requires ^0.11.0, plan specified ^0.9.4 -- [Phase 04-01]: flutter_local_notifications v21 uses named parameters in initialize() and zonedSchedule() — positional API removed in v20+ -- [Phase 04-01]: Generated Riverpod 3 provider named notificationSettingsProvider (not notificationSettingsNotifierProvider) — consistent with themeProvider naming convention -- [Phase 04-01]: nextInstanceOf exposed as @visibleForTesting public method to enable TZ logic unit testing without native dispatch mocking -- [Phase Phase 04-02]: openNotificationSettings() not available in flutter_local_notifications v21 — simplified to informational SnackBar (no action button) -- [Phase Phase 04-02]: ConsumerStatefulWidget for SettingsScreen — async permission callbacks require mounted guards after every await -- [Phase 04-notifications]: Phase 4 verification gate passed: dart analyze --fatal-infos zero issues, 89/89 tests passing — all NOTF-01 and NOTF-02 requirements confirmed functional +All v1.0 decisions are recorded in PROJECT.md Key Decisions table with outcomes. ### Pending Todos -None yet. +None. ### Blockers/Concerns -- ~~[Research]: Recurrence policy edge cases not fully specified~~ — **RESOLVED** in 2-CONTEXT.md: calendar-anchored intervals clamp to last day with anchor memory, day-count intervals roll forward. Next due from original due date. Catch-up skips to next future date. -- [Research]: Notification time configuration (user-adjustable vs hardcoded) not resolved. Decide before Phase 4 planning. -- ~~[Research]: First-launch template seeding UX (silent vs prompted) not resolved~~ — **RESOLVED** in 2-CONTEXT.md: post-creation prompt with all templates unchecked. Room type is optional, detected from name. Custom rooms skip templates entirely. +None — all v1.0 blockers resolved. ## Session Continuity -Last session: 2026-03-16T14:13:32.148Z -Stopped at: Completed 04-03-PLAN.md (Phase 4 Verification Gate) +Last session: 2026-03-16 +Stopped at: v1.0 milestone complete Resume file: None diff --git a/.planning/REQUIREMENTS.md b/.planning/milestones/v1.0-REQUIREMENTS.md similarity index 98% rename from .planning/REQUIREMENTS.md rename to .planning/milestones/v1.0-REQUIREMENTS.md index eb36f51..c3b3810 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/milestones/v1.0-REQUIREMENTS.md @@ -1,3 +1,12 @@ +# Requirements Archive: v1.0 MVP + +**Archived:** 2026-03-16 +**Status:** SHIPPED + +For current requirements, see `.planning/REQUIREMENTS.md`. + +--- + # Requirements: HouseHoldKeaper **Defined:** 2026-03-15 diff --git a/.planning/milestones/v1.0-ROADMAP.md b/.planning/milestones/v1.0-ROADMAP.md new file mode 100644 index 0000000..e2620a3 --- /dev/null +++ b/.planning/milestones/v1.0-ROADMAP.md @@ -0,0 +1,100 @@ +# Roadmap: HouseHoldKeaper + +## Overview + +Four phases build the app bottom-up along its natural dependency chain. Phase 1 lays the technical foundation every subsequent phase relies on. Phase 2 delivers complete room and task management — the core scheduling loop. Phase 3 surfaces that data as the daily plan view (the primary user experience) and adds the cleanliness indicator. Phase 4 adds notifications and completes the v1 feature set. After Phase 3, the app is usable daily. After Phase 4, it is releasable. + +## Phases + +**Phase Numbering:** +- Integer phases (1, 2, 3): Planned milestone work +- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED) + +Decimal phases appear between their surrounding integers in numeric order. + +- [x] **Phase 1: Foundation** - Project scaffold, database, state management, theme, and localization infrastructure (completed 2026-03-15) +- [x] **Phase 2: Rooms and Tasks** - Complete room CRUD, task CRUD with auto-scheduling, and bundled templates (completed 2026-03-15) +- [x] **Phase 3: Daily Plan and Cleanliness** - Primary daily plan screen with overdue/today/upcoming, cleanliness indicators per room (completed 2026-03-16) +- [x] **Phase 4: Notifications** - Daily summary notification with configurable time and Android permission handling (completed 2026-03-16) + +## Phase Details + +### Phase 1: Foundation +**Goal**: The app compiles, opens, and enforces correct architecture patterns — ready to receive features without accumulating technical debt +**Depends on**: Nothing (first phase) +**Requirements**: FOUND-01, FOUND-02, FOUND-03, FOUND-04, THEME-01, THEME-02 +**Success Criteria** (what must be TRUE): + 1. App launches on Android without errors and shows a bottom navigation bar with Home, Rooms, and Settings tabs + 2. Light and dark themes work correctly and follow the system setting by default, using the calm Material 3 palette (muted greens, warm grays, gentle blues) + 3. All UI strings are loaded from ARB localization files — no hardcoded German text in Dart code + 4. The Drift database opens on first launch with schemaVersion 1 and the migration workflow is established (drift_dev make-migrations runs without errors) + 5. riverpod_lint is active and flags ref.watch usage outside build() as an analysis error +**Plans**: 2 plans +Plans: +- [x] 01-01-PLAN.md — Scaffold Flutter project and build core infrastructure (database, providers, theme, localization) +- [x] 01-02-PLAN.md — Navigation shell, placeholder screens, Settings, and full app wiring + +### Phase 2: Rooms and Tasks +**Goal**: Users can create and manage rooms and tasks, mark tasks done, and trust the app to schedule the next occurrence automatically +**Depends on**: Phase 1 +**Requirements**: ROOM-01, ROOM-02, ROOM-03, ROOM-04, ROOM-05, TASK-01, TASK-02, TASK-03, TASK-04, TASK-05, TASK-06, TASK-07, TASK-08, TMPL-01, TMPL-02 +**Success Criteria** (what must be TRUE): + 1. User can create a room with a name and icon, edit it, reorder rooms via drag-and-drop, and delete it (with confirmation that removes all associated tasks) + 2. User can create a task in a room with name, description, frequency interval (daily through yearly and custom), and effort level; tasks can be edited and deleted with confirmation + 3. When creating a room, user can select from bundled German-language task templates for the chosen room type (all 14 room types covered) and they are added to the room as tasks + 4. User can mark a task done (tap or swipe), which records the completion and sets the next due date correctly based on the interval + 5. Overdue tasks are visually highlighted with a distinct color or badge on room cards and in task lists; tasks within a room are sorted by due date by default + 6. Each room card shows its name, icon, count of due tasks, and cleanliness indicator +**Plans**: 5 plans +Plans: +- [x] 02-01-PLAN.md — Data layer: Drift tables, migration v1->v2, DAOs, scheduling utility, domain models, templates, tests +- [x] 02-02-PLAN.md — Room CRUD UI: 2-column card grid, room form, icon picker, drag-and-drop reorder, providers +- [x] 02-03-PLAN.md — Task CRUD UI: task list, task row with completion, task form, overdue highlighting, providers +- [x] 02-04-PLAN.md — Template selection: template picker bottom sheet, room type detection, integration with room creation +- [x] 02-05-PLAN.md — Visual and functional verification checkpoint + +### Phase 3: Daily Plan and Cleanliness +**Goal**: Users can open the app and immediately see what needs doing today, act on tasks directly from the plan view, and see a room-level health indicator +**Depends on**: Phase 2 +**Requirements**: PLAN-01, PLAN-02, PLAN-03, PLAN-04, PLAN-05, PLAN-06, CLEAN-01 +**Success Criteria** (what must be TRUE): + 1. The Home tab shows today's tasks grouped by room, with a separate highlighted section at the top for overdue tasks + 2. User can mark a task done directly from the daily plan view via swipe or checkbox without navigating to the room + 3. User can see upcoming tasks (tomorrow and this week) from the daily plan screen + 4. A progress indicator shows completed vs total tasks for today (e.g., "5 von 12 erledigt") + 5. When no tasks are due, an encouraging "all clear" empty state is shown instead of an empty list + 6. Each room card displays a cleanliness indicator derived from the ratio of overdue tasks to total tasks in that room +**Plans**: 3 plans +Plans: +- [x] 03-01-PLAN.md — Data layer: DailyPlanDao with cross-room join query, providers, and localization keys +- [x] 03-02-PLAN.md — Daily plan UI: HomeScreen rewrite with progress card, task sections, animated completion, empty state +- [x] 03-03-PLAN.md — Visual and functional verification checkpoint + +### Phase 4: Notifications +**Goal**: Users receive a daily summary notification reminding them of today's task count, and can control notification behavior from settings +**Depends on**: Phase 2 +**Requirements**: NOTF-01, NOTF-02 +**Success Criteria** (what must be TRUE): + 1. User receives one daily notification showing the count of tasks due today, scheduled at a configurable time + 2. User can enable or disable notifications from the Settings tab, and the change takes effect immediately + 3. Notifications are correctly rescheduled after device reboot (RECEIVE_BOOT_COMPLETED receiver active) + 4. On Android API 33+, the app requests POST_NOTIFICATIONS permission at the appropriate moment and degrades gracefully if denied +**Plans**: 3 plans +Plans: +- [ ] 04-01-PLAN.md — Infrastructure: packages, Android config, NotificationService, NotificationSettingsNotifier, DAO queries, timezone init, tests +- [ ] 04-02-PLAN.md — Settings UI: Benachrichtigungen section with toggle, time picker, permission flow, scheduling wiring, tests +- [ ] 04-03-PLAN.md — Verification gate: dart analyze + full test suite + requirement confirmation + +## Progress + +**Execution Order:** +Phases execute in numeric order: 1 -> 2 -> 3 -> 4 + +Note: Phase 4 depends on Phase 2 (needs scheduling data) but can be developed in parallel with Phase 3. + +| Phase | Plans Complete | Status | Completed | +|-------|----------------|--------|-----------| +| 1. Foundation | 2/2 | Complete | 2026-03-15 | +| 2. Rooms and Tasks | 5/5 | Complete | 2026-03-15 | +| 3. Daily Plan and Cleanliness | 3/3 | Complete | 2026-03-16 | +| 4. Notifications | 3/3 | Complete | 2026-03-16 |