From 9419d5d5e7600218846f3a24729c5a9645b8cbe3 Mon Sep 17 00:00:00 2001 From: Jakub Zych Date: Thu, 1 Oct 2026 00:15:35 +0200 Subject: [PATCH] docs(11.1-06): validate the phase 11.1 verification map - every per-task row of plans 01 to 06 ran green on 2026-10-01 - status validated, nyquist_compliant and wave_0_complete true - search and dark mode stay as manual UAT rows for /gsd-verify-work --- .../11.1-VALIDATION.md | 77 ++++++++++--------- 1 file changed, 39 insertions(+), 38 deletions(-) diff --git a/.planning/phases/11.1-summercms-documentation-for-humans-and-ai-agents/11.1-VALIDATION.md b/.planning/phases/11.1-summercms-documentation-for-humans-and-ai-agents/11.1-VALIDATION.md index 7ae2ee3..1f1b691 100644 --- a/.planning/phases/11.1-summercms-documentation-for-humans-and-ai-agents/11.1-VALIDATION.md +++ b/.planning/phases/11.1-summercms-documentation-for-humans-and-ai-agents/11.1-VALIDATION.md @@ -3,10 +3,11 @@ 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 +status: validated +nyquist_compliant: true +wave_0_complete: true created: "2026-09-28" +validated: "2026-10-01" --- # Phase 11.1 — Validation Strategy @@ -39,41 +40,41 @@ created: "2026-09-28" ## Per-Task Verification Map -Filled in by the planner from the six PLAN.md files. Real-tree checks live in `cmd/summer` (package main owns `toolCommands()`, which the command checker needs); fixture and unit tests live in `internal/docsite`. Plan 11.1-06 Task 3 updates the Status column and the sign-off. +Filled in by the planner from the six PLAN.md files. Real-tree checks live in `cmd/summer` (package main owns `toolCommands()`, which the command checker needs); fixture and unit tests live in `internal/docsite`. Plan 11.1-06 Task 3 ran every command below on 2026-10-01 and recorded the result; `scripts/check-phase11.1.sh --named` re-runs every named test by exact name and refuses a failure, a skip, a missing or renamed test and "no tests to run". | Task ID | Plan | Requirement | Behavior | Test Type | Automated Command | File Exists | Status | |---------|------|-------------|----------|-----------|-------------------|-------------|--------| -| 11.1-01-T1 | 01 | DOCS-01, DOCS-02, DOCS-03 | docs:build writes html, .md, llms.txt, llms-full.txt, search index; strict frontmatter; output guard | smoke (real tree) | `go test ./internal/docsite ./cmd/summer -run '^(TestDocsTree\|TestDocsBuildRealTree\|TestToolCommandNames)$' -count=1 -v` | ❌ W0 | ⬜ pending | -| 11.1-01-T2 | 01 | DOCS-01, DOCS-03 | Every module is an API page in the sidebar; shared slug IDs; AI outputs match the page tree | unit + smoke | `go test ./internal/docsite ./cmd/summer -run '^(TestSlugIDs\|TestReadmeIngestion\|TestEveryModuleInSidebar\|TestDocsAIOutputsInSync\|TestDocsTree)$' -count=1 -v` | ❌ W0 | ⬜ pending | -| 11.1-01-T3 | 01 | DOCS-04 | src= extraction, confinement, drift, docs:sync; ExampleCall runs | unit + toolchain | `go vet ./... && go test ./internal/docsite ./cmd/summer ./modules/bonfire -count=1` | ❌ W0 | ⬜ pending | -| 11.1-02-T1 | 02 | DOCS-05 | Identifier checker over docs, module READMEs and root README; gate self-test | unit + gate | `go test ./internal/docsite ./cmd/summer -run '^(TestIdentifierChecker\|TestDocsTree)$' -count=1 -v && scripts/check-phase11.1.sh --self-test` | ❌ W0 | ⬜ pending | -| 11.1-02-T2 | 02 | DOCS-05, DOCS-08 | Links/anchors, command names (collected sets), forbidden names, go-fence policy; CLAUDE.md rule | unit + gate | `go test ./internal/docsite ./cmd/summer -count=1 && scripts/check-phase11.1.sh --claude` | ❌ W0 | ⬜ pending | -| 11.1-02-T3 | 02 | DOCS-02 | UI-SPEC theme markers, chroma highlighting, search assets, docs:serve loopback and 404; go.mod adds only chroma/v2 and regexp2/v2 | unit + gate | `go test ./internal/docsite -run '^(TestBuildSiteMarkers\|TestServeHandler\|TestServeRefusesNonLoopback)$' -count=1 -v && scripts/check-phase11.1.sh --deps` | ❌ W0 | ⬜ pending | -| 11.1-03-T1 | 03 | DOCS-06 | Coming from WinterCMS page with checked identifiers and ExamplePlugin | toolchain + smoke | `go test ./modules/party -run '^ExamplePlugin$' -count=1 -v && go test ./cmd/summer -run '^(TestDocsTree\|TestDocsRequiredPages)$' -count=1` | ❌ W0 | ⬜ pending | -| 11.1-03-T2 | 03 | DOCS-01, DOCS-04 | Architecture and Plugins pages with running Examples | toolchain + smoke | `go test ./modules/backpack ./modules/pact ./modules/festival ./modules/towel -run '^Example' -count=1 && go test ./cmd/summer -run '^(TestDocsTree\|TestDocsRequiredPages)$' -count=1` | ❌ W0 | ⬜ pending | -| 11.1-03-T3 | 03 | DOCS-01, DOCS-04 | Setup and Console pages; every command name verified | smoke + gate | `go test ./cmd/summer -run '^(TestDocsTree\|TestDocsRequiredPages)$' -count=1 && scripts/check-phase11.1.sh --docs` | ❌ W0 | ⬜ pending | -| 11.1-04-T1 | 04 | DOCS-04 | Jobs page with a runnable Example and a database-backed region run by TestDocsDispatch | integration (Docker) | `go test ./modules/conga -run '^(Example.*\|TestDocsDispatch)$' -count=1 -v` | ❌ W0 | ⬜ pending | -| 11.1-04-T2 | 04 | DOCS-01, DOCS-04 | Database and core Services pages with running examples | toolchain + integration | `go test ./modules/lagoon/... ./modules/compass ./modules/surf ./modules/wire ./modules/bouncer ./modules/wristband ./modules/postcard ./modules/phrasebook -run '^(Example\|TestDocs)' -count=1` | ❌ W0 | ⬜ pending | -| 11.1-04-T3 | 04 | DOCS-01, DOCS-06 | Backend and remaining Services pages, Frontend and AJAX page, section order, concept-map links | smoke + gate | `go test ./cmd/summer -run '^(TestDocsTree\|TestDocsRequiredPages)$' -count=1 && scripts/check-phase11.1.sh --forbidden` | ❌ W0 | ⬜ pending | -| 11.1-05-T1 | 05 | DOCS-07 | Blog plugin activates, route registered; walkthrough page from src= | unit + smoke | `go test -short ./docs/examples/... -count=1 -v` | ❌ W0 | ⬜ pending | -| 11.1-05-T2 | 05 | DOCS-07 | Admin controller, command, second migration proven against Postgres | integration (Docker) | `go test ./docs/examples/... -count=1 -v` | ❌ W0 | ⬜ pending | -| 11.1-05-T3 | 05 | DOCS-07 | Walkthrough file set equals scaffolder output | unit | `go test -short ./docs/examples/blog -run '^TestScaffoldLayout$' -count=1 -v` | ❌ W0 | ⬜ pending | -| 11.1-06-T1 | 06 | DOCS-05 | Every rule has a planted fixture that fails for its own rule | unit | `go test ./internal/docsite -run '^(TestPlantedViolations\|TestCleanFixture)$' -count=1 -v` | ❌ W0 | ⬜ pending | -| 11.1-06-T2 | 06 | DOCS-01..05 | internal/docsite statement coverage at least 85% | unit | `go test ./internal/docsite -count=1 -coverprofile=cover.out && go tool cover -func=cover.out` | ❌ W0 | ⬜ pending | -| 11.1-06-T3 | 06 | DOCS-01..08 | SC1..SC5 acceptance subtests; final gate | acceptance + gate | `go test ./cmd/summer -run '^TestPhase11_1Acceptance$' -count=1 -v && scripts/check-phase11.1.sh --all` | ❌ W0 | ⬜ pending | +| 11.1-01-T1 | 01 | DOCS-01, DOCS-02, DOCS-03 | docs:build writes html, .md, llms.txt, llms-full.txt, search index; strict frontmatter; output guard | smoke (real tree) | `go test ./internal/docsite ./cmd/summer -run '^(TestDocsTree\|TestDocsBuildRealTree\|TestToolCommandNames)$' -count=1 -v` | ✅ | ✅ green | +| 11.1-01-T2 | 01 | DOCS-01, DOCS-03 | Every module is an API page in the sidebar; shared slug IDs; AI outputs match the page tree | unit + smoke | `go test ./internal/docsite ./cmd/summer -run '^(TestSlugIDs\|TestReadmeIngestion\|TestEveryModuleInSidebar\|TestDocsAIOutputsInSync\|TestDocsTree)$' -count=1 -v` | ✅ | ✅ green | +| 11.1-01-T3 | 01 | DOCS-04 | src= extraction, confinement, drift, docs:sync; ExampleCall runs | unit + toolchain | `go vet ./... && go test ./internal/docsite ./cmd/summer ./modules/bonfire -count=1` | ✅ | ✅ green | +| 11.1-02-T1 | 02 | DOCS-05 | Identifier checker over docs, module READMEs and root README; gate self-test | unit + gate | `go test ./internal/docsite ./cmd/summer -run '^(TestIdentifierChecker\|TestDocsTree)$' -count=1 -v && scripts/check-phase11.1.sh --self-test` | ✅ | ✅ green | +| 11.1-02-T2 | 02 | DOCS-05, DOCS-08 | Links/anchors, command names (collected sets), forbidden names, go-fence policy; CLAUDE.md rule | unit + gate | `go test ./internal/docsite ./cmd/summer -count=1 && scripts/check-phase11.1.sh --claude` | ✅ | ✅ green | +| 11.1-02-T3 | 02 | DOCS-02 | UI-SPEC theme markers, chroma highlighting, search assets, docs:serve loopback and 404; go.mod adds only chroma/v2 and regexp2/v2 | unit + gate | `go test ./internal/docsite -run '^(TestBuildSiteMarkers\|TestServeHandler\|TestServeRefusesNonLoopback)$' -count=1 -v && scripts/check-phase11.1.sh --deps` | ✅ | ✅ green | +| 11.1-03-T1 | 03 | DOCS-06 | Coming from WinterCMS page with checked identifiers and ExamplePlugin | toolchain + smoke | `go test ./modules/party -run '^ExamplePlugin$' -count=1 -v && go test ./cmd/summer -run '^(TestDocsTree\|TestDocsRequiredPages)$' -count=1` | ✅ | ✅ green | +| 11.1-03-T2 | 03 | DOCS-01, DOCS-04 | Architecture and Plugins pages with running Examples | toolchain + smoke | `go test ./modules/backpack ./modules/pact ./modules/festival ./modules/towel -run '^Example' -count=1 && go test ./cmd/summer -run '^(TestDocsTree\|TestDocsRequiredPages)$' -count=1` | ✅ | ✅ green | +| 11.1-03-T3 | 03 | DOCS-01, DOCS-04 | Setup and Console pages; every command name verified | smoke + gate | `go test ./cmd/summer -run '^(TestDocsTree\|TestDocsRequiredPages)$' -count=1 && scripts/check-phase11.1.sh --docs` | ✅ | ✅ green | +| 11.1-04-T1 | 04 | DOCS-04 | Jobs page with a runnable Example and a database-backed region run by TestDocsDispatch | integration (Docker) | `go test ./modules/conga -run '^(Example.*\|TestDocsDispatch)$' -count=1 -v` | ✅ | ✅ green | +| 11.1-04-T2 | 04 | DOCS-01, DOCS-04 | Database and core Services pages with running examples | toolchain + integration | `go test ./modules/lagoon/... ./modules/compass ./modules/surf ./modules/wire ./modules/bouncer ./modules/wristband ./modules/postcard ./modules/phrasebook -run '^(Example\|TestDocs)' -count=1` | ✅ | ✅ green | +| 11.1-04-T3 | 04 | DOCS-01, DOCS-06 | Backend and remaining Services pages, Frontend and AJAX page, section order, concept-map links | smoke + gate | `go test ./cmd/summer -run '^(TestDocsTree\|TestDocsRequiredPages)$' -count=1 && scripts/check-phase11.1.sh --forbidden` | ✅ | ✅ green | +| 11.1-05-T1 | 05 | DOCS-07 | Blog plugin activates, route registered; walkthrough page from src= | unit + smoke | `go test -short ./docs/examples/... -count=1 -v` | ✅ | ✅ green | +| 11.1-05-T2 | 05 | DOCS-07 | Admin controller, command, second migration proven against Postgres | integration (Docker) | `go test ./docs/examples/... -count=1 -v` | ✅ | ✅ green | +| 11.1-05-T3 | 05 | DOCS-07 | Walkthrough file set equals scaffolder output | unit | `go test -short ./docs/examples/blog -run '^TestScaffoldLayout$' -count=1 -v` | ✅ | ✅ green | +| 11.1-06-T1 | 06 | DOCS-05 | Every rule has a planted fixture that fails for its own rule (63 committed cases plus 5 built at run time), and the clean fixture passes | unit + gate | `go test ./internal/docsite -run '^(TestPlantedViolations\|TestCleanFixture\|TestBuildOutputGuard)$' -count=1 -v && scripts/check-phase11.1.sh --self-test` | ✅ | ✅ green | +| 11.1-06-T2 | 06 | DOCS-01..05 | internal/docsite statement coverage at least 85% (94.8% measured) | unit | `go test ./internal/docsite -count=1 -coverprofile="${TMPDIR:-/tmp}/docsite.cover" && go tool cover -func="${TMPDIR:-/tmp}/docsite.cover"` | ✅ | ✅ green | +| 11.1-06-T3 | 06 | DOCS-01..08 | SC1..SC5 acceptance subtests; final gate with --named | acceptance + gate | `go test ./cmd/summer -run '^TestPhase11_1Acceptance$' -count=1 -v && scripts/check-phase11.1.sh --all` | ✅ | ✅ green | -*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky* +*Status: ✅ green · ❌ red · ⚠️ flaky. Every automated row is green; only the two manual rows below wait for /gsd-verify-work.* --- ## 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` +- [x] `internal/docsite/` package with test scaffolding and a `testdata/` planted-violation corpus (11.1-01, corpus in 11.1-06) +- [x] `modules/bonfire/example_test.go` — first verified snippet (tracer, 11.1-01) +- [x] `docs/site.yaml`, `docs/index.md`, `docs/setup/installation.md` (11.1-01) +- [x] `cmd/summer/docs.go` + `TestToolCommandNames` extension (11.1-01) +- [x] `scripts/check-phase11.1.sh` with `--self-test` (11.1-02, corpus and `--named` in 11.1-06) +- [x] `/site/` in `.gitignore` (11.1-01) --- @@ -81,18 +82,18 @@ Filled in by the planner from the six PLAN.md files. Real-tree checks live in `c | 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 | +| 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. Status: pending (manual UAT in /gsd-verify-work) | +| Dark mode toggles and persists | DOCS-02 | Visual | `summer docs:serve`, toggle theme, reload, confirm persistence and contrast per UI-SPEC at 1280px, 1024px and 375px, and the no-JS layout. Status: pending (manual UAT in /gsd-verify-work) | --- ## Validation Sign-Off -- [ ] All tasks have `` 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 +- [x] All tasks have `` verify or Wave 0 dependencies +- [x] Sampling continuity: no 3 consecutive tasks without automated verify +- [x] Wave 0 covers all MISSING references +- [x] No watch-mode flags +- [x] Feedback latency < 60s for the quick run; the full gate (`--all`, Docker) takes several minutes +- [x] `nyquist_compliant: true` set in frontmatter -**Approval:** pending +**Approval:** approved 2026-10-01 (plan 11.1-06). Manual UAT of search and dark mode remains for /gsd-verify-work.