@mrclrchtr/supi-review 2.8.0 → 3.1.0

package/README.md

@@ -1,14 +1,6 @@
-<div align="center">
-  <a href="https://github.com/mrclrchtr/supi/tree/main/packages/supi-review">
-    <picture>
-      <img src="https://raw.githubusercontent.com/mrclrchtr/supi/main/packages/supi-review/assets/logo.png" alt="SuPi" width="50%">
-    </picture>
-  </a>
-</div>
-
 # @mrclrchtr/supi-review
 
-Adds human-driven and agent-driven Session-Aware Review workflows to the [pi coding agent](https://github.com/earendil-works/pi).
+Runs caller-defined, read-only code review tasks in managed Pi child sessions.
 
 ## Install
 
@@ -16,198 +8,97 @@ Adds human-driven and agent-driven Session-Aware Review workflows to the [pi cod
 pi install npm:@mrclrchtr/supi-review
 ```
 
-This is a **beta** package. Install individually.
-
-For local development:
-
-```bash
-pi install ./packages/supi-review
-```
-
-## What you get
-
-After install, pi gets one human-driven command and two agent-facing tools:
-
-- `/supi-review` — launch a guided review flow over a concrete git snapshot
-- `supi_review_prepare` — synthesize a versioned brief and return a session-scoped `planId`
-- `supi_review_run` — accept the main agent's structured brief critique, freshness-check the plan, and run focused reviewers concurrently
-
-The run tool is initially inactive and is dynamically enabled after `supi_review_prepare` returns a plan. This keeps the initial agent-facing prompt surface small.
-
-The reviewer runs in managed child agent sessions:
-
-- a **brief synthesizer** creates a structured review brief from the active session branch
-- a **read-only reviewer** inspects the selected snapshot (without receiving bulk inline diffs) and submits structured review items
-
-![Review target selection](https://raw.githubusercontent.com/mrclrchtr/supi/main/screenshots/supi-review-1.png)
-
-![Review brief preview](https://raw.githubusercontent.com/mrclrchtr/supi/main/screenshots/supi-review-2.png)
-
-![Review result](https://raw.githubusercontent.com/mrclrchtr/supi/main/screenshots/supi-review-3.png)
-
-![Review progress](https://raw.githubusercontent.com/mrclrchtr/supi/main/screenshots/supi-review-4.png)
-
-## Review flow
-
-`/supi-review` walks you through:
-
-1. choose a review target
-2. choose the reviewer model
-3. optionally add a short note
-4. resolve the snapshot
-5. synthesize a review brief from the current session history
-6. preview the synthesized brief + compact prompt preview, then press `v` for an in-app inspector (Overview first, Raw Prompt via `tab`, export via `e`)
-7. the reviewer fetches per-file diffs on demand via snapshot-aware tools; live progress widget shows activity
-8. normalize the submitted review items into a host-derived verdict + structured result
-9. if review items exist, hand off to the main agent so it can ask what to do next with fixed options (`Fix all`, `Fix selected`, `Verify findings`, `Skip`)
-
-## Agent-driven review flow
-
-The agent-facing path deliberately separates preparation from execution:
-
-1. `supi_review_prepare` resolves the target, serializes the active session context, and synthesizes a generated brief.
-2. The main agent compares that brief with the user request, session evidence, and snapshot.
-3. The main agent calls `supi_review_run` with:
-   - the prepared `planId`
-   - an `accept` or `revise` critique
-   - evidence-backed critique findings
-   - at least one evidence-backed finding and a full `revisedBrief` when revision is required
-   - one to four independent reviewer assignments
-4. The host atomically consumes the plan, checks snapshot freshness, and runs reviewer child sessions concurrently.
-5. The tool returns each normalized review result plus a retained brief evaluation artifact.
-
-The evaluation artifact keeps the generated brief, main-agent critique, effective brief, synthesis prompt version, model id, and snapshot fingerprint separate. This makes brief-synthesis prompt regressions inspectable instead of hiding main-agent repairs. The full artifact is stored in tool-result `details`; a summary is also recorded as a `supi-review/brief-critique` SuPi Debug event when debug capture is enabled.
+This is a beta package with intentionally unstable interfaces.
 
-Prepared plans are session-scoped. File or git changes before or during review invalidate the run, so `supi_review_run` should not share a tool batch with mutating tools.
+## Surfaces
 
-## Review targets
+- `/supi-review` — interactive Direct or Planner-assisted review
+- `supi_review_prepare` — optional one-shot preparation with `planning: "none" | "suggest"`
+- `supi_review_run` — universal Direct or Prepared Review execution
 
-Current targets:
+Preparation is optional. Skills and agents that already know how to review should use Direct Review.
 
-- working tree
-- branch diff vs a selected local base branch (`merge-base..HEAD`, excluding dirty worktree changes)
-- one commit (recent-commit picker in the command; hexadecimal object id in the agent tool)
+## Direct Review
 
-Agent-provided branch targets must name an existing local branch. Commit targets must be unique 7–64 character hexadecimal commit-object ids: object-only disambiguation rejects ambiguous prefixes, non-commit objects, and hexadecimal branch/tag fallback. Git revision arguments are option-hardened before execution.
-
-## Session-aware brief synthesis
+```json
+{
+  "mode": "direct",
+  "target": {
+    "kind": "comparison",
+    "baseCommit": "<full commit object id>"
+  },
+  "review": {
+    "sharedContext": "The change implements issue #123.",
+    "tasks": [
+      {
+        "id": "standards",
+        "instructions": "Review against the repository standards."
+      },
+      {
+        "id": "spec",
+        "instructions": "Review against issue #123 and cite unmet requirements."
+      }
+    ]
+  }
+}
+```
 
-The generated review prompt is **not** just a static diff wrapper.
+All tasks use one reviewer model and run concurrently. A run accepts one to four tasks. Direct and Prepared adapters use the same canonical packet compiler; every task result includes the SHA-256 of the exact packet bytes.
 
-Before the actual review starts, the package:
+## Prepared Review
 
-- resolves the **active session branch into the current LLM-visible context**
-- **serializes** that resolved context into a compaction-style transcript
-- feeds the serialized transcript (plus snapshot + optional note) to a dedicated brief synthesizer
-- synthesizes a structured brief with:
-  - summary
-  - intended outcome
-  - constraints to preserve
-  - focus areas
-  - risky files
-  - unresolved questions
-  - `reviewInstructionBlockIds` selected from a fixed host-owned catalog
+```json
+{
+  "target": { "kind": "working-tree" },
+  "planning": "suggest"
+}
+```
 
-The synthesizer also receives a bounded diff excerpt from the snapshot so it can reason about actual code changes, not just filenames.
+Preparation returns a session-scoped, one-shot `planId` and optional Planner Draft. Execute it with an explicit decision:
 
-That synthesized brief is then combined with the git snapshot into a compact reviewer prompt. The host owns a fixed catalog of review instruction blocks, and the brief selects zero or more block IDs from that catalog when extra review guidance is warranted. The resulting prompt contains the brief, file manifest, per-file overview, and any brief-selected **mandatory review instructions**, but no large inline diffs. Instead, the reviewer session gets snapshot-aware tools (`read_snapshot_diff`, `read_snapshot_file`) to fetch exact per-file diffs and before/after file contents on demand.
+```json
+{
+  "mode": "prepared",
+  "planId": "review-plan-...",
+  "decision": { "kind": "accept-draft" }
+}
+```
 
-The session-transcript approach mirrors how Pi summarizes context for compaction: the entire resolved conversation is rendered in a readable label format and sent to the model as a whole, rather than relying on heuristic excerpt ranking.
+Use `use-review` with a complete replacement review when the draft needs editing.
 
-## Review-plan inspector
+## Targets
 
-Before the reviewer runs, the plan preview stays inside Pi:
+- `working-tree` — net `HEAD` to current filesystem, plus non-ignored untracked files, computed through a temporary HEAD-seeded index rather than the caller's real index
+- `comparison` — merge base of a full `baseCommit` and captured `HEAD` to captured `HEAD`
+- `commit` — first parent (or empty tree) to a full commit object id
 
-- `v` opens an in-app inspector instead of spawning an external pager
-- the inspector opens in **Overview** mode first
-- `tab` toggles between **Overview** and **Raw Prompt**
-- `↑↓` or `j` / `k` scroll long content in the inspector
-- `q` or `esc` returns to the summary preview without canceling the review
-- `e` exports the raw prompt to a temp file as a debugging fallback
+Agent-facing commit values must be full hexadecimal object ids. The repository must remain stable from preparation or Direct invocation until reviewers finish; drift is not detected.
 
-The Overview mode uses the same structured packet data that feeds the reviewer prompt: mandatory review instructions, file overview rows, and truncated snapshot notes all come from shared packet derivation rather than re-parsing the raw prompt text.
+## Reviewer protocol
 
-## Model selection
+Callers own task methodology. The Review Engine owns:
 
-Every `/supi-review` command run asks you to choose the reviewer model.
+- target resolution
+- target-aware read-only tools
+- minimal finding-quality instructions
+- structured submission
+- child lifecycle handling
+- per-task verdict derivation
 
-- the picker only shows **scoped models** from Pi's `enabledModels` configuration
-- the current session model is preselected only when it is inside that scoped set
-- the selected model is used for both brief synthesis and the final review
-- the command selection is not persisted
+Reviewers receive no shell, arbitrary extension tools, Pi context files, skills, or prompt templates. Discovered `SYSTEM.md` and `APPEND_SYSTEM.md` files are explicitly suppressed; only the package-owned reviewer protocol is appended to Pi's base system prompt. In-memory child settings disable compaction and retries so provider limits apply to the original packet. Inspection-tool and parent-visible outputs are paged/bounded; canonical packet bytes are never truncated.
 
-Agent-driven tool runs use the **Review → Agent tool model** setting in `/supi-settings` when `@mrclrchtr/supi-settings` is installed:
+## Result
 
-- `current session model` is the default and preserves the active-session behavior
-- an explicit choice stores a canonical `provider/model-id` from Pi's scoped `enabledModels` set
-- the configured model is used for brief synthesis and every focused reviewer
-- project settings override global settings through the normal SuPi settings scopes
-- a configured model that is no longer scoped or available causes preparation to fail with a corrective error
+Each successful task returns a summary and ordered findings. Findings contain:
 
-The resolved model is retained in the prepared plan, so changing the setting or active session model between tool calls cannot silently alter the run.
+- `blocksAcceptance`
+- `impact`: `low | medium | high`
+- `effort`: `small | medium | large`
+- `confidence`: `0..1`
+- optional target-relative location
 
-For a standalone `supi-review` install without `supi-settings`, set the same value directly in the global `~/.pi/agent/supi/config.json` or project `.pi/supi/config.json` file:
+The Review Engine derives `pass` or `issues` per task and never aggregates or reranks tasks. Batch details also record `mode`, caller/planner provenance, and each task's packet hash.
 
-```json
-{
-  "review": {
-    "agentModel": "openai/gpt-5"
-  }
-}
-```
+## Models
 
-Use `"current"` instead of a canonical model id to follow the active session model.
-
-## Result shape
-
-A successful review includes:
-
-- a host-derived binary verdict:
-  - `PATCH IS CORRECT`
-  - `PATCH HAS ISSUES`
-- overall explanation
-- overall confidence score
-- normalized action/category summary counts
-- structured review items with:
-  - title
-  - body
-  - category
-  - impact
-  - effort
-  - recommended action
-  - confidence score
-  - suggested fix
-  - verification hint
-  - optional code location
-- the synthesized brief that drove the review
-
-The renderer also handles failed, canceled, and timed-out reviews.
-
-The reviewer model does **not** decide the final binary verdict directly. It submits review items plus overall explanation/confidence, then the host derives the verdict from the normalized items (`must-fix` items => `PATCH HAS ISSUES`).
-
-When a successful review contains review items, `supi-review` also injects an agent-visible hidden follow-up message that asks the main agent to decide the next step with the user. If `ask_user` is available, the main agent is instructed to use it and offer:
-
-- Fix all
-- Fix selected
-- Verify findings
-- Skip
-
-## Source
-
-- `src/review.ts` — command orchestration and interactive flow
-- `src/config.ts` — persisted agent-tool model setting and `/supi-settings` registration
-- `src/model.ts` — explicit and configured model selection helpers
-- `src/git.ts` — git snapshot resolution
-- `src/history/collect.ts` — compaction-style session-context serialization
-- `src/history/synthesize.ts` — brief synthesis orchestration
-- `src/review-result.ts` — review-item normalization, verdict derivation, and summary counts
-- `src/target/review-instruction-blocks.ts` — fixed catalog of host-owned review instruction blocks
-- `src/target/packet.ts` — final reviewer packet builder + shared preview-data derivation for the inspector
-- `src/session/review-plan-store.ts` — session-scoped, one-shot prepared review plans
-- `src/tool/agent-review-tools.ts` — prepare/run tool registration, dynamic activation, progress, and debug artifact recording
-- `src/tool/agent-review-workflow.ts` — preparation, critique validation, freshness checks, and concurrent reviewer fan-out
-- `src/tool/brief-runner.ts` — brief synthesis child session
-- `src/tool/review-runner.ts` — read-only reviewer child session with snapshot-aware tools
-- `src/tool/snapshot-tools.ts` — per-file diff and before/after content tools scoped to the selected snapshot
-- `src/ui/review-plan-inspector.ts` — in-app summary/inspector preview with Overview + Raw Prompt modes and export fallback
-- `src/ui/renderer.ts` — structured result rendering
+`/supi-review` asks for the reviewer model. Agent-triggered runs use `review.agentModel`. Optional planning uses the separately configured `review.plannerModel` at low thinking effort. Both settings default to the current session model for availability; configure `review.plannerModel` to a lightweight model when using Planner suggestions.

package/node_modules/@mrclrchtr/supi-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrclrchtr/supi-core",
-  "version": "2.8.0",
+  "version": "3.1.0",
   "description": "SuPi core — shared infrastructure for SuPi extensions (XML context tags, config system)",
   "license": "MIT",
   "repository": {
@@ -55,6 +55,7 @@
     "./config": "./src/config.ts",
     "./context": "./src/context.ts",
     "./debug": "./src/debug-registry.ts",
+    "./evidence-badge": "./src/evidence-badge.ts",
     "./footer-registry": "./src/footer-registry.ts",
     "./llm": "./src/llm.ts",
     "./model-selection": "./src/model-selection.ts",

package/node_modules/@mrclrchtr/supi-core/src/api.ts

@@ -15,6 +15,8 @@ export * from "./context.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./debug-registry.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
+export * from "./evidence-badge.ts";
+// biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./footer-registry.ts";
 // biome-ignore lint/performance/noReExportAll: intentional convenience barrel
 export * from "./llm.ts";

package/node_modules/@mrclrchtr/supi-core/src/evidence-badge.ts

@@ -0,0 +1,40 @@
+/**
+ * TUI-facing evidence badge string formatter.
+ *
+ * Pure string formatting — no pi-tui dependency. Consumes evidence
+ * completeness metadata and produces compact human-readable badges.
+ */
+
+/** Metadata describing how many evidence atoms were shown vs exist. */
+export interface EvidenceBadgeInput {
+  shownCount: number;
+  totalCount: number | null;
+  omittedCount: number | null;
+  partialReason: string | null;
+  /** Human-readable label for the badge, e.g. "references", "symbols". */
+  label: string;
+}
+
+/**
+ * Format a compact evidence completeness badge.
+ *
+ * | Input                                                | Output                                |
+ * |------------------------------------------------------|---------------------------------------|
+ * | shown=12, total=12, omitted=0, label="references"   | `12 references`                       |
+ * | shown=8,  total=20, omitted=12, label="symbols"     | `8 of 20 symbols (12 omitted)`        |
+ * | shown=5,  total=null, reason="timeout", label="matches" | `5 matches — timeout`              |
+ */
+export function formatEvidenceBadge(input: EvidenceBadgeInput): string {
+  const { shownCount, totalCount, omittedCount, partialReason, label } = input;
+
+  if (totalCount === null) {
+    const reasonSuffix = partialReason ? ` — ${partialReason}` : "";
+    return `${shownCount} ${label}${reasonSuffix}`;
+  }
+
+  if (omittedCount !== null && omittedCount > 0) {
+    return `${shownCount} of ${totalCount} ${label} (${omittedCount} omitted)`;
+  }
+
+  return `${shownCount} ${label}`;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mrclrchtr/supi-review",
-  "version": "2.8.0",
-  "description": "SuPi Review extension — session-aware review command and agent tools",
+  "version": "3.1.0",
+  "description": "SuPi Review extension — caller-defined read-only review tasks for users and agents",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -31,7 +31,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@mrclrchtr/supi-core": "2.8.0"
+    "@mrclrchtr/supi-core": "3.1.0"
   },
   "bundledDependencies": [
     "@mrclrchtr/supi-core"

package/src/config.ts

@@ -3,32 +3,39 @@ import { loadSupiConfig } from "@mrclrchtr/supi-core/config";
 import { registerDeclarativeSettings } from "@mrclrchtr/supi-core/settings";
 import { CURRENT_SESSION_REVIEW_MODEL } from "./model.ts";
 
-/** Persisted configuration for agent-driven Session-Aware Review. */
+/** Persisted model choices for agent-triggered reviews and optional planning. */
 export interface ReviewConfig extends Record<string, unknown> {
-  /** Canonical `provider/model-id`, or `current` to use the active session model. */
+  /** Canonical reviewer model id, or `current` for the active session model. */
   agentModel: string;
+  /** Canonical Planner model id, or `current` for the active session model. */
+  plannerModel: string;
 }
 
-/** Shared SuPi config section owned by supi-review. */
+/** Shared SuPi configuration section owned by this package. */
 export const REVIEW_CONFIG_SECTION = "review";
-
-/** Package defaults for supi-review configuration. */
+/** Availability-safe defaults; users can configure a separate lightweight Planner model. */
 export const REVIEW_DEFAULTS: ReviewConfig = {
   agentModel: CURRENT_SESSION_REVIEW_MODEL,
+  plannerModel: CURRENT_SESSION_REVIEW_MODEL,
 };
 
-/** Load merged, validated supi-review configuration for a workspace. */
+/** Load merged and normalized review configuration. */
 export function loadReviewConfig(cwd: string, homeDir?: string): ReviewConfig {
   const raw = loadSupiConfig(REVIEW_CONFIG_SECTION, cwd, REVIEW_DEFAULTS, { homeDir });
-  const agentModel =
-    typeof raw.agentModel === "string" && raw.agentModel.trim()
-      ? raw.agentModel.trim()
-      : REVIEW_DEFAULTS.agentModel;
-  return { agentModel };
+  const readModel = (value: unknown, fallback: string) =>
+    typeof value === "string" && value.trim() ? value.trim() : fallback;
+  return {
+    agentModel: readModel(raw.agentModel, REVIEW_DEFAULTS.agentModel),
+    plannerModel: readModel(raw.plannerModel, REVIEW_DEFAULTS.plannerModel),
+  };
 }
 
-/** Register the Review section contributed to `/supi-settings`. */
+/** Contribute reviewer and Planner model pickers to `/supi-settings`. */
 export function registerReviewSettings(pi: ExtensionAPI, homeDir?: string): void {
+  const currentOption = {
+    value: CURRENT_SESSION_REVIEW_MODEL,
+    label: "current session model",
+  };
   registerDeclarativeSettings(pi, {
     id: REVIEW_CONFIG_SECTION,
     label: "Review",
@@ -38,16 +45,18 @@ export function registerReviewSettings(pi: ExtensionAPI, homeDir?: string): void
       {
         kind: "modelPicker",
         key: "agentModel",
-        label: "Agent tool model",
-        description: "Model used for brief synthesis and reviewers started by supi_review_prepare.",
+        label: "Reviewer model",
+        description: "Model shared by all tasks in an agent-triggered review run.",
+        includeDisabled: false,
+        staticOptions: [currentOption],
+      },
+      {
+        kind: "modelPicker",
+        key: "plannerModel",
+        label: "Planner model",
+        description: "Lightweight model used only when planning is set to suggest.",
         includeDisabled: false,
-        staticOptions: [
-          {
-            value: CURRENT_SESSION_REVIEW_MODEL,
-            label: "current session model",
-            description: "Use the model active when supi_review_prepare starts",
-          },
-        ],
+        staticOptions: [currentOption],
       },
     ],
     ...(homeDir ? { homeDir } : {}),

package/src/git-command.ts

@@ -0,0 +1,78 @@
+import { execFile } from "node:child_process";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+const GIT_TIMEOUT_MS = 30_000;
+
+function gitOptions(cwd: string, indexFile?: string) {
+  const env = { ...process.env };
+  for (const key of Object.keys(env)) if (key.startsWith("GIT_")) delete env[key];
+  if (indexFile) env.GIT_INDEX_FILE = indexFile;
+  return { cwd, env, timeout: GIT_TIMEOUT_MS, maxBuffer: 50 * 1024 * 1024 };
+}
+
+/** Run Git with bounded resources and a sanitized environment. */
+export async function runGit(cwd: string, args: string[], indexFile?: string): Promise<string> {
+  return (await execFileAsync("git", args, gitOptions(cwd, indexFile))).stdout;
+}
+
+export function expectedGitExitOutput(error: unknown, allowedCodes: number[]): string | undefined {
+  if (!error || typeof error !== "object") return undefined;
+  const failure = error as {
+    code?: unknown;
+    killed?: unknown;
+    signal?: unknown;
+    stdout?: unknown;
+  };
+  if (
+    typeof failure.code !== "number" ||
+    !allowedCodes.includes(failure.code) ||
+    failure.killed === true ||
+    failure.signal
+  ) {
+    return undefined;
+  }
+  if (typeof failure.stdout === "string") return failure.stdout;
+  if (Buffer.isBuffer(failure.stdout)) return failure.stdout.toString("utf8");
+  return "";
+}
+
+/** Allow only documented non-zero Git outcomes while preserving operational failures. */
+export async function runGitAllowExit(
+  cwd: string,
+  args: string[],
+  allowedCodes: number[],
+  indexFile?: string,
+): Promise<string> {
+  try {
+    return await runGit(cwd, args, indexFile);
+  } catch (error) {
+    const stdout = expectedGitExitOutput(error, allowedCodes);
+    if (stdout !== undefined) return stdout;
+    throw error;
+  }
+}
+
+/** Execute an operation against a temporary index seeded only from HEAD. */
+export async function withHeadIndex<T>(
+  cwd: string,
+  head: string,
+  operation: (indexFile: string) => Promise<T>,
+): Promise<T> {
+  const directory = await mkdtemp(join(tmpdir(), "supi-review-index-"));
+  const indexFile = join(directory, "index");
+  try {
+    await runGit(cwd, ["read-tree", head], indexFile);
+    return await operation(indexFile);
+  } finally {
+    await rm(directory, { recursive: true, force: true });
+  }
+}
+
+/** Disable Git pathspec magic for a path-taking command. */
+export function literalPathspec(args: string[]): string[] {
+  return ["--literal-pathspecs", ...args];
+}