---
name: verify-gate
description: "Runs project compile, test, and lint commands between implementation and quality review. Gates simplify-and-harden behind machine verification. If checks fail, enters a fix loop with diagnostics. If checks pass, signals ready for quality pass. Use after any implementation work completes and before signaling done. Essential for the inner loop's verify step."
---

# Verify Gate

Machine verification gate between implementation and quality review. Runs the project's compile, test, and lint commands. If any fail, enters a fix loop. If all pass, unblocks the quality pass.

This is the inner loop's **verify** step. Without it, the agent hands off code with zero machine signal about whether it actually works.

## When to Use

- After any implementation work completes, before signaling "done"
- Before running simplify-and-harden or quality review
- After fixing audit findings from code review
- Any time you want a machine-verified green signal

## Pipeline Position

```
[implementation] → verify-gate → [quality review / simplify-and-harden]
                   ↻ fix loop — on failure, diagnose and retry
```

## Step 1: Discover Project Commands

Read the project's configuration to find verification commands. Check these sources in order:

1. **Project instruction files** (`CLAUDE.md`, `data/AGENTS.md`) — look for a `## Verification` or `## Test Commands` section
2. **package.json** — `scripts.test`, `scripts.lint`, `scripts.typecheck`, `scripts.build`. BooCode uses pnpm, so prefer `pnpm run <script>` when `pnpm-lock.yaml` is present.
3. **Makefile** / **Justfile** — `test`, `lint`, `check`, `build` targets
4. **Cargo.toml** — `cargo build`, `cargo test`, `cargo clippy`
5. **pyproject.toml** / **setup.cfg** — `pytest`, `mypy`, `ruff`
6. **go.mod** — `go build ./...`, `go test ./...`, `go vet ./...`
7. **deno.json** / **deno.jsonc** — `deno task <name>` for any defined tasks

If no commands are discoverable, ask the user once and suggest they add a `## Verification` section to `CLAUDE.md` for future sessions:

```markdown
## Verification

- Build: `pnpm run build`
- Test: `pnpm test`
- Lint: `pnpm run lint`
- Type check: `npx tsc -p apps/server/tsconfig.json --noEmit`
```

## Step 2: Run Verification

Run discovered commands in this order. Stop at the first failure category.

### Phase 1: Compile / Type Check
Run the build or type-check command. These catch structural errors before wasting time on tests.

```
Exit 0 → proceed to Phase 2
Exit non-zero → enter fix loop with compiler output
```

### Phase 2: Tests
Run the test command. Scope to changed files if the test runner supports it.

```
Exit 0 → proceed to Phase 3
Exit non-zero → enter fix loop with test output
```

### Phase 3: Lint (optional, skippable with --skip-lint)
Run the lint command. Lint failures are lower severity but still worth catching.

```
Exit 0 → all phases green, gate passes
Exit non-zero → enter fix loop with lint output
```

## Step 3: Fix Loop

When a phase fails:

1. **Read the output.** Parse the error output for actionable diagnostics — file paths, line numbers, error messages.
2. **Scope the fix.** Only fix what the verification caught. Do not refactor, improve, or touch unrelated code.
3. **Apply the fix.** Make the minimal change to resolve the failure.
4. **Re-run the failed phase.** Not all phases — just the one that failed.
5. **If it passes**, continue to the next phase.
6. **If it fails again**, increment the attempt counter.

### Fix Loop Limits

- **Default max attempts:** 3 per phase (configurable via `--fix-limit N`)
- **Counter increments on every attempt**, even if the error changes. Fixing Error A and uncovering Error B counts as attempt 2, not attempt 1. The counter tracks fix attempts, not unique errors.
- **If limit reached:** Stop. Report what failed, what was tried, and the remaining error output. Do not guess further — signal to the user that manual intervention is needed.
- **Total budget:** The fix loop should not exceed 20% of the original implementation effort. If fixes are snowballing, stop and report.

## Step 4: Gate Signal

When all phases pass:

```markdown
## Verify Gate: PASSED

- Build: passed
- Tests: passed (N tests, M suites)
- Lint: passed (or skipped)

Ready for quality review.
```

When the fix loop is exhausted:

```markdown
## Verify Gate: BLOCKED

- Build: passed
- Tests: FAILED (attempt 3/3)
  - [file:line] error description
  - [file:line] error description
- Lint: not reached

Fix loop exhausted. Manual intervention needed before quality review.
```

## Integration with Other Skills

### boocode simplify-and-harden / quality review
verify-gate should gate any quality pass. Run verify-gate first; only proceed to review if the gate passes.

### self-healing (if available)
On any failure during the verify run, consider handing the diagnostics to a self-healing loop (diagnose → patch → verify → persist). Verify-gate then re-runs the checks. Up to 3 heal attempts per phase before abandoning.

### self-improvement
If a recurring error pattern emerges across verify runs, capture it in `CLAUDE.md` or as a new skill under `data/skills/boocode/` so future verify-gate runs don't rediscover the same fix.

## What This Skill Does NOT Do

- Does not review code quality (that's a separate review pass)
- Does not check security
- Does not verify spec compliance
- Does not modify test files or add new tests
- Does not run tests for code it didn't change (unless the test runner doesn't support scoping)

## Configuration

If the project has a `verify-gate` section in `CLAUDE.md` or `data/AGENTS.md`:

```yaml
## Verify Gate Config

build: pnpm run build
test: pnpm test
lint: pnpm run lint
type_check: npx tsc -p apps/server/tsconfig.json --noEmit
fix_limit: 3
skip_lint: false
test_scope: changed  # changed | all
```

If no configuration exists, discover commands automatically (Step 1) and suggest persisting them.

### Custom Verification Steps

Projects with custom invariants can define additional verification phases. These run as extra phases after the standard compile/test/lint checks.

Example — a project that needs API schema validation:

```yaml
## Verify Gate Config

custom_checks:
  - name: validate-schema
    command: python scripts/validate_schema.py --strict
  - name: check-no-legacy-imports
    command: grep -r "from legacy" src/ --include="*.py" && exit 1 || exit 0
```

When custom checks are defined, verify-gate runs them as **Phase 4** after lint. Each check's exit code determines pass/fail. Failed checks enter the same fix loop as standard phases.

This moves project-specific invariants from "knowledge in your head" to "knowledge in the harness" — exactly where the agent can reach it.
