01. The AI Coding Reality: Scalability vs. Security Invariants
Autonomous programming agents (such as Claude Code, Codex, and Cursor) generate software artifacts at a velocity exceeding any engineering team's manual cognitive bandwidth. Reading every single generated line does not scale; reading nothing introduces critical vulnerabilities into production codebases.
Directly inspired by Anthropic's architectural report “How the Claude Code team does code review” (October 2026), review-harness implements a tiered inspection pipeline engineered for resource efficiency:
- Zero-Cost Precedence: Free, deterministic checks (unit tests, static credential scanners, and path diff inspections) execute first. Costly LLM tokens are never consumed on broken or invalid diffs.
- Budget-Bounded AI Invocations: AI review runs strictly on medium- and high-risk PRs with rigid token budgets and a hard ceiling of 3 iterative rounds per PR.
- Hallucination Pruning: Findings referencing code coordinates outside the actual pull request diff are discarded in memory before posting to GitHub.
02. Architectural Pipeline: The 3-State Verdict Matrix
Every inspected pull request converges onto one of three unambiguous outcomes, eliminating ambiguity for human maintainers:
| Verdict | Execution Meaning | Action Required |
|---|---|---|
| PASS | All test suites passed, zero credentials leaked, and only low-risk peripheral files modified. | Merge allowed |
| NEEDS HUMAN | All verification tests passed, but the diff touches sensitive areas (auth, payments, secrets, CI rules). | Human peer review required |
| FAIL | Unit/integration tests failed, CVE detected in dependencies, or plaintext secret identified by Gitleaks. | Blocked from merging |
“An AI agent can flag potential architectural defects, but it must never be granted authority to approve a PR. Verification invariants belong to deterministic static checks and human security engineers.”— Vinicius Pontual, review-harness Design Philosophy
03. Five-Stage Pipeline: Tiered Execution Lifecycle
The engine processes changes in strict serial priority to protect computing budgets and developer time:
// 01: Test Suite VerificationExecutes user-defined test commands (cargo test, npm test, pytest). Without clean execution, a PR can never receive a “Pass” status.
// 02: Path-Based Risk TieringEvaluates file path glob patterns against user-specified sensitive directories (e.g., authentication modules, payment gateways, CI configs, env files).
// 03: Static Security AuditingExecutes native gitleaks to detect exposed private keys, bearer tokens, and secrets, paired with cargo-audit to flag vulnerable supply chain dependencies.
// 04: Budget-Capped LLM Inspection (Optional)Queries Gemini, Claude, or Groq backends strictly over changed lines of medium/high-risk PRs. Hallucinated line references are automatically stripped.
// 05: Atomic Verdict CommentPublishes a single, structured Markdown status comment directly on the GitHub pull request containing itemized execution breakdowns.
04. Zero-Trust Security Guarantees & Branch Protection
Traditional CI actions often introduce supply chain risks where untrusted pull requests tamper with evaluation scripts or exfiltrate environment secrets. review-harness implements strict isolation defenses:
.review-harness.toml) is read strictly from the target main branch, never from the PR branch. A pull request cannot modify its own verification rules.contents: read and pull-requests: write permissions, prohibiting unauthorized repository alterations.05. Workflow & Project Configuration
Integrating the harness into any GitHub repository requires two declarative files:
// 1. .github/workflows/review-harness.yml
name: review-harness
on:
pull_request:
types: [opened, synchronize, reopened]
permissions:
contents: read
pull-requests: write
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
persist-credentials: false
- uses: Vinisilva0010/review-harness@main
with:
base-sha: ${{ github.event.pull_request.base.sha }}
head-sha: ${{ github.event.pull_request.head.sha }}
pr-number: ${{ github.event.pull_request.number }}
// 2. .review-harness.toml (Root of Project)
[verify]
checks = [
{ name = "test", command = "cargo test --all" },
]
[risk]
high = [".github/workflows/**", "**/*auth*/**", "**/.env*"]
[review]
provider = "none" # Toggle "gemini" / "anthropic" / "openai"
06. Specifications & CLI Toolchain
Technical specifications and local developer tooling:
| Component | Specification / Dependency |
|---|---|
| Core Implementation | Rust 1.98.1+ / Tokio Runtime |
| Security Scanners | Gitleaks 8.x + cargo-audit (RustSec Advisory Database) |
| Supported LLM Providers | Google Gemini, Anthropic Claude, OpenAI / Groq |
| CI Platform | GitHub Actions (Ubuntu x86_64 runner) |
cargo install --git https://github.com/Vinisilva0010/review-harness harness-cli --lockedreview-harness init && review-harness --help