From e0cf189ad846ccb58ca7d34aaf3e14cf253a3db4 Mon Sep 17 00:00:00 2001 From: Jakub Zych Date: Mon, 26 Oct 2026 20:04:32 +0100 Subject: [PATCH] docs(phase-32): add validation strategy --- .../phases/32-seo-foundation/32-VALIDATION.md | 94 +++++++++++++++++++ 1 file changed, 94 insertions(+) create mode 100644 .planning/phases/32-seo-foundation/32-VALIDATION.md diff --git a/.planning/phases/32-seo-foundation/32-VALIDATION.md b/.planning/phases/32-seo-foundation/32-VALIDATION.md new file mode 100644 index 00000000..30b59411 --- /dev/null +++ b/.planning/phases/32-seo-foundation/32-VALIDATION.md @@ -0,0 +1,94 @@ +--- +phase: "32" +slug: "seo-foundation" +# 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 +created: "2026-10-26" +--- + +# Phase 32 — Validation Strategy + +> Per-phase validation contract for feedback sampling during execution. Source: `32-RESEARCH.md` § Validation Architecture. + +--- + +## Test Infrastructure + +| Property | Value | +|----------|-------| +| **Framework** | Go `testing` (+ testify), testcontainers-go Postgres; vitest + happy-dom for `admin/` and the sm-seo-plugin elements | +| **Config file** | none for Go; `admin/vitest.config.ts`; `../sm-seo-plugin/vite.config.ts` (Wave 0) | +| **Quick run command** | `go test -short ./modules/cabana ./modules/pact ./modules/signpost` and `go -C ../sm-seo-plugin test -short ./...` | +| **Full suite command** | `go vet ./... && go test ./...` in summercms.go, sm-seo-plugin, sm-journal-plugin, sm-demo-app; `npm --prefix admin run test`; `npm --prefix ../sm-seo-plugin run test`; `scripts/check-phase32.sh --all` | +| **Estimated runtime** | ~60 seconds quick, ~6 minutes full (Docker) | + +--- + +## Sampling Rate + +- **After every task commit:** `go vet ./... && go test -short ./...` in the touched repo (+ `npm --prefix admin run test` if `admin/` changed) +- **After every plan wave:** full `go test ./...` with Docker in each touched repo; `scripts/check-admin-openapi.sh --check` if cabana payloads changed +- **Before `/msd-verify-work`:** `scripts/check-phase32.sh --all` green +- **Max feedback latency:** 60 seconds (quick loop) + +--- + +## Per-Task Verification Map + +Filled by the planner per task. Success-criterion map from research: + +| Criterion | Behavior | Test Type | Automated Command | File Exists | Status | +|-----------|----------|-----------|-------------------|-------------|--------| +| SC-1 | Placement: C after A → A, C, B; before first; tab between tabs; shared anchor order; hide; span | unit | `go test -short ./modules/cabana -run 'TestFormExtension'` | ❌ W0 | ⬜ pending | +| SC-1 | Boot errors: unknown anchor, anchor outside `Requires()`, duplicate, cycle | unit | `go test -short ./modules/cabana -run 'TestFormExtensionBootErrors'` | ❌ W0 | ⬜ pending | +| SC-1 | Extension Load/Save inside the save transaction, rollback on error | integration | `go test ./modules/cabana -run 'TestFormExtensionSave'` | ❌ W0 | ⬜ pending | +| SC-1 | SPA renders compiled order | vitest | `npm --prefix admin run test -- tests/form/FormView.test.ts` | ✅ | ⬜ pending | +| SC-2 | Content descriptors optional, existing types unchanged | unit | `go test -short ./modules/signpost ./modules/pact -run 'TestContent'` | ❌ W0 | ⬜ pending | +| SC-2 | Precedence URL rule > record > global > derived, with sources | unit | `go -C ../sm-seo-plugin test -short ./classes -run TestResolverPrecedence` | ❌ W0 | ⬜ pending | +| SC-2 | SEO tab on posts, categories, tags; journal never imports sm-seo-plugin | integration + grep | `go -C ../sm-seo-plugin test ./... -run TestSEOTab`; `scripts/check-phase32.sh` | ❌ W0 | ⬜ pending | +| SC-3 | Redirect graph flatten, back-and-forth, loop refusal (exact/pattern/regex) | unit | `go -C ../sm-seo-plugin test -short ./classes -run 'TestRedirectGraph'` | ❌ W0 | ⬜ pending | +| SC-3 | Record event after commit → 301 (cabana and journal API paths) | integration | `go test ./modules/cabana -run TestRecordEvents`; `go -C ../sm-seo-plugin test ./... -run TestSlugChange301`; `go -C ../sm-journal-plugin test ./... -run TestAPIRecordEvents` | ❌ W0 | ⬜ pending | +| SC-3 | Loops refused from admin, MCP API, CSV import | integration | `go -C ../sm-seo-plugin test ./... -run 'TestLoopRefused'` | ❌ W0 | ⬜ pending | +| SC-4 | Every SEO admin operation has an MCP tool | integration | `go -C ../sm-demo-app test -tags summercms_mcp ./... -run TestSEOToolsCatalog` | ❌ W0 | ⬜ pending | +| SC-4 | Batch dry-run writes nothing; apply all-or-nothing; undo change/batch | integration | `go -C ../sm-seo-plugin test ./... -run 'TestBatch|TestUndo'` | ❌ W0 | ⬜ pending | +| SC-5 | Framework tag; consumers build against it; docs checker | gate | `scripts/check-phase32.sh --all`; `summer docs:build --check` | ❌ W0 | ⬜ pending | + +*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky* + +--- + +## Wave 0 Requirements + +- [ ] `modules/cabana/form_extension_test.go` — placement and boot-error tables +- [ ] `modules/cabana/record_events_test.go` — after-commit and rollback (testcontainers) +- [ ] `modules/signpost` content-descriptor tests +- [ ] `../sm-seo-plugin/testmain_test.go` (`flag.Parse()` + `testing.Short()`) and a fake content plugin fixture +- [ ] `../sm-seo-plugin/package.json`, `vite.config.ts`, vitest setup +- [ ] `scripts/check-phase32.sh` modelled on `scripts/check-phase19.7.sh`, with a grep stage: no SEO identifiers under `modules/` (D-90), no consuming app named +- [ ] `journal-tag` menu item type test in sm-journal-plugin + +--- + +## Manual-Only Verifications + +| Behavior | Requirement | Why Manual | Test Instructions | +|----------|-------------|------------|-------------------| +| SEO tab visual layout and SERP preview in the admin | SC-2 | visual rendering | Open a journal post in the demo app admin, check the SEO tab against UI-SPEC | +| MCP session from a real Claude client (noindex/301 by URL) | SC-4 | external client | Link an admin, run the tools with dry-run, apply, undo | +| Release tag push and changelog post | SC-5 | needs Jakub's go-ahead | Per CLAUDE.md release steps | + +--- + +## 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 + +**Approval:** pending