From ce5dcec7e4e0733b07676b36abb26188d7150501 Mon Sep 17 00:00:00 2001 From: Jakub Zych Date: Thu, 1 Oct 2026 08:53:11 +0200 Subject: [PATCH] docs(11.1-07): record gap-closure checks in validation and the README follow-up - validation map rows 11.1-07-T1 through T5 with the commands that passed - the README src= todo names the refusal, caption and Sync work left --- .../11.1-VALIDATION.md | 7 ++++++- .planning/todos/pending/readme-go-fences-src.md | 2 ++ 2 files changed, 8 insertions(+), 1 deletion(-) 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 1f1b691..5e1e0a1 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 @@ -40,7 +40,7 @@ validated: "2026-10-01" ## 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 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". +Filled in by the planner from plans 01 to 06, with plan 07 rows added for the gap-closure checks. 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 the earlier commands on 2026-10-01; plan 11.1-07 ran its five rows the same day 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 | |---------|------|-------------|----------|-----------|-------------------|-------------|--------| @@ -62,6 +62,11 @@ Filled in by the planner from the six PLAN.md files. Real-tree checks live in `c | 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 | +| 11.1-07-T1 | 07 | DOCS-04 | AST fence discovery refuses a nested src= fence; real tree stays clean | unit + smoke | `go vet ./... && go test ./internal/docsite ./cmd/summer -count=1 && d=$(mktemp -d) && cp -r internal/docsite/testdata/clean/. "$d" && go run ./cmd/summer docs:build --root "$d" --check && printf '\n> [!TIP]\n> ```go src=modules/demo/example_test.go#ExampleHello\n> BOGUS\n> ```\n' >> "$d/docs/extras/faq.md" && ! go run ./cmd/summer docs:build --root "$d" --check > "$d/check.log" 2>&1 && grep -F 'modules/demo/example_test.go#ExampleHello: src= code block must be a top-level block' "$d/check.log" && go run ./cmd/summer docs:build --check` | ✅ | ✅ green | +| 11.1-07-T2 | 07 | DOCS-04 | A golang fence without src= and a module README src= fence are refused | unit + smoke | `go vet ./... && go test ./internal/docsite ./cmd/summer -count=1 && d=$(mktemp -d) && cp -r internal/docsite/testdata/clean/. "$d" && printf '\n```golang\nx := 1\n```\n' >> "$d/docs/extras/faq.md" && ! go run ./cmd/summer docs:build --root "$d" --check > "$d/check.log" 2>&1 && grep -F 'snippet: golang code block has no src= reference' "$d/check.log" && d=$(mktemp -d) && cp -r internal/docsite/testdata/clean/. "$d" && printf '\n```go src=modules/demo/example_test.go#ExampleHello\nfmt.Println(demo.Hello("blog"))\n// Output: Hello, blog\n```\n' >> "$d/modules/demo/README.md" && ! go run ./cmd/summer docs:build --root "$d" --check > "$d/check.log" 2>&1 && grep -F 'module README code blocks are rendered as written' "$d/check.log" && go run ./cmd/summer docs:build --check` | ✅ | ✅ green | +| 11.1-07-T3 | 07 | DOCS-04, DOCS-05 | Build-ignored Go, wrong-case go doc -c, and an env-prefixed command are refused | unit + smoke | `go vet ./... && go test ./internal/docsite ./cmd/summer -count=1 && d=$(mktemp -d) && cp -r internal/docsite/testdata/clean/. "$d" && printf '\n```sh\nFOO=1 summer no:such\n```\n' >> "$d/docs/extras/faq.md" && ! go run ./cmd/summer docs:build --root "$d" --check > "$d/check.log" 2>&1 && grep -F '"no:such" is not a summer or application command' "$d/check.log" && d=$(mktemp -d) && cp -r internal/docsite/testdata/clean/. "$d" && printf 'package demo\n\n// OpenFromApp is a fixture.\nfunc OpenFromApp() {}\n' > "$d/modules/demo/open.go" && printf '\nCall `demo.Openfromapp`.\n' >> "$d/docs/extras/faq.md" && ! go run ./cmd/summer docs:build --root "$d" --check > "$d/check.log" 2>&1 && grep -F 'identifier: demo.Openfromapp does not exist in modules/demo' "$d/check.log" && d=$(mktemp -d) && cp -r internal/docsite/testdata/clean/. "$d" && printf '//go:build ignore\n\npackage demo\n\n// Broken is never built.\nfunc Broken() { undefinedCall() }\n' > "$d/modules/demo/broken.go" && printf '\n```go src=modules/demo/broken.go#Broken\n// Broken is never built.\nfunc Broken() { undefinedCall() }\n```\n' >> "$d/docs/extras/faq.md" && ! go run ./cmd/summer docs:build --root "$d" --check > "$d/check.log" 2>&1 && grep -F 'file is excluded from the default build' "$d/check.log" && go run ./cmd/summer docs:build --check` | ✅ | ✅ green | +| 11.1-07-T4 | 07 | DOCS-04, DOCS-05 | Eighteen planted fixtures and the fence, caption, root, go doc and commandWord tests; coverage at least 85% (94.1% measured) | unit | `go vet ./... && go test ./internal/docsite -run '^(TestPlantedViolations\|TestCleanFixture\|TestCollectFences\|TestFenceCaptionsOnlyVerified\|TestGoLang\|TestNestedFenceChecks\|TestIdentifierGoDocCaseSensitive\|TestCommandWord\|TestSnippetRootsAndBuild\|TestSyncParsedFences)$' -count=1 -v && go test ./internal/docsite -count=1 -coverprofile="${TMPDIR:-/tmp}/docsite.cover" && go tool cover -func="${TMPDIR:-/tmp}/docsite.cover" \| awk '/^total:/ { sub("%", "", $3); if ($3 + 0 < 85.0) { print "coverage " $3 "% below 85%"; exit 1 } }'` | ✅ | ✅ green | +| 11.1-07-T5 | 07 | DOCS-04, DOCS-05 | Acceptance scanner sees blockquoted and aliased fences; the gate plants the holes and --all passes | acceptance + gate | `go vet ./... && go test ./cmd/summer -run '^(TestPhase11_1Acceptance\|TestAcceptanceFenceScanner)$' -count=1 -v && bash -n scripts/check-phase11.1.sh && scripts/check-phase11.1.sh --self-test && scripts/check-phase11.1.sh --all` | ✅ | ✅ green | *Status: ✅ green · ❌ red · ⚠️ flaky. Every automated row is green; only the two manual rows below wait for /gsd-verify-work.* diff --git a/.planning/todos/pending/readme-go-fences-src.md b/.planning/todos/pending/readme-go-fences-src.md index b98e4a2..33d0010 100644 --- a/.planning/todos/pending/readme-go-fences-src.md +++ b/.planning/todos/pending/readme-go-fences-src.md @@ -6,3 +6,5 @@ area: summercms.go/modules/*/README.md, internal/docsite --- Phase 11.1 (D-18) publishes every module README as an `api/` docs page, but its Go code blocks (about 41 across 22 READMEs) are only identifier-checked, not compiled. Move each to an `Example*` or region in the module's `example_test.go` and reference it with `src=`, then drop the README exemption in `internal/docsite` `check_policy.go` so ROADMAP 11.1 SC4 can be widened back to "every Go example in the docs". + +Since 11.1-07, checkSnippets refuses `src=` in module READMEs (`readmeSrcMessage`) and fenceAnnotator captions only docs/ pages. Converting README fences means replacing that refusal with checkFences over README pages, captioning their top-level `src=` fences, and extending Sync to README files.