@unifan/pi-unifan-zh 1.0.0

package/extensions/review/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.

package/extensions/review/src/cli-args.ts

@@ -0,0 +1,105 @@
+/**
+ * Parse `/review` command arguments.
+ *
+ * Surface is intentionally minimal:
+ *   - `--lite`      fast single-agent review (no fan-out, no gate)
+ *   - `--no-spawn`  hidden dry-run (prints the resolved plan, no subprocess)
+ *   - trailing freeform text → user review request (focus / requirements /
+ *     PR url / context), injected into reviewers and gate via target.userContext
+ *     (see src/prep.ts and src/git-input.ts)
+ *
+ * Removed flags (--threshold / --reviewer / --score-per-issue / --diff) are
+ * accepted-but-ignored for graceful degradation of old invocations: a valued
+ * legacy flag also consumes its next token so its value does not leak into
+ * `input`. Those capabilities now live in config.json (`/review-config`).
+ * `--gate-model <id>` remains an active per-run override.
+ */
+
+export interface ParsedReviewArgs {
+	/** Freeform user request: review focus, PR url, or context. */
+	input?: string;
+	/** Dry-run: print resolved plan without spawning. */
+	noSpawn: boolean;
+	/** Single-agent fast mode: one reviewer, no gate. */
+	lite: boolean;
+	/** Override the gate model for this run (otherwise config.gate.model). */
+	gateModel?: string;
+}
+
+/** Removed valued flags — silently skip flag + value to keep input clean. */
+const LEGACY_VALUED_FLAGS = new Set([
+	"--threshold",
+	"--reviewer",
+	"--score-per-issue",
+	"--diff",
+]);
+
+export function parseReviewArgs(raw: string): ParsedReviewArgs {
+	const tokens = tokenize(raw);
+	const result: ParsedReviewArgs = { noSpawn: false, lite: false };
+	const inputParts: string[] = [];
+
+	for (let i = 0; i < tokens.length; i++) {
+		const t = tokens[i];
+		if (LEGACY_VALUED_FLAGS.has(t)) {
+			i++; // consume the value too
+			continue;
+		}
+		if (t === "--no-spawn") {
+			result.noSpawn = true;
+			continue;
+		}
+		if (t === "--lite") {
+			result.lite = true;
+			continue;
+		}
+		if (t === "--gate-model") {
+			const id = tokens[++i];
+			if (id) result.gateModel = id;
+			continue;
+		}
+		if (t.startsWith("-")) {
+			continue; // ignore other legacy / unknown flags
+		}
+		inputParts.push(t);
+	}
+
+	const input = inputParts.join(" ").trim();
+	if (input.length > 0) {
+		result.input = input;
+	}
+
+	return result;
+}
+
+/** Split on whitespace preserving quoted segments. */
+function tokenize(raw: string): string[] {
+	const out: string[] = [];
+	let cur = "";
+	let quote: "'" | '"' | null = null;
+	for (let i = 0; i < raw.length; i++) {
+		const c = raw[i];
+		if (quote) {
+			if (c === quote) {
+				quote = null;
+			} else {
+				cur += c;
+			}
+			continue;
+		}
+		if (c === "'" || c === '"') {
+			quote = c;
+			continue;
+		}
+		if (/\s/.test(c)) {
+			if (cur.length > 0) {
+				out.push(cur);
+				cur = "";
+			}
+			continue;
+		}
+		cur += c;
+	}
+	if (cur.length > 0) out.push(cur);
+	return out;
+}