autoreview

Auto Review

Run the bundled structured review helper only when the user explicitly asks for autoreview, a second-model review, or one of its named review engines. This is code review, not Guardian auto_review approval routing.

Codex review is the default when no engine is set. It uses gpt-5.6-sol with high reasoning by default, then retries once with gpt-5.6-terra only when the account cannot access Sol. Claude review is optional and uses claude-fable-5 by default. Amp review is optional and uses openai/gpt-5.6-sol with high reasoning by default. Pi and Kimi use the model configured by their respective CLIs unless --model overrides it.

Do not invoke Autoreview automatically before a commit, push, PR, merge, deploy, or final reply. Repository or workflow rules may call it only when they explicitly name it.

Contract

• Default accepted findings are P0 only: report issues worth blocking the current change because they materially break the normal flow, outcome, or safety boundary. Use --max-priority P1, P2, or P3 only when the caller explicitly asks for a wider review.
• Treat review output as advisory. Never blindly apply it.
• Verify every finding by reading the real code path and adjacent files.
• Read dependency docs/source/types when the finding depends on external behavior.
• Reject unrealistic edge cases, speculative risks, unrelated rewrites, and fixes that over-complicate the codebase.
• Prefer root-cause fixes at the right ownership boundary. A coherent refactor is appropriate when it removes the bug class, duplicate policy, stale paths, or ownership confusion; do not default to a symptom patch.
• When an accepted finding exposes a bug class or repeated pattern, inspect its owner and relevant sibling implementations before fixing.
• Fix the same bug class across its owner-boundary neighborhood when practical; stop at unrelated invariants, different owners, and unapproved contract changes.
• Run one bounded review pass. If an accepted finding changes code, run the smallest relevant test; rerun Autoreview only when the user explicitly requests another pass.
• For security-audit suppression changes, verify accepted findings remain auditable: suppressed findings stay in structured output, active output keeps an unsuppressible suppression notice, and aggregate findings cannot hide unrelated active risk.
• Never switch or override the requested review engine/model except for the documented Codex Sol-to-Terra account-access fallback. Capacity, rate-limit, and unrelated failures keep the same engine/model.
• Be patient with large bundles. Structured review can take up to 30 minutes while the model call is active, especially with Codex tools or web search.
• Treat heartbeat lines like review still running: ... elapsed=... pid=... as healthy progress, not a hang. Let the helper continue while heartbeats are advancing. Pass --stream-engine-output when live engine text is useful; Codex and Claude filter tool/file chatter, other runnable engines pass raw output through.
• Do not kill a review just because it has been quiet for 2-5 minutes, or because it is still running under the 30-minute window. Inspect the process only after missing multiple expected heartbeats, after 30 minutes, or after an obviously failed subprocess; prefer letting the same helper command finish.
• Tools are useful in review mode. Codex receives the validated bundle in an empty workspace so ignored files and linked-worktree metadata remain unreadable; web search stays available for dependency contracts and upstream docs.
• Security perspective is always included, but it should not cripple legitimate functionality. Report security findings only when the change creates a concrete, actionable risk or removes an important safety check.
• Reviewer subprocesses preserve engine authentication and non-credentialed proxy variables needed by headless or restricted-network environments while stripping process-injection, Git override, and credentialed proxy values.
• Immediately before every provider call, autoreview writes the exact outgoing review pack to an owner-only temporary file and scans it with TruffleHog using verified,unknown. It uses the installed binary with --no-update to disable self-update checks and attempts. The scan covers prompt and dataset inputs, untracked content, and every diff line, including deleted lines. A finding, scanner error, or missing TruffleHog binary refuses the send and names the implicated repository file when it can be resolved; credentials are never redacted and forwarded. Security-sensitive paths remain omitted. Safe large diffs are sent as one pass while they fit the aggregate prompt limit, then partitioned into complete bounded passes without truncation.
• Regression provenance needs patch proof, not blame alone. git log -S/-G, git blame, commit subjects, and PR metadata locate candidates. Before saying introduced by, inspect raw parents with git --no-replace-objects cat-file -p <sha> and verify the implicated behavior changed in git --no-replace-objects diff --no-ext-diff --no-textconv <raw-parent> <sha> -- <path>; a genuine root needs raw-header proof that it has no parents.
• Blame ^sha, porcelain boundary, and shallow/grafted history alone are not introduction proof. --root can hide boundary markers; git show or rev-list --parents can make a shallow boundary look like a root. An available raw parent permits explicit comparison even at a shallow boundary; missing parents or an unverifiable patch require unknown with the gap. Use carried forward only for verified preexisting behavior and made visible only for a verified trigger. Apply the same bar to finding prose, summaries, and owner hints.
• Keep code author, introducing PR author, merger, committer, automation trigger, and current PR author separate; none of those roles alone proves causation. Cite the verified commit/PR/date. If no PR is traceable, use the verified commit and known author identity; unknown identities stay unknown, and missing PR metadata is not a separate finding.
• For automation merges, identify the human trigger only from explicit timeline/comment/event evidence, such as a maintainer automerge command or arming label. Report automerge triggered by @login only when verified; otherwise say trigger unknown. Triggering or merging is not proof of authorship or introduction.
• Do not invoke built-in codex review, nested reviewers, or review panels from inside the review. The helper builds one validated bundle, calls the selected engine once for normal inputs or once per complete bounded chunk for oversized inputs, validates the structured results, and stops.
• Stop as soon as the helper exits 0 with no accepted/actionable findings. Do not run an extra review just to get a nicer "clean" line, a second opinion, or clearer closeout wording.
• Treat scoped-clean with exit 0 as clean only for the selected Git target and requested priority. filtered is not a correctness certificate; incomplete requires resolving the scope mismatch or missing required finding before claiming clean.
• If rejecting a finding as intentional/not worth fixing, add a brief inline code comment only when it explains a real invariant or ownership decision that future reviewers should know.
• If gh/Gitcrawl reports database disk image is malformed, run gitcrawl doctor --json once to let the portable cache repair before retrying review; do not bypass the shim unless repair fails and freshness requires live GitHub.
• If Gitcrawl reports a portable manifest mismatch, source/runtime DB health error, or stale portable-store checkout, run gitcrawl doctor --json and inspect source_db_health, runtime_db_health, and portable_store_status before falling back to live GitHub.
• Do not push just to review. Push only when the user requested push/ship/PR update.