docs(01): create phase plan (4 plans, MVP walking skeleton)

.planning/STATE.md

@@ -3,12 +3,13 @@ gsd_state_version: 1.0
 milestone: v1.0
 milestone_name: milestone
 status: unknown
-last_updated: "2026-05-14T14:42:38.681Z"
+last_updated: "2026-05-14T15:18:59.172Z"
 progress:
   total_phases: 7
   completed_phases: 0
-  total_plans: 0
+  total_plans: 4
   completed_plans: 0
+  percent: 0
 ---
 
 # STATE

.planning/phases/01-foundation/01-01-PLAN.md

@@ -41,6 +41,16 @@ must_haves:
     - "Running `just --list` shows recipes for at least: bootstrap, dev, db-up, db-down, migrate, generate, styles-watch, test, lint, build"
     - "Tailwind input CSS declares @source globs that include backend/templates/**/*.templ and backend/internal/web/**/*.{templ,go} so JIT does not purge classes used only in templ files"
     - ".env.example documents DATABASE_URL, PORT, ENV and .env is gitignored"
+    - "D-01: Two-binary cmd/web + cmd/worker layout with shared internal/ packages"
+    - "D-02: Phase 1 creates directory skeleton for all internal/<domain> packages with placeholder doc.go files"
+    - "D-04: goose (pressly/goose) chosen as migration tool with .sql files using +goose Up/Down annotations"
+    - "D-05: just migrate up/down/status recipes wired via goose CLI for local development"
+    - "D-06: Phase 1 includes one trivial bootstrap migration 0001_init.sql exercising the migration pipeline end-to-end"
+    - "D-12: Standalone Tailwind CLI binary downloaded by just bootstrap into ./bin/tailwindcss — no Node or pnpm toolchain"
+    - "D-13: air (cosmtrek/air) used for Go live-reload via just dev watching .go and .templ files"
+    - "D-14: Tailwind watch mode runs as separate just styles-watch process — not via air pre_cmd"
+    - "D-15: Env-driven configuration via .env files with required keys DATABASE_URL PORT ENV documented in .env.example"
+    - "D-16: Postgres driver pgx/v5 with pgxpool for connection pool; sqlc configured to emit pgx-compatible code"
   artifacts:
     - path: backend/go.mod
       provides: Go module declaration with required deps (chi, templ, pgx, goose, uuid)

.planning/phases/01-foundation/01-02-PLAN.md

@@ -37,6 +37,9 @@ must_haves:
     - "The `internal/web/ui` design-system package compiles standalone and its `ui_test.go` smoke tests PASS — each shipped variant of Button, Card, Badge renders without panicking and emits the expected root CSS class"
     - "The UI component package mirrors the enum surface of `go-backend/internal/web/ui/` for Size, ButtonVariant, ButtonTone, BadgeVariant — future phases extend these enums' CSS without redefining them"
     - "Test files declare the exact handler function signatures and templ component names that Plan 03 will implement, so Plan 03 is a fill-in not an exploration"
+    - "D-07: templ (a-h/templ) used as type-safe HTML templating; UI library components are templ functions returning templ.Component"
+    - "D-09: templ generate runs as part of the dev loop via just generate alongside sqlc generate; *_templ.go artifacts are gitignored"
+    - "D-20: /healthz response shape locked — 200 with status:ok db:ok when pinger succeeds; 503 with status:degraded db:down otherwise — asserted by TestHealthz_OK and TestHealthz_Down"
   artifacts:
     - path: backend/internal/web/ui/variants.go
       provides: Size, ButtonVariant, ButtonTone, BadgeVariant enums + class-builder functions + normalizers

.planning/phases/01-foundation/01-03-PLAN.md

@@ -38,6 +38,11 @@ must_haves:
     - "The root page is rendered via `internal/web/ui` components — handlers do NOT inline Tailwind classes — and contains the canonical `hx-get` button declared in UI-SPEC"
     - "Sending SIGINT to the web binary triggers graceful shutdown: in-flight requests are allowed to finish (up to 10s), then the pgxpool is closed, then the process exits 0"
     - "`./tmp/worker` connects to Postgres, logs `worker ready` via slog, blocks on signal, and exits 0 on SIGINT (D-03)"
+    - "D-08: chi router middleware stack ordered RequestID then RealIP then Logger then Recoverer per the locked CONTEXT decision"
+    - "D-10: HTMX runtime vendored at backend/static/htmx.min.js — never loaded from a CDN; base layout references the local path"
+    - "D-17: Structured logging via log/slog standard library — JSON handler when ENV=production and text handler in development"
+    - "D-18: RequestID middleware attaches a UUIDv4 per request into context.Context and onto the slog logger as request_id attribute"
+    - "D-19: Graceful shutdown traps SIGINT and SIGTERM; http.Server.Shutdown runs with 10-second timeout then pgxpool Close runs before process exits"
   artifacts:
     - path: backend/internal/db/pool.go
       provides: NewPool(ctx, dsn) (*pgxpool.Pool, error) per RESEARCH Pattern 1

.planning/phases/01-foundation/01-04-PLAN.md

@@ -20,6 +20,8 @@ must_haves:
     - "The README spells out the docker compose fallback for contributors who don't use podman (D-11)"
     - "The README documents the two-terminal dev workflow (`just dev` + `just styles-watch`) per RESEARCH Open Question 2"
     - "The README documents the bootstrap order: `just bootstrap` → `just db-up` → `just migrate up` → `just dev` (in 1st terminal) + `just styles-watch` (in 2nd terminal) → open localhost:8080"
+    - "D-11: podman compose chosen for local Postgres; README documents docker compose as the fallback for contributors who do not use podman"
+    - "D-14: README documents the two-terminal dev workflow — just dev in terminal 1 and just styles-watch in terminal 2 — per the locked Tailwind watch decision"
   artifacts:
     - path: backend/README.md
       provides: Five-minute onboarding doc covering prereqs, bootstrap, dev workflow, common commands, troubleshooting pointers

.planning/phases/01-foundation/01-RESEARCH.md

@@ -655,22 +655,22 @@ stop_on_error = true
 
 **Interpretation:** All four assumptions are LOW risk; planner can proceed without user confirmation but should re-verify HTMX/Tailwind versions at the moment of bootstrap.
 
-## Open Questions
+## Open Questions (RESOLVED)
 
 1. **Goose: pure CLI in Phase 1, or library-call from a `backend migrate` subcommand now?**
    - What we know: D-04 + D-05 say CLI for Phase 1; D-71 (Claude's discretion) says planner may set up for Phase 7's likely library approach.
    - What's unclear: Whether to add the `cmd/migrate/main.go` (or `cmd/web` subcommand) skeleton now or wait.
-   - Recommendation: Pure CLI in Phase 1. Adding the library wiring now blurs the phase boundary and creates two migration paths (CLI + lib) before one is hardened. Phase 7 can introduce `cmd/web migrate` cleanly.
+   - RESOLVED: Pure CLI in Phase 1. Adding the library wiring now blurs the phase boundary and creates two migration paths (CLI + lib) before one is hardened. Phase 7 can introduce `cmd/web migrate` cleanly.
 
 2. **Tailwind watch: separate `just styles` process, or air `pre_cmd`?**
    - What we know: D-14 leaves this to the planner.
    - What's unclear: Whether developers run `just dev` (one terminal) or `just dev` + `just styles` (two terminals).
-   - Recommendation: Two terminals — keep concerns separated. Tailwind watch is independent of Go rebuild; piping through air's `pre_cmd` would trigger CSS rebuild on every `.go` save, which is wasteful. Document the two-terminal workflow in README.
+   - RESOLVED: Two terminals — keep concerns separated. Tailwind watch is independent of Go rebuild; piping through air's `pre_cmd` would trigger CSS rebuild on every `.go` save, which is wasteful. Document the two-terminal workflow in README.
 
 3. **Phase 1 `/healthz` smoke test: ship it or defer?**
    - What we know: Phase 2 establishes the testing strategy.
    - What's unclear: Whether a single `handlers_test.go` covering `/healthz` (with a stub `Pinger` interface) earns its keep now.
-   - Recommendation: Ship it. It exercises the chi+slog wiring, provides a regression net for Phase 2 to extend, and the `Pinger` interface stub costs <10 lines. See Validation Architecture below.
+   - RESOLVED: Ship it. It exercises the chi+slog wiring, provides a regression net for Phase 2 to extend, and the `Pinger` interface stub costs <10 lines. See Validation Architecture below.
 
 ## Environment Availability