From 9574994abb517534655382531305d95d4ba4d7e9 Mon Sep 17 00:00:00 2001
From: sstent <stuart.stent@gmail.com>
Date: Fri, 13 Feb 2026 14:31:21 -0800
Subject: [PATCH] conductor(setup): Add conductor setup files

---
 conductor/code_styleguides/html-css.md        |  49 +++++
 conductor/code_styleguides/javascript.md      |  51 ++++++
 conductor/code_styleguides/python.md          |  37 ++++
 conductor/index.md                            |  14 ++
 conductor/product-guidelines.md               |  16 ++
 conductor/product.md                          |  26 +++
 conductor/setup_state.json                    |   1 +
 conductor/tech-stack.md                       |  23 +++
 conductor/tracks.md                           |   8 +
 .../tracks/add_calcium_20260213/index.md      |   5 +
 .../tracks/add_calcium_20260213/metadata.json |   8 +
 conductor/tracks/add_calcium_20260213/plan.md |  18 ++
 conductor/tracks/add_calcium_20260213/spec.md |  25 +++
 conductor/workflow.md                         | 169 ++++++++++++++++++
 14 files changed, 450 insertions(+)
 create mode 100644 conductor/code_styleguides/html-css.md
 create mode 100644 conductor/code_styleguides/javascript.md
 create mode 100644 conductor/code_styleguides/python.md
 create mode 100644 conductor/index.md
 create mode 100644 conductor/product-guidelines.md
 create mode 100644 conductor/product.md
 create mode 100644 conductor/setup_state.json
 create mode 100644 conductor/tech-stack.md
 create mode 100644 conductor/tracks.md
 create mode 100644 conductor/tracks/add_calcium_20260213/index.md
 create mode 100644 conductor/tracks/add_calcium_20260213/metadata.json
 create mode 100644 conductor/tracks/add_calcium_20260213/plan.md
 create mode 100644 conductor/tracks/add_calcium_20260213/spec.md
 create mode 100644 conductor/workflow.md
diff --git a/conductor/code_styleguides/html-css.md b/conductor/code_styleguides/html-css.md
new file mode 100644
index 0000000..74a0932
--- /dev/null
+++ b/conductor/code_styleguides/html-css.md
@@ -0,0 +1,49 @@
+# Google HTML/CSS Style Guide Summary
+
+This document summarizes key rules and best practices from the Google HTML/CSS Style Guide.
+
+## 1. General Rules
+- **Protocol:** Use HTTPS for all embedded resources.
+- **Indentation:** Indent by 2 spaces. Do not use tabs.
+- **Capitalization:** Use only lowercase for all code (element names, attributes, selectors, properties).
+- **Trailing Whitespace:** Remove all trailing whitespace.
+- **Encoding:** Use UTF-8 (without a BOM). Specify `<meta charset="utf-8">` in HTML.
+
+## 2. HTML Style Rules
+- **Document Type:** Use `<!doctype html>`.
+- **HTML Validity:** Use valid HTML.
+- **Semantics:** Use HTML elements according to their intended purpose (e.g., use `<p>` for paragraphs, not for spacing).
+- **Multimedia Fallback:** Provide `alt` text for images and transcripts/captions for audio/video.
+- **Separation of Concerns:** Strictly separate structure (HTML), presentation (CSS), and behavior (JavaScript). Link to CSS and JS from external files.
+- **`type` Attributes:** Omit `type` attributes for stylesheets (`<link>`) and scripts (`<script>`).
+
+## 3. HTML Formatting Rules
+- **General:** Use a new line for every block, list, or table element, and indent its children.
+- **Quotation Marks:** Use double quotation marks (`""`) for attribute values.
+
+## 4. CSS Style Rules
+- **CSS Validity:** Use valid CSS.
+- **Class Naming:** Use meaningful, generic names. Separate words with a hyphen (`-`).
+  - **Good:** `.video-player`, `.site-navigation`
+  - **Bad:** `.vid`, `.red-text`
+- **ID Selectors:** Avoid using ID selectors for styling. Prefer class selectors.
+- **Shorthand Properties:** Use shorthand properties where possible (e.g., `padding`, `font`).
+- **`0` and Units:** Omit units for `0` values (e.g., `margin: 0;`).
+- **Leading `0`s:** Always include leading `0`s for decimal values (e.g., `font-size: 0.8em;`).
+- **Hexadecimal Notation:** Use 3-character hex notation where possible (e.g., `#fff`).
+- **`!important`:** Avoid using `!important`.
+
+## 5. CSS Formatting Rules
+- **Declaration Order:** Alphabetize declarations within a rule.
+- **Indentation:** Indent all block content.
+- **Semicolons:** Use a semicolon after every declaration.
+- **Spacing:**
+  - Use a space after a property name's colon (`font-weight: bold;`).
+  - Use a space between the last selector and the opening brace (`.foo {`).
+  - Start a new line for each selector and declaration.
+- **Rule Separation:** Separate rules with a new line.
+- **Quotation Marks:** Use single quotes (`''`) for attribute selectors and property values (e.g., `[type='text']`).
+
+**BE CONSISTENT.** When editing code, match the existing style.
+
+*Source: [Google HTML/CSS Style Guide](https://google.github.io/styleguide/htmlcssguide.html)*
diff --git a/conductor/code_styleguides/javascript.md b/conductor/code_styleguides/javascript.md
new file mode 100644
index 0000000..123f504
--- /dev/null
+++ b/conductor/code_styleguides/javascript.md
@@ -0,0 +1,51 @@
+# Google JavaScript Style Guide Summary
+
+This document summarizes key rules and best practices from the Google JavaScript Style Guide.
+
+## 1. Source File Basics
+- **File Naming:** All lowercase, with underscores (`_`) or dashes (`-`). Extension must be `.js`.
+- **File Encoding:** UTF-8.
+- **Whitespace:** Use only ASCII horizontal spaces (0x20). Tabs are forbidden for indentation.
+
+## 2. Source File Structure
+- New files should be ES modules (`import`/`export`).
+- **Exports:** Use named exports (`export {MyClass};`). **Do not use default exports.**
+- **Imports:** Do not use line-wrapped imports. The `.js` extension in import paths is mandatory.
+
+## 3. Formatting
+- **Braces:** Required for all control structures (`if`, `for`, `while`, etc.), even single-line blocks. Use K&R style ("Egyptian brackets").
+- **Indentation:** +2 spaces for each new block.
+- **Semicolons:** Every statement must be terminated with a semicolon.
+- **Column Limit:** 80 characters.
+- **Line-wrapping:** Indent continuation lines at least +4 spaces.
+- **Whitespace:** Use single blank lines between methods. No trailing whitespace.
+
+## 4. Language Features
+- **Variable Declarations:** Use `const` by default, `let` if reassignment is needed. **`var` is forbidden.**
+- **Array Literals:** Use trailing commas. Do not use the `Array` constructor.
+- **Object Literals:** Use trailing commas and shorthand properties. Do not use the `Object` constructor.
+- **Classes:** Do not use JavaScript getter/setter properties (`get name()`). Provide ordinary methods instead.
+- **Functions:** Prefer arrow functions for nested functions to preserve `this` context.
+- **String Literals:** Use single quotes (`'`). Use template literals (`` ` ``) for multi-line strings or complex interpolation.
+- **Control Structures:** Prefer `for-of` loops. `for-in` loops should only be used on dict-style objects.
+- **`this`:** Only use `this` in class constructors, methods, or in arrow functions defined within them.
+- **Equality Checks:** Always use identity operators (`===` / `!==`).
+
+## 5. Disallowed Features
+- `with` keyword.
+- `eval()` or `Function(...string)`.
+- Automatic Semicolon Insertion.
+- Modifying builtin objects (`Array.prototype.foo = ...`).
+
+## 6. Naming
+- **Classes:** `UpperCamelCase`.
+- **Methods & Functions:** `lowerCamelCase`.
+- **Constants:** `CONSTANT_CASE` (all uppercase with underscores).
+- **Non-constant Fields & Variables:** `lowerCamelCase`.
+
+## 7. JSDoc
+- JSDoc is used on all classes, fields, and methods.
+- Use `@param`, `@return`, `@override`, `@deprecated`.
+- Type annotations are enclosed in braces (e.g., `/** @param {string} userName */`).
+
+*Source: [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html)*
diff --git a/conductor/code_styleguides/python.md b/conductor/code_styleguides/python.md
new file mode 100644
index 0000000..b684577
--- /dev/null
+++ b/conductor/code_styleguides/python.md
@@ -0,0 +1,37 @@
+# Google Python Style Guide Summary
+
+This document summarizes key rules and best practices from the Google Python Style Guide.
+
+## 1. Python Language Rules
+- **Linting:** Run `pylint` on your code to catch bugs and style issues.
+- **Imports:** Use `import x` for packages/modules. Use `from x import y` only when `y` is a submodule.
+- **Exceptions:** Use built-in exception classes. Do not use bare `except:` clauses.
+- **Global State:** Avoid mutable global state. Module-level constants are okay and should be `ALL_CAPS_WITH_UNDERSCORES`.
+- **Comprehensions:** Use for simple cases. Avoid for complex logic where a full loop is more readable.
+- **Default Argument Values:** Do not use mutable objects (like `[]` or `{}`) as default values.
+- **True/False Evaluations:** Use implicit false (e.g., `if not my_list:`). Use `if foo is None:` to check for `None`.
+- **Type Annotations:** Strongly encouraged for all public APIs.
+
+## 2. Python Style Rules
+- **Line Length:** Maximum 80 characters.
+- **Indentation:** 4 spaces per indentation level. Never use tabs.
+- **Blank Lines:** Two blank lines between top-level definitions (classes, functions). One blank line between method definitions.
+- **Whitespace:** Avoid extraneous whitespace. Surround binary operators with single spaces.
+- **Docstrings:** Use `"""triple double quotes"""`. Every public module, function, class, and method must have a docstring.
+  - **Format:** Start with a one-line summary. Include `Args:`, `Returns:`, and `Raises:` sections.
+- **Strings:** Use f-strings for formatting. Be consistent with single (`'`) or double (`"`) quotes.
+- **`TODO` Comments:** Use `TODO(username): Fix this.` format.
+- **Imports Formatting:** Imports should be on separate lines and grouped: standard library, third-party, and your own application's imports.
+
+## 3. Naming
+- **General:** `snake_case` for modules, functions, methods, and variables.
+- **Classes:** `PascalCase`.
+- **Constants:** `ALL_CAPS_WITH_UNDERSCORES`.
+- **Internal Use:** Use a single leading underscore (`_internal_variable`) for internal module/class members.
+
+## 4. Main
+- All executable files should have a `main()` function that contains the main logic, called from a `if __name__ == '__main__':` block.
+
+**BE CONSISTENT.** When editing code, match the existing style.
+
+*Source: [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html)*
diff --git a/conductor/index.md b/conductor/index.md
new file mode 100644
index 0000000..ce6eea1
--- /dev/null
+++ b/conductor/index.md
@@ -0,0 +1,14 @@
+# Project Context
+
+## Definition
+- [Product Definition](./product.md)
+- [Product Guidelines](./product-guidelines.md)
+- [Tech Stack](./tech-stack.md)
+
+## Workflow
+- [Workflow](./workflow.md)
+- [Code Style Guides](./code_styleguides/)
+
+## Management
+- [Tracks Registry](./tracks.md)
+- [Tracks Directory](./tracks/)
diff --git a/conductor/product-guidelines.md b/conductor/product-guidelines.md
new file mode 100644
index 0000000..502f29d
--- /dev/null
+++ b/conductor/product-guidelines.md
@@ -0,0 +1,16 @@
+# Product Guidelines - FoodPlanner
+
+## Visual Identity & Tone
+- **Minimalist and Focused:** The interface should be clean and distraction-free, highlighting one primary task at a time to reduce cognitive load.
+- **Data Clarity:** Prioritize a high-contrast, readable layout that makes nutritional values easy to scan.
+
+## User Interface Principles
+- **Page-Specific Nutritional Awareness:**
+    - **Global Context:** Use a subtle, persistent summary (e.g., a sticky header) to keep total macros/calories visible for continuous goal tracking.
+    - **Local Context:** On list-heavy pages (like Food Search or Meal Building), integrate nutritional data directly with the items for immediate decision-making.
+- **Task-Oriented "Empty States":** When a user encounters an empty view (no foods, no plans), provide clear, actionable instructions and buttons within that space to guide them to the next step.
+
+## Interaction & Behavior
+- **Immediate & Reactive:** Every user action (adjusting quantities, adding items) must trigger an instant UI update to the relevant nutritional totals.
+- **Unambiguous Validation:** Use Modal Alerts for errors that require immediate attention or could result in data loss, ensuring critical issues are never overlooked.
+- **Low Friction:** Design interactions to minimize the number of clicks required for common tasks like portion adjustments or food selection.
diff --git a/conductor/product.md b/conductor/product.md
new file mode 100644
index 0000000..2fbc7f3
--- /dev/null
+++ b/conductor/product.md
@@ -0,0 +1,26 @@
+# Initial Concept\nAn existing Meal Planner application built with FastAPI, SQLAlchemy, and Jinja2 for managing foods, meals, and nutritional plans.
+
+# Product Definition - FoodPlanner
+
+## Vision
+A performance-oriented meal planning application designed for health-conscious households (specifically 2-person units) to hit precise nutritional and macronutrient targets. The application prioritizes speed, data reliability, and structured planning over complex external integrations.
+
+## Target Users
+- **Macro-Trackers:** Individuals who meticulously track their caloric and macronutrient intake.
+- **2-Person Households:** Users who need to coordinate meal plans for a small, consistent group.
+
+## Core Goals
+- **Nutritional Precision:** Enable users to reach specific daily and weekly macro/calorie goals through structured 2-week planning.
+- **Efficiency:** Reduce the friction of meal prep by providing tools to save, reuse, and template successful plans and meals.
+- **Reliability:** Provide a fast, local-first experience with robust data storage (SQLite/PostgreSQL).
+
+## Key Features
+- **Nutritional Totaling:** Automated, real-time calculation of macros and calories for individual foods, combined meals, and full daily/weekly plans.
+- **Detailed Daily Planner:** A granular view of each day to visualize meal distribution and ensure macro balance across the day.
+- **Meals Library:** A centralized repository to create and save custom meals from individual food components.
+- **Template System:** Save and apply successful daily or weekly structures to future plans to minimize repetitive data entry.
+- **Open Food Facts Integration:** Rapidly expand the local food database by importing data directly from the Open Food Facts API.
+
+## Technical Philosophy
+- **Local-First & Fast:** The UI must be highly responsive, prioritizing a smooth user experience for frequent data entry.
+- **Structured Data:** Use a relational database to ensure data integrity across foods, meals, and plans.
diff --git a/conductor/setup_state.json b/conductor/setup_state.json
new file mode 100644
index 0000000..00fd665
--- /dev/null
+++ b/conductor/setup_state.json
@@ -0,0 +1 @@
+{"last_successful_step": "3.3_initial_track_generated"}
diff --git a/conductor/tech-stack.md b/conductor/tech-stack.md
new file mode 100644
index 0000000..1ecc7e8
--- /dev/null
+++ b/conductor/tech-stack.md
@@ -0,0 +1,23 @@
+# Tech Stack - FoodPlanner
+
+## Core Backend
+- **Language:** Python 3.7+
+- **Web Framework:** FastAPI (Asynchronous, high-performance web framework)
+- **Data Validation:** Pydantic (Used for schema definition and request/response validation)
+
+## Data Layer
+- **ORM:** SQLAlchemy (Using 2.0+ patterns for database interactions)
+- **Database:** Support for SQLite (local development) and PostgreSQL (production)
+- **Migrations:** Alembic (Handles database schema evolution)
+
+## Frontend & UI
+- **Templating:** Jinja2 (Server-side rendering for HTML templates)
+- **Frontend Logic:** Minimal JavaScript for reactive UI updates and modal management
+
+## External Integrations
+- **Food Data:** Open Food Facts API (For importing nutritional information)
+- **AI/Extraction:** OpenAI API (Used for extracting food data from unstructured text)
+
+## Quality Assurance
+- **E2E Testing:** Playwright (For browser-based integration tests)
+- **Unit/Integration Testing:** pytest (For backend logic and API testing)
diff --git a/conductor/tracks.md b/conductor/tracks.md
new file mode 100644
index 0000000..152ddba
--- /dev/null
+++ b/conductor/tracks.md
@@ -0,0 +1,8 @@
+# Project Tracks
+
+This file tracks all major tracks for the project. Each track has its own detailed plan in its respective folder.
+
+---
+
+- [ ] **Track: Add Calcium bottom row of "Daily Totals" on the tracker page**
+  *Link: [./tracks/add_calcium_20260213/](./tracks/add_calcium_20260213/)*
diff --git a/conductor/tracks/add_calcium_20260213/index.md b/conductor/tracks/add_calcium_20260213/index.md
new file mode 100644
index 0000000..e44f0f1
--- /dev/null
+++ b/conductor/tracks/add_calcium_20260213/index.md
@@ -0,0 +1,5 @@
+# Track add_calcium_20260213 Context
+
+- [Specification](./spec.md)
+- [Implementation Plan](./plan.md)
+- [Metadata](./metadata.json)
diff --git a/conductor/tracks/add_calcium_20260213/metadata.json b/conductor/tracks/add_calcium_20260213/metadata.json
new file mode 100644
index 0000000..a7a0f5d
--- /dev/null
+++ b/conductor/tracks/add_calcium_20260213/metadata.json
@@ -0,0 +1,8 @@
+{
+  "track_id": "add_calcium_20260213",
+  "type": "feature",
+  "status": "new",
+  "created_at": "2026-02-13T00:00:00Z",
+  "updated_at": "2026-02-13T00:00:00Z",
+  "description": "Add Calcium bottom row of 'Daily Totals' on the tracker page"
+}
diff --git a/conductor/tracks/add_calcium_20260213/plan.md b/conductor/tracks/add_calcium_20260213/plan.md
new file mode 100644
index 0000000..7fea510
--- /dev/null
+++ b/conductor/tracks/add_calcium_20260213/plan.md
@@ -0,0 +1,18 @@
+# Implementation Plan - Add Calcium to Tracker Totals
+
+This plan follows the Test-Driven Development (TDD) process as outlined in `conductor/workflow.md`.
+
+## Phase 1: Infrastructure and Red Phase
+- [ ] Task: Create a failing E2E test for Calcium display
+    - [ ] Define a new test in `tests/calcium_display.spec.js` that navigates to the tracker and expects a "Calcium" label and a numeric value in the Daily Totals section.
+    - [ ] Execute the test and confirm it fails (Red Phase).
+
+## Phase 2: Implementation (Green Phase)
+- [ ] Task: Update tracker template to include Calcium
+    - [ ] Modify `templates/tracker.html` to add a fourth column to the third row of the "Daily Totals" card.
+    - [ ] Update existing `col-4` classes in that row to `col-3` to accommodate the new column.
+    - [ ] Bind the display to `day_totals.calcium` with a `0` decimal place filter and "mg" unit.
+- [ ] Task: Verify implementation
+    - [ ] Execute the E2E test created in Phase 1 and confirm it passes (Green Phase).
+    - [ ] Run existing backend tests to ensure no regressions in nutrition calculations.
+- [ ] Task: Conductor - User Manual Verification 'Implementation' (Protocol in workflow.md)
diff --git a/conductor/tracks/add_calcium_20260213/spec.md b/conductor/tracks/add_calcium_20260213/spec.md
new file mode 100644
index 0000000..289c6a8
--- /dev/null
+++ b/conductor/tracks/add_calcium_20260213/spec.md
@@ -0,0 +1,25 @@
+# Specification - Add Calcium to Tracker Totals
+
+## Overview
+This track adds a Calcium display to the "Daily Totals" section of the tracker page. This allows users to track their calcium intake (in mg) alongside other micronutrients and macronutrients.
+
+## Functional Requirements
+- **Display Calcium:** Add a new column to the third row of the "Daily Totals" card on the `tracker.html` page.
+- **Unit of Measurement:** Calcium shall be displayed in milligrams (mg).
+- **Precision:** Calcium values shall be rounded to the nearest whole number (0 decimal places).
+- **Data Source:** Use the `day_totals.calcium` value provided by the backend, which is already correctly calculated in `calculate_day_nutrition_tracked`.
+
+## Non-Functional Requirements
+- **UI Consistency:** The new Calcium display should match the style of the existing Sugar, Fiber, and Sodium displays (border, padding, centered text, small muted label).
+- **Responsiveness:** The layout should remain functional on various screen sizes. Adding a fourth column to the row may require adjusting column widths (e.g., from `col-4` to `col-3`).
+
+## Acceptance Criteria
+- [ ] A "Calcium" box is visible in the "Daily Totals" section of the tracker page.
+- [ ] The value displayed matches the sum of calcium from all tracked foods for that day.
+- [ ] The unit "mg" is displayed next to or below the value.
+- [ ] The layout of the "Daily Totals" card remains clean and balanced.
+
+## Out of Scope
+- Adding Calcium to individual food or meal breakdown tables.
+- Updating Open Food Facts import logic (unless found to be missing Calcium data during verification).
+- Adding Calcium targets or progress bars.
diff --git a/conductor/workflow.md b/conductor/workflow.md
new file mode 100644
index 0000000..b98d4c0
--- /dev/null
+++ b/conductor/workflow.md
@@ -0,0 +1,169 @@
+# Project Workflow
+
+## Guiding Principles
+
+1. **The Plan is the Source of Truth:** All work must be tracked in `plan.md`
+2. **The Tech Stack is Deliberate:** Changes to the tech stack must be documented in `tech-stack.md` *before* implementation
+3. **Test-Driven Development:** Write unit tests before implementing functionality
+4. **High Code Coverage:** Aim for >80% code coverage for all modules
+5. **User Experience First:** Every decision should prioritize user experience
+6. **Non-Interactive & CI-Aware:** Prefer non-interactive commands. Use `CI=true` for watch-mode tools (tests, linters) to ensure single execution.
+
+## Task Workflow
+
+All tasks follow a strict lifecycle:
+
+### Standard Task Workflow
+
+1. **Select Task:** Choose the next available task from `plan.md` in sequential order
+
+2. **Mark In Progress:** Before beginning work, edit `plan.md` and change the task from `[ ]` to `[~]`
+
+3. **Write Failing Tests (Red Phase):**
+   - Create a new test file for the feature or bug fix.
+   - Write one or more unit tests that clearly define the expected behavior and acceptance criteria for the task.
+   - **CRITICAL:** Run the tests and confirm that they fail as expected. This is the "Red" phase of TDD. Do not proceed until you have failing tests.
+
+4. **Implement to Pass Tests (Green Phase):**
+   - Write the minimum amount of application code necessary to make the failing tests pass.
+   - Run the test suite again and confirm that all tests now pass. This is the "Green" phase.
+
+5. **Refactor (Optional but Recommended):**
+   - With the safety of passing tests, refactor the implementation code and the test code to improve clarity, remove duplication, and enhance performance without changing the external behavior.
+   - Rerun tests to ensure they still pass after refactoring.
+
+6. **Verify Coverage:** Run coverage reports using the project's chosen tools (e.g., `pytest --cov=app`). Target: >80% coverage for new code.
+
+7. **Document Deviations:** If implementation differs from tech stack:
+   - **STOP** implementation
+   - Update `tech-stack.md` with new design
+   - Add dated note explaining the change
+   - Resume implementation
+
+8. **Record Completion in Plan:** Update `plan.md`, find the line for the completed task, and update its status from `[~]` to `[x]`. 
+   *Note: Committing code and plan updates is deferred until the entire phase is complete.*
+
+### Phase Completion Verification and Checkpointing Protocol
+
+**Trigger:** This protocol is executed immediately after a task is completed that also concludes a phase in `plan.md`.
+
+1.  **Announce Protocol Start:** Inform the user that the phase is complete and the verification and checkpointing protocol has begun.
+
+2.  **Ensure Test Coverage for Phase Changes:**
+    -   **Step 2.1: Determine Phase Scope:** Identify files changed since the last phase checkpoint.
+    -   **Step 2.2: List Changed Files:** Execute `git diff --name-only <previous_checkpoint_sha> HEAD` (or since first commit if no previous checkpoint).
+    -   **Step 2.3: Verify and Create Tests:** Ensure all new code has corresponding tests following project conventions.
+
+3.  **Execute Automated Tests with Proactive Debugging:**
+    -   Announce and run the automated test suite (e.g., `pytest` and `playwright test`).
+    -   If tests fail, debug and fix (maximum two attempts before seeking guidance).
+
+4.  **Propose a Detailed, Actionable Manual Verification Plan:**
+    -   Analyze `product.md`, `product-guidelines.md`, and `plan.md` to define user-facing goals.
+    -   Present a step-by-step verification plan with expected outcomes.
+
+5.  **Await Explicit User Feedback:**
+    -   Pause for the user to confirm: "Does this meet your expectations?"
+
+6.  **Create Phase Checkpoint Commit:**
+    -   Stage all code changes and the updated `plan.md`.
+    -   Perform a single commit for the entire phase with a message like `feat(phase): Complete <Phase Name>`.
+
+7.  **Attach Consolidated Task Summary using Git Notes:**
+    -   **Step 7.1: Draft Note Content:** Create a detailed summary for *all* tasks completed in this phase, including verification results.
+    -   **Step 7.2: Attach Note:** Use `git notes add -m "<summary>" <checkpoint_commit_hash>`.
+
+8.  **Get and Record Phase Checkpoint SHA:**
+    -   Obtain the hash of the checkpoint commit and update the phase heading in `plan.md` with `[checkpoint: <sha>]`.
+
+9. **Commit Plan Update:**
+    - Stage `plan.md` and commit with `conductor(plan): Mark phase '<PHASE NAME>' as complete`.
+
+10. **Announce Completion:** Inform the user that the phase is complete and the checkpoint has been created.
+
+## Quality Gates
+
+Before marking any task complete, verify:
+
+- [ ] All tests pass
+- [ ] Code coverage meets requirements (>80%)
+- [ ] Code follows project's code style guidelines
+- [ ] All public functions/methods are documented
+- [ ] Type safety is enforced (Pydantic models, type hints)
+- [ ] No linting or static analysis errors
+- [ ] Documentation updated if needed
+- [ ] No security vulnerabilities introduced
+
+## Development Commands
+
+### Setup
+```bash
+python -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+npm install
+```
+
+### Daily Development
+```bash
+# Start FastAPI server
+uvicorn main:app --reload
+
+# Run Backend Tests
+pytest
+
+# Run E2E Tests
+npx playwright test
+```
+
+### Before Committing
+```bash
+# Run all checks
+pytest && npx playwright test
+```
+
+## Testing Requirements
+
+### Unit Testing
+- Every module must have corresponding tests in `tests/`.
+- Use `pytest` fixtures for database and app setup.
+- Mock external APIs (Open Food Facts, OpenAI).
+
+### Integration Testing
+- Test complete API flows using `httpx`.
+- Verify database state after operations.
+
+### E2E Testing
+- Use Playwright to test critical user journeys (Creating Plans, Adding Foods).
+
+## Commit Guidelines
+
+### Message Format
+```
+<type>(<scope>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+### Types
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation only
+- `style`: Formatting, missing semicolons, etc.
+- `refactor`: Code change that neither fixes a bug nor adds a feature
+- `test`: Adding missing tests
+- `chore`: Maintenance tasks
+
+## Definition of Done
+
+A task is complete when:
+
+1. All code implemented to specification
+2. Unit tests written and passing
+3. Code coverage meets project requirements
+4. Documentation complete (if applicable)
+5. Code passes all configured linting and static analysis checks
+6. Implementation notes recorded for the phase summary
+7. Phase changes committed and summarized with Git Notes
\ No newline at end of file
