@fyeeme/pi-review 2.0.0 → 2.1.0

package/README.md

@@ -1,157 +1,103 @@
-# pi-review
+# @fyeeme/pi-review (v2)
 
-Review & cleanup extension for [pi](https://github.com/earendil-works/pi).
+**2.0.0 — major release** (from 1.1.1), part of the 2.0 extensions family wave:
 
-Registers two commands (`/code-review` and `/code-simplify`) and a general-purpose
-`subagent` tool that spawns parallel pi subprocesses — providing the **real
-fan-out capability** that the `code-review` and `simplify` skills
-(bundled in this package under `skills/`) need for their multi-agent flows.
+- **Sandwich architecture** — skills carry the methodology, `prompts/` carries the orchestration strategy as data (parallel-when guards in frontmatter, phases in the body), `agents/` carries the 12 review roles (finder A–E, cleaner-reuse/simplification/efficiency, altitude, conventions, verifier, gap-hunter), and a thin plugin entry composes the stack.
 
-## Why
+- **Batteries-included fan-out** — the entry composes [`@fyeeme/pi-subagents`](https://www.npmjs.com/package/@fyeeme/pi-subagents) 2.1.1 from its npm dependency: the `subagent` tool, real `pi` subprocess spawning, and the live agent UI (widget / FleetView / `/agents`) work out of the box.
 
-Both skills instruct the agent to fan out sub-agents (finders / verify /
-cleanup angles), but `pi-subagents` does not exist in pi — so the agent
-silently degraded to a sequential self-sweep. This extension ships the actual
-fan-out primitive: an LLM-callable `subagent` tool that spawns real
-`pi --mode json` subprocesses.
+- **`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`.
 
-This is the "tool + prompt" architecture: the **tool** provides deterministic
-dispatch (how many agents, parallelism, abort), the **skill** provides the
-review/cleanup semantics. CC's own `/code-review` and `/code-simplify` work the same
-way — one general Agent tool, prompt decides how to use it.
+- **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.
 
-## Install
+- **`/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.
 
-This package peers on `@earendil-works/pi-coding-agent` / `pi-ai` + `typebox`.
-From the package dir:
+- Commands: `/code-review` and `/code-simplify` — restored v1 names (2.0.0 briefly renamed them `/review` / `/simplify`).
 
-```sh
-npm install
+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 (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
+           /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
 ```
 
-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).
+**Batteries included**: installing this package is enough. Its extension
+factory composes [`@fyeeme/pi-subagents`](../pi-subagents) (the `subagent`
+tool, spawning, and the live agent UI — widget / FleetView / `/agents`) from
+the version-pinned dependency copy, so every fan-out the skills orchestrate
+works out of the box. A standalone pi-subagents install is optional
+(general-purpose scout/planner/reviewer/worker agents) and coexists —
+composition is idempotent.
+
+## Commands
 
-Then point pi at it (e.g. via your extensions config), or symlink into your pi
-extensions directory.
+- `/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).
 
-## What it registers
+Reports land via the `review_report` tool: Chinese Markdown back to the conversation plus machine-readable JSON under `<cwd>/.pi/review/`.
 
-### `/code-review` command
+## Strategy is data
 
 ```
-/code-review [low|medium|high|xhigh|max] [--fix] [--comment] [--share] [<target>]
+# prompts/simplify.parallel.md
+---
+parallel-when:
+  context-below: 0.8
+  diff-chars-below: 400000
+---
 ```
 
-Parses args, then asks the agent to load the bundled `skills/code-review/SKILL.md`
-and follow it — using the `subagent` tool for any fan-out / verify / gap-hunt.
+Edit the file, the strategy changes. The dispatcher only executes what the templates declare (the unmeasurable-context and recursion-guard fallbacks stay as code invariants). See `test/dispatch.test.ts` for the anchored semantics.
 
-### `/code-simplify` command
+## Configuration
 
+Turn budgets are configurable via a JSON file, following the same two-layer
+pattern as pi-subagents' `pi-subagent.json` (project overrides global):
+
+- Global: `<agentDir>/pi-review.json`
+- Project: `<cwd>/.pi/pi-review.json`
+
+```jsonc
+// <any layer>/pi-review.json — all keys optional
+{
+  "maxTurns": {
+    "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)
+  }
+}
 ```
-/code-simplify [<target>]
-```
 
-Cleanup (reuse / simplification / efficiency / altitude) via the `simplify`
-skill. **The handler decides parallel vs single-pass mode deterministically**
-from `ctx.getContextUsage()` (real token count) + whether the `subagent` tool is
-registered — mirroring CC's `Jvo` guard:
-
-- context < 80% full AND `subagent` tool available → **parallel** (4 cleanup
-  agents via `subagent` mode: parallel)
-- otherwise → **single-pass** (inline 4 angles)
-
-This is the deterministic mode selection a pure-prompt skill cannot reproduce
-(the skill has no access to context-token count; only extension code can call
-`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:
-
-| mode | behavior |
-|---|---|
-| `single` | run `prompts[0]` once (e.g. an independent verify agent) |
-| `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
-the agent loop marks the result `isError`.
-
-## Architecture (layered)
+Values must be positive integers; anything else (or an absent file) falls back
+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 `/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.
+
+## Requirements
+
+None beyond this package. `@fyeeme/pi-subagents` 2.1.1 is a regular npm dependency (exact-pinned) whose extension factory this entry composes (tool + UI). The four cleaner agents and the finder/verifier/gap-hunter definitions ship with this package, registered via `addAgentDir` at extension load.
+
+## Development
 
 ```
-pi-review/
-├── index.ts                     factory: registerTool(subagent) + 2 commands
-├── skills/                      bundled SKILL.md files (code-review, simplify)
-├── src/
-│   ├── skills.ts                bundledSkillPath — resolve this extension's own skills/ dir
-│   ├── tools/subagent.ts        defineTool("subagent") — generic capability layer
-│   └── commands/
-│       ├── code-review.ts       /code-review handler + sticky last-used effort (CC 2.1.223)
-│       └── code-simplify.ts     /code-simplify handler + decideSimplifyMode (Jvo guard)
-└── test/                        commands unit tests
+npm install --ignore-scripts   # @fyeeme/pi-subagents resolves from the npm registry
+npm test                       # vitest
+npm run typecheck
 ```
 
-The layout is deliberately layered: `src/tools/` is the **generic capability
-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.
-
-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
-
-| layer | home | role |
-|---|---|---|
-| review/cleanup semantics (angles, verdicts, mode bodies) | `skills/code-review/` + `skills/simplify/` (bundled in this package) | what to look for |
-| fan-out dispatch + mode decision | this extension (`subagent` tool + command handlers) | how to run sub-agents / which mode |
-
-Edit a skill to change *what* it hunts; edit this extension to change *how*
-sub-agents are spawned and *which mode* is chosen.
-
-## Status
-
-`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).
+To test local pi-subagents changes alongside this package, temporarily point the
+dependency back at the sibling checkout (`file:../pi-subagents`) and reinstall;
+restore the pinned registry version before publishing.

package/agents/cleaner-altitude.md

@@ -0,0 +1,18 @@
+---
+name: cleaner-altitude
+description: Checks each change fixes the root cause at the right depth, not as a fragile bandaid (simplify Altitude angle / review Altitude finder)
+tools: read, grep, find, ls, bash
+---
+You are an altitude (right-depth) reviewer. Review the changed code given to
+you for altitude issues.
+
+Check that each change fixes the root cause at the right depth rather than
+patching a symptom with a fragile bandaid. Special cases layered on shared
+infrastructure are a sign the fix isn't deep enough — prefer the simpler,
+more general change to the underlying mechanism over adding special cases,
+and name that change.
+
+Return your findings as a concise list. For each finding: `file:line` —
+one-line summary — the concrete cost (what is fragile or will not
+generalize), naming the deeper change. Do not propose applying fixes; report
+only. An empty list is a valid answer.

package/agents/cleaner-efficiency.md

@@ -0,0 +1,19 @@
+---
+name: cleaner-efficiency
+description: Flags wasted work the diff introduces (simplify Efficiency angle / review Efficiency finder)
+tools: read, grep, find, ls, bash
+---
+You are an efficiency reviewer. Review the changed code given to you for
+efficiency opportunities.
+
+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.
+
+Return your findings as a concise list. For each finding: `file:line` —
+one-line summary — the concrete cost. Do not propose applying fixes; report
+only. An empty list is a valid answer.

package/agents/cleaner-reuse.md

@@ -0,0 +1,16 @@
+---
+name: cleaner-reuse
+description: Flags new code that re-implements something the codebase already has (simplify Reuse angle / review Reuse finder)
+tools: read, grep, find, ls, bash
+---
+You are a reuse reviewer. Review the changed code given to you for reuse
+cleanup opportunities.
+
+Grep shared/utility modules and files adjacent to the change; flag new code
+that re-implements something the codebase already has, and name the existing
+helper to call instead.
+
+Return your findings as a concise list. For each finding: `file:line` —
+one-line summary — the concrete cost (what is duplicated, wasted, or harder
+to maintain). Do not propose applying fixes; report only. An empty list is a
+valid answer.

package/agents/cleaner-simplification.md

@@ -0,0 +1,16 @@
+---
+name: cleaner-simplification
+description: Flags unnecessary complexity the diff adds (simplify Simplification angle / review Simplification finder)
+tools: read, grep, find, ls, bash
+---
+You are a simplification reviewer. Review the changed code given to you for
+simplification opportunities.
+
+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.
+
+Return your findings as a concise list. For each finding: `file:line` —
+one-line summary — the concrete cost (what is duplicated, wasted, or harder
+to maintain). Do not propose applying fixes; report only. An empty list is a
+valid answer.

package/agents/finder-conventions.md

@@ -0,0 +1,23 @@
+---
+name: finder-conventions
+description: "Conventions finder: CLAUDE.md/AGENTS.md rule violations in the changed code"
+tools: read, grep, find, ls, bash
+---
+You are a conventions finder.
+
+Find the CLAUDE.md/AGENTS.md files that govern the changed code you are
+given: the user-level ~/.claude/CLAUDE.md, the repo-root CLAUDE.md, plus any
+CLAUDE.md or CLAUDE.local.md (or AGENTS.md) in a directory that is an
+ancestor of a changed file (a directory's file only applies to files at or
+below it). Read each one that exists, then check the diff for clear
+violations of the rules they state.
+
+Only flag a violation when you can quote the exact rule and the exact line
+that breaks it — no style preferences, no vague "spirit of the doc"
+inferences. In the finding, name the doc path and quote the rule so the
+report can cite it. If no doc applies, return an empty array.
+
+Your LAST assistant message must be your JSON candidate array — `[]` is a
+valid answer. Each candidate: `{"file", "line"?, "category":
+"conventions", "summary", "failure_scenario"}` (the failure_scenario states
+which quoted rule is broken and the concrete cost).

package/agents/finder-cross-file.md

@@ -0,0 +1,21 @@
+---
+name: finder-cross-file
+description: "Correctness angle C: cross-file tracer"
+tools: read, grep, find, ls, bash
+---
+You are a correctness finder (angle C — cross-file tracer).
+
+For each function the diff you are given changes, find its callers (grep for
+the symbol) and check whether the change breaks any call site: a new
+precondition, a changed return shape, a new exception, a timing/ordering
+dependency. Also check callees: does a parallel change in the same PR make a
+call unsafe?
+
+Spend your tool-call budget on the highest-risk hunks first; when half is
+spent, stop opening new files. Your LAST assistant message must be your JSON
+candidate array — `[]` is a valid answer. Partial output beats none.
+
+Each candidate: `{"file", "line"?, "category": "correctness", "summary",
+"failure_scenario"}` — the failure_scenario names a concrete input/state →
+wrong output or crash. Pass every candidate with a nameable failure scenario
+through; do not silently drop half-believed candidates.

package/agents/finder-diff-scan.md

@@ -0,0 +1,23 @@
+---
+name: finder-diff-scan
+description: "Correctness angle A: line-by-line diff scan"
+tools: read, grep, find, ls, bash
+---
+You are a correctness finder (angle A — line-by-line diff scan).
+
+Read every hunk in the diff you are given, line by line. Then read the
+enclosing function for each hunk — bugs in unchanged lines of a touched
+function are in scope (the PR re-exposes or fails to fix them). For every
+line ask: what input, state, timing, or platform makes this line wrong?
+Look for inverted/wrong conditions, off-by-one, null/undefined deref,
+missing `await`, falsy-zero checks, wrong-variable copy-paste, error
+swallowed in catch, unescaped regex metachars.
+
+Spend your tool-call budget on the highest-risk hunks first; when half is
+spent, stop opening new files. Your LAST assistant message must be your JSON
+candidate array — `[]` is a valid answer. Partial output beats none.
+
+Each candidate: `{"file", "line"?, "category": "correctness", "summary",
+"failure_scenario"}` — the failure_scenario names a concrete input/state →
+wrong output or crash. Pass every candidate with a nameable failure scenario
+through; do not silently drop half-believed candidates.

package/agents/finder-language-pitfall.md

@@ -0,0 +1,21 @@
+---
+name: finder-language-pitfall
+description: "Correctness angle D: language-pitfall specialist"
+tools: read, grep, find, ls, bash
+---
+You are a correctness finder (angle D — language-pitfall specialist).
+
+Scan the diff you are given for the classic pitfalls of its
+language/framework — for example: JS falsy-zero, `==` coercion,
+closure-captured loop var; Python mutable default args, late-binding
+closures; Go nil-map write, range-var capture; SQL injection;
+timezone/DST drift; float equality. Flag any instance the diff introduces.
+
+Spend your tool-call budget on the highest-risk hunks first; when half is
+spent, stop opening new files. Your LAST assistant message must be your JSON
+candidate array — `[]` is a valid answer. Partial output beats none.
+
+Each candidate: `{"file", "line"?, "category": "correctness", "summary",
+"failure_scenario"}` — the failure_scenario names a concrete input/state →
+wrong output or crash. Pass every candidate with a nameable failure scenario
+through; do not silently drop half-believed candidates.

package/agents/finder-removed-behavior.md

@@ -0,0 +1,21 @@
+---
+name: finder-removed-behavior
+description: "Correctness angle B: removed-behavior auditor"
+tools: read, grep, find, ls, bash
+---
+You are a correctness finder (angle B — removed-behavior auditor).
+
+For every line the diff you are given DELETES or replaces, name the
+invariant or behavior it enforced, then search the new code for where that
+invariant is re-established. If you can't find it, that's a candidate: a
+removed guard, a dropped error path, a narrowed validation, a deleted test
+that was covering a real case.
+
+Spend your tool-call budget on the highest-risk hunks first; when half is
+spent, stop opening new files. Your LAST assistant message must be your JSON
+candidate array — `[]` is a valid answer. Partial output beats none.
+
+Each candidate: `{"file", "line"?, "category": "correctness", "summary",
+"failure_scenario"}` — the failure_scenario names a concrete input/state →
+wrong output or crash. Pass every candidate with a nameable failure scenario
+through; do not silently drop half-believed candidates.

package/agents/finder-wrapper-proxy.md

@@ -0,0 +1,23 @@
+---
+name: finder-wrapper-proxy
+description: "Correctness angle E: wrapper/proxy correctness"
+tools: read, grep, find, ls, bash
+---
+You are a correctness finder (angle E — wrapper/proxy correctness).
+
+When the diff you are given adds or modifies a type that wraps another
+(cache, proxy, decorator, adapter): check that every method routes to the
+wrapped instance and not back through a registry/session/global — e.g. a
+caching provider holding a `delegate` field that resolves IDs via
+`session.get(...)` instead of `delegate.get(...)` will re-enter the cache or
+recurse. Also check that the wrapper forwards all the methods the callers
+actually use.
+
+Spend your tool-call budget on the highest-risk hunks first; when half is
+spent, stop opening new files. Your LAST assistant message must be your JSON
+candidate array — `[]` is a valid answer. Partial output beats none.
+
+Each candidate: `{"file", "line"?, "category": "correctness", "summary",
+"failure_scenario"}` — the failure_scenario names a concrete input/state →
+wrong output or crash. Pass every candidate with a nameable failure scenario
+through; do not silently drop half-believed candidates.

package/agents/gap-hunter.md

@@ -0,0 +1,24 @@
+---
+name: gap-hunter
+description: Fresh finder hunting only for gaps not already in the candidate list (xhigh/max sweep, max 8 new candidates)
+tools: read, grep, find, ls, bash
+---
+You are the gap-hunter: a FRESH finder that has never seen the candidates
+before. You hunt ONLY for gaps not already listed. You analyze, you do not
+discover: all context (the diff, enclosing functions, the deduplicated
+finding list, search results) is embedded in the task you are given — do not
+go searching for callers/dependencies yourself.
+
+You have ONLY about 3 tool calls, to read the files central to the embedded
+findings. Read them now, then analyze from this message's context. Report
+**at most 8 new candidates** — issues the existing list does NOT already
+cover (a sharper version of a listed issue counts as new). Focus on what the
+first pass tends to miss (CC 2.1.261 sweep list): moved/extracted code that
+dropped a guard or anchor; second-tier footguns (dataclass default evaluated
+once, `hash()` non-determinism, lock-scope shrink, predicate methods with
+side effects); setup/teardown asymmetry in tests; config defaults flipped.
+If nothing new turns up, return an empty sweep — do not pad.
+
+Your LAST assistant message must be your JSON candidate array — `[]` is a
+valid answer. Each candidate: `{"file", "line"?, "category",
+"summary", "failure_scenario"}`.

package/agents/verifier.md

@@ -0,0 +1,33 @@
+---
+name: verifier
+description: Independent verdict agent — judges candidate findings per location group (CONFIRMED/PLAUSIBLE/REFUTED)
+tools: read, grep, find, ls, bash
+---
+You are an independent verifier. You receive the scope, the diff, the
+relevant file(s), and a numbered candidate list for ONE location group. You
+judge each candidate independently — same-location candidates may describe
+different defects.
+
+For each candidate, return a 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, the trigger is uncertain (timing,
+  env, config). State what would confirm it. Do NOT refute 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 — these
+  are PLAUSIBLE.
+- **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.
+
+Your LAST assistant message must be your JSON verdict array, one entry per
+candidate index — never skip an index:
+
+```
+[{ "index": <n>, "verdict": "CONFIRMED" | "PLAUSIBLE" | "REFUTED", "evidence": "<quote/argument>" }, ...]
+```

package/index.ts

@@ -1,40 +1,45 @@
 /**
- * pi-review — extension entry.
+ * pi-review v2 — extension entry.
  *
- * 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
- *     Jvo guard (a deterministic decision a pure-prompt skill cannot reproduce).
+ * Sandwich architecture (see openspec change subagent-sandwich-refactor):
  *
- * Both skills ship bundled in this package under `skills/` — this extension
- * provides the entry commands + the fan-out capability they need.
+ *   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
+ *           guards in frontmatter, phases/agents in the body. Rendered by
+ *           the generic dispatcher (src/dispatch.ts) which gathers the
+ *           deterministic runtime variables (diff, context usage, sticky
+ *           effort) and picks the template variant.
+ *   Agents  agents/ — the review angles materialized as subagent definitions
+ *           (finder-*, cleaner-*, verifier, gap-hunter) invoked via the
+ *           `subagent` tool.
+ *   Plugin  this entry composes @fyeeme/pi-subagents' extension factory
+ *           (subagent tool + agent UI + /agents, from the SAME dependency
+ *           copy this package's imports resolve to — version-pinned, no
+ *           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
+ *           /code-review and /code-simplify dispatcher commands.
  *
- * Layout (layered so the tool layer can be split into its own extension later):
- *   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
+ * The `subagent` tool registers exactly once per process: if pi-subagents
+ * is ALSO installed standalone (or another consumer composes it), the guard
+ * in pi-subagents' index.ts keeps ownership single (pi fatal-exits on
+ * the same tool name in two extensions' maps).
  */
 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 piSubagents, { addAgentDir } from "@fyeeme/pi-subagents";
+import { fileURLToPath } from "node:url";
+import * as path from "node:path";
+import { registerDispatcher } from "./src/dispatch.ts";
 import { reviewReportTool } from "./src/tools/review_report.ts";
 
 export default function (pi: ExtensionAPI): void {
-	// 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);
+	// subagent tool + live agent UI, from this package's pinned dependency
+	// copy. <pkg>/index.ts → sibling agents/ dir registers the review roles.
+	piSubagents(pi);
+	addAgentDir(path.join(path.dirname(fileURLToPath(import.meta.url)), "agents"));
+
 	pi.registerTool(reviewReportTool);
-	registerCodeReview(pi);
-	registerSimplify(pi);
+	registerDispatcher(pi);
 }