@unifan/pi-review-zh 1.0.0

package/reference/claude-code-review.md

@@ -0,0 +1,133 @@
+# Claude Code Review — reference
+
+> **Source of truth:** `anthropics/claude-plugins-official` → `plugins/code-review/commands/code-review.md`  
+> **Secondary (may be stale):** `plugins/code-review/README.md` — describes 4 agents and “2× CLAUDE.md compliance”; the command file is authoritative and lists **5 distinct content agents**.
+
+Last verified: 2026-07-19.
+
+## Product intent
+
+Automated PR review: multiple independent agents audit the same change from different angles, then **confidence scoring** filters false positives so only high-signal issues are posted.
+
+- **Trigger:** `/code-review` (GitHub PR context, uses `gh`)
+- **Output:** PR comment with issues ≥ threshold (default **80/100**), or no comment if none qualify
+- **Not in scope:** auto-fix, harness gating merges, worktree isolation
+
+## Pipeline (ordered phases)
+
+Claude is **not** “spawn N reviewers and done”. It is a **sequential pipeline** with one parallel batch in the middle.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│ Phase 1 — Eligibility (Haiku)                                   │
+│ Skip if: closed, draft, trivial/automated, already reviewed     │
+│ → STOP if ineligible                                            │
+└────────────────────────────┬────────────────────────────────────┘
+                             ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ Phase 2 — Prep (Haiku, sequential)                              │
+│ 2a. List paths to relevant CLAUDE.md files (not full contents)  │
+│ 2b. Summarize PR / change                                       │
+└────────────────────────────┬────────────────────────────────────┘
+                             ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ Phase 3 — Content review (5× Sonnet, PARALLEL)                  │
+│ Each returns issues + reason flagged (compliance, bug, history…)  │
+└────────────────────────────┬────────────────────────────────────┘
+                             ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ Phase 4 — Confidence scoring (Haiku, PARALLEL per issue)        │
+│ One scorer agent per issue from Phase 3                         │
+│ Rubric: 0 / 25 / 50 / 75 / 100 (verbatim in command)            │
+└────────────────────────────┬────────────────────────────────────┘
+                             ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ Phase 5 — Filter                                                │
+│ Drop issues with score < 80 (configurable in command)           │
+│ → STOP if no issues remain (no comment posted)                  │
+└────────────────────────────┬────────────────────────────────────┘
+                             ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ Phase 6 — Re-eligibility (Haiku)                                │
+│ Repeat Phase 1 checks before posting                            │
+└────────────────────────────┬────────────────────────────────────┘
+                             ▼
+┌─────────────────────────────────────────────────────────────────┐
+│ Phase 7 — Output (`gh pr comment`)                              │
+│ Brief markdown; link file:line with full SHA                    │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Phase 3 — five content agents (command file)
+
+| # | Task | Focus |
+|---|------|--------|
+| 1 | CLAUDE.md compliance | Rules in CLAUDE.md; not every writing-time instruction applies at review time |
+| 2 | Bug detector | Shallow scan of **diff only**; large bugs; ignore nitpicks and likely FPs |
+| 3 | History | `git blame` + history on modified code; bugs in light of historical context |
+| 4 | Previous PRs | PRs that touched same files; comments that may apply to current PR |
+| 5 | Code comments | Inline comments in modified files; change must comply with comment guidance |
+
+Agents run **in parallel** after prep. They do **not** score their own issues for final output.
+
+## Phase 4 — confidence rubric (0–100)
+
+Given verbatim to each scorer (summarized):
+
+| Score | Meaning |
+|-------|---------|
+| **0** | False positive; does not survive scrutiny; or pre-existing |
+| **25** | Might be real; cannot verify; stylistic without explicit CLAUDE.md callout |
+| **50** | Real but minor / nitpick / rare in practice |
+| **75** | Verified likely real and important; or explicitly in CLAUDE.md |
+| **100** | Certain; will happen in practice; direct evidence |
+
+**CLAUDE.md issues:** scorer must verify the guideline **explicitly** mentions the issue.
+
+**Default threshold:** 80 — issues below are dropped.
+
+## Documented false positives (Phases 3–4)
+
+Scorers are instructed to down-rank:
+
+- Pre-existing issues not introduced in the PR
+- Things that look like bugs but are not
+- Pedantic nitpicks a senior engineer would skip
+- Linter / typechecker / formatter / import / test failures (CI handles)
+- General quality (tests, docs, generic security) **unless** CLAUDE.md requires it
+- Issues silenced in code (e.g. lint-ignore)
+- Intentional functional changes related to the PR scope
+- Real issues on lines the author did not modify
+
+**Explicit non-goals:** do not build or typecheck; do not use web fetch for GitHub (use `gh`).
+
+## README vs command discrepancies
+
+| Topic | README | Command (`code-review.md`) |
+|-------|--------|----------------------------|
+| Content agent count | 4 (2× compliance + bug + history) | **5** distinct roles |
+| Agent #2 | Second compliance | **Bug detector** |
+| Agents #4–5 | Not listed | Previous PRs + code comments |
+| Scoring | “Nx confidence scorers” | One Haiku per issue, parallel |
+
+**For pi-review alignment, follow the command file.**
+
+## Architecture notes (from README technical section)
+
+- Compliance redundancy in README (“2×”) is **not** what the current command specifies.
+- Scoring is **per issue**, not one aggregating judge.
+- GitHub integration: `gh pr view`, `gh pr diff`, blame/history, post comment.
+
+## Implications for pi-review
+
+| Claude phase | pi-review adaptation (v0.4) |
+|--------------|-------------------------|
+| 1 Eligibility | PR ref / `--diff` / git repo; optional trivial probe for local-git only |
+| 2 Prep | Rule-file paths + lightweight `gh pr view` / hint metadata (no full diff) |
+| 3 Content (5) | Bundled reviewers **obtain the change themselves** (gh/git/read playbook) |
+| 4 Scoring | Gate + optional per-issue scorers on reviewer evidence (no full diff embed) |
+| 5 Filter | Code-side threshold (map 80/100 → 8/10) |
+| 6 Re-eligibility | Target still present before render |
+| 7 Output | TUI markdown + `appendEntry`; no `gh pr comment` yet |
+
+**v0.4 design note:** Claude `/code-review` is an instruction document for the main agent. pi-review keeps parallel spawn + structured_output + gate enforce in the plugin, but must not hard-fail on `gh pr diff` — oversized PRs are handled inside reviewer tool loops.

package/reference/cursor-review-skills.md

@@ -0,0 +1,72 @@
+# Cursor Bugbot & Security Review — reference
+
+> **Source:** Cursor built-in skills `review-bugbot`, `review-security` (subagent invocation patterns).
+
+Last verified: 2026-07-19.
+
+## Product intent (Cursor)
+
+**Single-purpose review skills** — user manually invokes `/review-bugbot` or `/review-security`. Each launches **one** specialized subagent. There is **no** multi-phase pipeline, no gate, no per-issue confidence loop.
+
+Cursor’s general `/review` skill routes to these specialists; they are **not** a full clone of Claude code-review.
+
+## Invocation contract
+
+Both skills use the same prompt shape:
+
+```text
+Full Repository Path: <absolute path>
+Diff: <"branch changes" | "uncommitted changes">
+Base Branch: <optional; only when comparing against a known non-default base>
+Custom Instructions: <optional>
+```
+
+| `Diff` value | Meaning |
+|--------------|---------|
+| `branch changes` (default) | Merge-base vs default branch; includes committed + staged + unstaged |
+| `uncommitted changes` | Working tree only |
+
+Subagent computes diff internally — caller should **not** pre-compute diff.
+
+**PR / branch special case:** checkout target branch before launch; stash only with user confirmation.
+
+## Subagent types
+
+| Skill | `subagent_type` | Purpose |
+|-------|-----------------|---------|
+| `/review-bugbot` | `bugbot` | Correctness / logic bugs in the change |
+| `/review-security` | `security-review` | Security issues in the change |
+
+## Output discipline
+
+After subagent completes, parent summarizes:
+
+- Empty diff → one-line “no diff”
+- No issues → one-line status
+- Issues → markdown table: **Severity | Location (file:line) | Finding**, sorted by severity
+
+**Do not** auto-fix or re-run unless user asks.
+
+## Retry policy
+
+- Wrong invocation shape → fix and retry once
+- Other failures → retry once with same prompt
+- Still failing → stop, report error (no infinite retry)
+
+## What to borrow for pi-review
+
+| Borrow | Do not borrow |
+|--------|----------------|
+| Bug-focused diff scope (no whole-repo nitpicks) | Single-subagent-only UX (we use parallel reviewers) |
+| Security category checklist mindset | Letting subagent compute diff (we resolve diff in parent) |
+| Compact table-friendly findings | Separate `/review-bugbot` commands (use `/review --reviewer`) |
+| “Only changed lines” discipline | Cursor’s Task/subagent harness |
+
+## Mapping to pi-review agents
+
+| Cursor | pi-review agent (planned) | Notes |
+|--------|---------------------------|-------|
+| `bugbot` | `bugbot` (rename from `bug-detector`) | Align prompt with Cursor output discipline |
+| `security-review` | `security-review` (new) | `category: security` in schema already exists |
+
+These are **Phase 3 content reviewers** in our pipeline, not replacements for eligibility, prep, or gate.

package/reference/pi-review-roadmap.md

@@ -0,0 +1,183 @@
+# pi-review — design & version roadmap
+
+> **Positioning:** Pure **skills** extension — user manually runs `/review`. No harness, no auto-fix, no GitHub bot in v1.  
+> **Pattern:** Claude code-review **pipeline shape** + Cursor **bug/security prompt discipline**.  
+> **See also:** [claude-code-review.md](./claude-code-review.md), [cursor-review-skills.md](./cursor-review-skills.md)
+
+Last updated: 2026-07-19.
+
+## Design principles
+
+1. **Pipeline, not a bag of agents** — eligibility → prep → parallel content → score/filter → output.
+2. **High signal** — default threshold aligned with Claude’s 80/100 (our **8/10**).
+3. **Local-first** — `git diff` / diff file; no `gh` required in v1.
+4. **Manual invocation only** — no `registerTool`, no CI hooks in v1.
+5. **Gate = Phase 4+5 compression** — one cheap spawn for dedupe + re-score + verdict; optional per-issue scorers in a later version.
+
+## Phase mapping (Claude → pi-review)
+
+| Claude phase | pi-review module (planned) | v1 behavior |
+|--------------|----------------------------|-------------|
+| **0 Eligibility** | `src/eligibility.ts` | Empty diff, non-git, optional trivial skip |
+| **1 Prep** | `src/prep.ts` | Rule paths (`AGENTS.md`, `CLAUDE.md`, `.pi/`) + diff summary injected into reviewer task |
+| **2 Content (×5)** | `src/review.ts` + `agents/*.md` | Parallel subagents; bundled prompts as `--system-prompt` |
+| **3 Score + filter** | `src/gate.ts` + `prompts/gate.md` | Dedupe, apply Claude rubric (adapted to 1–10), threshold, verdict |
+| **4 Re-check** | `index.ts` | Optional: re-verify diff non-empty before render |
+| **5 Output** | `src/report.ts` | `sendMessage` + `appendEntry("pi-review", …)` |
+
+```text
+/review
+  │
+  ├─ Phase 0  eligibility()          → notify + exit if skip
+  ├─ Phase 1  resolveDiff()            → git-input / path / @file
+  ├─ Phase 1  prepareContext()         → rule paths + summary (sync or 1 cheap spawn)
+  ├─ Phase 2  runReviewers()           → 5 parallel (cap 4 concurrency → 2 waves)
+  ├─ Phase 3  runGate()                → unless --no-gate
+  └─ Phase 4  buildReport + render     → TUI markdown
+```
+
+## Default reviewer roster (v0.2 target)
+
+Aligned to Claude’s five content agents, adapted for local use:
+
+| ID | Claude agent | Status | Tools (default) |
+|----|--------------|--------|-----------------|
+| `claude-md-compliance` | #1 CLAUDE.md | exists | read, grep, find, ls |
+| `bugbot` | #2 Bug detector | rename `bug-detector` | read, grep, find |
+| `history-context` | #3 History | exists | read, bash |
+| `security-review` | *(pi addition)* | **new** | read, grep, find |
+| `code-comments` | #5 Code comments | **new** | read, grep |
+
+**Dropped / deferred**
+
+| ID | Reason |
+|----|--------|
+| `pr-context` (Claude #4) | Requires `gh` + PR metadata — **v1 out of scope** |
+| `conventions` | Overlaps compliance + Claude false-positive list; keep as **optional** `enabled: false` |
+
+**Concurrency:** hard cap 4 → five reviewers run as batch of 4 + batch of 1 (or user passes `--reviewer` subset).
+
+## Confidence scale
+
+| System | Scale | Default keep |
+|--------|-------|--------------|
+| Claude Phase 4 | 0–100 | ≥ 80 |
+| pi-review reviewer + gate | 1–10 | ≥ **8** (change default from 3) |
+
+Gate prompt must embed Claude’s rubric (translated to 1–10) for **re-scoring**, not only filtering reviewer self-reported confidence.
+
+## Known gaps (v0.1.0 codebase)
+
+| Gap | Blocks |
+|-----|--------|
+| Missing `index.ts` | Extension load |
+| `agents/*.md` not used as system prompt | Reviewer quality |
+| `PI_SUBAGENT_STRUCTURED_OUTPUT_*` not handled by stock `pi` | Subagent spawn |
+| No eligibility / prep phases | Claude alignment |
+| Default threshold 3 | Too noisy vs Claude |
+
+## Version plan
+
+### v0.1.0 — current (incomplete)
+
+**Shipped:** core libs, 4 agent templates, gate schema, tests (92).  
+**Not shipped:** `index.ts`, npm publish, end-to-end run.
+
+No further work on 0.1.0 except tagging reality in CHANGELOG if needed.
+
+---
+
+### v0.2.0 — “skills MVP” (target)
+
+**Goal:** User can `pi -e .` or install package and run `/review` on local diff with Claude-shaped pipeline.
+
+| Work item | Priority |
+|-----------|----------|
+| `index.ts` — `/review`, `/review-config`, `/review-agents` | P0 |
+| `src/structured-output-capture.ts` — minimal child extension OR document `-e` flag for structured output | P0 |
+| Wire `agents/<id>.md` + `prompts/gate.md` as system prompts | P0 |
+| `src/eligibility.ts` — empty diff, non-git, trivial diff heuristic | P0 |
+| `src/prep.ts` — rule file paths + diff summary in task preamble | P1 |
+| Rename `bug-detector` → `bugbot`; add `security-review.md`, `code-comments.md` | P1 |
+| Default threshold **8**; gate prompt Claude rubric | P1 |
+| `conventions` default `enabled: false` | P2 |
+| Update README + CHANGELOG | P1 |
+| `reference/` in package `files` | P1 |
+
+**Out of scope v0.2:** `gh`, per-issue scorers, `registerTool`, worktree, retry loop.
+
+**Implementation:** see [v0.2-plan.md](./v0.2-plan.md) for the full task list (54 tasks, 7 tracks).
+
+**Exit criteria**
+
+- [ ] `pi -e /path/to/pi-review` → `/review` on dirty repo produces report
+- [ ] Gate drops low-confidence issues; empty high-confidence → clear message
+- [ ] `bun test` + `bun run check` pass
+- [ ] npm publish `@georgedong32/pi-review@0.2.0`
+
+---
+
+### v0.3.0 — “quality & optional GH”
+
+| Work item | Notes |
+|-----------|-------|
+| Per-issue scorer mode (`--score-per-issue`) | True Claude Phase 4; higher cost |
+| `pr-context` reviewer (optional) | Behind `gh` detection + config flag |
+| Reviewer failure retry (1×) | Only on spawn/timeout errors |
+| `registerMessageRenderer` for collapsible report | TUI polish |
+| Eligibility: “already reviewed” via session `appendEntry` hash | Optional |
+
+---
+
+### v1.0.0 — stable API
+
+- Frozen config schema v1
+- Documented reviewer add/replace contract
+- Published pi gallery entry
+- No breaking changes without `schemaVersion` bump
+
+## File layout (target)
+
+```text
+index.ts                      Extension entry
+src/
+  eligibility.ts              Phase 0
+  prep.ts                     Phase 1
+  git-input.ts                Diff resolution (existing)
+  review.ts                   Phase 2 fan-out (existing)
+  gate.ts                     Phase 3 (existing)
+  report.ts                   Phase 5 output (existing)
+  structured-output-capture.ts  Child pi extension for spawn (new)
+agents/
+  claude-md-compliance.md
+  bugbot.md                     (was bug-detector)
+  history-context.md
+  security-review.md            (new)
+  code-comments.md              (new)
+  conventions.md                (optional, disabled)
+prompts/
+  gate.md
+reference/                      This folder
+```
+
+## Commands (unchanged UX)
+
+```text
+/review [path | @path] [--threshold N] [--reviewer id ...] [--no-gate] [--gate-model id] [--no-spawn]
+/review-config
+/review-agents
+```
+
+## Decision log
+
+| Date | Decision | Rationale |
+|------|----------|-----------|
+| 2026-07-19 | Pure skills, manual `/review` only | User intent; avoid harness scope |
+| 2026-07-19 | Follow Claude **pipeline**, not just parallel agents | User correction; command file is SoT |
+| 2026-07-19 | Keep `history-context` in default roster | Claude agent #3; not merged into bugbot |
+| 2026-07-19 | Add `security-review` (Cursor-inspired) | Orthogonal to bug + compliance |
+| 2026-07-19 | Gate compresses Phase 4+5 for v0.2 | Cost vs fidelity; document in reference |
+| 2026-07-19 | Skip `pr-context` until v0.3+ | Requires `gh`; local-first v1 |
+| 2026-07-19 | Default threshold 8/10 | Maps to Claude 80/100 |
+| 2026-07-26 | CLI collapsed to `--lite` dual-mode; per-issue scorer default off; gate default Haiku | Lighten the CLI surface + align with Claude code-review |
+| 2026-07-26 | Foreground directive mode via `sendUserMessage` (relies on pi-subagents); `--gate-model` restored; spawn path kept as fallback | Review visible in chat; gate model user-configurable |

package/reference/structured-output.md

@@ -0,0 +1,26 @@
+# Structured output capture (child extension)
+
+Child `pi` processes spawned by pi-review load `src/structured-output-capture.ts` via:
+
+```text
+pi --no-session --no-extensions --no-skills -e <path/to/structured-output-capture.ts> ...
+```
+
+## Environment variables
+
+| Variable | Purpose |
+|----------|---------|
+| `PI_SUBAGENT_STRUCTURED_OUTPUT_SCHEMA` | Path to JSON Schema file (written by parent; informs model via system prompt) |
+| `PI_SUBAGENT_STRUCTURED_OUTPUT_CAPTURE` | Path where child must write final JSON payload |
+
+## Tool contract
+
+The capture extension registers a single tool: `structured_output`.
+
+- Parameters: open object (`additionalProperties: true`) — parent validates with TypeBox after spawn.
+- `execute`: writes `JSON.stringify(params)` to capture path; returns `terminate: true`.
+- Parent passes `--tools structured_output` (reviewers also include read/grep/… as configured).
+
+## Parent validation
+
+`src/spawn.ts` reads the capture file and validates against `ReviewerOutputSchema` or `GateOutputSchema`.

package/reference/v0.2-plan.md

@@ -0,0 +1,268 @@
+# v0.2.0 implementation plan
+
+> **Goal:** Skills MVP — user runs `/review` locally and gets a Claude-shaped pipeline report.  
+> **Baseline:** v0.1.0 (core libs + tests; no `index.ts`, no E2E).  
+> **Design refs:** [pi-review-roadmap.md](./pi-review-roadmap.md), [claude-code-review.md](./claude-code-review.md)
+
+Target release: `@georgedong32/pi-review@0.2.0`
+
+---
+
+## Goals
+
+- [x] Extension loads via `pi -e .` and registers `/review`, `/review-config`, `/review-agents`
+- [x] `/review` runs full pipeline: **eligibility → prep → reviewers → gate → report**
+- [x] Five default content reviewers with bundled prompts wired as system prompts
+- [~] Subagent spawn + structured JSON capture works on real `pi` child processes (unit + args tests pass; live spawn E2E pending API key)
+- [x] Default confidence threshold **8/10** (Claude 80/100 equivalent)
+- [ ] Publish to npm
+
+## Non-goals (v0.2)
+
+- GitHub / `gh` integration (`pr-context` reviewer)
+- Per-issue Haiku scorers (`--score-per-issue`)
+- `registerTool` / agent auto-invoke
+- Worktree isolation, auto-fix, retry loops
+- Custom TUI message renderer (collapsible sections)
+
+---
+
+## Task list
+
+Status key: `[ ]` todo · `[~]` in progress · `[x]` done
+
+### Track A — Extension entry (P0)
+
+| ID | Task | Depends | Status |
+|----|------|---------|--------|
+| A1 | Create `index.ts` — default export `ExtensionAPI` factory | — | [x] |
+| A2 | Register `/review` command with arg string passthrough | A1 | [x] |
+| A3 | Register `/review-config` — ensure config dir, open editor, re-validate on save | A1 | [x] |
+| A4 | Register `/review-agents` — list reviewers with resolved model/thinking/tools | A1 | [x] |
+| A5 | Implement `src/cli-args.ts` — parse flags + path/`@file` from `/review` args | A1 | [x] |
+| A6 | Wire orchestration in `index.ts`: load config → eligibility → diff → prep → review → gate → output | A2, A5, B*, C*, D* | [x] |
+| A7 | Output: `renderReport` via `pi.sendMessage` (assistant-visible markdown) | A6 | [x] |
+| A8 | Output: `pi.appendEntry("pi-review", report)` machine-readable payload | A6 | [x] |
+| A9 | Long-run UX: `ctx.ui.setStatus("pi-review", …)` during spawn phases | A6 | [x] |
+| A10 | Add `index.ts` to `package.json` `files`; verify `tsc` includes it | A1 | [x] |
+
+**A3 notes:** Prefer `ctx.ui.editor()` with JSON text for in-TUI edit; fall back to `pi.exec($EDITOR, [configPath])` when `ctx.hasUI` and editor env set.
+
+**A5 flags to parse:**
+
+```text
+--threshold N
+--reviewer <id>       (repeatable)
+--no-gate
+--gate-model <id>
+--no-spawn
+[path | @path]
+```
+
+---
+
+### Track B — Structured output / spawn (P0)
+
+| ID | Task | Depends | Status |
+|----|------|---------|--------|
+| B1 | Add `src/structured-output-capture.ts` — minimal pi extension: register `structured_output` tool; read schema from env; write capture file; `terminate: true` | — | [x] |
+| B2 | Document env contract in `reference/structured-output.md` (or inline in spawn.ts header) | B1 | [x] |
+| B3 | Update `src/args.ts` — append `-e <capture-ext>` to child args (resolve path via `import.meta.url`) | B1 | [x] |
+| B4 | Verify child still uses `--no-session --no-extensions --no-skills` **except** capture extension | B3 | [x] |
+| B5 | Manual E2E: one reviewer spawn writes valid `output.json` | B3, C2 | [ ] |
+| B6 | Integration test with fake spawn (existing pattern) updated for `-e` arg | B3 | [x] |
+
+**B1 contract (unchanged env vars):**
+
+- `PI_SUBAGENT_STRUCTURED_OUTPUT_SCHEMA` → JSON Schema file path
+- `PI_SUBAGENT_STRUCTURED_OUTPUT_CAPTURE` → output JSON path
+
+---
+
+### Track C — Pipeline phases (P0–P1)
+
+| ID | Task | Depends | Status |
+|----|------|---------|--------|
+| C1 | Add `src/eligibility.ts` — `checkEligibility(input): { ok, reason? }` | — | [x] |
+| C2 | Eligibility rules: empty diff → skip; non-git without path → skip; optional trivial diff heuristic | C1 | [x] |
+| C3 | Add `tests/eligibility.test.ts` | C1 | [x] |
+| C4 | Add `src/prep.ts` — `prepareContext(cwd, diff): { rulePaths, summary }` | — | [x] |
+| C5 | Rule discovery: `AGENTS.md`, `CLAUDE.md`, `.pi/rules`, `.pi/conventions.md` (paths only, like Claude step 2) | C4 | [x] |
+| C6 | Diff summary: first N lines / hunk count / files touched (sync, no LLM required for v0.2) | C4 | [x] |
+| C7 | Inject prep block into reviewer task preamble in `review.ts` | C4, D6 | [x] |
+| C8 | Add `tests/prep.test.ts` | C4 | [x] |
+| C9 | Light re-check before render: diff still non-empty (Claude phase 6 lite) | C1, A6 | [x] |
+
+**Trivial diff heuristic (v0.2):** only lockfile / only formatting-only / &lt; 3 lines — configurable `skipTrivial: true` in config later; hardcode simple rules OK for v0.2.
+
+---
+
+### Track D — Reviewers & prompts (P1)
+
+| ID | Task | Depends | Status |
+|----|------|---------|--------|
+| D1 | Add `src/paths.ts` — `packageRoot()` via `import.meta.url` | — | [x] |
+| D2 | `resolveAgentPrompt(id)` → `agents/<id>.md` (strip YAML frontmatter body for system prompt) | D1 | [x] |
+| D3 | `resolveGatePrompt()` → `prompts/gate.md` | D1 | [x] |
+| D4 | Refactor `review.ts`: use bundled agent md as `--system-prompt`; task = prep + diff | D2, C7 | [x] |
+| D5 | Refactor `gate.ts`: use `prompts/gate.md` as gate system prompt | D3 | [x] |
+| D6 | Rename `agents/bug-detector.md` → `agents/bugbot.md`; update id in config defaults | — | [x] |
+| D7 | Tighten `bugbot.md` prompt per [cursor-review-skills.md](./cursor-review-skills.md) | D6 | [x] |
+| D8 | Add `agents/security-review.md` | — | [x] |
+| D9 | Add `agents/code-comments.md` (Claude agent #5) | — | [x] |
+| D10 | Update `src/config.ts` `DEFAULT_CONFIG.reviewers` roster (5 enabled, conventions disabled) | D6–D9 | [x] |
+| D11 | Update `prompts/gate.md` — embed Claude 0–100 rubric mapped to 1–10; re-score not just filter | D5 | [x] |
+| D12 | Change default `gate.threshold` from 3 → **8** in config + README | D10 | [x] |
+| D13 | Keep `agents/conventions.md`; `enabled: false` in defaults | D10 | [x] |
+
+**Default enabled reviewers (v0.2):**
+
+1. `claude-md-compliance`
+2. `bugbot`
+3. `history-context`
+4. `security-review`
+5. `code-comments`
+
+---
+
+### Track E — Types, schema, report (P1)
+
+| ID | Task | Depends | Status |
+|----|------|---------|--------|
+| E1 | Extend `ResolvedInput` / report if needed for prep metadata (`rulePaths`, `summary`) | C4 | [x] |
+| E2 | `buildReport` — handle eligibility skip / no high-confidence issues messaging | A6 | [x] |
+| E3 | `renderReport` — “No high-confidence issues” path (Claude: no comment posted) | E2 | [x] |
+| E4 | Update `tests/report.test.ts` for new messages | E3 | [x] |
+| E5 | Update `tests/config.test.ts` for new defaults + bugbot id | D10 | [x] |
+
+---
+
+### Track F — Tests & docs (P1)
+
+| ID | Task | Depends | Status |
+|----|------|---------|--------|
+| F1 | Add `tests/cli-args.test.ts` | A5 | [x] |
+| F2 | Update `tests/args.test.ts` if child argv shape changes (`-e`) | B3 | [x] |
+| F3 | Update `tests/review.test.ts` for bundled prompt resolution (mock fs or inject paths) | D4 | [x] |
+| F4 | Update README — pipeline diagram, 5 reviewers, threshold 8, reference links | * | [x] |
+| F5 | CHANGELOG `[0.2.0]` section | * | [x] |
+| F6 | Bump `package.json` version → `0.2.0` | * | [x] |
+| F7 | `bun test` + `bun run check` green | * | [x] |
+
+---
+
+### Track G — Release (P1)
+
+| ID | Task | Depends | Status |
+|----|------|---------|--------|
+| G1 | Manual smoke: `pi -e .` → `/review` on dirty repo | A6, B5 | [ ] |
+| G2 | Manual smoke: `/review --no-gate`, `--reviewer bugbot`, `--no-spawn` | A5, A6 | [ ] |
+| G3 | Manual smoke: `/review-config` round-trip | A3 | [ ] |
+| G4 | `npm publish` (user-triggered) | G1–G3, F7 | [ ] |
+
+---
+
+## Suggested implementation order
+
+```text
+Week 1 — unblock E2E
+  D1 → B1 → B3 → D2/D3 → D4/D5 → A1 → A5 → C1/C4 → A6 (no-gate path first)
+
+Week 2 — full pipeline
+  D6–D13 → C7 → D11/D12 → A7/A8/A9 → A3/A4 → tests (F*) → docs (F4/F5)
+
+Week 3 — polish & release
+  C2/C9 trivial + re-check → G* smoke → version bump → publish
+```
+
+**Critical path:** `B1 → B3 → D4 → A6 → G1`
+
+---
+
+## Acceptance criteria (release gate)
+
+1. **Load:** `pi -e /path/to/pi-review` lists `/review` in commands.
+2. **Happy path:** Dirty git repo → `/review` → markdown report with verdict + per-reviewer sections + gate section.
+3. **Empty:** Clean repo, no commits ahead → eligibility message, no spawn storm.
+4. **Filter:** Reviewer returns low-confidence issue → gate drops it; report says no high-confidence issues if all dropped.
+5. **Flags:** `--no-gate` shows raw reviewer JSON sections; `--no-spawn` prints resolved plan; `--reviewer bugbot` runs one agent.
+6. **Config:** `/review-config` edit + save → `/review-agents` reflects changes.
+7. **CI:** `bun test` (≥ current count, new tests for eligibility/cli-args/prep) + `tsc --noEmit` pass.
+
+---
+
+## File manifest (expected diff)
+
+### New files
+
+```text
+index.ts
+src/cli-args.ts
+src/eligibility.ts
+src/prep.ts
+src/paths.ts
+src/structured-output-capture.ts
+agents/bugbot.md              (from bug-detector)
+agents/security-review.md
+agents/code-comments.md
+tests/cli-args.test.ts
+tests/eligibility.test.ts
+tests/prep.test.ts
+reference/v0.2-plan.md        (this file)
+```
+
+### Modified files
+
+```text
+src/review.ts
+src/gate.ts
+src/args.ts
+src/config.ts
+src/report.ts
+src/types.ts                  (if prep metadata)
+prompts/gate.md
+README.md
+CHANGELOG.md
+package.json
+reference/README.md
+tests/args.test.ts
+tests/config.test.ts
+tests/report.test.ts
+tests/review.test.ts
+```
+
+### Removed / renamed
+
+```text
+agents/bug-detector.md  →  agents/bugbot.md
+```
+
+---
+
+## Risk register
+
+| Risk | Mitigation |
+|------|------------|
+| Stock `pi` rejects `-e` with `--no-extensions` | B4: confirm CLI allows single extension override; else use minimal inline prompt + `--tools` only |
+| Long diff exceeds argv limits | Pass `@file` temp path for task text (already noted in args.ts) |
+| 5 reviewers × spawn cost | Document expected latency; `--reviewer` subset; concurrency cap 4 |
+| Gate re-score drift vs per-issue scorers | Document in reference; v0.3 adds `--score-per-issue` |
+
+---
+
+## Progress summary
+
+| Track | Tasks | Done |
+|-------|-------|------|
+| A Extension | 10 | 10 |
+| B Spawn | 6 | 5 |
+| C Pipeline | 9 | 9 |
+| D Reviewers | 13 | 13 |
+| E Types/report | 5 | 5 |
+| F Tests/docs | 7 | 7 |
+| G Release | 4 | 0 |
+| **Total** | **54** | **49** |
+
+**Remaining:** B5 live spawn E2E; G1–G3 manual `pi` smoke; G4 `npm publish` (user-triggered).
+
+Update the **Progress summary** table as tasks complete.