From 0778b8787be28446206f4cb2c116556673e73c3d Mon Sep 17 00:00:00 2001 From: Daniel Covington Date: Mon, 10 Aug 2026 10:53:58 -0400 Subject: [PATCH] Backlog Setup --- AGENTS.md | 43 ++- CLAUDE.md | 23 ++ README.md | 7 + docs/scrum-backlog.md | 744 ++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 803 insertions(+), 14 deletions(-) create mode 100644 docs/scrum-backlog.md diff --git a/AGENTS.md b/AGENTS.md index b2e17b9..70e7beb 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,6 +2,19 @@ ## 1. Mission +## 1A. Backlog and Scrum Tracking + +The living Scrum backlog for this repository is `docs/scrum-backlog.md`. + +Agents must use it as the primary planning artifact for implementation work: +- review the relevant epic, story, and tasks before starting substantial feature work +- update `docs/scrum-backlog.md` when work is selected, split, deferred, blocked, or completed +- mark completed work in the backlog as soon as the code, tests, and verification for that item are done +- add newly discovered implementation tasks under the appropriate story rather than tracking them only in chat +- keep backlog status aligned with the actual repository state + +If implementation order changes to unblock work, update `docs/scrum-backlog.md` to reflect that decision and keep the reasoning brief and explicit. + Build **CartWise v1**, a mobile-first grocery companion web application using **ASP.NET Core MVC**, **Razor Views**, **HTML5**, **CSS3**, **jQuery**, and **vanilla JavaScript**. CartWise v1 is not a grocery delivery platform and is not tied to any retailer. Its first job is to become the shopper's grocery memory: @@ -1386,20 +1399,22 @@ Architectural seams may be left for later, but do not build speculative systems. ## 25. Agent Coding Rules 1. Read this file before changing architecture. -2. Inspect existing code before creating parallel abstractions. -3. Prefer extending existing patterns over inventing new ones. -4. Keep controllers thin. -5. Keep persistence code out of Razor views and controllers. -6. Keep external provider response types inside Infrastructure. -7. Add tests for business rules and bug fixes. -8. Run build/tests after meaningful changes. -9. Do not silently change database semantics. -10. Create migrations for schema changes; never hand-edit production schema. -11. Never fabricate retailer capabilities or data. -12. If external data is unavailable, represent it as unavailable/stale—not guessed. -13. Preserve backward-compatible URLs where practical once routes ship. -14. Use comments for why, not obvious what. -15. Prefer clear conventional C# over clever abstraction. +2. Review `docs/scrum-backlog.md` before starting implementation work. +3. Update `docs/scrum-backlog.md` as work starts, changes, and completes. +4. Inspect existing code before creating parallel abstractions. +5. Prefer extending existing patterns over inventing new ones. +6. Keep controllers thin. +7. Keep persistence code out of Razor views and controllers. +8. Keep external provider response types inside Infrastructure. +9. Add tests for business rules and bug fixes. +10. Run build/tests after meaningful changes. +11. Do not silently change database semantics. +12. Create migrations for schema changes; never hand-edit production schema. +13. Never fabricate retailer capabilities or data. +14. If external data is unavailable, represent it as unavailable/stale—not guessed. +15. Preserve backward-compatible URLs where practical once routes ship. +16. Use comments for why, not obvious what. +17. Prefer clear conventional C# over clever abstraction. --- diff --git a/CLAUDE.md b/CLAUDE.md index 810d34f..8f2d9ae 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,6 +6,29 @@ This repository builds **CartWise**, a mobile-first grocery companion implemente The canonical architecture and scope are defined in `AGENTS.md`. Read `AGENTS.md` completely before making architectural changes. This file gives Claude-specific operating guidance and a compact execution map. +The living Scrum backlog is `docs/scrum-backlog.md`. Review it before starting substantial implementation work, and update it as work is started, split, blocked, deferred, or completed so the repository backlog stays aligned with the actual codebase state. + +Use `docs/scrum-backlog.md` as the shared execution tracker for epics, stories, and tasks rather than keeping implementation progress only in chat. + +--- + +## Backlog Workflow + +Before implementation work begins: +- review the relevant epic and story in `docs/scrum-backlog.md` +- confirm the work still fits the current `AGENTS.md` phase and scope +- add or refine implementation tasks if new concrete work is discovered + +While work is in progress: +- keep backlog task wording specific and implementation-oriented +- note blockers or sequencing changes in `docs/scrum-backlog.md` when they affect delivery order +- avoid treating the backlog as static documentation; it is a living delivery artifact + +When work is completed: +- update `docs/scrum-backlog.md` to reflect completed stories or tasks +- ensure code, tests, and verification support the completion claim +- keep backlog status consistent with the actual repository contents + --- ## Core Stack diff --git a/README.md b/README.md index c717405..ac931fa 100644 --- a/README.md +++ b/README.md @@ -143,6 +143,13 @@ tests/ This repository is being initialized from the `AGENTS.md` build specification. The current focus is establishing the project foundation, backlog, and delivery workflow before implementing the application phases. +## Project Planning + +- Delivery guidance and architectural rules live in `AGENTS.md` +- Claude-specific working guidance lives in `CLAUDE.md` +- The living Scrum backlog lives in `docs/scrum-backlog.md` +- Update `docs/scrum-backlog.md` as stories and tasks move into active work and when work is completed + ## Getting Started The solution scaffolding is planned but may not yet be present in this repository. Once the projects are created, the expected local development flow will be: diff --git a/docs/scrum-backlog.md b/docs/scrum-backlog.md new file mode 100644 index 0000000..97caad8 --- /dev/null +++ b/docs/scrum-backlog.md @@ -0,0 +1,744 @@ +# CartWise Scrum Backlog + +## Purpose + +This document translates the product and implementation guidance from `AGENTS.md` into a Scrum-friendly backlog for CartWise v1. It organizes work into epics, user stories, and implementation tasks that align with the required phased delivery order. + +## Product Vision + +CartWise is a mobile-first grocery companion web app that helps households remember what to buy, what they bought, what they paid, and what they may need again soon. + +## Scrum Workflow + +### Cadence + +- Sprint length: 2 weeks +- Planning: first day of sprint +- Daily Scrum: 15 minutes +- Backlog refinement: once per sprint +- Review and demo: final day of sprint +- Retrospective: immediately after review + +### Roles + +- **Product Owner**: prioritizes scope, clarifies acceptance criteria, approves sprint outcomes +- **Scrum Master**: facilitates ceremonies, removes blockers, protects sprint focus +- **Development Team**: designs, builds, tests, documents, and verifies product increments + +### Board Columns + +- Backlog +- Ready +- In Sprint +- In Progress +- Code Review +- Verify +- Done + +### Estimation + +- Estimate stories in story points +- Track tasks as checklist items or engineering subtasks +- Keep stories small enough to complete within one sprint when possible + +## Definitions + +### Definition of Ready + +A story is ready when: + +- Business value is clear +- Acceptance criteria are written +- Dependencies are identified +- UI, domain, and data impact are understood +- Test approach is known +- The story is small enough to deliver in a sprint + +### Definition of Done + +A story is done when: + +- Code is implemented +- Tests are added or updated +- Build passes +- Authorization and validation are enforced where applicable +- Logging is added where useful +- User-facing behavior is verified +- Work remains aligned with `AGENTS.md` architecture and scope + +## Tracking Conventions + +- Use `- [ ]` for not started tasks +- Use `- [x]` for completed tasks +- Update story acceptance criteria or add a short status note when a story is fully delivered +- Keep task state aligned with the actual repository state + +## Epic Roadmap + +1. `CW-EPIC-01` Platform Foundation +2. `CW-EPIC-02` Household and Access Control +3. `CW-EPIC-03` Smart Shopping List +4. `CW-EPIC-04` Product Catalog and Barcode Resolution +5. `CW-EPIC-05` Stores, Purchases, and Price Intelligence +6. `CW-EPIC-06` Shopping Mode +7. `CW-EPIC-07` Running-Low Suggestions +8. `CW-EPIC-08` UX Polish, Security, and Release Readiness + +--- + +## `CW-EPIC-01` Platform Foundation + +**Goal:** establish the solution structure, authentication, PostgreSQL wiring, and baseline engineering standards. + +### `CW-STORY-01.1` Create solution skeleton +**User story:** As a developer, I want the CartWise solution scaffolded so the app follows a clean modular architecture. + +**Acceptance criteria** +- `CartWise.sln` exists +- `src/` and `tests/` project layout matches the spec +- Project references follow approved dependency direction +- Nullable reference types are enabled + +**Tasks** +- [ ] Create `CartWise.sln` +- [ ] Create `src/CartWise.Web` +- [ ] Create `src/CartWise.Application` +- [ ] Create `src/CartWise.Domain` +- [ ] Create `src/CartWise.Infrastructure` +- [ ] Create `tests/CartWise.Domain.Tests` +- [ ] Create `tests/CartWise.Application.Tests` +- [ ] Create `tests/CartWise.Web.Tests` +- [ ] Add project references +- [ ] Enable nullable reference types + +### `CW-STORY-01.2` Configure application startup +**User story:** As a developer, I want a runnable MVC shell so the team can build on a working baseline. + +**Acceptance criteria** +- ASP.NET Core MVC app starts locally +- Shared layout and static assets load correctly +- Environment-based configuration is wired +- PostgreSQL connection is configurable + +**Tasks** +- [ ] Configure MVC services and middleware +- [ ] Add base layout and navigation shell +- [ ] Organize `wwwroot` structure +- [ ] Add configuration bindings +- [ ] Wire PostgreSQL connection string +- [ ] Verify local app startup + +### `CW-STORY-01.3` Add Identity authentication +**User story:** As a user, I want to sign in so my household data is protected. + +**Acceptance criteria** +- Registration and sign-in are available +- Authenticated routes can be protected +- Identity persistence is configured + +**Tasks** +- [ ] Add ASP.NET Core Identity +- [ ] Create `ApplicationUser` +- [ ] Configure Identity persistence +- [ ] Scaffold auth UI +- [ ] Verify login and logout flow + +### `CW-STORY-01.4` Establish engineering baseline +**User story:** As a team, we want build and test standards so changes remain stable over time. + +**Acceptance criteria** +- Build can run consistently +- Basic test execution is available +- Logging defaults are configured + +**Tasks** +- [ ] Add analyzer and formatting settings +- [ ] Configure structured logging baseline +- [ ] Add smoke test coverage +- [ ] Add CI-oriented build and test commands to docs + +--- + +## `CW-EPIC-02` Household and Access Control + +**Goal:** enable household creation, membership, and household-scoped authorization. + +### `CW-STORY-02.1` Model households and membership +**User story:** As a developer, I want household entities persisted so household features have a secure foundation. + +**Acceptance criteria** +- Household and membership entities exist +- Roles are defined +- EF configurations and migration are created + +**Tasks** +- [ ] Create `Household` entity +- [ ] Create `HouseholdMember` entity +- [ ] Add role enum +- [ ] Add EF configurations +- [ ] Create migration +- [ ] Add domain tests + +### `CW-STORY-02.2` Implement household service +**User story:** As a developer, I want household operations centralized so controllers stay thin and rules stay testable. + +**Acceptance criteria** +- Household creation is supported +- Current household can be resolved +- Membership checks are reusable + +**Tasks** +- [ ] Create `IHouseholdService` +- [ ] Implement `HouseholdService` +- [ ] Add create household use case +- [ ] Add get current household use case +- [ ] Add membership verification logic +- [ ] Add application tests + +### `CW-STORY-02.3` Build household UI +**User story:** As a user, I want to create and view my household so I can begin using CartWise. + +**Acceptance criteria** +- Household create page is available +- Household overview page is available +- Validation errors are shown clearly + +**Tasks** +- [ ] Create `HouseholdController` +- [ ] Create household view models +- [ ] Build `Views/Household/Create.cshtml` +- [ ] Build `Views/Household/Index.cshtml` +- [ ] Add validation messaging +- [ ] Add redirect flow after creation + +### `CW-STORY-02.4` Enforce household authorization +**User story:** As a user, I want household data isolated so other users cannot access it. + +**Acceptance criteria** +- Household membership is enforced on household-scoped resources +- Unauthorized requests are blocked +- Resource isolation is covered by tests + +**Tasks** +- [ ] Add household authorization policy or helper +- [ ] Enforce membership checks in services +- [ ] Add integration tests for access control +- [ ] Add tests for unauthorized and cross-household access + +--- + +## `CW-EPIC-03` Smart Shopping List + +**Goal:** allow household members to maintain a shared grocery list, including unresolved free-text items. + +### `CW-STORY-03.1` Model shopping list and grocery concepts +**User story:** As a developer, I want shopping list entities defined so shared list workflows can be persisted. + +**Acceptance criteria** +- Grocery concept, category, shopping list, and shopping list item entities exist +- Item statuses are defined +- Optimistic concurrency is supported for list items + +**Tasks** +- [ ] Create `GroceryConcept` +- [ ] Create `ProductCategory` +- [ ] Create `ShoppingList` +- [ ] Create `ShoppingListItem` +- [ ] Add list status enums +- [ ] Add row version concurrency token +- [ ] Add EF configurations +- [ ] Create migration + +### `CW-STORY-03.2` Implement active shopping list service +**User story:** As a user, I want my household to have an active grocery list so shared planning is easy. + +**Acceptance criteria** +- Active list can be retrieved +- Default active list can be created +- Household rule for default active list is enforced + +**Tasks** +- [ ] Create `IShoppingListService` +- [ ] Implement get active list +- [ ] Implement create list +- [ ] Enforce one default active list rule +- [ ] Add application tests + +### `CW-STORY-03.3` Add grocery items quickly +**User story:** As a household member, I want to add free-text grocery items quickly so I do not lose shopping intent. + +**Acceptance criteria** +- Free-text item entry is supported +- Quantity and unit are optional +- Item appears on the active list +- Product resolution is not required to add an item + +**Tasks** +- [ ] Implement add item use case +- [ ] Support `DisplayName`, quantity, and unit +- [ ] Add validation rules +- [ ] Add item partial view +- [ ] Add controller POST action +- [ ] Add tests + +### `CW-STORY-03.4` Update shopping list items +**User story:** As a household member, I want to toggle, skip, and delete items so the list stays accurate. + +**Acceptance criteria** +- Items can be marked purchased +- Items can be skipped and unskipped +- Items can be deleted +- Concurrency conflicts are handled safely + +**Tasks** +- [ ] Implement toggle purchased +- [ ] Implement skip and unskip +- [ ] Implement delete item +- [ ] Handle concurrency exceptions +- [ ] Add progressive enhancement with jQuery +- [ ] Preserve server-post fallback +- [ ] Add tests + +### `CW-STORY-03.5` Deliver a mobile-first list UI +**User story:** As a shopper, I want a touch-friendly grocery list so it works well on my phone. + +**Acceptance criteria** +- List page is readable on mobile +- Quick add is prominent +- Tap targets are appropriate for shopping use + +**Tasks** +- [ ] Build `Views/ShoppingList/Index.cshtml` +- [ ] Build `Views/ShoppingList/_ListItem.cshtml` +- [ ] Add quick-add UI +- [ ] Add touch-friendly styles +- [ ] Add `wwwroot/js/pages/shopping-list.js` + +--- + +## `CW-EPIC-04` Product Catalog and Barcode Resolution + +**Goal:** support product identity, household product preferences, and local-first barcode resolution with provider fallback. + +### `CW-STORY-04.1` Model product catalog entities +**User story:** As a developer, I want product and identifier entities modeled so products can be resolved independently of UPC. + +**Acceptance criteria** +- Brand, product, identifier, and household preference entities exist +- Identifier uniqueness rules are defined +- EF configurations and migration are created + +**Tasks** +- [ ] Create `Brand` +- [ ] Create `Product` +- [ ] Create `ProductIdentifier` +- [ ] Create `HouseholdProductPreference` +- [ ] Add source type enums +- [ ] Add indexes and normalized fields +- [ ] Add EF configurations +- [ ] Create migration + +### `CW-STORY-04.2` Search and view products +**User story:** As a user, I want to search and view products so I can understand and choose preferred items. + +**Acceptance criteria** +- Local product search works +- Product details page displays key product information +- Household price insights can be shown later on the details page + +**Tasks** +- [ ] Create `IProductService` +- [ ] Implement local catalog search +- [ ] Create `ProductController` +- [ ] Build `Views/Product/Search.cshtml` +- [ ] Build `Views/Product/Details.cshtml` +- [ ] Add product view models +- [ ] Add tests + +### `CW-STORY-04.3` Implement barcode lookup flow +**User story:** As a shopper, I want a barcode lookup flow so known products can be resolved quickly. + +**Acceptance criteria** +- Barcode input is normalized +- Local identifier lookup runs first +- Provider fallback runs when local lookup misses +- Accepted results persist locally + +**Tasks** +- [ ] Define `IProductDataProvider` +- [ ] Implement barcode normalization +- [ ] Implement local-first lookup flow +- [ ] Persist imported products and identifiers +- [ ] Add unit and application tests + +### `CW-STORY-04.4` Integrate Open Food Facts +**User story:** As a developer, I want a provider fallback for unknown products so barcode resolution remains useful. + +**Acceptance criteria** +- Open Food Facts provider can query by barcode +- Provider models remain isolated to infrastructure +- Provider errors are logged safely + +**Tasks** +- [ ] Implement `OpenFoodFactsProductDataProvider` +- [ ] Map provider responses to internal DTOs +- [ ] Add configuration and secrets support +- [ ] Add error handling and logging +- [ ] Add tests with mocked provider behavior + +### `CW-STORY-04.5` Build scan page +**User story:** As a shopper, I want a camera-based scan page so I can identify products with my phone. + +**Acceptance criteria** +- Scan page requests camera permission +- Barcode result can resolve product details +- User can add scanned product to the list or record a price + +**Tasks** +- [ ] Create `ScanController` +- [ ] Build `Views/Scan/Index.cshtml` +- [ ] Add camera permission flow +- [ ] Add barcode JS integration +- [ ] Add add-to-list and record-price actions + +--- + +## `CW-EPIC-05` Stores, Purchases, and Price Intelligence + +**Goal:** record where purchases happened and build a trustworthy append-only price history. + +### `CW-STORY-05.1` Model retailers and store locations +**User story:** As a developer, I want retailer and store entities so purchases can be tied to real locations. + +**Acceptance criteria** +- Retailer and store entities exist +- Location fields support practical v1 store data +- EF configurations and migration are created + +**Tasks** +- [ ] Create `Retailer` +- [ ] Create `StoreLocation` +- [ ] Add EF configurations +- [ ] Create migration +- [ ] Add tests for basic persistence rules + +### `CW-STORY-05.2` Model purchases and purchase items +**User story:** As a developer, I want purchase history modeled so shopping outcomes can be stored. + +**Acceptance criteria** +- Purchase and purchase item entities exist +- Purchase source types are defined +- EF configurations and migration are created + +**Tasks** +- [ ] Create `Purchase` +- [ ] Create `PurchaseItem` +- [ ] Add source type enum +- [ ] Add EF configurations +- [ ] Create migration +- [ ] Add tests + +### `CW-STORY-05.3` Model append-only price observations +**User story:** As a developer, I want append-only price observations so historical price facts are preserved. + +**Acceptance criteria** +- Price observation entity exists +- Useful indexes are defined for history queries +- Older observations are not overwritten by newer ones + +**Tasks** +- [ ] Create `PriceObservation` +- [ ] Add indexes for product, household, and store history +- [ ] Add EF configuration +- [ ] Create migration +- [ ] Add tests for append-only behavior + +### `CW-STORY-05.4` Record household purchases +**User story:** As a shopper, I want to record purchases so CartWise can remember what I bought and what I paid. + +**Acceptance criteria** +- Purchase flow can start and complete +- Purchase items can be added +- Shopping list items can be linked when relevant + +**Tasks** +- [ ] Create `IPurchaseService` +- [ ] Implement start purchase flow +- [ ] Implement add purchase item flow +- [ ] Implement complete purchase flow +- [ ] Link purchase items to shopping list items where applicable +- [ ] Add tests + +### `CW-STORY-05.5` Derive price intelligence +**User story:** As a user, I want price history and price insights so I can make better grocery decisions. + +**Acceptance criteria** +- Purchase items can create price observations +- Latest, average, median, lowest, and unit price calculations are supported when data allows +- Freshness and source can be displayed + +**Tasks** +- [ ] Create `IPriceService` +- [ ] Derive observations from purchase items +- [ ] Implement latest price calculation +- [ ] Implement average and median calculations +- [ ] Implement lowest recent price calculation +- [ ] Implement unit price calculation +- [ ] Add tests for price statistics + +### `CW-STORY-05.6` Build price views +**User story:** As a user, I want a price history screen so I can review what my household typically pays. + +**Acceptance criteria** +- Prices index page exists +- Product-specific price history page exists +- Product details can show historical price insight + +**Tasks** +- [ ] Create `PriceController` +- [ ] Build `Views/Price/Index.cshtml` +- [ ] Build `Views/Price/Product.cshtml` +- [ ] Add price history to product details view +- [ ] Add filtering and sorting UI +- [ ] Add freshness and source display + +--- + +## `CW-EPIC-06` Shopping Mode + +**Goal:** provide a simple, touch-friendly in-store workflow for marking progress and recording purchases. + +### `CW-STORY-06.1` Implement shopping mode service +**User story:** As a developer, I want shopping-mode orchestration so in-store behavior is consistent and testable. + +**Acceptance criteria** +- Shopping mode view can be prepared from list data +- Items can be grouped for easier shopping +- Remaining and purchased counts are available + +**Tasks** +- [ ] Create `IShoppingModeService` +- [ ] Implement shopping mode preparation +- [ ] Group by category-based sections +- [ ] Calculate remaining and purchased counts +- [ ] Add tests + +### `CW-STORY-06.2` Build shopping mode UI +**User story:** As a shopper, I want a low-noise mobile shopping view so I can use CartWise during a real trip. + +**Acceptance criteria** +- Shopping mode works well on a phone +- Groups and counts are clear +- Key actions are easy to reach + +**Tasks** +- [ ] Create `ShoppingController` +- [ ] Build `Views/Shopping/Start.cshtml` +- [ ] Build `Views/Shopping/_ShoppingItem.cshtml` +- [ ] Add touch-friendly controls +- [ ] Add `wwwroot/js/pages/shopping-mode.js` + +### `CW-STORY-06.3` Support in-store item actions +**User story:** As a shopper, I want to mark items purchased, skipped, unavailable, or substituted so the trip stays accurate. + +**Acceptance criteria** +- Item transitions are supported +- Anti-forgery is enforced on state changes +- Actions update the shopping workflow correctly + +**Tasks** +- [ ] Add purchase action +- [ ] Add skip action +- [ ] Add unavailable action +- [ ] Add substitute action +- [ ] Add anti-forgery for AJAX and form posts +- [ ] Add tests + +### `CW-STORY-06.4` Record prices while shopping +**User story:** As a shopper, I want to optionally enter prices in shopping mode so price history stays current. + +**Acceptance criteria** +- Optional price entry is available during purchase actions +- Money input is validated +- Captured values feed purchase and price history logic + +**Tasks** +- [ ] Add optional per-item price input +- [ ] Validate price and quantity inputs +- [ ] Persist captured values through purchase service +- [ ] Add tests + +--- + +## `CW-EPIC-07` Running-Low Suggestions + +**Goal:** use deterministic purchase history to suggest what a household may need soon. + +### `CW-STORY-07.1` Build replenishment engine +**User story:** As a developer, I want deterministic running-low logic so suggestions are explainable and testable. + +**Acceptance criteria** +- Last N purchase dates can be evaluated +- Median interval is used when sufficient history exists +- Minimum-history and tolerance rules are enforced + +**Tasks** +- [ ] Create `IReplenishmentService` +- [ ] Gather recent purchase dates +- [ ] Calculate purchase intervals +- [ ] Implement median interval logic +- [ ] Add minimum-history thresholds +- [ ] Add tolerance window logic +- [ ] Return score and reason data +- [ ] Add tests + +### `CW-STORY-07.2` Show suggestions on home and list views +**User story:** As a user, I want running-low suggestions surfaced in context so I can act on them quickly. + +**Acceptance criteria** +- Home page can display suggestions +- Shopping list page can display suggestions +- Suggestions include reason or confidence context + +**Tasks** +- [ ] Extend `HomeViewModel` +- [ ] Add suggestions to home controller flow +- [ ] Add running-low partial views +- [ ] Render suggestions on list page +- [ ] Add tests + +### `CW-STORY-07.3` Add suggestion-to-list workflow +**User story:** As a user, I want to add a running-low suggestion to my list so I can convert insight into action quickly. + +**Acceptance criteria** +- Suggestion can be added to the active list +- Existing list workflows are reused +- Duplicate accidental adds are reasonably controlled + +**Tasks** +- [ ] Add controller action to add suggestion +- [ ] Reuse shopping list add-item workflow +- [ ] Add duplicate-prevention rules if needed +- [ ] Add tests + +--- + +## `CW-EPIC-08` UX Polish, Security, and Release Readiness + +**Goal:** harden the v1 experience for real-world use and release confidence. + +### `CW-STORY-08.1` Improve mobile usability and accessibility +**User story:** As a user, I want the app to be easy to use on my phone and accessible across core workflows. + +**Acceptance criteria** +- Key pages are responsive +- Labels, focus states, and contrast meet baseline usability needs +- Error handling is understandable + +**Tasks** +- [ ] Review responsive layouts +- [ ] Improve form labels and focus states +- [ ] Improve contrast and tap sizes +- [ ] Validate keyboard navigation +- [ ] Validate error summaries + +### `CW-STORY-08.2` Harden security coverage +**User story:** As a team, we want security-sensitive paths reviewed so household data remains protected. + +**Acceptance criteria** +- Anti-forgery coverage is verified +- Authorization coverage is verified +- Secrets handling is consistent with app rules + +**Tasks** +- [ ] Review anti-forgery coverage +- [ ] Review authorization enforcement +- [ ] Review validation across state-changing flows +- [ ] Review secrets and configuration handling +- [ ] Add integration tests for protected routes + +### `CW-STORY-08.3` Add diagnostics and logging +**User story:** As a team, we want actionable diagnostics so failures can be understood and fixed quickly. + +**Acceptance criteria** +- External provider failures are logged +- Barcode misses can be diagnosed +- Authorization failures are logged safely + +**Tasks** +- [ ] Add structured logging for provider failures +- [ ] Log unresolved barcode outcomes +- [ ] Log authorization failures safely +- [ ] Add basic health-check strategy if included + +### `CW-STORY-08.4` Seed realistic development data +**User story:** As a developer, I want realistic sample data so workflows can be tested quickly during development. + +**Acceptance criteria** +- Development-only seed data exists +- Seed data covers household, products, stores, and price history +- Production is not polluted with fake data + +**Tasks** +- [ ] Seed one household +- [ ] Seed grocery concepts and categories +- [ ] Seed brands and products +- [ ] Seed product identifiers +- [ ] Seed store locations +- [ ] Seed purchase and price history +- [ ] Restrict seeding to development only + +--- + +## Suggested Sprint Sequence + +### Sprint 1 +- `CW-EPIC-01` Platform Foundation +- Start `CW-EPIC-02` Household and Access Control + +### Sprint 2 +- Finish `CW-EPIC-02` Household and Access Control +- Start `CW-EPIC-03` Smart Shopping List + +### Sprint 3 +- Finish `CW-EPIC-03` Smart Shopping List + +### Sprint 4 +- `CW-EPIC-04` Product Catalog and Barcode Resolution + +### Sprint 5 +- `CW-EPIC-05` Stores, Purchases, and Price Intelligence + +### Sprint 6 +- `CW-EPIC-06` Shopping Mode + +### Sprint 7 +- `CW-EPIC-07` Running-Low Suggestions + +### Sprint 8 +- `CW-EPIC-08` UX Polish, Security, and Release Readiness +- Stabilization and release verification + +## Story Template + +Use this format for new backlog items: + +```md +### `CW-STORY-XX.X` Story Title +**User story:** As a `user type`, I want `capability` so that `benefit`. + +**Acceptance criteria** +- Criterion 1 +- Criterion 2 + +**Tasks** +- [ ] Task 1 +- [ ] Task 2 +``` + +## Notes + +- Keep v1 scope tightly aligned to the grocery-memory goals +- Avoid introducing speculative architecture or out-of-scope features +- Reprioritize stories only when dependencies or product value clearly require it +- Preserve the implementation order unless a small change is needed to unblock progress