# 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