kvitt/PLAN-M11.md

PLAN-M11: Import history

Path changed by D-125 (SPEC v0.24, 2026-10-20). /opt/kvitt/import is now ~/kvitt/import (/home/jacobhagstedt/kvitt/import), and every Pi command runs in ~/kvitt; SPEC §10.8 "Production run" is current.

1. Goal

Run the Splitwise importer once against the production database with the owner's two real exports, so six years of history appear on both phones. Prove it by comparing the imported per-account balances with Splitwise's own total rows and record the comparison, aggregates only, in docs/validation/splitwise-import.md.

2. Read first

1. SPEC §10.8 Splitwise import, §4 FR-17 Splitwise import.
2. SPEC §12 OQ-2 (answered) and docs/decisions.md D-003.
3. SPEC §10.8 "Production run" (D-025), §10.2 (the /opt/kvitt/import mount), §10.9 Backups and restore (backup run), §10.4 (running commands on the Pi), §10.10 Operations.
4. SPEC §9.3 Balances.
5. SPEC §11.2 (row M11), §14.7.
6. PLAN-M9.md §3 (mapping notes: header lines and member names), infra/README.md, infra/RESTORE.md.
7. CLAUDE.md (ANTI-PATTERNS: never commit personal data or the Splitwise CSV; THE OWNER: confirm before anything destructive; EXECUTION PROTOCOLS: Reports are deliverables).

3. Already established

• Files: export/export_hemma.csv (English variant, group "hemma") into account "Hemma"; export/export_general.csv (Swedish variant, general group, about 1750 rows) into account "Vardag"; both in the main checkout, git-ignored, all SEK (D-003).
• Command per file: kvitt-import --db /data/kvitt.sqlite --file <csv> --account "<name>" --user "<Splitwise name of the owner>=<owner user id>" --user "<Splitwise name of the partner>=<partner user id>" [--dry-run], run on the Pi with the server stopped as docker compose run --rm --entrypoint kvitt-import server … (§10.8 "Production run", D-025). Names exactly as in the file headers (PLAN-M9 mapping notes).
• Re-running creates nothing new (import key); imported rows get audit entries with source import and no pushes (AC-17.2, AC-17.6).
• Unknown categories map to other and are counted as a warning (§10.8).
• Splitwise's trailing Total balance / Totalsumma row is ignored by the importer and is the reference for the comparison (§10.8, §11.2).
• Reports carry aggregates only; no descriptions, no individual amounts, no names beyond the account names (CLAUDE.md).

4. Owned paths

From SPEC §14.7, verbatim: docs/validation/<file> | "the milestone that names the file", here docs/validation/splitwise-import.md.

Edit nothing outside these paths; a needed change elsewhere is a contract request to the orchestrator.

Never edit SPEC.md or docs/decisions.md: put proposed decision entries in the report.

Resolved open points (SPEC v0.3, D-025):

• (a) The CSVs are copied from the Mac to the Pi into /opt/kvitt/import/, bind-mounted read-only into server as /import; the import runs on the Pi as docker compose run --rm --entrypoint kvitt-import server --db /data/kvitt.sqlite --file /import/<file> … (--entrypoint because the image's entrypoint is kvitt-server); the CSVs are deleted from the Pi afterwards.
• (b) A backup is taken first (docker compose exec backup /backup.sh, confirmed on Drive).
• (c) The production user ids are resolved by display name from the database (read-only SELECT id, role, display_name FROM users through the backup container's sqlite3); the owner is the admin user.

5. Deliverables

• docs/validation/splitwise-import.md: per file: rows read, expenses, settlements, skipped duplicates, unmapped category names with counts; per account: the imported balance (net from the owner's side) and Splitwise's total-row balance, equal or not; the re-run result (nothing new); the phones' confirmation; a "Results (owner's phone)" section if anything is still to come.
• Production database on the Pi with the imported history (not in git).

6. Steps

1. Worktree. From the main checkout /Users/jhag/projects/kvitt: git worktree add .claude/worktrees/agent-m11 -b agent-m11 main, then in .claude/worktrees/agent-m11: git reset --hard main. Copy infra/secrets/ from the main checkout if SSH to the Pi needs it. Do not copy export/ into the worktree; read the files from /Users/jhag/projects/kvitt/export/. Run tools/install-git-hooks.sh.
2. Read §2 in order. Confirm M9 and M10 have landed and production is healthy; if not, stop and report.
3. Backup (resolved point b), resolve the user ids (resolved point c), copy the CSVs to /opt/kvitt/import/, stop server, and dry-run each file with the command of resolved point (a) and --dry-run; start server again; record the aggregates; stop and ask if any row is invalid, any currency is not SEK, or unmapped categories are more than the owner expects.
4. Confirm with the owner (through the orchestrator) before writing to production. If anything was written since the backup of step 3, take a new one (docker compose exec backup /backup.sh, confirmed on Drive).
5. docker compose stop server; run the import for "Hemma" then "Vardag" with the command of resolved point (a); docker compose start server; check /health. Delete the CSVs from /opt/kvitt/import/.
6. Re-run both imports with --dry-run (copy the CSVs again, delete them afterwards): zero new rows expected.
7. Compute each account's balance from the database with the §9.3 definition (or via the app's numbers pulled over USB), and compare with the total row of each file (parsed by a script that prints only the two member totals); record equal or not.
8. The phones sync; the owner confirms the balances (§8).
9. Write docs/validation/splitwise-import.md. Commit on agent-m11 (only that file; git status shows no CSV), git rebase main. Never merge, push or remove the worktree.

7. Gate

From SPEC §11.2, verbatim: "Imported balances equal Splitwise's "Total balance" rows per group". Green means: for "Hemma" and "Vardag" the imported balance equals the file's total row (Total balance in the English file, Totalsumma in the Swedish file) to the öre, recorded in docs/validation/splitwise-import.md; the re-run dry run reports zero new rows.

8. HUMAN steps

From SPEC §11.2, verbatim: "Provide the CSVs; confirm the balances on the phone match Splitwise".

• Provide the CSVs: done for both files (export/, D-003). If the owner exports newer files before the run, they replace these in export/ before step 3.
• Before step 5: the owner says yes to writing into production (CLAUDE.md, destructive-data rule).
• After step 8, on each phone: open Kvitt Home and Splitwise side by side; answer yes/no: "Hemma" and "Vardag" show the same balance and direction as Splitwise.

9. Out of scope

• Changing the importer (M9; findings go in the report as new work).
• Importing other groups or later Splitwise data.
• Editing imported rows by hand; deleting anything.
• Committing, copying into the repository, or quoting the CSVs.

10. Report

• Branch agent-m11, head commit hash after rebasing on main.
• Gate: the per-account comparison lines (equal or not) and the re-run result.
• Dry-run aggregates per file; unmapped category names with counts.
• Backup stamp taken before the import.
• How resolved points (a) to (c) were applied.
• Proposed decision entries (never written to SPEC.md or docs/decisions.md by this agent) or TODO(spec) occurrences.
• HUMAN steps done and outstanding, worded for relay.
• Contract requests, open questions, spec gaps (with section numbers).

11. Numbering

Decision ids, spec version and schema version are assigned by the orchestrator in the start prompt; use TODO(spec) if none was given.