Windsurf rules

1---
2name: verify-work
3model: haiku
4description: "Multi-phase UAT gate — cold-start smoke, build, typecheck, lint, tests, step-by-step manual verification, gaps-closure loop. Use after execute-plan or develop-tdd, before audit-code."
5---
6 
7<!-- story: e02s01 e46s03 -->
8<!-- story: e38s05 -->
9<!-- story: e45s05 -->
10<!-- story: e45s09 -->
11<!-- story: e45s13 -->
12<!-- story: e45s40 -->
13<!-- story: e51s03 -->
14<!-- story: e20s04 -->
15<!-- story: e20s06 -->
16 
17 
18# Verify Work
19 
20> **HARD GATE** — No story is "done" until manual UAT for the active story is confirmed with evidence.
21>
22> **HARD GATE** — Do NOT run on `main` or `master`. Use the feature branch from `kickoff-branch`.
23 
24Review answers "is the code good?"; Verify answers "does the built thing do what was promised?"
25 
26## Modes
27 
28- Default: full UAT plus gaps loop
29- --smoke: Cold-start only plus one happy-path flow. Use for hotfixes.
30- --cli: CLI tool verification — replaces cold-start with binary smoke checklist. Use for CLI tools with no server process.
31 
32## Risk-Scaled Depth
33 
34`verify-work` reads the `risk:` field from the story template (defaults to `P1` if absent) to scale verification rigor:
35- **P0**: Full verify-work multi-phase + `security-review` (step 5) + NFR evidence gate (step 5b).
36- **P1**: Standard verify-work (build, test, lint, step-by-step manual).
37- **P2**: Smoke, typecheck, lint only. Skip tests, security scan, and step-by-step manual UAT.
38- **P3**: Typecheck and lint only. Skip smoke, tests, security scan, and step-by-step manual UAT.
39 
40## Process
41 
42> **Timing:** `bash scripts/bp-timing.sh start verify-work` at invocation; `bash scripts/bp-timing.sh end verify-work` before handoff.
43 
440. **Branch check** — must not be `main`/`master`.
45 
460a. **Preflight / CI green (HARD GATE — e51s03)** — Run Preflight from `CLAUDE.md` or `BP_PREFLIGHT` (`bp-read-agents.sh`). If PR open: `gh pr checks` (**CI green**). Failure blocks all phases → `quick-fix` or `fix-bug`.
47 
481. Read active story tasks from `specs/epics/<capsule>/eNNsYY-tasks.yaml` and story spec from `specs/epics/<capsule>/eNNsYY-<slug>.md` (countable-story-format, Gherkin in §17). Note the `risk:` level (`P0`–`P3`).
491a. **Pre-UAT verify validation** — for each task's `verify:` command, run it and detect pattern mismatches before UAT begins. If a grep/awk/jq command fails, check whether the pattern is wrong vs. a genuine failure:
50```bash
51    # For a failing grep -q 'PATTERN' FILE, check what is actually in FILE
52    grep 'PATTERN' FILE || grep -n '' FILE | head -20   # show nearest lines
53```
54    Report: `"Pattern 'X' not found. Nearest match: 'Y' at line N"` and ask `"Update verify command? [Y/n]"`. Fix before proceeding — a mismatched verify command produces false failures during UAT.
552. **Cold-start smoke** (if app; skip if P3): stop server, clear caches, boot from scratch.
563. **AGENTS.md preflight** — if 0a skipped BP_PREFLIGHT, run `bash scripts/bp-read-agents.sh` and use detected command.
574. Mechanical gates: build → typecheck → lint → tests (from `CLAUDE.md` or AGENTS.md). Skip tests if P2/P3.
58 
59> **HARD GATE — One-test-minimum terminal verdict (e45s13):** At least one mechanical gate MUST be a **real terminal-verdict command** (shell exits 0 or non-zero — not prose, not combined log excerpts). Record that command's stdout/stderr from a **single contiguous run** in `specs/verifications/eNNsYY-verify.yaml` under `terminal_verdict`. Bug reports and gap logs MUST NOT merge evidence from multiple runs into one verdict — each failing run gets its own evidence block.
60 
615. **Security scan** (skip if P2/P3) — run `security-review` against the git diff (working tree vs merge-base). Parse findings report. If any HIGH findings with confidence ≥ 8 exist → **block the gate**. Write findings to `specs/security/REVIEW.md`. Allow documented exceptions via `specs/security/EXCEPTIONS.md`. MEDIUM/LOW findings warn but don't block.
625a. **Blind-spot check** — run `bash scripts/check-blind-spots.sh`. This detects structural quality gaps (verify-gap, test-gap, stale-tag, etc.) beyond percentage coverage. If any HIGH-severity findings exist → **block the verify-work PASS gate**. Findings are written to `specs/blind-spots.json`. MEDIUM/LOW findings warn but don't block.
635a2. **Completeness critic (e45s05)** — `bash scripts/lib/completeness-critic.sh`. **BLOCKER** aborts merge gate; WARNING → gaps loop; FILLED = evidence only.
64 
655b. **NFR Evidence Gate** (P0 only) — Produces go/no-go output on three dimensions: Performance (response time, throughput), Reliability (error rate, recovery), and Operability (logging, health checks). Reads thresholds from `specs/tech-architecture/eNN-TEST_PLAN_LATEST.md` and writes evidence as OKF verification-report bundles to `specs/verifications/NFR-eNNsYY.json`. FAIL on any dimension blocks the gate.
666. **Step-by-step UAT** (skip if P2/P3) — one user-observable action at a time.
677. **Gaps loop** — failures → log → `plan-work` → re-verify. Unaddressed HIGH findings from step 5 feed into this loop alongside other quality gaps.
68 
697a. **Validation gate (e45s09)** — All tasks `status: passing`; evidence in `specs/verifications/`; update `execution-status.yaml`.
707b. **Reopen-don't-refile (e45s09)** — Regressions reopen existing story/bug — no duplicate capsule entries.
71 
72## Verify sub-operations
73 
74### Cold-Start Smoke (absorbed)
75 
76Stop server, clear caches, boot from scratch; confirm no stale config affects behavior.
77 
78### Gaps Loop (absorbed)
79 
80After UAT, identify and close any gaps between promised behavior and actual behavior:
81 
82- Capture what was promised in the epic task description
83- Document what actually happened (expected vs actual)
84- If behavior doesn't match the promises, log the gap
85- Loop back to `plan-work` or `develop-tdd` to fix the gap
86- Re-verify until all gaps are closed (gaps count = 0)
87 
88## UAT dialogue
89 
90- Pass: user confirms per step.
91- Fail: capture expected vs actual; do not mark done in `execution-status.yaml`.
92 
93## Persist verification evidence
94 
95After UAT passes, write structured evidence to `specs/verifications/eNNsYY-verify.yaml`:
96 
97```yaml
98story_id: e01s01
99verified_at: "2026-06-11T14:30:00Z"
100verifier: verify-work
101phases:
102  smoke:
103    passed: true
104  build:
105    passed: true
106    command: "npm run build"
107  typecheck:
108    passed: true
109  lint:
110    passed: true
111  tests:
112    passed: true
113    coverage: "94.2%"
114  terminal_verdict:
115    command: "npm test"
116    exit_code: 0
117    captured_at: "2026-06-11T14:25:00Z"
118    note: "Single run — do not merge output from other attempts"
119  manual:
120    steps:
121      - step: "Open /login"
122        expected: "Login form renders"
123        actual: "Login form rendered correctly"
124        passed: true
125  gaps:
126    closed: true
127```
128 
129### 5b. OKF wiki LINT (e39s08)
130 
131```bash
132for p in specs/skills-wiki/skills/*.md; do s=&quot;skills/$(basename &quot;$p&quot; .md)/SKILL.md&quot;; [ -f &quot;$s&quot; ]&&[ &quot;$p&quot; -ot &quot;$s&quot; ]&&echo &quot;STALE: $p&quot;; done
133for p in specs/conventions-wiki/*.md; do [ &quot;$(basename &quot;$p&quot;)&quot; = &quot;index.md&quot; ]&&continue; grep -q &quot;$(basename &quot;$p&quot; .md)&quot; CONVENTIONS.md||echo &quot;ORPHAN: $p&quot;; done
134```
135 
136> **HARD GATE** — Verification evidence MUST be persisted before marking the story done. No evidence = not verified.
137 
138## --cli mode
139 
140CLI tools: use `--cli` when no server process. Binary detect + checklist: [REFERENCE.md](REFERENCE.md#cli-mode).
141 
142## Verify
143 
144→ verify: `find specs/verifications -maxdepth 1 -name '*-verify.yaml' 2>/dev/null | grep -q .`
145 
146## Handoff
147READY -> next: audit-code
148Writes: state.yaml handoff.next_skill = audit-code
149 
150---
151 
152# Verify Work — Reference
153 
154## Cold-start smoke
155 
156```bash
157# Example — adapt to project CLAUDE.md
158pkill -f &quot;&lt;dev-server&gt;&quot; 2&gt;/dev/null || true
159rm -rf .next/cache node_modules/.cache 2&gt;/dev/null || true
160&lt;run command&gt; &amp;
161sleep 3 && curl -sf http://localhost:&lt;port&gt;/health || echo &quot;BOOT FAIL&quot;
162```
163 
164## Gaps template
165 
166```markdown
167## Gaps (verify-work)
168 
169| Step | Expected | Actual | Status |
170|------|----------|--------|--------|
171| 1 | ... | ... | FAIL |
172```
173 
174Feed gaps to `plan-work` as new steps with verify commands, then re-run verify-work.
175 
176## CLI mode
177 
178For CLI tools where cold-start smoke does not apply. Auto-detected when no server process; or use `--cli`.
179 
180**Auto-detect binary name:**
181```bash
182BINARY=$(grep '^name' Cargo.toml | head -1 | awk -F'"' '{print $2}')  # Cargo
183BINARY=$(node -e &quot;console.log(require('./package.json').bin && Object.keys(require('./package.json').bin)[0] || '')&quot; 2&gt;/dev/null)
184BINARY=$(grep '^BIN\s*=' Makefile 2&gt;/dev/null | awk '{print $3}')
185```
186 
187**Checklist (replaces cold-start smoke):**
1881. `$BINARY --help` → output contains "Usage"
1892. `$BINARY --version` → matches manifest
1903. README example command → non-empty output
1914. `$BINARY --invalid-flag` → exit ≠ 0 with error message
192