diff --git a/.planning/phases/01-foundation-broker-spike/01-VALIDATION.md b/.planning/phases/01-foundation-broker-spike/01-VALIDATION.md new file mode 100644 index 0000000..ee5dfca --- /dev/null +++ b/.planning/phases/01-foundation-broker-spike/01-VALIDATION.md @@ -0,0 +1,83 @@ +--- +phase: 1 +slug: foundation-broker-spike +status: draft +nyquist_compliant: false +wave_0_complete: false +created: 2026-06-04 +--- + +# Phase 1 — Validation Strategy + +> Per-phase validation contract for feedback sampling during execution. + +--- + +## Test Infrastructure + +| Property | Value | +|----------|-------| +| **Framework** | vitest (Vite-native, shared backend + frontend per CLAUDE.md) | +| **Config file** | none — Wave 0 installs vitest + workspace config | +| **Quick run command** | `pnpm vitest run --changed` | +| **Full suite command** | `pnpm vitest run` | +| **Estimated runtime** | ~30 seconds | + +--- + +## Sampling Rate + +- **After every task commit:** Run `pnpm vitest run --changed` +- **After every plan wave:** Run `pnpm vitest run` +- **Before `/gsd-verify-work`:** Full suite must be green +- **Max feedback latency:** 60 seconds + +--- + +## Per-Task Verification Map + +> Populated by the planner against the final task IDs. Each phase success criterion maps to at least one automated or manual verification below. + +| Success Criterion | Requirement | Verification approach | Test Type | +|-------------------|-------------|-----------------------|-----------| +| SC1 — OIDC login lands on home, no Fastmail creds | AUTH-01 | E2E: unauthenticated request to protected route 302→Authelia; authenticated session reaches home | manual (real Authelia) + integration (middleware mounted) | +| SC2 — Sessions persist across browser restart | AUTH-02 | Integration: signed JWT session cookie issued; refresh-token interval configured; unit test cookie attrs (httpOnly, same-site, maxAge) | integration + manual | +| SC3 — Stable distinct member color | AUTH-03 | Unit: color assignment is deterministic round-robin by join order, persisted on user row keyed by oidc_iss+oidc_sub, unchanged on re-login | unit | +| SC4 — Broker fetches + caches ≥1 real event | CAL-01 | Integration: broker PROPFIND discovers collections, REPORT returns VEVENT, parsed + written to cache table (raw blob + dtstart_utc/date); all-day DATE handling unit-tested | integration + manual (real Fastmail) | +| SC5 — CAL-08 go/no-go documented | CAL-08 | Manual: spike confirms app password reads shared + personal collections; decision recorded in a committed doc | manual (decision artifact) | + +*Status tracked per task by the planner. Status legend: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky* + +--- + +## Wave 0 Requirements + +- [ ] `vitest` + workspace test config installed (no framework exists — greenfield) +- [ ] Shared test fixtures: in-memory/throwaway MariaDB or test schema for Drizzle integration tests +- [ ] Fastmail CalDAV fixtures: captured raw VEVENT samples (timed + all-day) for offline parser unit tests +- [ ] Crypto helper test vectors for AES-256-GCM encrypt/decrypt round-trip + +--- + +## Manual-Only Verifications + +| Behavior | Requirement | Why Manual | Test Instructions | +|----------|-------------|------------|-------------------| +| Authelia OIDC end-to-end login | AUTH-01 | Requires real Authelia + Pangolin topology; no mock substitutes for redirect/cookie behavior | Reach public URL → redirected to Authelia → authenticate → land on home with no Fastmail prompt | +| Session persistence across restart | AUTH-02 | Browser-restart behavior not unit-testable | Log in, fully close browser, revisit URL → no re-login | +| Real Fastmail event fetch + cache | CAL-01 | Requires real app password + live calendar | Run broker against Lucas's account → confirm ≥1 event row cached | +| CAL-08 personal-calendar ACL spike | CAL-08 | Spike produces a human go/no-go judgement | Confirm app password reads shared + personal collections via PROPFIND/REPORT; record GO/NO-GO + fallback | +| Pangolin SSE pass-through smoke test | (D-08, de-risks Phase 4) | Idle-timeout behavior only observable over real public URL | Open long-lived SSE endpoint over Pangolin URL ≥5 min → confirm stream not cut | + +--- + +## Validation Sign-Off + +- [ ] All tasks have an automated verify or a Wave 0 dependency, or are listed under Manual-Only with justification +- [ ] Sampling continuity: no 3 consecutive tasks without automated verify +- [ ] Wave 0 covers all MISSING references +- [ ] No watch-mode flags +- [ ] Feedback latency < 60s +- [ ] `nyquist_compliant: true` set in frontmatter once planner maps task IDs + +**Approval:** pending