git:20261010.38b67bc to git:20261012.cea3040

- Run an independent review when the user or an owning workflow asks for one.

- This is code review, not Guardian approval routing. Let the reviewer choose how

- to analyze the change; provide the target, relevant context, and desired severity.

- Findings are advice to verify, not instructions to apply blindly.

- Weigh every finding by likelihood, impact, and fix complexity. Fix what is

- real and likely, or rare but dangerous (data loss, security, money). Skip rare,

- recoverable edge cases and theoretical timing races whose fix adds

- disproportionate complexity, and state the accepted tradeoff instead.

-

- Before starting a review, read the complete [diagnostic and result guidance](references/diagnostics-and-results.md). It is part of this skill; follow its

- output-path, status, failure, usage, and diagnostic rules.

- Use `scripts/autoreview` beside this skill. Keep its custom `codex exec` path:

- native `codex review` cannot combine explicit Git target flags with custom instructions.

- The helper combines those with evidence, severity filtering, and validated JSON;

- it leaves review judgment to Codex. Install this skill once with the canonical

- repository's `python3 scripts/install-skills autoreview`. The default installation

- at `~/.agents/skills/autoreview` links to this source checkout.

-

- Run from the repository being reviewed:

- python3 "$AUTOREVIEW" --mode local

- In the canonical agent-skills repo, the path is

- `skills/autoreview/scripts/autoreview`. Use the selected installation path when

- installed with `--target`. On Windows, invoke the helper with Python 3.10 or newer,

- or use the adjacent `autoreview.ps1` launcher.

- Use `--help` for the complete flags and environment overrides.

-

- Repositories keep only the [shared-skill entrypoint](references/repository-entrypoint.md).

- Read this full skill and its required references from the shared installation.

- Keep repository-specific thresholds and review requirements in the consumer's

- instructions. Upstream changes to shared behavior here.

-

- Update the canonical checkout once to update every symlinked consumer. Finish

- active reviews before updating their helper. Copy-mode installations require

- re-running `scripts/install-skills --mode copy --force autoreview` after updating

- the source checkout. Review commands never download or update themselves.

-

- Choose the Git target explicitly when the default is ambiguous:

- | Target | Arguments | Scope |

- | ------------------------------ | ------------------------------ | ----------------------------------------------------------- |

- | Local work | `--mode local` | HEAD → index → working tree, plus untracked files |

- | Local candidate against a base | `--mode local --base <ref>` | Pinned base → index → working tree, plus untracked files |

- | Committed branch/PR | `--mode branch --base <ref>` | Merge-base → HEAD; excludes dirty work |

- | One commit | `--mode commit --commit <ref>` | Raw parent → commit; a root compares against the empty tree |

- `--mode auto` selects local work when dirty, otherwise a branch review using the

- PR base or `origin/main`. Clean main has no implicit review target.

- `--mode uncommitted` is an alias for local. The helper does not fetch refs.

- Registered nested linked checkouts from the same repository are outside the

- current review scope. Their presence or edits do not make the parent dirty;

- ordinary adjacent files remain included in the review. Worktree boundaries are

- revalidated without changing Git ignore rules.

- For a complete PR candidate **including dirty rewrites**, use local mode with

- its pinned merge base—not branch mode:

- "$AUTOREVIEW" --mode local --base "$merge_base"

- When a file has both staged and unstaged changes, both states are reviewed.

- A defect in the index remains actionable even if the working tree fixes it;

- the report labels it `INDEX-only`.

- Git display settings cannot suppress context markers or add patch colors;

- repository configuration is not changed. Source paths and text retain literal

- whitespace. An empty present

- source uses line 1, column 1, and an empty excerpt; empty physical lines also

- use an empty excerpt at column 1. Source identity remains mandatory.

-

- Binary deletions remain in scope as Git deletion metadata; their former contents

- are not included or reviewed. Each local transition is checked independently:

- deleting a file in the working tree cannot hide a staged binary change.

-

- Finding locations may use native absolute paths that resolve inside the reviewed

- repository; these become repository-relative paths before scope and attribution

- checks, preserving a changed symlink's path when its target is also inside.

- Parent traversal and paths resolving outside the repository remain invalid.

- An invalid location still fails the report; findings are never silently dropped.

-

- Local selection honors `core.autocrlf` from external operator Git configuration,

- with repository-local values and attributes retaining precedence. Only its

- validated scalar value reaches diff/status; other global and system Git

- configuration stays disabled. Repository-owned or relative global-config

- overrides are not imported, and reviewed source bytes are not rewritten.

-

- Local collection disables effective Git clean/process commands and requires

- conversion to succeed. Unused drivers, unchanged filtered neighbors, staged-only

- changes, and deletions can still be reviewed without executing converters.

- If Git needs executable conversion to assemble the diff, collection fails before

- any reviewer starts. This can include an unchanged filtered file whose stat cache

- needs refreshing. Use explicit branch or commit mode for committed content in

- that case. Built-in line-ending normalization remains enabled; raw bytes never

- stand in for a required executable conversion.

- PR-base discovery uses trusted external Git and a scoped GitHub CLI environment,

- preserving external authentication/configuration and proxy settings while excluding

- inherited Git routing, `GH_REPO` redirection, and checkout-owned executables.

- A differently named `AUTOREVIEW_GIT` override that cannot also be selected as `git`

- by the child requires an explicit `--base`; rejected GitHub configuration paths

- also require one.

- Use `--prompt` for task-specific guidance, or `--prompt-file` and `--dataset` for

- repository-relative context files. Context does not expand the selected Git

- target. The reviewer cannot read unchanged repository files from its empty

- sandbox; supply relevant source or dependency evidence when the diff is insufficient.

- `--prompt-file` also accepts an absolute path inside the repository; the same

- sensitive-path, symlink, and mutation checks apply. `--dataset` stays repo-relative.

- Repeated paths in the same evidence role share one validated capture. Equal

- content at different paths and prompt-file versus dataset roles stay distinct.

-

- For unchanged committed source, use repeatable `--source-context <repo-relative-path>`

- with branch or commit mode. Use `--source-context-file <repo-relative-path>` when

- that source must stay intact in every review pass. Both read the exact regular-file

- blob from the frozen reviewed commit (branch HEAD or `--commit`), including executable source files.

- Local mode, including an auto-selected local target, is unsupported. No separate

- context revision or working-copy substitution is accepted. The checkout path must

- remain a regular file; its bytes and path topology are revalidated throughout review.

- Repeated normalized source-context paths share one capture after every argument

- is validated; different paths and evidence roles remain distinct.

-

- Both roles use tracked-source filename classification, so source names such as

- `src/token_count.py` are accepted. Credential directories, stores and keyfiles

- remain forbidden. Existing prompt-file and dataset restrictions are unchanged.

- Every source block carries path, commit, blob and mode provenance. `--source-context`

- bytes are partitioned with the change when needed. `--source-context-file` blocks

- stay complete in every pass and must fit with the instructions and change framing;

- the helper refuses an over-capacity plan without dropping required evidence.

- Context never adds finding targets or instruction authority. This is a

- source-provenance contract, not secret-content scanning.

-

- ```bash

- "$AUTOREVIEW" --mode branch --base origin/main --source-context src/token_count.py

- "$AUTOREVIEW" --mode branch --base origin/main --source-context-file src/token_count.py

- ```

- The default threshold is **P0 only**: material blockers to normal operation or

- safety. Use `--max-priority P1`, `P2`, or `P3` when the caller requests a wider

- review. `AUTOREVIEW_MAX_PRIORITY` accepts the same `P0`–`P3` values; an explicit

- flag overrides it. Invalid resolved priorities fail during argument parsing,

- before preparation or reviewer startup.

- Do not add unrelated redesign goals or prescribe file counts, reading

- sequences, or ritual extra passes. Historical blame requires a verified

- parent-relative patch; otherwise leave the attribution unknown.

- ```bash

- "$AUTOREVIEW" --mode local --prompt-file review-notes.md --dataset evidence.json

- ```

- For automatic reviewer selection, try OpenAI models through Codex before Claude.

- Start with `--engine codex` even when the invoking agent uses Codex or asks for

- an independent second opinion. Use Claude only when the user explicitly selects

- it or Codex is unavailable for the review; report the concrete availability failure

- before switching. Do not switch because a review is slow, rate-limited, or returns

- findings, or to bypass a safety refusal or isolation failure.

-

- Codex defaults to `gpt-6.1-sol`, high reasoning, with a single `gpt-6-sol` retry

- only for an account-access failure. Explicit `gpt-6.1-sol` selections use the same

- retry. Explicit `gpt-6-sol` selections retain their access-only `gpt-6-luna` retry;

- other explicit models, including Luna and Astra, have no model fallback.

- Explicit `gpt-5.6-sol` selections retain their access-only `gpt-5.6-terra` retry.

- GPT-6.1 Sol rejects `none` and `minimal` effort before review preparation;

- GPT-6 Sol and Luna reject `minimal`. An effort-only override keeps the default model.

- Honor explicit user engine/model choices.

- The helper does not automatically fall back between engines.

-

- Use `--engine`, `--model`, and `--thinking` to override the defaults.

- `--codex-speed fast` selects priority service when supported; `--codex-speed ultrafast`

- selects Ultrafast when the active model catalog lists it (Codex otherwise silently

- sends the standard tier). Only Claude accepts

- `--fallback-model`. Per-engine environment overrides use `AUTOREVIEW_<ENGINE>_*`.

-

- If your account cannot access Sol or Luna, pin an available model. To require

- GPT-6 Astra without a model fallback, select it explicitly:

-

- ```bash

- "$AUTOREVIEW" --mode local --model gpt-6-astra --thinking high

- ```

-

- GPT-6.1 Sol and GPT-6 Astra support `low`, `medium`, `high`, `xhigh`, and `max`;

- neither supports `none` or `minimal`. GPT-6 Sol and Luna additionally support `none`,

- but not `minimal`. AutoReview defaults to

- `high` and does not fall back from an explicit Luna or Astra selection.

- Codex's `ultra` mode uses automatic

- delegation and is outside this helper's supported effort levels. Use `max`

- for its deepest supported review. For EU data residency, use

- `--codex-speed default`; GPT-6 fast mode is unavailable there.

- See the [GPT-6.1 Sol](https://developers.openai.com/api/docs/models/gpt-6.1-sol),

- [GPT-6 Sol](https://developers.openai.com/api/docs/models/gpt-6-sol), and

- [GPT-6 Luna](https://developers.openai.com/api/docs/models/gpt-6-luna) model docs

- and [Codex reasoning modes](https://learn.chatgpt.com/docs/models#know-when-to-use-max-or-ultra).

-

- By default, Codex preserves only authentication settings from user configuration;

- provider, profile, context and catalogue settings remain ignored. To project a

- named route, select it explicitly through the existing config override:

-

- ```bash

- "$AUTOREVIEW" --mode local --codex-config 'model_provider="review_api"'

- ```

-

- The selector must match `model_provider` in the operator's external

- `CODEX_HOME/config.toml`. It accepts one bare or simply quoted identifier;

- provider definitions and other capabilities cannot be supplied through overrides.

- Projection requires Python 3.11 or `tomli`; default auth-only operation retains

- its existing fallback parser.

-

- The selected route must use `https://api.openai.com/v1` and command authentication

- with an absolute external executable. Fixed arguments belong in that executable's

- wrapper; omitted or empty `auth.args` are accepted. Omitted `wire_api` and

- `requires_openai_auth` retain Codex's `responses` and `false` defaults. Optional

- auth timing and context settings keep native defaults and semantics.

-

- On POSIX, a private launcher restores the validated caller `HOME` only for the

- selected authentication executable; the engine and reviewer tools retain their

- isolated environment and filesystem access. Caller `HOME` must be an available

- absolute directory with no repository-owned path or symlink provenance. Windows

- keeps the native executable route. Command-auth runs suppress raw provider

- diagnostics and report fixed failure categories, while retaining compact progress,

- usage and assistant report streaming. An empty final report fails without exposing

- captured stdout.

-

- Catalogue and authentication working-directory paths resolve relative to the

- operator config directory and must remain outside the reviewed repository.

- A supplied catalogue is copied byte-for-byte into the private client runtime;

- retries use the same route and catalogue snapshot. Dry runs check the same

- ownership and route shape without executing authentication. Codex owns catalogue

- validation, model access and context clamping. Other custom provider forms and

- split context overrides are unsupported when projection is selected.

- | Optional engine | Prerequisites |

- | --------------- | ----------------------------------------------------------------------------------------------------- |

- | Claude | CLI 2.1.169+; safe mode with web-only tools |

- | Amp | `AMP_API_KEY` for a plugin-free account; local POSIX execution, no custom endpoint or cloud/orb agent |

- | Pi | CLI 0.79.0+; configured model; no tools or project resources |

- `--engine kimi` remains recognized but is refused for reviews and `--dry-run`

- before any Kimi process, configuration read or authentication setup. The supported

- Kimi Code prompt mode accepts review content only as a command-line argument;

- the helper has no supported private prompt input channel for it. This intentionally

- retires the previous Kimi execution path rather than exposing the bundle in process

- arguments. Existing `--kimi-bin` arguments remain accepted for the same clear refusal;

- the helper never silently selects another engine. A custom agent file is not an

- equivalent replacement because it changes the input into a templated system prompt.

- Branch mode with Codex supports **added, single-frame PNG, JPEG and WebP** files.

- Install Pillow in the Python environment running the helper (`python -m pip install Pillow`).

- Use a vision-capable Codex model and a CLI supporting `codex exec --image`.

- No new bypass flag is required. Full decoding rejects corrupt and animated files.

- Images must have at most 16,777,216 pixels and no dimension above 16,384 pixels;

- decoder bomb warnings fail closed before pixel loading. Added image paths are

- limited to 20 MiB of encoded bytes each and 100 MiB total, checked against Git

- object sizes before capture. Exceeding a limit fails the entire review.

-

- The helper captures exact bytes from the pinned HEAD, stages only those images

- in its isolated workspace, and attaches them through Codex's native image input.

- Every pass receives the path, media type, byte count and SHA-256 manifest alongside

- the image attachments and text diff. Image findings use the original path and line 1.

- Text-only review does not require Pillow.

-

- Binary deletions, including images, are reviewed as deletion metadata in every

- mode without image attachments or Pillow. Other binaries, modified images,

- local/commit image additions or modifications, and image review with other engines

- remain unsupported and fail closed. Missing Pillow or provider

- image limits fail the review rather than silently dropping assets. Sensitive-path,

- source-mutation, authentication and sandbox controls remain enabled.

-

- For partial clones, materialize required Git objects **before** review. The isolated

- Git reader intentionally disables lazy network fetching; do not weaken that boundary.

- The helper owns reviewer isolation, sanitized authentication, process cleanup,

- Git scope, and structured result validation. Keep those controls enabled.

- Before repository detection or target selection, Git must pass `--version`

- within 10 seconds. Failure exits `2` with an `incomplete` diagnostic and the

- resolved executable (or the unresolved selection); it never means `scoped-clean`.

- Executable discovery skips inaccessible search candidates; an inaccessible

- explicit executable override still fails preflight.

- Set `AUTOREVIEW_GIT` to a trusted external Git executable to override every

- helper-owned Git invocation. On macOS with a broken selected Xcode, use

- `DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer` for the invocation.

- Only an absolute, external `DEVELOPER_DIR` is additionally retained in Git's

- sanitized environment;

- neither override is forwarded to the isolated reviewer environment.

-

- Every reviewer pass must inspect its bundle for real credentials and report

- suspected credentials as P0 findings without reproducing their values. Harmless

- placeholders and test fixtures are not credentials. Autoreview does not require

- or invoke an external secret scanner. Never work around an isolation failure.

- Keep approved secret scanning outside autoreview; reviewer findings happen after

- transmission. Reintroducing a scanner requires an explicit maintainer decision.

- See [#240](https://github.com/openclaw/agent-skills/pull/240) for rationale and history.

- On macOS, reviewer tools cannot access the shared `/tmp` and `/var/tmp` trees

- (including their `/private` aliases). Codex preflight rejects those temporary

- roots before workspace, runtime, or authentication setup; unset a shared

- `TMPDIR`/`TMP`/`TEMP` override to use macOS's private

- temporary directory. Other engines and platforms retain their normal isolation.

- Tools installed in shared scratch or requiring writes there will be denied too.

-

- Text review files have no size/count cap and are never truncated; image inputs

- use the explicit safety limits above. Large diffs and

- datasets are partitioned automatically. Change partitions retain complete

- datasets when they fit with sufficient change space. This preference may use more

- passes or prompt bytes than evidence batching; the explicit pass budget still applies.

- Terminal fallbacks preserve a feasible complete-evidence plan when batch framing cannot fit.

- Intact instructions, source-context files and required mixed source context must

- fit the per-pass prompt budget. A failed pass does not produce a partial clean verdict.

- Otherwise, the planner compares a bounded set of evidence allocations and keeps the existing

- plan unless total prompt bytes improve without more passes, or equal bytes need

- fewer passes. Every change is still reviewed against every evidence batch.

- Each pass is an independent assignment, not a continuing conversation. Its

- private completion field must confirm a finished assessment; deferring to

- another pass leaves the overall review incomplete.

- Do not edit inputs during a review: the helper verifies captured sources before

- sending and publishing results. Long reviews are normal; advancing heartbeats

- mean progress. Use `--stream-engine-output` for visibility, not extra reviewer

- runs. `--dry-run` checks preparation and startup without contacting a reviewer.

- Both dry runs and execution print planned pass count and total prompt bytes.

- Use `--max-review-passes N` (or `AUTOREVIEW_MAX_REVIEW_PASSES`) to reject the whole

- plan before any reviewer starts when it exceeds an explicit campaign budget.

- There is no default pass ceiling. `--engine-timeout-seconds` remains an optional

- deadline per process attempt. Pass counts, prompt bytes, and deadlines are not

- token hard caps; they do not bound model reasoning or tool use.

- Follow the [diagnostic and result guidance](references/diagnostics-and-results.md)

- for local stage observation, output paths, exit codes, status, and usage.