From 771608d3d4f4cdcfadc1b5c0d0563bc989d72a18 Mon Sep 17 00:00:00 2001
From: Lucas Berger <me@lucasberger.ca>
Date: Sat, 13 Jun 2026 20:49:25 -0400
Subject: [PATCH] docs(11): capture phase context for per-event reminders

---
 .planning/STATE.md                            |  16 +--
 .../11-per-event-reminders/11-CONTEXT.md      | 130 ++++++++++++++++++
 .../11-DISCUSSION-LOG.md                      |  72 ++++++++++
 3 files changed, 210 insertions(+), 8 deletions(-)
 create mode 100644 .planning/phases/11-per-event-reminders/11-CONTEXT.md
 create mode 100644 .planning/phases/11-per-event-reminders/11-DISCUSSION-LOG.md

diff --git a/.planning/STATE.md b/.planning/STATE.md
index 7105e07..7467121 100644
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -3,15 +3,15 @@ gsd_state_version: 1.0
 milestone: v1.1
 milestone_name: Operability & Polish
 status: verifying
-stopped_at: "Completed Phase 10 Plan 02 (admin role primitives: requireAdmin, upsertUser is_admin, /api/me isAdmin+needsProviderSetup)"
-last_updated: "2026-06-13T19:45:55.920Z"
-last_activity: 2026-06-13
+stopped_at: Phase 11 context gathered
+last_updated: "2026-06-14T00:49:25.513Z"
+last_activity: "2026-06-13 - Completed quick task 260613-ndv: isolated local apps/api tests to familysync_test (dev DB no longer polluted)"
 progress:
-  total_phases: 20
+  total_phases: 21
   completed_phases: 8
   total_plans: 27
   completed_plans: 27
-  percent: 40
+  percent: 38
 ---
 
 # Project State
@@ -246,9 +246,9 @@ Recent decisions affecting current work:
 
 ## Session Continuity
 
-Last session: 2026-06-13T19:27:40.437Z
-Stopped at: Completed Phase 10 Plan 02 (admin role primitives: requireAdmin, upsertUser is_admin, /api/me isAdmin+needsProviderSetup)
-Resume file: None
+Last session: 2026-06-14T00:49:25.504Z
+Stopped at: Phase 11 context gathered
+Resume file: .planning/phases/11-per-event-reminders/11-CONTEXT.md
 
 ## Operator Next Steps
 
diff --git a/.planning/phases/11-per-event-reminders/11-CONTEXT.md b/.planning/phases/11-per-event-reminders/11-CONTEXT.md
new file mode 100644
index 0000000..17a5a63
--- /dev/null
+++ b/.planning/phases/11-per-event-reminders/11-CONTEXT.md
@@ -0,0 +1,130 @@
+# Phase 11: Per-Event Reminders - Context
+
+**Gathered:** 2026-06-13
+**Status:** Ready for planning
+
+<domain>
+## Phase Boundary
+
+A per-event reminder lead picker on the event form, round-tripped to Fastmail as a
+VALARM, with a variable-lead push scheduler that honors each event's choice. The
+preset list, default-None, VALARM DURATION-trigger format, preserve-on-edit
+mechanism, `uid:dtstartMs` dedup, variable scan window, dropping the `isShared`-only
+reminder restriction, and the scheduler reading `reminder_lead_minutes` from the DB
+as ground truth are all **locked by ROADMAP Phase 11 + research/PITFALLS.md** — this
+discussion only resolved the product/UX gray areas on top of that.
+
+</domain>
+
+<decisions>
+## Implementation Decisions
+
+### Reminder picker — timed vs all-day presets
+- **D-01:** Timed events keep the locked preset list: None / 5m / 10m / 15m / 30m / 1h / 2h / 1d / 2d, default **None**.
+- **D-02:** All-day events get a **context-swapped, day-granularity** preset list: **None / Same day / 1 day before / 2 days before / 1 week before**, default **None**. The picker is NOT hidden or disabled for all-day events.
+- **D-03:** The picker is shown for both event types — it swaps its option set based on the All-day toggle, rather than disappearing.
+
+### All-day reminder semantics
+- **D-04:** All-day reminders fire at **9 AM local** on the computed alert day (retains the roadmap's sensible-morning decision; "Same day" = 9 AM on the event's own date, "1 day before" = 9 AM the prior day, etc.).
+- **D-05:** All-day leads are stored in the existing `reminder_lead_minutes` column as minutes: Same day = `0`, 1d = `1440`, 2d = `2880`, 1wk = `10080`. The scheduler applies the 9 AM-local rule whenever the event is all-day.
+- **D-06:** **`reminder_lead_minutes` must distinguish "no reminder" from "same-day".** No reminder = `NULL` (no VALARM, no push). Same-day all-day = `0` (fire 9 AM on the event date). For timed events `0`/absent still means None. The scheduler and `outboxPayloadSchema` must treat NULL-vs-0 as semantically distinct.
+
+### Existing / non-preset alarms on edit (preserve — CAL-14)
+- **D-07:** **Show exact if single.** When an event already carries a reminder that isn't a preset: if it is a *single simple relative alarm*, render its real value in the picker (e.g. "45 min before") even though it's off-list. For *absolute-time triggers or multiple alarms*, show a read-only **"Custom (kept)"** entry.
+- **D-08:** In both off-list cases the original VALARM(s) are **preserved verbatim** on save unless the user explicitly selects a preset or None — never silently rewritten or dropped (mirrors the WR-01 RRULE-preserve pattern; `outboxPayloadSchema` distinguishes "no change" from explicit "no reminder").
+
+### Notification copy
+- **D-09:** Reminder push body uses **humanized relative** phrasing, largest sensible unit: "Starts in 2 days" / "Starts in 1 hour" / "Starts in 30 min". Replaces the current hardcoded `Starts in ${minutes} min` which breaks for long leads. Title and deep-link `navigate` behavior are unchanged.
+
+### Recurring events
+- **D-10:** **Series-level only.** One VALARM on the master event; every occurrence inherits the same lead, and the scheduler fires per occurrence naturally. No per-occurrence (RECURRENCE-ID) reminder override in this phase — see Deferred.
+
+### Claude's Discretion
+- Picker placement within `EventForm.tsx` (reuse the existing labeled `<select>` pattern used for Recurrence).
+- Exact humanized-unit thresholds/wording for D-09 (e.g. when to switch min→hour→day).
+
+</decisions>
+
+<roadmap_amendments>
+## Roadmap / Requirement Amendments (planner MUST honor)
+
+The all-day decision **reverses a locked roadmap criterion** — surfaced and authorized by the user during discussion:
+
+- **ROADMAP Phase 11 success-criterion 5** and **research/PITFALLS.md Pitfall 3** lock *"the reminder selector is disabled/hidden for all-day events"*. This is **overridden**: the picker is shown for all-day events with the D-02 day-granularity presets. The "9 AM local" fire time (criterion 5 / NOTIF-06) is **retained** and now applies to the chosen day-lead.
+- **`buildVeventString`'s `if (!allDay && reminderMinutes > 0)` guard** (Pitfall 3) must change to also emit a VALARM for all-day events with a day-based lead.
+- **CAL-13** preset list is extended for the all-day case (day-granularity presets per D-02); timed presets unchanged.
+- **NOTIF-06** stays satisfied (9 AM all-day fire) but now governs all-day day-leads, not a hidden/disabled selector.
+
+</roadmap_amendments>
+
+<open_questions>
+## Open for Research
+
+- **VALARM trigger encoding for all-day "N days before at 9 AM"** for other-client interop. An all-day VEVENT's DTSTART is a DATE (midnight); a bare relative DURATION trigger fires at midnight, not 9 AM. Research the best-effort trigger representation (relative DURATION offset vs absolute trigger) that other clients (Fastmail/Apple) honor reasonably. The **scheduler remains ground truth** for the actual push fire time (9 AM local via D-04/D-05), so interop fidelity here is best-effort, not exactly-once-critical.
+- Confirm `eventFieldsSchema` / `outboxPayloadSchema` can carry the NULL-vs-0 distinction (D-06) end to end.
+
+</open_questions>
+
+<canonical_refs>
+## Canonical References
+
+**Downstream agents MUST read these before planning or implementing.**
+
+### Phase scope & requirements
+- `.planning/ROADMAP.md` §"Phase 11: Per-Event Reminders" — goal, success criteria, owned pitfalls (note criterion-5 amendment above).
+- `.planning/REQUIREMENTS.md` — CAL-13, CAL-14 (lines 15–16); NOTIF-04, NOTIF-05, NOTIF-06 (lines 21–23).
+- `.planning/research/PITFALLS.md` — Pitfalls 1 (preserve-on-edit), 2 (no TRIGGER VALUE=TEXT), 3 (all-day guard — amended), 4 (`uid:dtstartMs` dedup).
+
+### Implementation surface (existing code this phase modifies)
+- `apps/api/src/broker/vevent.ts` — `buildVeventString` (VALARM emission, allDay guard to amend).
+- `apps/api/src/broker/write.ts` — write-back path; VALARM extraction/preserve from `rawVevent`.
+- `apps/api/src/broker/outboxWorker.ts` + `outboxPayloadSchema` — "no change" vs explicit "no reminder" distinction.
+- `apps/api/src/broker/reminderScheduler.ts` — variable per-event window, `uid:dtstartMs` dedup, drop `isShared`-only restriction, read `reminder_lead_minutes`, all-day 9 AM rule, humanized body (D-09).
+- `apps/api/src/db/schema.ts` — `calendarEvents.reminder_lead_minutes` (NULL-vs-0 semantics, D-06).
+- `apps/pwa/src/components/EventForm.tsx` — reminder `<select>` (reuse Recurrence-select pattern; allDay-aware preset swap).
+
+</canonical_refs>
+
+<code_context>
+## Existing Code Insights
+
+### Reusable Assets
+- `EventForm.tsx` already renders a labeled `<select>` for Recurrence (~line 852) — the reminder picker reuses this exact pattern, including the allDay-conditional rendering already present for time fields (`{!allDay && (...)}`).
+- `reminderScheduler.ts` already has the dispatch loop, per-event/per-sub error isolation, deep-link `navigate`, and the prune step — Phase 11 changes the *query window, dedup key, lead source, and body text*, not the dispatch plumbing.
+- `dispatchPush` / `pushDispatcher.ts` push pipeline reused unchanged.
+
+### Established Patterns
+- **WR-01 RRULE-preserve** in the write path is the template for VALARM preserve-on-edit (D-08): extract sub-components from `rawVevent`, re-attach rather than rebuild.
+- Phase 10 added `reminder_lead_minutes` as the scheduler's ground truth — the column already exists from the v1.1 migration (use generate+migrate if any column change is needed, **never** `drizzle-kit push`).
+- `setInterval`-only scheduling (node-cron silently skips ticks in the long-lived process — do not reintroduce).
+
+### Integration Points
+- Event form → `outboxPayloadSchema` → outbox worker → `buildVeventString` → Fastmail PUT.
+- DB `reminder_lead_minutes` → `reminderScheduler` → `dispatchPush` → browser push.
+
+</code_context>
+
+<specifics>
+## Specific Ideas
+
+- The current scheduler body is literally `Starts in ${minutes} min` (reminderScheduler.ts:157) — that is the string being replaced by D-09.
+- All-day "Same day" reminder was explicitly requested by the user as a useful heads-up case ("why not").
+
+</specifics>
+
+<deferred>
+## Deferred Ideas
+
+- **Per-occurrence reminder override** (RECURRENCE-ID) — flexible but significantly more complex; its own phase if ever wanted (D-10 keeps this phase series-level).
+- **Reminder snooze / notification-preferences UI** — already declared out of scope in REQUIREMENTS.md (over-build for a 2-member household).
+
+### Reviewed Todos (not folded)
+- `2026-06-13-pwa-phone-bottombar-overlap.md` — BottomTabBar overlaps the New Event FAB/legend. Belongs to **Phase 17 (UI Optimization & Polish)**, not reminders.
+- `2026-06-10-gitea-ci-regression-and-docker-publish.md` — CI regression/Docker publish. Tooling/CI scope (Phase 8 / backlog), unrelated to reminders.
+
+</deferred>
+
+---
+
+*Phase: 11-per-event-reminders*
+*Context gathered: 2026-06-13*
diff --git a/.planning/phases/11-per-event-reminders/11-DISCUSSION-LOG.md b/.planning/phases/11-per-event-reminders/11-DISCUSSION-LOG.md
new file mode 100644
index 0000000..2cefc32
--- /dev/null
+++ b/.planning/phases/11-per-event-reminders/11-DISCUSSION-LOG.md
@@ -0,0 +1,72 @@
+# Phase 11: Per-Event Reminders - Discussion Log
+
+> **Audit trail only.** Do not use as input to planning, research, or execution agents.
+> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered.
+
+**Date:** 2026-06-13
+**Phase:** 11-per-event-reminders
+**Areas discussed:** Existing-alarm display, All-day treatment, Notification copy, Recurring events
+
+---
+
+## Existing-alarm display (edit / preserve)
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| "Custom (kept)" sentinel | Read-only Custom entry; preserve verbatim unless changed | |
+| Snap to nearest preset | Show nearest preset; risks silent rewrite | |
+| Show exact if single | Render real value for single relative alarm; "Custom" for absolute/multiple | ✓ |
+
+**User's choice:** Show exact if single.
+**Notes:** Off-list single relative alarm shows its real value ("45 min before"); absolute-time or multiple alarms → read-only "Custom (kept)", preserved verbatim (CAL-14).
+
+---
+
+## All-day treatment
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Hidden when all-day | Picker disappears once All-day toggled on | |
+| Shown but disabled | Picker greyed with a hint | |
+| (Free text) All-day fires reminders like any event, in days | User override of the locked roadmap criterion | ✓ |
+
+**User's choice:** All-day events DO get reminders, with day-granularity leads.
+**Notes:** Reverses ROADMAP criterion 5 / PITFALLS Pitfall 3 (which locked selector hidden/disabled for all-day). Follow-up: presets **None / 1d / 2d / 1wk**, fire at **9 AM local**. Later in discussion the user added **"Same day"** to the all-day presets ("why not"), giving None / Same day / 1d / 2d / 1wk.
+
+---
+
+## Notification copy
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Humanized relative | "Starts in 2 days" / "in 1 hour" / "in 30 min" | ✓ |
+| Absolute local time | "Starts at 3:00 PM" / "Tomorrow 9:00 AM" | |
+| Keep "Starts in N min" | No change | |
+
+**User's choice:** Humanized relative.
+**Notes:** Replaces hardcoded `Starts in ${minutes} min` (reminderScheduler.ts:157), which is absurd for long leads.
+
+---
+
+## Recurring events
+
+| Option | Description | Selected |
+|--------|-------------|----------|
+| Series-level only | One VALARM on master; per-occurrence fire via scheduler | ✓ |
+| Per-occurrence override | RECURRENCE-ID override per occurrence | |
+
+**User's choice:** Series-level only.
+**Notes:** Per-occurrence override deferred to a possible future phase.
+
+---
+
+## Claude's Discretion
+
+- Picker placement within `EventForm.tsx` (reuse Recurrence `<select>` pattern).
+- Exact humanized-unit thresholds/wording for the notification body.
+
+## Deferred Ideas
+
+- Per-occurrence (RECURRENCE-ID) reminder override — its own phase if wanted.
+- Reminder snooze / notification-preferences UI — already out of scope per REQUIREMENTS.md.
+- Reviewed-not-folded todos: PWA BottomTabBar overlap (Phase 17), Gitea CI regression/Docker publish (Phase 8 / backlog).