---
phase: 1
slug: foundation
status: draft
nyquist_compliant: false
wave_0_complete: false
created: 2026-05-14
---

# Phase 1 — Validation Strategy

> Per-phase validation contract for feedback sampling during execution.

---

## Test Infrastructure

| Property | Value |
|----------|-------|
| **Framework** | go test (stdlib) |
| **Config file** | none — stdlib testing |
| **Quick run command** | `go test ./backend/internal/web/...` |
| **Full suite command** | `go test ./backend/...` |
| **Estimated runtime** | ~5 seconds |

---

## Sampling Rate

- **After every task commit:** Run `go test ./backend/internal/web/...`
- **After every plan wave:** Run `go test ./backend/...`
- **Before `/gsd-verify-work`:** Full suite must be green
- **Max feedback latency:** 10 seconds

---

## Per-Task Verification Map

| Task ID | Plan | Wave | Requirement | Threat Ref | Secure Behavior | Test Type | Automated Command | File Exists | Status |
|---------|------|------|-------------|------------|-----------------|-----------|-------------------|-------------|--------|
| 01-01-01 | 01 | 1 | FOUND-01 | — | N/A | manual | `just dev` boots and live-reloads | ❌ W0 | ⬜ pending |
| 01-02-01 | 02 | 1 | FOUND-02 | — | `/healthz` returns 200 with `{status:"ok",db:"ok"}` only when DB reachable | unit | `go test ./backend/internal/web/ -run TestHealthz` | ❌ W0 | ⬜ pending |
| 01-03-01 | 03 | 1 | FOUND-03 | — | Index page renders with `hx-get` attribute, no console errors | unit | `go test ./backend/internal/web/ -run TestIndex` | ❌ W0 | ⬜ pending |
| 01-03-02 | 03 | 1 | FOUND-03 | — | `/demo/time` returns HTMX fragment | unit | `go test ./backend/internal/web/ -run TestDemoTime` | ❌ W0 | ⬜ pending |
| 01-04-01 | 04 | 1 | FOUND-04 | — | `just migrate up` applies migrations to local Postgres | manual | `just migrate up && just migrate status` | ❌ W0 | ⬜ pending |
| 01-05-01 | 05 | 2 | FOUND-05 | — | Fresh clone → `compose up -d` + `just dev` → page renders within ~5 min following README | manual | follow `backend/README.md` from scratch | ❌ W0 | ⬜ pending |

*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*

---

## Wave 0 Requirements

- [ ] `backend/internal/web/handlers_test.go` — stubs covering `/healthz` both states, RequestID middleware, slog handler switch, index page `hx-get` presence, `/demo/time` fragment
- [ ] Optional: `backend/internal/db/db_test.go` — pgxpool integration test that skips when `DATABASE_URL` is unset
- [ ] No external test framework install needed — stdlib `go test` covers all automated checks

---

## Manual-Only Verifications

| Behavior | Requirement | Why Manual | Test Instructions |
|----------|-------------|------------|-------------------|
| `just dev` starts web server and live-reloads on `.go` + template changes | FOUND-01 | Live-reload is observed behavior — requires running watcher and modifying a file | Run `just dev`, edit a handler and a `.templ` file, confirm rebuild/reload |
| `just migrate up` applies migrations to local Postgres | FOUND-04 | Requires running Postgres + migration tool — easier to verify by inspection than to mock | `just migrate up`, then `just migrate status` shows applied migrations |
| New dev onboarding under ~5 minutes via README | FOUND-05 | End-to-end onboarding flow involves Docker, env setup, and human reading — only verifiable by walking through it | Clone fresh, run `compose up -d` then `just dev`, time it, confirm page loads |
| HTMX page has no browser console errors | FOUND-03 | Browser-only check | Open root in browser DevTools, confirm no errors and `hx-get` round-trips |

---

## 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 < 10s
- [ ] `nyquist_compliant: true` set in frontmatter

**Approval:** pending
