golem15/summercms
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(11.1): create phase plan

Browse Source 
Six plans (tracer generator, site UX and checkers, content A, content B,
acme/blog walkthrough, unit tests). SC4/DOCS-04 narrowed to docs/ pages per
D-18; README Go fence conversion logged as a todo.
This commit is contained in:
Jakub Zych
2026-09-30 20:33:51 +02:00
parent a33b1ada80
commit 6f57604028
13 changed files with 1901 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -39,20 +39,28 @@ created: "2026-09-28"
## Per-Task Verification Map
Filled in by the planner once PLAN.md files exist. Requirement → test mapping from RESEARCH.md:
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.
| 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 |
| 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 |
*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*