wip: project setup paused pre-Phase-1 (0/5 phases)

.planning/.continue-here.md

@@ -0,0 +1,86 @@
+---
+context: default
+phase: none (pre-Phase-1 — project initialized, planning not started)
+task: 0
+total_tasks: 5
+status: paused
+last_updated: 2026-06-03T20:34:20.534Z
+---
+
+<current_state>
+`/gsd-new-project` ran to completion. FamilySync is fully initialized: PROJECT.md, config.json,
+research (STACK/FEATURES/ARCHITECTURE/PITFALLS/SUMMARY), REQUIREMENTS.md (20 v1 reqs), and an
+approved 5-phase ROADMAP.md (MVP mode) are all written and committed. Working tree is clean.
+No phase/plan/task work has started yet. The immediate next step is `/gsd-discuss-phase 1`.
+</current_state>
+
+<completed_work>
+
+- PROJECT.md written + committed (ad2aad8)
+- config.json: interactive mode, standard granularity, parallel, balanced (Sonnet) models,
+  research + plan-check + verifier + drift-guard all on (1ce0348)
+- Domain research: 4 parallel researchers + synthesis (0f79277)
+- REQUIREMENTS.md: 20 v1 requirements — AUTH-01..03, CAL-01..08, LIST-01..04, NOTIF-01..03, PWA-01..02 (a20afd4)
+- ROADMAP.md + STATE.md: 5 phases, 20/20 coverage; CLAUDE.md generated (ac82d32)
+</completed_work>
+
+<remaining_work>
+
+5 phases, none started:
+1. Foundation + Broker Spike — AUTH-01/02/03, CAL-01, CAL-08
+2. Calendar Display — CAL-02, CAL-03
+3. Event Write-Back + PWA Install — CAL-04/05/06/07, PWA-01/02
+4. Shared Lists + Live Sync — LIST-01/02/03/04
+5. Web Push Notifications — NOTIF-01/02/03
+</remaining_work>
+
+<decisions_made>
+
+- **Fastmail calendars are CalDAV-only** — JMAP-for-calendars is not available (pending RFC 8984).
+  Broker authenticates with a Fastmail **app password**, NOT an API token (tokens are JMAP-only).
+  This resolves the long-open JMAP-vs-CalDAV question.
+- **Stack:** Hono + Drizzle (mysql2/MariaDB) + tsdav + ical.js + rrule + vite-plugin-pwa +
+  web-push + @hono/oidc-auth; SSE (+ optional Redis) for live list sync.
+- **CAL-08 personal-calendar overlay is spike-gated in Phase 1** with a shared-family-only fallback.
+- v1 scope: all 4 calendar views; recurring create+display only (single-instance edit -> v1.x);
+  all 3 push types (event reminder, list-change, event-change).
+- **Vertical MVP** structure (each phase = end-to-end user capability).
+- Authelia already deployed + both members have accounts -> Phase 1 auth is OIDC-client
+  integration only.
+</decisions_made>
+
+<blockers>
+- None blocking. One important open question (see Pre-Execution / human actions): where the wife's
+  personal calendar actually lives (Fastmail vs iCloud) — determines whether CAL-08 is achievable.
+</blockers>
+
+## Required Reading (in order)
+1. `.planning/ROADMAP.md` — the 5-phase plan and per-phase success criteria
+2. `.planning/research/SUMMARY.md` — cross-cutting findings; read before Phase 1 planning
+3. `.planning/research/PITFALLS.md` — phase-mapped risks (CalDAV RRULE/ETag, iOS Web Push, Authelia, Pangolin)
+4. `.planning/REQUIREMENTS.md` — 20 v1 requirements + traceability
+5. `.planning/PROJECT.md` — project context, constraints, open questions
+6. `.planning/notes/familysync-architecture.md` — reasoning behind dropped options (Baikal/Vikunja)
+
+## Critical Anti-Patterns (do NOT repeat these)
+- ANTI-PATTERN: Assuming JMAP for calendar read/write → it does not exist on Fastmail. Use CalDAV (tsdav) only.
+- ANTI-PATTERN: Building calendar UI before proving the personal-calendar share works → Phase 1 spike gates CAL-08 first.
+- ANTI-PATTERN: Treating iOS Web Push as working from a Safari tab → it requires an installed (Add-to-Home-Screen) PWA; the guided install UX is load-bearing, not optional.
+
+## Infrastructure State
+- Unraid + Docker Compose host; Authelia deployed (both members have accounts); Pangolin/Newt tunnel for public access (no open ports); MariaDB available, Redis available, no PostgreSQL.
+- Nothing for FamilySync deployed yet — greenfield repo, only `.planning/` + generated CLAUDE.md exist.
+
+## Pre-Execution Critique Required
+- Before/at Phase 1: confirm where the wife's PERSONAL calendar lives (Fastmail vs iCloud). If iCloud, CAL-08 (personal overlay) is unreachable via the Fastmail broker and degrades to shared-only (v1.x). This is the Phase 1 go/no-go spike.
+
+<context>
+This is a clean handoff right after project setup — no mid-task state to untangle. The roadmap is
+approved as-is. The one piece of judgment to carry forward is the CAL-08 risk: front-loaded into
+Phase 1 deliberately. Knowing the wife's calendar location before planning Phase 1 would sharpen it.
+</context>
+
+<next_action>
+Start with: `/gsd-discuss-phase 1` — and open by confirming where the wife's personal calendar
+lives, since it drives the CAL-08 go/no-go spike.
+</next_action>

.planning/HANDOFF.json

@@ -0,0 +1,42 @@
+{
+  "version": "1.0",
+  "timestamp": "2026-06-03T20:34:20.534Z",
+  "phase": null,
+  "phase_name": "Pre-Phase-1 (project initialized, planning not started)",
+  "phase_dir": null,
+  "plan": null,
+  "task": null,
+  "total_tasks": null,
+  "status": "paused",
+  "completed_tasks": [
+    {"id": 1, "name": "PROJECT.md written + committed", "status": "done", "commit": "ad2aad8"},
+    {"id": 2, "name": "config.json (interactive, standard, parallel, balanced, research/plan-check/verifier/drift-guard on)", "status": "done", "commit": "1ce0348"},
+    {"id": 3, "name": "Domain research — 4 parallel researchers + synthesis (STACK/FEATURES/ARCHITECTURE/PITFALLS/SUMMARY)", "status": "done", "commit": "0f79277"},
+    {"id": 4, "name": "REQUIREMENTS.md — 20 v1 requirements across AUTH/CAL/LIST/NOTIF/PWA", "status": "done", "commit": "a20afd4"},
+    {"id": 5, "name": "ROADMAP.md + STATE.md — 5 phases, MVP mode, 20/20 coverage; CLAUDE.md generated", "status": "done", "commit": "ac82d32"}
+  ],
+  "remaining_tasks": [
+    {"id": 6, "name": "Phase 1 — Foundation + Broker Spike: discuss → plan → execute", "status": "not_started"},
+    {"id": 7, "name": "Phase 2 — Calendar Display", "status": "not_started"},
+    {"id": 8, "name": "Phase 3 — Event Write-Back + PWA Install", "status": "not_started"},
+    {"id": 9, "name": "Phase 4 — Shared Lists + Live Sync", "status": "not_started"},
+    {"id": 10, "name": "Phase 5 — Web Push Notifications", "status": "not_started"}
+  ],
+  "blockers": [],
+  "human_actions_pending": [
+    {"action": "Confirm where the wife's PERSONAL calendar actually lives (Fastmail vs iCloud)", "context": "CAL-08 personal-calendar overlay depends on cross-account Fastmail CalDAV sharing, which is unconfirmed. If her calendar is on iCloud, the broker cannot reach it and CAL-08 degrades to shared-family-only (moves to v1.x). This is the Phase 1 go/no-go spike — knowing the answer up front de-risks planning.", "blocking": false},
+    {"action": "Have a Fastmail app password ready for the broker account (CalDAV)", "context": "Fastmail calendar access is CalDAV-only (no JMAP for calendars). The broker authenticates with an app password, NOT an API token (API tokens are JMAP-only). Needed for the Phase 1 broker read spike.", "blocking": false},
+    {"action": "Be ready to register FamilySync as an OIDC confidential client in the existing Authelia", "context": "Authelia is already deployed and both members already have accounts. Phase 1 auth = OIDC client registration + integration only (no Authelia deploy, no account provisioning).", "blocking": false}
+  ],
+  "decisions": [
+    {"decision": "Calendar access is CalDAV-only; JMAP-for-calendars is not available on Fastmail", "rationale": "Fastmail docs: JMAP calendar support pending RFC 8984 finalization. Resolves the long-standing JMAP-vs-CalDAV open question.", "phase": "pre-1"},
+    {"decision": "Recommended stack: Hono + Drizzle (mysql2/MariaDB) + tsdav + ical.js + rrule + vite-plugin-pwa + web-push + @hono/oidc-auth; SSE (+ optional Redis) for list sync", "rationale": "Full convergence across all 4 research threads; current/maintained libraries.", "phase": "pre-1"},
+    {"decision": "Personal-calendar overlay (CAL-08) is spike-gated in Phase 1 with shared-only fallback", "rationale": "Cross-account CalDAV sharing unconfirmed and wife's cal may be on iCloud — biggest v1 risk; prove before building UI.", "phase": "1"},
+    {"decision": "v1 includes all 4 calendar views, recurring create+display (single-instance edit -> v1.x), and all 3 push types", "rationale": "User scoping decisions during requirements.", "phase": "pre-1"},
+    {"decision": "Vertical MVP structure (each phase = end-to-end user capability)", "rationale": "Fits broker-spike-then-build order; validates risk on a working slice early.", "phase": "pre-1"},
+    {"decision": "Wall display deferred to v2; lists in MariaDB (no Vikunja); calendar on Fastmail (no Baikal)", "rationale": "From PROJECT.md + architecture note; v1 core is calendar + lists.", "phase": "pre-1"}
+  ],
+  "uncommitted_files": [],
+  "next_action": "Run /gsd-discuss-phase 1 (Foundation + Broker Spike). Open with confirming where the wife's personal calendar lives, since it drives the CAL-08 go/no-go.",
+  "context_notes": "Project initialization via /gsd-new-project is fully complete and committed; working tree is clean. No phase/plan/task work has started. The roadmap is approved (5 phases, MVP mode). The single most important thing carried forward: the personal-calendar overlay risk (CAL-08) — Fastmail is CalDAV-only and cross-account sharing is unproven. Phase 1 front-loads this as a go/no-go spike."
+}