---
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