review-gauntlet 0.1.0

Coverage-driven review gauntlet for agentic code reviews

Review Gauntlet

Coverage-driven review orchestration for agentic code reviews.

The goal is not to pretend an LLM can guarantee bug-free code. The goal is to guarantee that a defined review surface was inspected, with evidence, before a project is called reviewed.

Commands

uv sync
make check

Run the published CLI without installing it permanently:

uvx review-gauntlet --help

Install the local CLI as the canonical review-gauntlet command when you want to run it outside uv run:

make install
review-gauntlet --help

Shell completion

The installed review-gauntlet command can generate completion scripts for common interactive shells. Evaluate the script for the current session, or write it to the location your shell startup files load.

Bash:

source <(review-gauntlet completion bash)

Zsh:

review-gauntlet completion zsh > "${fpath[1]}/_review-gauntlet"
autoload -Uz compinit && compinit

Fish:

review-gauntlet completion fish > ~/.config/fish/completions/review-gauntlet.fish

Start normal use by initializing a review session, then run exactly one review step with a configured external CLI adapter:

uv run review-gauntlet init
uv run review-gauntlet review --config review-gauntlet.jsonc

Target selection happens on init; review only advances the active session once. A bare init now uses .review-gauntlet/checkpoints/latest/status.json when a complete usable checkpoint exists, reviewing from its review_base_commit to HEAD. If no checkpoint exists, bare init reviews all eligible files. Scripts that need the previous workspace-diff default must pass --worktree explicitly. OCR-compatible target mappings are:

# Default review: latest finalized checkpoint -> HEAD, or all files for first review.
uv run review-gauntlet init

# OCR workspace diff review: staged, unstaged, and untracked non-ignored files.
uv run review-gauntlet init --worktree

# OCR branch/range review: files changed between two refs.
uv run review-gauntlet init --from main --to HEAD

# OCR single-commit review: files changed by one commit.
uv run review-gauntlet init --commit <commit-oid>

# review-gauntlet-only full repository review: every eligible inventory file.
uv run review-gauntlet init --all

# Execute exactly one review step for the initialized session.
uv run review-gauntlet review --config review-gauntlet.jsonc

# Select at most 20 cells for this run and execute up to 4 adapter calls at once.
uv run review-gauntlet review --budget 20 --concurrency 4

After a review step, inspect session state and findings, optionally record human finding decisions, and finalize only when both coverage and findings are closed:

uv run review-gauntlet status
uv run review-gauntlet findings
uv run review-gauntlet mark <finding-id> fixed --reason "fixed in follow-up"
uv run review-gauntlet verify-fixes --config review-gauntlet.jsonc
uv run review-gauntlet finalize
# Finalize writes Git-reviewable JSON/Markdown snapshots atomically.
git add .review-gauntlet/checkpoints/latest

Successful finalize requires both coverage and live findings to be closed and review-universe files to match HEAD; dirty tracked, staged, unstaged, or untracked eligible files block checkpoint creation. It writes .review-gauntlet/checkpoints/latest/status.json, findings.json, events.json, and summary.md, then clears the active session so the next command is review-gauntlet init. There is intentionally no separate checkpoint command.

review --concurrency defaults to 8 and must be a positive integer. --budget still caps the total cells selected for one review run; --concurrency only limits how many of those selected adapter invocations run at the same time. It does not automatically pass a concurrency flag through to the nested external adapter command.

Diagnostic and legacy planning commands

The inventory, plan, and report commands remain available for compatibility and inspection. Use them to inspect file discovery, review slicing, and report rendering; they are not the normal day-to-day review lifecycle.

Inspect the current repository inventory and classification:

uv run review-gauntlet inventory

Inspect the legacy review plan with slices and required checks:

uv run review-gauntlet plan

Render the legacy markdown matrix report:

uv run review-gauntlet report

Default file filtering

Inventory discovery keeps Git behavior intact: Git-backed repositories still use git ls-files --cached --others --exclude-standard with the existing bounded subprocess timeout, so .gitignore and other exclude-standard rules apply before review-gauntlet's built-in filters.

The built-in artifact filter removes generated or dependency paths from both full inventory and target-scoped inventory. This includes Python/editor/cache outputs such as .review-gauntlet/, __pycache__/, .ruff_cache/, build/, dist/, wheels/, htmlcov/, and OCR-inspired dependency/build staging paths such as vendor/, node_modules/, target/, .happypack/, .cachefile/, _packages/, rpm/, pkgs/, and oh_modules/.

Review sessions apply an additional default review-path filter when creating cells and digests. Files can remain classifiable in general inventory, but init omits openspec/, tests/, and docs/ by default, as well as common OCR-style test or generated paths such as __tests__/, *_test.go, *Test.java, *Test.kt, *.spec.ts, *.test.tsx, test_*.py, *_spec.rb, *.spec.ets, and *.test.ets. Review cells and target digests also omit common package manifests and lock files such as uv.lock, poetry.lock, requirements*.txt, package.json, package-lock.json, yarn.lock, pnpm-lock.yaml, Cargo.toml, Cargo.lock, go.mod, go.sum, pom.xml, Gemfile.lock, composer.lock, Package.resolved, pubspec.lock, mix.lock, vcpkg.json, flake.lock, stack.yaml.lock, Manifest.toml, and renv.lock. These package files are not removed from general inventory unless another artifact or Git ignore rule excludes them. Normal source files and package-adjacent executable logic files such as setup.py, build.gradle, mix.exs, and build.zig remain eligible for review cells.

review discovers configuration in this order: explicit --config, .review-gauntlet/config.jsonc, .review-gauntlet/config.json, review-gauntlet.jsonc, review-gauntlet.json, $XDG_CONFIG_HOME/review-gauntlet/config.jsonc, then $XDG_CONFIG_HOME/review-gauntlet/config.json. When XDG_CONFIG_HOME is unset or empty, the global fallback base is ~/.config, so the JSONC fallback path is ~/.config/review-gauntlet/config.jsonc. Repository-local configuration always wins over global XDG configuration, and discovery only reads existing files; it never creates global config directories or files. The command adapter uses argv arrays and never shell strings; provider login, model choice, and secrets stay inside the external CLI configuration.

Minimal JSONC configuration for opencode file-json verdicts:

{
  "adapter": {
    "type": "command",
    "command": "opencode",
    "args": ["run", "--dangerously-skip-permissions", "{prompt}"],
    "output": {"mode": "file-json", "path": "{output_file}"}
  }
}

The generated OCR prompt is expanded into {prompt} as one argv element. Prompt artifacts are still written for audit evidence, but prompt-file transport is not part of the command adapter contract. cwd, env, and timeout_seconds are optional escape hatches: omitted cwd inherits the caller's current working directory, omitted env inherits the parent environment without fixed automatic variables, explicit env values override that inherited environment, and omitted timeout_seconds defaults to 600 seconds.

The verdict must be JSON with OCR-style comments:

{"comments":[{"path":"src/app.py","content":"Issue","start_line":1,"end_line":1}]}

Supported template variables include {repo_root}, {state_dir}, {run_id}, {run_dir}, {cell_id}, {cell_dir}, {prompt}, {output_file}, {file_path}, and {rule_id}.

Developer Workflow

make format
make lint
make typecheck
make test
make coverage

Design

Review Gauntlet treats review as a stateful coverage workflow:

• initialize a session from an explicit target set
• classify eligible files into review slices and coverage cells
• run exactly one review step at a time through an external command adapter
• record prompts, outputs, findings, and coverage state as audit evidence
• finalize only after required coverage and live findings are closed

External review tools are integrated through the command adapter rather than hard-coded runners. The adapter accepts argv arrays, expands review artifacts into safe template variables, and supports JSON verdicts written to stdout or files so CLIs such as opencode, Codex-style tools, static analyzers, or custom wrappers can participate without review-gauntlet owning provider login or secret management.