@fyeeme/pi-review 2.0.1 → 2.1.0

package/README.md

@@ -8,22 +8,22 @@
 
 - **`review_report` structured findings sink** — Chinese Markdown rendered back to the conversation plus machine-readable JSON under `<cwd>/.pi/review/` for CI, `--fix` re-reports, and `--comment`.
 
-- **Effort levels with CC-parity semantics** — `/review [low|medium|high|xhigh|max]`: quad tuples `{correctnessAngles, perAngle, maxFindings, sweep}`, grouped-by-location independent verification, and the xhigh/max gap-hunt.
+- **Effort split (v2.1)** — `/code-review [low|medium|high|xhigh|max]`: low/medium/high review the diff in ONE pass in the main session (no subagents: rubric-ported flag criteria, P0–P3 priorities, in-session self-verify at medium/high); xhigh/max keep the opt-in deep sweep — quad tuples `{correctnessAngles, perAngle, maxFindings, sweep}`, grouped-by-location independent verification, and the gap-hunt.
 
-- **`/simplify` dual-mode** — the dispatcher measures context usage and diff size against the declared strategy, then renders either the PARALLEL template (4 cleaner agents via `subagent`) or the SINGLE-PASS one.
+- **`/code-simplify` dual-mode** — the dispatcher measures context usage and diff size against the declared strategy, then renders either the PARALLEL template (4 cleaner agents via `subagent`) or the SINGLE-PASS one.
 
-- Breaking: commands renamed `/code-review` → `/review`, `/code-simplify` → `/simplify`.
+- Commands: `/code-review` and `/code-simplify` — restored v1 names (2.0.0 briefly renamed them `/review` / `/simplify`).
 
 Review & cleanup assets for [pi](https://github.com/earendil-works/pi-mono), in the sandwich shape (skills + prompts + agents on top of a thin plugin entry):
 
 ```
-skills/    methodology (review, simplify) — registered natively via the `pi` manifest
+skills/    methodology (code-review, code-simplify) — registered natively via the `pi` manifest
 prompts/   orchestration strategy as data — parallel-when guards in frontmatter,
            CC-parity phase structure in the body; rendered by the generic dispatcher
 agents/    the review roles as subagent definitions (finder-*, cleaner-*, verifier,
            gap-hunter) invoked via the `subagent` tool of @fyeeme/pi-subagents
 index.ts   plugin entry: the review_report structured findings sink + the
-           /review and /simplify dispatcher commands
+           /code-review and /code-simplify dispatcher commands
 src/       dispatch.ts (variable gathering, guard evaluation, rendering),
            diff.ts (deterministic diff ladder — unchanged v1 semantics),
            strategy.ts (guard evaluator), tools/review_report.ts
@@ -39,8 +39,8 @@ composition is idempotent.
 
 ## Commands
 
-- `/review [low|medium|high|xhigh|max] [--fix] [--comment] [--share] [<pr#>|<branch>|<path>]` — effort-level code review via the review skill. Effort is sticky: an explicit level is remembered; the next bare `/review` reuses it.
-- `/simplify [<target>]` — cleanup of the changed code (reuse/simplification/efficiency/altitude). The dispatcher resolves the diff (upstream merge-base → HEAD worktree → staged → unstaged; submodule-aware), evaluates the strategy declared in `prompts/simplify.parallel.md` frontmatter (context usage < 80%, diff < 400k chars, fan-out available), and renders either the PARALLEL template (Phase 0 visible diff read → `subagent` parallel dispatch of the 4 cleaner agents with `maxTurns: 15` → Phase 2 apply/verify/report) or the SINGLE-PASS template (angles worked inline).
+- `/code-review [low|medium|high|xhigh|max] [--fix] [--loop] [--comment] [--share] [<pr#>|<branch>|<path>]` — effort-level code review via the code-review skill. low/medium/high run as a single pass in this session (fast path, default); xhigh/max fan out finder/verifier/gap-hunt agents through `subagent`. Effort is sticky: an explicit level is remembered; the next bare `/code-review` reuses it. `--loop` (single-pass levels only) drives extension-orchestrated fix→re-review rounds (≤ `maxTurns.loop`, default 3) until no P0/P1 findings remain.
+- `/code-simplify [<target>]` — cleanup of the changed code (reuse/simplification/efficiency/altitude). The dispatcher resolves the diff (upstream merge-base → HEAD worktree → staged → unstaged; submodule-aware), evaluates the strategy declared in `prompts/simplify.parallel.md` frontmatter (context usage < 80%, diff < 400k chars, fan-out available), and renders either the PARALLEL template (Phase 0 visible diff read → `subagent` parallel dispatch of the 4 cleaner agents with `maxTurns: 15` → Phase 2 apply/verify/report) or the SINGLE-PASS template (angles worked inline).
 
 Reports land via the `review_report` tool: Chinese Markdown back to the conversation plus machine-readable JSON under `<cwd>/.pi/review/`.
 
@@ -69,19 +69,20 @@ pattern as pi-subagents' `pi-subagent.json` (project overrides global):
 // <any layer>/pi-review.json — all keys optional
 {
   "maxTurns": {
-    "subagent": 20,   // each /review finder-batch subagent call
-    "verifier": 15,   // each /review Phase 2 verifier call
-    "gapHunt": 15,   // the /review Phase 3 gap-hunter
-    "simplify": 15    // each /simplify PARALLEL cleaner agent
+    "subagent": 20,   // each /code-review finder-batch subagent call
+    "verifier": 15,   // each /code-review Phase 2 verifier call
+    "gapHunt": 15,   // the /code-review Phase 3 gap-hunter (xhigh/max)
+    "simplify": 15,  // each /code-simplify PARALLEL cleaner agent
+    "loop": 3        // --loop fix→re-review round cap (single-pass levels)
   }
 }
 ```
 
 Values must be positive integers; anything else (or an absent file) falls back
-to the built-in defaults — `20` / `15` / `15` / `15`, the numbers the bundled
+to the built-in defaults — `20` / `15` / `15` / `15` / `3`, the numbers the bundled
 prompts and skills were written with — so with no configuration the rendered
 instructions are byte-identical to the pre-config behavior. Files are read at
-command time: an edit takes effect on the next `/review` or `/simplify`
+command time: an edit takes effect on the next `/code-review` or `/code-simplify`
 without a restart. When a budget is configured, the trigger message states it
 and the skills defer to it over their built-in defaults.
 

package/index.ts

@@ -3,7 +3,7 @@
  *
  * Sandwich architecture (see openspec change subagent-sandwich-refactor):
  *
- *   Skills  skills/review, skills/simplify — review methodology,
+ *   Skills  skills/code-review, skills/code-simplify — review methodology,
  *           registered natively via the pi manifest (`pi.skills`); they
  *           reference capabilities by stable tool/agent names only.
  *   Prompts prompts/ — the orchestration strategy as data: parallel-when
@@ -20,7 +20,7 @@
  *           manifest path wiring and no separate install step), registers
  *           this package's agents directory as a discovery source, and adds
  *           the `review_report` structured findings sink plus the
- *           /review and /simplify dispatcher commands.
+ *           /code-review and /code-simplify dispatcher commands.
  *
  * The `subagent` tool registers exactly once per process: if pi-subagents
  * is ALSO installed standalone (or another consumer composes it), the guard

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fyeeme/pi-review",
-  "version": "2.0.1",
-  "description": "Review & cleanup assets for pi: /review and /simplify commands dispatching declarative prompt templates (parallel strategy as frontmatter data) plus review methodology skills and finder/verifier agent definitions. Spawning lives in @fyeeme/pi-subagents; this package registers the review_report findings sink and the generic dispatcher.",
+  "version": "2.1.0",
+  "description": "Review & cleanup assets for pi: /code-review and /code-simplify commands dispatching declarative prompt templates (parallel strategy as frontmatter data) plus review methodology skills and finder/verifier agent definitions. Spawning lives in @fyeeme/pi-subagents; this package registers the review_report findings sink and the generic dispatcher.",
   "type": "module",
   "license": "MIT",
   "author": "fyeeme",
@@ -30,8 +30,8 @@
       "./index.ts"
     ],
     "skills": [
-      "skills/review",
-      "skills/simplify"
+      "skills/code-review",
+      "skills/code-simplify"
     ]
   },
   "scripts": {
@@ -48,9 +48,9 @@
     "typebox": ">=1.0.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "0.84.4",
-    "@earendil-works/pi-coding-agent": "0.84.4",
-    "@earendil-works/pi-tui": "0.84.4",
+    "@earendil-works/pi-ai": "0.85.1",
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@earendil-works/pi-tui": "0.85.1",
     "@types/node": "22.19.19",
     "jiti": "2.7.0",
     "typebox": "1.1.38",

package/prompts/{review.md → review.parallel.md}

@@ -1,12 +1,12 @@
 ---
-description: "/review trigger — effort-level code review via the review skill"
+description: "/code-review trigger — xhigh/max deep sweep: finder/verifier/gap-hunt fan-out via the code-review skill"
 vars: [effort, effort-source, extra-args, skill, finder-max-turns, verifier-max-turns, gap-hunt-max-turns, verify]
 ---
 Run a code review now. Effective effort: {{effort}} ({{effort-source}}){{extra-args}}.
 
-First load the review skill with the read tool: {{skill}}. Then follow it
-exactly — dispatch the finder / verifier / gap-hunter agents it calls for
-through the `subagent` tool (bundled agents: finder-diff-scan,
+First load the code-review skill with the read tool: {{skill}}. Then follow its
+XHIGH/MAX FLOW exactly — dispatch the finder / verifier / gap-hunter agents it
+calls for through the `subagent` tool (bundled agents: finder-diff-scan,
 finder-removed-behavior, finder-cross-file, finder-language-pitfall,
 finder-wrapper-proxy, cleaner-reuse, cleaner-simplification,
 cleaner-efficiency, cleaner-altitude, finder-conventions, verifier,

package/prompts/review.single.md

@@ -0,0 +1,16 @@
+---
+description: "/code-review trigger — single-pass main-session review via the code-review skill (low/medium/high)"
+vars: [effort, effort-source, extra-args, skill, verify, loop-note]
+---
+Run a code review now. Effective effort: {{effort}} ({{effort-source}}){{extra-args}}.
+
+First load the code-review skill with the read tool: {{skill}}. Then follow its
+SINGLE-PASS FLOW for effort {{effort}}: review the diff yourself in this
+session — read it, surface candidates against the skill's rubric, self-verify
+them (medium/high), and report via the `review_report` tool. No subagent
+fan-out at this level: do NOT dispatch finder or verifier agents, even though
+the `subagent` tool may be in your session toolset.
+{{loop-note}}
+Verification guidance (the skill's `--fix` flow consumes it):
+
+{{verify}}

package/prompts/simplify.parallel.md

@@ -1,5 +1,5 @@
 ---
-description: "/simplify trigger — PARALLEL mode (4-agent fan-out via the subagent tool)"
+description: "/code-simplify trigger — PARALLEL mode (4-agent fan-out via the subagent tool)"
 parallel-when:
   context-below: 0.8
   diff-chars-below: 400000

package/prompts/simplify.single.md

@@ -1,5 +1,5 @@
 ---
-description: "/simplify trigger — SINGLE-PASS mode (angles worked inline, no fan-out)"
+description: "/code-simplify trigger — SINGLE-PASS mode (angles worked inline, no fan-out)"
 vars: [target, reasons, scope-label, too-large, git-command, context-package, skill, verify]
 ---
 Clean up the changed code now. Target: {{target}}.

package/skills/{review → code-review}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: review
-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: fewer, high-confidence findings; high→max: broader coverage, may include uncertain findings). 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, --comment to post findings (GitHub inline / GitLab MR note), --share to publish a review page."
+name: code-review
+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."
 ---
 
 <!--
@@ -10,6 +10,19 @@ description: "Review the current diff, or a PR number/branch/path target, for co
   earlier v2.1.220 reconstruction. Every section below was located in the
   extracted strings (cc_strings_223.txt) and verified.
 
+  ── 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
@@ -61,9 +74,11 @@ description: "Review the current diff, or a PR number/branch/path target, for co
     - Fixed-later obligation (CC Q8m): later fixes in the session must
       re-report findings with updated outcome.
 
-  Invocation: /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
-    With no level given, the /review HANDLER reuses the last level you
+    --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.
     (CC also supports `ultra` — deep multi-agent review in the cloud.
@@ -82,6 +97,8 @@ description: "Review the current diff, or a PR number/branch/path target, for co
                   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 2.1.217 routed high/xhigh/max to a background Workflow
@@ -101,8 +118,9 @@ description: "Review the current diff, or a PR number/branch/path target, for co
                   mirrors both fallbacks (see the --comment section).
 
   Prerequisite: the `subagent` tool (@fyeeme/pi-subagents; parallel mode) for
-                medium and above, and for the xhigh/max gap-hunter. lavish-axi
-                for --share. low runs standalone (no subagents).
+                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 /
@@ -111,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
@@ -177,52 +203,123 @@ 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)
+# XHIGH/MAX FLOW  (deep sweep: fan-out + verify)
 
-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.
+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
@@ -255,15 +352,11 @@ every finder batch:
    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): 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.
+**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
@@ -410,12 +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. At xhigh/max a missed bug ships — err on the
-side of surfacing hardest there.
+**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
@@ -452,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
@@ -471,7 +561,9 @@ or publish an artifact of the review — the tool call is the report");
 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
@@ -498,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 扩展之外），
@@ -508,7 +600,9 @@ 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

package/skills/{simplify → code-simplify}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: simplify
-description: "Review the changed code for reuse, simplification, efficiency, and altitude cleanups, then apply the fixes. Quality only — it does not hunt for bugs; use /review for that. v3 (from Claude Code CLI v2.1.227, symbol-level verified; re-verified against v2.1.261 on 2026-09-05 — bodies unchanged except Altitude) — 4 cleanup agents fan out in parallel when context allows, else a single-pass inline cleanup; either way the fixes are applied, verified against the project's check command, and auto-reverted on failure, then reported as structured outcomes via review_report."
+name: code-simplify
+description: "Review the changed code for reuse, simplification, efficiency, and altitude cleanups, then apply the fixes. Quality only — it does not hunt for bugs; use /code-review for that. v3 (from Claude Code CLI v2.1.227, symbol-level verified; re-verified against v2.1.261 on 2026-09-05 — bodies unchanged except Altitude) — 4 cleanup agents fan out in parallel when context allows, else a single-pass inline cleanup; either way the fixes are applied, verified against the project's check command, and auto-reverted on failure, then reported as structured outcomes via review_report."
 ---
 
 <!--
   Origin: Claude Code built-in skill `/simplify` (CLI v2.1.227), reverse-
-  engineered from bin/claude.exe raw bytes. Pi registers it as /simplify.
+  engineered from bin/claude.exe raw bytes. Pi registers it as /code-simplify.
 
   Lineage:
     v2.1.220 → the first reconstruction         (v1)
@@ -26,7 +26,7 @@ description: "Review the changed code for reuse, simplification, efficiency, and
                behavior"; "Quality only — it does not hunt for bugs; use
                /code-review for that") and the Agent-tool fan-out ("all in a
                single message so they run concurrently") are unchanged.
-               The /code-review↔/simplify division of labor is now stated
+               The /code-review↔/code-simplify division of labor is now stated
                explicitly in both skills upstream — same as here.
 
   CC 2.1.227 empirical evidence (symbol-level, extracted from bin/claude.exe):
@@ -46,9 +46,9 @@ description: "Review the changed code for reuse, simplification, efficiency, and
       FORKED_AGENT_DEFAULT_MAX_TURNS = 50 — mirrored as the subagent tool's
       defaults (PI_MAX_CONCURRENT_SUBAGENTS env still overrides the ceiling).
 
-  Bundled: ships inside the pi-review extension (skills/simplify/SKILL.md).
+  Bundled: ships inside the pi-review extension (skills/code-simplify/SKILL.md).
 
-  Invocation: /simplify [<target>]
+  Invocation: /code-simplify [<target>]
     target = file path | PR number | branch name
 
   ════════════════════════════════════════════════════════════════════════
@@ -69,10 +69,10 @@ description: "Review the changed code for reuse, simplification, efficiency, and
        Dii. The cleanup agents' tool whitelist (read/grep/find/ls/bash) never
        includes a fan-out tool, so recursion stays physically bounded
        regardless of tool registration. The decision is made
-       DETERMINISTICALLY by the /simplify handler — it can
+       DETERMINISTICALLY by the /code-simplify handler — it can
        read ctx.getContextUsage(), which a pure-prompt skill cannot — and announced
        in the trigger message; this skill just provides the two mode bodies.
-    3. Command     — CC: /simplify; Pi: /simplify.
+    3. Command     — CC: /simplify; Pi: /code-simplify.
     4. Dispatch    — CC's lead model writes the 4 Agent prompts itself after its
        visible Phase 0. Pi keeps the same TIMELINE but moves the packaging into
        code: the trigger message carries the handler-resolved scope, the
@@ -94,9 +94,9 @@ description: "Review the changed code for reuse, simplification, efficiency, and
 
 You are improving the quality of the changed code, not hunting for bugs. Review
 it for reuse, simplification, efficiency, and altitude issues, then fix what you
-find. Do not look for correctness bugs — that is what `/review` is for.
+find. Do not look for correctness bugs — that is what `/code-review` is for.
 
-The `/simplify` handler has already chosen the mode (PARALLEL or
+The `/code-simplify` handler has already chosen the mode (PARALLEL or
 SINGLE-PASS) from real context usage and announced it in the trigger message.
 Follow the body that matches; do not fake the mode you weren't asked to run.
 Both modes open the same way: the trigger message carries the handler-resolved
@@ -106,7 +106,7 @@ VISIBLE, model-run step before anything launches.
 ## Phase 0 — Gather the diff
 
 When the trigger message carries a handler-resolved scope (it always does for
-/simplify), use THAT: run the exact `git -C … diff …` command the trigger
+/code-simplify), use THAT: run the exact `git -C … diff …` command the trigger
 provides — the handler already ran the cascade (merge-base → HEAD → staged →
 unstaged) to pick it — read the full diff, and write a 2–4 line change-intent
 summary before anything else. Do not re-derive a different range. That summary
@@ -125,7 +125,7 @@ review that target instead. Treat this diff as the review scope.)
 
 # PARALLEL MODE  (context not near-full AND diff under the fan-out threshold AND fan-out available)
 
-`/simplify → visible Phase 0 (read the diff, summarize) → subagent tool (parallel, 4 cleaner agents) → apply the fixes`
+`/code-simplify → visible Phase 0 (read the diff, summarize) → subagent tool (parallel, 4 cleaner agents) → apply the fixes`
 
 ## Phase 1 — Review (4 cleanup agents in parallel)
 
@@ -184,7 +184,7 @@ Follow the shared **Phase 2** procedure at the end of this skill (snapshot → a
 
 # SINGLE-PASS MODE  (context near-full OR diff too large OR fan-out unavailable)
 
-`/simplify → handler decided single-pass (reasons in the trigger message) → inline cleanup → apply the fixes`
+`/code-simplify → handler decided single-pass (reasons in the trigger message) → inline cleanup → apply the fixes`
 
 The handler decided against the 4-agent fan-out (context near-full, diff too
 large, fan-out unavailable, or usage unmeasurable — the exact reasons are in
@@ -237,7 +237,7 @@ Follow the shared **Phase 2** procedure at the end of this skill (snapshot → a
 # Phase 2 — Apply, verify, and report (shared by both modes)
 
 Dedup findings that point at the same line or mechanism first. Then apply,
-verify, and report. This safety net is what distinguishes `/simplify` from
+verify, and report. This safety net is what distinguishes `/code-simplify` from
 a blind cleanup: a finding is only "done" once it is applied AND the project
 still verifies — otherwise it is reverted.
 
@@ -258,7 +258,7 @@ for any file in a subdirectory. If a fix CREATES a new file, record its path so
 Step 3a can remove it on rollback (it has no baseline entry).
 
 This baseline captures the working-tree state **including** the user's
-uncommitted changes — reverting to it undoes only `/simplify`'s fixes,
+uncommitted changes — reverting to it undoes only `/code-simplify`'s fixes,
 never the user's diff. Do **not** use `git checkout` / `git restore` to revert:
 that would discard the user's intended changes too.
 

package/src/config.ts

@@ -10,19 +10,20 @@
  *
  *   {
  *     "maxTurns": {
- *       "subagent": 20,   // per-call budget for each /review finder batch
- *       "gapHunt":  15,   // budget for the /review Phase 3 gap-hunter
- *       "simplify": 15    // budget for each /simplify PARALLEL cleaner agent
+ *       "subagent": 20,   // per-call budget for each /code-review finder batch (xhigh/max)
+ *       "gapHunt":  15,   // budget for the /code-review Phase 3 gap-hunter (xhigh/max)
+ *       "simplify": 15,   // budget for each /code-simplify PARALLEL cleaner agent
+ *       "loop": 3         // --loop fix→re-review round cap (single-pass levels)
  *     }
  *   }
  *
  * The defaults here are the numbers the bundled prompts and skills were
- * written with (finder 20 / gap-hunt 15 / simplify 15). With no config file
+ * written with (finder 20 / gap-hunt 15 / simplify 15 / loop 3). With no config file
  * — or with any key absent or invalid — the rendered instructions carry
  * exactly those numbers, so absence of configuration changes nothing.
  *
  * Read at command time (like pi-subagents' maxConcurrency): an edited file
- * takes effect on the next /review or /simplify without a restart. Malformed
+ * takes effect on the next /code-review or /code-simplify without a restart. Malformed
  * files are ignored with a stderr warning (never fatal); unknown/garbage
  * fields are dropped on read.
  */
@@ -33,16 +34,18 @@ import { getAgentDir } from "@earendil-works/pi-coding-agent";
 /** Settings file name (both layers). */
 const CONFIG_FILE = "pi-review.json";
 
-/** The four dispatchable turn budgets, keyed by what they throttle. */
+/** The dispatchable turn budgets, keyed by what they throttle. */
 export interface TurnBudgets {
-	/** `maxTurns` set on each /review finder-batch `subagent` call. */
+	/** `maxTurns` set on each /code-review finder-batch `subagent` call. */
 	subagent: number;
-	/** `maxTurns` set on each /review Phase 2 verifier `subagent` call. */
+	/** `maxTurns` set on each /code-review Phase 2 verifier `subagent` call. */
 	verifier: number;
-	/** `maxTurns` set on the /review Phase 3 gap-hunt `subagent` call. */
+	/** `maxTurns` set on the /code-review Phase 3 gap-hunt `subagent` call. */
 	gapHunt: number;
-	/** `maxTurns` set on each /simplify PARALLEL cleaner `subagent` call. */
+	/** `maxTurns` set on each /code-simplify PARALLEL cleaner `subagent` call. */
 	simplify: number;
+	/** Max fix→re-review rounds when /code-review runs with --loop. */
+	loop: number;
 }
 
 /** Built-in budgets — identical to the literals in prompts/ and skills/. */
@@ -51,6 +54,7 @@ export const DEFAULT_TURN_BUDGETS: TurnBudgets = {
 	verifier: 15,
 	gapHunt: 15,
 	simplify: 15,
+	loop: 3,
 };
 
 function globalPath(): string {
@@ -85,6 +89,8 @@ function readBudgetsFile(path: string): Partial<TurnBudgets> {
 		if (gapHunt !== undefined) out.gapHunt = gapHunt;
 		const simplify = sanitizeBudget(mt.simplify);
 		if (simplify !== undefined) out.simplify = simplify;
+		const loop = sanitizeBudget(mt.loop);
+		if (loop !== undefined) out.loop = loop;
 		return out;
 	} catch (err) {
 		const reason = err instanceof Error ? err.message : String(err);

package/src/diff.ts

@@ -30,7 +30,7 @@ export function findGitRoot(from: string): string | null {
 	}
 }
 
-/** Normalize a /simplify target argument: trimmed, with an optional
+/** Normalize a /code-simplify target argument: trimmed, with an optional
  *  path-prefix `@` PRESERVED — a real directory may itself start with `@`
  *  (e.g. node_modules/@scope/pkg), so the resolver tries the literal path
  *  first and only falls back to the @-stripped form when it does not exist. */
@@ -38,7 +38,7 @@ function normalizeTarget(target: string | undefined): string {
 	return (target ?? "").trim();
 }
 
-/** Resolve the diff scope for a review/simplify target. Pure — unit-testable.
+/** Resolve the diff scope for a code-review/code-simplify target. Pure — unit-testable.
  *
  *  - target absent/unresolvable → the nearest git root of `cwd`, full diff.
  *  - target is a path → its nearest git root; the relative path inside that

package/src/dispatch.ts

@@ -13,14 +13,14 @@
  * change here — the templates and skills are the registration surface.
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { CONFIG_DIR_NAME, getAgentDir, parseFrontmatter } from "@earendil-works/pi-coding-agent";
 import { isFanoutToolAllowed } from "@fyeeme/pi-subagents";
 import * as fs from "node:fs";
-import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { loadTurnBudgets } from "./config.ts";
 import { DIFF_SCOPES, buildContextPackage, getRepoDiff, verifyLine } from "./diff.ts";
+import { extractLoopFlag, runLoopFixing } from "./loop.ts";
 import { bundledSkillPath } from "./skills.ts";
 import { parseGuards, selectVariant } from "./strategy.ts";
 
@@ -51,17 +51,19 @@ export function render(body: string, vars: Record<string, string>): string {
 }
 
 // ---------------------------------------------------------------------------
-// /review — effort-level code review (v1 command semantics, relocated)
+// /code-review — effort-level code review (v1 command semantics, relocated)
 // ---------------------------------------------------------------------------
 
-/** Effort levels the /review command accepts (mirrors CC's effort enum). */
+/** Effort levels the /code-review command accepts (mirrors CC's effort enum). */
 export const REVIEW_LEVELS = ["low", "medium", "high", "xhigh", "max"] as const;
 export type ReviewLevel = (typeof REVIEW_LEVELS)[number];
 
 const DEFAULT_LEVEL: ReviewLevel = "low";
 
-/** Where the last explicitly-typed effort is persisted (CC 2.1.223 codeReviewLastEffort). */
-const STATE_FILE = path.join(os.homedir(), ".pi", ".pi-review-state.json");
+/** Where the last explicitly-typed effort is persisted (CC 2.1.223
+ *  codeReviewLastEffort). Shares the config file so users have a single
+ *  pi-review.json; the field is written alongside `maxTurns`, never over it. */
+const STATE_FILE = path.join(getAgentDir(), "pi-review.json");
 
 export type EffortSource = "explicit" | "last-used" | "default";
 
@@ -69,6 +71,12 @@ export type EffortSource = "explicit" | "last-used" | "default";
  * Parse a leading effort level out of raw args; the remainder (flags + target)
  * is returned verbatim. Pure — unit-testable.
  */
+/** True when the effort level uses the xhigh/max finder/verifier fan-out;
+ *  false for the single-pass levels (low/medium/high). Pure — unit-testable. */
+export function usesFanout(level: ReviewLevel): boolean {
+	return level === "xhigh" || level === "max";
+}
+
 export function parseReviewArgs(args: string): { level: ReviewLevel | undefined; rest: string } {
 	const tokens = (args ?? "").trim().split(/\s+/).filter(Boolean);
 	if (tokens.length === 0) return { level: undefined, rest: "" };
@@ -108,15 +116,30 @@ function readLastEffort(): ReviewLevel | undefined {
 }
 function writeLastEffort(level: ReviewLevel): void {
 	try {
+		// The state field shares a file with user-authored config (maxTurns), so
+		// read-modify-write instead of overwriting, and never clobber a
+		// hand-edited file we cannot parse.
+		let existing: Record<string, unknown> = {};
+		if (fs.existsSync(STATE_FILE)) {
+			let raw: unknown;
+			try {
+				raw = JSON.parse(fs.readFileSync(STATE_FILE, "utf8"));
+			} catch {
+				return;
+			}
+			if (!raw || typeof raw !== "object" || Array.isArray(raw)) return;
+			existing = raw as Record<string, unknown>;
+		}
+		existing.codeReviewLastEffort = level;
 		fs.mkdirSync(path.dirname(STATE_FILE), { recursive: true });
-		fs.writeFileSync(STATE_FILE, JSON.stringify({ codeReviewLastEffort: level }));
+		fs.writeFileSync(STATE_FILE, `${JSON.stringify(existing, null, 2)}\n`);
 	} catch {
 		/* ignore — non-critical */
 	}
 }
 
 // ---------------------------------------------------------------------------
-// /simplify — cleanup fan-out with the declared parallel strategy
+// /code-simplify — cleanup fan-out with the declared parallel strategy
 // ---------------------------------------------------------------------------
 
 /** v1 DIFF_TOO_LARGE_CHARS — kept for the single-pass "too large to read at
@@ -128,11 +151,11 @@ const DIFF_TOO_LARGE_CHARS = 400_000;
 // ---------------------------------------------------------------------------
 
 export function registerDispatcher(pi: ExtensionAPI): void {
-	pi.registerCommand("review", {
+	pi.registerCommand("code-review", {
 		description:
-			"Review the current diff using the review skill. Usage: /review [low|medium|high|xhigh|max] [--fix] [--comment] [--share] [<pr#>|<branch>|<path>]",
+			"Review the current diff using the code-review skill. low/medium/high review in a single pass in this session; xhigh/max fan out finder/verifier agents. Usage: /code-review [low|medium|high|xhigh|max] [--fix] [--loop] [--comment] [--share] [<pr#>|<branch>|<path>]",
 		getArgumentCompletions(prefix) {
-			const tokens = ["low", "medium", "high", "xhigh", "max", "--fix", "--comment", "--share"];
+			const tokens = ["low", "medium", "high", "xhigh", "max", "--fix", "--loop", "--comment", "--share"];
 			return tokens.filter((t) => t.startsWith(prefix)).map((t) => ({ label: t, value: t }));
 		},
 		async handler(args, ctx) {
@@ -141,42 +164,82 @@ export function registerDispatcher(pi: ExtensionAPI): void {
 			const lastUsed = explicit ? undefined : readLastEffort();
 			if (explicit) writeLastEffort(explicit); // remember the explicit level
 			const { level, source } = resolveEffort(explicit, lastUsed);
-			const { body } = loadTemplate("review.md");
 			const budgets = loadTurnBudgets();
-			pi.sendUserMessage(
-				render(body, {
-					effort: level,
-					"effort-source": source,
-					"extra-args": rest ? `; extra args: ${rest}` : "",
-					skill: bundledSkillPath("review/SKILL.md"),
-					"finder-max-turns": String(budgets.subagent),
-					"verifier-max-turns": String(budgets.verifier),
-					"gap-hunt-max-turns": String(budgets.gapHunt),
-					// Consumed by the skill's --fix flow (apply → verify → re-report).
-					verify: verifyLine(ctx.cwd),
-				}),
+
+			// Effort split: low/medium/high review in ONE pass in the main session
+			// (no subprocess fan-out); xhigh/max keep the finder/verifier pipeline.
+			const fanout = usesFanout(level);
+
+			// --loop is extension-level (drives fix→re-review rounds against the
+			// structured report), so it never reaches the skill text. It needs a
+			// single report turn to loop on — fan-out levels have no such turn.
+			const { wantLoop, rest: flagsRest } = extractLoopFlag(rest);
+			const loopArmed = wantLoop && !fanout;
+			if (wantLoop && fanout) {
+				ctx.ui.notify(
+					`/code-review: --loop applies to single-pass levels (low/medium/high) — ignored for ${level}.`,
+					"warning",
+				);
+			}
+
+			const { body } = loadTemplate(fanout ? "review.parallel.md" : "review.single.md");
+			const shared = {
+				effort: level,
+				"effort-source": source,
+				"extra-args": flagsRest ? `; extra args: ${flagsRest}` : "",
+				skill: bundledSkillPath("code-review/SKILL.md"),
+				// Consumed by the skill's --fix flow (apply → verify → re-report).
+				verify: verifyLine(ctx.cwd),
+			};
+			void pi.sendUserMessage(
+				render(
+					body,
+					fanout
+						? {
+								...shared,
+								"finder-max-turns": String(budgets.subagent),
+								"verifier-max-turns": String(budgets.verifier),
+								"gap-hunt-max-turns": String(budgets.gapHunt),
+							}
+						: {
+								...shared,
+								// Told to the session so every finding carries a P0–P3 priority.
+								"loop-note": loopArmed
+									? `\nLoop fixing is armed: after your report, the extension drives up to ${budgets.loop} fix→re-review rounds until no P0/P1 findings remain — so tag every finding with a priority (P0–P3).\n`
+									: "",
+							},
+				),
 			);
+			if (loopArmed) {
+				await runLoopFixing(pi, ctx, {
+					level,
+					passes: budgets.loop,
+					// Must match where review_report writes (CONFIG_DIR_NAME,
+					// not necessarily ".pi") or the loop never finds a report.
+					reviewDir: path.join(ctx.cwd, CONFIG_DIR_NAME, "review"),
+				});
+			}
 		},
 	});
 
-	pi.registerCommand("simplify", {
+	pi.registerCommand("code-simplify", {
 		description:
-			"Clean up the changed code (reuse/simplification/efficiency/altitude) using the simplify skill. Mode (parallel 4-agent vs single-pass) is decided from the strategy declared in prompts/simplify.*.md (context usage, diff size, fan-out availability); PARALLEL opens with a visible Phase 0 before the subagent tool launches the agents. Usage: /simplify [<target>]",
+			"Clean up the changed code (reuse/simplification/efficiency/altitude) using the code-simplify skill. Mode (parallel 4-agent vs single-pass) is decided from the strategy declared in prompts/simplify.*.md (context usage, diff size, fan-out availability); PARALLEL opens with a visible Phase 0 before the subagent tool launches the agents. Usage: /code-simplify [<target>]",
 		async handler(args, ctx) {
 			try {
 				// ctx.signal (undefined while idle) lets Esc abort an in-flight diff.
 			const outcome = await getRepoDiff(ctx.cwd, args?.trim() || undefined, undefined, ctx.signal);
 				if (outcome.kind === "no-repo") {
-					ctx.ui.notify(`/simplify: ${ctx.cwd} is not inside a git repo — nothing to clean up.`, "warning");
+					ctx.ui.notify(`/code-simplify: ${ctx.cwd} is not inside a git repo — nothing to clean up.`, "warning");
 					return;
 				}
 				if (outcome.kind === "git-error") {
-					ctx.ui.notify(`/simplify: git failed — ${outcome.message}`, "error");
+					ctx.ui.notify(`/code-simplify: git failed — ${outcome.message}`, "error");
 					return;
 				}
 				if (outcome.kind === "empty") {
 					ctx.ui.notify(
-						`/simplify: no changes found (checked unpushed+uncommitted vs @{upstream}, uncommitted vs HEAD, staged, unstaged) — nothing to clean up.`,
+						`/code-simplify: no changes found (checked unpushed+uncommitted vs @{upstream}, uncommitted vs HEAD, staged, unstaged) — nothing to clean up.`,
 						"warning",
 					);
 					return;
@@ -193,7 +256,7 @@ export function registerDispatcher(pi: ExtensionAPI): void {
 				});
 				const pct = usage && usage.percent != null ? `${Math.round(usage.percent)}%` : "?";
 				const target = args || "(whole diff)";
-				const skill = bundledSkillPath("simplify/SKILL.md");
+				const skill = bundledSkillPath("code-simplify/SKILL.md");
 				const scopeLabel = DIFF_SCOPES[outcome.scopeKind];
 				const contextPackage = buildContextPackage(outcome.diff, outcome.gitRoot, scopeLabel);
 				const verify = verifyLine(outcome.gitRoot);
@@ -231,7 +294,7 @@ export function registerDispatcher(pi: ExtensionAPI): void {
 					}),
 				);
 			} catch (err) {
-				ctx.ui.notify(`/simplify failed: ${err instanceof Error ? err.message : String(err)}`, "error");
+				ctx.ui.notify(`/code-simplify failed: ${err instanceof Error ? err.message : String(err)}`, "error");
 			}
 		},
 	});

package/src/loop.ts

@@ -0,0 +1,266 @@
+/**
+ * src/loop.ts — /code-review --loop: extension-driven fix→re-review cycles.
+ *
+ * Ported from the standalone Codex-style review extension's loop fixing
+ * (review → blocking-check → fix → re-review, bounded), with one deliberate
+ * deviation: the blocking decision reads the structured `review_report` JSON
+ * the skill must have written under the project's pi config dir
+ * (<cwd>/.pi/review/ by default — CONFIG_DIR_NAME) instead of scraping the
+ * assistant's markdown. The tool call is the report, so the JSON is the
+ * reliable artifact; markdown scraping was only ever a fallback.
+ *
+ * Loop shape (single-pass levels only — low/medium/high):
+ *   review turn → read newest report → OPEN P0/P1 findings (P0/P1 without a
+ *     decided outcome — a fix turn's re-report marks its findings
+ *     fixed/skipped/no_change_needed)?
+ *     none            → done
+ *     some, rounds left → fix prompt (followUp) → idle → re-review prompt → next round
+ *     some, rounds spent → stop with a safety-limit note
+ * Esc/abort or a missing report stops the loop.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import { OUTCOME_VALUES } from "./tools/review_report.ts";
+
+// --- pure helpers (unit-tested) ---------------------------------------------
+
+export const BLOCKING_PRIORITIES = ["P0", "P1"] as const;
+
+/** Strip a --loop flag out of the trailing args; report whether it was there.
+ *  Pure — unit-testable. */
+export function extractLoopFlag(rest: string): { wantLoop: boolean; rest: string } {
+	const tokens = (rest ?? "").split(/\s+/).filter(Boolean);
+	const kept = tokens.filter((t) => t !== "--loop");
+	return { wantLoop: kept.length !== tokens.length, rest: kept.join(" ") };
+}
+
+/** A blocking finding as surfaced back to the fix prompt. */
+export interface BlockingFinding {
+	file: string;
+	line?: number;
+	priority: string;
+	summary: string;
+}
+
+/** Extract P0/P1 findings from a parsed review_report JSON (lenient: any
+ *  shape mismatch → no findings rather than a throw). Pure — unit-testable. */
+export function blockingFindings(report: unknown): BlockingFinding[] {
+	if (!report || typeof report !== "object" || Array.isArray(report)) return [];
+	const raw = (report as { findings?: unknown }).findings;
+	if (!Array.isArray(raw)) return [];
+	const out: BlockingFinding[] = [];
+	for (const f of raw) {
+		if (!f || typeof f !== "object" || Array.isArray(f)) continue;
+		const rec = f as Record<string, unknown>;
+		if (rec.priority !== "P0" && rec.priority !== "P1") continue;
+		if (typeof rec.file !== "string" || rec.file.length === 0) continue;
+		// A decided outcome (a fix turn re-reports its findings with one, per
+		// the skill's fixed-later obligation) un-blocks the finding —
+		// re-prompting a fixed/skipped/declined finding just burns rounds.
+		if (typeof rec.outcome === "string" && (OUTCOME_VALUES as readonly string[]).includes(rec.outcome)) {
+			continue;
+		}
+		out.push({
+			file: rec.file,
+			line: typeof rec.line === "number" ? rec.line : undefined,
+			priority: rec.priority,
+			summary: typeof rec.summary === "string" ? rec.summary : "",
+		});
+	}
+	return out;
+}
+
+/** Newest `*.json` report under `dir` modified after `sinceMs`, or null.
+ *  Missing/unreadable dir → null. Pure — unit-testable. */
+export function latestReportFile(dir: string, sinceMs: number): string | null {
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return null;
+	}
+	let newest: { file: string; mtime: number } | null = null;
+	for (const e of entries) {
+		if (!e.isFile() || !e.name.endsWith(".json")) continue;
+		const file = path.join(dir, e.name);
+		try {
+			const mtime = fs.statSync(file).mtimeMs;
+			if (mtime <= sinceMs) continue;
+			if (!newest || mtime > newest.mtime) newest = { file, mtime };
+		} catch {
+			/* stat failed — skip this entry */
+		}
+	}
+	return newest?.file ?? null;
+}
+
+/** Parse a report JSON file; garbage → null (the loop must not crash on a
+ *  half-written or hand-edited file). */
+function readReport(file: string): unknown {
+	try {
+		return JSON.parse(fs.readFileSync(file, "utf8"));
+	} catch {
+		return null;
+	}
+}
+
+// --- loop driver -------------------------------------------------------------
+
+/** Minimal session view for the quiescence wait — structural, so
+ *  ExtensionCommandContext satisfies it and tests can drive the logic
+ *  without a live session. */
+export interface QuiescenceView {
+	isIdle(): boolean;
+	hasPendingMessages(): boolean;
+	waitForIdle(): Promise<void>;
+	signal?: { aborted: boolean };
+}
+
+/** Wait until the session is fully quiescent: nothing running AND nothing
+ *  queued. A single `waitForIdle()` is NOT enough — it resolves at the first
+ *  idle point even while follow-ups are still queued (a queued message does
+ *  not flip `isIdle` until its run actually starts), which is exactly the
+ *  window between `sendUserMessage(…, followUp)` and that turn's first
+ *  token. Aborts return false; there is no timeout — Esc is the escape
+ *  hatch, same as for the bare waitForIdle call. */
+export async function waitForQuiescent(session: QuiescenceView): Promise<boolean> {
+	for (;;) {
+		if (session.signal?.aborted) return false;
+		if (!session.isIdle() || session.hasPendingMessages()) {
+			await session.waitForIdle();
+			continue;
+		}
+		return true;
+	}
+}
+
+/** Poll until the review turn has started (idle → busy or a new assistant
+ *  message appears), then wait for it to finish. Returns false on timeout
+ *  or abort. Mirrors the reference extension's waitForLoopTurnToStart. */
+async function waitForTurnSettled(ctx: ExtensionCommandContext, baselineAssistantId: string): Promise<boolean> {
+	const START_TIMEOUT_MS = 15_000;
+	const POLL_MS = 50;
+	const deadline = Date.now() + START_TIMEOUT_MS;
+
+	const lastAssistantId = (): string | undefined => {
+		const branch = ctx.sessionManager.getBranch();
+		for (let i = branch.length - 1; i >= 0; i--) {
+			const entry = branch[i]!;
+			if (entry.type === "message" && entry.message.role === "assistant") return entry.id;
+		}
+		return undefined;
+	};
+
+	while (Date.now() < deadline) {
+		if (ctx.signal?.aborted) return false;
+		const current = lastAssistantId();
+		if (!ctx.isIdle() || ctx.hasPendingMessages() || (current && current !== baselineAssistantId)) {
+			// Wait past every queued message, not merely to the next idle
+			// point — waitForIdle() alone returns inside the gap between
+			// queueing a followUp and its run actually starting.
+			return waitForQuiescent(ctx);
+		}
+		await new Promise((resolve) => setTimeout(resolve, POLL_MS));
+	}
+	return false;
+}
+
+function baselineAssistantId(ctx: ExtensionCommandContext): string {
+	const branch = ctx.sessionManager.getBranch();
+	for (let i = branch.length - 1; i >= 0; i--) {
+		const entry = branch[i]!;
+		if (entry.type === "message" && entry.message.role === "assistant") return entry.id;
+	}
+	return "";
+}
+
+function fixPrompt(findings: BlockingFinding[]): string {
+	const list = findings
+		.map((f) => `- \`${f.file}${f.line != null ? `:${f.line}` : ""}\` [${f.priority}] ${f.summary}`)
+		.join("\n");
+	return [
+		"Fix the following blocking findings from the code review you just reported",
+		"(full failure scenarios are in the latest report JSON under .pi/review/):",
+		"",
+		list,
+		"",
+		"Apply minimal, surgical fixes — no drive-by refactors. Then re-report these",
+		"findings via the `review_report` tool with `outcome` set per finding",
+		"(fixed / skipped / no_change_needed) and run the verification guidance from",
+		"the review trigger message. Never leave the working tree verified-broken.",
+	].join("\n");
+}
+
+function reReviewPrompt(level: string): string {
+	return [
+		`Fixes applied. Re-run the code-review SINGLE-PASS flow for effort ${level} now`,
+		"— the diff has changed: re-resolve it, re-check the fixed locations and",
+		"sweep for regressions or newly exposed issues, then report via the",
+		"`review_report` tool again (fresh findings list, empty array if clean).",
+	].join("\n");
+}
+
+export interface LoopOptions {
+	/** The effort level the review runs at (echoed in re-review prompts). */
+	level: string;
+	/** Max fix→re-review rounds (config maxTurns.loop). */
+	passes: number;
+	/** Directory the review_report JSON files land in. */
+	reviewDir: string;
+}
+
+/**
+ * Drive the fix→re-review rounds after the FIRST review prompt has already
+ * been sent by the dispatcher. Each iteration reads the newest report (the
+ * first iteration sees the initial review's report, later ones the previous
+ * round's re-review) and sends at most one fix prompt. Runs at most `passes`
+ * fix→re-review rounds; the final iteration only reads the last re-review's
+ * verdict for the safety-limit message. Returns the number of fix rounds run.
+ */
+export async function runLoopFixing(
+	pi: ExtensionAPI,
+	ctx: ExtensionCommandContext,
+	options: LoopOptions,
+): Promise<number> {
+	const { level, passes, reviewDir } = options;
+	const baseline = baselineAssistantId(ctx);
+	const loopStart = Date.now();
+
+	let fixes = 0;
+	for (;;) {
+		if (!(await waitForTurnSettled(ctx, baseline))) return fixes;
+
+		const reportFile = latestReportFile(reviewDir, loopStart);
+		if (reportFile === null) {
+			ctx.ui.notify("/code-review --loop: no review_report JSON found — stopping the loop.", "warning");
+			return fixes;
+		}
+		const findings = blockingFindings(readReport(reportFile));
+		if (findings.length === 0) {
+			ctx.ui.notify(
+				fixes === 0
+					? "/code-review --loop: no P0/P1 findings — nothing to fix, loop done."
+					: `/code-review --loop: clean after ${fixes} fix round(s) — no open P0/P1 findings remain.`,
+				"info",
+			);
+			return fixes;
+		}
+		if (fixes === passes) {
+			ctx.ui.notify(
+				`/code-review --loop: ${findings.length} P0/P1 finding(s) still open after ${passes} fix round(s) — safety limit reached, stopping.`,
+				"warning",
+			);
+			return fixes;
+		}
+
+		fixes++;
+		ctx.ui.notify(
+			`/code-review --loop: ${findings.length} blocking finding(s) — fixing (round ${fixes}/${passes})…`,
+			"info",
+		);
+		await pi.sendUserMessage(fixPrompt(findings), { deliverAs: "followUp" });
+		if (!(await waitForTurnSettled(ctx, baseline))) return fixes;
+		pi.sendUserMessage(reReviewPrompt(level), { deliverAs: "followUp" });
+	}
+}

package/src/tools/review_report.ts

@@ -31,12 +31,19 @@ import * as path from "node:path";
 const VERDICT_VALUES = ["CONFIRMED", "PLAUSIBLE"] as const;
 const Verdict = StringEnum(VERDICT_VALUES);
 
-const OUTCOME_VALUES = ["fixed", "skipped", "no_change_needed"] as const;
 /** CC ReportFindings `outcome` 三档（2.1.227 二进制实证）。fixed-later 再上报时更新。 */
+export const OUTCOME_VALUES = ["fixed", "skipped", "no_change_needed"] as const;
 const Outcome = StringEnum(OUTCOME_VALUES);
 
+/** --loop 的 blocking 阈值：P0/P1 触发修复→再评审一轮（P2/P3 只入报告）。 */
+const PRIORITY_VALUES = ["P0", "P1", "P2", "P3"] as const;
+const Priority = StringEnum(PRIORITY_VALUES, {
+	description:
+		"优先级 P0（阻断，立刻修）/ P1（高）/ P2（中）/ P3（低）。--loop 循环修复以 P0/P1 为 blocking 阈值；省略视为 P2。",
+});
+
 // 供 SKILL-schema 同步测试引用（防漂移：SKILL 流程契约不得与常量脱节）。
-export { OUTCOME_VALUES, VERDICT_VALUES };
+export { PRIORITY_VALUES, VERDICT_VALUES };
 
 const Level = StringEnum([
 	"low",
@@ -59,6 +66,7 @@ const FindingParams = Type.Object({
 			"产生该发现的角度 slug：correctness / reuse / simplification / efficiency / altitude / conventions（或更具体如 test-coverage）。",
 	}),
 	verdict: Type.Optional(Verdict),
+	priority: Type.Optional(Priority),
 	short_summary: Type.Optional(
 		Type.String({
 			description:
@@ -108,6 +116,7 @@ type LooseFinding = {
 	line?: number;
 	category: string;
 	verdict?: string;
+	priority?: string;
 	short_summary?: string;
 	summary: string;
 	failure_scenario: string;
@@ -126,7 +135,10 @@ function sanitizeFinding(f: LooseFinding): { f: LooseFinding; note?: string } |
 		note = `（outcome "${outcome}" 非法，已归一化为 skipped）`;
 		outcome = "skipped";
 	}
-	return { f: { ...f, outcome }, note };
+	// 非法 priority 静默丢弃（降至未标注），不影响该条 finding 存活。
+	const priority =
+		f.priority !== undefined && (PRIORITY_VALUES as readonly string[]).includes(f.priority) ? f.priority : undefined;
+	return { f: { ...f, outcome, priority }, note };
 }
 
 /**
@@ -155,6 +167,7 @@ interface FindingInput {
 	line?: number;
 	category: string;
 	verdict?: string;
+	priority?: string;
 	short_summary?: string;
 	summary: string;
 	failure_scenario: string;
@@ -202,13 +215,14 @@ function renderReport(p: ReportInput): string {
 	lines.push("|---|------|------|------|------|");
 	for (let i = 0; i < p.findings.length; i++) {
 		const f = p.findings[i]!;
-		lines.push(`| ${i + 1} | ${escapeCell(f.verdict ?? "")} | ${escapeCell(f.category)} | ${escapeCell(fmtLoc(f))} | ${escapeCell(f.short_summary ?? f.summary)} |`);
+		const verdictCell = [f.priority, f.verdict].filter(Boolean).join(" · ");
+		lines.push(`| ${i + 1} | ${escapeCell(verdictCell)} | ${escapeCell(f.category)} | ${escapeCell(fmtLoc(f))} | ${escapeCell(f.short_summary ?? f.summary)} |`);
 	}
 	lines.push("");
 	lines.push("**详情**");
 	lines.push("");
 	p.findings.forEach((f, i) => {
-		const v = f.verdict ? ` *(${f.verdict})*` : "";
+		const v = [f.priority, f.verdict].filter(Boolean).length > 0 ? ` *(${[f.priority, f.verdict].filter(Boolean).join(" · ")})*` : "";
 		const out = f.outcome ? `\n修复结果：\`${f.outcome}\`` : "";
 		const note = f.note ? `\n${f.note}` : "";
 		lines.push(`**${i + 1}. ${fmtLoc(f)} — ${f.category}**${v}`);