wastebin-mcp-go/docs/agents/verification.md

64 lines
3 KiB
Markdown

# Verification
- Code changes must be verified with the narrowest meaningful build/test
commands before committing. Broaden verification for shared behavior, public
interfaces, test infrastructure, or CI changes.
- PR agents must run local verification before opening or updating a PR or
reporting the task complete. Choose the gate by the affected surface.
- Do not run the Go completion gate for changes that cannot affect Go code,
dependencies, build, test, lint, or release behavior. For example, pure
documentation changes should use narrow validation such as diff checks or
YAML parsing.
- If `golangci-lint` is unavailable, run `just vet` as the fallback static
check and state in the PR body that the linter itself could not be run.
- If a subagent made code changes, the coordinating agent must review and verify
those changes before committing.
- Never trust your own knowledge of version numbers, release dates, or
specification statuses. Time-sensitive external facts must be verified against
a current authoritative source before being stated as fact; if verification is
unavailable, avoid the claim or state the verification gap.
## Build and Test Commands
| Command | Scope |
|---------|-------|
| `just deps` | Verify and download dependencies |
| `just mod-tidy` | Check module files are tidy |
| `just build` | Build the canonical `wastebin-mcp-go` binary |
| `just test-cover` | CI-style test run with race detector and coverage |
| `just test-e2e` | E2E tests against a configured Wastebin server |
| `just vulncheck` | Known vulnerability scan |
| `just lint` | Lint; CI uses v2.12.2 |
| `just fmt-check` | Check formatting (gofumpt / goimports / gci) |
| `just vet` | Static analysis fallback |
| `just verify` | Full non-E2E verification gate |
## Completion Gate for AI Agents
Before any AI agent opens a PR, updates a PR, or reports a code-changing task
complete, it must run the gate that matches the touched surface.
For Go code, Go tests, Go dependencies, Go-related scripts, or workflow changes
that alter Go setup, Go commands, test/lint commands, or required environment
for Go execution, run:
- `just verify`
Run `just vulncheck` separately when the change affects the vulnerability scan
or release security gate; it is intentionally not part of `just verify`.
For MCP tool schema changes, also verify with a CLI mode test or manual MCP
inspection after the build gate.
For workflow-only changes that do not affect Go execution, use targeted
workflow validation instead of the Go completion gate. At minimum, inspect the
diff and run `git diff --check`; also run `actionlint` or a YAML parser when
available.
Pure documentation changes (`.md` files only) do not require the build, test,
lint, or vet gates.
If a required tool is unavailable, use the documented fallback when one exists
and state the exact limitation in the PR body or final response. If the missing
tool means the completion gate could not be run, do not claim the task is fully
verified.