Pre Release Cleanup

---
description: Long-running pre-release sweep — branch/DB sanity, UI consistency, dedup, silent-default eradication, locale enforcement, date semantics, LoC reduction, Dart best-practices audit, dead code, provider-name leak check, bug hunt loop. Run before every major release.
---

Mission: harden the codebase before a major release. Long-running and exhaustive — keep iterating until a full pass produces zero findings in every phase. Behavior must be preserved unless a phase explicitly fixes a bug (in which case a failing test must exist first). Read the project guidelines file (`AGENTS.md`, or `CLAUDE.md` if that is what the repo uses) in full before starting.

Do not hardcode-trust the paths/filenames mentioned in this command — the codebase refactors over time. Treat every path below as a hint, not a guarantee: if a referenced file does not exist, locate the current equivalent by its role (grep/glob for the canonical implementation) and proceed. The phase intent is authoritative; the example path is not.

## Phase 0 — Sanity gate (do once, never skip)
1. Confirm current branch is `develop` (or whatever target the user specified). If not, STOP and ask.
2. Confirm `DB_FILE_NAME` in `.env` matches the intended dev DB. Never let tests/builds touch the user's real production DB (the sandboxed app DB — see the "Database & Sandbox" section of the guidelines file for the current per-platform location). Tests/builds must always run against a disposable dev/test DB.
3. Capture green baseline (all four MUST pass before proceeding). Integration runs MUST target the disposable test DB — never the dev/real DB:
   - `dart fix --apply && dart analyze lib/ test/ integration_test/`  (zero warnings/infos)
   - `flutter test`
   - `flutter test integration_test/all_tests.dart -d macos --dart-define=DB_FILE_NAME=finance_copilot_test.db`
   - `flutter test integration_test/live_data_fetch_test.dart -d macos --dart-define=DB_FILE_NAME=finance_copilot_test.db`
   (If the test entrypoints have been renamed, discover the current ones under `integration_test/` before running. Always pass `DB_FILE_NAME=finance_copilot_test.db` — integration tests delete that file.)
4. Record starting LoC: `find lib -name '*.dart' -not -name '*.g.dart' | xargs wc -l | tail -1`.
5. If anything in step 3 is red, STOP — fix the existing red before this command can do anything else.

## Phase 1 — UI consistency audit (report only, no edits)
Catalog every instance of these patterns and flag deviations from the canonical reference:
- **Delete affordances**: trashcan icon in detail view + swipe-to-delete in lists is canonical. Any long-press-to-delete is a violation. Any three-dot menu offering delete must be reconciled.
- **Collapsible cards**: chevron + header layout MUST match the canonical Cash Flow tab implementation (currently `lib/ui/screens/dashboard/cashflow_tab.dart`; if renamed/split, find it by role). Header must NOT change on expand/collapse; expand must scroll smoothly, not snap.
- **Wizard "Next" button bars**: must use one shared widget, not per-screen reimplementations.
- **Empty states**: same icon + tagline pattern across screens.
- **Error toasts / snackbars**: same component, same placement.
Output: a markdown table of `screen | pattern | canonical? | action`. Then proceed to fix only the ones that are clear-cut; leave ambiguous ones for the user.

## Phase 2 — Duplication kill (pinning test required)
For each suspected duplication:
1. Grep for the duplicated function body / widget tree / SQL fragment.
2. Identify the older / canonical implementation. The older one wins; the newer collapses into it.
3. Write a pinning test that captures current behavior of BOTH sites.
4. Extract to a single shared utility / service method / widget.
5. Re-run the pinning test — must pass with byte-identical output.
NEVER copy/paste. NEVER start a new implementation when one exists — fit into the current codebase.

## Phase 3 — Silent-default eradication
Hunt and fix every silent fallback that hides incorrect financial data:
- Every `?? <number>` in money/FX/quantity paths.
- Every `try/catch` in conversion code that returns the original amount on failure.
- Every `return amount` after a failed FX lookup.
- Every per-asset price fallback (FORBIDDEN — missing price → asset shows "—" and is excluded from totals with a footnote count).
For each: replace with one of (a) surface to user via visible indicator + log warning, (b) skip the calculation entirely, (c) propagate the error. NEVER hide.

## Phase 4 — Locale enforcement
1. Grep for literal user-visible text in `lib/ui/`:
   `grep -rEn "Text\\(['\"]" lib/ui/ | grep -v AppStrings | grep -v '//'`
   Every hit must move to `AppStrings` / l10n.
2. Grep for hardcoded decimal-separator parsing (`.replaceAll('.', '')`, `.split(',')` on numbers, `double.parse` on un-normalized strings). Replace with locale-aware `NumberFormat(localeTag).parse()`.
3. Grep for hardcoded date format strings (`DateFormat('dd/MM/yyyy')` without locale arg). Route through `lib/utils/date_parser.dart`.
4. Verify all l10n bundles (en, it, …) cover every key — no missing translations.

## Phase 5 — Date semantics audit
1. List every `Date` column in `lib/database/tables.dart`. For each, classify as `valueDate`-style or `operationDate`-style.
2. Grep every consumer (queries, widgets, charts). Verify display/sort/charts use `valueDate`. `operationDate` may ONLY appear in import dedup cutoff logic.
3. Confirm `assetEvents` and `incomes` tables both have a populated `valueDate` column. If not — bug. Add a failing test, then fix.

## Phase 6 — LoC reduction (no behavior change)
Tests are NOT in scope for shrinking. Each pass:
- Collapse remaining duplicated logic into single source of truth.
- Inline one-shot helpers used only once.
- Replace verbose `if/else` chains with expression form, `switch`, or collection methods where it stays readable.
- Remove unreachable branches and redundant null checks where the type syste