F-r-ldraledigplannerare/NextSteps260914.md

Next Steps — handoff, 2026-09-14

Written at the end of a long, delivery-focused session so a fresh session can pick up without re-deriving anything. Read CLAUDE.md and ARCHITECTURE.md first — both remain current from the previous session. PLANNING_ENGINE_SPEC.md holds the approved design of the planning engine.

---

1. Where the app is

The core user journey works end to end, and every significant feature from NextSteps260913.md §3 is now implemented and committed.

log in → set up child, vacation days per year, planning goal → describe breaks as "6 weeks every summer, 4 weeks every Christmas" → get a costed multi-year plan showing which days are already free, which cost a semesterdag, which cost a föräldrapenningdag → save it to the calendar.

What was completed this session (all of §3.1–3.10 from the previous handoff, plus §4.1 issues):

• 3.1 surplus_advice now renders in PlanResults.tsx, matching the shortfall remedies layout
• 3.2 is_assumed surfaced with badges in the Plan balances table and Settings per-year table
• 3.3 Age-4 projection added to Plan tab proposal view (Age4Projection component reusing existing _age4_projections arithmetic from the Dashboard)
• 3.4 Röda dagar / klämdagar shaded in calendar with R/K badges (colour not the only signal)
• 3.5 Five backend-generated Swedish surfaces converted to message_key+data pattern; old fields REPLACED (not kept); demo_plan.py updated
• 3.6 Click-to-override mode toggle in Calendar (chose explicit toggle over modifier-click because drag multi-select owns plain click)
• 3.7 Click month name / year to fast-navigate between months
• 3.8 Red-days list in Settings (statutory + user overrides), paginated 4 years at a time
• 3.9 Flexible wishes ("när det passar bäst") with engine-driven red-day-dense proposals; PLANNING_ENGINE_SPEC.md §10 updated; backend entity/migration/repository/allocator; frontend season-preset toggle and unplaced outcome
• 3.10 Tests added for DevFetch, CalendarWeek, Dashboard, usePlannedDays
• 4.1 Three verification issues all fixed: typecheck pinned to local tsc, ESLint ignores coverage//dist/, flaky usePlanApply test fixed with waitFor
• Bonus: New GET /api/calendar/days endpoint (see ARCHITECTURE.md §13.3)

State at handoff

• Backend: 404 tests passing, ruff check clean, ruff format --check clean
• Frontend: 704 tests / 56 files, typecheck clean, lint 0 warnings
• Coverage: 96.52% lines / 91.08% functions / 86.78% branches (configured thresholds are being ratcheted up concurrently by another agent; state the measured numbers here, not the new targets)

---

2. Running it

cd frontend && npm run dev     # starts BOTH vite (5173) and uvicorn (8000)

If the servers die, restart individually:

cd backend  && uv run uvicorn app.main:app --reload --port 8000
cd frontend && npx vite

Gotcha that cost an hour last session: a stray python -m http.server 8000 was squatting *:8000 over IPv6. macOS resolves localhost → ::1 first, so Vite's /api proxy hit the squatter and every login returned 501. frontend/vite.config.ts now targets 127.0.0.1 explicitly. If the API behaves impossibly, check lsof -nP -iTCP:8000 -sTCP:LISTEN for extra listeners.

---

3. What's genuinely left

Every numbered item from the previous handoff is done. Only these remain:

3.1 Browser verification — HIGHEST PRIORITY

This is the single most important open item. The entire feature set is implemented and both test suites pass, but nothing has been clicked yet. Every significant bug last session was found by clicking through the app while tests were green.

Priority surfaces to click:

• §3.6: the new click-to-override mode toggle in Calendar
• §3.4: the röda dagar / klämdagar shading and R/K badges (colour accuracy)
• §3.8: the Settings red-days list pagination
• §3.9: flexible wishes end-to-end (propose, preview, apply) with season presets

(A browser pass may be running as this handoff is written — state it as outstanding at time of writing if it hasn't completed.)

3.2 Flexible-wish bounding-range picker (deferred, not rejected)

The WishEditor ships v1 with season presets only (vår, sommar, höst, jul). A custom date-range picker for flexible wishes is known, deliberate, and deferred. The product owner chose season presets as the first ship to unblock the core feature.

3.3 Frontend branch coverage

Currently 86.78%, the weakest coverage metric. It drifted slightly down during the session (components added faster than tests). This is a regression-ratchet issue — not urgent if the metric is rising over time, but worth watching.

---

4. Product-owner decisions made this session — don't relitigate

• Flexible wishes are a propose-time suggestion, confirmed in the Plan tab; never auto-applied. The engine picks the window, the family sees it in the Plan view and approves, like every other plan.
• Fixed wishes always win; flexible wishes fill remaining space. A flexible wish cannot displace a fixed one (displacing user-chosen dates would be surprising). Priority still orders among several flexible wishes.
• WishEditor ships v1 with season presets only: vår (03-01→05-31), sommar (06-01→08-31), höst (09-01→10-31), jul (12-01→01-31 wrapping). Custom bounding-range picker is deferred.
• An applied flexible occurrence may move on a later re-propose. No wish_id on planned_leave_day; the propose→apply preview is the guardrail.
• The Age4Projection stat on the Plan tab uses the proposed allocation. It answers "how many days expire if this plan is taken," acknowledging that life may not work out that way.

---

5. Known issues & traps

5.1 Traps from previous handoff (still true)

• The holidays library returns combined names. Easter Sunday comes back as "Påskdagen; Söndag". Filtering with "Söndag" in name silently deletes Påskdagen, Pingstdagen, Nationaldagen and Annandag jul. Match exact strings.
• _FULL_SCHEMA in backend/app/db/connection.py must stay in sync with Alembic migrations. Test fixtures apply that DDL string directly; forgetting it means tests run against a stale schema.
• vi.mock('@/context') does NOT intercept direct submodule imports like @/context/AuthContext. Mock the specifier the component actually imports.
• The dataclass → response mapping in app/models/plan.py is hand-written. New engine outputs are invisible to the UI until mapped. Always add an API-level test, not just a service test, when the wire format changes.
• localStorage is unreliable in the test sandbox. Work around it with vi.stubGlobal('localStorage', mock).
• git grep only searches tracked files. Use plain grep to catch untracked work.

5.2 New trap from this session

• A literal */ inside a JSDoc block comment prematurely closes it, breaking the whole file. Found in WishEditor.tsx during the flexible-wishes implementation. Avoid nested JSDoc strings with */ or escape them carefully.

---

6. How to verify

cd backend  && uv run ruff check . && uv run ruff format --check . && uv run pytest
cd frontend && npm run typecheck && npm run lint && npx vitest run && npm run coverage

Cost rule (from CLAUDE.md): large models must NOT run these themselves. Spawn a Haiku subagent to run them and paste raw output. Haiku agents run them directly. Always give the verifier the expected baseline and require verbatim output.

And verify in a browser. Both suites may pass while the app is broken in the browser. See §3.1.

---

7. Repo pointers

• PLANNING_ENGINE_SPEC.md — the engine design, including §10 on flexible wishes (added this session)
• ARCHITECTURE.md — system design; §13 covers the calendar cache and allocation service
• backend/scripts/demo_plan.py — runs the allocator standalone on Swedish defaults and prints a readable plan
• backend/scripts/fetch_swedish_calendar.py — regenerates the 10-year calendar cache
• CLAUDE.md — the operating guide for the repo

---

8. Clean state

All changes committed as e3d19f2. Working tree clean. Old todo files (todo.txt, todo_260912.txt) were fully addressed and deleted. todo-backend.txt (June notes on smoketests, postgres, scraper scope) is also deleted; those items are pre-work scope or in separate tracks and do not block any current work.