makiolaj/HouseHoldKeaper
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

chore: complete v1.0 MVP milestone
Some checks failed
Build and Release to F-Droid / build-and-deploy (push) Has been cancelled
Details

Browse Source 
Archive roadmap and requirements to milestones/, evolve PROJECT.md
with validated requirements and decision outcomes, reorganize
ROADMAP.md with milestone grouping, create retrospective.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Jean-Luc Makiola
2026-03-16 20:10:01 +01:00
parent 36126acc18
commit 1a1a10c9ea
7 changed files with 263 additions and 197 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
.planning/MILESTONES.md Normal file
View File

@@ -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`
---

60
.planning/PROJECT.md
View File

@@ -2,7 +2,7 @@
## What This Is ## 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 ## Core Value
@@ -12,20 +12,22 @@ Users can see what needs doing today, mark it done, and trust the app to schedul
### Validated ### 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 ### Active
- [ ] Room CRUD with icons and optional photos - [ ] Data export/import (JSON)
- [ ] Task CRUD with frequency intervals and due date calculation - [ ] English localization
- [ ] Daily plan view with overdue/today/upcoming sections - [ ] Room cover photos from camera or gallery
- [ ] Task completion with auto-scheduling of next due date - [ ] Task completion history log
- [ ] Bundled task templates per room type (German only) - [ ] Additional task sorting (alphabetical, interval, effort)
- [ ] 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)
### Out of Scope ### 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 - Subscription model / in-app purchases — free forever
- Family profile sharing across devices — single-device app - Family profile sharing across devices — single-device app
- Server-side infrastructure — zero backend - Server-side infrastructure — zero backend
- Data export/import (JSON) — deferred to v1.1 - AI-powered task suggestions — overkill for curated templates
- English localization — deferred to v1.1 (ship German-only MVP) - 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 - Real-time cross-device sync — potential future self-hosted feature
- Tablet-optimized layout — future enhancement - Tablet-optimized layout — future enhancement
- Statistics & insights dashboard — v2.0 - 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 ## 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 - 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 - Code and comments in English; UI strings German-only for v1.0
- 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
- Gitea (self-hosted on Hetzner) for version control; no CI/CD pipeline yet - Gitea (self-hosted on Hetzner) for version control; no CI/CD pipeline yet
## Constraints ## 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) - **Platform**: Android-first (iOS later)
- **Offline**: 100% offline-capable, zero network dependencies - **Offline**: 100% offline-capable, zero network dependencies
- **Privacy**: No data leaves the device, no analytics, no tracking - **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 - **No CI**: No automated build pipeline initially
## Key Decisions ## Key Decisions
| Decision | Rationale | Outcome | | Decision | Rationale | Outcome |
|----------|-----------|---------| |----------|-----------|---------|
| Riverpod over Bloc | Modern, compile-safe, less boilerplate, Dart-native | — 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 | — Pending | | 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 | — Pending | | Android-first | Primary device is Android; iOS follows | Good — no iOS-specific issues encountered |
| German-only MVP | Primary user language; defer localization infrastructure | — Pending | | 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 | — Pending | | 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, not playful | — Pending | | 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 | — Pending | | 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*

65
.planning/RETROSPECTIVE.md Normal file
View File

@@ -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)

104
.planning/ROADMAP.md
View File

@@ -1,100 +1,28 @@
# Roadmap: HouseHoldKeaper # 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 ## Phases
**Phase Numbering:** <details>
- Integer phases (1, 2, 3): Planned milestone work <summary>v1.0 MVP (Phases 1-4) — SHIPPED 2026-03-16</summary>
- 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 (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) See `milestones/v1.0-ROADMAP.md` for full phase details.
- [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 </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 ## Progress
**Execution Order:** | Phase | Milestone | Plans Complete | Status | Completed |
Phases execute in numeric order: 1 -> 2 -> 3 -> 4 |-------|-----------|----------------|--------|-----------|
| 1. Foundation | v1.0 | 2/2 | Complete | 2026-03-15 |
Note: Phase 4 depends on Phase 2 (needs scheduling data) but can be developed in parallel with Phase 3. | 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 |
| Phase | Plans Complete | Status | Completed | | 4. Notifications | v1.0 | 3/3 | Complete | 2026-03-16 |
|-------|----------------|--------|-----------|
| 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 |

102
.planning/STATE.md
View File

@@ -1,11 +1,11 @@
--- ---
gsd_state_version: 1.0 gsd_state_version: 1.0
milestone: v1.0 milestone: v1.0
milestone_name: milestone milestone_name: MVP
status: executing status: shipped
stopped_at: Completed 04-03-PLAN.md (Phase 4 Verification Gate) stopped_at: v1.0 milestone complete
last_updated: "2026-03-16T14:20:25.850Z" last_updated: "2026-03-16T20:00:00.000Z"
last_activity: 2026-03-16 — Completed 04-01-PLAN.md (Notification infrastructure) last_activity: 2026-03-16 — v1.0 MVP milestone shipped
progress: progress:
total_phases: 4 total_phases: 4
completed_phases: 4 completed_phases: 4
@@ -18,26 +18,25 @@ progress:
## Project Reference ## 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. **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 ## Current Position
Phase: 4 of 4 (Notifications) Milestone: v1.0 MVP — SHIPPED 2026-03-16
Plan: 1 of 2 in current phase -- COMPLETE Status: All 4 phases complete, 13/13 plans executed, 89 tests passing
Status: Phase 4 in progress — plan 1 complete, plan 2 (Settings UI) pending Next: `/gsd:new-milestone` for v1.1
Last activity: 2026-03-16 — Completed 04-01-PLAN.md (Notification infrastructure)
Progress: [██████████] 100% Progress: [##########] 100%
## Performance Metrics ## Performance Metrics
**Velocity:** **Velocity:**
- Total plans completed: 10 - Total plans completed: 13
- Average duration: 6.1 min - Total execution time: ~1.3 hours
- Total execution time: 1.0 hours - Average duration: ~6 min/plan
**By Phase:** **By Phase:**
@@ -46,85 +45,24 @@ Progress: [██████████] 100%
| 1 - Foundation | 2 | 15 min | 7.5 min | | 1 - Foundation | 2 | 15 min | 7.5 min |
| 2 - Rooms and Tasks | 5 | 35 min | 7.0 min | | 2 - Rooms and Tasks | 5 | 35 min | 7.0 min |
| 3 - Daily Plan and Cleanliness | 3 | 11 min | 3.7 min | | 3 - Daily Plan and Cleanliness | 3 | 11 min | 3.7 min |
| 4 - Notifications | 3 | 16 min | 5.3 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 |
## Accumulated Context ## Accumulated Context
### Decisions ### Decisions
Decisions are logged in PROJECT.md Key Decisions table. All v1.0 decisions are recorded in PROJECT.md Key Decisions table with outcomes.
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<Widget> 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
### Pending Todos ### Pending Todos
None yet. None.
### Blockers/Concerns ### 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. None — all v1.0 blockers resolved.
- [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.
## Session Continuity ## Session Continuity
Last session: 2026-03-16T14:13:32.148Z Last session: 2026-03-16
Stopped at: Completed 04-03-PLAN.md (Phase 4 Verification Gate) Stopped at: v1.0 milestone complete
Resume file: None Resume file: None

9
.planning/REQUIREMENTS.md → .planning/milestones/v1.0-REQUIREMENTS.md
View File

@@ -1,3 +1,12 @@
# Requirements Archive: v1.0 MVP
**Archived:** 2026-03-16
**Status:** SHIPPED
For current requirements, see `.planning/REQUIREMENTS.md`.
---
# Requirements: HouseHoldKeaper # Requirements: HouseHoldKeaper
**Defined:** 2026-03-15 **Defined:** 2026-03-15

100
.planning/milestones/v1.0-ROADMAP.md Normal file
View File

@@ -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 |