| name | validate |
| description | Pick the right verification ladder for a change - unit tests, sanitizers, validation suite, integration tests, fuzzing, lint - and emit exact Deferred Gate commands. Use before merging, when the user asks "how do I verify this", or when preparing the developer's Docker test checklist. |
| argument-hint | ["change-description"] |
VERIFICATION PLAN
Change under test: $ARGUMENTS
This sandbox is static analysis only — none of these commands run here. This skill's output is a Deferred Gate list: the exact commands for the developer's Docker container / rig, in order, with expected pass output. Never claim a gate passed; claim it was emitted.
THE LADDER (cheapest first — stop emitting once coverage is sufficient for the change)
| Rung | Command | Catches | When required |
|---|
| 1. Async lint | ./scripts/lint-seastar-async.sh | Unmarked seastar::async( call sites (Rule #12 — it does NOT offload to a thread pool) | Any change adding/near seastar::async; cheap enough to always run |
| 2. Unit tests | make test-unit | Logic regressions in reactor-free components | Every change |
| 3. Sanitized units | make sanitize-test | UAF, buffer overflows, UB (ASan/UBSan, clang; Dockerfile.sanitize image; 60s/test timeout) | Lifetime-sensitive changes: gates, timers, buffers, cross-shard, FFI |
| 4. Validation suite | make validate (full) / make validate-quick / make validate-ci | The four architecture invariants: zero reactor stalls, disk-I/O decoupling (P99 < 10% degradation under stress), no SMP queue overflow, atomic-free RadixTree. Single target: ./validation/validate_v1.sh --test stall etc. | Hot-path, persistence, gossip, or routing-core changes |
| 5. Integration | make test-integration (multi-node Docker Compose; -fast/-full/-ci variants; make integration-up/-down/-logs) | Cluster behavior: graceful shutdown, peer discovery, prefix routing, streaming, negative paths | Anything touching HTTP surface, gossip, discovery, persistence recovery |
| 6. Fuzzing | make fuzz-ci (short) or make fuzz-run-radix-tree / -request-rewriter / -stream-parser (FUZZ_TIME=600 to override) | Parser crashes on malicious input (libFuzzer + ASan/UBSan; Dockerfile.fuzz image) | Changes to radix tree, request rewriter, stream parser, or any new parser of untrusted bytes |
| 7. Benchmark | see /benchmark | Performance regressions (TTFT, cache-hit) | Routing-decision or hot-path changes |
| 8. Deploy checks | make helm-lint, make helm-template | Chart validity | Helm/deploy changes |
Also available: make lint (clang-tidy; needs build/compile_commands.json), make format (clang-format over src+tests).
Gotcha: make fuzz-run-stream-parser requires the default-allocator base image (Dockerfile.base.default-alloc) — on the production base image, Seastar's per-shard allocator crashes libFuzzer with munmap_chunk: invalid pointer. The Makefile detects this and prints the unblock recipe; see tests/fuzz/README.md.
New parser of untrusted input? Adding a fuzz harness (tests/fuzz/<name>_fuzz.cpp, wired into fuzz_harnesses) is part of the change, not a follow-up. Untrusted surfaces today: HTTP bodies, gossip packets, KV-event msgpack, Prometheus scrape text, EPP gRPC.
MAPPING FAILURES BACK
| Failure signature | First suspect | Next step |
|---|
| ASan use-after-free in callback/timer | Gate holder scope (Rule #5), lambda coroutine (Rule #16), do_with copy (Rule #20) | /debug-build |
| Reactor stall detected (validation test 1) | Blocking call or unyielding loop (Rules #12, #17) | /debug-build, check lint rung 1 |
| P99 collapse under disk stress (test 2) | Persistence work leaked onto reactor | docs/internals/async-persistence.md |
| Atomics found in RadixTree (test 4) | std::shared_ptr/atomic crept into tree path (Rule #0) | /review the diff |
| Fuzz crash | Parser edge case | Minimize with libFuzzer, fix, keep the corpus file |
OUTPUT FORMAT
Deferred Gates for this change
# In the dev Docker container, in order:
./scripts/lint-seastar-async.sh # expect: "lint passed", exit 0
make test-unit # expect: 100% tests passed
make sanitize-test # expect: 100% tests passed, no sanitizer reports
...
For each rung: why it's included (which risk in this change it covers) or why it's skipped. If the developer reports a failure, triage with /debug-build.
