Spec is done and ready for work.

1 viikko sitten · eb0115fa05
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -15,6 +15,37 @@ Agents must use it as the primary planning artifact for implementation work:

 If implementation order changes to unblock work, update `docs/scrum-backlog.md` to reflect that decision and keep the reasoning brief and explicit.

 Agents must also consult:
 - `docs/decision-log.md` for accepted product and delivery decisions
 - `docs/release-mvp-checklist.md` for the current MVP completion criteria

 ## 1B. Current MVP-Now Delivery Contract

 The full CartWise v1 vision in this file remains the long-term target architecture and product direction.

 However, the **current active delivery target** is a **local MVP by September 10, 2026** for a **solo founder + AI** workflow.

 For the current MVP, prioritize only the smallest launchable grocery-memory slice:
 1. Register and sign in.
 2. Create and use a household.
 3. Maintain one active grocery list.
 4. Add free-text grocery items without requiring product resolution.
 5. Toggle, skip, edit, and delete list items as required by the backlog.
 6. Record purchases manually.
 7. View basic personal price history.
 8. Show deterministic running-low suggestions.
 9. Ensure core flows work on a phone-sized layout.

 For the current MVP, these are explicitly **not launch blockers** unless the user reprioritizes them:
 - barcode scanning
 - camera scan workflows
 - Open Food Facts or USDA integration
 - dedicated shopping mode screens beyond what the list page can cover
 - hosted deployment
 - production PostgreSQL setup

 When this file and `docs/scrum-backlog.md` differ on near-term execution priority, use `docs/scrum-backlog.md` as the active delivery plan and keep this file as the broader product specification.

 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:
@@ -45,6 +76,10 @@ Do **not** expand v1 into meal planning, coupon clipping, universal retailer che
 - Entity Framework Core
 - PostgreSQL

 ### MVP Development Note
 - SQLite is acceptable and preferred for the current local MVP timeline
 - keep the design compatible with a later PostgreSQL move

 ### Optional / Later
 - PostgreSQL PostGIS when geographic querying becomes necessary
 - IndexedDB + Service Worker for advanced offline/PWA functionality
@@ -1243,6 +1278,18 @@ Suggested concepts:

 Agents must follow this order unless a blocking dependency requires a small adjustment.

 ### 22A. Current MVP-Now Build Order

 For the current local MVP target, execute in this order unless the user explicitly reprioritizes:
 1. Foundation: solution, SQLite wiring, Identity, baseline tests.
 2. Household: household entities, authorization, create household flow.
 3. Grocery List: list and list item workflows with mobile-first Razor UI.
 4. Purchases and Price History: manual purchase entry and basic price history.
 5. Running-Low: deterministic suggestions on home/list experiences.
 6. MVP Hardening: authorization review, anti-forgery review, mobile usability pass, release checklist verification.

 Post-MVP resumes after that in the backlog-defined order, especially product catalog/barcode work and dedicated shopping mode.

 ### Phase 0 — Repository and Baseline
 1. Create `CartWise.sln` and the four projects.
 2. Add project references with clean direction:
@@ -1253,10 +1300,12 @@ Agents must follow this order unless a blocking dependency requires a small adju
 3. Configure nullable reference types.
 4. Configure formatting/analyzers.
 5. Configure PostgreSQL connection through environment/user secrets.
   - For the current MVP, SQLite may be used instead and is preferred for local delivery speed.
 6. Add ASP.NET Core Identity.
 7. Verify app starts and basic test project runs.

 **Exit condition:** authenticated MVC shell runs against PostgreSQL.
 For the current MVP, an authenticated MVC shell running correctly against SQLite is sufficient.

 ### Phase 1 — Household Foundation
 1. ApplicationUser.
@@ -1354,6 +1403,21 @@ Agents must follow this order unless a blocking dependency requires a small adju

 ## 23. Definition of Done for v1

 ### 23A. Definition of Done for the Current MVP

 The current MVP is done when an authenticated household user can:
 1. Register and sign in.
 2. Create and use a household.
 3. Maintain a grocery list from a phone-sized layout.
 4. Add free-text grocery concepts without requiring catalog resolution.
 5. Toggle, skip, edit, or delete list items as required by the MVP backlog.
 6. Record purchase prices manually.
 7. See basic personal price history.
 8. Receive deterministic running-low suggestions from purchase history.
 9. Use the application locally with SQLite and without retailer integrations, barcode scanning, or external product providers.

 For the current MVP, use `docs/release-mvp-checklist.md` as the practical release gate.

 CartWise v1 is done when an authenticated household can:

 1. Create/use a household.
@@ -1401,20 +1465,21 @@ Architectural seams may be left for later, but do not build speculative systems.
 1. Read this file before changing architecture.
 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.
 4. Review `docs/decision-log.md` before changing near-term MVP scope or delivery assumptions.
 5. Inspect existing code before creating parallel abstractions.
 6. Prefer extending existing patterns over inventing new ones.
 7. Keep controllers thin.
 8. Keep persistence code out of Razor views and controllers.
 9. Keep external provider response types inside Infrastructure.
 10. Add tests for business rules and bug fixes.
 11. Run build/tests after meaningful changes.
 12. Do not silently change database semantics.
 13. Create migrations for schema changes; never hand-edit production schema.
 14. 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.
 16. Preserve backward-compatible URLs where practical once routes ship.
 17. Use comments for why, not obvious what.
 18. Prefer clear conventional C# over clever abstraction.

 ---

--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,33 +1,66 @@
 # CLAUDE.md — CartWise v1 Development Guide
 # CLAUDE.md - CartWise MVP Development Guide

 ## Read First

 This repository builds **CartWise**, a mobile-first grocery companion implemented as a conventional **ASP.NET Core MVC** application.

 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.
 Read these files before making substantial changes:
 - `AGENTS.md` for the canonical product and architecture rules
 - `docs/scrum-backlog.md` for the living backlog and current execution plan
 - `docs/decision-log.md` for accepted scope and delivery decisions
 - `docs/release-mvp-checklist.md` for MVP completion criteria

 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. Do not keep meaningful implementation progress only in chat.

 Use `docs/scrum-backlog.md` as the shared execution tracker for epics, stories, and tasks rather than keeping implementation progress only in chat.
 ---

 ## Current Delivery Context

 The current target is a **local MVP by September 10, 2026**.

 This repository is optimized for a **solo founder + AI** delivery model:
 - the founder acts as product owner, reviewer, and primary QA
 - AI helps with scaffolding, implementation, refactoring, and documentation
 - scope control matters more than feature breadth

 When in doubt, choose the **smallest working vertical slice** that moves MVP forward.

 ---

 ## Backlog Workflow
 ## MVP Scope

 The current MVP must allow a user to:
 1. Register and sign in
 2. Create a household
 3. Maintain one active shared grocery list
 4. Add free-text grocery items without requiring product resolution
 5. Toggle, skip, edit, or delete list items as needed by the MVP backlog
 6. Record purchases manually
 7. View basic personal price history
 8. See deterministic running-low suggestions
 9. Use the main flows on a phone-sized layout

 For MVP, CartWise must still be useful with:
 - zero retailer API access
 - zero barcode scanning
 - zero external product providers
 - local-first development and verification

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

 ## Explicitly Post-MVP

 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
 Unless the user explicitly changes scope, these are not MVP blockers:
 - barcode scanning
 - camera scan flows
 - Open Food Facts integration
 - USDA integration
 - dedicated shopping mode page
 - hosted deployment
 - production PostgreSQL setup
 - advanced product preference workflows beyond what the backlog marks as MVP

 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
 If a request touches one of these areas, check `docs/scrum-backlog.md` first and keep the work aligned with its `Release`, `Priority`, and `Decision Gate` notes.

 ---

@@ -42,463 +75,280 @@ Use:
 - jQuery
 - vanilla JavaScript
 - EF Core
 - PostgreSQL
 - SQLite for MVP and local development
 - ASP.NET Core Identity

 Do not introduce React, Vue, Angular, Blazor, MAUI, Flutter, SPA architecture, microservices, MediatR, or unnecessary repository/unit-of-work wrappers unless explicitly requested.

 ---

 ## Product Goal

 CartWise v1 must help a household:

 1. Maintain a shared grocery list.
 2. Add generic concepts such as “milk” without requiring exact product selection.
 3. Resolve exact packaged products when useful.
 4. Scan UPC/GTIN barcodes.
 5. Record purchases and prices.
 6. Build personal price history.
 7. Show typical/low/latest/unit price intelligence.
 8. Suggest repeat items that are likely running low.
 9. Shop from a simple phone-friendly shopping mode.

 CartWise must still be useful with **zero retailer API access**.
 Plan for later, but do not optimize for now:
 - PostgreSQL for hosted production
 - external product providers
 - scan workflows

 Do not introduce without explicit approval:
 - React
 - Vue
 - Angular
 - Blazor
 - .NET MAUI
 - Flutter
 - SPA architecture
 - microservices
 - MediatR
 - generic repository abstractions added only for pattern compliance

 ---

 ## Architectural Boundaries
 ## Architecture Boundaries

 ### Web
 `CartWise.Web`
 - Controllers
 ### `CartWise.Web`
 Owns:
 - MVC controllers
 - Razor Views
 - ViewModels
 - HTML/CSS/JS
 - ASP.NET-specific concerns

 ### Application
 `CartWise.Application`
 - use cases
 ### `CartWise.Application`
 Owns:
 - use-case orchestration
 - services
 - interfaces
 - validation
 - DTOs/results
 - DTOs and results

 ### Domain
 `CartWise.Domain`
 ### `CartWise.Domain`
 Owns:
 - entities
 - enums
 - value objects
 - business rules
 - business rules and invariants

 No EF Core, HTTP, Razor, or provider SDK dependencies here.
 Do not place EF Core, Razor, HTTP, or provider SDK concerns here.

 ### Infrastructure
 `CartWise.Infrastructure`
 ### `CartWise.Infrastructure`
 Owns:
 - DbContext
 - EF configurations/migrations
 - PostgreSQL
 - Open Food Facts/USDA integrations
 - future retailer adapters

 Dependency direction should remain clean.

 ---

 ## Critical Domain Distinction

 Never collapse these concepts:

 ```text
 GroceryConcept: Peanut Butter

 Product: Jif Creamy Peanut Butter 16 oz
 - EF configurations and migrations
 - SQLite persistence for MVP
 - future PostgreSQL migration path
 - external integrations when they are actually implemented

 ProductIdentifier: UPC/GTIN identifying that package
 ```

 A shopping list item may exist with only free text / concept data. Product resolution must not be mandatory to make a useful list.

 UPC/GTIN is never the Product primary key.

 ---

 ## Core Entities

 Implement in the order given in `AGENTS.md`.

 ### Identity / Household
 - ApplicationUser
 - Household
 - HouseholdMember

 ### Product Catalog
 - GroceryConcept
 - ProductCategory
 - Brand
 - Product
 - ProductIdentifier
 - HouseholdProductPreference

 ### Shopping
 - ShoppingList
 - ShoppingListItem

 ### Retail / Location
 - Retailer
 - StoreLocation

 ### History
 - Purchase
 - PurchaseItem
 - PriceObservation

 See `AGENTS.md` for exact fields, indexes, enums, and relationships.
 Keep dependency direction clean.

 ---

 ## Required Services

 Keep controllers thin and use:

 - `IHouseholdService`
 - `IShoppingListService`
 - `IProductService`
 - `IProductEnrichmentService`
 - `IPriceService`
 - `IPurchaseService`
 - `IReplenishmentService`
 - `IShoppingModeService`
 - `IStoreService`

 Do not create one giant `CartWiseService`.

 Do not add abstractions without a real responsibility or testability benefit.

 ---

 ## Product Provider Rule

 External provider models stay inside Infrastructure.

 Use a normalized contract similar to:

 ```csharp
 public interface IProductDataProvider
 {
    string Name { get; }

    Task<ProductLookupResult?> FindByBarcodeAsync(
        string barcode,
        CancellationToken cancellationToken = default);

    Task<IReadOnlyList<ProductSearchResult>> SearchAsync(
        string query,
        CancellationToken cancellationToken = default);
 }
 ```
 ## Backlog Workflow

 Lookup is always **local first**, provider second, then normalize and cache.
 Before implementation work:
 1. Read the relevant epic and story in `docs/scrum-backlog.md`.
 2. Confirm the story is still in MVP scope if the work is intended for the current release.
 3. Check `docs/decision-log.md` for any accepted constraints.
 4. Refine or add concrete tasks in the backlog if new implementation work is discovered.

 Open Food Facts should be the first packaged-product provider. USDA can enrich generic/nutrition data later.
 While implementing:
 1. Keep backlog task wording specific and implementation-oriented.
 2. Update `docs/scrum-backlog.md` if work is split, deferred, blocked, or completed.
 3. Keep repository state and backlog state aligned.
 4. Do not silently expand scope beyond the current story.

 Never expose an external provider's API response object to a controller or Razor view.
 After implementing:
 1. Mark completed tasks in `docs/scrum-backlog.md`.
 2. Add a brief note if a story is effectively complete.
 3. Update `docs/decision-log.md` if a meaningful product or architecture decision was made.
 4. Check `docs/release-mvp-checklist.md` when the work affects launch readiness.

 ---

 ## Retailer API Rule
 ## Solo-Founder Working Rules

 Retailer integrations are optional.
 Optimize for finishing, not for theoretical completeness.

 Do not build application logic around specific retailer names. Use capability-aware adapters.
 Prefer:
 - one active story at a time
 - thin vertical slices
 - explicit acceptance criteria
 - simple database and hosting assumptions during MVP
 - reusable services only when they solve a real current need

 Never assume that price, inventory, promotions, or aisle data are available.
 Avoid:
 - speculative abstractions
 - premature generalization
 - building post-MVP capabilities during MVP work
 - “while I’m here” feature expansion
 - large refactors unless they unblock current backlog work

 When data is stale or unavailable, show that state explicitly instead of guessing.
 If a story feels larger than a day or two, split it before implementing.

 ---

 ## MVC Routes

 Preserve these route intentions unless existing code requires a compatible adjustment.

 ```text
 GET  /                         Home
 GET  /household               Household
 GET  /list                    Active grocery list
 POST /list/items              Add list item
 POST /list/items/{id}/toggle  Toggle purchased
 POST /list/items/{id}/skip
 POST /list/items/{id}/delete

 GET  /products/{id}
 GET  /products/search?q=
 GET  /products/barcode/{barcode}

 GET  /scan

 GET  /shopping/start
 POST /shopping/items/{id}/purchase
 POST /shopping/items/{id}/skip
 POST /shopping/items/{id}/unavailable
 POST /shopping/items/{id}/substitute
 POST /shopping/complete

 GET  /prices
 GET  /prices/product/{productId}
 POST /prices/product/{productId}/observe

 GET  /purchases
 GET  /purchases/{id}
 ```

 Use `/api/...` only where browser JavaScript genuinely benefits from JSON.
 ## Domain Priorities For MVP

 ### Household
 Keep household isolation correct from the start.
 - do not trust posted household ids alone
 - validate membership server-side
 - prevent IDOR on household-scoped resources

 ### Shopping List
 The list is the center of MVP value.
 - free-text entry must work well
 - product resolution must not be required
 - mobile usability matters
 - one active list is enough for MVP

 ### Purchases and Prices
 Manual capture is acceptable for MVP.
 - a purchase flow does not need scan support
 - price history must be trustworthy
 - `PriceObservation` remains append-only
 - show latest, average, and lowest where data supports it

 ### Running Low
 Keep suggestions deterministic and explainable.
 - use purchase dates
 - use interval calculations
 - prefer median when enough history exists
 - never auto-add predicted items to the list

 ---

 ## Razor / JavaScript Rules

 Razor is primary rendering. jQuery and vanilla JavaScript are both approved.

 Prefer jQuery for:
 - DOM selection and manipulation
 - delegated event handlers
 - form serialization
 - AJAX requests
 - lightweight partial refreshes
 - shopping-mode UI interactions
 ## Data and Persistence Rules

 Prefer vanilla JavaScript for:
 - barcode camera/scanner browser APIs
 - `navigator.mediaDevices`
 - IndexedDB and Service Workers
 - focused browser-native functionality where jQuery adds no value
 For MVP:
 - use SQLite
 - create EF Core migrations for schema changes
 - use explicit entity configurations
 - avoid lazy loading
 - use `AsNoTracking()` for read-heavy paths where appropriate
 - protect historical data from accidental cascade deletion
 - treat `PriceObservation` as append-only history

 Organize JavaScript under:

 ```text
 wwwroot/js/pages/
 wwwroot/js/services/
 wwwroot/js/components/
 wwwroot/js/utils/
 ```

 Do not create a global monolithic `app.js`.
 Do not reinvent client-side framework patterns by hand.
 Do not mix jQuery and native DOM approaches arbitrarily inside the same function.
 Use `$.ajax`/`$.get`/`$.post` where jQuery is the clearer choice and `fetch` where native code is more appropriate.

 Use anti-forgery tokens for every state-changing JavaScript request.
 If a future PostgreSQL move affects a current design choice, note it in `docs/decision-log.md` rather than overengineering now.

 ---

 ## Database Rules
 ## Security Rules

 - PostgreSQL UUID domain keys.
 - Identity's normal user key can remain its native string unless deliberately changed project-wide.
 - UTC timestamps / timestamptz.
 - decimal/numeric for money and quantities.
 - no float/double for prices.
 - explicit EF entity configurations.
 - no lazy loading.
 - `AsNoTracking()` for read paths.
 - protect historical data from accidental cascade deletion.
 - `PriceObservation` is append-only.
 - add indexes described in `AGENTS.md`.
 Always enforce:
 - ASP.NET Core Identity for authentication
 - anti-forgery protection on state-changing MVC requests
 - server-side validation
 - household-scoped authorization checks
 - safe handling of secrets and local configuration

 Every schema change requires an EF Core migration.
 Never:
 - trust client-supplied household ownership
 - expose secrets to client-side JavaScript
 - skip authorization because the app is currently local-only

 ---

 ## Price Intelligence

 Do not call a stale observation a current price.

 Every price observation includes:
 - Product
 - optional Store
 - Price/SalePrice
 - ObservedUtc
 - SourceType
 - ConfidenceScore

 Display source/freshness where material.
 ## UI Rules

 For a household's typical price, favor median as the robust statistic; average may also be shown.
 Keep UI:
 - server-rendered first
 - mobile-first
 - touch-friendly on phone-sized layouts
 - progressively enhanced with jQuery or small vanilla JS modules

 Only label a price “good” after enough history exists.
 Do not turn the app into a client-side SPA.

 Unit price comparisons must use compatible units.
 Use JavaScript to enhance workflows, not replace Razor as the primary application shell.

 ---

 ## Replenishment Algorithm v1
 ## Validation and Testing

 No ML or LLM required.
 Before claiming work complete, prefer to verify:
 - valid input succeeds
 - invalid input fails clearly
 - household isolation holds
 - state-changing actions require anti-forgery coverage
 - impacted tests pass

 Use purchase history:
 1. get recent purchase dates
 2. calculate intervals
 3. use median interval when enough data exists
 4. estimate next due date
 5. return a suggestion with confidence and reason
 When implementing business rules or bug fixes, add or update tests.

 Never automatically add predicted groceries to the list. The user chooses.
 When data model changes, verify migrations are included.

 ---

 ## Authorization

 Household isolation is critical.

 For every household-scoped resource:
 - derive or validate household context server-side
 - verify current user membership
 - do not trust posted HouseholdId alone
 - prevent IDOR

 Use centralized household authorization/service logic.

 All state-changing MVC requests require anti-forgery protection.
 Do not claim a feature works if the relevant build or tests were not run when the environment makes them available.

 ---

 ## Working Style for Claude

 Before modifying code:
 1. Read `AGENTS.md`.
 2. Inspect the relevant existing controller/service/entity/configuration/tests.
 3. Identify the smallest vertical change that satisfies the request.
 4. Preserve existing architecture unless it conflicts with the specification.

 While implementing:
 1. Keep methods small and intention-revealing.
 2. Prefer conventional C#.
 3. Use async I/O.
 4. Pass `CancellationToken` through external/database-heavy application paths where appropriate.
 5. Add validation close to the boundary and invariants in the domain where appropriate.
 6. Avoid duplicate normalization or authorization logic.

 After implementing:
 1. Build the solution.
 2. Run relevant tests.
 3. Run the full test suite when practical.
 4. Check migrations when data model changes.
 5. Report files changed and any intentionally deferred work.
 ## Recommended MVP Build Order

 Do not claim a feature works without running the relevant build/tests when the environment permits it.
 Follow this order unless the user explicitly reprioritizes:

 ---

 ## Exact Build Order

 Follow this progression:

 ### 0. Baseline
 - solution/projects
 - dependencies
 - PostgreSQL
 ### 1. Foundation
 - solution and projects
 - SQLite wiring
 - Identity
 - test harness
 - baseline test harness

 ### 1. Household
 ### 2. Household
 - household entities
 - membership
 - authorization
 - create/select household

 ### 2. Grocery List
 - concepts/categories
 - list/list items
 - add/toggle/delete
 - mobile Razor view

 ### 3. Products and Scan
 - brand/product/identifiers
 - household product preferences
 - local product lookup
 - Open Food Facts provider
 - barcode scan page

 ### 4. Purchase and Price History
 - retailer/store
 - purchase/purchase item
 - price observations
 - price service and views
 - membership and authorization
 - create household flow

 ### 5. Shopping Mode
 - grouped mobile list
 - purchase/skip/unavailable
 - optional entered price
 - complete trip
 ### 3. Grocery List
 - grocery concepts and categories as needed for MVP
 - list and list items
 - add, edit, toggle, skip, delete
 - mobile list UI

 ### 6. Running Low
 ### 4. Purchases and Price History
 - purchase and purchase item flows
 - price observations
 - basic price history views

 ### 5. Running Low
 - deterministic replenishment service
 - suggestions on Home/List
 - home and list suggestions

 ### 7. Polish
 - accessibility
 - mobile/responsive testing
 - performance
 - PWA/offline only when core workflows are stable
 ### 6. MVP Hardening
 - authorization review
 - anti-forgery review
 - mobile usability pass
 - local release checklist verification

 Do not jump to Phase 6 features while Phase 2 is incomplete unless the user explicitly requests it.
 Post-MVP resumes after that.

 ---

 ## First End-to-End Slice

 When asked to begin implementation, build this before broad scaffolding:
 When starting implementation, prove the foundation with a small working path:

 ```text
 Register/Login
  -> Create Household
  -> Open /list
  -> Add “Milk”
  -> Add "Milk"
  -> Persist item
  -> Toggle Purchased
  -> Reload
  -> Verify correct household-scoped state
 ```

 This proves authentication, household authorization, EF persistence, MVC routing, Razor rendering, and form/JS behavior.

 ---

 ## Out of Scope Unless Explicitly Added

 Do not implement proactively:
 - meal planning
 - recipes
 - AI chat
 - nutrition optimization
 - receipt OCR
 - coupon clipping
 - retailer loyalty accounts
 - delivery/checkout
 - live universal inventory
 - store aisle maps
 - indoor navigation
 - multi-store routing
 - shrinkflation analysis
 - push notifications

 Leave clean seams for future work; do not build speculative infrastructure.
 This gives an early proof of:
 - authentication
 - household authorization
 - EF persistence
 - MVC routing
 - Razor rendering
 - state changes on the core list workflow

 ---

 ## Definition of a Good CartWise Change

 A good change:
 - improves the shopper's grocery memory
 - keeps MVC server-rendered
 - works on a phone
 - does not require a retailer API unless specifically implementing one
 - preserves price source/freshness
 - maintains household isolation
 - adds tests for meaningful rules
 - avoids unnecessary framework or architecture expansion
 ## Definition Of A Good Change

 A good CartWise change:
 - advances the current MVP backlog
 - improves the household grocery-memory workflow
 - keeps MVC server-rendered first
 - works on a phone-sized layout
 - preserves household isolation
 - keeps price history trustworthy
 - avoids unnecessary architecture expansion
 - updates backlog or decision docs when needed

 North star:

--- a/README.md
+++ b/README.md
@@ -48,7 +48,8 @@ The following are explicitly out of scope for v1 unless requirements change:
 - jQuery
 - Vanilla JavaScript
 - Entity Framework Core
 - PostgreSQL
 - SQLite for MVP and local development
 - PostgreSQL planned for later hosted production use
 - ASP.NET Core Identity

 ### Architecture
@@ -141,13 +142,15 @@ tests/

 ## Development Status

 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.
 This repository is being initialized from the `AGENTS.md` build specification. The current focus is a solo-founder MVP targeted for local completion by **September 10, 2026**.

 ## 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`
 - Key product and scope decisions live in `docs/decision-log.md`
 - MVP completion criteria live in `docs/release-mvp-checklist.md`
 - Update `docs/scrum-backlog.md` as stories and tasks move into active work and when work is completed

 ## Getting Started
@@ -155,9 +158,9 @@ This repository is being initialized from the `AGENTS.md` build specification. T
 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:

 1. Install the .NET SDK
 2. Install PostgreSQL
 3. Configure connection settings via environment variables or user secrets
 4. Run EF Core migrations
 2. Use SQLite for local MVP development
 3. Configure connection settings via environment variables, app settings, or user secrets as needed
 4. Run EF Core migrations or schema creation steps
 5. Start the ASP.NET Core MVC app

 Example commands that will be used once the solution exists:
@@ -176,7 +179,7 @@ The team plans to manage this project using Scrum with:
 - Epics aligned to the implementation phases
 - User stories for each feature slice
 - Tasks under each story for development, testing, and UI work
 - Two-week sprints
 - A solo weekly planning cadence with one active story at a time
 - A definition of done that includes tests, authorization, validation, and logging

 ## Security and Data Principles
--- a/docs/decision-log.md
+++ b/docs/decision-log.md
@@ -0,0 +1,90 @@
 # CartWise Decision Log

 ## Purpose

 This file records product, scope, architecture, and delivery decisions for CartWise so a solo founder + AI workflow does not repeatedly revisit the same unresolved questions.

 ## How To Use

 - Add a new entry when a decision changes backlog scope, technical direction, or release timing
 - Keep entries short and explicit
 - Reference related backlog stories in `docs/scrum-backlog.md` when helpful
 - Update an existing entry only to add a superseding decision or revisit trigger

 ## Entry Template

 ```md
 ### DEC-XXX - Short title
 - Date: YYYY-MM-DD
 - Status: Proposed | Accepted | Superseded
 - Decision: One-sentence summary
 - Reason: Why this was chosen
 - Impact: What changes in the backlog, implementation, or release plan
 - Revisit Trigger: What would cause this to be reconsidered
 ```

 ## Decisions

 ### DEC-001 - MVP target and launch window
 - Date: 2026-08-10
 - Status: Accepted
 - Decision: Target a local MVP completion by September 10, 2026.
 - Reason: A one-month deadline forces scope discipline and creates a practical solo-founder release target.
 - Impact: Only `MVP` and `P0` backlog work should be treated as launch-critical.
 - Revisit Trigger: The MVP cut changes or the launch target date moves.

 ### DEC-002 - Delivery model
 - Date: 2026-08-10
 - Status: Accepted
 - Decision: Use a solo founder + AI delivery model with the founder acting as product owner, reviewer, and primary QA.
 - Reason: AI can accelerate implementation, but final product judgment and local verification remain human responsibilities.
 - Impact: Backlog items must stay small, explicit, and easy to verify locally.
 - Revisit Trigger: Additional human contributors join active development.

 ### DEC-003 - Barcode scanning is out of MVP
 - Date: 2026-08-10
 - Status: Accepted
 - Decision: Barcode scanning, camera workflows, and scan-page work are deferred until after MVP.
 - Reason: These features add complexity and are not required for the first launchable grocery-memory workflow.
 - Impact: `CW-EPIC-04` barcode and scan stories remain `Post-MVP` or `Deferred`.
 - Revisit Trigger: Core MVP is stable and there is time to add scan functionality.

 ### DEC-004 - External product providers are out of MVP
 - Date: 2026-08-10
 - Status: Accepted
 - Decision: Open Food Facts, USDA, and other external provider integrations are deferred until after MVP.
 - Reason: Manual and local-only workflows are sufficient for MVP and reduce dependency risk.
 - Impact: Provider-related backlog stories remain `Deferred` or `Post-MVP`.
 - Revisit Trigger: MVP is complete and product resolution becomes the next highest-value feature.

 ### DEC-005 - SQLite for MVP development
 - Date: 2026-08-10
 - Status: Accepted
 - Decision: Use SQLite for MVP and local development instead of PostgreSQL.
 - Reason: SQLite lowers setup friction and is better suited for a fast local-first development loop.
 - Impact: Foundation stories should wire SQLite first while keeping a future PostgreSQL path possible.
 - Revisit Trigger: Hosted or multi-user production deployment becomes the priority.

 ### DEC-006 - Local-first release strategy
 - Date: 2026-08-10
 - Status: Accepted
 - Decision: Build and validate the app locally before any public deployment work.
 - Reason: Local-first release reduces operational complexity during MVP delivery.
 - Impact: Public hosting, infrastructure, and deployment work are not launch blockers for the current MVP.
 - Revisit Trigger: Local MVP is stable and ready for broader testing.

 ### DEC-007 - Shopping mode may be deferred
 - Date: 2026-08-10
 - Status: Accepted
 - Decision: A dedicated shopping mode page is post-MVP unless the standard list page proves insufficient.
 - Reason: A mobile-friendly list can satisfy core purchase flow needs with less implementation overhead.
 - Impact: `CW-EPIC-06` is treated as post-MVP for now.
 - Revisit Trigger: MVP list flow cannot support practical in-store use.

 ### DEC-008 - Manual purchase flow is acceptable for MVP
 - Date: 2026-08-10
 - Status: Accepted
 - Decision: Manual purchase entry is acceptable for MVP even if list-to-purchase linkage is simplified at first.
 - Reason: Price history and replenishment value can be delivered without sophisticated scan or shopping workflows.
 - Impact: Purchase and price stories stay in MVP while more advanced purchase linkage can evolve later.
 - Revisit Trigger: Manual purchase entry creates too much friction during testing.
--- a/docs/release-mvp-checklist.md
+++ b/docs/release-mvp-checklist.md
@@ -0,0 +1,62 @@
 # CartWise MVP Release Checklist

 ## Target

 Local MVP ready by **September 10, 2026**.

 ## Scope Guardrail

 This checklist applies only to the MVP scope currently defined in `docs/scrum-backlog.md`. Post-MVP work such as barcode scanning, external product providers, and a dedicated shopping mode page should not block MVP completion.

 ## Product Outcomes

 - [ ] User can register and sign in
 - [ ] User can create a household
 - [ ] User can access only their own household-scoped data
 - [ ] User can create or access one active grocery list
 - [ ] User can add free-text grocery items
 - [ ] User can edit, toggle, skip, or delete grocery items as required by MVP
 - [ ] User can manually record a purchase
 - [ ] User can view basic price history for purchased items
 - [ ] User can see running-low suggestions from purchase history
 - [ ] Core list and purchase flows are usable on a phone-sized layout

 ## Technical Outcomes

 - [ ] Solution builds locally
 - [ ] Tests for implemented business rules pass locally
 - [ ] SQLite is wired and used for MVP development
 - [ ] Migrations or schema creation flow are documented and verified
 - [ ] Anti-forgery protection is enforced on state-changing requests
 - [ ] Household authorization is enforced on every household-scoped workflow
 - [ ] Validation messages are shown for key invalid inputs
 - [ ] Logging exists for meaningful failures and authorization issues

 ## Verification Steps

 - [ ] Start from a clean local setup
 - [ ] Create a new user account
 - [ ] Create a household
 - [ ] Add several grocery list items
 - [ ] Mark at least one item purchased
 - [ ] Record a manual purchase with price data
 - [ ] Confirm price history appears correctly
 - [ ] Confirm running-low logic works with seeded or test purchase history
 - [ ] Confirm unauthorized household access is blocked
 - [ ] Confirm layout is acceptable on a phone-sized viewport

 ## Non-Blocking Items For MVP

 These may remain unfinished without blocking MVP signoff:

 - [ ] Barcode scanning
 - [ ] Open Food Facts integration
 - [ ] USDA integration
 - [ ] Camera scan page
 - [ ] Dedicated shopping mode page
 - [ ] Hosted deployment
 - [ ] Production PostgreSQL setup

 ## Release Decision

 - [ ] MVP accepted for local release and continued post-MVP iteration
--- a/docs/scrum-backlog.md
+++ b/docs/scrum-backlog.md
@@ -4,26 +4,28 @@

 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.

 This backlog is optimized for a solo founder + AI delivery model targeting a local MVP by **September 10, 2026**.

 ## 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
 ### Solo 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
 - Planning cadence: weekly
 - Delivery rhythm: one active story at a time
 - Daily check-in: review top 3 priorities and blockers
 - Backlog refinement: once per week
 - Review/demo: every Friday
 - Retrospective: every 2 weeks

 ### Roles
 ### Working Model

 - **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
 - **Founder / Product Owner**: prioritizes scope, clarifies acceptance criteria, reviews AI output, and decides trade-offs
 - **AI Development Partner**: scaffolds, implements, documents, and proposes follow-up tasks within approved scope
 - **Primary QA**: founder validates behavior locally before marking stories done

 ### Board Columns

@@ -37,9 +39,9 @@ CartWise is a mobile-first grocery companion web app that helps households remem

 ### 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
 - Use `XS`, `S`, `M`, and `L` sizing on stories
 - Split any story larger than `L` before implementation
 - Track tasks as checklist items and keep them aligned with the repository state

 ## Definitions

@@ -73,24 +75,42 @@ A story is done when:
 - 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

 ## Release Strategy

 - `Release: MVP` means required for the local launch target by **September 10, 2026**
 - `Release: Post-MVP` means explicitly deferred until after MVP is stable
 - `Release: Deferred` means do not implement unless scope changes
 - `Priority: P0` means must ship for MVP
 - `Priority: P1` means valuable next but can slip
 - `Priority: P2` means later or exploratory
 - `Effort: XS` under 2 hours, `S` about half a day, `M` about a day, `L` 2 or more days
 - `Decision Gate` calls out places where the founder must make a product or architecture decision before implementation continues

 ## Epic Roadmap

 ### MVP Release
 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
 4. `CW-EPIC-05` Stores, Purchases, and Price Intelligence
 5. `CW-EPIC-07` Running-Low Suggestions
 6. Selected hardening work from `CW-EPIC-08`

 ### Post-MVP Release
 1. `CW-EPIC-04` Product Catalog and Barcode Resolution
 2. `CW-EPIC-06` Shopping Mode
 3. Remaining polish work from `CW-EPIC-08`

 ---

 ## `CW-EPIC-01` Platform Foundation

 **Goal:** establish the solution structure, authentication, PostgreSQL wiring, and baseline engineering standards.
 **Goal:** establish the solution structure, authentication, SQLite wiring for MVP, and baseline engineering standards.

 ### `CW-STORY-01.1` Create solution skeleton
 **Release:** MVP  
 **Priority:** P0  
 **Effort:** S
 **User story:** As a developer, I want the CartWise solution scaffolded so the app follows a clean modular architecture.

 **Acceptance criteria**
@@ -112,23 +132,31 @@ A story is done when:
 - [ ] Enable nullable reference types

 ### `CW-STORY-01.2` Configure application startup
 **Release:** MVP  
 **Priority:** P0  
 **Effort:** M
 **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
 - SQLite connection is configurable for MVP
 - PostgreSQL migration path remains possible later

 **Tasks**
 - [ ] Configure MVC services and middleware
 - [ ] Add base layout and navigation shell
 - [ ] Organize `wwwroot` structure
 - [ ] Add configuration bindings
 - [ ] Wire PostgreSQL connection string
 - [ ] Wire SQLite connection string for MVP
 - [ ] Note PostgreSQL transition path in docs
 - [ ] Verify local app startup

 ### `CW-STORY-01.3` Add Identity authentication
 **Release:** MVP  
 **Priority:** P0  
 **Effort:** M
 **User story:** As a user, I want to sign in so my household data is protected.

 **Acceptance criteria**
@@ -144,6 +172,9 @@ A story is done when:
 - [ ] Verify login and logout flow

 ### `CW-STORY-01.4` Establish engineering baseline
 **Release:** MVP  
 **Priority:** P1  
 **Effort:** S
 **User story:** As a team, we want build and test standards so changes remain stable over time.

 **Acceptance criteria**
@@ -164,6 +195,9 @@ A story is done when:
 **Goal:** enable household creation, membership, and household-scoped authorization.

 ### `CW-STORY-02.1` Model households and membership
 **Release:** MVP  
 **Priority:** P0  
 **Effort:** S
 **User story:** As a developer, I want household entities persisted so household features have a secure foundation.

 **Acceptance criteria**
@@ -180,6 +214,9 @@ A story is done when:
 - [ ] Add domain tests

 ### `CW-STORY-02.2` Implement household service
 **Release:** MVP  
 **Priority:** P0  
 **Effort:** M
 **User story:** As a developer, I want household operations centralized so controllers stay thin and rules stay testable.

 **Acceptance criteria**
@@ -196,6 +233,9 @@ A story is done when:
 - [ ] Add application tests

 ### `CW-STORY-02.3` Build household UI
 **Release:** MVP  
 **Priority:** P0  
 **Effort:** S
 **User story:** As a user, I want to create and view my household so I can begin using CartWise.

 **Acceptance criteria**
@@ -212,6 +252,9 @@ A story is done when:
 - [ ] Add redirect flow after creation

 ### `CW-STORY-02.4` Enforce household authorization
 **Release:** MVP  
 **Priority:** P0  
 **Effort:** S
 **User story:** As a user, I want household data isolated so other users cannot access it.

 **Acceptance criteria**
@@ -232,6 +275,9 @@ A story is done when:
 **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
 **Release:** MVP  
 **Priority:** P0  
 **Effort:** M
 **User story:** As a developer, I want shopping list entities defined so shared list workflows can be persisted.

 **Acceptance criteria**
@@ -250,6 +296,9 @@ A story is done when:
 - [ ] Create migration

 ### `CW-STORY-03.2` Implement active shopping list service
 **Release:** MVP  
 **Priority:** P0  
 **Effort:** S
 **User story:** As a user, I want my household to have an active grocery list so shared planning is easy.

 **Acceptance criteria**
@@ -265,6 +314,9 @@ A story is done when:
 - [ ] Add application tests

 ### `CW-STORY-03.3` Add grocery items quickly
 **Release:** MVP  
 **Priority:** P0  
 **Effort:** S
 **User story:** As a household member, I want to add free-text grocery items quickly so I do not lose shopping intent.

 **Acceptance criteria**
@@ -282,6 +334,9 @@ A story is done when:
 - [ ] Add tests

 ### `CW-STORY-03.4` Update shopping list items
 **Release:** MVP  
 **Priority:** P0  
 **Effort:** M
 **User story:** As a household member, I want to toggle, skip, and delete items so the list stays accurate.

 **Acceptance criteria**
@@ -300,6 +355,9 @@ A story is done when:
 - [ ] Add tests

 ### `CW-STORY-03.5` Deliver a mobile-first list UI
 **Release:** MVP  
 **Priority:** P0  
 **Effort:** S
 **User story:** As a shopper, I want a touch-friendly grocery list so it works well on my phone.

 **Acceptance criteria**
@@ -321,6 +379,10 @@ A story is done when:
 **Goal:** support product identity, household product preferences, and local-first barcode resolution with provider fallback.

 ### `CW-STORY-04.1` Model product catalog entities
 **Release:** Post-MVP  
 **Priority:** P1  
 **Effort:** M  
 **Decision Gate:** Confirm whether a product catalog is still needed before barcode work begins.
 **User story:** As a developer, I want product and identifier entities modeled so products can be resolved independently of UPC.

 **Acceptance criteria**
@@ -339,6 +401,9 @@ A story is done when:
 - [ ] Create migration

 ### `CW-STORY-04.2` Search and view products
 **Release:** Post-MVP  
 **Priority:** P1  
 **Effort:** M
 **User story:** As a user, I want to search and view products so I can understand and choose preferred items.

 **Acceptance criteria**
@@ -356,6 +421,10 @@ A story is done when:
 - [ ] Add tests

 ### `CW-STORY-04.3` Implement barcode lookup flow
 **Release:** Deferred  
 **Priority:** P2  
 **Effort:** M  
 **Decision Gate:** Barcode scanning is out of MVP scope.
 **User story:** As a shopper, I want a barcode lookup flow so known products can be resolved quickly.

 **Acceptance criteria**
@@ -372,6 +441,10 @@ A story is done when:
 - [ ] Add unit and application tests

 ### `CW-STORY-04.4` Integrate Open Food Facts
 **Release:** Deferred  
 **Priority:** P2  
 **Effort:** M  
 **Decision Gate:** External providers are out of MVP scope.
 **User story:** As a developer, I want a provider fallback for unknown products so barcode resolution remains useful.

 **Acceptance criteria**
@@ -387,6 +460,10 @@ A story is done when:
 - [ ] Add tests with mocked provider behavior

 ### `CW-STORY-04.5` Build scan page
 **Release:** Deferred  
 **Priority:** P2  
 **Effort:** M  
 **Decision Gate:** Camera scan flow is out of MVP scope.
 **User story:** As a shopper, I want a camera-based scan page so I can identify products with my phone.

 **Acceptance criteria**
@@ -408,6 +485,10 @@ A story is done when:
 **Goal:** record where purchases happened and build a trustworthy append-only price history.

 ### `CW-STORY-05.1` Model retailers and store locations
 **Release:** MVP  
 **Priority:** P1  
 **Effort:** S  
 **Decision Gate:** Decide whether store tracking in MVP is minimal or omitted from first purchase flow.
 **User story:** As a developer, I want retailer and store entities so purchases can be tied to real locations.

 **Acceptance criteria**
@@ -423,6 +504,9 @@ A story is done when:
 - [ ] Add tests for basic persistence rules

 ### `CW-STORY-05.2` Model purchases and purchase items
 **Release:** MVP  
 **Priority:** P0  
 **Effort:** M
 **User story:** As a developer, I want purchase history modeled so shopping outcomes can be stored.

 **Acceptance criteria**
@@ -439,6 +523,9 @@ A story is done when:
 - [ ] Add tests

 ### `CW-STORY-05.3` Model append-only price observations
 **Release:** MVP  
 **Priority:** P0  
 **Effort:** S
 **User story:** As a developer, I want append-only price observations so historical price facts are preserved.

 **Acceptance criteria**
@@ -454,6 +541,10 @@ A story is done when:
 - [ ] Add tests for append-only behavior

 ### `CW-STORY-05.4` Record household purchases
 **Release:** MVP  
 **Priority:** P0  
 **Effort:** M  
 **Decision Gate:** Decide whether MVP purchase entry must link directly to shopping list items or can begin as a manual flow.
 **User story:** As a shopper, I want to record purchases so CartWise can remember what I bought and what I paid.

 **Acceptance criteria**
@@ -470,6 +561,9 @@ A story is done when:
 - [ ] Add tests

 ### `CW-STORY-05.5` Derive price intelligence
 **Release:** MVP  
 **Priority:** P0  
 **Effort:** M
 **User story:** As a user, I want price history and price insights so I can make better grocery decisions.

 **Acceptance criteria**
@@ -487,6 +581,9 @@ A story is done when:
 - [ ] Add tests for price statistics

 ### `CW-STORY-05.6` Build price views
 **Release:** MVP  
 **Priority:** P0  
 **Effort:** S
 **User story:** As a user, I want a price history screen so I can review what my household typically pays.

 **Acceptance criteria**
@@ -509,6 +606,10 @@ A story is done when:
 **Goal:** provide a simple, touch-friendly in-store workflow for marking progress and recording purchases.

 ### `CW-STORY-06.1` Implement shopping mode service
 **Release:** Post-MVP  
 **Priority:** P1  
 **Effort:** S  
 **Decision Gate:** Decide whether a dedicated shopping mode is needed beyond the list page.
 **User story:** As a developer, I want shopping-mode orchestration so in-store behavior is consistent and testable.

 **Acceptance criteria**
@@ -524,6 +625,9 @@ A story is done when:
 - [ ] Add tests

 ### `CW-STORY-06.2` Build shopping mode UI
 **Release:** Post-MVP  
 **Priority:** P1  
 **Effort:** M
 **User story:** As a shopper, I want a low-noise mobile shopping view so I can use CartWise during a real trip.

 **Acceptance criteria**
@@ -539,6 +643,9 @@ A story is done when:
 - [ ] Add `wwwroot/js/pages/shopping-mode.js`

 ### `CW-STORY-06.3` Support in-store item actions
 **Release:** Post-MVP  
 **Priority:** P1  
 **Effort:** M
 **User story:** As a shopper, I want to mark items purchased, skipped, unavailable, or substituted so the trip stays accurate.

 **Acceptance criteria**
@@ -555,6 +662,9 @@ A story is done when:
 - [ ] Add tests

 ### `CW-STORY-06.4` Record prices while shopping
 **Release:** Post-MVP  
 **Priority:** P1  
 **Effort:** S
 **User story:** As a shopper, I want to optionally enter prices in shopping mode so price history stays current.

 **Acceptance criteria**
@@ -575,6 +685,9 @@ A story is done when:
 **Goal:** use deterministic purchase history to suggest what a household may need soon.

 ### `CW-STORY-07.1` Build replenishment engine
 **Release:** MVP  
 **Priority:** P0  
 **Effort:** M
 **User story:** As a developer, I want deterministic running-low logic so suggestions are explainable and testable.

 **Acceptance criteria**
@@ -593,6 +706,10 @@ A story is done when:
 - [ ] Add tests

 ### `CW-STORY-07.2` Show suggestions on home and list views
 **Release:** MVP  
 **Priority:** P0  
 **Effort:** S  
 **Decision Gate:** Confirm the minimum launch dashboard: active list count, recent prices, and running-low suggestions.
 **User story:** As a user, I want running-low suggestions surfaced in context so I can act on them quickly.

 **Acceptance criteria**
@@ -608,6 +725,9 @@ A story is done when:
 - [ ] Add tests

 ### `CW-STORY-07.3` Add suggestion-to-list workflow
 **Release:** MVP  
 **Priority:** P1  
 **Effort:** S
 **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**
@@ -628,6 +748,9 @@ A story is done when:
 **Goal:** harden the v1 experience for real-world use and release confidence.

 ### `CW-STORY-08.1` Improve mobile usability and accessibility
 **Release:** MVP  
 **Priority:** P1  
 **Effort:** S
 **User story:** As a user, I want the app to be easy to use on my phone and accessible across core workflows.

 **Acceptance criteria**
@@ -643,6 +766,9 @@ A story is done when:
 - [ ] Validate error summaries

 ### `CW-STORY-08.2` Harden security coverage
 **Release:** MVP  
 **Priority:** P0  
 **Effort:** S
 **User story:** As a team, we want security-sensitive paths reviewed so household data remains protected.

 **Acceptance criteria**
@@ -658,6 +784,9 @@ A story is done when:
 - [ ] Add integration tests for protected routes

 ### `CW-STORY-08.3` Add diagnostics and logging
 **Release:** MVP  
 **Priority:** P1  
 **Effort:** S
 **User story:** As a team, we want actionable diagnostics so failures can be understood and fixed quickly.

 **Acceptance criteria**
@@ -672,6 +801,9 @@ A story is done when:
 - [ ] Add basic health-check strategy if included

 ### `CW-STORY-08.4` Seed realistic development data
 **Release:** Post-MVP  
 **Priority:** P2  
 **Effort:** M
 **User story:** As a developer, I want realistic sample data so workflows can be tested quickly during development.

 **Acceptance criteria**
@@ -690,34 +822,28 @@ A story is done when:

 ---

 ## Suggested Sprint Sequence
 ## Suggested 30-Day Delivery Sequence

 ### Sprint 1
 ### Week 1 - Foundation
 - `CW-EPIC-01` Platform Foundation
 - Start `CW-EPIC-02` Household and Access Control

 ### Sprint 2
 ### Week 2 - Shared List
 - 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
 - Start and finish core stories in `CW-EPIC-03` Smart Shopping List

 ### Sprint 6
 - `CW-EPIC-06` Shopping Mode
 ### Week 3 - Purchases and Price History
 - Deliver `CW-EPIC-05` MVP stories

 ### Sprint 7
 - `CW-EPIC-07` Running-Low Suggestions
 ### Week 4 - Running Low and Hardening
 - Deliver `CW-EPIC-07` MVP stories
 - Deliver selected `CW-EPIC-08` hardening stories
 - Run local MVP release checklist

 ### Sprint 8
 - `CW-EPIC-08` UX Polish, Security, and Release Readiness
 - Stabilization and release verification
 ### After MVP
 - Resume `CW-EPIC-04` Product Catalog and Barcode Resolution
 - Resume `CW-EPIC-06` Shopping Mode
 - Complete remaining polish work in `CW-EPIC-08`

 ## Story Template