@fyeeme/pi-review 1.0.0 → 1.0.2

package/README.md

@@ -29,6 +29,9 @@ From the package dir:
 npm install
 ```
 
+This resolves [`@fyeeme/pi-subagent-core`](https://www.npmjs.com/package/@fyeeme/pi-subagent-core)
+(`^0.3.0`, from the npm registry — no sibling-repo layout requirement).
+
 Then point pi at it (e.g. via your extensions config), or symlink into your pi
 extensions directory.
 
@@ -63,6 +66,17 @@ This is the deterministic mode selection a pure-prompt skill cannot reproduce
 `ctx.getContextUsage()`). The decision is announced in the trigger message so
 it is observable.
 
+**Apply → verify → revert safety net** (harden-code-simplify): after Phase 2
+applies the cleanups, the handler also injects a verification command detected
+from `package.json` scripts (`check` → `test` → `lint` → `typecheck`). The
+skill snapshots the touched files, applies the fixes, runs that command, and
+on failure auto-reverts per-file (a clean apply runs verify exactly once; only
+a failure escalates to one verify per touched file). The result is reported as
+structured outcomes via `review_report` (`level: "simplify"`), not a free-text
+summary. If no verification command is detectable, fixes are kept but the
+report states no verification was run (verification is opportunistic, never
+blocking).
+
 ### `subagent` tool
 
 An LLM-callable tool that spawns one or more real pi subprocesses:
@@ -70,9 +84,22 @@ An LLM-callable tool that spawns one or more real pi subprocesses:
 | mode | behavior |
 |---|---|
 | `single` | run `prompts[0]` once (e.g. an independent verify agent) |
-| `parallel` | run all prompts concurrently, capped at 8 (e.g. one finder per angle) |
+| `parallel` | run all prompts concurrently, capped at the ceiling (e.g. one finder per angle) |
 | `chain` | run sequentially; each later prompt receives prior output |
 
+**Fan-out guards** (harden-code-simplify, shared with `/code-review`):
+
+- **Recursion cap (whitelist-by-default)** — a spawned sub-agent does not
+  receive the `subagent` tool in its default toolset, so it cannot recurse. A
+  caller opts in by listing `subagent` in the child's `tools` whitelist; set
+  `PI_SUBAGENT_MAX_SPAWN_DEPTH` to allow multi-level fan-out up to a hard cap.
+- **Default turn budget** — fan-out agents get a finite default `maxTurns` (50,
+  aligned to CC's `FORKED_AGENT_DEFAULT_MAX_TURNS` in 2.1.227)
+  when the caller omits it; an explicit `0` is honored.
+- **Configurable concurrency** — `PI_MAX_CONCURRENT_SUBAGENTS` (default 20,
+  aligned to CC's `CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS ?? 20` in 2.1.227;
+  invalid values fall back to the default).
+
 Each sub-agent is a full `pi --mode json -p --no-session` run. Progress streams
 to the TUI via `onUpdate` as each agent completes. ESC aborts the whole batch
 (SIGTERM → 5s → SIGKILL per subprocess). Errors are thrown (not returned) so
@@ -85,8 +112,6 @@ pi-review/
 ├── index.ts                     factory: registerTool(subagent) + 2 commands
 ├── skills/                      bundled SKILL.md files (code-review, simplify)
 ├── src/
-│   ├── agent/dispatch.ts        spawnAgent + mapWithConcurrencyLimit (self-contained copy
-│   │                            from pi-dynamic-workflows; no external dep beyond node + pi-ai)
 │   ├── skills.ts                bundledSkillPath — resolve this extension's own skills/ dir
 │   ├── tools/subagent.ts        defineTool("subagent") — generic capability layer
 │   └── commands/
@@ -96,15 +121,18 @@ pi-review/
 ```
 
 The layout is deliberately layered: `src/tools/` is the **generic capability
-layer** (subagent tool + dispatch), `src/commands/` is the **entry layer** (one
+layer** (subagent tool), `src/commands/` is the **entry layer** (one
 file per skill). If a third or fourth skill needs the subagent tool, `src/tools/`
 can be split into its own `pi-subagent` extension with zero refactor — the code
 is already separated.
 
-`src/agent/dispatch.ts` is a self-contained copy of the spawn pattern from
-`examples/extensions/subagent` and `pi-dynamic-workflows/src/agent/dispatch.ts`
-(~150 lines). When pi promotes `spawnAgent` to a public `pi-coding-agent`
-export, this file should be deleted in favor of that import.
+The dispatch primitive (`spawnAgent`, `mapWithConcurrencyLimit`,
+`createSpawnRegistry`, `abortAgent`, `getPiInvocation` + types) lives in
+[`pi-subagent-core`](../pi-subagent-core) (npm `@fyeeme/pi-subagent-core`), a
+shared library extracted from the duplicated copies that used to live here and
+in `pi-dynamic-workflows`. When pi promotes `spawnAgent` to a public
+`pi-coding-agent` export, `pi-subagent-core` should be deleted in favor of that
+import.
 
 ## Relation to the skills
 
@@ -118,6 +146,12 @@ sub-agents are spawned and *which mode* is chosen.
 
 ## Status
 
-MVP. Phase 2 (not yet built): a `review_verify` tool encapsulating 3-vote
-adversarial verify, and a `review_report` tool enforcing the output schema /
-`--share` lavish artifact.
+`review_report` is built — schema aligned to CC `ReportFindings` (2.1.227
+empirical): 3-state `outcome` (`fixed`/`skipped`/`no_change_needed`), 2-value
+`verdict` (`CONFIRMED`/`PLAUSIBLE`), `short_summary` (≤60, table overview),
+`report_id` for fixed-later re-reports; renders the Chinese Markdown report
+and writes JSON to `<cwd>/.pi/review/` for CI / `--fix` / `--comment`.
+
+Remaining Phase 2 item (not yet built): a `review_verify` tool encapsulating
+3-vote adversarial verify. `--share` already routes through lavish-axi (see
+the code-review skill).

package/index.ts

@@ -4,6 +4,9 @@
  * Registers:
  *   - the `subagent` tool — general-purpose parallel/sequential sub-agent fan-out
  *     via real pi subprocesses. Shared capability used by both skills below;
+ *   - the `review_report` tool — structured findings sink for the code-review
+ *     skill (Pi's counterpart to CC's ReportFindings): renders the Markdown
+ *     report + writes JSON to <cwd>/.pi/review/ for CI;
  *   - the `/code-review` command — effort-level review via the code-review skill;
  *   - the `/code-simplify` command — cleanup via the simplify skill; the handler
  *     decides parallel vs single-pass from ctx.getContextUsage(), mirroring CC's
@@ -13,16 +16,25 @@
  * provides the entry commands + the fan-out capability they need.
  *
  * Layout (layered so the tool layer can be split into its own extension later):
- *   src/tools/subagent.ts    — generic capability (subagent tool + dispatch)
- *   src/commands/*.ts        — per-skill entry commands
+ *   src/tools/subagent.ts      — generic capability (subagent tool; dispatch from pi-subagent-core)
+ *   src/tools/review_report.ts — structured findings sink (review_report tool; CC ReportFindings counterpart)
+ *   src/commands/*.ts          — per-skill entry commands
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { isFanoutToolAllowed } from "@fyeeme/pi-subagent-core";
 import { registerCodeReview } from "./src/commands/code-review.ts";
 import { registerSimplify } from "./src/commands/code-simplify.ts";
 import { subagentTool } from "./src/tools/subagent.ts";
+import { reviewReportTool } from "./src/tools/review_report.ts";
 
 export default function (pi: ExtensionAPI): void {
-	pi.registerTool(subagentTool);
+	// The fan-out tool registers only when recursion is allowed for THIS
+	// process (top-level, or a child the spawner explicitly opted in AND that is
+	// below the max-depth cap). A default child — spawned without the fan-out
+	// tool in its whitelist — loads without it, so it physically cannot recurse.
+	// This is the whitelist-by-default recursion guard (harden-code-simplify).
+	if (isFanoutToolAllowed()) pi.registerTool(subagentTool);
+	pi.registerTool(reviewReportTool);
 	registerCodeReview(pi);
 	registerSimplify(pi);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fyeeme/pi-review",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Review & cleanup extension for pi. Registers /code-review and /code-simplify commands plus a general-purpose `subagent` tool that spawns parallel pi subprocesses — providing the real fan-out capability the code-review and simplify skills (bundled under `skills/`) need for their multi-agent flows. The /code-simplify handler uses ctx.getContextUsage() to decide parallel vs single-pass mode deterministically.",
   "type": "module",
   "license": "MIT",
@@ -34,16 +34,21 @@
     "test": "vitest --run",
     "typecheck": "tsc"
   },
+  "dependencies": {
+    "@fyeeme/pi-subagent-core": "^0.3.3"
+  },
   "peerDependencies": {
-    "@earendil-works/pi-ai": ">=0.77.0",
-    "@earendil-works/pi-coding-agent": ">=0.77.0",
+    "@earendil-works/pi-ai": ">=0.84.1",
+    "@earendil-works/pi-coding-agent": ">=0.84.1",
+    "@earendil-works/pi-tui": ">=0.84.1",
     "jiti": ">=2.0.0",
     "typebox": ">=1.0.0",
     "typescript": ">=5.0.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "0.77.0",
-    "@earendil-works/pi-coding-agent": "0.77.0",
+    "@earendil-works/pi-ai": "0.84.1",
+    "@earendil-works/pi-coding-agent": "0.84.1",
+    "@earendil-works/pi-tui": "0.84.1",
     "@types/node": "22.19.19",
     "jiti": "2.7.0",
     "typebox": "1.1.38",

package/skills/code-review/SKILL.md

@@ -10,24 +10,27 @@ description: "Review the current diff for correctness bugs and reuse/simplificat
   earlier v2.1.220 reconstruction. Every section below was located in the
   extracted strings (cc_strings_223.txt) and verified.
 
-  What CC 2.1.223 actually contains (verified against the binary):
-    - Effort: medium = precision; high = recall ("err on the side of
-      surfacing"); xhigh/max add a gap-hunt. Each finder surfaces ≤6 candidates.
+  What CC 2.1.227 actually contains (verified against the binary):
+    - 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
+      ("err on the side of surfacing"); xhigh/max add a gap-hunt (≤8 new
+      candidates). Correctness angles are taken in order A→E (`slice(0, N)`).
+    - Inline finder allocation: medium/high = 8 finders (A/B/C + 3 cleanup +
+      altitude + conventions); xhigh/max = 10 finders (A–E + same). Each
+      cleanup angle gets its own finder.
     - Low effort: 1 diff pass, no verify, target min(files_changed, 4) findings.
-    - Finder allocation (workflow Find-phase, linearized inline for Pi): one
-      finder per correctness angle (A–E) + Conventions, plus one combined cleanup
-      finder, pooled before verify. (CC's native *inline* medium path splits
-      differently — 8 finders: 3 correctness + 3 cleanup + altitude + conventions.)
+    - Verify via an independent agent, grouped by (file, line) (absorbed from
+      the workflow GROUP_VERDICT_SCHEMA): CONFIRMED / PLAUSIBLE / REFUTED,
+      "PLAUSIBLE by default". Keep CONFIRMED + PLAUSIBLE, drop REFUTED.
+    - ReportFindings schema: verdict CONFIRMED|PLAUSIBLE, outcome
+      fixed|skipped|no_change_needed, finding carries short_summary (≤60).
     - Angles A–E + Reuse/Simplification/Efficiency/Altitude + Conventions,
       verbatim (same source variables the /simplify skill reuses).
-    - Verify via an independent agent: CONFIRMED / PLAUSIBLE / REFUTED,
-      "PLAUSIBLE by default". Keep CONFIRMED + PLAUSIBLE, drop REFUTED.
     - Gap-hunt (xhigh/max): one fresh finder hunting only for gaps not
       already listed (CC's Sweep phase: "Fresh finder hunting only for gaps").
-    - Output: Markdown findings table + per-finding details block, printed
-      as text (no ReportFindings tool on Pi); carries file:line/category/
-      verdict/summary/failure_scenario per finding.
-    - --share publishes an Artifact; --fix applies findings to the working tree.
+    - 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>]
     target = Class#method | file path | PR number | branch name
@@ -41,9 +44,13 @@ description: "Review the current diff for correctness bugs and reuse/simplificat
   Pi ADAPTATIONS (differ from the CC runtime)
   ════════════════════════════════════════════════════════════════════════
     1. Output   — CC calls a ReportFindings tool with {level, findings}; Pi
-                  PRINTS a Markdown findings table + details block as text
-                  (no such tool on Pi). [was JSON array; switched for
-                  readability]
+                  uses this extension's `review_report` tool (the Pi counterpart
+                  to ReportFindings, verdict/outcome enums aligned to CC
+                  v2.1.227): it 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. If the tool is absent, fall back to printing the
+                  Markdown as text.
     2. Fan-out  — CC uses the Agent tool; Pi uses the `subagent` tool
                   (mode: parallel), or runs angles sequentially if unavailable.
     3. Verify   — CC uses the Agent tool; Pi uses `subagent` for the
@@ -68,15 +75,26 @@ altitude, and conventions findings when the output cap forces a cut.
 
 ## Effort levels
 
-| Level | Intent | Verify | Subagents | Output cap |
+| Level | Intent | Verify | Subagents | 四元组 `{correctnessAngles, perAngle, maxFindings, sweep}` |
 |-------|--------|--------|-----------|------------|
-| low (default) | quick scan | no | no | min(files_changed, 4) |
-| medium | **precision** — surface only findings a maintainer would act on | independent agent | fan-out (1 finder/angle) | ≤ 8 |
-| high | **recall** — catch every real bug a careful reviewer would; **err on the side of surfacing** | independent agent | more angles | ≤ 10 |
-| xhigh → max | recall + **gap-hunt** | independent agent | above + 1 fresh gap finder | larger, may include uncertain |
+| 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 |
+
+**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):
+
+- `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).
 
-Each finder surfaces **up to 6 candidate findings** with `file`, `line`, a
-one-line `summary`, and a concrete `failure_scenario`.
+Each finder surfaces up to `perAngle` candidate findings with `file`, `line`, a
+one-line `summary`, a ≤60-char `short_summary`, and a concrete
+`failure_scenario`.
 
 If a target argument was provided, review that target instead of the whole diff.
 
@@ -90,6 +108,43 @@ commit. If a PR number, branch name, or file path was passed as an argument,
 review that target instead. Treat this diff as the review scope. Note the
 files-changed count — low effort uses it for the dynamic output cap.
 
+## Phase 0.5 — Scope (run once in the main session, before any fan-out)
+
+Before dispatching any finder, establish the review scope yourself in this
+session (absorbed from CC's workflow Scope phase: turns N repeated
+discoveries by subagents into one, and keeps every subagent on the same
+scope — subagents stop running their own `git diff` / CLAUDE.md discovery):
+
+1. Run the diff command from Phase 0 and **confirm it is non-empty**. If it is
+   empty (or the target is invalid), terminate here — report that there is
+   nothing to review, spawn no subagents.
+2. List the changed files, plus the files-changed count.
+3. Find the applicable CLAUDE.md files (user-level, repo-root, plus any in a
+   directory that is an ancestor of a changed file) and read them; extract the
+   conventions relevant to the diff.
+4. Write a short change summary (what the diff does, 2–4 lines).
+
+Assemble these into a scope block:
+
+```
+## Review scope
+
+Diff command: <the exact command>
+Changed files: <list>
+Files changed count: <n>
+Applicable CLAUDE.md files: <list>
+Conventions: <the extracted rules relevant to the diff>
+Change summary: <2–4 lines>
+
+Target parameter (informational only): <target args, if any — do not perform
+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.
+
 ---
 
 # LOW-EFFORT FLOW  (default; runs standalone, no subagents)
@@ -118,7 +173,9 @@ 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. Do not call a ReportFindings tool even if one is available.
+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)`，不调用任何上报工具。
 
 ---
 
@@ -131,13 +188,25 @@ 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** (the workflow Find-phase, linearized inline for Pi;
-verbatim from the binary): **one finder per correctness angle, plus one finder
-covering all cleanup angles, pooled before verify** — not a priority-sorted
-packing. That is one finder each for A/B/C/D/E plus Conventions, and one
-combined finder for the cleanup angles (Reuse / Simplification / Efficiency /
-Altitude). Never silently drop a correctness angle; if you must consolidate,
-fold cleanup into a correctness finder.
+**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.
+
+Each cleanup angle (Reuse / Simplification / Efficiency) gets its own finder;
+Altitude and Conventions are independent finders. Never silently drop an
+angle — if you must consolidate (subagent unavailable), fold the cleanup
+angles into a correctness finder, but say so in the report.
+
+**Suppression 禁令（xhigh/max）** — different finders may surface different
+candidates for the same line with different reasons. At xhigh/max all of them
+are recorded and pass through verify independently: do NOT let one angle's
+conclusions suppress another's — record both.
 
 The correctness angles hunt for bugs; the cleanup angles hunt for cleanup in
 the changed code. Cleanup, altitude, and conventions candidates use the same
@@ -180,29 +249,33 @@ through a registry/session/global — e.g. a caching provider holding a
 wrapper forwards all the methods the callers actually use.
 
 ### Reuse
-Flag new code that re-implements something the codebase already has — Grep
-shared/utility modules and files adjacent to the change, and name the existing
-helper to call instead.
+
+Flag new code that re-implements something the codebase
+already has — Grep shared/utility modules and files adjacent to the change,
+and name the existing helper to call instead.
 
 ### Simplification
+
 Flag unnecessary complexity the diff adds: redundant or derivable state,
-copy-paste with slight variation, deep nesting, dead code left behind. Name the
-simpler form that does the same job.
+copy-paste with slight variation, deep nesting, dead code left behind. Name
+the simpler form that does the same job.
 
 ### Efficiency
+
 Flag wasted work the diff introduces: redundant computation or repeated I/O,
-independent operations run sequentially, blocking work added to startup or hot
-paths. Also flag long-lived objects built from closures or captured environments
-— they keep the entire enclosing scope alive for the object's lifetime (a memory
-leak when that scope holds large values); prefer a class/struct that copies only
-the fields it needs. Name the cheaper alternative.
+independent operations run sequentially, blocking work added to startup or
+hot paths. Also flag long-lived objects built from closures or captured
+environments — they keep the entire enclosing scope alive for the object's
+lifetime (a memory leak when that scope holds large values); prefer a
+class/struct that copies only the fields it needs. Name the cheaper
+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 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.
 ### 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
@@ -222,15 +295,36 @@ are the dominant cause of misses.
 
 ## Phase 2 — Dedup and verify
 
-Dedup near-duplicates (same defect, same location, same reason → keep one).
-
-Then verify each candidate. If the `subagent` tool is available, dispatch an
-independent verify agent (one per candidate, or a small batch): give it the
-diff, the relevant file(s), and the candidate; it returns exactly one of
-**CONFIRMED / PLAUSIBLE / REFUTED**. An independent agent counters the
-confirmation bias of self-review. If `subagent` is unavailable, fall back to
-re-checking each candidate yourself (self-check). Keep **CONFIRMED and
-PLAUSIBLE**, drop REFUTED. Give each surviving finding a verdict:
+Dedup near-duplicates (same defect, same location, same reason → keep one;
+different reasons for the same line are NOT duplicates — at xhigh/max both
+are kept per the suppression ban).
+
+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
+returns a verdict per candidate:
+
+```
+[{ "index": <candidate index>, "verdict": "CONFIRMED" | "PLAUSIBLE" | "REFUTED", "evidence": "<quote/argument>" }, ...]
+```
+
+Grouping is by location, NOT dedup — each candidate is judged independently;
+same-location candidates may describe different defects. A candidate the
+verifier omitted (interrupted or skipped an index) is **dropped** — never
+invent a PLAUSIBLE for it. One verifier failure drops its whole group (the
+same trade-off CC's workflow makes); if you are not confident in a group's
+verifier, fall back to one verifier per candidate for that group.
+
+This group-by-location verify is a deliberate absorption of CC's workflow
+optimization into the inline path (CC inline dispatches one verifier per
+candidate): a location with 3 candidates costs 1 verifier instead of 3 —
+~40% fewer verifier agents is the expectation, not a guarantee.
+
+If `subagent` is unavailable, fall back to re-checking each candidate yourself
+(self-check). Keep **CONFIRMED and PLAUSIBLE**, drop REFUTED. Give each
+surviving finding a verdict:
 
 - **CONFIRMED** — can name the inputs/state that trigger it and the wrong
   output or crash. Quote the line.
@@ -246,6 +340,12 @@ 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.
+
 **REFUTED** only when constructible from the code: factually wrong (quote the
 actual line); provably impossible (type/constant/invariant — show it); already
 handled in this diff (cite the guard); or pure style with no observable effect.
@@ -254,7 +354,8 @@ 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.
+already listed — **at most 8 new candidates**. 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):
@@ -277,48 +378,49 @@ At **high and below**, skip Phase 3.
 
 ## Output
 
-Print the findings as a **Markdown table + a details block** — readable in a
-terminal and in rendered Markdown (no JSON, no ReportFindings tool on Pi). Cap =
-low's min(files_changed, 4); 8 at medium; 10 at high; larger at xhigh → max.
-
-**全部用中文输出**：表头、概述、场景一律用中文；`Verdict`、`Category` 作为标识符保留
-英文 token（CONFIRMED / PLAUSIBLE；correctness / reuse …）。
-
-**1. 表头行** — 单行写明：力度、diff 命令/范围、改动文件数、命中条数、是否真的多智能体
-并发（见下文 Single-pass honesty）。示例：
-
-> `max` · `git diff HEAD` · 29 个文件 · 3 条发现 · 多智能体（验证 + 查漏）
-
-**2. 发现汇总表** — 按严重程度从高到低，每条一行：
-
-| # | 判定 | 类别 | 位置 | 概述 |
-|---|------|------|------|------|
-| 1 | CONFIRMED | correctness | path/file.ext:123 | 一句话说明这个 bug |
-| 2 | PLAUSIBLE | reuse | path/file.ext:45 | … |
-
-- `判定` — `CONFIRMED` / `PLAUSIBLE` / 留空（未做验证）。
-- `类别` — 产生该发现的角度，短横线小写 slug（`correctness`、`simplification`、
-  `efficiency`、`reuse`、`altitude`、`conventions`，或更具体的如 `test-coverage`）。
-- `位置` — `文件:行号`。
-- `概述` — 一句话说明（≤ 约 80 字，同时作为紧凑标签）。
-
-**3. 详情块** — 与表格同序；场景放不进单元格，在这里展开：
-
-**1. path/file.ext:123 — 类别** *(判定)*
-概述：<一句话>
-场景：<具体的输入/状态 → 错误输出/崩溃；若是清理类发现，写明具体代价——重复了什么、
-浪费了什么、哪里更难维护，或违反了哪条规则>
-
-If more than `{cap}` survive, keep the `{cap}` most severe (correctness outranks
-cleanup/altitude/conventions when cutting). If nothing survives, print the header
-line with count 0 and skip the table and details — don't emit an empty table.
-
-### Single-pass honesty
-
-If this review did not actually fan out — low effort, or medium+ where the
-`subagent` tool was unavailable so the angles ran sequentially in one context —
-state clearly in the header line that this was a single-pass review done without the
-multi-agent fan-out, so whoever reads it isn't misled about what actually ran.
+Report the findings via the `review_report` tool (this extension's counterpart
+to CC's `ReportFindings`) — call it **once** with
+`{ level, target, files_changed, fanned_out, report_id, findings }`, findings
+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.
+
+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 字符、纯声明——去掉理由与
+后果，汇总表概述列优先使用它；示例：`"off-by-one in loop bound"`),
+`summary` (一行中文，含理由与后果，详情块使用), `failure_scenario`
+(concrete input/state → wrong output/crash; for cleanup findings, the
+concrete cost — Chinese). When re-reporting after applying `--fix`, set
+`outcome` on each finding (`fixed` / `skipped` / `no_change_needed` — CC
+`ReportFindings` 三档，2.1.227 实证).
+
+Cap = `maxFindings` from the effort table: `min(files_changed, 4)` at low; 8
+at medium; 10 at high; 15 at xhigh/max. If more than the cap survive, send
+the cap most severe (correctness outranks cleanup/altitude/conventions when
+cutting; CONFIRMED outranks PLAUSIBLE). If nothing survives, send an empty
+`findings` array — the tool prints a zero-count header.
+
+**Fixed-later 义务** (CC `Q8m`): if, after this report, any later work in this
+session fixes one of the reported findings (a user-requested fix, or a fix
+that comes along with other changes), you MUST call `review_report` again
+with the same `report_id`, the same findings, and updated `outcome` values —
+before writing any text summary. The re-report updates states only; it does
+not repeat the findings text. Generate the `report_id` (e.g. `review-<ts>`)
+on the first report and reuse it on every re-report so consumers can merge
+the files by id.
+
+**全部用中文**：`summary` 与 `failure_scenario` 一律中文；`verdict`、`category`、
+`outcome` 作为标识符保留英文 token。
+
+**`fanned_out` 诚实** — 准确设置：仅当多智能体 fan-out 真的跑起来（subagent
+finder + verify agent）才为 `true`；low effort 或任何单遍/自审降级为 `false`。该
+字段会出现在报告表头，让读者不被误导（替代旧的 Single-pass honesty 小节）。
+
+**降级** — 若 `review_report` 工具未注册（这份 SKILL.md 跑在 pi-review 扩展之外），
+退回到直接打印 Markdown 表格 + 详情块文本；不要报错。
 
 ---
 
@@ -329,8 +431,14 @@ 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. Finish with a brief summary of what was fixed
-and what was skipped.
+skip rather than arguing with it. 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.
+If `review_report` is unavailable, fall back to a brief text summary of what was
+fixed and what was skipped.
 
 ## Posting comments (--comment)