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

phase, slug, status, nyquist_compliant, wave_0_complete, created

phase	slug	status	nyquist_compliant	wave_0_complete	created
11.1	summercms-documentation-for-humans-and-ai-agents	draft	false	false	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