arah2/.planning/phases/03-mini-app-shell-geolocation/03-VALIDATION.md

phase, slug, status, nyquist_compliant, wave_0_complete, created

phase	slug	status	nyquist_compliant	wave_0_complete	created
3	mini-app-shell-geolocation	draft	false	false	2026-10-22

Phase 3 — Validation Strategy

Per-phase validation contract for feedback sampling during execution.

---

Test Infrastructure

Property	Value
Framework	Hand-rolled zero-dependency runner — web/test/runner.mjs + harness.mjs, mirroring bot/test/ and theme/scripts/audit.test.mjs (repo precedent, D-11's "hand-rolled test runner pattern prevails")
Config file	none (no vitest/jest config — by design)
Quick run command	npm test -w web
Full suite command	npm test -w web && npm test -w bot && npm run typecheck -w web && npm run build -w web
Browser/visual checks	npm run capture -w web — Playwright, extends the theme/scripts/screenshot.mjs pattern (static server + chromium + MIN_BYTES blank-bar check already established there)
Estimated runtime	~30 seconds

⚠️ ESM caveat: maplibre-gl@6.15.0 exports only an import condition. The runner uses dynamic import() on .mjs files with "type": "module", which resolves it correctly. Unit tests test the chain logic against injected fakes, never against a real MapLibre instance.

---

Sampling Rate

• After every task commit: Run npm test -w web (plus npm test -w bot for bot-side tasks)
• After every plan wave: Run npm test -w web && npm test -w bot && npm run typecheck -w web && npm run build -w web
• Before /gsd-verify-work: Full suite must be green
• Max feedback latency: ~30 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	(scaffold)	—	N/A	unit	npm test -w web	❌ W0	⬜ pending
(W0)	01	1	GEO-01	—	chain vs fakes	unit	npm test -w web	❌ W0	⬜ pending
(W0)	01	1	GEO-03	T-3-x	no storage API in web/src	unit grep gate	npm test -w web	❌ W0	⬜ pending
(W0)	01	1	PX-02	—	theme slot switch	unit	npm test -w web	❌ W0	⬜ pending
(W0)	01	1	GEO-02	T-3-03	TTL'd location pin KV	unit (bot)	npm test -w bot	❌ W0	⬜ pending
(W0)	01	1	copy gate	—	strings.ts = UI-SPEC table	unit	npm test -w web	❌ W0	⬜ pending
(plans)	02-0N	2	GEO-01	—	source fallback chain	unit	npm test -w web	❌ W0	⬜ pending
(plans)	02-0N	2	GEO-02	—	pin poll bounded	unit	npm test -w web	❌ W0	⬜ pending
(plans)	03-0N	3	D-14	T-3-06	no CDN refs in dist	build gate	npm run build -w web	❌ W0	⬜ pending
(plans)	03-0N	3	GEO-03 / D-09 / D-10	—	runtime probes	integration (Playwright)	npm run capture -w web	❌ W0	⬜ pending

Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky (task IDs will be filled by the plans' own <automated> fields; the map above is the Wave-0 skeleton.)

---

Wave 0 Requirements

• web/test/runner.mjs — hand-rolled runner (copy the bot/test/runner.mjs shape)
• web/test/harness.mjs — test registry
• web/src/mock/telegram-mock.ts — D-11 fake WebApp; the keystone that makes every location test possible without a device
• web/test/location-chain.test.mjs — covers GEO-01, GEO-02 (client half)
• web/test/no-storage.test.mjs — GEO-03 grep gate
• web/test/theme.test.mjs — PX-02 slot-switch gate
• web/test/copy-gate.test.mjs — UI-SPEC copy table gate
• bot/test/location-pin.test.mjs — GEO-02 bot half + TTL grep assertion
• web/scripts/capture.mjs — Playwright harness captures (extend theme/scripts/screenshot.mjs)
• GET /api/location Worker route + KV module — the missing link between the bot's received pin and the open Mini App

None of these exist yet — web/ does not exist. Every test above is Wave 0.

---

Manual-Only Verifications

Behavior	Requirement	Why Manual	Test Instructions
Live position on Rams basemap on real Android + iOS	GEO-01	WebView location bugs are device/client-specific (Bot API 10.2, WKWebView, LocationManager)	Device-matrix exit pass: boot → session → position on each device
Chat "send location" keyboard fallback on Desktop Telegram	GEO-02	Desktop Telegram has no geolocation at all (issue #77); only real clients show the path	Open Mini App on Desktop Telegram; trigger fallback via chat location
Android stale-fix workaround effectiveness (A1)	GEO-01	Community-sourced, unverified on our devices	On Android: issue ONE stale Telegram fix → attempt in-app refresh (navigator nudge) → verify fix freshness updates
Theme flip live (light ↔ dark) while map stays Rams-constant	PX-02	Telegram theme switching only happens inside the real client	Switch Telegram theme mid-session; verify shell re-themes, map unchanged

---

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 < 30s
• nyquist_compliant: true set in frontmatter

Approval: pending

---

Source: .planning/phases/03-mini-app-shell-geolocation/03-RESEARCH.md § Validation Architecture (2026-10-22)