familysync/.planning/phases/02-calendar-display/.continue-here.md

context, phase, task, total_tasks, status, last_updated

context	phase	task	total_tasks	status	last_updated
phase	02-calendar-display	0	5	planned-not-executed	2026-06-04T19:28:41.530Z

<current_state> Phase 2 (calendar-display) is fully planned and verified, not yet executed. The plan-checker PASSED on iteration 2 (the initial check found 2 blockers + 3 warnings; all were fixed). 5 PLAN.md files exist across 4 waves. Phase 1 already shipped a working pnpm monorepo (apps/api Hono+Drizzle+CalDAV broker, apps/pwa React+Vite).

The immediate next step is execution: /gsd-execute-phase 2.

One uncommitted file: .planning/config.json (this session's settings changes). </current_state>

<completed_work>

This session:

• Phase 2 RESEARCH.md + Nyquist VALIDATION.md written and committed (a707f8d)
• PATTERNS.md written — 23 files classified, 19 analogs from Phase 1 code (5e14413)
• 5 PLAN.md files created in 4 waves; plan-checker PASSED iteration 2 (fc4cc2c)
  • Requirements coverage 3/3 (CAL-02, CAL-03, CAL-07); decision coverage 10/10
• Backlog item 999.1 added — "treat Fastmail as a calendar provider, support more" (8bd52c6)
• GSD config changed via /gsd-config: Adaptive profile, TDD on, per-milestone branching, auto-advance on; saved as global defaults (~/.gsd/defaults.json). config.json uncommitted. </completed_work>

<remaining_work>

• Execute Phase 2 — run all 5 plans across 4 waves:
  • Wave 1: 02-01 — schema (has_rrule/is_shared) + [BLOCKING] drizzle-kit push + dev-auth bypass + PWA vitest/jsdom harness + ICS fixtures + RED stubs
  • Wave 2: 02-02 (backend: expandOccurrences + windowed /api/events) ∥ 02-03 (frontend foundation: tokens, colorUtils, calendarConfig, hydrateEvents, Zustand store) — no file overlap
  • Wave 3: 02-04 — CalendarShell renders REAL windowed Fastmail events, color-coded, 4 views
  • Wave 4: 02-05 — EventDetailPopover + ColorLegend + nav/toolbar + skeleton/empty/error + human verify </remaining_work>

<decisions_made>

• Server-side recurrence expansion via ICAL.RecurExpansion, with VTIMEZONE registered BEFORE expansion (or DST events render at wrong wall-clock time).
• Schedule-X calendarId = occ.isShared ? 'shared' : String(occ.ownerUserId) — NOT String(occ.calendarId). The calendars config is keyed by userId; using the DB calendar-row id silently breaks color routing for members owning multiple calendars.
• Shared-family calendar identified via a calendars.is_shared column + operator checkpoint (chosen over fragile displayName matching).
• This-session GSD config: Adaptive profile, TDD on, per-milestone branching, auto-advance on. </decisions_made>

- None. Clean pause between plan and execute.

Required Reading (in order)

1. .planning/phases/02-calendar-display/02-01-PLAN.md … 02-05-PLAN.md — the plans to execute
2. .planning/phases/02-calendar-display/02-RESEARCH.md — DST/VTIMEZONE, Schedule-X Temporal, firstDayOfWeek 0→7, has_rrule pre-filter (the landmines)
3. .planning/phases/02-calendar-display/02-VALIDATION.md — per-task verification map (Nyquist)
4. .planning/phases/02-calendar-display/02-PATTERNS.md — analog files in the Phase 1 codebase

Critical Anti-Patterns (do NOT repeat these)

• Do NOT skip the [BLOCKING] npx drizzle-kit push task in Wave 1 (02-01). Build/types pass without it because TS types come from config, not the live DB → false-positive verification.
• Do NOT stamp String(occ.calendarId) as the Schedule-X calendarId — use isShared/ownerUserId.
• Do NOT expand recurrences before registering VTIMEZONE; do NOT shift all-day events through UTC (keep them as 'YYYY-MM-DD' / Temporal.PlainDate).

Infrastructure State

• Branch: main. git.branching_strategy is now milestone — execute may create a milestone branch.
• Phase 1 shipped: apps/api + apps/pwa, MariaDB via docker-compose. No background processes running.
• TDD is ON globally now, but Phase 2 plans were written PRE-TDD — they carry no TDD gates. Only Phase 3+ will get TDD. (Re-plan Phase 2 if you want TDD gates here.)

Everything went smoothly — no failures discovered, no rework beyond the one planned revision loop. The plans are execution-ready. The only thing a fresh agent must internalize is the auto-advance + per-milestone branching change made this session, and that TDD won't retroactively apply to Phase 2's already-written plans.

<next_action> Start with: /gsd-execute-phase 2. Two human checkpoints will pause execution — marking the shared-family calendar (Wave 2, plan 02-02) and final visual verification of the 4 success criteria (Wave 4, plan 02-05). Consider committing .planning/config.json first. </next_action>