From 31c78965a7f86a2ff0f2d2a4f09d48fbe1aaeab0 Mon Sep 17 00:00:00 2001 From: Lucas Berger Date: Wed, 3 Jun 2026 16:35:19 -0400 Subject: [PATCH] wip: project setup paused pre-Phase-1 (0/5 phases) --- .planning/.continue-here.md | 86 +++++++++++++++++++++++++++++++++++++ .planning/HANDOFF.json | 42 ++++++++++++++++++ 2 files changed, 128 insertions(+) create mode 100644 .planning/.continue-here.md create mode 100644 .planning/HANDOFF.json diff --git a/.planning/.continue-here.md b/.planning/.continue-here.md new file mode 100644 index 0000000..00ca2e4 --- /dev/null +++ b/.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 +--- + + +`/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`. + + + + +- 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) + + + + +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 + + + + +- **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. + + + +- 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. + + +## 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. + + +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. + + + +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. + diff --git a/.planning/HANDOFF.json b/.planning/HANDOFF.json new file mode 100644 index 0000000..623bf4b --- /dev/null +++ b/.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." +}