@fyeeme/pi-review 2.0.0 → 2.1.0

package/skills/code-review/SKILL.md

@@ -1,16 +1,58 @@
 ---
 name: code-review
-description: "Review the current diff for correctness bugs and reuse/simplification/efficiency cleanups at the given effort level. Fresh reverse of CC `/code-review` (CLI v2.1.223). Effort semantics: medium = precision, high+ = recall. Pass --fix to apply, --comment to post inline PR comments, --share to publish a review page."
+description: "Review the current diff, or a PR number/branch/path target, for correctness bugs and reuse/simplification/efficiency cleanups at the given effort level (low/medium/high: single-pass in-session review — medium precision, high recall; xhigh/max: subagent fan-out deep sweep). Fresh reverse of CC `/review` (its own name there is `code-review`), re-verified against CLI v2.1.261 (2026-09-05; originally reversed from v2.1.223). Effort semantics: medium = precision, high+ = recall. Pass --fix to apply, --loop to cycle fix→re-review until no P0/P1 findings remain, --comment to post findings (GitHub inline / GitLab MR note), --share to publish a review page."
 ---
 
 <!--
-  Origin: Claude Code built-in skill `/code-review` (CLI v2.1.223), freshly
+  Origin: Claude Code built-in skill `/review` (CLI v2.1.223), freshly
   reverse-engineered 2026-08-06 from bin/claude.exe strings. This file is
   sourced DIRECTLY from the 2.1.223 binary — NOT carried forward from the
   earlier v2.1.220 reconstruction. Every section below was located in the
   extracted strings (cc_strings_223.txt) and verified.
 
-  What CC 2.1.227 actually contains (verified against the binary):
+  ── v2.1 redesign: effort split (single-pass default) ──
+    - low/medium/high → SINGLE-PASS FLOW in the main session (no subagents):
+      rubric-ported flag criteria, P0–P3 priorities, in-session self-verify.
+      Rationale: the medium+ fan-out pipeline (8–10 finder subprocesses +
+      grouped verifiers) cost tens of minutes per run and returned zero
+      findings when spawned subprocesses failed to boot — unacceptable ROI
+      for the default path.
+    - xhigh/max keep the fan-out pipeline unchanged (opt-in deep sweep).
+    - NEW --loop: extension-driven fix→re-review rounds (≤ maxTurns.loop,
+      default 3) until no P0/P1 findings remain; blocking decisions read
+      the structured review_report JSON (never markdown scraping).
+    - review_report findings gained an optional `priority` (P0–P3).
+
+  ── RE-VERIFIED against CLI v2.1.261 (bin/claude.exe raw bytes, 2026-09-05) ──
+    - The 2.1.217-era background Workflow (phases Scope/Find/Verify/Sweep/
+      Synthesize) is GONE — the phase prompts now live inline in the skill
+      and dispatch via the Agent tool; per the bundled changelog, high/
+      xhigh/max now run inside a background agent (a CC host capability Pi
+      has no counterpart for — Pi runs inline in the session).
+    - 2.1.261 ships flag-gated effort variants (e.g. an inline, dedup-only
+      xhigh WITHOUT verify, alongside the fan-out + 1-vote-verify shape).
+      This skill keeps the uniform linearization: medium+ = fan-out +
+      grouped verify; sweep at xhigh/max.
+    - Angle bodies A–E and Reuse/Simplification/Efficiency/Conventions are
+      byte-identical to what we carried; **Altitude** gained CC's
+      root-cause phrasing + "name that change" (synced below).
+    - NEW sweep focus list ("what the first pass tends to miss") — synced
+      into Phase 3 and agents/gap-hunter.md.
+    - --comment gained GitLab: ONE general MR note via `glab mr note`
+      (glab has no single verb for line-anchored comments); GitHub inline
+      falls back to `gh api repos/{owner}/{repo}/pulls/{pr}/comments`,
+      suggestion block only when it fully fixes the issue — synced below.
+    - Output contract unchanged: {level, findings} with file/line/summary/
+      short_summary(≤60)/failure_scenario/category/verdict; outcome 三档
+      fixed / skipped / no_change_needed on re-report — all still match.
+      NEW: CC forbids creating/publishing an artifact of the review ("the
+      tool call is the report"); Pi keeps --share as the explicit opt-in
+      and forbids UNSOLICITED artifacts instead.
+    - `ultra` (deep multi-agent cloud review) still exists upstream; still
+      omitted here (requires claude.ai cloud access, which Pi lacks).
+      Sticky last-effort (codeReviewLastEffort) unchanged.
+
+  What CC 2.1.227 contained (historical basis, verified 2026-08-11):
     - Effort quad tuple {correctnessAngles, perAngle, maxFindings, sweep}:
       medium {3,6,8,false} / high {3,6,10,false} / xhigh {5,8,15,true} / max
       same structure as xhigh. medium = precision; high+ = recall
@@ -32,8 +74,10 @@ description: "Review the current diff for correctness bugs and reuse/simplificat
     - Fixed-later obligation (CC Q8m): later fixes in the session must
       re-report findings with updated outcome.
 
-  Invocation: /code-review [low|medium|high|xhigh|max] [--fix] [--comment] [--share] [<target>]
+  Invocation: /code-review [low|medium|high|xhigh|max] [--fix] [--loop] [--comment] [--share] [<target>]
     target = Class#method | file path | PR number | branch name
+    --loop = extension-driven fix→re-review rounds (single-pass levels only,
+    ≤ maxTurns.loop, default 3) until no P0/P1 findings remain
     With no level given, the /code-review HANDLER reuses the last level you
     typed (CC 2.1.223 codeReviewLastEffort); the skill always receives a
     concrete level.
@@ -53,20 +97,30 @@ description: "Review the current diff for correctness bugs and reuse/simplificat
                   Markdown as text.
     2. Fan-out  — CC uses the Agent tool; Pi uses the `subagent` tool
                   (mode: parallel), or runs angles sequentially if unavailable.
+                  v2.1: fan-out is the XHIGH/MAX path only — low/medium/high
+                  run as a single pass in the main session (no subagents).
     3. Verify   — CC uses the Agent tool; Pi uses `subagent` for the
                   independent verify agent (fallback: self-check).
-    4. Workflow — CC routes high/xhigh/max to a background Workflow (phases
-                  Scope/Find/Verify/Sweep/Synthesize) when workflows are
-                  enabled; Pi has no such tool, so this skill runs INLINE and
-                  linearizes those phases into the flow below.
+    4. Workflow — CC 2.1.217 routed high/xhigh/max to a background Workflow
+                  (phases Scope/Find/Verify/Sweep/Synthesize); 2.1.261 removed
+                  it and runs the phases inline via its Agent tool, with high+
+                  inside a background agent. Pi has neither host capability, so
+                  this skill runs INLINE and linearizes those phases into the
+                  flow below; the Phase 0.5 scope block is our absorption of
+                  the old workflow's Scope phase (kept: it still turns N
+                  repeated subagent discoveries into one).
     5. ultra    — dropped (cloud-only).
-    6. --share  — CC uses the Artifact tool; Pi uses lavish-axi.
-    7. --comment— CC uses mcp__github_inline_comment; Pi falls back to gh api
-                  or printing.
-
-  Prerequisite: the `subagent` tool (pi-review extension; mode: parallel) for
-                medium and above, and for the xhigh/max gap-hunter. lavish-axi
-                for --share. low runs standalone (no subagents).
+    6. --share  — CC uses the Artifact tool; Pi uses lavish-axi. CC 2.1.261
+                  forbids UNSOLICITED review artifacts; --share stays the
+                  explicit opt-in.
+    7. --comment— CC uses mcp__github_inline_comment (fallback `gh api`) and
+                  posts GitLab MRs as one general note via `glab mr note`; Pi
+                  mirrors both fallbacks (see the --comment section).
+
+  Prerequisite: the `subagent` tool (@fyeeme/pi-subagents; parallel mode) for
+                xhigh/max only (finder/verifier/gap-hunt fan-out). lavish-axi
+                for --share. low/medium/high run standalone in this session
+                (no subagents).
 -->
 
 You are reviewing the current diff for correctness bugs and reuse /
@@ -75,22 +129,30 @@ altitude, and conventions findings when the output cap forces a cut.
 
 ## Effort levels
 
-| Level | Intent | Verify | Subagents | 四元组 `{correctnessAngles, perAngle, maxFindings, sweep}` |
+| Level | Path | Intent | Verify | Cap |
 |-------|--------|--------|-----------|------------|
-| low (default) | quick scan | no | no | 上限 `min(files_changed, 4)` |
-| medium | **precision** — surface only findings a maintainer would act on | independent verifier (grouped) | 8 finders | `{3, 6, 8, false}` |
-| high | **recall** — catch every real bug a careful reviewer would; **err on the side of surfacing** | recall-biased verifier (grouped) | 8 finders | `{3, 6, 10, false}` |
-| xhigh | recall + **gap-hunt** | recall-biased verifier (grouped) | 10 finders + 1 gap | `{5, 8, 15, true}` |
-| max | 同 xhigh | 同 xhigh | 同 xhigh | 同 xhigh |
+| low (default) | SINGLE-PASS | quick scan | no | `min(files_changed, 4)` |
+| medium | SINGLE-PASS | **precision** — surface only findings a maintainer would act on | self-verify (in-session) | 8 |
+| high | SINGLE-PASS | **recall** — catch every real bug a careful reviewer would; **err on the side of surfacing** | self-verify (in-session) | 10 |
+| xhigh | FAN-OUT (below) | recall + **gap-hunt** | independent verifier agents (grouped) | `{5, 8, 15, true}` |
+| max | FAN-OUT（同 xhigh） | 同 xhigh | 同 xhigh | 同 xhigh |
+
+**low/medium/high never dispatch subagents** — one pass in this session:
+read the diff (Turn 1), surface candidates against the rubric (Turn 2),
+self-verify them (Turn 3, medium/high only), report (Turn 4). This is the
+default path: the 8–10 finder + grouped-verifier pipeline cost tens of
+minutes per run and twice produced zero findings when spawned subprocesses
+failed to boot — unacceptable ROI for a daily-driver review.
 
 **max 与 xhigh 结构相同**：fan-out / verify / sweep 完全一致，差别仅在模型 reasoning effort（CC v2.1.226 注释实证：`max → same structure as xhigh (the API reasoning effort differs, not the fan-out)`）。若运行时不支持调节 reasoning effort，max 在结构上退化为 xhigh——不要因档名而期待更多 fan-out。
 
-The quad tuple parameterizes the whole pipeline (CC inline semantics, verified 2.1.227):
+The quad tuple parameterizes the XHIGH/MAX fan-out only (CC inline semantics,
+verified 2.1.227):
 
-- `correctnessAngles` — how many correctness angles A–E run, taken **in order** (medium/high: A/B/C; xhigh/max: A–E).
-- `perAngle` — candidate cap per finder (6 at medium/high, 8 at xhigh/max).
-- `maxFindings` — the report cap after verify (8 / 10 / 15).
-- `sweep` — whether Phase 3 gap-hunt runs (xhigh/max only, ≤ 8 new candidates).
+- `correctnessAngles` — 5 at xhigh/max (angles A–E all run).
+- `perAngle` — candidate cap per finder (8).
+- `maxFindings` — the report cap after verify (15).
+- `sweep` — whether Phase 3 gap-hunt runs (≤ 8 new candidates).
 
 Each finder surfaces up to `perAngle` candidate findings with `file`, `line`, a
 one-line `summary`, a ≤60-char `short_summary`, and a concrete
@@ -141,62 +203,160 @@ actions based on it>
 ```
 
 Embed this block verbatim at the top of **every** finder / verifier / gap-hunt
-subagent prompt. Subagents do not re-discover the diff or CLAUDE.md; the
-target argument travels as a scope constraint only, never as an instruction to
-a subagent.
+subagent prompt (XHIGH/MAX FLOW). Subagents do not re-discover the diff or
+CLAUDE.md; the target argument travels as a scope constraint only, never as an
+instruction to a subagent. In the SINGLE-PASS FLOW, keep the assembled block
+as your own working notes — conventions come from it, not from re-discovery.
 
 ---
 
-# LOW-EFFORT FLOW  (default; runs standalone, no subagents)
+# SINGLE-PASS FLOW  (default: low / medium / high — no subagents)
+
+You review the diff yourself, in this session. Do NOT dispatch finder or
+verifier agents at these levels, even if the `subagent` tool is available.
 
-`low effort → 1 diff pass → no verify → min(files_changed, 4) findings`
+- `low` — 1 diff pass, no self-verify, cap `min(files_changed, 4)`.
+- `medium` — 1 pass + self-verify, cap 8, **precision**.
+- `high` — 1 pass + self-verify, cap 10, **recall**.
 
 ## Turn 1 — read
 
 One tool call: read the unified diff (`git diff @{upstream}...HEAD; git diff HEAD`
 to cover both committed and uncommitted changes, or `git diff main...HEAD` / the
-target passed as an argument). Skip test/fixture hunks (`test/`, `spec/`,
-`__tests__/`, `*_test.*`, `*.test.*`, `fixtures/`, `testdata/`) — test-file
-changes are not reviewed at this level. No subagents, no full-file reads.
-
-## Turn 2 — findings
-
-Flag runtime-correctness bugs visible from the hunk alone: inverted/wrong
-condition, off-by-one, null/undefined deref where adjacent lines show the value
-can be absent, removed guard, falsy-zero check, missing `await`,
-wrong-variable copy-paste, error swallowed in a catch that should propagate.
-Also flag — still from the hunk alone — new code that duplicates an existing
-helper visible in the diff context, and dead code the diff leaves behind.
-
-Do **not** flag style, naming, perf, missing tests, or anything outside the hunk.
-
-Target **min(files_changed, 4) findings**, most-severe first. If you have fewer,
-do one more pass focused on the largest changed file and on any **removed** code
-blocks. Output exactly `(none)` only if the diff is trivially correct after
-that pass.
-
-Low 档输出契约是**双变体**（与 CC 的 `p$p`/`d$p` 一致）：若 `review_report` 工具可用（本扩展已注册），调用它**一次**上报 `{level: "low", fanned_out: false, findings}`，每条 finding 带 `file` / `line` / `summary` / `short_summary`（≤60 字符）/ `failure_scenario`；无发现时传空数组。不要重复打印文本——工具负责渲染。若 `review_report` 不可用，改为纯文本输出：每行 `path/to/file.ext:123 — 问题与失败后果`，无发现输出 `(none)`，不调用任何上报工具。
+target passed as an argument). At low, skip test/fixture hunks (`test/`,
+`spec/`, `__tests__/`, `*_test.*`, `*.test.*`, `fixtures/`, `testdata/`) —
+test-file changes are not reviewed at that level; medium/high include them.
+Then read the enclosing function for each nontrivial hunk; the applicable
+CLAUDE.md conventions are already pinned in the Phase 0.5 scope block.
+
+## Turn 2 — candidates (the rubric)
+
+Work the finder angles inline — their definitions live in the XHIGH/MAX FLOW
+below and are shared with the subagent definitions:
+
+- **low** — Angle A over the hunks only: runtime-correctness bugs visible
+  from the hunk alone (inverted/wrong condition, off-by-one, null/undefined
+  deref where adjacent lines show the value can be absent, removed guard,
+  falsy-zero check, missing `await`, wrong-variable copy-paste, error
+  swallowed in a catch that should propagate), plus new code duplicating an
+  existing helper visible in the diff context, plus dead code the diff leaves
+  behind. Do **not** flag style, naming, perf, missing tests, or anything
+  outside the hunk. If you have fewer than the cap, do one more pass focused
+  on the largest changed file and on any **removed** code blocks. Output
+  exactly `(none)` only if the diff is trivially correct after that pass.
+- **medium** — Angles A, B, C, then a quick Reuse / Simplification /
+  Efficiency pass over the changed code.
+- **high** — the full angle set: A–E, then Reuse / Simplification /
+  Efficiency / Altitude / Conventions.
+
+Flag issues that (rubric ported from the reference /review implementation):
+
+1. Meaningfully impact the accuracy, performance, security, or
+   maintainability of the code.
+2. Are discrete and actionable (not general issues or multiple combined
+   issues).
+3. Don't demand rigor inconsistent with the rest of the codebase.
+4. Were introduced in the changes being reviewed (not pre-existing bugs).
+5. The author would likely fix if made aware of them.
+6. Don't rely on unstated assumptions about the codebase or the author's
+   intent.
+
+Every candidate carries `file`, `line`, `category`, a one-line `summary`, a
+≤60-char `short_summary`, a concrete `failure_scenario`, and a **priority**
+(`--loop` treats P0/P1 as blocking):
+
+- **P0** — data loss, security hole, crash on a main path, broken build.
+- **P1** — real bug on a plausible path; broken invariant with visible
+  effect.
+- **P2** — worthwhile cleanup (duplication, wasted work, wrong altitude) or
+  an uncertain-trigger correctness issue.
+- **P3** — nice-to-have.
+
+Correctness outranks cleanup when the cap forces a cut.
+
+## Turn 3 — self-verify (medium / high; low skips)
+
+Re-read every candidate against the code once, in this session:
+
+- Drop anything whose `failure_scenario` you cannot make concrete.
+- Set the verdict: **`CONFIRMED`** — you can name the inputs/state that
+  trigger it and the wrong output or crash (quote the line); **`PLAUSIBLE`**
+  — the mechanism is real but the trigger is uncertain (timing, env,
+  config); state what would confirm it.
+- **`PLAUSIBLE` by default** — do not drop a candidate for being
+  "speculative" or "depends on runtime state" when the state is realistic:
+  concurrency races, nil/undefined on a rare-but-reachable path (error
+  handler, cold cache, missing optional field), falsy-zero treated as
+  missing, off-by-one on a boundary the code does not exclude, retry storms
+  / partial failures, regex/allowlist that lost an anchor.
+- At medium (precision), additionally drop what a maintainer would not act
+  on. At high (recall), keep every surviving candidate — a missed bug ships.
+
+## Turn 4 — report
+
+Report via the `review_report` tool exactly as the Output section below
+specifies, with `fanned_out: false` (honesty: this was a single-pass
+self-review). At low the candidates ARE the findings (unverified — leave
+`verdict` unset so the reader can discount them); if the `review_report` tool
+is unavailable, print the findings as text (one line per finding:
+`path/to/file.ext:123 — 问题与失败后果`), `(none)` when empty.
+
+## Loop fixing (--loop)
+
+When the trigger message says loop fixing is armed, the extension takes over
+after your report: it reads the newest `review_report` JSON under
+`.pi/review/`, and while P0/P1 findings remain it sends a fix prompt (apply
+them per the --fix section's rules), waits, then asks you to re-run this
+single-pass flow. Treat each re-review as a fresh pass with a fresh
+`report_id` and an honest fresh findings list — do not rubber-stamp the
+previous run.
 
 ---
 
-# MEDIUM-AND-ABOVE FLOW  (fan-out + verify)
-
-## Phase 1 — Find candidates (single pass or parallel fan-out)
-
-Work through the angles below. If the `subagent` tool is available, launch
-finder agents in a single batch (mode: parallel) so they run concurrently;
-otherwise do not fake the fan-out — work the angles yourself in sequence in
-this same context, or report that the subagent capability is unavailable.
-
-**Finder allocation** (CC inline, verified 2.1.227): the number of correctness
-angles comes from the effort quad tuple, taken **in order A→E** (`slice(0, N)`
-— do not hand-pick angles; that makes runs unreproducible):
-
-- **medium / high** (3 correctness angles): **8 finders** — A, B, C + one
-  finder each for Reuse, Simplification, Efficiency + one Altitude + one
-  Conventions.
-- **xhigh / max** (5 correctness angles): **10 finders** — A, B, C, D, E + the
-  same 3 cleanup finders + Altitude + Conventions.
+# XHIGH/MAX FLOW  (deep sweep: fan-out + verify)
+
+Reached only at effort xhigh/max — low/medium/high use the SINGLE-PASS FLOW
+above. Launch finder agents through the `subagent` tool in a single batch
+(mode: parallel) so they run concurrently; if it is unavailable, do not fake
+the fan-out — work the angles yourself in sequence in this same context, or
+report that the subagent capability is unavailable.
+
+**Checking `subagent` availability** — wherever this skill says "if the
+`subagent` tool is available", decide from THIS session's tool list, never by
+probing: `subagent` is a pi extension tool registered alongside
+read/bash/edit, not an MCP server tool, so the `mcp` gateway's tool search
+answers "No tools matching subagent" even when the tool is registered and
+callable. If it is in your toolset, use it without further verification; if it
+is genuinely absent, take the sequential fallback above.
+
+**Finder turn budget（Pi adaptation — the same runaway-exploration guard the
+Phase 3 gap-hunt already carries）** — a finder that exhausts its turn cap
+mid-read returns NOTHING and silently loses its whole angle (observed on a
+168-file diff: 7/10 finders burned their full turn budget with zero output,
+and the coverage hole cascaded into two extra compensation waves). Constrain
+every finder batch:
+
+1. **Set `maxTurns: 20` on the `subagent` call** — the slowest finder pins
+   the wave's wall time; 20 turns covers the highest-risk hunks of any
+   single angle, and a capped finder still owes partial output (next item).
+   (20 is the built-in default — if the trigger message states a different
+   finder budget, use that instead.)
+2. **Declare the budget inside each finder prompt** — e.g. "You have ~15
+   tool calls. Spend them on the highest-risk hunks first; when half are
+   spent, stop opening new files."
+3. **Final-message contract** — the finder's LAST assistant message must be
+   its JSON candidate array (an empty `[]` is a valid answer). Partial
+   output beats none: candidates that never reach text never reach verify.
+4. **A finder that hits max-turns with no JSON is a FAILED finder**, not an
+   empty angle: re-dispatch that single angle on a narrower file slice
+   before Phase 2 (or fold it into the xhigh/max gap-hunt), and note the
+   re-dispatch in the report.
+
+**Finder allocation** (CC inline, verified 2.1.227): xhigh/max run all five
+correctness angles — **10 finders**: A, B, C, D, E + one finder each for
+Reuse, Simplification, Efficiency + one Altitude + one Conventions. The quad
+tuple's angles are taken **in order A→E** (`slice(0, N)` — do not hand-pick
+angles; that makes runs unreproducible).
 
 Each cleanup angle (Reuse / Simplification / Efficiency) gets its own finder;
 Altitude and Conventions are independent finders. Never silently drop an
@@ -272,10 +432,11 @@ alternative.
 
 ### Altitude
 
-Check that each change is implemented at the right depth, not as a fragile
-bandaid. Special cases layered on shared infrastructure are a sign the fix
-isn't deep enough — prefer generalizing the underlying mechanism over adding
-special cases.
+Check that each change fixes the root cause at the right depth rather than
+patching a symptom with a fragile bandaid. Special cases layered on shared
+infrastructure are a sign the fix isn't deep enough — prefer the simpler,
+more general change to the underlying mechanism over adding special cases,
+and name that change.
 ### Conventions (CLAUDE.md)
 Find the CLAUDE.md files that govern the changed code: the user-level
 ~/.claude/CLAUDE.md, the repo-root CLAUDE.md, plus any CLAUDE.md or
@@ -303,7 +464,9 @@ Then verify each candidate **grouped by location**. If the `subagent` tool is
 available: group the deduplicated candidates by `(file, line)`; dispatch ONE
 independent verify agent per group (mode: parallel, one prompt per group),
 giving it the scope block, the diff, the relevant file(s), and the full
-candidate list for that location with each candidate's index. The verifier
+candidate list for that location with each candidate's index. Set
+`maxTurns: 15` on each verifier call (15 is the built-in default — a
+different verifier budget stated in the trigger message wins). The verifier
 returns a verdict per candidate:
 
 ```
@@ -340,11 +503,11 @@ optional field), falsy-zero treated as missing, off-by-one on a boundary the
 code does not exclude, retry storms / partial failures, regex/allowlist that
 lost an anchor. These are PLAUSIBLE.
 
-**Recall bias by level** — at high/xhigh/max, a single non-REFUTED verdict
-keeps the candidate: do NOT drop it on uncertainty ("speculative", "depends
-on runtime state"). That is the recall contract of high+. Medium is the
-precision level: there, additionally weigh whether a maintainer would act on
-the finding before keeping it.
+**Recall bias** — a single non-REFUTED verdict keeps the candidate: do NOT
+drop it on uncertainty ("speculative", "depends on runtime state"). This
+flow is the recall contract of xhigh/max — a missed bug ships, so err on the
+side of surfacing hardest here. (Medium's precision filter lives in the
+single-pass self-verify; it never reaches this flow.)
 
 **REFUTED** only when constructible from the code: factually wrong (quote the
 actual line); provably impossible (type/constant/invariant — show it); already
@@ -354,8 +517,13 @@ handled in this diff (cite the guard); or pure style with no observable effect.
 
 At **xhigh and max**, after Phase 2 dedup, dispatch ONE fresh finder agent (the
 `subagent` tool) that has never seen the candidates and hunts only for gaps not
-already listed — **at most 8 new candidates**. Feed anything it finds back
-through Phase 2 verify before keeping it.
+already listed — **at most 8 new candidates**. Focus the hunt on what the first
+pass tends to miss (CC 2.1.261 sweep list): moved/extracted code that dropped a
+guard or anchor; second-tier footguns (dataclass default evaluated once,
+`hash()` non-determinism, lock-scope shrink, predicate methods with side
+effects); setup/teardown asymmetry in tests; config defaults flipped. If
+nothing new turns up, return an empty sweep — do not pad. Feed anything it
+finds back through Phase 2 verify before keeping it.
 
 Constrain it so exploration can't run away (Pi adaptation — CC's workflow bounds
 this differently):
@@ -365,7 +533,9 @@ this differently):
    results: the diff, the enclosing functions, the deduplicated finding list,
    and any search results. The gap-hunt agent **analyzes**, it does not
    **discover**.
-2. **Set `maxTurns: 15`** on the `subagent` call — caps it at 15 assistant turns.
+2. **Set `maxTurns: 15`** on the `subagent` call — caps it at 15 assistant turns
+   (built-in default — a different gap-hunt budget stated in the trigger
+   message wins).
 3. **Declare a tool-call budget in the prompt** — e.g. "You have ONLY 3 tool
    calls to read files. Read them now, then analyze from this message's
    context."
@@ -374,8 +544,6 @@ Feed anything it finds back through Phase 2 verify before keeping it. If the
 `subagent` tool is unavailable, take one self-sweep instead and note the
 gap-hunt was self-run (lacks the independent fresh-eyes benefit).
 
-At **high and below**, skip Phase 3.
-
 ## Output
 
 Report the findings via the `review_report` tool (this extension's counterpart
@@ -384,12 +552,18 @@ to CC's `ReportFindings`) — call it **once** with
 ranked most-severe first (empty array if nothing survived verification). The
 tool renders the Chinese Markdown report (table + details) back to the
 conversation AND writes a machine-readable JSON to `<cwd>/.pi/review/` for CI /
-`--fix` / `--comment`. Do **not** also hand-write the Markdown table.
+`--fix` / `--comment`. Do **not** also hand-write the Markdown table. Also do
+**not** spontaneously produce a review page/artifact when `--share` was not
+passed — the `review_report` call IS the report (CC 2.1.261: "do not create
+or publish an artifact of the review — the tool call is the report");
+`--share` is the only explicit exception.
 
 Each finding in the array carries: `file`, `line` (optional), `category`
 (`correctness` / `reuse` / `simplification` / `efficiency` / `altitude` /
 `conventions`, or a more specific slug like `test-coverage`), `verdict`
-(`CONFIRMED` / `PLAUSIBLE`), `short_summary` (≤60 字符、纯声明——去掉理由与
+(`CONFIRMED` / `PLAUSIBLE`), `priority` (`P0`–`P3`; single-pass levels
+always set it — `--loop` treats P0/P1 as blocking; xhigh/max may omit it),
+`short_summary` (≤60 字符、纯声明——去掉理由与
 后果，汇总表概述列优先使用它；示例：`"off-by-one in loop bound"`),
 `summary` (一行中文，含理由与后果，详情块使用), `failure_scenario`
 (concrete input/state → wrong output/crash; for cleanup findings, the
@@ -416,7 +590,7 @@ the files by id.
 `outcome` 作为标识符保留英文 token。
 
 **`fanned_out` 诚实** — 准确设置：仅当多智能体 fan-out 真的跑起来（subagent
-finder + verify agent）才为 `true`；low effort 或任何单遍/自审降级为 `false`。该
+finder + verify agent，xhigh/max）才为 `true`；low/medium/high 单遍或任何自审降级为 `false`。该
 字段会出现在报告表头，让读者不被误导（替代旧的 Single-pass honesty 小节）。
 
 **降级** — 若 `review_report` 工具未注册（这份 SKILL.md 跑在 pi-review 扩展之外），
@@ -426,36 +600,57 @@ finder + verify agent）才为 `true`；low effort 或任何单遍/自审降级
 
 ## Applying fixes (--fix)
 
-The `--fix` flag was passed. After producing the findings list, apply the
+The `--fix` flag was passed (the extension-driven `--loop` sends the same
+fix prompts between re-review passes — follow them identically). After
+producing the findings list, apply the
 findings to the working tree instead of stopping at the report: fix each one
 directly — correctness bugs and reuse/simplification/efficiency cleanups alike.
 Skip any finding whose fix would change intended behavior, require changes well
 outside the reviewed diff, or that you judge to be a false positive — note the
-skip rather than arguing with it. Then call `review_report` once more to
+skip rather than arguing with it. If a verification command was detected (see
+the trigger message's verification line), run it BEFORE re-reporting: a finding
+whose fix breaks verification is reverted and re-reported as `skipped`
+(verification is opportunistic — with no detected command, re-report directly
+and say verification was not run). Then call `review_report` once more to
 re-report (same `report_id`), setting `outcome` on each finding (`fixed` =
 applied and verified / `skipped` = real but not applied, incl. reverted /
 `no_change_needed` = not applicable or already handled). This structured
 re-report replaces the hand-written summary and makes the fix result
-machine-consumable.
+machine-consumable. Make that call immediately after the fixes land, before
+any prose summary (CC 2.1.261: the host UI's per-finding status updates only
+from it).
 If `review_report` is unavailable, fall back to a brief text summary of what was
 fixed and what was skipped.
 
 ## Posting comments (--comment)
 
-The `--comment` flag was passed. Post the findings as inline PR comments on the
-corresponding `file`/`line`. If no GitHub commenting tool is available on Pi,
-fall back to printing the findings as text and note that inline posting was
-unavailable.
+The `--comment` flag was passed. After producing the findings list:
+
+- **GitHub PR target** — post each finding as an inline PR comment on the
+  corresponding `file`/`line`, one call per finding; include a suggestion
+  block only when it fully fixes the issue (CC 2.1.261 rule). If no
+  inline-comment tool is available on Pi, fall back to `gh api
+  repos/{owner}/{repo}/pulls/{pr}/comments`; if `gh` is unavailable too,
+  print the findings as text and note that inline posting was unavailable.
+- **GitLab MR target** — post the findings as ONE general MR note via
+  `glab mr note -m "<body>"` from inside the project's checkout — every
+  finding with its file:line, the issue, and the suggested fix (CC 2.1.261;
+  glab has no single verb for line-anchored comments, so post the general
+  note unless the user explicitly asks for inline threads — those need
+  `glab api projects/:id/merge_requests/:iid/discussions`). If `glab` is
+  unavailable, print the findings instead.
+- **Not a PR/MR target** — print the findings to the terminal and note that
+  `--comment` was ignored.
 
 ## Publishing a shareable review (--share)
 
 The `--share` flag was passed. After producing the findings list, also publish
 them as an artifact so they can be shared and iterated on outside the terminal.
 
-1. Write a self-contained HTML review page to `.lavish/code-review-<n>.html`
+1. Write a self-contained HTML review page to `.lavish/review-<n>.html`
    (create `.lavish/` in the repo root if missing). The page must render with no
    server and carry every finding plus its context.
-2. Open it with `lavish-axi .lavish/code-review-<n>.html` so the reader can
+2. Open it with `lavish-axi .lavish/review-<n>.html` so the reader can
    review, annotate, and send feedback back through the poll.
 
 Page structure (follow lavish design guidance — clear visual hierarchy, no