Initial commit

examples/pantry-planner/specs/001-pantry-meal-planner/checklists/requirements.md

@@ -0,0 +1,13 @@
+# Quality Checklist: 001-pantry-meal-planner
+
+*Created: 2026-08-18*
+
+Reviewer-owned quality gate for the written requirements — these boxes judge
+the spec text, not the implementation. Check an item only after actually
+reviewing it; add domain-specific items freely.
+
+- [x] Every user story has at least one concrete acceptance scenario
+- [x] Each requirement is verifiable (a test could pass or fail it)
+- [x] Success criteria are measurable without naming technologies
+- [x] All clarification markers are resolved or consciously accepted
+- [ ] Assumptions state the chosen default AND what was ruled out

examples/pantry-planner/specs/001-pantry-meal-planner/plan.md

@@ -0,0 +1,33 @@
+# Implementation Plan: 001-pantry-meal-planner
+
+*Created: 2026-08-18*
+
+Turn the spec into concrete technical decisions. Stay minimal: prefer the
+simplest structure that satisfies the spec, and justify anything that isn't.
+
+## Technical Context
+
+- Language: Python 3 (stdlib only)
+- Dependencies: none at runtime; pytest for tests
+- Storage: two JSON files in the project dir — pantry.json, recipes.json
+  (starter set written on first run)
+- Testing: pytest, TDD; planner logic tested against handwritten pantries
+
+## Structure
+
+```
+pantry_planner/
+  planner.py      # pantry CRUD, plan generation, shopping list derivation
+  cli.py          # argparse: pantry add/remove/list, plan, shoplist
+  recipes.json    # bundled starter set (10 recipes)
+  tests/test_planner.py
+```
+
+## Decisions
+
+- D1: Greedy day-by-day plan generation with stock simulation — because R2 only
+  demands feasibility, not optimality; rejected: constraint solver (overkill).
+- D2: JSON files over SQLite — because two flat collections with <1k entries
+  need no queries; rejected: SQLite (adds schema/migration weight).
+- D3: Shopping list = sum(plan needs) − stock, clamped at 0 per item (R3) —
+  computed on demand, never stored; rejected: persisting derived data.

examples/pantry-planner/specs/001-pantry-meal-planner/spec.md

@@ -0,0 +1,61 @@
+# Feature Specification: 001-pantry-meal-planner
+
+*Created: 2026-08-18*
+
+> Original request: pantry meal planner
+
+## User Stories
+
+### Story 1 — (P1)
+
+As a home cook, I want to record what is in my pantry, so that meal suggestions
+are based on what I actually have.
+
+**Acceptance:** Given an empty pantry list, when I add "500 g rice" and
+"2 cans tomatoes", then the pantry shows both items with their quantities.
+
+### Story 2 — (P1)
+
+As a home cook, I want a weekly plan of meals cookable from my pantry, so that
+I don't have to decide every evening.
+
+**Acceptance:** Given a pantry with rice, tomatoes and lentils, when I request
+a plan for 7 days, then every suggested meal uses only pantry items and no
+item is over-consumed across the week.
+
+### Story 3 — (P2)
+
+As a home cook, I want a shopping list for the gaps, so that one store visit
+covers the whole week.
+
+**Acceptance:** Given a 7-day plan that needs 3 onions while the pantry has 1,
+when I open the shopping list, then it shows "2 onions" and nothing already
+covered by the pantry.
+
+## Requirements
+
+- R1: The system must store pantry items as name + quantity + unit and support
+  add, update and remove.
+- R2: The system must generate a 7-day plan where each meal's ingredients are
+  fully covered by the current pantry stock minus what earlier meals in the
+  same plan consume.
+- R3: The system must derive a shopping list as the difference between a plan's
+  total ingredient needs and current stock.
+- R4: Recipes come from a local, user-editable recipe file; a starter set of
+  10 common recipes is bundled so the planner works out of the box.
+
+**Entities:** PantryItem (name, quantity, unit), Recipe (name, ingredients),
+MealPlan (7 ordered days -> recipe), ShoppingList (derived).
+
+## Success Criteria
+
+- S1: Recording a 10-item pantry takes under 2 minutes.
+- S2: A generated 7-day plan never references an ingredient with insufficient
+  stock at the point it is cooked.
+- S3: Buying exactly the shopping list makes every meal of the week cookable.
+
+## Assumptions
+
+- A1: Single household, single device, no sharing — fully local data.
+- A2: Quantities use metric units and piece counts; no unit conversion in v1.
+- A3: One meal per day is planned (dinner); breakfast/lunch out of scope.

examples/pantry-planner/specs/001-pantry-meal-planner/tasks.md

@@ -0,0 +1,23 @@
+# Tasks: 001-pantry-meal-planner
+
+*Created: 2026-08-18*
+
+Dependency-ordered, checkable work items derived from the spec and plan.
+Work top to bottom; a phase starts only when the one before it is done.
+
+## Phases
+
+### Setup
+
+- [x] T1: Scaffold pantry_planner/ package with pytest harness and empty modules per plan Structure
+- [x] T2: Define PantryItem/Recipe dataclasses in pantry_planner/planner.py and JSON load/save for pantry.json + recipes.json (Story 1 entities)
+
+### Implementation
+
+- [x] T3: Story 1 — pantry CRUD in planner.py + `pantry add/remove/list` in cli.py, test-first (acceptance: add 500 g rice + 2 cans tomatoes, list shows both)
+- [ ] T4: Story 2 — 7-day plan generation with stock simulation in planner.py (test: no ingredient over-consumed across the week, R2/S2)
+- [ ] T5: Story 3 — shopping list derivation (plan needs − stock, clamp 0) + `shoplist` command (acceptance: 3 onions needed, 1 in stock → "2 onions")
+
+### Polish
+
+- [ ] T6: Bundle 10-recipe starter set (R4), README for the example, full test run