Imported from 0xjgv/harness (go/AGENTS.md). Install upstream with npx skills add 0xjgv/harness --skill go. Copyright stays with the author.

CLAUDE

Commands

• After edits: go run harness.go check — fix, format, lint, test, suppression ratchet
• Pre-commit: go run harness.go pre-commit — arch config guard warns first, even on an arch-config-only commit with no other staged Go files; then fix/format over the staged packages (auto via git hook). A staged CLAUDE.md is copied to AGENTS.md and staged with it; a hand edit to AGENTS.md alone fails. Arch config changes warn here, they do not fail. Tests run at pre-push.
• Pre-push: go run harness.go pre-push — branch guard runs first and short-circuits (refuses pushes to main/master unless HARNESS_ALLOW_PROTECTED_PUSH=1, printing only the refusal and exiting before anything else runs); then the test suite (without git's GIT_* hook variables, since tests create temp git repos; a failure stops the push); then a read-only push gate over the whole tree: lint (golangci-lint covers format), acceptance, arch run in parallel, then agents-md drift as a separate hard check after that batch (the offline checks pre-commit and stop-hook skip). Auto via git pre-push hook.
• CI: go run harness.go ci — read-only gates (lint, audit, complexity, acceptance, arch) run in parallel — captured, printed in submission order, run to completion — then agents-md drift as a separate hard check, then test-cov (streams) + crap. CRAP is advisory (warns only — pass --enforce to hard-fail). Requires uvx on PATH.
• Complexity: go run harness.go complexity — lizard@1.22.2 CC gate (CCN≤15, args≤8, length≤100) over the module
• Deadcode: no separate target — golangci-lint's unused linter (run by lint/ci, and by stop-hook on changed lines) already flags unreachable functions, vars, and types, and go mod tidy prunes unused dependencies. (x/tools/cmd/deadcode needs a main package; this template is a library.)
• Audit: go run harness.go audit — audit dependencies for known vulnerabilities (via govulncheck)
• Acceptance: go run harness.go acceptance — run godog against features/
• Coverage: go run harness.go coverage (alias: test-cov) — tests with race detector + coverage.out; default threshold comes from .harness-baseline coverage.min
• Mutation (advisory): go run harness.go mutation — gremlins kill-rate on ./suppressions
• CRAP (advisory): go run harness.go crap --max=30 — complexity × coverage gate. Add --enforce to exit 1 on offenders (default exits 0 with warning).
• Suppressions: go run harness.go suppressions — full suppression breakdown; --update-baseline requires human sign-off and updates .harness-baseline
• Arch: go run harness.go arch — go-arch-lint against .go-arch-lint.yml
• Branch guard: go run harness.go branch-guard — refuses pushes to (or deletions of) main/master; reads HARNESS_PRE_PUSH_REFS, else git pre-push stdin (1s deadline; partial input fails), else the current branch; HARNESS_ALLOW_PROTECTED_PUSH=1 overrides
• Arch config guard: go run harness.go arch-config-guard — unreviewed .go-arch-lint.yml changes warn in check/pre-commit, block pre-push/CI; use HARNESS_ALLOW_ARCH_CONFIG=1 after review
• Agents drift: go run harness.go agents-md-drift — fail if AGENTS.md differs from CLAUDE.md
• Sync: go run harness.go sync-agents-md — overwrite AGENTS.md from CLAUDE.md
• Setup: go run harness.go setup-hooks installs git pre-commit + pre-push hooks (path resolved via git rev-parse, worktree-safe) and idempotently installs the Claude/Codex Stop wiring; the Claude PostToolUse wiring ships in .claude/settings.json, and check warns when either is missing
• Stop hook: go run harness.go stop-hook — post-edit, then lint on changed lines and lizard limits on the functions the change touches; silent on success, exit 2 with findings on stderr (at most 20 lines). Changed lines = git diff against the merge-base with the base branch (HARNESS_ARCH_BASE, GITHUB_BASE_REF, origin/HEAD, origin/main, origin/master, main, master; never fetched) plus untracked files. Touching an over-limit function blocks, so leave what you touch better; untouched debt never blocks. Compile errors always block. Exit 1: a tool could not run, or this stop already blocked once (stop_hook_active). The hooks run go build -o harness harness.go && ./harness stop-hook, because go run turns exit 2 into 1. An uncommitted CLAUDE.md edit is copied to AGENTS.md.
• Post-edit: go run harness.go post-edit — golangci-lint fmt on Go files with uncommitted changes, then golangci-lint run --fix --new-from-rev=HEAD over their packages only. --hook (Claude PostToolUse) does this for the edited file and, if it changed, asks the agent to re-read it; it never blocks.

Definition of done

• go run harness.go check passes clean — never stop with check failing.
• Behavior worth specifying → a .feature scenario exists and acceptance passes; other behavior changes have unit tests.
• No new suppressions: additions above .harness-baseline fail check; suppress only with the human's sign-off, stating why.
• Arch config changes are integration-blocked: check/pre-commit warn, and pre-push/ci fail unless HARNESS_ALLOW_ARCH_CONFIG=1 is set after review.
• pre-push/ci must pass on your branch before you open or update a PR. Merge is the human's.
• Never spend a turn on what a tool checks: formatting, lint, types, dead code, drift, and complexity come back as check/stop-hook output. Read the output, fix the code, never the gate.

Behavior contract

• The human is the engineer. They own design, API shape, and merge authority. You propose on a branch, they merge.
• Commit and push on a feature branch as you go. Never commit to main/master, never force-push, never merge. pre-push refuses direct pushes to main/master unless a human sets HARNESS_ALLOW_PROTECTED_PUSH=1; that guard stops accidents, not --no-verify, so merge ownership is a rule you follow, not one the tool can enforce.