From 2fdadd3f12be59049e4ce02baf0b2ff994b1ce57 Mon Sep 17 00:00:00 2001
From: Jakub Zych <jakub@keios.eu>
Date: Fri, 18 Sep 2026 12:34:15 +0200
Subject: [PATCH] docs(phase-4): add validation strategy

---
 .../04-VALIDATION.md                          | 60 +++++++++++++++++++
 1 file changed, 60 insertions(+)
 create mode 100644 .planning/phases/04-cli-scaffolding-i18n-and-mail/04-VALIDATION.md

diff --git a/.planning/phases/04-cli-scaffolding-i18n-and-mail/04-VALIDATION.md b/.planning/phases/04-cli-scaffolding-i18n-and-mail/04-VALIDATION.md
new file mode 100644
index 0000000..13790b7
--- /dev/null
+++ b/.planning/phases/04-cli-scaffolding-i18n-and-mail/04-VALIDATION.md
@@ -0,0 +1,60 @@
+---
+phase: 04
+slug: cli-scaffolding-i18n-and-mail
+status: draft
+nyquist_compliant: false
+wave_0_complete: false
+created: 2026-09-18
+---
+
+# Phase 4 — Validation Strategy
+
+## Test Infrastructure
+
+| Property | Value |
+|---|---|
+| Framework | Go 1.27 `testing`; existing `testcontainers-go` convention for Docker integration |
+| Config | Root `go.mod`, `go.work`, and `examples/hello/go.mod` |
+| Quick run | `go test ./internal/build ./cmd/summer ./phrasebook ./postcard -short` after those packages exist |
+| Full suite | `go vet ./... && go test ./...` followed by focused Mailpit SMTP integration and `go test -race ./internal/build ./phrasebook ./postcard` |
+| Estimated runtime | Measure at implementation; require focused checks to stay under 60 seconds on a warm cache |
+
+## Sampling Rate
+
+- After every task commit: run the affected package's focused test, or the generated-plugin build/vet test for scaffold changes.
+- After every plan wave: run root `go vet ./... && go test ./...` and, once generation exists, the temporary hello-plugin compile/vet test.
+- Before `$gsd-verify-work`: run the full suite including Mailpit SMTP receipt; Docker absence is a failure outside `-short`.
+- Maximum feedback latency: 60 seconds for focused tests on a warm cache; Mailpit starts only at the full gate.
+
+## Per-Task Verification Map
+
+| Task ID | Plan | Wave | Requirement | Threat Ref | Secure Behavior | Test Type | Automated Command | File Exists | Status |
+|---|---|---|---|---|---|---|---|---|---|
+| To fill after PLAN.md creation | — | — | CLI-02 | T-04-01 | Generated names and imports stay inside plugin module | compile/integration | `go test ./internal/build ./cmd/summer` | ❌ W0 | ⬜ pending |
+| To fill after PLAN.md creation | — | — | I18N-01 | T-04-02 | Malformed YAML/plurals fail boot with context | unit | `go test ./phrasebook` | ❌ W0 | ⬜ pending |
+| To fill after PLAN.md creation | — | — | I18N-03 | T-04-03, T-04-04 | Safe final HTML, explicit SMTP policy, driver errors propagated | unit/integration | `go test ./postcard` | ❌ W0 | ⬜ pending |
+
+*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
+
+## Wave 0 Requirements
+
+- [ ] Add an `internal/build` test that generates all six artifacts into a temporary copy of `examples/hello` and runs `go build` plus `go vet` there.
+- [ ] Add `phrasebook` fixture plugin assets for pl/en YAML, nested keys, map and pipe plurals, and fallback tests.
+- [ ] Add `postcard` memory-driver rendering tests, malicious-variable cases, and a Mailpit testcontainer fixture with SMTP and HTTP ports.
+
+No new test framework is needed. These fixtures should be created by the first implementation task that uses them.
+
+## Manual-Only Verifications
+
+All phase behaviors have automated verification. Production SMTP credentials and transport are deployment configuration, so the phase uses Mailpit for a real SMTP receipt without a live external account.
+
+## Validation Sign-Off
+
+- [ ] Every plan task has an automated `<verify>` command or a Wave 0 dependency.
+- [ ] No three consecutive tasks lack automated verification.
+- [ ] Generated plugin compiles and vets; pl/en catalog and Mailpit send pass.
+- [ ] No watch-mode flags in verification commands.
+- [ ] Fill task IDs and measured runtime after plans and implementation evidence exist.
+- [ ] Set `nyquist_compliant: true` only after the full gate passes.
+
+**Approval:** pending.