CartWise/docs/scrum-backlog.md

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:

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