From efae7159a4aad408deb8e8733fea363a8a272be7 Mon Sep 17 00:00:00 2001
From: Lucas Berger <me@lucasberger.ca>
Date: Sun, 14 Jun 2026 21:41:06 -0400
Subject: [PATCH] docs(18): add validation strategy

---
 .../18-VALIDATION.md                          | 83 +++++++++++++++++++
 1 file changed, 83 insertions(+)
 create mode 100644 .planning/phases/18-auto-timezone-detection-and-ability-to-change-timezone/18-VALIDATION.md

diff --git a/.planning/phases/18-auto-timezone-detection-and-ability-to-change-timezone/18-VALIDATION.md b/.planning/phases/18-auto-timezone-detection-and-ability-to-change-timezone/18-VALIDATION.md
new file mode 100644
index 0000000..f4dca6f
--- /dev/null
+++ b/.planning/phases/18-auto-timezone-detection-and-ability-to-change-timezone/18-VALIDATION.md
@@ -0,0 +1,83 @@
+---
+phase: 18
+slug: auto-timezone-detection-and-ability-to-change-timezone
+status: draft
+nyquist_compliant: false
+wave_0_complete: false
+created: 2026-06-14
+---
+
+# Phase 18 — Validation Strategy
+
+> Per-phase validation contract for feedback sampling during execution.
+
+---
+
+## Test Infrastructure
+
+| Property | Value |
+|----------|-------|
+| **Framework** | vitest |
+| **Config file** | apps/api/vitest.config.ts (backend), apps/pwa/vitest.config.ts (frontend) |
+| **Quick run command** | `pnpm --filter @familysync/api test -- --run` |
+| **Full suite command** | `pnpm -r test -- --run` |
+| **Estimated runtime** | ~30 seconds |
+
+---
+
+## Sampling Rate
+
+- **After every task commit:** Run `pnpm --filter @familysync/api test -- --run`
+- **After every plan wave:** Run `pnpm -r test -- --run`
+- **Before `/gsd-verify-work`:** Full suite must be green
+- **Max feedback latency:** 60 seconds
+
+---
+
+## Per-Task Verification Map
+
+| Task ID | Plan | Wave | Requirement | Threat Ref | Secure Behavior | Test Type | Automated Command | File Exists | Status |
+|---------|------|------|-------------|------------|-----------------|-----------|-------------------|-------------|--------|
+| {N}-01-01 | 01 | 1 | D-05/D-06 | — | tz accessor returns stored value, falls back to process.env.TZ ?? Intl when unset | unit | `pnpm --filter @familysync/api test -- --run` | ❌ W0 | ⬜ pending |
+
+*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
+
+> Planner fills this table per task. Key automated coverage targets from RESEARCH.md "Validation Architecture":
+> - stored-tz accessor + D-06 fallback chain (unit)
+> - IANA validation (try/catch on `Intl.DateTimeFormat`, accepts UTC) (unit)
+> - `computeAlertInstantUtc` fed the stored tz vs fallback produces correct 9 AM-local instant (unit)
+> - admin change-tz read/write round-trip (integration)
+> - all-day reminder fires at 9 AM in the stored zone under a non-UTC value (integration/E2E)
+
+---
+
+## Wave 0 Requirements
+
+- [ ] Backend unit-test stubs for the stored-tz accessor + fallback chain
+- [ ] Backend unit-test stubs for IANA validation
+- [ ] vitest already present — no framework install needed
+
+*Existing all-day scheduler tests remain green unmodified (mock DB returns no app_config rows → D-06 fallback path).*
+
+---
+
+## Manual-Only Verifications
+
+| Behavior | Requirement | Why Manual | Test Instructions |
+|----------|-------------|------------|-------------------|
+| Searchable IANA picker UX in /admin Settings | D-04 | Visual/interaction quality | Drive with `playwright-cli`: open /admin Settings, search a zone, save, reload, confirm persisted |
+
+*iOS-Safari standalone behavior is out of scope for this phase.*
+
+---
+
+## Validation Sign-Off
+
+- [ ] All tasks have `<automated>` verify or Wave 0 dependencies
+- [ ] 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
+
+**Approval:** pending