docs(11.1): insert documentation phase with context and validation strategy

.planning/phases/11.1-summercms-documentation-for-humans-and-ai-agents/11.1-VALIDATION.md

@@ -0,0 +1,90 @@
+---
+phase: "11.1"
+slug: "summercms-documentation-for-humans-and-ai-agents"
+# status lifecycle: draft (seeded by plan-phase) → validated (set by validate-phase §6)
+# audit-milestone §5.5 distinguishes NOT-VALIDATED (draft) from PARTIAL (validated + nyquist_compliant: false) (#2117)
+status: draft
+nyquist_compliant: false
+wave_0_complete: false
+created: "2026-09-28"
+---
+
+# Phase 11.1 — Validation Strategy
+
+> Per-phase validation contract for feedback sampling during execution.
+
+---
+
+## Test Infrastructure
+
+| Property | Value |
+|----------|-------|
+| **Framework** | go test (stdlib `testing`) |
+| **Config file** | none. Tests locate `docs/` and `modules/` via relative paths from `internal/docsite` |
+| **Quick run command** | `go test -short ./internal/docsite/... ./cmd/summer/... ./docs/examples/...` |
+| **Full suite command** | `go vet ./... && go test ./...` (Docker required for walkthrough and lagoon DB tests) |
+| **Phase gate** | `scripts/check-phase11.1.sh --all` |
+| **Estimated runtime** | ~60 seconds (quick), several minutes (full with Docker) |
+
+---
+
+## Sampling Rate
+
+- **After every task commit:** Run `go vet ./... && go test -short ./...`
+- **After every plan wave:** Run `go test ./...` plus `scripts/check-phase11.1.sh --docs --forbidden`
+- **Before `/gsd-verify-work`:** `scripts/check-phase11.1.sh --all` must be green, then manual UAT of search and dark mode
+- **Max feedback latency:** 60 seconds
+
+---
+
+## Per-Task Verification Map
+
+Filled in by the planner once PLAN.md files exist. Requirement → test mapping from RESEARCH.md:
+
+| Requirement | Behavior | Test Type | Automated Command | File Exists | Status |
+|-------------|----------|-----------|-------------------|-------------|--------|
+| DOCS-01 / SC1 | Strict frontmatter, section/dir match, unique order, H1 == title, every module in sidebar | unit | `go test ./internal/docsite -run 'TestContentTree\|TestEveryModuleInSidebar'` | ❌ W0 | ⬜ pending |
+| DOCS-02 / SC2 | Build emits html with sidebar, TOC, prev/next, edit link, search, theme toggle; assets embedded; no Node | unit + smoke | `go test ./internal/docsite -run TestBuildSite && go test ./cmd/summer -run TestToolCommandNames` | ❌ W0 | ⬜ pending |
+| DOCS-02 / SC2 | `go.mod` direct requires unchanged | gate | `scripts/check-phase11.1.sh --deps` | ❌ W0 | ⬜ pending |
+| DOCS-03 / SC3 | nav pages == html == md == llms.txt links == llms-full sources, in sidebar order; llms.txt spec shape | unit | `go test ./internal/docsite -run TestAIOutputsInSync` | ❌ W0 | ⬜ pending |
+| DOCS-04 / SC4 | Every go fence has `src=`, bodies equal sources, referenced Examples have Output, missing ref fails | unit | `go test ./internal/docsite -run TestSnippets` | ❌ W0 | ⬜ pending |
+| DOCS-04 / SC4 | Examples compile and run with valid names | toolchain | `go vet ./... && go test ./modules/...` | ❌ W0 | ⬜ pending |
+| DOCS-05 / SC4 | Identifier, link/anchor, CLI-name, forbidden-name checkers fail on planted violations and pass on the real tree | unit | `go test ./internal/docsite -run 'TestIdentifiers\|TestLinks\|TestCommands\|TestForbidden'` | ❌ W0 | ⬜ pending |
+| DOCS-06 / SC5 | "Coming from WinterCMS" page exists and its identifiers pass | unit | covered by `TestContentTree` + `TestIdentifiers` | ❌ W0 | ⬜ pending |
+| DOCS-07 / SC5 | `acme/blog` walkthrough compiles, registers, serves routes, migrates up/down, matches the scaffold layout | unit + integration | `go test ./docs/examples/...` | ❌ W0 | ⬜ pending |
+| DOCS-08 | CLAUDE.md carries the D-13 docs-update rule | gate | `scripts/check-phase11.1.sh --claude` | ❌ W0 | ⬜ pending |
+
+*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
+
+---
+
+## Wave 0 Requirements
+
+- [ ] `internal/docsite/` package with test scaffolding and a `testdata/` planted-violation corpus
+- [ ] `modules/bonfire/example_test.go` — first verified snippet (tracer)
+- [ ] `docs/site.yaml`, `docs/index.md`, `docs/setup/installation.md`
+- [ ] `cmd/summer/docs.go` + `TestToolCommandNames` extension
+- [ ] `scripts/check-phase11.1.sh` with `--self-test`
+- [ ] `/site/` in `.gitignore`
+
+---
+
+## Manual-Only Verifications
+
+| Behavior | Requirement | Why Manual | Test Instructions |
+|----------|-------------|------------|-------------------|
+| Client-side search returns relevant pages | DOCS-02 | No JS test runner without a Node toolchain | `summer docs:serve`, search for a module name and a CLI command, confirm results link correctly |
+| Dark mode toggles and persists | DOCS-02 | Visual | `summer docs:serve`, toggle theme, reload, confirm persistence and contrast per UI-SPEC |
+
+---
+
+## 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