docs(18): add validation strategy

2026-06-14 21:41:06 -04:00
parent 12fb5d2adb
commit efae7159a4
1 changed files with 83 additions and 0 deletions
@@ -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