docs(13): add research + validation strategy

2026-06-11 19:04:13 -04:00
parent ef87a3edf6
commit ee67dfecef
1 changed files with 82 additions and 0 deletions
@@ -0,0 +1,82 @@
+---
+phase: 13
+slug: real-lint-gate-eslint
+status: draft
+nyquist_compliant: false
+wave_0_complete: false
+created: 2026-06-11
+---
+
+# Phase 13 — Validation Strategy
+
+> Per-phase validation contract for feedback sampling during execution.
+> This phase's deliverable IS a validation gate (ESLint + Prettier). Most
+> verification is gate-based (`pnpm lint` / `pnpm format:check` exit codes),
+> not new vitest specs.
+
+---
+
+## Test Infrastructure
+
+| Property | Value |
+|----------|-------|
+| **Framework** | Vitest (apps/api: node env; apps/pwa: jsdom env) — already present, unchanged |
+| **Config file** | `apps/api/vitest.config.ts`, `apps/pwa/vitest.config.ts` |
+| **Quick run command** | `pnpm lint` (root — runs ESLint across both apps) |
+| **Full suite command** | `pnpm lint && pnpm format:check && pnpm typecheck && pnpm test` |
+| **Estimated runtime** | ~30–60s (type-aware lint over ~91 src files + tests + e2e, no cache) |
+
+---
+
+## Sampling Rate
+
+- **After every task commit:** Run `pnpm lint` (the gate under construction)
+- **After every plan wave:** Run `pnpm lint && pnpm format:check`
+- **Before `/gsd-verify-work`:** `pnpm lint` AND `pnpm format:check` AND `pnpm typecheck` AND `pnpm test` all green across both apps
+- **Max feedback latency:** ~60 seconds
+
+---
+
+## Per-Task Verification Map
+
+| Task ID | Plan | Wave | Requirement | Threat Ref | Secure Behavior | Test Type | Automated Command | File Exists | Status |
+|---------|------|------|-------------|------------|-----------------|-----------|-------------------|-------------|--------|
+| 13-XX-XX | TBD | 1 | SC-1 (gate fails on violation) | — | N/A | smoke gate | `pnpm lint` exits non-zero on deliberate violation | ❌ W0 | ⬜ pending |
+| 13-XX-XX | TBD | 1 | SC-1 (format gate fails) | — | N/A | smoke gate | `pnpm format:check` exits non-zero on unformatted file | ❌ W0 | ⬜ pending |
+| 13-XX-XX | TBD | 2 | SC-3 (baseline green) | — | N/A | end-to-end gate | `pnpm lint` exits 0 (both apps) | ❌ W0 | ⬜ pending |
+| 13-XX-XX | TBD | 2 | SC-3 (format baseline) | — | N/A | end-to-end gate | `pnpm format:check` exits 0 | ❌ W0 | ⬜ pending |
+| 13-XX-XX | TBD | 2 | SC-2 (CI gate blocks PR) | — | N/A | integration | CI `fast-checks` lint + format:check steps report violations (not silent pass) | ❌ W0 | ⬜ pending |
+
+*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky. Task IDs assigned by planner.*
+
+---
+
+## Wave 0 Requirements
+
+- [ ] No new vitest test files are required — the validation is the lint/format gate itself.
+- [ ] `eslint.config.js` + Prettier config + package-level `lint` scripts must exist before any gate assertion can run (this is the phase's own Wave 1 work, not a test scaffold).
+
+*Existing vitest infrastructure is untouched; this phase adds no unit specs.*
+
+---
+
+## Manual-Only Verifications
+
+| Behavior | Requirement | Why Manual | Test Instructions |
+|----------|-------------|------------|-------------------|
+| Lint gate fails CI on a real violation | SC-1 | One-time smoke proof; not a repeatable automated spec | Create throwaway `apps/api/src/_lint-gate-test.ts` with an unhandled `Promise.resolve(1)` (triggers `no-floating-promises`); run `pnpm lint` → assert non-zero; delete file → assert exit 0; do NOT commit the throwaway file |
+| Prettier reformats existing files | SC-3 | Visual confirmation of the mechanical reformat diff | `pnpm format && git diff --stat` shows the reformat; commit isolated from logic fixes for reviewability |
+| CI step activates (was a no-op) | SC-2 | Requires a real PR to main on the Gitea runner | Open PR; observe `fast-checks` lint + format:check steps now report/gate instead of silently passing |
+
+---
+
+## Validation Sign-Off
+
+- [ ] All tasks have a gate command (`pnpm lint` / `pnpm format:check`) or are Wave-1 config prerequisites
+- [ ] Sampling continuity: lint runs after every task commit (gate is the unit of feedback)
+- [ ] Deliberate-violation smoke test documented (SC-1) and executed once
+- [ ] No watch-mode flags in CI
+- [ ] Feedback latency < 60s
+- [ ] `nyquist_compliant: true` set in frontmatter after planner maps task IDs
+
+**Approval:** pending