autoreview

Files (21)

• AGENTS.md
• SKILL.md
• diagnostics-and-results.md · references/
• autoreview · scripts/
• autoreview_test.py · scripts/
• test-review-harness · scripts/
• test-review-harness.ps1 · scripts/
• test-review-harness.py · scripts/
• swift-benign-status-literals.swift · tests/fixtures/
• typescript-benign-config-path-references.ts · tests/fixtures/
• typescript-benign-references.ts · tests/fixtures/
• typescript-sensitive-literals.ts · tests/fixtures/
• test_autoreview_hardening.py · tests/
• test_codex_inference_route.py · tests/
• test_codex_sandbox.py · tests/
• test_engine_stage.py · tests/
• test_git_boundary.py · tests/
• test_git_filter_collection.py · tests/
• test_git_line_endings.py · tests/
• test_output_path_interpretation.py · tests/
• test_terminal_report_authority.py · tests/

SKILL.md (first lines)

# Auto Review

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.

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.

## Run

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. For an OpenClaw checkout:

```bash
AUTOREVIEW=".agents/skills/autoreview/scripts/autoreview"
"$AUTOREVIEW" --mode local
```

In the canonical agent-skills repo, the path is
`skills/autoreview/scripts/autoreview`. On Windows, invoke the helper with Python.
Use `--help` for the complete flags and environment overrides.

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:

```bash
pr_base=$(gh pr view --json baseRefName --jq .baseRefName)
merge_base=$(git merge-base HEAD "origin/$pr_base")
"$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.

## Context and severity

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

From Elogic360/imClaw, MIT.

More from Elogic360/imClaw