docs: capture D-14/D-15 (Gate 2 deferral + local-Newt test rig) + deployment runbook
- docs/deployment.md: operator runbook — Mode A (local Newt test rig) vs Mode B (Unraid prod), Authelia client block, env reference, Pangolin SSE idle-timeout note, Gate 2 checklist. - ROADMAP: Phase 1 verification-status note (Gate 1 done, Gate 2 deferred); Phase 3 gains live AUTH + iOS standalone-PWA criterion; Phase 4 gains hard SSE-smoke entry gate (#1034). - PROJECT.md: D-14 (Gate 2 deferral split) + D-15 (local Newt rig); CAL-08 marked validated. - STATE: decisions/blockers updated to reflect deferral and dev-auth-bypass approach.
This commit is contained in:
Lucas Berger
@@ -75,7 +75,9 @@ The household can see and co-edit one color-coded family calendar (shared + each
|
||||
| React PWA only, no React Native / App Store | App-like UX with one codebase for all surfaces; lowest onboarding friction (one URL) | — Pending |
|
||||
| Authelia OIDC for all members | True SSO consistent with existing infra; no separate calendar-credential problem | — Pending |
|
||||
| Web Push notifications in v1 (not deferred) | Family alerts judged essential day one; build push into the foundation | — Pending |
|
||||
| Personal-calendar overlay in v1 (not shared-only) | Unified view of everyone's schedules is the Skylight magic worth shipping early | — Pending |
|
||||
| Personal-calendar overlay in v1 (not shared-only) | Unified view of everyone's schedules is the Skylight magic worth shipping early | — Validated (CAL-08 GO, Phase 1): per-member app password reaches all of an account's calendars; no cross-account ACL needed |
|
||||
| **D-14:** Defer Phase 1 Gate 2 (live Authelia/Pangolin verification). SSE-over-Pangolin smoke = hard gate before Phase 4; live AUTH smoke incl. iOS standalone-PWA folded into Phase 3; full 2-member prod login verified there. Phases 2–3 develop behind a documented dev-auth bypass. | Gate 2 needs operator infra (Authelia config + tunnel) + docs that didn't exist; deferring unblocks Phase 2/3 code without rework risk, since the broker data path (CAL-01/CAL-08) is already proven live. SSE must still be verified before Phase 4 to avoid building live-sync on an unverified transport (#1034). | Tracked: `01-HUMAN-UAT.md`, `docs/deployment.md` |
|
||||
| **D-15:** Validate the real external topology via a **local Newt connector + test subdomain** through existing Pangolin (Mode A), not an Unraid deploy. Unraid (Mode B) reserved for go-live. | Authelia OIDC + SSE pass-through behaviour live in Authelia + Pangolin/Newt, not in where the origin runs — so a local Newt rig faithfully tests both, decoupling "does the topology work" from "is it in production." Newt dials outbound (no open ports). Only shared touch is an additive, reversible Authelia client. | — Pending (Gate 2) |
|
||||
|
||||
## Evolution
|
||||
|
||||
|
||||
@@ -35,6 +35,8 @@ Decimal phases appear between their surrounding integers in numeric order.
|
||||
4. The broker successfully fetches and caches at least one event from the shared Fastmail calendar via CalDAV PROPFIND/REPORT
|
||||
5. The personal-calendar ACL spike produces a documented go/no-go decision: either the broker token sees the wife's personal calendar after Fastmail share+accept, or the fallback strategy (shared-family-only or per-member app password) is chosen and recorded
|
||||
|
||||
**Verification status (D-14, 2026-06-04):** Code + **Gate 1** complete. Gate 1 = stack up (`/health` live), CAL-01 proven live (503 real events cached via REPORT), CAL-08 = **GO** (per-member app-password model, see `CAL-08-DECISION.md`). **Gate 2 deferred** — criteria 1/2/3 (live Authelia OIDC login over Pangolin, session persistence, distinct colors in a real browser) and the SSE-over-Pangolin smoke test require the operator's Authelia + Pangolin/Newt infra; tracked in `01-HUMAN-UAT.md` and `docs/deployment.md`. The live AUTH smoke (incl. iOS) is folded into **Phase 3**; the SSE smoke is a hard gate before **Phase 4**. Phases 2–3 develop behind a documented dev-auth bypass.
|
||||
|
||||
**Plans**: 4 plans
|
||||
Plans:
|
||||
|
||||
@@ -72,6 +74,7 @@ Plans:
|
||||
3. A member can delete an event and it disappears from all views on the next sync
|
||||
4. On Android, the app shows a browser install prompt and installs to the home screen; on iOS, the app shows a guided "Add to Home Screen" walkthrough with annotated screenshots that a non-technical user can follow independently
|
||||
5. The installed PWA opens full-screen without browser chrome on both iOS and Android
|
||||
6. **(Carried from Phase 1 Gate 2, D-14)** Live Authelia OIDC login works over the public Pangolin URL — including the **iOS standalone-PWA** flow: the wife can install to Home Screen and complete login without the redirect breaking out of standalone mode; sessions persist (AUTH-01/02) and members get distinct stable colors (AUTH-03). Verify per `docs/deployment.md` Gate 2 checklist; this is the first real external deploy (local Newt test rig is sufficient — Unraid prod is optional until go-live).
|
||||
|
||||
**Plans**: TBD
|
||||
**UI hint**: yes
|
||||
@@ -81,6 +84,7 @@ Plans:
|
||||
**Goal**: Both members can create and manage shared named lists with real-time co-edit sync — edits by one member appear for the other without any manual refresh
|
||||
**Mode:** mvp
|
||||
**Depends on**: Phase 1
|
||||
**⚠️ Entry gate (D-14):** The **SSE-over-Pangolin smoke test** (deferred from Phase 1 Gate 2, issue #1034) MUST pass before building live sync — hold `/api/sse/heartbeat` open 5+ min through the tunnel without it being cut (see `docs/deployment.md`). If it FAILS: fix Pangolin idle-timeout/buffering, or plan a reconnect/polling fallback into this phase before proceeding. Do not build the live-sync layer on an unverified transport.
|
||||
**Requirements**: LIST-01, LIST-02, LIST-03, LIST-04
|
||||
**Success Criteria** (what must be TRUE):
|
||||
|
||||
|
||||
+11
-8
@@ -60,10 +60,12 @@ Progress: [░░░░░░░░░░] 0%
|
||||
Decisions are logged in PROJECT.md Key Decisions table.
|
||||
Recent decisions affecting current work:
|
||||
|
||||
- Phase 1 gate: Personal-calendar CalDAV ACL must be spiked before calendar UI is built. Fallback is shared-family-only if spike fails.
|
||||
- CAL-08 RESOLVED → GO (Phase 1): per-member Fastmail app password reaches all of that account's calendars; no cross-account ACL needed. Unified view stands; no shared-only fallback. See CAL-08-DECISION.md.
|
||||
- D-14 (2026-06-04): Phase 1 Gate 2 (live Authelia/Pangolin) deferred. SSE-over-Pangolin smoke = hard gate before Phase 4; live AUTH smoke incl. iOS standalone-PWA folded into Phase 3. Phases 2–3 build behind a dev-auth bypass. Tracked in 01-HUMAN-UAT.md + docs/deployment.md.
|
||||
- D-15 (2026-06-04): Validate real topology via local Newt connector + test subdomain through Pangolin (Mode A), not an Unraid deploy; Unraid reserved for go-live.
|
||||
- CalDAV locked: Fastmail does not expose calendars over JMAP. CalDAV via tsdav is the only protocol. No reconsideration.
|
||||
- Identity: Use oidc_iss + oidc_sub as stable composite key. Never email.
|
||||
- Real-time transport: Prefer SSE over WebSocket (proxy-resilient through Pangolin). Verify Pangolin SSE pass-through in Phase 1 infra spike.
|
||||
- Real-time transport: Prefer SSE over WebSocket (proxy-resilient through Pangolin). SSE pass-through STILL UNVERIFIED — gate before Phase 4 (D-14).
|
||||
- Recurring events: Create + display only in v1 (CALDAV:expand on server side). Single-occurrence edit deferred to v1.x.
|
||||
|
||||
### Pending Todos
|
||||
@@ -72,9 +74,10 @@ None yet.
|
||||
|
||||
### Blockers/Concerns
|
||||
|
||||
- Phase 1: Personal-calendar CalDAV ACL behavior on Fastmail is LOW confidence (must spike). Failure degrades unified view to shared-family-only for v1.
|
||||
- Phase 1: Pangolin SSE/WebSocket pass-through is an open infra question (known issue #1034). Must smoke-test before Phase 4 real-time sync is built.
|
||||
- Phase 3: iOS install guide is load-bearing for the wife — she will never receive push notifications if she does not install the PWA.
|
||||
- ~~Phase 1: Personal-calendar CalDAV ACL~~ RESOLVED → CAL-08 GO (per-member app password; no cross-account ACL).
|
||||
- Phase 4 ENTRY GATE: Pangolin SSE pass-through (issue #1034) still unverified — deferred from Phase 1 Gate 2 (D-14). Must pass the 5-min SSE smoke (docs/deployment.md) before building live sync.
|
||||
- Phase 3: iOS standalone-PWA + Authelia login is load-bearing for the wife and is the first real external auth test (carried Gate 2 item, D-14). Also: iOS install guide is load-bearing — she gets no push notifications if she does not install the PWA.
|
||||
- Phase 2/3 dev: build behind a documented dev-auth bypass until Gate 2 deploy (D-14).
|
||||
- Phase 5: iOS push subscriptions silently revoked after 3 silent pushes. Subscription health-check and event.waitUntil() are mandatory from day one.
|
||||
|
||||
## Deferred Items
|
||||
@@ -89,6 +92,6 @@ None yet.
|
||||
|
||||
## Session Continuity
|
||||
|
||||
Last session: 2026-06-04T11:55:07.995Z
|
||||
Stopped at: Phase 1 context gathered
|
||||
Resume file: .planning/phases/01-foundation-broker-spike/01-CONTEXT.md
|
||||
Last session: 2026-06-04
|
||||
Stopped at: Phase 1 code + Gate 1 complete (CAL-01/CAL-08 proven live). Gate 2 (live Authelia/Pangolin + SSE) deferred per D-14, tracked in 01-HUMAN-UAT.md + docs/deployment.md. Decisions D-14/D-15 logged. Ready to plan Phase 2.
|
||||
Resume file: .planning/phases/01-foundation-broker-spike/01-HUMAN-UAT.md
|
||||
|
||||
Reference in New Issue
Block a user