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

docs(11.2): validate the phase verification map

Browse Source
This commit is contained in:
Jakub Zych
2026-10-01 16:39:09 +02:00
parent 29adc23595
commit a2f2d1e5c7
1 changed files with 56 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

92
.planning/phases/11.2-ready-to-share-summercms-io-website-and-newsletter-plugin/11.2-VALIDATION.md
View File

@@ -3,10 +3,11 @@ phase: "11.2"
slug: "ready-to-share-summercms-io-website-and-newsletter-plugin" slug: "ready-to-share-summercms-io-website-and-newsletter-plugin"
# status lifecycle: draft (seeded by plan-phase) → validated (set by validate-phase §6) # 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) # audit-milestone §5.5 distinguishes NOT-VALIDATED (draft) from PARTIAL (validated + nyquist_compliant: false) (#2117)
status: draft status: validated
nyquist_compliant: false nyquist_compliant: true
wave_0_complete: false wave_0_complete: true
created: "2026-10-01" created: "2026-10-01"
validated: "2026-10-01"
--- ---
# Phase 11.2 — Validation Strategy # Phase 11.2 — Validation Strategy
@@ -20,10 +21,11 @@ created: "2026-10-01"
| Property | Value | | Property | Value |
|----------|-------| |----------|-------|
| **Framework** | Go `testing` (stdlib, `httptest`, `testing/fstest`) in summercms.go, sm-summercmsio-plugin and sm-summercmsio-app; `node:test` in vue-summercmsio-app | | **Framework** | Go `testing` (stdlib, `httptest`, `testing/fstest`) in summercms.go, sm-summercmsio-plugin and sm-summercmsio-app; `node:test` in vue-summercmsio-app |
| **Config file** | none; `vue-summercmsio-app/package.json` script `"test": "node --test tests/*.test.ts"` (Wave 0) | | **Config file** | none; `vue-summercmsio-app/package.json` script `"test": "node --test tests/*.test.ts"` |
| **Quick run command** | touched repo: `go vet ./... && go test ./...`; site: `pnpm generate && pnpm test` | | **Quick run command** | touched repo: `go vet ./... && go test ./...`; site: `pnpm generate && pnpm test` |
| **Full suite command** | framework `go vet ./... && go test ./...`; app `scripts/build.sh dev` then `go vet ./... && go test ./...` (plugin with `SUMMERCMS_REQUIRE_BUILD=1`); site `pnpm generate && pnpm test` | | **Full suite command** | framework `go vet ./... && go test ./...`; app `scripts/build.sh dev` then `go vet ./... && go test ./...` (plugin with `SUMMERCMS_REQUIRE_BUILD=1`); site `pnpm generate && pnpm test` |
| **Estimated runtime** | ~180 seconds (framework DB suites dominate) | | **Phase gate** | `scripts/check-phase11.2.sh --all` (stages `--framework`, `--plugin`, `--app`, `--site`, `--built`, `--smoke`, `--deploy`, `--terminal`, `--full`) |
| **Estimated runtime** | about 15 s per Go stage, about 20 s for the site, about 1 min for build and smoke, several minutes for `--full` (Docker database suites) |
--- ---
@@ -31,41 +33,57 @@ created: "2026-10-01"
- **After every task commit:** the touched repo's `go vet ./... && go test ./...` (framework may use `-short` except on D-25/D-41 tasks); `pnpm generate` when Nuxt files change - **After every task commit:** the touched repo's `go vet ./... && go test ./...` (framework may use `-short` except on D-25/D-41 tasks); `pnpm generate` when Nuxt files change
- **After every plan wave:** framework full `go test ./...`; `scripts/build.sh dev`; plugin tests with `SUMMERCMS_REQUIRE_BUILD=1`; `pnpm test` - **After every plan wave:** framework full `go test ./...`; `scripts/build.sh dev`; plugin tests with `SUMMERCMS_REQUIRE_BUILD=1`; `pnpm test`
- **Before `/gsd-verify-work`:** full suite green, plus `SUMMERCMS_TERMINAL_CHECK=1` with a local clone override, `scripts/smoke.sh` on postgres:15, `nginx -t` of the shipped config - **Before `/gsd-verify-work`:** `scripts/check-phase11.2.sh --all` green. It covers `SUMMERCMS_TERMINAL_CHECK=1` with a local clone override, `scripts/smoke.sh` on postgres:15 and `nginx -t` of the shipped config.
- **Max feedback latency:** 180 seconds - **Max feedback latency:** 180 seconds per stage; `--full` is the slow outlier
--- ---
## Per-Task Verification Map ## Per-Task Verification Map
Filled from the PLAN.md files once written. Requirement → check map: One row per task of plans 11.2-01, 11.2-02 and 11.2-03. Commands run from the summercms.go root; `APP` is `../sm-summercmsio-app`, `PLUG` is `APP/plugins/golem15/summercms` and `SITE` is `APP/vue-summercmsio-app`. Plan 11.2-03 Task 3 re-ran every row through `scripts/check-phase11.2.sh --all` on 2026-10-01. The gate runs Go tests with `-json` and refuses a failure, a skip, a missing or renamed test, zero tests and "no tests to run".
| Task ID | Plan | Proves | Behavior | Test Type | Automated Command | File Exists | Status |
|---------|------|--------|----------|-----------|-------------------|-------------|--------|
| 11.2-01-T1 | 01 | SC1, D-33, D-34, D-36, D-37 | `nuxt generate` prerenders the header and hero from en.json, self-hosts the fonts, ships the real sun and the static SEO output | output assertion | `pnpm -C ../sm-summercmsio-app/vue-summercmsio-app install --frozen-lockfile && pnpm -C ../sm-summercmsio-app/vue-summercmsio-app run generate && pnpm -C ../sm-summercmsio-app/vue-summercmsio-app test` | ✅ | ✅ green |
| 11.2-01-T2 | 01 | SC1, SC3, D-09, D-12, D-44 | Why, Features, From WinterCMS and the footer, with every docs, source and credit link | output assertion | `pnpm -C ../sm-summercmsio-app/vue-summercmsio-app run generate && pnpm -C ../sm-summercmsio-app/vue-summercmsio-app test` | ✅ | ✅ green |
| 11.2-01-T3 | 01 | SC1, D-39, D-40, D-45 | Terminal card with six commands, a Copy payload of six lines, scroll-spy selection | unit (TS) + output | `pnpm -C ../sm-summercmsio-app/vue-summercmsio-app run generate && pnpm -C ../sm-summercmsio-app/vue-summercmsio-app test && node --test ../sm-summercmsio-app/vue-summercmsio-app/tests/terminal.test.ts ../sm-summercmsio-app/vue-summercmsio-app/tests/scrollSpy.test.ts` | ✅ | ✅ green |
| 11.2-02-T1 | 02 | SC2, D-05, D-07, D-24, D-47 | One binary boots on postgres:15 and serves `/` and `/docs` with indexable, cache-correct responses | integration smoke | `../sm-summercmsio-app/scripts/build.sh dev && ../sm-summercmsio-app/scripts/smoke.sh && go -C ../sm-summercmsio-app vet ./... && go -C ../sm-summercmsio-app/plugins/golem15/summercms vet ./... && go -C ../sm-summercmsio-app/plugins/golem15/summercms test ./... -run '^TestStaticSmoke$' -count=1 -v` | ✅ | ✅ green |
| 11.2-02-T2 | 02 | D-25, D-26, D-41, D-46 | Framework docs say PostgreSQL 15 or newer; `site_url`/`site_label` and the flags add the docs header link; unset output unchanged | unit + gate | `go vet ./... && go test ./internal/docsite ./cmd/summer -run '^(TestDocsTree\|TestDocsBuildRealTree\|TestToolCommandNames\|TestParseSite\|TestSiteLink\|TestDocsBuildSiteFlags)$' -count=1 -v && scripts/check-phase11.1.sh --docs && scripts/check-phase11.1.sh --forbidden` | ✅ | ✅ green |
| 11.2-02-T3 | 02 | D-42 | The v0.1.0 tag decision (blocking-human checkpoint) | decision checkpoint | none: resolved as defer-tag. `git tag -l v0.1.0` prints nothing until cutover; the release path was proven on a scratch clone with a local tag (11.2-02-SUMMARY) | n/a | ✅ green (resolved: defer-tag) |
| 11.2-02-T4 | 02 | SC3, SC4, D-40, D-42, D-44, D-46 | Every landing link resolves against the built site, the page shows every terminal command, the docs header links back, and the six commands run from a fresh shell | integration + scripted e2e | `scripts/check-phase11.2.sh --built && scripts/check-phase11.2.sh --smoke && scripts/check-phase11.2.sh --terminal` (runs `SUMMERCMS_REQUIRE_BUILD=1 ... -run '^(TestLandingLinks\|TestTerminalCommandsInPage\|TestDocsHeaderSiteLink)$'` and `SUMMERCMS_TERMINAL_CHECK=1 SUMMERCMS_CLONE_URL=<summercms.go> ... -run '^TestTerminalCommands$'`) | ✅ | ✅ green |
| 11.2-02-T5 | 02 | SC4, D-27 to D-32 | nginx config passes `nginx -t`; the supervisor program parses; DEPLOY.md and the env and rollback copies exist | scripted | `../sm-summercmsio-app/scripts/check-deploy.sh` (gate: `scripts/check-phase11.2.sh --deploy`) | ✅ | ✅ green |
| 11.2-03-T1 | 03 | SC2, SC5, D-07, D-47, T-11.2-04, T-11.2-05 | Every static serving rule and route behaviour of the site plugin; plugin coverage at least 90% (98.2% measured) | unit + gate | `go -C ../sm-summercmsio-app/plugins/golem15/summercms vet ./... && go -C ../sm-summercmsio-app/plugins/golem15/summercms test ./... -run '^(TestStatic\|TestNewHandlersMissingIndex\|TestContentType\|TestSiteImmutable\|TestRoutes\|TestPlugin\|TestPageLinks)' -count=1 -v && scripts/check-phase11.2.sh --plugin` | ✅ | ✅ green |
| 11.2-03-T2 | 03 | SC5, D-40, D-41, D-46, T-11.2-09 | `checkSiteURL`, `siteLabel`, the override precedence, header escaping and CLI flags; terminal-check helpers; TS edge cases; docsite coverage at least 85% (94.2% measured) | unit + gate | `go vet ./... && go test ./internal/docsite ./cmd/summer -run '^(TestParseSite\|TestCheckSiteURL\|TestSiteLabel\|TestSiteURLPrecedence\|TestSiteLink\|TestDocsBuildSiteFlags\|TestDocsSiteFlagsInHelp\|TestDocsTree)$' -count=1 -v && go -C ../sm-summercmsio-app test -run '^(TestLoadTerminal\|TestTerminalScript\|TestTerminalEnv)$' -count=1 -v . && scripts/check-phase11.2.sh --framework && scripts/check-phase11.2.sh --app && scripts/check-phase11.2.sh --site` | ✅ | ✅ green |
| 11.2-03-T3 | 03 | SC1 to SC5 | The whole phase across the four repositories through one fail-closed gate | gate | `scripts/check-phase11.2.sh --all` | ✅ | ✅ green |
### Requirement map
| Req | Behavior | Test Type | Automated Command | File Exists | Status | | Req | Behavior | Test Type | Automated Command | File Exists | Status |
|-----|----------|-----------|-------------------|-------------|--------| |-----|----------|-----------|-------------------|-------------|--------|
| SC1 | generate succeeds; section ids, en.json copy, self-hosted fonts, robots + flat sitemap, absolute og:image, six commands | output assertion | `pnpm generate && node --test tests/output.test.ts` | ❌ W0 | ⬜ pending | | SC1 | generate succeeds; section ids, en.json copy, self-hosted fonts, robots + flat sitemap, absolute og:image, six commands | output assertion | `pnpm generate && node --test tests/output.test.ts` (gate `--site`) | ✅ | ✅ green |
| SC1 | scroll-spy selection; copy payload = six lines | unit (TS) | `node --test tests/scrollSpy.test.ts tests/terminal.test.ts` | ❌ W0 | ⬜ pending | | SC1 | scroll-spy selection; copy payload = six lines | unit (TS) | `node --test tests/scrollSpy.test.ts tests/terminal.test.ts` | ✅ | ✅ green |
| SC2 | status, content type and cache headers for `/`, `/_nuxt`, `/_fonts`, `/docs`, 404s, ETag/304, traversal | unit | `go test ./... -run TestStatic` (plugin) | ❌ W0 | ⬜ pending | | SC2 | status, content type and cache headers for `/`, `/_nuxt`, `/_fonts`, `/docs`, 404s, ETag/304, HEAD, Range, traversal, redirect locations | unit | `go test ./... -run '^TestStatic'` (plugin; gate `--plugin`) | ✅ | ✅ green |
| SC2 | plugin routes assemble without conflict; no admin routes | unit | `go test ./... -run TestRoutesAssemble` (plugin) | ❌ W0 | ⬜ pending | | SC2 | plugin routes assemble without conflict, GET only, no admin routes, coexist with the admin patterns | unit | `go test ./... -run '^(TestRoutes\|TestPlugin)'` (plugin) | ✅ | ✅ green |
| SC2 | binary boots on PG15 and serves both trees | integration smoke | `scripts/smoke.sh` (app) | ❌ W0 | ⬜ pending | | SC2 | binary boots on PG15 and serves both trees | integration smoke | `scripts/smoke.sh` (app; gate `--smoke`) | ✅ | ✅ green |
| SC3 | every href in the built index.html resolves | integration | `SUMMERCMS_REQUIRE_BUILD=1 go test ./... -run TestLandingLinks` (plugin) | ❌ W0 | ⬜ pending | | SC3 | every link in the built index.html resolves | integration | `SUMMERCMS_REQUIRE_BUILD=1 go test ./... -run TestLandingLinks` (plugin; gate `--built`) | ✅ | ✅ green |
| SC3 | external links 200 anonymously | network, at cutover | `SUMMERCMS_CHECK_EXTERNAL=1 go test ./... -run TestExternalLinks` | ❌ W0 | ⬜ pending | | SC4 | terminal commands run from a fresh shell (local clone override) | scripted e2e | `SUMMERCMS_TERMINAL_CHECK=1 SUMMERCMS_CLONE_URL=<summercms.go> go test -run TestTerminalCommands .` (app; gate `--terminal`) | ✅ | ✅ green |
| SC4 | terminal commands run verbatim | scripted e2e | `SUMMERCMS_TERMINAL_CHECK=1 go test -run TestTerminalCommands .` (app) | ❌ W0 | ⬜ pending | | SC4 | linux/amd64 binary with both trees embedded | scripted | `scripts/build.sh dev` (gate `--built`; release mode when the v0.1.0 tag exists) | ✅ | ✅ green |
| SC4 | linux/amd64 binary with both trees embedded | scripted | `scripts/build.sh dev && file bin/summercms-io` | ❌ W0 | ⬜ pending | | SC4 | nginx config syntactically valid | scripted | `scripts/check-deploy.sh` (gate `--deploy`) | ✅ | ✅ green |
| SC4 | nginx config syntactically valid | scripted | `nginx -t -p $TMP -c $TMP/nginx.conf` | ❌ W0 | ⬜ pending | | D-25 | DB suites green on PG 15 | scripted throwaway | export + sed + `go test` (RESEARCH § PostgreSQL 15); run in 11.2-02 with EXIT=0 on 11 postgres:15 containers | ✅ | ✅ green |
| D-25 | DB suites green on PG 15 | scripted throwaway | export + sed + `go test` (RESEARCH § PostgreSQL 15) | ✅ | ⬜ pending | | D-41 | `site_url` parsed and validated; header link only when set; unset output unchanged | unit | `go test ./internal/docsite -run '^(TestParseSite\|TestCheckSiteURL\|TestSiteLabel\|TestSiteURLPrecedence\|TestSiteLink)$' && go test ./cmd/summer -run '^(TestDocsTree\|TestDocsBuildSiteFlags\|TestDocsSiteFlagsInHelp)$'` (gate `--framework`) | ✅ | ✅ green |
| D-41 | `site_url` parsed; header link only when set; unset output unchanged | unit | `go test ./internal/docsite -run 'TestParseSite\|TestSiteURL' && go test ./cmd/summer -run TestDocsTree` | partial | ⬜ pending | | SC5 | coverage of the new Go code | unit | plugin at least 90% (`--plugin`), `internal/docsite` at least 85% (`--framework`), app helpers by `TestLoadTerminal`, `TestTerminalScript`, `TestTerminalEnv` (`--app`) | ✅ | ✅ green |
| SC5 | coverage of new Go code | unit | `go test -cover ./...` (plugin, app) | ❌ W0 | ⬜ pending |
*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky* *Status: ✅ green · ❌ red · ⚠️ flaky. Every automated row is green; the cutover-only checks are in the manual table below.*
--- ---
## Wave 0 Requirements ## Wave 0 Requirements
- [ ] `vue-summercmsio-app/tests/{output,scrollSpy,terminal}.test.ts` and the `"test"` script - [x] `vue-summercmsio-app/tests/{output,scrollSpy,terminal}.test.ts` and the `"test"` script (11.2-01)
- [ ] sm-summercmsio-plugin `static_test.go`, `routes_test.go`, `links_test.go` with `fstest.MapFS` fixtures - [x] sm-summercmsio-plugin `static_test.go`, `routes_test.go`, `links_test.go` with `fstest.MapFS` fixtures (smoke and links in 11.2-02, the rule tables in 11.2-03)
- [ ] sm-summercmsio-app `terminal_check_test.go`, `scripts/smoke.sh`, optional `scripts/check-nginx.sh` - [x] sm-summercmsio-app `terminal_check_test.go`, `scripts/smoke.sh`, `scripts/check-deploy.sh` (11.2-02; the ungated helper tests in 11.2-03)
- [ ] framework: extend `internal/docsite/load_test.go` and `theme_test.go` for `site_url` - [x] framework: `internal/docsite/load_test.go` and `theme_test.go` extended for `site_url` (11.2-02, full branch coverage in 11.2-03)
- [x] `scripts/check-phase11.2.sh` phase gate (11.2-03)
--- ---
@@ -73,19 +91,21 @@ Filled from the PLAN.md files once written. Requirement → check map:
| Behavior | Requirement | Why Manual | Test Instructions | | Behavior | Requirement | Why Manual | Test Instructions |
|----------|-------------|------------|-------------------| |----------|-------------|------------|-------------------|
| Visual fidelity at 1280/721/720/375px, sticky header, Copy → "Copied" 1.5s, nav hidden ≤720px | SC1 | pixel and interaction fidelity against the handoff | open the generated site next to `design/SummerCMS Landing.dc.html` at each width | | Visual fidelity at 1280/721/720/375px, sticky header, live scroll-spy, Copy → "Copied" for 1.5s and the clipboard contents, nav hidden at 720px and below | SC1, D-23 | pixel and interaction fidelity against the handoff | open the generated site next to `design/SummerCMS Landing.dc.html` at each width. Status: pending (manual UAT in /gsd-verify-work) |
| Clean-server bring-up on rome | SC4 | server not reachable from the dev machine | follow DEPLOY.md end to end; human checkpoint | | Clean-server bring-up on rome | SC4 | the server is not reachable from the dev machine | follow DEPLOY.md end to end at cutover. Status: pending (cutover) |
| Source link anonymous access | SC3 / D-38 | repo must be made public by the user first | run `TestExternalLinks` at cutover | | External links answer 200 anonymously, including the Source link | SC3, D-38 | the framework repository must be made public by the user first | at cutover: `SUMMERCMS_CHECK_EXTERNAL=1 go -C ../sm-summercmsio-app/plugins/golem15/summercms test -run '^TestExternalLinks$' -count=1 -v ./...`. Status: pending (cutover, after D-38) |
| The six terminal commands run verbatim against the public clone URL | SC4, D-38, D-40 | needs the public repository | at cutover: `scripts/check-phase11.2.sh --terminal --verbatim`. Status: pending (cutover, after D-38) |
| Release build from the real v0.1.0 tag | D-42 | the tag was deferred by the user (defer-tag) | after the tag is created: `scripts/check-phase11.2.sh --built` reports a release build, then `--smoke`. Status: pending (cutover, after D-42) |
--- ---
## Validation Sign-Off ## Validation Sign-Off
- [ ] All tasks have `<automated>` verify or Wave 0 dependencies - [x] All tasks have `<automated>` verify or Wave 0 dependencies (11.2-02-T3 is the D-42 decision checkpoint, resolved defer-tag)
- [ ] Sampling continuity: no 3 consecutive tasks without automated verify - [x] Sampling continuity: no 3 consecutive tasks without automated verify
- [ ] Wave 0 covers all MISSING references - [x] Wave 0 covers all MISSING references
- [ ] No watch-mode flags - [x] No watch-mode flags
- [ ] Feedback latency < 180s - [x] Feedback latency < 180s per stage; `--full` (Docker database suites) takes several minutes
- [ ] `nyquist_compliant: true` set in frontmatter - [x] `nyquist_compliant: true` set in frontmatter
**Approval:** pending **Approval:** approved 2026-10-01 (plan 11.2-03). The manual rows (visual UAT, rome bring-up, external links, the verbatim clone and the release build from the real tag) remain for /gsd-verify-work and the cutover.