---
context: phase
phase: 02-calendar-display
task: 0
total_tasks: 5
status: planned-not-executed
last_updated: 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>

<blockers>
- None. Clean pause between plan and execute.
</blockers>

## 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.)

<context>
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.
</context>

<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>