kvitt/docs/HANDOFF.md

Handoff: state of the work

Living document, rewritten in place (never a second copy). A new orchestrator session reads CLAUDE.md, then this.

1. Where things stand

• main at 6b60ef7 (M12a) plus the SPEC v0.8 docs commit from agent-spec8 once it lands. History: 5e1be38 plans and prompts, c885aba M2c-dev, 76ee957 SPEC v0.3, fad6fc9 M2b, fdf2093 M2a, 040bf41 SPEC v0.4, 503cee5 M3, c28c52b M5, 982451d SPEC v0.5, bd6f10a M4, 23a2f1e SPEC v0.6, ab298ab M9, e8ee518 SPEC v0.7, 6b60ef7 M12a.
• Landed: M0 spec, M1 contracts and vectors (c6df2ab), M2a server skeleton and kvitt-domain (fdf2093), M2b Android skeleton and :domain (fad6fc9), M2c-dev infra for development (c885aba), M3 server core API (503cee5), M4 server sync, audit, push, scheduler (bd6f10a), M5 Android data layer (c28c52b), M9 Splitwise importer (ab298ab), SPEC v0.7 (e8ee518), M12a category contract v2 contracts and :domain suggestCategory (6b60ef7; OpenAPI DefaultCategoryKey and the new category examples held back for M12b). With agent-spec8: SPEC v0.8, the owner's UX-session decisions UX-1 to UX-8 as D-047 to D-054 (Kalas muted, three tabs, category suggestion §9.11, S-1 name field, colour tokens, smaller UX rules, finer import mapping, fourteen default categories with server schema 2), and the milestone group M12 with PLAN-M12a/b/c and prompts, reconciled with what M12a landed (§14.1.1 copied from the contract file, :domain types with UnicodeText, vector keys).
• Known red test: from the landing of SPEC v0.8 until M12b lands, main's server gate has exactly one failing test, the importer's category_table_matches_the_spec, which parses the §10.8 table that v0.8 changed (D-053). M12b fixes it; land M12b next.
• Both gates exist: Android tools/gradle-serial.sh check (from android/), server cargo fmt --check && cargo clippy --all-targets -- -D warnings && cargo test (from server/).
• Worktrees in flight under .claude/worktrees/: agent-spec8 (this docs change: SPEC v0.8).
• The owner runs the UX sprint in a separate Claude session in ~/orca/workspaces/kvitt/UX-sprint on branch UX-sprint; it commits only under docs/ux/ and rebases on main before landing; its results reach the main line through docs/ux/proposed-decisions.md and a docs agent (CLAUDE.md › Orchestration). Direction 3 "Kalas" with the muted palette is picked and approved (D-047); U2 (design spec, renamed strings.csv, per-screen PNGs, the §9.7 hex values including slate and amber) is in progress there.
• Importer rehearsal (M11 preparation), 2026-10-18: the real run reconciled on both real files in a throwaway database (Vardag 1746 rows, Hemma 37 rows); 21 rows were unmapped before D-044, 0 are expected after it. After M12b the mapping is finer (D-053); the next dry run confirms it. The CSV files stay in export/ (git-ignored).
• Development stack (M2c-dev): running on the Mac with the M4 image, reachable at http://192.168.1.210:8080; the owner confirmed /health from the phone on the home Wi-Fi on 2026-10-17. Its database is at schema 1; an image with M12b upgrades it to 2 on start (back it up first). Firebase project kvitt-1337 with apps se.hagstedt.kvitt and se.hagstedt.kvitt.debug; service account kvitt-fcm; infra/secrets/fcm-service-account.json and infra/secrets/google-services.json in the main checkout (git-ignored).
• Installed on the owner's phone (SM-S942B): the debug app se.hagstedt.kvitt.debug built from main at c28c52b, as of 2026-10-18.

2. Open work (one line each, with who owns it: agent or owner)

• Land agent-spec8 (orchestrator): SPEC v0.8, decisions D-047 to D-054, PLAN-M12a/b/c, prompts M12a/b/c, CLAUDE.md UX-sprint note, plan touch-ups (M6, M7c, M7f, U2).
• Next: M12b (server; also the OpenAPI enum and the held-back examples) and M12c (Android) in parallel.
• Image build for the Pi (M2c-pi or M10): since M4 the arm64 server image needs a C toolchain in the build stage (aws-lc-rs) and CA roots in the distroless image (§10.3); confirm both and one FCM send from the shipped image.
• D-027 re-stamp (orchestrator assigns: M8 as a contract request on :data, a small :data agent, or fold into M12c): on the first sync attempt after a clock_skew rejection the phone re-stamps updated_at of each such pending row to its current clock before pushing. Not in :data at c28c52b.
• Picture size (M6, if needed): :data always fetches E-11 at 512; a size parameter for the 128 variant is a contract request on :core:model and :data.
• After U2 reports: a docs agent records the §9.7 hex values (muted Kalas, slate and amber), U2's other spec proposals, and the four new default names in docs/ux/strings.csv (D-051, D-054).
• Plans (SPEC §11.2 v0.8), in dependency order; prompt prompts/<id>.md:
  • M1, M2a, M2b, M2c-dev, M3, M4, M5, M9: landed.
  • M12a Category contract v2, contracts: landed (6b60ef7).
  • Next waves: M12b (server) and M12c (Android) in parallel now; U2 (owner's session; owner approves); then M6 Design system after U2, the §9.7 values and M12c; M7a to M7f after M6 in parallel (M7c also after M12c); M8 App integration after M7; M2c-pi Infra on the Pi after M8 (owner: answer OQ-3, grant the Pi, Home Assistant Pi, Gitea and Drive allowances at the start, D-023); M10 First release after M2c-pi (owner: keystore per §10.6, D-024); M11 Import history after M9 and M10 (procedure §10.8 "Production run", D-025; each run must reconcile, D-045).

3. HUMAN steps pending (relay in chat)

• U2 approval: the owner approves U2's design spec in the UX-sprint session.

4. Owner questions (asked, unanswered)

• OQ-3 LAN addresses and SSH users of the Kvitt Pi and the Home Assistant Pi; SSH port of the HA Pi; certificate directory there; which SSH add-on (SPEC §12). Needed by M2c-pi only. The only open question (OQ-1, OQ-2, OQ-4 answered: D-001, D-003, §10.9).

5. Paused (waiting on something outside the repo)

• Nothing.

6. Numbering

• Decisions: D-001 to D-054 used (D-008 and D-009 unused). Next free: D-055.
• Spec version: v0.8 written; next v0.9.
• Server schema version 2 (migration 0002, implemented by M12b); next 3. Room schema version 1 (android/data/schemas/se.hagstedt.kvitt.data.db.KvittDatabase/1.json, unchanged by M12); next 2.
• Sync protocol 1, push payload 1.

7. How the work is run

See CLAUDE.md › Orchestration. HUMAN steps in reports are relayed in chat by the orchestrator; the owner does not read them in files.