@qwen-code/qwen-code 0.15.5 → 0.15.6-nightly.20260502.5d1052a35

package/bundled/qc-helper/docs/configuration/settings.md

@@ -73,7 +73,13 @@ When both legacy settings are present with different values, the migration follo
 
 ### Available settings in `settings.json`
 
-Settings are organized into categories. All settings should be placed within their corresponding top-level category object in your `settings.json` file.
+Settings are organized into categories. Most settings should be placed within their corresponding top-level category object in your `settings.json` file. A few compatibility settings, such as `proxy`, are top-level keys.
+
+#### top-level
+
+| Setting | Type   | Description                                                                                                                                                                | Default     |
+| ------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
+| `proxy` | string | Proxy URL for CLI HTTP requests. Precedence is `--proxy` > `proxy` in `settings.json` > `HTTPS_PROXY` / `https_proxy` / `HTTP_PROXY` / `http_proxy` environment variables. | `undefined` |
 
 #### general
 
@@ -470,6 +476,7 @@ Here is an example of a `settings.json` file with the nested structure, new as o
 
 ```
 {
+  "proxy": "http://localhost:7890",
   "general": {
     "vimMode": true,
     "preferredEditor": "code"

package/bundled/qc-helper/docs/features/code-review.md

@@ -29,14 +29,16 @@ The `/review` command runs a multi-stage pipeline:
 Step 1:  Determine scope (local diff / PR worktree / file)
 Step 2:  Load project review rules
 Step 3:  Run deterministic analysis (linter, typecheck)    [zero LLM cost]
-Step 4:  5 parallel review agents                          [5 LLM calls]
-           |-- Agent 1: Correctness & Security
-           |-- Agent 2: Code Quality
-           |-- Agent 3: Performance & Efficiency
-           |-- Agent 4: Undirected Audit
-           '-- Agent 5: Build & Test (runs shell commands)
+Step 4:  9 parallel review agents                          [9 LLM calls]
+           |-- Agent 1: Correctness
+           |-- Agent 2: Security
+           |-- Agent 3: Code Quality
+           |-- Agent 4: Performance & Efficiency
+           |-- Agent 5: Test Coverage
+           |-- Agent 6: Undirected Audit (3 personas: 6a/6b/6c)
+           '-- Agent 7: Build & Test (runs shell commands)
 Step 5:  Deduplicate --> Batch verify --> Aggregate         [1 LLM call]
-Step 6:  Reverse audit (find coverage gaps)                 [1 LLM call]
+Step 6:  Iterative reverse audit (1-3 rounds, gap finding) [1-3 LLM calls]
 Step 7:  Present findings + verdict
 Step 8:  Autofix (user-confirmed, optional)
 Step 9:  Post PR inline comments (if requested)
@@ -46,15 +48,17 @@ Step 11: Clean up (remove worktree + temp files)
 
 ### Review Agents
 
-| Agent                             | Focus                                                              |
-| --------------------------------- | ------------------------------------------------------------------ |
-| Agent 1: Correctness & Security   | Logic errors, null handling, race conditions, injection, XSS, SSRF |
-| Agent 2: Code Quality             | Style consistency, naming, duplication, dead code                  |
-| Agent 3: Performance & Efficiency | N+1 queries, memory leaks, unnecessary re-renders, bundle size     |
-| Agent 4: Undirected Audit         | Business logic, boundary interactions, hidden coupling             |
-| Agent 5: Build & Test             | Runs build and test commands, reports failures                     |
+| Agent                             | Focus                                                                                       |
+| --------------------------------- | ------------------------------------------------------------------------------------------- |
+| Agent 1: Correctness              | Logic errors, edge cases, null handling, race conditions, type safety                       |
+| Agent 2: Security                 | Injection, XSS, SSRF, auth bypass, sensitive data exposure                                  |
+| Agent 3: Code Quality             | Style consistency, naming, duplication, dead code                                           |
+| Agent 4: Performance & Efficiency | N+1 queries, memory leaks, unnecessary re-renders, bundle size                              |
+| Agent 5: Test Coverage            | Untested code paths in the diff, missing branch coverage, weak assertions                   |
+| Agent 6: Undirected Audit         | 3 parallel personas (attacker / 3am-oncall / maintainer) — catches cross-dimensional issues |
+| Agent 7: Build & Test             | Runs build and test commands, reports failures                                              |
 
-All agents run in parallel. Findings from Agents 1-4 are verified in a **single batch verification pass** (one agent reviews all findings at once, keeping LLM calls fixed). After verification, a **reverse audit agent** re-reads the entire diff with knowledge of all confirmed findings to catch issues that every other agent missed. Reverse audit findings skip the verification step (the agent already has full context) and are included directly as high-confidence results.
+All agents run in parallel (Agent 6 launches 3 persona variants concurrently, totaling 9 parallel tasks for same-repo reviews). Findings from Agents 1-6 are verified in a **single batch verification pass** (one agent reviews all findings at once, keeping verification cost fixed regardless of finding count). After verification, **iterative reverse audit** runs 1-3 rounds of gap-finding — each round receives the cumulative finding list from prior rounds, so successive rounds focus on whatever's left undiscovered. The loop stops as soon as a round returns "No issues found", or after 3 rounds (hard cap). Reverse audit findings skip verification (the agent already has full context) and are included as high-confidence results.
 
 ## Deterministic Analysis
 
@@ -127,8 +131,8 @@ This runs in **lightweight mode** — no worktree, no linter, no build/test, no
 
 | Capability                                       | Same-repo | Cross-repo                    |
 | ------------------------------------------------ | --------- | ----------------------------- |
-| LLM review (Agents 1-4 + verify + reverse audit) | ✅        | ✅                            |
-| Agent 5: Build & test                            | ✅        | ❌ (no local codebase)        |
+| LLM review (Agents 1-6 + verify + iterative reverse audit) | ✅        | ✅                            |
+| Agent 7: Build & test                                      | ✅        | ❌ (no local codebase)        |
 | Deterministic analysis (linter/typecheck)        | ✅        | ❌                            |
 | Cross-file impact analysis                       | ✅        | ❌                            |
 | Autofix                                          | ✅        | ❌                            |
@@ -157,6 +161,12 @@ Or, after running `/review 123`, type `post comments` to publish findings withou
 - Nice to have findings (including linter warnings)
 - Low-confidence findings
 
+**Self-authored PRs:** GitHub does not allow you to submit `APPROVE` or `REQUEST_CHANGES` reviews on your own pull request — both fail with HTTP 422. When `/review` detects that the PR author matches the current authenticated user, it automatically downgrades the API event to `COMMENT` regardless of verdict, so the submission still succeeds. The terminal still shows the honest verdict ("Approve" / "Request changes" / "Comment") — only the GitHub-side review event is neutralized. The actual findings still appear as inline comments on specific lines, so substantive feedback is unchanged.
+
+**Re-reviewing a PR with prior Qwen Code comments:** when `/review` runs on a PR that already has previous Qwen Code review comments, it classifies them before posting new ones. Only **same-line overlap** (an existing comment on the same `(path, line)` as a new finding) prompts you to confirm — that's the case where you'd see a visual duplicate on the same code line. Comments from older commits, replied-to comments (treated as resolved), and comments that simply don't overlap with any new finding are silently skipped, with a terminal log line so you know what was filtered.
+
+**CI / build status check before APPROVE:** if the verdict is "Approve", `/review` queries the PR's check-runs and commit statuses before submitting. If any check has failed (or all checks are still pending), the API event is automatically downgraded from `APPROVE` to `COMMENT`, with the review body explaining why. Rationale: the LLM review reads code statically and cannot see runtime test failures; approving while CI is red would be misleading. The inline findings are still posted unchanged. If you want to approve anyway (e.g., a known-flaky CI failure), submit the GitHub approval manually after verifying.
+
 ## Follow-up Actions
 
 After the review, context-aware tips appear as ghost text. Press Tab to accept:
@@ -179,7 +189,7 @@ You can customize review criteria per project. `/review` reads rules from these
 3. `AGENTS.md` — `## Code Review` section
 4. `QWEN.md` — `## Code Review` section
 
-Rules are injected into the LLM review agents (1-4) as additional criteria. For PR reviews, rules are read from the **base branch** to prevent a malicious PR from injecting bypass rules.
+Rules are injected into the LLM review agents (1-6) as additional criteria. For PR reviews, rules are read from the **base branch** to prevent a malicious PR from injecting bypass rules.
 
 Example `.qwen/review-rules.md`:
 
@@ -246,15 +256,17 @@ For large diffs (>10 modified symbols), analysis prioritizes functions with sign
 
 ## Token Efficiency
 
-The review pipeline uses a fixed number of LLM calls regardless of how many findings are produced:
+The review pipeline uses a bounded number of LLM calls regardless of how many findings are produced:
+
+| Stage                            | LLM calls         | Notes                                                |
+| -------------------------------- | ----------------- | ---------------------------------------------------- |
+| Deterministic analysis (Step 3)  | 0                 | Shell commands only                                  |
+| Review agents (Step 4)           | 9 (or 8)          | Run in parallel; Agent 7 skipped in cross-repo mode  |
+| Batch verification (Step 5)      | 1                 | Single agent verifies all findings at once           |
+| Iterative reverse audit (Step 6) | 1-3               | Loops until "No issues found" or 3-round cap         |
+| **Total**                        | **11-13 (10-12)** | Same-repo: 11-13; cross-repo: 10-12 (no Agent 7)     |
 
-| Stage                           | LLM calls  | Notes                                               |
-| ------------------------------- | ---------- | --------------------------------------------------- |
-| Deterministic analysis (Step 3) | 0          | Shell commands only                                 |
-| Review agents (Step 4)          | 5 (or 4)   | Run in parallel; Agent 5 skipped in cross-repo mode |
-| Batch verification (Step 5)     | 1          | Single agent verifies all findings at once          |
-| Reverse audit (Step 6)          | 1          | Finds coverage gaps; findings skip verification     |
-| **Total**                       | **7 or 6** | Same-repo: 7; cross-repo: 6 (no Agent 5)            |
+Most PRs converge to the lower end of the range (1 reverse audit round); the cap prevents runaway cost on pathological cases.
 
 ## What's NOT Flagged
 

package/bundled/qc-helper/docs/features/lsp.md

@@ -40,7 +40,7 @@ You need to have the language server for your programming language installed:
 
 ### .lsp.json File
 
-You can configure language servers using a `.lsp.json` file in your project root. This uses the language-keyed format described in the [Claude Code plugin LSP configuration reference](https://code.claude.com/docs/en/plugins-reference#lsp-servers).
+You can configure language servers using a `.lsp.json` file in your project root. Each top-level key is a language identifier, and its value is the server configuration object.
 
 **Basic format:**
 
@@ -104,9 +104,9 @@ Example:
 
 #### Required Fields
 
-| Option    | Type   | Description                                       |
-| --------- | ------ | ------------------------------------------------- |
-| `command` | string | Command to start the LSP server (must be in PATH) |
+| Option    | Type   | Description                                                                                                                                       |
+| --------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `command` | string | Command to start the LSP server. Supports bare command names resolved via `PATH` (e.g. `clangd`) and absolute paths (e.g. `/opt/llvm/bin/clangd`) |
 
 #### Optional Fields
 
@@ -148,6 +148,8 @@ For servers that use TCP or Unix socket transport:
 
 Qwen Code exposes LSP functionality through the unified `lsp` tool. Here are the available operations:
 
+Location-based operations (`goToDefinition`, `findReferences`, `hover`, `goToImplementation`, and `prepareCallHierarchy`) require an exact `filePath` + `line` + `character` position. If you do not know the exact position, use `workspaceSymbol` or `documentSymbol` first to locate the symbol.
+
 ### Code Navigation
 
 #### Go to Definition
@@ -315,7 +317,7 @@ LSP servers are only started in trusted workspaces by default. This is because l
 - **Trusted Workspace**: LSP servers start if configured
 - **Untrusted Workspace**: LSP servers won't start unless `trustRequired: false` is set in the server configuration
 
-To mark a workspace as trusted, use the `/trust` command or configure trusted folders in settings.
+To mark a workspace as trusted, use the `/trust` command.
 
 ### Per-Server Trust Override
 
@@ -338,11 +340,12 @@ You can override trust requirements for specific servers in their configuration:
 
 ### Server Not Starting
 
-1. **Check if the server is installed**: Run the command manually to verify
-2. **Check the PATH**: Ensure the server binary is in your system PATH
-3. **Check workspace trust**: The workspace must be trusted for LSP
-4. **Check logs**: Look for error messages in the console output
-5. **Verify --experimental-lsp flag**: Make sure you're using the flag when starting Qwen Code
+1. **Verify `--experimental-lsp` flag**: Make sure you're using the flag when starting Qwen Code
+2. **Check if the server is installed**: Run the command manually (e.g. `clangd --version`) to verify
+3. **Check the command**: The server binary must be in your system `PATH`, or specified as an absolute path (e.g. `/opt/llvm/bin/clangd`). Relative paths that escape the workspace are blocked
+4. **Check workspace trust**: The workspace must be trusted for LSP (use `/trust`)
+5. **Check logs**: Look for `[LSP]` entries in the debug log (see Debugging section below)
+6. **Check the process**: Run `ps aux | grep <server-name>` to verify the server process is running
 
 ### Slow Performance
 
@@ -351,41 +354,34 @@ You can override trust requirements for specific servers in their configuration:
 
 ### No Results
 
-1. **Server not ready**: The server may still be indexing
+1. **Server not ready**: The server may still be indexing. For C/C++ projects with clangd, ensure `--background-index` is in the args and a `compile_commands.json` (or `compile_flags.txt`) exists in the project root or a parent directory. Use `--compile-commands-dir=<path>` if it is in a build subdirectory
 2. **File not saved**: Save your file for the server to pick up changes
 3. **Wrong language**: Check if the correct server is running for your language
+4. **Check the process**: Run `ps aux | grep <server-name>` to verify the server is actually running
 
 ### Debugging
 
-Enable debug logging to see LSP communication:
+LSP debug logs are automatically written to session log files in `~/.qwen/debug/`. To check LSP-related entries:
 
 ```bash
-DEBUG=lsp* qwen --experimental-lsp
-```
-
-Or check the LSP debugging guide at `packages/cli/LSP_DEBUGGING_GUIDE.md`.
-
-## Claude Code Compatibility
+# View the latest session log
+grep '\[LSP\]' ~/.qwen/debug/latest
 
-Qwen Code supports Claude Code-style `.lsp.json` configuration files in the language-keyed format defined in the [Claude Code plugins reference](https://code.claude.com/docs/en/plugins-reference#lsp-servers). If you're migrating from Claude Code, use the language-as-key layout in your configuration.
-
-### Configuration Format
+# Common error messages to look for:
+#   "command path is unsafe"  → relative path escapes workspace, use absolute path or add to PATH
+#   "command not found"       → server binary not installed or not in PATH
+#   "requires trusted workspace" → run /trust first
+```
 
-The recommended format follows Claude Code's specification:
+You can also verify the server process is running:
 
-```json
-{
-  "go": {
-    "command": "gopls",
-    "args": ["serve"],
-    "extensionToLanguage": {
-      ".go": "go"
-    }
-  }
-}
+```bash
+ps aux | grep clangd   # or typescript-language-server, jdtls, etc.
 ```
 
-Claude Code LSP plugins can also supply `lspServers` in `plugin.json` (or a referenced `.lsp.json`). Qwen Code loads those configs when the extension is enabled, and they must use the same language-keyed format.
+## Extension LSP Configuration
+
+Extensions can provide LSP server configurations through the `lspServers` field in their `plugin.json`. This can be either an inline object or a path to a `.lsp.json` file. Qwen Code loads these configs when the extension is enabled. The format is the same language-keyed layout used in project `.lsp.json` files.
 
 ## Best Practices
 
@@ -406,7 +402,7 @@ qwen --experimental-lsp
 
 ### Q: How do I know which language servers are running?
 
-Use the `/lsp status` command to see all configured and running language servers.
+Check the debug log for `[LSP]` entries (`grep '\[LSP\]' ~/.qwen/debug/latest`), or verify the process directly with `ps aux | grep <server-name>`.
 
 ### Q: Can I use multiple language servers for the same file type?
 

package/bundled/review/DESIGN.md

@@ -2,20 +2,35 @@
 
 > Architecture decisions, trade-offs, and rejected alternatives for the `/review` skill.
 
-## Why 5 agents + 1 verify + 1 reverse, not 1 agent?
+## Why 9 agents + 1 verify + iterative reverse, not 1 agent?
 
 **Considered:**
 
 - **1 agent (Copilot approach):** Single agent with tool-calling, reads and reviews in one pass. Cheapest (1 LLM call). But dimensional coverage depends entirely on one prompt's attention — easy to miss performance issues while focused on security.
-- **5 parallel agents (chosen):** Each agent focuses on one dimension. Higher coverage through forced diversity of perspective. Cost: 5 LLM calls, but they run in parallel so wall-clock time is similar to 1 agent.
+- **5 parallel agents (original design):** Each agent focuses on one dimension. Higher coverage through forced diversity of perspective. Limited by combined Correctness+Security and a single undirected pass — recall ceiling left findings on the table that the user only discovered in subsequent /review rounds.
+- **9 parallel agents (current):** 6 review dimensions (Correctness, Security, Code Quality, Performance, Test Coverage, Undirected) + Build & Test. Undirected runs as 3 personas in parallel.
 
-**Decision:** 5 agents. The marginal cost (5x vs 1x) is acceptable because:
+**Decision:** 9 agents. The marginal cost (9x vs 1x) is acceptable because:
 
-1. Parallel execution means time cost is ~1x (all 5 agents must launch in one response)
+1. Parallel execution means time cost is ~1x (all 9 agents launch in one response)
 2. Dimensional focus produces higher recall (fewer missed issues)
-3. Agent 4 (Undirected Audit) catches cross-dimensional issues
+3. Three undirected personas (attacker / 3am-oncall / maintainer) catch cross-dimensional issues that a single undirected agent's prompt-induced bias would miss
 4. The "Silence is better than noise" principle + verification controls precision
 
+### Why split Correctness from Security
+
+A single Correctness+Security agent has split attention — empirically one dimension dominates the output and the other is shallow. Different mindsets too: correctness asks "does this do what it intends," security asks "what unintended thing can a hostile actor make this do." Splitting forces both to get full attention.
+
+### Why a dedicated Test Coverage agent
+
+Test gaps are a systematic blind spot. Review agents focused on bugs in the new code itself rarely look at whether the change came with adequate tests. A dedicated agent that asks "what scenarios in this diff are untested?" catches misses no other dimension hits.
+
+### Why three undirected personas instead of one or many
+
+A single undirected agent has prompt-induced bias and tends to find the same kinds of issues across runs. Three personas — attacker / 3am-oncall / maintainer — force completely different mental traversals, and the union of findings is meaningfully larger than 1.5× a single agent.
+
+Empirically, ensemble diversity drops sharply past 3-5 sampled paths. Three is the sweet spot: enough to break single-prompt bias, few enough that the marginal cost stays bounded.
+
 ## Why batch verification instead of N independent agents?
 
 **Considered:**
@@ -25,16 +40,46 @@
 
 **Decision:** Batch. The quality difference is minimal — a single agent verifying 15 findings has MORE context than 15 independent agents (sees cross-finding relationships). Cost drops from O(N) to O(1).
 
-## Why reverse audit is a separate step, not merged with verification
+## Why reverse audit is a separate step, and why iterative
 
-**Considered:**
+### Why separate from verification
 
 - **Merge with verification:** Verification agent also looks for gaps. Saves 1 LLM call.
 - **Separate step (chosen):** Reverse audit is a full diff re-read, not a finding check. Different cognitive task.
 
-**Decision:** Separate. Verification is targeted (check specific claims at specific locations). Reverse audit is open-ended (scan entire diff for missed issues). Combining overloads one agent with two fundamentally different tasks, degrading both.
+Verification is targeted (check specific claims at specific locations). Reverse audit is open-ended (scan entire diff for missed issues). Combining overloads one agent with two fundamentally different tasks, degrading both.
+
+### Why iterative (multi-round)
+
+A single reverse audit pass leaves whatever the reverse audit agent itself missed. Each new round receives the cumulative finding list from prior rounds, so it focuses on what's left undiscovered. Empirically, most PRs converge in 1-2 rounds; the 3-round hard cap prevents runaway cost on pathological cases.
+
+### Why cap at 3 rounds, not unlimited
+
+Diminishing returns. Past round 3, the marginal yield is low and a stuck-loop hazard rises (the model may fabricate issues to satisfy the "find more" framing). The "No issues found" termination already exits early on most PRs — the cap is a safety net, not the common path.
 
-**Optimization:** Reverse audit findings skip verification. The reverse audit agent already has full context (all confirmed findings + entire diff), so its output is inherently high-confidence. This keeps total calls at 7, not 8.
+**Optimization preserved:** Reverse audit findings skip verification (across all rounds). The agent has full context, so output is inherently high-confidence.
+
+## Why low-confidence over rejection on uncertain findings
+
+**Original behavior:** When verification was uncertain, it would reject. Bias toward precision.
+
+**Problem:** Uncertain findings often turn out to be real after human inspection. Rejection silently swallows valid concerns. Users discover them in the next iteration of /review or after merging — exactly the "iterate many rounds" pain this redesign targets.
+
+**Current behavior:** Uncertain → "confirmed (low confidence)". Low-confidence findings:
+
+- Appear in terminal output under "Needs Human Review"
+- Are filtered out of PR inline comments (preserves "Silence is better than noise" for PR interactions)
+- Do not affect the verdict (Approve/Request changes/Comment is computed from high-confidence findings only)
+
+**Trade-off:** Terminal output gets noisier. PR comments stay clean. The user sees concerns without the cost of false-positive PR noise.
+
+**Reserved for outright rejection:**
+
+- Finding describes behavior the code does not actually have (factually wrong about the code)
+- Finding matches an Exclusion Criterion (pre-existing issue, formatting nitpick, etc.)
+- Vague suspicion with no concrete code reference
+
+This boundary keeps the low-confidence bucket meaningful — it's "likely real but needs human judgment," not "I have no idea."
 
 ## Why worktree instead of stash + checkout
 
@@ -59,6 +104,76 @@ Applied throughout:
 - Uncertain issues → rejected, not reported
 - Pattern aggregation → same issue across N files reported once
 
+## Why classify existing Qwen Code comments instead of always prompting
+
+**Original behavior:** any existing Qwen Code review comment on the PR → inform the user and require confirmation before posting new comments.
+
+**Problem:** in real /review usage, most existing Qwen Code comments fall into one of three "no-real-conflict" cases:
+
+1. **Stale by commit**: the comment was posted against an older PR HEAD; the underlying code has changed.
+2. **Resolved by reply**: someone has replied in the thread (the original author "fixed in abc123" or a reviewer "ok, approved"). The conversation is closed.
+3. **No anchor overlap**: the old comment is on a different `(path, line)` from any new finding. They simply coexist.
+
+Forcing the user to confirm-or-decline every time the PR has any Qwen Code history creates prompt fatigue without protecting against the real risk — which is **commenting twice on the same line**, producing visual duplicates that look like a bug to PR readers.
+
+**New behavior:** classify each existing Qwen Code comment by checking in priority order — **Stale by commit** > **Resolved by reply** > **Overlap** (same `path + line` as a new finding) > **No conflict**. The first match wins. Only the Overlap class blocks; the other three log to the terminal and continue.
+
+**Priority matters because** a stale or resolved comment that happens to share a `(path, line)` with a new finding is not a real conflict — the underlying code may have changed in the stale case, and the conversation is already closed in the resolved case. Without priority, the line-based check would fire false-positive prompts on those.
+
+**Trade-off:**
+- ✅ Common case (re-running /review on a PR after a few new commits) no longer prompts unnecessarily.
+- ✅ The terminal log keeps the user informed about what was skipped, so transparency is preserved.
+- ❌ Conceptual overlap that doesn't share a line is missed — e.g. a prior comment on line 559 about cache lifecycle and a new comment on line 1352 about cache lifecycle would be classified `No conflict`. Line-based heuristics cannot detect "same root cause, different anchor." If the user wants semantic-overlap detection, they must read the terminal log and the PR comments themselves.
+
+Line-based classification was chosen because it's deterministic, cheap, and catches the precise UX failure (visual duplicate at the same line). Semantic overlap detection would require an extra LLM call for what is, in practice, a rare edge case.
+
+## Why downgrade APPROVE when CI is non-green
+
+**Original behavior:** if Step 7 resolved verdict to `APPROVE`, the API event was submitted as `APPROVE` without any check on CI status.
+
+**Problem:** the LLM review pipeline reads the diff and surrounding code statically. It does not run tests, does not exercise integration boundaries, and does not see runtime failures. CI does. A PR with red CI but no static red flags is **the worst case** for an LLM `APPROVE` — the human reader sees an Approve badge from a tool that didn't actually verify the change runs.
+
+**Current behavior:** before submitting `APPROVE`, query `check-runs` and legacy commit `statuses` for the PR HEAD. Classify:
+
+- All success → `APPROVE` continues.
+- Any failure → downgrade `APPROVE` to `COMMENT`, body explains.
+- All pending → downgrade to `COMMENT` (don't approve before CI decides), body explains.
+
+**Why downgrade rather than block:** the reviewer LLM has done substantive work; throwing the review away because CI is red wastes that. Downgrading to `COMMENT` keeps all inline findings, preserves the static review value, and lets GitHub's check status carry the "do not merge" signal naturally.
+
+**Why this stacks with self-PR downgrade:** a self-authored PR with red CI hits **both** downgrade rules. The event is `COMMENT` either way, so stacking is operationally a no-op — but the body should mention both reasons so a future maintainer reading the review knows why an LLM that found no Critical issues did not approve.
+
+**Trade-off:**
+- ✅ No more "LLM approved while CI is red" embarrassments.
+- ✅ Reviewer's substantive work (inline comments) is preserved.
+- ❌ Adds two extra API calls (`check-runs` + `statuses`) per APPROVE-bound submit; only relevant for the `APPROVE` path so the cost is negligible.
+- ❌ A genuinely flaky CI failure can downgrade what should have been an Approve. Mitigation: the body text directs the user to verify; they can always submit `APPROVE` manually after triaging.
+
+## Why the deterministic checks live as `qwen review` subcommands
+
+**Original behavior:** Step 9's three pre-submission checks (self-PR detection, CI status, existing-comment classification) and Step 11's cleanup were inlined in SKILL.md as `gh api` / `git` shell commands. The LLM ran each command itself, parsed the output, and applied the classification logic.
+
+**Problems with inlining:**
+
+1. **Token cost**: each command, jq filter, classification rule, and output schema is part of the prompt — every `/review` invocation pays this cost.
+2. **Drift risk**: the classification logic exists twice (in the prompt's English description, and in whatever the LLM internally synthesizes). When rules change (new check_run conclusion type, new comment bucket), both have to update or they drift.
+3. **Cross-platform fragility**: `/tmp/qwen-review-*` worked on macOS shell but Node's `os.tmpdir()` returned `/var/folders/...`. The mismatch only surfaced when the cleanup logic was tested.
+4. **Testability**: prompt text isn't unit-testable. Logic that classifies CI states or comment buckets is the kind of thing that benefits from real assertions.
+
+**Current behavior:** the deterministic logic lives in `packages/cli/src/commands/review/` as TypeScript subcommands of the `qwen` CLI:
+
+- `qwen review presubmit <pr> <sha> <owner/repo> <out>` — emits a single JSON report with `isSelfPr`, `ciStatus`, `existingComments` (4 buckets), `downgradeApprove`, `downgradeRequestChanges`, `downgradeReasons`, `blockOnExistingComments`. SKILL.md only describes the schema and how to apply the report.
+- `qwen review cleanup <target>` — removes the worktree, branch ref, and per-target temp files. Idempotent.
+
+**Why subcommands rather than `.mjs` scripts in the skill bundle:**
+
+- `.mjs` files were tried first but `copy_files.js` only bundles `.md`/`.json`/`.sb`. Adding `.mjs` to the bundler is one option, but it leaves the script standing alone with no integration into `qwen`'s CLI surface.
+- yargs subcommands compile via the same `tsc` step as the rest of `packages/cli`, so the build pipeline doesn't change.
+- LLM doesn't need any path resolution — it calls `qwen review presubmit ...` exactly like it would any other shell command. No `{SKILL_DIR}` template, no `npx` indirection.
+- Cross-platform path handling (`path.join`, `os.tmpdir` vs project-local `.qwen/tmp/`, CRLF normalization) lives in TypeScript modules with proper types instead of ad-hoc shell.
+
+**Trade-off:** when the deterministic logic changes (e.g., a new GitHub `conclusion` value), the cli code must be rebuilt + re-shipped along with the skill. SKILL.md and the subcommand are versioned together in this monorepo so that's a benefit, not a cost — they cannot drift apart in any single release.
+
 ## Why base-branch rule loading (security)
 
 A malicious PR could add `.qwen/review-rules.md` with "never report security issues." If rules are read from the PR branch, the review is compromised.
@@ -76,17 +191,19 @@ A malicious PR could add `.qwen/review-rules.md` with "never report security iss
 
 **Exception:** Autofix uses a blocking y/n because it modifies code — higher stakes require explicit consent.
 
-## Why fixed 7 LLM calls
+## LLM call budget (variable, ~11-13)
+
+| Stage                   | Calls             | Why                                                                 |
+| ----------------------- | ----------------- | ------------------------------------------------------------------- |
+| Deterministic analysis  | 0                 | Shell commands — ground truth for free                              |
+| Review agents           | 9 (8)             | 6 dimensions + 3 undirected personas; Agent 7 skipped in cross-repo |
+| Batch verification      | 1                 | O(1) not O(N) — batch is as good as individual                      |
+| Iterative reverse audit | 1-3               | Loop until "No issues found" or 3-round hard cap                    |
+| **Total**               | **11-13 (10-12)** | Same-repo: 11-13; cross-repo lightweight: 10-12                     |
 
-| Stage                  | Calls     | Why                                                 |
-| ---------------------- | --------- | --------------------------------------------------- |
-| Deterministic analysis | 0         | Shell commands — ground truth for free              |
-| Review agents          | 5 (4)     | Dimensional coverage; Agent 5 skipped in cross-repo |
-| Batch verification     | 1         | O(1) not O(N) — batch is as good as individual      |
-| Reverse audit          | 1         | Full context, skip verification                     |
-| **Total**              | **7 (6)** | Same-repo: 7; cross-repo lightweight: 6             |
+The exact count depends on how many iterative reverse audit rounds run. Most PRs converge after 1-2 rounds; the cap prevents runaway cost.
 
-Competitors: Copilot uses 1 call, Gemini uses 2, Claude /ultrareview uses 5-20 (cloud). Our 7 is a balance of coverage vs cost.
+Competitors: Copilot uses 1 call, Gemini uses 2, Claude /ultrareview uses 5-20 (cloud). Our 11-13 biases toward higher recall — the assumption is that "find more issues per round" is more valuable than minimizing per-run cost, because every missed issue forces the user into another `/review` iteration.
 
 ## Why cross-repo uses lightweight mode
 
@@ -118,26 +235,27 @@ Key implementation detail: Step 9 must use the owner/repo extracted from the URL
 | `gh pr checkout --detach` for worktree                       | It modifies the current working tree, defeating the purpose of worktree isolation.                                        |
 | Shell-like tokenizer for argument parsing                    | LLM handles quoted arguments naturally from conversation context.                                                         |
 | Model attribution via LLM self-identification                | Unreliable (hallucination risk). `{{model}}` template variable from `config.getModel()` is accurate.                      |
-| Verbose agent prompts (no length limit)                      | 5 long prompts exceed output token budget → model falls back to serial. Each prompt must be ≤200 words for parallel.      |
+| Verbose agent prompts (no length limit)                      | 9 long prompts exceed output token budget → model falls back to serial. Each prompt must be ≤200 words for parallel.      |
 | Relaxed parallel instruction ("if you can't fit 5, try 3+2") | Model always takes the fallback. Strict "MUST include all in one response" is required.                                   |
 
 ## Token cost analysis
 
 For a PR with 15 findings:
 
-| Approach                        | LLM calls | Notes                           |
-| ------------------------------- | --------- | ------------------------------- |
-| Copilot (1 agent)               | 1         | Lowest cost, lowest coverage    |
-| Gemini (2 LLM tasks)            | 2         | Good cost, medium coverage      |
-| Our design (original, N verify) | 21        | 5+15+1 — too expensive          |
-| Our design (batch verify)       | 7         | 5+1+1 — fixed, good coverage    |
-| Claude /ultrareview             | 5-20      | Cloud-hosted, cost on Anthropic |
+| Approach                                            | LLM calls | Notes                                                |
+| --------------------------------------------------- | --------- | ---------------------------------------------------- |
+| Copilot (1 agent)                                   | 1         | Lowest cost, lowest coverage                         |
+| Gemini (2 LLM tasks)                                | 2         | Good cost, medium coverage                           |
+| Our design (5 agents, N verify)                     | 21        | 5+15+1 — too expensive                               |
+| Our design (5 agents, batch verify, single reverse) | 7         | 5+1+1 — original design                              |
+| Our design (9 agents, iterative reverse, current)   | 11-13     | 9+1+(1-3) — +50% cost for meaningfully higher recall |
+| Claude /ultrareview                                 | 5-20      | Cloud-hosted, cost on Anthropic                      |
 
 ## Future optimization: Fork Subagent
 
 > Dependency: [Fork Subagent proposal](https://github.com/wenshao/codeagents/blob/main/docs/comparison/qwen-code-improvement-report-p0-p1-core.md#2-fork-subagentp0)
 
-**Current problem:** Each of the 7 LLM calls (5 review + 1 verify + 1 reverse) creates a new subagent from scratch. The system prompt (~50K tokens) is sent independently to each, totaling ~350K input tokens with massive redundancy.
+**Current problem:** Each of the 11-13 LLM calls (9 review + 1 verify + 1-3 reverse audit rounds) creates a new subagent from scratch. The system prompt (~50K tokens) is sent independently to each, totaling ~550-650K input tokens with massive redundancy. The cost grew along with the agent count — Fork Subagent matters more under the current 9-agent design than under the original 5-agent design.
 
 **Fork Subagent solution:** Instead of creating independent subagents, fork the current conversation. All forks inherit the parent's full context (system prompt, conversation history, Step 1/1.1/1.5 results) and share a prompt cache prefix. The API caches the common prefix once; each fork only pays for its unique delta (~2K per agent).
 
@@ -145,13 +263,13 @@ For a PR with 15 findings:
 Current (independent subagents):
   Agent 1: [50K system] + [2K task]  = 52K
   Agent 2: [50K system] + [2K task]  = 52K
-  ...× 7 agents                     = ~350K total input tokens
+  ...× 11-13 agents                 = ~570-680K total input tokens
 
 With Fork + prompt cache sharing:
   Cached prefix: [50K system + conversation history]  (cached once)
   Fork 1: [cache hit] + [2K delta]   = ~2K effective
   Fork 2: [cache hit] + [2K delta]   = ~2K effective
-  ...× 7 forks                       = ~50K cached + ~14K delta = ~65K total
+  ...× 11-13 forks                  = ~50K cached + ~22-26K delta = ~72-76K total
 ```
 
 **Additional benefits for /review:**
@@ -159,7 +277,8 @@ With Fork + prompt cache sharing:
 - Forked agents inherit Step 3 linter results, PR context, review rules — no need to repeat in each agent prompt
 - SKILL.md workaround "Do NOT paste the full diff into each agent's prompt" becomes unnecessary — fork already has the context
 - Verification and reverse audit agents inherit all prior findings naturally
+- Agent 6 personas can fork from a shared diff-loaded base, paying only the persona-framing delta
 
-**Estimated savings:** ~65% token reduction (350K → ~120K) with zero quality impact.
+**Estimated savings:** ~85-90% token reduction (~620K → ~75K) with zero quality impact. The savings ratio is now even more compelling than under the 5-agent design.
 
 **Why not implemented now:** Fork Subagent requires changes to the Qwen Code core (`AgentTool`, `forkSubagent.ts`, `CacheSafeParams`). This is a platform-level feature (~400 lines, ~5 days), not a /review-specific change. When available, /review should be updated to use fork instead of independent subagents.