agentleFS
kuhlman-labskuhlman-labs/fishhawk/.agents/skills/verify-gate/SKILL.md

verify-gate

Skill9 starsChanged 5 days agoApache-2.0View on GitHub

Run and interpret Fishhawk verification safely. Use before push/PR, or when asked to run verify, tests or the CI gate.

7 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Files
SKILL.md

Run the verify gate

scripts/verify-change is the repository committed-tree gate: path-aware frontend checks followed by scripts/test verify. Offline dependencies, exit 75, stage order and coverage contracts are owned by scripts/README.md and routed by the verification guide. Lint and static checks run before the test loop; scoped and no-tests runs do not establish a full pass. Avoid maintaining a second copy of the gate's leg list here.

1. Preflight — do all of these first

pgrep -fl '[f]ishhawk-runner .*--run-id' || echo no-live-runner
uptime; sysctl -n hw.ncpu
go env GOVERSION
scripts/check-gate-image --host
docker info >/dev/null 2>&1 && echo docker-ok || echo docker-DOWN
git status --short
  • Live runner. It may be holding the per-repository verify lock. A shell verify that meets a live holder refuses immediately. That refusal is final for that invocation: do NOT retry or poll it. Narrow to scripts/test single -run TestX ./path/to/pkg/... instead, or wait for the run to finish.
  • Load average above ~4× the core count. The host is starved, and unrelated tests will flake. Use the diagnose-red skill (orphaned agent processes) before running anything.
  • Toolchain mismatch. The host checker compares the exact lint version, its build Go and standalone gofmt with the checked-in gate-image pins. Treat host_toolchain_mismatch as environmental, never a reason to edit code. Put the matching tools first on PATH or use --in-gate-image. Read the current Go version from deploy/gate-image/Dockerfile; prefer a per-command toolchain/PATH change. Changing persistent go env -w settings needs authorization and does not switch standalone gofmt.
  • Postgres prerequisite. Host tests use Docker/testcontainers. A runner gate container instead uses its supplied FISHHAWK_TEST_PG_URL and has no Docker daemon; a missing or failing service there is a failure, never a skip.
  • Dirty tree. That's allowed: patch coverage diffs merge-base → work tree, so uncommitted edits are gated too.

2. Run

SituationCommand
Before a PR / final check (outside a run)scripts/verify-change
Inside a Fishhawk run (scripts/is-run-agent prints run-agent, i.e. FISHHAWK_RUN_AGENT is set) whose stage configures a verify gateFocused scripts/test single plus a scoped scripts/test verify --packages … only. The runner's committed-tree gate runs the full verify on the passing SHA; don't spend the agent budget repeating it (#5148). The marker only selects this workflow and never replaces the gate: with no configured gate, run the full verify yourself
Iterating on known packagesscripts/test verify --packages backend/internal/foo,runner/internal/bar (repo-relative). It skips patch coverage, so finish with a full run, which inside a run is the runner's gate
One testscripts/test single -run TestName ./backend/internal/foo/
Lint onlyscripts/test lint

A full verify takes many minutes. Run it in the background (or with your shell tool's longest timeout) and wait for it to exit. Don't start a second concurrent verify.

3. Read the result

FailureMeaning / fix
golangci-lint / gofmtFix the code; the matching pinned gofmt -w / goimports -w on the named files
Schema sync driftA docs/spec/ canonical file changed without mirroring it: run scripts/sync-schemas and commit the mirrors
Doc-line budgetA docs/ARCHITECTURE.md line is over 1000 chars; move the prose to the package README
check-adrRecord/index mismatch: scripts/check-adr --write-index (see the record-adr skill)
Site gates (check-site-voice, check-site-ia, site reference drift)Banned §5 term on the site, a sidebar/page mismatch, or a stale generated region (scripts/gen-site-reference)
TestKnownCategoriesCoversEmittedCategoriesA new audit category: register it in backend/internal/audit/categories.go
TestCrossModuleWireParityA cross-module wire struct drifted: see backend/internal/wirecontract/README.md
Patch coverage below 85%Add tests that exercise the changed lines. Never set FISHHAWK_SKIP_PATCH_COVERAGE to get a pass
A test unrelated to the diffLikely environmental (host load, toolchain, Docker): use the diagnose-red skill before touching code
host_toolchain_mismatchFix the tool environment or use the gate image; do not change code
Refused: verify lock heldSee preflight. Don't retry

A skipped harness (zsh or helm absent) is a printed skip, not a failure. Report it as an uncovered area.

4. Report

State pass/fail and the failed gate leg. If the test loop ran, report every failing module and its failing tests/build errors from the aggregate summary. Include the relevant diagnostics and every skip; distinguish scoped/no-tests evidence from a full pass.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.