---
description: 
globs: 
alwaysApply: false
---
**CRITICAL PRE-PHASE: STABILIZE THE CORE (No Excuses. Do this FIRST.)**

This isn't about new features. This is about making what you *have* not be a liability.

can you start going through the tasks in tasks ruke, and write in /notes.md any notes for left todos etc..

dont actually run tests, just review tests and whatnot. dont actually run them!!!!!!


*   **Task 0.1: Fix Backend Financial Logic.**
    *   **File(s):** `be/app/api/v1/endpoints/costs.py`, `be/app/crud/expense.py`, `be/app/crud/settlement_activity.py`.
    *   **Objective:** Correct the balance calculation logic. Specifically, address the issues noted in your `test_costs.py` where `SettlementActivity` affects `total_settlements_paid` in a way that leads to incorrect net balances and non-zero sums for group balances.
    *   **Action for LLM:** "Refactor the group balance calculation within `costs.py` (and its dependencies in `crud/expense.py`, `crud/settlement_activity.py`) to ensure that when a `SettlementActivity` records a payment for an `ExpenseSplit`, the `net_balance` of the payer accurately reflects this (e.g., their debt decreases). The sum of all user `net_balance` values within a group's balance summary MUST equal zero after all expenses and settlements (including activities) are accounted for. Update relevant tests in `test_costs.py` to assert correct balances."
    *   **Verification:** The test `test_group_balance_summary_with_settlement_activity` in `be/tests/api/v1/test_costs.py` passes with logically sound assertions for all user balances, and the sum of net balances is zero.

*   **Task 0.2: Implement Frontend Expense Split Settlement.**
    *   **File(s):** `fe/src/stores/listDetailStore.ts`, `fe/src/pages/ListDetailPage.vue` (for UI interaction if any), `fe/src/services/api.ts` (if `apiClient.settleExpenseSplit` needs adjustment).
    *   **Objective:** Connect the frontend "Settle Share" functionality to the backend API.
    *   **Action for LLM:** "In `fe/src/stores/listDetailStore.ts`, modify the `settleExpenseSplit` action. Remove the placeholder/simulation. Implement a call to the backend API endpoint `/api/v1/financials/expense_splits/{expense_split_id}/settle` using the `apiClient` (ensure `apiClient` has or is updated to have a method like `settleExpenseSplit` or a generic `post` can be used with the correct URL construction from `API_ENDPOINTS`). The payload should be `activity_data`. On successful API response, `fetchListWithExpenses` should be called to update the UI. Handle API errors by setting `this.error` and returning `false`."
    *   **Verification:** User can click a "Settle" button in the UI for an expense split, the action calls the correct backend API, the `ExpenseSplit` status and `Expense` `overall_settlement_status` are updated in the database, and the UI reflects these changes after the list is refetched. Create a basic E2E test for this flow.

*   **Task 0.3: Review & Test Core Auth Flows.**
    *   **File(s):** `be/app/auth.py`, `be/app/api/auth/oauth.py`, relevant `fastapi-users` configurations, `fe/src/stores/auth.ts`, `fe/src/pages/LoginPage.vue`, `SignupPage.vue`, `AuthCallbackPage.vue`.
    *   **Objective:** Confirm standard email/password and Google/Apple OAuth flows are functional and robust.
    *   **Action for LLM:** "Review the configuration and implementation of `fastapi-users` for email/password authentication, and the OAuth flows for Google and Apple. Ensure:
        1.  Signup creates a user.
        2.  Login returns tokens.
        3.  `AuthCallbackPage.vue` correctly handles tokens from OAuth and calls `authStore.setTokens`.
        4.  `authStore.fetchCurrentUser` works after login.
        5.  Logout clears session/tokens.
        Write/verify Playwright E2E tests for each of these flows (email/password signup, email/password login, Google login, Apple login, logout)."
    *   **Verification:** All authentication E2E tests pass. Users can reliably sign up, log in (via all methods), and log out.

---

**PHASE 1: FULL-FEATURED LIST & ITEM MANAGEMENT (Your V1 Baseline)**

*   **Task 1.1: Backend - Robust List CRUD & Permissions.**
    *   **File(s):** `be/app/api/v1/endpoints/lists.py`, `be/app/crud/list.py`, `be/app/models.py` (List model).
    *   **Objective:** Implement all list CRUD operations with correct permissions and optimistic locking.
    *   **Action for LLM (Iterate for each endpoint - Create, Get All, Get ID, Update, Delete):** "For the `[CREATE/GET/UPDATE/DELETE]` list endpoint in `lists.py` and its corresponding CRUD function in `crud_list.py`:
        1.  Ensure user permissions are checked (creator for personal lists, group member for group lists; `require_creator` for delete/sensitive updates).
        2.  For `UPDATE` and `DELETE`, implement optimistic locking using the `version` field (HTTP 409 on mismatch).
        3.  For `CREATE`, handle potential `DatabaseIntegrityError` for unique list names within a group/user's personal lists by returning a 409 with the existing list's details (as noted in your endpoint).
        4.  Ensure all relationships (creator, group, items) are correctly handled and loaded/returned as per `ListPublic` and `ListDetail` schemas.
        5.  Write comprehensive unit tests in `be/tests/crud/test_list.py` and API tests for these scenarios."
    *   **Verification:** All API endpoints for lists function as documented in `mitlist_doc.md` (V1 scope), pass all tests, and handle permissions/versioning correctly.

*   **Task 1.2: Frontend - Full List UI/UX.**
    *   **File(s):** `fe/src/pages/ListsPage.vue`, `fe/src/pages/ListDetailPage.vue`, `fe/src/components/CreateListModal.vue`.
    *   **Objective:** Implement all UI for list management.
    *   **Action for LLM (Iterate per feature):** "Implement the UI in Vue components for:
        1.  Displaying all accessible lists (`ListsPage.vue`).
        2.  Creating new lists (personal or group-associated) using `CreateListModal.vue`.
        3.  Viewing list details and items (`ListDetailPage.vue`).
        4.  Updating list name/description (handle `version` for optimistic lock, show conflict notification).
        5.  Deleting lists (with confirmation, handle `version` for optimistic lock)."
    *   **Verification:** All list management features are usable from the frontend. E2E tests (from `fe/e2e/lists.spec.ts`, unskip and fix) pass.

*   **Task 1.3: Backend - Robust Item CRUD & Permissions.**
    *   **File(s):** `be/app/api/v1/endpoints/items.py`, `be/app/crud/item.py`, `be/app/models.py` (Item model).
    *   **Objective:** Implement all item CRUD operations with permissions and optimistic locking.
    *   **Action for LLM (Iterate for each endpoint):** "Similar to Task 1.1, implement/review CRUD operations for items within a list. Ensure:
        1.  Permissions are based on access to the parent list.
        2.  `UPDATE` and `DELETE` use optimistic locking with `version`.
        3.  Updating `is_complete` correctly sets/unsets `completed_by_id`.
        4.  Item price can be added/updated.
        5.  Write comprehensive unit and API tests."
    *   **Verification:** All item CRUD endpoints function correctly, pass tests, handle permissions/versioning.

*   **Task 1.4: Frontend - Full Item UI/UX in List Detail.**
    *   **File(s):** `fe/src/pages/ListDetailPage.vue`.
    *   **Objective:** Implement all UI for item management within a list.
    *   **Action for LLM:** "In `ListDetailPage.vue`, implement UI for:
        1.  Adding new items (name, quantity).
        2.  Displaying items with their details.
        3.  Marking items as complete/incomplete (checkbox) and updating the backend (handle `version`).
        4.  Adding/editing price for completed items (handle `version`).
        5.  Editing item name/quantity (handle `version`).
        6.  Deleting items (with confirmation, handle `version`).
        Handle loading states and errors for each action."
    *   **Verification:** Item management is fully functional in the UI. E2E tests (from `fe/e2e/lists.spec.ts`, unskip and fix for items) pass.

*   **Task 1.5: Backend - OCR Integration (Gemini).**
    *   **File(s):** `be/app/core/gemini.py`, `be/app/api/v1/endpoints/ocr.py`.
    *   **Objective:** Reliable item extraction from images.
    *   **Action for LLM:** "Refine and test `gemini.py` and the `/ocr/extract-items` endpoint.
        1.  Ensure robust error handling for API key issues, quota limits (`OCRQuotaExceededError`), service unavailability (`OCRServiceUnavailableError`), and general processing errors (`OCRProcessingError`). Return appropriate HTTP status codes.
        2.  Thoroughly test the `OCR_ITEM_EXTRACTION_PROMPT` with various real-world receipt/list images to optimize accuracy. Handle cases where Gemini returns no usable text or indicates the image is not a list.
        3.  Ensure `ALLOWED_IMAGE_TYPES` and `MAX_FILE_SIZE_MB` are enforced."
    *   **Verification:** OCR endpoint is stable, handles errors gracefully, and provides reasonably accurate item extraction.

*   **Task 1.6: Frontend - OCR UI Flow.**
    *   **File(s):** `fe/src/pages/ListDetailPage.vue` (or a dedicated OCR component).
    *   **Objective:** Smooth user experience for adding items via OCR.
    *   **Action for LLM:** "Implement the OCR flow in the Vue frontend:
        1.  UI for image capture/upload (using `input capture` or `getUserMedia`).
        2.  File validation (type, size) on the client side before upload.
        3.  API call to the backend OCR endpoint with loading indicators.
        4.  Display extracted items in an editable format (e.g., list of text inputs).
        5.  Allow users to add, edit, or remove items from this extracted list.
        6.  Button to add the confirmed items to the current shopping list (batch API calls if necessary)."
    *   **Verification:** Users can successfully use the OCR feature from image capture to adding items to a list.

---

**PHASE 2: FULL-FEATURED COST SPLITTING & TRACEABILITY (Your V1 Differentiator)**

This phase assumes Phase 0 (financial fixes) is COMPLETE.

*   **Task 2.1: Backend - Expense Creation with All Split Types.**
    *   **File(s):** `be/app/crud/expense.py` (specifically `_generate_expense_splits` and its helpers like `_create_equal_splits`, `_create_exact_amount_splits`, etc.), `be/app/api/v1/endpoints/financials.py` (`create_new_expense`).
    *   **Objective:** Support creation of expenses with all V1 split types (Equal, Exact Amounts, Percentage, Shares, Item-Based).
    *   **Action for LLM:** "For each `SplitTypeEnum` defined in your V1 scope:
        1.  In `crud_expense.py`, ensure the corresponding helper function (`_create_exact_amount_splits`, `_create_percentage_splits`, `_create_shares_splits`, `_create_item_based_splits`) correctly calculates and creates `ExpenseSplitModel` instances based on the input `expense_in.splits_in` (for exact, percentage, shares) or item data (for item-based).
        2.  Validate input: sum of exact amounts/percentages/shares must match total expense. Item-based splits should correctly sum item prices.
        3.  Ensure `overall_settlement_status` on `ExpenseModel` and `status` on `ExpenseSplitModel` are initialized correctly (`unpaid`).
        4.  Write unit tests in `be/tests/crud/test_expense.py` for each split type, covering valid and invalid scenarios."
    *   **Verification:** Expenses can be created with all V1 split types, and the resulting splits are mathematically correct and persisted.

*   **Task 2.2: Frontend - Expense Creation UI for All Split Types.**
    *   **File(s):** `fe/src/components/CreateExpenseForm.vue` (or similar).
    *   **Objective:** UI allows users to create expenses with any V1 split type.
    *   **Action for LLM:** "Enhance `CreateExpenseForm.vue`:
        1.  Add UI elements (dynamic forms) to input split details when `split_type` is Exact Amounts, Percentage, or Shares (e.g., inputs for each user's amount/percentage/share).
        2.  For Item-Based splits, the UI might involve selecting items from the list or this might be triggered automatically post-OCR/price entry – clarify flow.
        3.  Ensure the form correctly constructs the `ExpenseCreate` payload, including `splits_in` where appropriate.
        4.  Validate inputs on the frontend (e.g., sum of percentages is 100)."
    *   **Verification:** Users can create expenses with all supported split types through the UI.

*   **Task 2.3: Backend & Frontend - Viewing Expenses and Settlement Status.**
    *   **File(s):** `be/app/api/v1/endpoints/financials.py` (GET expenses), `be/app/schemas/expense.py` (ensure `ExpensePublic`, `ExpenseSplitPublic` include status fields), `fe/src/pages/ListDetailPage.vue` (or wherever expenses are displayed).
    *   **Objective:** Users can clearly see expenses, their splits, and the settlement status of each.
    *   **Action for LLM:**
        1.  "BE: Ensure `ExpensePublic` and `ExpenseSplitPublic` schemas include `overall_settlement_status`, `status`, `paid_at`, and `settlement_activities`. Ensure GET expense endpoints populate these fields."
        2.  "FE: In `ListDetailPage.vue`, display expenses associated with the list. For each expense, show its splits, including who owes what, the current `status` (Unpaid, Partially Paid, Paid), and when it was paid (`paid_at`). Display `overall_settlement_status` for the expense."
    *   **Verification:** UI accurately displays detailed expense and split information, including settlement statuses.

*   **Task 2.4: Backend & Frontend - Recording Settlement Activities.**
    *   **File(s):** `be/app/api/v1/endpoints/financials.py` (POST `/expense_splits/{expense_split_id}/settle`), `be/app/crud/settlement_activity.py`, `be/app/models.py` (`SettlementActivity`), `fe/src/stores/listDetailStore.ts`, `fe/src/pages/ListDetailPage.vue`.
    *   **Objective:** Users can mark their `ExpenseShare` (represented by `ExpenseSplit`) as paid, creating a traceable `SettlementActivity`.
    *   **Action for LLM:**
        1.  "BE: Implement `crud_settlement_activity.create_settlement_activity`. When a `SettlementActivity` is created for an `ExpenseSplit`:
            *   Update the `ExpenseSplit.status` (to `partially_paid` or `paid`) based on `amount_paid` vs `owed_amount`. If fully paid, set `ExpenseSplit.paid_at`.
            *   Update the parent `Expense.overall_settlement_status` based on the status of all its splits.
        2.  "BE: Ensure the `/financials/expense_splits/{expense_split_id}/settle` endpoint correctly calls the CRUD function and handles permissions (user can settle their own split, or group owner can settle for others)."
        3.  "FE: In `ListDetailPage.vue`, provide a button/action for a user to "Settle My Share" for an `ExpenseSplit` they owe. This should trigger the `settleExpenseSplit` action in `listDetailStore.ts` (which now calls the real API - Task 0.2)."
    *   **Verification:** Users can settle their expense shares. The backend correctly updates statuses. UI reflects these changes. All settlement activities are logged in the `settlement_activities` table.

---

**PHASE 3: FULL-FEATURED CHORE MANAGEMENT (Your V1 Scope)**

*   **Task 3.1: Backend - Chore CRUD (Personal & Group) with Recurrence.**
    *   **File(s):** `be/app/api/v1/endpoints/chores.py`, `be/app/crud/chore.py`, `be/app/core/chore_utils.py`.
    *   **Objective:** Full CRUD for personal and group chores, including all recurrence logic.
    *   **Action for LLM:** "Implement/Refine `create_chore`, `get_chore_by_id`, `get_personal_chores`, `get_chores_by_group_id`, `update_chore`, `delete_chore` in `crud_chore.py` and corresponding endpoints in `chores.py`.
        1.  For `create_chore` and `update_chore`: If `frequency` is `custom`, `custom_interval_days` must be provided. Validate chore `type` (`personal` vs `group`) and `group_id` consistency.
        2.  Implement `calculate_next_due_date` in `chore_utils.py` to accurately calculate the next due date based on `frequency`, `custom_interval_days`, and `last_completed_at`. Handle edge cases for monthly recurrence (e.g., due on 31st).
        3.  Ensure appropriate permissions are checked (e.g., user must be member of group to create/view group chores)."
    *   **Verification:** All chore CRUD operations work for both personal and group chores. Recurrence settings are handled correctly. Permissions are enforced. Unit and API tests cover these.

*   **Task 3.2: Frontend - Chore Management UI.**
    *   **File(s):** `fe/src/pages/ChoresPage.vue`, `fe/src/pages/PersonalChoresPage.vue`.
    *   **Objective:** UI for users to manage personal and group chores.
    *   **Action for LLM:** "Implement UI in `ChoresPage.vue` (for all chores, filterable by group) and `PersonalChoresPage.vue`:
        1.  Display lists of chores, showing name, description, frequency, next due date.
        2.  Modals/forms for creating and editing chores (personal and group, including all recurrence options).
        3.  Functionality to delete chores (with confirmation)."
    *   **Verification:** Users can manage personal and group chores via the UI. E2E tests for chore CRUD pass.

*   **Task 3.3: Backend & Frontend - Chore Assignments & Completion.**
    *   **File(s):** `be/app/models.py` (`ChoreAssignment`), `be/app/crud/chore.py` (new functions for assignments), `be/app/api/v1/endpoints/chores.py` (new endpoints for assignments), `fe/src/pages/ChoresPage.vue` (or a "My Chores" page).
    *   **Objective:** Chores can be assigned, and assignees can mark them complete, triggering recurrence updates.
    *   **Action for LLM:**
        1.  "BE: Define `ChoreAssignment` model. Create CRUD functions and API endpoints for:
            *   Manually assigning a chore instance (from a recurring `Chore`) to a user for a specific `due_date`.
            *   Allowing an assigned user to mark their `ChoreAssignment` as complete. This should set `completed_at`.
            *   When a recurring chore's assignment is completed, update the parent `Chore.last_completed_at` and use `calculate_next_due_date` to set its new `Chore.next_due_date`.
        2.  "FE: Implement UI for:
            *   Group admins/owners to assign chore instances to members.
            *   A "My Chores" view where users see their pending `ChoreAssignments`.
            *   Users to mark their assigned chores as complete."
    *   **Verification:** Chore assignment and completion workflow is functional. Recurrence updates correctly.

---

**PHASE 4: FULL PWA OFFLINE & BACKGROUND SYNC (Your V1 Scope)**

*   **Task 4.1: Frontend - Implement Offline Action Queuing for All V1 Features.**
    *   **File(s):** `fe/src/stores/offline.ts`.
    *   **Objective:** All mutable actions from V1 (list/item/chore CRUD, expense/settlement creation, chore completion) are queued when offline.
    *   **Action for LLM:** "Extend `OfflineAction` type and `processAction` in `offline.ts` to handle all mutable operations for lists, items, expenses, settlements, and chores (CRUD, marking complete, etc.) as defined in your V1 feature set. Ensure each action type has a corresponding case in `processAction` that makes the correct API call using `fetch` (or a thin wrapper around `apiClient` if `apiClient` is made compatible with background sync context)."
    *   **Verification:** When offline, performing any V1 action adds it to the `pendingActions` queue in `localStorage`.

*   **Task 4.2: Frontend - Robust Background Sync & Retry.**
    *   **File(s):** `fe/src/sw.ts`, `fe/src/stores/offline.ts`.
    *   **Objective:** Queued actions are reliably synced via the service worker's Background Sync API.
    *   **Action for LLM:** "Ensure the `BackgroundSyncPlugin` in `sw.ts` is correctly configured for the `offline-actions-queue`. The `sync` event handler in the service worker must correctly iterate through actions from `offlineStore.pendingActions` (potentially via `IDBKeyval` or directly if store is accessible in SW) and attempt to replay them using `fetch`. Ensure `maxRetentionTime` is set. Test retry behavior for failed syncs."
    *   **Verification:** Offline actions are processed when online. Failed actions are retried by background sync.

*   **Task 4.3: Frontend - Implement Conflict Resolution UI & Logic.**
    *   **File(s):** `fe/src/components/ConflictResolutionDialog.vue`, `fe/src/stores/offline.ts`.
    *   **Objective:** Users can resolve data conflicts arising from offline sync.
    *   **Action for LLM:**
        1.  "In `offline.ts`, when `processAction` receives a 409 conflict from the backend:
            *   Extract local data (from the `action.payload`) and server data (from the 409 response body).
            *   Populate `currentConflict` with this data and set `showConflictDialog = true`.
            *   Halt further queue processing until this conflict is resolved.
        2.  "In `ConflictResolutionDialog.vue`, display the local and server versions of the conflicting data clearly. Provide options: 'Keep Local Version', 'Keep Server Version', and 'Merge Changes' (if applicable and simple merge logic can be defined, e.g., field-by-field choice).
        3.  "Implement `handleConflictResolution` in `offline.ts`. Based on user's choice:
            *   'Keep Local': Re-submit the local action, potentially with the server's latest `version` number to overcome the 409.
            *   'Keep Server': Discard the local action.
            *   'Merge': Construct merged data and PUT it to the server (with server's `version`).
            *   Remove the original conflicting action from `pendingActions` on successful resolution. Resume queue processing."
    *   **Verification:** Conflicts are detected. Dialog appears. User can choose a resolution strategy. The chosen strategy is applied, and the queue continues.

---

**PHASE 5: FINAL TESTING, POLISHING, DEPLOYMENT (Your V1 Launch)**

*   **Task 5.1: Comprehensive E2E Testing of ALL V1 Features.**
    *   **Objective:** All user flows, including offline scenarios and conflict resolution, are covered by E2E tests.
    *   **Action for LLM:** "Write new Playwright E2E tests and update existing ones (`fe/e2e/`) to cover every feature in your `mitlist_doc.md` V1 scope. This includes:
        *   All CRUD for lists, items, group chores, personal chores.
        *   All expense creation types, viewing expenses/splits, settling shares.
        *   OCR item addition.
        *   Offline scenarios: create/update/delete an item offline, go online, verify sync.
        *   Simulate a conflict and test the conflict resolution dialog flow."
    *   **Verification:** All E2E tests pass reliably.

*   **Task 5.2: Final UI/UX Polish & Accessibility (Valerie UI).**
    *   **Action for LLM:** "Review all UI components and pages. Ensure consistent use of Valerie UI. Check for usability issues, clear error messaging, and intuitive workflows. Perform an accessibility check (e.g., using browser dev tools, axe-core plugin) and address any critical violations (keyboard navigation, ARIA attributes, color contrast)."
    *   **Verification:** App feels polished, is easy to use, and meets basic accessibility standards.

*   **Task 5.3: CI/CD Pipeline Enhancement.**
    *   **File(s):** `.gitea/workflows/ci.yml`.
    *   **Action for LLM:** "Update the Gitea CI workflow:
        1.  Add steps to run all backend unit and integration tests.
        2.  Add steps to build the frontend.
        3.  Add steps to run all Playwright E2E tests against the built frontend (potentially using a preview server).
        4.  Ensure the pipeline fails if any tests fail.
        5.  (Optional Advanced) Add steps for automated deployment to staging/production on successful builds of specific branches."
    *   **Verification:** CI pipeline automatically tests backend and frontend, including E2E, on commits/PRs.

*   **Task 5.4: DevOps - Dockerization & Deployment Prep.**
    *   **File(s):** `be/Dockerfile`, `fe/Dockerfile`, `docker-compose.yml`.
    *   **Action for LLM:** "Review Dockerfiles for backend and frontend for production readiness (e.g., multi-stage builds, minimal image size, correct CMD). Ensure `docker-compose.yml` correctly sets up services for local development and can serve as a basis for production deployment environment variables. Document deployment steps for chosen cloud platforms (as per your doc)."
    *   **Verification:** Application can be built and run reliably using Docker locally. Deployment strategy is clear.

*   **Task 5.5: Error Tracking & Logging Review.**
    *   **File(s):** `be/app/main.py` (Sentry init), `fe/src/main.ts` (Sentry init).
    *   **Action for LLM:** "Verify Sentry is correctly initialized in both frontend and backend. Test that errors are captured in Sentry. Review backend logging (`LOG_LEVEL`, `LOG_FORMAT` in `be/app/config.py`) to ensure it provides useful information for debugging in production."
    *   **Verification:** Errors from both frontend and backend are reported to Sentry. Logs are informative.

