Add income tracking Phase 3: net budget math + income edit/delete

[derekl-beep]

Summary

Phase 3 of income tracking — closes the two pieces deliberately deferred out of Phase 2 (#45): net budget math for reimbursed expenses, and the ability to edit/delete income entries at all.

• Net budget math: get_budget_status's "spent" figure now nets each expense against any income linked to it via reimburses_expense_id, clipped at 0 per-expense so an over-reimbursed expense can't drag a category negative (e.g. a $60 dinner with a $30 linked reimbursement now counts as $30 spent against the Dining budget, not $60).
• Income edit/delete: update_income/delete_income (hard delete — unlike expenses, nothing else references income.id as a foreign key, so there's no soft-delete need), matching chat tools, and PATCH/DELETE /income/{id} endpoints mirroring the existing expense pattern. update_income deliberately never touches reimburses_expense_id — that stays link_income_to_expense's exclusive job, keeping the two tools non-overlapping.
• Net cash-flow stat: a small "Net" figure (all-time income − expenses) next to the existing "Total" in the Expenses/Income toggle header, computed client-side from data already loaded — no new fetch.

Deliberately not added: a get_cash_flow chat tool or /cashflow slash command. This repo's own roadmap already flags the analytics tool/command surface as possibly over-built (worth assessing real usage before investing further), so the net figure stays UI-only rather than adding a 13th query tool.

Review

Ran this repo's three-angle adversarial review pass (line-by-line, cross-file/removed-behavior, CLAUDE.md conventions) against the diff before committing. Confirmed: no SQL injection risk in the new dynamic queries, no dangling references from delete_income's hard delete (nothing else FKs to income.id, so a deleted reimbursement correctly and automatically un-reimburses its expense on the next read), the frontend netCashFlow figure correctly recomputes after any chat-driven save (both income/expenses props refetch together), and the id-collision guidance introduced in earlier phases still holds without contradiction.

Two real findings, both fixed:

• The SYSTEM prompt said "four tools split cleanly by table" but actually names five (update_expense, delete_expense, update_income, delete_income, link_income_to_expense) — miscount corrected.
• get_budget_status's netting is deliberately unscoped by the reimbursement's own date (it ties to the expense's month, regardless of when the income was recorded or linked) and deliberately differs from get_category_breakdown/get_monthly_trend/etc., which still report gross amounts actually paid. Neither is a bug — the budget figure should reflect true net out-of-pocket cost, while historical-spend tools should reflect what was actually paid at the time — but nothing explained the distinction, so a user could get two different numbers for the same transactions with the model having no way to explain why. Added a paragraph to the SYSTEM prompt covering both points.

Test plan

• uv run pytest tests/ — 150 passed (includes new tests for the netting math, over-reimbursement clipping, update_income/delete_income)
• npm run lint / npm run build — clean
• npx playwright test e2e/cashflow.spec.js — 2/2 (Net figure correct and stable across the Expenses/Income toggle)
• Full regression: npm run test:e2e — 68/68, no regressions

Roadmap / future work

Income tracking (Phases 1–3) is now feature-complete per the original plan. Nothing further currently tracked for this feature.

---

Generated by Claude Code