vivekmind 0.15.6

package/bundled/review/SKILL.md

@@ -0,0 +1,663 @@
+---
+name: review
+description: Review changed code for correctness, security, code quality, and performance. Use when the user asks to review code changes, a PR, or specific files. Invoke with `/review`, `/review <pr-number>`, `/review <file-path>`, or `/review <pr-number> --comment` to post inline comments on the PR.
+argument-hint: '[pr-number|file-path] [--comment]'
+allowedTools:
+  - task
+  - run_shell_command
+  - grep_search
+  - read_file
+  - write_file
+  - edit
+  - glob
+---
+
+# Code Review
+
+You are an expert code reviewer. Your job is to review code changes and provide actionable feedback.
+
+**Critical rules (most commonly violated — read these first):**
+
+1. **Match the language of the PR.** If the PR is in English, ALL your output (terminal + PR comments) MUST be in English. If in Chinese, use Chinese. Do NOT switch languages. For **local reviews** (no PR), if the system prompt includes an output language preference, use that language; otherwise follow the user's input language.
+2. **Step 9: use Create Review API** with `comments` array for inline comments. Do NOT use `gh api .../pulls/.../comments` to post individual comments. See Step 9 for the JSON format.
+
+**Design philosophy: Silence is better than noise.** Every comment you make should be worth the reader's time. If you're unsure whether something is a problem, DO NOT MENTION IT. Low-quality feedback causes "cry wolf" fatigue — developers stop reading all AI comments and miss real issues.
+
+## Step 1: Determine what to review
+
+Your goal here is to understand the scope of changes so you can dispatch agents effectively in Step 4.
+
+First, parse the `--comment` flag: split the arguments by whitespace, and if any token is exactly `--comment` (not a substring match — ignore tokens like `--commentary`), set the comment flag and remove that token from the argument list. If `--comment` is set but the review target is not a PR, warn the user: "Warning: `--comment` flag is ignored because the review target is not a PR." and continue without it.
+
+To disambiguate the argument type: if the argument is a pure integer, treat it as a PR number. If it's a URL containing `/pull/`, extract the owner/repo/number from the URL. Then determine if the local repo can access this PR:
+
+1. Check if any git remote URL matches the URL's owner/repo: run `git remote -v` and look for a remote whose URL contains the owner/repo (e.g., `openjdk/jdk`). This handles forks — a local clone of `wenshao/jdk` with an `upstream` remote pointing to `openjdk/jdk` can still review `openjdk/jdk` PRs.
+2. If a matching remote is found, proceed with the **normal worktree flow** — use that remote name (instead of hardcoded `origin`) for `git fetch <remote> pull/<number>/head:qwen-review/pr-<number>`. In Step 9, use the owner/repo from the URL for posting comments.
+3. If **no remote matches**, use **lightweight mode**: run `gh pr diff <url>` to get the diff directly. Skip Steps 2 (no local rules), 3 (no local linter), 8 (no local files to fix), 10 (no local cache). In Step 11, skip worktree removal (none was created) but still clean up temp files (`.vivekmind/tmp/qwen-review-{target}-*`). Also fetch existing PR comments using the URL's owner/repo (`gh api repos/{owner}/{repo}/pulls/{number}/comments`) to avoid duplicating human feedback. In Step 9, use the owner/repo from the URL. Inform the user: "Cross-repo review: running in lightweight mode (no build/test, no linter, no autofix)."
+
+Otherwise (not a URL, not an integer), treat the argument as a file path.
+
+Based on the remaining arguments:
+
+- **No arguments**: Review local uncommitted changes
+  - Run `git diff` and `git diff --staged` to get all changes
+  - If both diffs are empty, inform the user there are no changes to review and stop here — do not proceed to the review agents
+
+- **PR number or same-repo URL** (e.g., `123` or a URL whose owner/repo matches the current repo — cross-repo URLs are handled by the lightweight mode above):
+  - **Run `vivekmind review fetch-pr`** to set up the working state in one pass — it cleans any stale worktree, fetches the PR HEAD into `qwen-review/pr-<n>`, queries `gh pr view` for metadata, and creates an ephemeral worktree at `.vivekmind/tmp/review-pr-<n>`:
+
+    ```bash
+    vivekmind review fetch-pr <pr_number> <owner>/<repo> \
+      --remote <remote> \
+      --out .vivekmind/tmp/qwen-review-pr-<pr_number>-fetch.json
+    ```
+
+    `<remote>` is the matched remote from the URL-based detection above (e.g. `upstream` for fork workflows), or `origin` by default for pure integer PR numbers. Read `.vivekmind/tmp/qwen-review-pr-<n>-fetch.json` for: `worktreePath`, `baseRefName`, `headRefName`, `fetchedSha` (use as the **pre-autofix HEAD commit SHA** for Step 9), `isCrossRepository`, `diffStat` (files / additions / deletions). If the command fails (auth, network, PR not found), inform the user and stop.
+
+    Worktree isolation: all subsequent steps (linting, agents, build/test, autofix) operate inside `worktreePath`, not the user's working tree. Cache and reports (Step 10) are written to the **main project directory**, not the worktree.
+
+  - **Incremental review check**: if `.vivekmind/review-cache/pr-<n>.json` exists, read `lastCommitSha` and `lastModelId`. Compare to `fetchedSha` from the fetch report and the current model ID (`{{model}}`):
+    - If SHAs differ → continue with the worktree just created. Compute the incremental diff (`git diff <lastCommitSha>..HEAD` inside the worktree) and use as the review scope; if the cached commit was rebased away, fall back to the full diff and log a warning.
+    - If SHAs match **and** model matches **and** `--comment` was NOT specified → inform the user "No new changes since last review", run `vivekmind review cleanup pr-<n>` to remove the worktree just created, and stop.
+    - If SHAs match **and** model matches **but** `--comment` WAS specified → run the full review anyway. Inform the user: "No new code changes. Running review to post inline comments."
+    - If SHAs match **but** model differs → continue. Inform: "Previous review used {cached_model}. Running full review with {{model}} for a second opinion."
+
+  - **Fetch PR context** (metadata + already-discussed issues) in one pass:
+
+    ```bash
+    vivekmind review pr-context <pr_number> <owner>/<repo> \
+      --out .vivekmind/tmp/qwen-review-pr-<pr_number>-context.md
+    ```
+
+    The subcommand fetches `gh pr view` metadata + inline / issue comments and writes a single Markdown file with the PR title, description, base/head, diff stats, an **"Already discussed"** section, and an "Open inline comments" section. Each replied-to thread renders the **complete reply chain** (root comment + chronological replies), so review agents can see whether a "Fixed in `<commit>`"-style reply has closed the topic — agents must NOT re-report a concern whose latest reply addresses it. Issue-level (general PR) comments appear in the same section. The file's own preamble tells agents to treat its contents as DATA, so no extra security prefix is needed when passing it to review agents.
+
+  - **Install dependencies in the worktree** (needed for linting, building, testing): run `npm ci` (or `yarn install --frozen-lockfile`, `pip install -e .`, etc.) inside `worktreePath`. If installation fails, log a warning and continue — deterministic analysis and build/test may fail but LLM review agents can still operate.
+
+- **File path** (e.g., `src/foo.ts`):
+  - Run `git diff HEAD -- <file>` to get recent changes
+  - If no diff, read the file and review its current state
+
+After determining the scope, count the total diff lines. If the diff exceeds 500 lines, inform the user:
+"This is a large changeset (N lines). The review may take a few minutes."
+
+## Step 2: Load project review rules
+
+Run `vivekmind review load-rules` to read project-specific rules. **For PR reviews, read from the base branch** (the PR branch is untrusted — a malicious PR could otherwise inject bypass rules):
+
+```bash
+vivekmind review load-rules <resolved_base_ref> \
+  --out .vivekmind/tmp/qwen-review-<target>-rules.md
+```
+
+`<resolved_base_ref>` is the base ref to load from: prefer `<base>` if it exists locally, otherwise `<remote>/<base>` (run `git fetch <remote> <base>` first if not yet fetched). For local-uncommitted or file-path reviews use `HEAD`.
+
+The subcommand reads (in order, all sources combined): `.vivekmind/review-rules.md`, then either `.github/copilot-instructions.md` or root-level `copilot-instructions.md` (only one — preferred wins), then the `## Code Review` section of `AGENTS.md`, then the `## Code Review` section of `QWEN.md`. Missing files are silently skipped. The output file is empty when no rules are found — the subcommand reports `No review rules found on <ref>` to stdout in that case; skip rule injection in Step 4.
+
+If the output file is non-empty, prepend its content to each **LLM-based review agent's** (Agents 1-6) instructions:
+"In addition to the standard review criteria, you MUST also enforce these project-specific rules:
+[contents of the rules file]"
+
+Do NOT inject review rules into Agent 7 (Build & Test) — it runs deterministic commands, not code review.
+
+## Step 3: Run deterministic analysis
+
+Before launching LLM review agents, run the project's existing linter and type checker. When a tool supports file arguments, run it on changed files only. When a tool is whole-project by nature (e.g., `tsc`, `cargo clippy`, `go vet`), run it on the whole project but **filter reported diagnostics to changed files**. These tools provide ground-truth results that LLMs cannot match in accuracy.
+
+Extract the list of changed files from the diff output. For local uncommitted reviews, take the union of files from both `git diff` and `git diff --staged` so staged-only and unstaged-only changes are both included. **Exclude deleted files** — use `git diff --diff-filter=d --name-only` (or filter out deletions from `git diff --name-status`) since running linters on non-existent paths would produce false failures. For file path reviews with no diff (reviewing a file's current state), use the specified file as the target. Then run the applicable checks:
+
+1. **Bundled deterministic checks** (covers TypeScript/JavaScript, Python, Rust, Go in one call): the subcommand auto-detects each language's config files (`tsconfig.json` / eslint config / `pyproject.toml [tool.ruff]` / `Cargo.toml` / `go.mod`), runs the applicable tool on changed files (or whole project filtered to changed files for whole-project tools), parses each tool's structured output (JSON or line-based), and emits a single findings JSON:
+
+   ```bash
+   echo '<json array of changed files relative to worktree>' \
+     > .vivekmind/tmp/qwen-review-<target>-changed.json
+   vivekmind review deterministic <worktree> \
+     --changed-files .vivekmind/tmp/qwen-review-<target>-changed.json \
+     --out .vivekmind/tmp/qwen-review-<target>-deterministic.json
+   ```
+
+   Tools currently covered:
+
+   | Language | Tools |
+   |---|---|
+   | TypeScript / JavaScript | `tsc --noEmit --incremental` (typecheck), `eslint --format=json` (linter, changed files only) |
+   | Python | `ruff check --output-format=json` (linter, changed files only) |
+   | Rust | `cargo clippy --message-format=json` (typecheck — clippy includes compile checks; Agent 7 can skip `cargo build`) |
+   | Go | `go vet ./...` (typecheck — vet includes compile checks; Agent 7 can skip `go build`), `golangci-lint run --out-format=json ./...` (linter) |
+
+   Read the output JSON. `findings[]` entries are already pre-confirmed (Source: `[typecheck]` for tsc / cargo-clippy / go-vet, `[linter]` for eslint / ruff / golangci-lint, with `severity` mapped to Critical / Nice to have); pass them straight through to Step 5. `toolsRun[]` records exit codes / durations / timeout flags; `toolsSkipped[]` records why a tool didn't run (no config, missing runtime, etc.) — include the skipped tool names in the Step 7 summary.
+
+2. **Additional language tools** (run inline if the project uses them — these aren't covered by `vivekmind review deterministic` yet):
+   - Python: `mypy <changed-files>` if `pyproject.toml` has `[tool.mypy]` / `mypy.ini` exists; `flake8 <changed-files>` if `.flake8` exists
+   - Capture, filter to changed files, parse `path:line: severity: msg` format manually
+
+3. **Java projects**:
+   - If `pom.xml` exists (Maven) → use `./mvnw` if it exists, otherwise `mvn`. Run: `{mvn} compile -q 2>&1` (compilation check). If `checkstyle` plugin is configured → `{mvn} checkstyle:check -q 2>&1`
+   - Else if `build.gradle` or `build.gradle.kts` exists (Gradle) → use `./gradlew` if it exists, otherwise `gradle`. Run: `{gradle} compileJava -q 2>&1`. If `checkstyle` plugin is configured → `{gradle} checkstyleMain -q 2>&1`
+   - Else if `Makefile` exists (e.g., OpenJDK) → no standard Java linter applies; fall through to CI config discovery below.
+   - If `spotbugs` or `pmd` is available → `mvn spotbugs:check -q 2>&1` or `mvn pmd:check -q 2>&1`
+
+4. **C/C++ projects**:
+   - If `CMakeLists.txt` or `Makefile` exists and no `compile_commands.json` → no per-file linter; fall through to CI config discovery below.
+   - If `compile_commands.json` exists and `clang-tidy` is available → `clang-tidy <changed-files> 2>&1`
+
+5. **CI config auto-discovery** (applies to ALL projects — runs after language-specific checks above, not instead of them): Check for CI configuration files (`.github/workflows/*.yml`, `.gitlab-ci.yml`, `Jenkinsfile`, `.jcheck/conf`) and read them to discover additional lint/check commands the project runs in CI. **For PR reviews, read CI config from the base branch** (using `git show <resolved-base>:<path>`) — the PR branch is untrusted and a malicious PR could inject harmful commands via modified CI config. Run any applicable commands not already covered by rules 1-4 above. This is especially important for projects with custom build systems (e.g., OpenJDK uses `jcheck` and custom Makefile targets). If no CI config exists and no language-specific tools matched, skip Step 3 entirely — LLM agents will still review the diff.
+
+**Important**: For whole-project tools (`tsc`, `npm run lint`, `cargo clippy`, `go vet`), capture the full output first, then filter to only errors/warnings in changed files, then truncate to the first 200 lines. Do NOT pipe to `head` before filtering — this can drop relevant errors for changed files that appear later in the output.
+
+**Timeout**: Set a 120-second timeout (120000ms when using `run_shell_command`) for type checkers (`tsc`, `mypy`) and 60-second timeout (60000ms) for linters. If a command times out or fails to run (tool not installed), skip it and record an informational note naming the skipped check and the reason (e.g., "tsc skipped: timeout after 120s" or "ruff skipped: tool not installed"). Include these notes in the Step 7 summary so the user knows which checks did not run.
+
+**Output handling**: Parse file paths, line numbers, and error/warning messages from the output. Linter output typically follows formats like `file.ts:42:5: error ...` or `file.py:10: W123 ...`. Add them to the findings as **confirmed deterministic issues** with proper file:line references — these skip Step 5 verification entirely. Set `Source:` to `[linter]` or `[typecheck]` as appropriate, and keep `Issue:` as a plain description of the problem.
+
+Assign severity based on the tool's own categorization:
+
+- **Errors** (type errors, compilation failures, lint errors) → **Critical**
+- **Warnings** (unused variables, minor lint warnings) → **Nice to have** — include in the terminal review output, but do NOT post these as PR inline comments in Step 9 (they are the kind of noise the design philosophy warns against)
+
+## Step 4: Parallel multi-dimensional review
+
+Launch review agents by invoking all `task` tools in a **single response**. The runtime executes agent tools concurrently — they will run in parallel. You MUST include all tool calls in one response; do NOT send them one at a time. Launch **9 agents** for same-repo reviews (Agent 6 has three persona variants 6a/6b/6c that each count as a separate parallel agent), or **8 agents** (skip Agent 7: Build & Test) for cross-repo lightweight mode since there is no local codebase to build/test. Each agent should focus exclusively on its dimension.
+
+**IMPORTANT**: Keep each agent's prompt **short** (under 200 words) to fit all tool calls in one response. Do NOT paste the full diff — give each agent:
+
+- The diff command (e.g., `git diff main...HEAD`)
+- A one-sentence summary of what the changes are about
+- Its review focus (copy the focus areas from its section below)
+- Project-specific rules from Step 2 (if any)
+- For Agent 7: which tools Step 3 already ran
+
+Apply the **Exclusion Criteria** (defined at the end of this document) — do NOT flag anything that matches those criteria.
+
+Each agent must return findings in this structured format (one per issue):
+
+```
+- **File:** <file path>:<line number or range>
+- **Source:** [review] (Agents 1-6) or [build]/[test] (Agent 7)
+- **Issue:** <clear description of the problem>
+- **Impact:** <why it matters>
+- **Suggested fix:** <concrete code suggestion when possible, or "N/A">
+- **Severity:** Critical | Suggestion | Nice to have
+```
+
+If an agent finds no issues in its dimension, it should explicitly return "No issues found."
+
+### Agent 1: Correctness
+
+Focus areas:
+
+- Logic errors and incorrect assumptions
+- Edge cases: null/undefined, empty collections, single-element vs multi-element, very large inputs, special characters/unicode
+- Boundary conditions: off-by-one, fence-post errors, integer overflow
+- Race conditions and concurrency issues
+- Type safety issues
+- Error handling gaps and exception propagation
+
+### Agent 2: Security
+
+Focus areas:
+
+- Injection (SQL, command, prototype pollution, code injection)
+- XSS (stored, reflected, DOM-based)
+- SSRF and path traversal
+- Authentication and authorization bypass
+- Sensitive data exposure in logs, error messages, or responses
+- Insecure deserialization, weak crypto
+- Hardcoded secrets, credentials, or API keys in the diff
+- CSRF, clickjacking (for web changes)
+
+### Agent 3: Code Quality
+
+Focus areas:
+
+- Code style consistency with the surrounding codebase
+- Naming conventions (variables, functions, classes)
+- Code duplication and opportunities for reuse
+- Over-engineering or unnecessary abstraction
+- Missing or misleading comments
+- Dead code
+
+### Agent 4: Performance & Efficiency
+
+Focus areas:
+
+- Performance bottlenecks (N+1 queries, unnecessary loops, etc.)
+- Memory leaks or excessive memory usage
+- Unnecessary re-renders (for UI code)
+- Inefficient algorithms or data structures
+- Missing caching opportunities
+- Bundle size impact
+
+### Agent 5: Test Coverage
+
+Focus areas:
+
+- Are new tests added for new code paths in the diff?
+- Are critical branches (success path, error path, edge cases) covered?
+- Are existing tests updated to reflect behavior changes?
+- Are obvious untested scenarios left out (e.g., a new validation function tested only on the happy path)?
+- Do test assertions actually verify behavior, not just that the code ran without throwing?
+- Are integration boundaries tested, not just unit-level happy path?
+
+Note: Do NOT complain about "low coverage" abstractly. Point to specific code paths in the diff that lack tests, and explain what scenario is uncovered.
+
+### Agent 6: Undirected Audit (three parallel personas)
+
+Launch **three separate undirected agents** (6a, 6b, 6c) in parallel, each with a different mental persona. The personas force diverse thinking paths — the union of their findings catches issues that a single undirected agent's prompt-induced bias would miss. Each persona shares the common focus areas below, but reviews under a different psychological framing.
+
+**Common focus areas (apply to all three personas):**
+
+- Business logic soundness and correctness of assumptions
+- Boundary interactions between modules or services
+- Implicit assumptions that may break under different conditions
+- Unexpected side effects or hidden coupling
+- Anything else that looks off — trust your instincts
+
+**Persona-specific framing** — prepend the matching framing to each persona's prompt:
+
+#### Agent 6a — Attacker mindset
+
+"You are a malicious user looking at this code. Find inputs, sequences of actions, or environmental conditions that would make this code misbehave, expose data, or cause harm. What is the most embarrassing bug a security researcher could file against this code?"
+
+#### Agent 6b — 3 AM oncall mindset
+
+"You are an oncall engineer who just got paged at 3 AM because something based on this code broke production. Looking at the diff: what is the most likely failure mode? What would be hardest to debug under sleep deprivation? Are there missing logs, unclear error messages, or silent failures that would make this a nightmare to investigate?"
+
+#### Agent 6c — Six-months-later maintainer mindset
+
+"You are an engineer who inherits this codebase six months from now. The original author has left the company. Looking at this diff: where will future-you stub a toe? What implicit assumption is undocumented and will break when someone modifies adjacent code? What is the most subtle landmine hidden in plain sight?"
+
+### Agent 7: Build & Test Verification
+
+This agent runs deterministic build and test commands to verify the code compiles and tests pass. If Step 3 already ran a tool that includes compilation (e.g., `cargo clippy`, `go vet`, `tsc --noEmit`), skip the redundant build command for that language and only run tests.
+
+1. Detect the build system and run **exactly one** build command (skip if Step 3 already verified compilation). Use this precedence order — choose the **first applicable** option only to avoid duplicate builds (e.g., a Makefile that wraps npm). Capture full output; if it exceeds 200 lines, keep the first 50 and last 100 lines:
+   - If `package.json` exists with a `build` script → `npm run build 2>&1`
+   - Else if `pom.xml` exists → use `./mvnw` if it exists, otherwise `mvn`: `{mvn} compile -q 2>&1`
+   - Else if `build.gradle` or `build.gradle.kts` exists → use `./gradlew` if it exists, otherwise `gradle`: `{gradle} compileJava -q 2>&1`
+   - Else if `Makefile` exists → `make build 2>&1`
+   - Else if `Cargo.toml` exists → `cargo build 2>&1`
+   - Else if `go.mod` exists → `go build ./... 2>&1`
+2. Run **exactly one** test command (same precedence and output handling):
+   - If `package.json` exists with a `test` script → `npm test 2>&1`
+   - Else if `pom.xml` exists → use `./mvnw` if it exists, otherwise `mvn`: `{mvn} test -q 2>&1`
+   - Else if `build.gradle` or `build.gradle.kts` exists → use `./gradlew` if it exists, otherwise `gradle`: `{gradle} test -q 2>&1`
+   - Else if `pytest.ini` or `pyproject.toml` with `[tool.pytest]` → `pytest 2>&1`
+   - Else if `Cargo.toml` exists → `cargo test 2>&1`
+   - Else if `go.mod` exists → `go test ./... 2>&1`
+   - If none of the above match, read CI configuration files (`.github/workflows/*.yml`, `Makefile`, etc.) to discover the project's build and test commands. For example, OpenJDK uses `make images` to build and `make test TEST=tier1` to test. Use the discovered commands.
+3. Set a **120-second timeout** (120000ms when using `run_shell_command`) for each command. If a command times out, report it as a finding.
+4. If build or tests fail, analyze the error output and correlate failures with specific changes in the diff. Distinguish between:
+   - **Code-caused failures** (compilation errors, test assertions) → **Critical**
+   - **Environment/setup failures** (missing dependencies, tool not installed, virtualenv not activated) → report as informational note, not Critical
+5. Output format: same as other agents, but the **Source** field MUST be `[build]` for build failures or `[test]` for test failures (not `[review]`).
+
+**Note**: Build/test results are deterministic facts. Code-caused failures skip Step 5 verification — the `[build]`/`[test]` source tag is how they are recognized as pre-confirmed. Environment/setup failures are informational only and should not affect the verdict.
+
+### Cross-file impact analysis (applies to Agents 1-6, same-repo reviews only)
+
+For same-repo reviews (where local files are available), each review agent (1-6) MUST perform cross-file impact analysis for modified functions, classes, or interfaces. Skip this for cross-repo lightweight mode (no local codebase to search). If the diff modifies more than 10 exported symbols, prioritize those with **signature changes** (parameter/return type modifications, renamed/removed members) and skip unchanged-signature modifications to avoid excessive search overhead.
+
+1. Use `grep_search` to find all callers/importers of each modified function/class/interface
+2. Check whether callers are compatible with the modified signature/behavior
+3. Pay special attention to:
+   - Parameter count or type changes
+   - Return type changes
+   - Behavioral changes (new exceptions thrown, null returns, changed defaults)
+   - Removed or renamed public methods/properties
+   - Breaking changes to exported APIs
+4. If `grep_search` results are ambiguous, also use `run_shell_command` with fixed-string grep (`grep -F`) for precise reference matching — do NOT use `-E` regex with unescaped symbol names, as symbols may contain regex metacharacters (e.g., `$` in JS). Run separate searches for each access pattern: `grep -rnF --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=dist --exclude-dir=build "functionName(" .` and `.functionName` and `import { functionName` etc. (use the project root; always exclude common non-source directories)
+
+## Step 5: Deduplicate, verify, and aggregate
+
+### Deduplication
+
+Before verification, merge findings that refer to the same issue (same file, same line range, same root cause) even if reported by different agents. Keep the most detailed description and note which agents flagged it. When severities differ across merged items, use the **highest severity** — never let deduplication downgrade severity. **If a merged finding includes any deterministic source** (`[linter]`, `[typecheck]`, `[build]`, `[test]`), treat the entire merged finding as pre-confirmed — retain all source tags for reporting, preserve deterministic severity as authoritative, and skip verification.
+
+### Batch verification
+
+Launch a **single verification agent** that receives **all** non-pre-confirmed findings at once (not one agent per finding — this keeps LLM calls fixed regardless of finding count). The verification agent receives:
+
+- The complete list of findings to verify (with file, line, issue description for each)
+- The command to obtain the diff (as determined in Step 1)
+- Access to read files and search the codebase
+
+The verification agent must, for each finding:
+
+1. Read the actual code at the referenced file and line
+2. Check surrounding context — callers, type definitions, tests, related modules
+3. Verify the issue is not a false positive — reject if it matches any item in the **Exclusion Criteria**
+4. Return a verdict with confidence level:
+   - **confirmed (high confidence)** — clearly a real issue, with severity: Critical, Suggestion, or Nice to have
+   - **confirmed (low confidence)** — likely a problem but not certain, recommend human review, with severity
+   - **rejected** — with a one-line reason why it's not a real issue
+
+**When uncertain, downgrade to "confirmed (low confidence)" rather than rejecting outright.** Low-confidence findings stay in terminal output (under "Needs Human Review") but are filtered from PR inline comments — this preserves the "Silence is better than noise" principle for PR interactions while ensuring valid concerns are not silently swallowed. Reserve outright rejection for findings that clearly do not match the actual code (the finding describes behavior the code does not have, or it matches an Exclusion Criterion). Vague suspicions with no concrete evidence in the code can still be rejected — low-confidence is for "likely real but needs human judgment," not for "I have no idea."
+
+**After verification:** remove all rejected findings. Separate confirmed findings into two groups: high-confidence and low-confidence. Low-confidence findings appear **only in terminal output** (under "Needs Human Review") and are **never posted as PR inline comments** — this preserves the "Silence is better than noise" principle for PR interactions.
+
+### Pattern aggregation
+
+After verification, identify **confirmed** findings that describe the **same type of problem** across different locations (e.g., "missing error handling" appearing in 8 places). Only group findings with the **same confidence level** together — do not mix high-confidence and low-confidence findings in the same pattern group. For each pattern group:
+
+1. Merge into a single finding with all affected locations listed
+2. Format:
+   - **File:** [list of all affected locations]
+   - **Pattern:** <unified description of the problem pattern>
+   - **Occurrences:** N locations
+   - **Example:** <the most representative instance>
+   - **Suggested fix:** <general fix approach>
+   - **Severity:** <highest severity among the group>
+3. If the same pattern has more than 5 occurrences and severity is **not** Critical, list the first 3 locations plus "and N more locations". For **Critical** patterns, always list all locations — every instance matters.
+
+All confirmed findings (aggregated or standalone) proceed to Step 6.
+
+## Step 6: Iterative reverse audit
+
+After aggregation, run reverse audit **iteratively** — keep launching new rounds until either (a) a round finds zero new issues, or (b) **3 rounds** have been completed (hard cap). Each round receives the cumulative confirmed findings from all prior rounds, so successive rounds focus on whatever the previous round missed.
+
+**Why iterative**: A single pass leaves whatever the reverse audit agent itself missed. Each round narrows what's left to discover, until diminishing returns terminate the loop. Most PRs converge in 1-2 rounds; the cap prevents runaway cost on pathological cases.
+
+For each round, launch a **single reverse audit agent** that receives:
+
+- The cumulative list of all confirmed findings so far (from Steps 4-5 plus all prior reverse audit rounds — so it knows what's already covered)
+- The command to obtain the diff
+- Access to read files and search the codebase
+
+The reverse audit agent must:
+
+1. Review the diff with full knowledge of what was already found
+2. Focus exclusively on **gaps** — important issues that no prior agent or round caught
+3. Only report **Critical** or **Suggestion** level findings — do not report Nice to have
+4. Apply the same **Exclusion Criteria** as other agents
+5. Return findings in the same structured format (with `Source: [review]`)
+6. If no new gaps are found, return exactly "No issues found." — this terminates the loop
+
+**Termination rules:**
+
+- Stop iterating as soon as a round returns "No issues found."
+- Stop after 3 rounds even if the third round still produces findings (hard cap).
+- New findings from each round are merged into the cumulative list **before** the next round begins, so each round sees an updated baseline.
+
+Reverse audit findings are treated as **high confidence** and **skip verification** — the agent already has full context (all confirmed findings + entire diff), so its output does not need a second opinion.
+
+If the very first round finds nothing, that is an excellent outcome — it means the initial review had strong coverage.
+
+All confirmed findings (from aggregation + all reverse audit rounds) proceed to Step 7.
+
+## Step 7: Present findings
+
+Present all confirmed findings (from Steps 5 and 6) as a single, well-organized review. Use this format:
+
+### Summary
+
+A 1-2 sentence overview of the changes and overall assessment.
+
+For **terminal output**: include verification stats ("X findings reported, Y confirmed after verification") and deterministic analysis results. This helps the user understand the review process.
+
+For **PR comments** (Step 9): do NOT include internal stats (agent count, raw/confirmed numbers, verification details). PR reviewers only care about the findings, not the review process.
+
+### Findings
+
+Use severity levels:
+
+- **Critical** — Must fix before merging. Bugs that cause incorrect behavior (e.g., logic errors, wrong return values, skipped code paths), security vulnerabilities, data loss risks, build/test failures. If code does something wrong, it's Critical — not Suggestion.
+- **Suggestion** — Recommended improvement. Better patterns, clearer code, potential issues that don't cause incorrect behavior today but may in the future.
+- **Nice to have** — Optional optimization. Minor style tweaks, small performance gains.
+
+For each **individual** finding, include:
+
+1. **File and line reference** (e.g., `src/foo.ts:42`)
+2. **Source tag** — `[linter]`, `[typecheck]`, `[build]`, `[test]`, or `[review]`
+3. **What's wrong** — Clear description of the issue
+4. **Why it matters** — Impact if not addressed
+5. **Suggested fix** — Concrete code suggestion when possible
+
+For **pattern-aggregated** findings, use the aggregated format from Step 5 (Pattern, Occurrences, Example, Suggested fix) with the source tag added.
+
+Group high-confidence findings first. Then add a separate section:
+
+### Needs Human Review
+
+List low-confidence findings here with the same format but prefixed with "Possibly:" — these are issues the verification agent was not fully certain about and should be reviewed by a human.
+
+If there are no low-confidence findings, omit this section.
+
+### Verdict
+
+Based on **high-confidence findings only** (low-confidence findings do not influence the verdict — they are terminal-only and "Needs Human Review"):
+
+- **Approve** — No high-confidence critical issues, good to merge
+- **Request changes** — Has high-confidence critical issues that need fixing
+- **Comment** — Has suggestions but no blockers
+
+Append a follow-up tip after the verdict (and after Step 8 Autofix if applicable). Choose based on remaining state:
+
+- **Local review with unfixed findings**: "Tip: type `fix these issues` to apply fixes interactively."
+- **PR review with findings** (only if `--comment` was NOT specified — if `--comment` was set, comments are already being posted in Step 9, so this tip is unnecessary): "Tip: type `post comments` to publish findings as PR inline comments." (Do NOT offer "fix these issues" for PR reviews — the worktree is cleaned up after the review, so interactive fixing is not possible. Autofix in Step 8 is the PR fix mechanism.)
+- **PR review, zero findings** (only if `--comment` was NOT specified): "Tip: type `post comments` to approve this PR on GitHub."
+- **Local review, all clear** (Approve or all issues fixed): "Tip: type `commit` to commit your changes."
+
+If the user responds with "fix these issues" (local review only), use the `edit` tool to fix each remaining finding interactively based on the suggested fixes from the review — do NOT re-run Steps 1-8.
+
+If the user responds with "post comments" (or similar intent like "yes post them", "publish comments"), proceed directly to Step 9 using the findings already collected — do NOT re-run Steps 1-8.
+
+## Step 8: Autofix
+
+If there are **Critical** or **Suggestion** findings with clear, unambiguous fixes, offer to auto-apply them.
+
+1. Count the number of auto-fixable findings (those with concrete suggested fixes that can be expressed as file edits).
+2. If there are fixable findings, ask the user:
+   "Found N issues with auto-fixable suggestions. Apply auto-fixes? (y/n)"
+3. If the user agrees:
+   - For each fixable finding, apply the fix using the appropriate file editing approach
+   - After all fixes are applied, re-run only per-file deterministic checks (e.g., `eslint`, `ruff check`, `flake8`) on the modified files to verify fixes don't introduce new issues. Skip whole-project checks (`tsc --noEmit`, `go vet ./...`) as they are too slow for a quick verification pass.
+   - Show a summary of applied fixes with file paths and brief descriptions
+4. If the user declines, continue with text-only suggestions.
+
+**After autofix**: Re-evaluate the verdict for the **terminal output** (Step 7). If all Critical findings were fixed, update the displayed verdict accordingly (e.g., from "Request changes" to "Comment" or "Approve"). However, for **PR review submission** (Step 9), always use the **pre-fix verdict** — the remote PR still contains the original unfixed code until the user pushes the autofix commit.
+
+**Important**:
+
+- Do NOT auto-fix without user confirmation. Do NOT auto-fix findings marked as "Nice to have" or low-confidence findings.
+- If reviewing a PR (worktree mode), autofix modifies files in the **worktree**, not the user's working tree. After applying fixes, commit from the worktree: `cd <worktree-path> && git add <fixed-files> && git commit -m "fix: apply auto-fixes from /review"`. Then attempt to push: `git push <remote> HEAD:<remote-branch-name>` (use the remote and branch name from Step 1). **Note**: push may fail if the PR is from a fork and the user doesn't have push access to the source repo — this is expected. Inform the user of the outcome: if push succeeds → "Auto-fixes committed and pushed to the PR branch." If push fails → "Auto-fix committed locally but push failed (you may not have push access to this repo). The commit is in the worktree at `<worktree-path>`. You can push manually or create a new PR." Step 9 (PR comments) may still proceed, but **skip Step 11 worktree cleanup** to preserve the commit for manual recovery.
+
+## Step 9: Submit PR review
+
+Skip this step if the review target is not a PR, or if BOTH of the following are true: `--comment` was not specified AND the user did not request "post comments" via follow-up.
+
+**Use the "Create Review" API to submit verdict + inline comments in a single call** (like Copilot Code Review). This eliminates separate summary comments — the inline comments ARE the review.
+
+First, determine the repository owner/repo. For **same-repo** reviews, run `gh repo view --json owner,name --jq '"\(.owner.login)/\(.name)"'`. For **cross-repo** reviews, use the owner/repo from the PR URL in Step 1.
+
+Use the **pre-autofix HEAD commit SHA** captured in Step 1. If not captured, fall back to `gh pr view {pr_number} --json headRefOid --jq '.headRefOid'`.
+
+**Run pre-submission checks**: the bundled `vivekmind review presubmit` subcommand performs self-PR detection, CI / build status classification, and existing-VivekMind-comment classification in one pass — three deterministic gh-API queries collapsed into a single JSON report. Read the report to drive the rest of Step 9.
+
+Optionally write the `(path, line)` anchors of the comments you're about to post so existing-comment Overlap can be detected:
+
+```bash
+echo '[{"path":"src/foo.ts","line":42}, ...]' > .vivekmind/tmp/qwen-review-{target}-findings.json
+```
+
+Then run:
+
+```bash
+vivekmind review presubmit \
+  {pr_number} {commit_sha} {owner}/{repo} \
+  .vivekmind/tmp/qwen-review-{target}-presubmit.json \
+  [--new-findings .vivekmind/tmp/qwen-review-{target}-findings.json]
+```
+
+Read `.vivekmind/tmp/qwen-review-{target}-presubmit.json`. Schema:
+
+```typescript
+{
+  isSelfPr: boolean;             // PR author === current authenticated user (case-insensitive)
+  ciStatus: {
+    class: 'all_pass' | 'any_failure' | 'all_pending' | 'no_checks';
+    failedCheckNames: string[];  // failing check names — include in body text
+    totalChecks: number;
+  };
+  existingComments: {
+    total: number;
+    byBucket: { stale, resolved, overlap, noConflict: number };
+    overlap: Comment[];          // BLOCK on submit if non-empty
+    stale: Comment[];            // log "Skipped N stale ..."
+    resolved: Comment[];         // log "Skipped N replied-to ..."
+    noConflict: Comment[];       // log "Found N prior with no overlap ..."
+  };
+  downgradeApprove: boolean;        // submit COMMENT instead of APPROVE
+  downgradeRequestChanges: boolean; // submit COMMENT instead of REQUEST_CHANGES (self-PR only)
+  downgradeReasons: string[];       // human-readable; join with '; ' for body
+  blockOnExistingComments: boolean; // inform user and ask before submit
+}
+```
+
+**Apply the report:**
+
+- `blockOnExistingComments=true` → list `existingComments.overlap` to the user, ask whether to proceed. If they decline, stop.
+- `downgradeApprove=true` → submit `event=COMMENT` instead of `APPROVE`.
+- `downgradeRequestChanges=true` → submit `event=COMMENT` instead of `REQUEST_CHANGES` (only set on self-PR).
+- `downgradeReasons` non-empty → prepend to `body` as `⚠️ Downgraded from <verdict> to Comment: <reasons joined with '; '>. <verb>...`.
+- For `stale` / `resolved` / `noConflict` buckets, log to terminal but do not block.
+
+**Why these checks block submission:**
+
+- **Self-PR**: GitHub rejects both `APPROVE` and `REQUEST_CHANGES` on your own PR (HTTP 422); `COMMENT` is the only accepted event. The Critical/Suggestion findings still appear as inline `comments` regardless, so substantive feedback is preserved.
+- **CI failure / pending**: the LLM review reads code statically and cannot see runtime test failures. Approving on red CI is misleading; pending CI means the verdict is premature.
+- **Overlap with existing comments**: posting on the same `(path, line)` as an existing VivekMind comment produces visual duplicates. Stale-commit and replied-to comments are skipped silently — they're false-positive overlap from line-based matching.
+
+⚠️ **Findings that can be mapped to a diff line → go in `comments` array (with `line` field). Findings that CANNOT be mapped to a specific diff line → go in `body` field.** Every entry in the `comments` array MUST have a valid `line` number. Do NOT put a comment in the `comments` array without a `line` — it creates an orphaned comment with no code reference.
+
+**Build the review JSON** with `write_file` to create `.vivekmind/tmp/qwen-review-{target}-review.json`. Every high-confidence Critical/Suggestion finding that can be mapped to a diff line MUST be an entry in the `comments` array:
+
+````json
+{
+  "commit_id": "{commit_sha}",
+  "event": "REQUEST_CHANGES",
+  "body": "",
+  "comments": [
+    {
+      "path": "src/file.ts",
+      "line": 42,
+      "body": "**[Critical]** issue description\n\n```suggestion\nfix code\n```\n\n_— YOUR_MODEL_ID via VivekMind /review_"
+    }
+  ]
+}
+````
+
+Rules:
+
+- `event`: `APPROVE` (no Critical), `REQUEST_CHANGES` (has Critical), or `COMMENT` (Suggestion only). Do NOT use `COMMENT` when there are Critical findings. **Apply downgrade decisions from the presubmit JSON above**: if `downgradeApprove=true`, submit `COMMENT` instead of `APPROVE`; if `downgradeRequestChanges=true`, submit `COMMENT` instead of `REQUEST_CHANGES`. The Critical/Suggestion content still appears in inline `comments` regardless, so substantive feedback is preserved.
+- `body`: **empty `""`** when there are inline comments. Only put text here if some findings cannot be mapped to diff lines (those go in body as a last resort). Never put section headers, "Review Summary", or analysis in body.
+- `comments`: **ALL** high-confidence Critical/Suggestion findings go here. Skip Nice to have and low-confidence. Each must reference a line in the diff.
+- Comment body format: `**[Severity]** description\n\n```suggestion\nfix\n```\n\n_— YOUR_MODEL_ID via VivekMind /review_`
+- The model name is declared at the top of this prompt. You MUST include it in every footer. Do NOT omit the model name.
+- Use ` ```suggestion ` for one-click fixes; regular code blocks if fix spans multiple locations.
+- Only ONE comment per unique issue.
+
+Then submit:
+
+```bash
+gh api repos/{owner}/{repo}/pulls/{pr_number}/reviews \
+  --input .vivekmind/tmp/qwen-review-{target}-review.json
+```
+
+If there are **no confirmed findings**, submit a single-line review. Use `event=APPROVE` by default; if the presubmit JSON has `downgradeApprove=true`, use `event=COMMENT` and prepend the downgrade reasons to the body:
+
+```bash
+# downgradeApprove=false (non-self PR, green CI):
+gh api repos/{owner}/{repo}/pulls/{pr_number}/reviews \
+  -f commit_id="{commit_sha}" \
+  -f event="APPROVE" \
+  -f body="No issues found. LGTM! ✅ _— YOUR_MODEL_ID via VivekMind /review_"
+
+# downgradeApprove=true (self-PR, CI failing, or CI still running):
+gh api repos/{owner}/{repo}/pulls/{pr_number}/reviews \
+  -f commit_id="{commit_sha}" \
+  -f event="COMMENT" \
+  -f body="No review findings. Downgraded from Approve to Comment: <downgradeReasons joined with '; '>. _— YOUR_MODEL_ID via VivekMind /review_"
+```
+
+Clean up the JSON file in Step 11.
+
+## Step 10: Save review report and cache
+
+### Report persistence
+
+Save the review results to a Markdown file for future reference:
+
+- Local changes review → `.vivekmind/reviews/<YYYY-MM-DD>-<HHMMSS>-local.md`
+- PR review → `.vivekmind/reviews/<YYYY-MM-DD>-<HHMMSS>-pr-<number>.md`
+- File review → `.vivekmind/reviews/<YYYY-MM-DD>-<HHMMSS>-<filename>.md`
+
+Include hours/minutes/seconds in the filename to avoid overwriting on same-day re-reviews.
+
+Create the `.vivekmind/reviews/` directory if it doesn't exist. **For PR worktree mode, use absolute paths to the main project directory** (not the worktree) — e.g., `mkdir -p /absolute/path/to/project/.vivekmind/reviews/`. Relative paths would land inside the worktree and be deleted in Step 11.
+
+Report content should include:
+
+- Review timestamp and target description
+- Diff statistics (files changed, lines added/removed) — omit if reviewing a file with no diff
+- Deterministic analysis results (linter/typecheck/build/test output summary)
+- All findings with verification status
+- Verdict
+
+### Incremental review cache
+
+If reviewing a PR, update the review cache for incremental review support:
+
+1. Create `.vivekmind/review-cache/` directory if it doesn't exist
+2. Write `.vivekmind/review-cache/pr-<number>.json` with:
+
+   ```json
+   {
+     "lastCommitSha": "<pre-autofix HEAD SHA captured in Step 1>",
+     "lastModelId": "{{model}}",
+     "lastReviewDate": "<ISO timestamp>",
+     "findingsCount": <number>,
+     "verdict": "<verdict>"
+   }
+   ```
+
+3. Ensure `.vivekmind/reviews/` and `.vivekmind/review-cache/` are ignored by `.gitignore` — a broader rule like `.vivekmind/*` also satisfies this. Only warn the user if those paths are not ignored at all.
+
+## Step 11: Clean up
+
+Run the bundled cleanup subcommand:
+
+```bash
+vivekmind review cleanup <target>
+```
+
+`<target>` is the same suffix used throughout (`pr-<n>`, `local`, or filename). The command removes the worktree at `.vivekmind/tmp/review-pr-<n>` (PR targets only), deletes the local branch ref `qwen-review/pr-<n>`, and clears any `.vivekmind/tmp/qwen-review-<target>-*` side files (review JSON, PR context, presubmit / findings reports). It is idempotent — missing files are silent OK.
+
+**If Step 8 flagged the worktree for preservation** (autofix commit/push failure), skip Step 11 entirely. The user needs the worktree intact to recover the autofix commit. Inform the user the worktree is preserved at `.vivekmind/tmp/review-pr-<n>` and they should run `vivekmind review cleanup pr-<n>` manually after recovering the commit.
+
+This step runs **after** Step 9 and Step 10 to ensure all review outputs are saved before cleanup.
+
+## Exclusion Criteria
+
+These criteria apply to both Step 4 (review agents) and Step 5 (verification agents). Do NOT flag or confirm any finding that matches:
+
+- Pre-existing issues in unchanged code (focus on the diff only)
+- Style, formatting, or naming that matches surrounding codebase conventions
+- Pedantic nitpicks that a senior engineer would not flag
+- Issues that a linter or type checker would catch automatically (these are handled by Step 3)
+- Subjective "consider doing X" suggestions that aren't real problems
+- If you're unsure whether something is a problem, do NOT report it
+- Minor refactoring suggestions that don't address real problems
+- Missing documentation or comments unless the logic is genuinely confusing
+- "Best practice" citations that don't point to a concrete bug or risk
+- Issues already discussed in existing PR comments (for PR reviews)
+
+## Guidelines
+
+- Be specific and actionable. Avoid vague feedback like "could be improved."
+- Reference the existing codebase conventions — don't impose external style preferences.
+- Focus on the diff, not pre-existing issues in unchanged code.
+- Keep the review concise. Don't repeat the same point for every occurrence — use pattern aggregation.
+- When suggesting a fix, show the actual code change.
+- Flag any exposed secrets, credentials, API keys, or tokens in the diff as **Critical**.
+- Silence is better than noise. If you have nothing important to say, say nothing.
+- **Do NOT use `#N` notation** (e.g., `#1`, `#2`) in PR comments or summaries — GitHub auto-links these to issues/PRs. Use `(1)`, `[1]`, or descriptive references instead.
+- **Match the language of the PR.** Write review comments, findings, and summaries in the same language as the PR title/description/code comments. If the PR is in English, write in English. If in Chinese, write in Chinese. Do NOT switch languages. For **local reviews** (no PR), respect the user's output language preference if set; otherwise follow the user's input language.