supipowers 1.5.2 → 2.0.0

package/src/review/multi-agent-runner.ts

@@ -1,9 +1,13 @@
 import agentReviewWrapperPrompt from "./prompts/agent-review-wrapper.md" with { type: "text" };
 import outputInstructionsPrompt from "./prompts/output-instructions.md" with { type: "text" };
-import reviewOutputSchema from "./prompts/review-output-schema.md" with { type: "text" };
 import type { ConfiguredReviewAgent, GateExecutionContext, ReviewOutput, ReviewScope } from "../types.js";
-import { explainReviewOutputFailure, parseReviewOutput, runWithOutputValidation } from "./output.js";
-import { renderReviewTemplate } from "./template.js";
+import { runWithOutputValidation, type ReliabilityReporter } from "../ai/structured-output.js";
+import { renderSchemaText } from "../ai/schema-text.js";
+import { explainReviewOutputFailure, parseReviewOutput } from "./output.js";
+import { renderTemplate } from "../ai/template.js";
+import { ReviewOutputSchema } from "./types.js";
+
+const REVIEW_OUTPUT_SCHEMA_TEXT = renderSchemaText(ReviewOutputSchema);
 
 export interface MultiAgentReviewInput {
   cwd: string;
@@ -13,8 +17,11 @@ export interface MultiAgentReviewInput {
   model?: string;
   thinkingLevel?: string | null;
   timeoutMs?: number;
+  /** Tool ids active in the host runtime. Used to gate `peerCoordination` on `irc`. */
+  activeTools?: string[];
   onAgentStart?: (agent: ConfiguredReviewAgent) => void;
   onAgentComplete?: (result: MultiAgentAgentResult) => void;
+  reliability?: ReliabilityReporter;
 }
 
 export interface MultiAgentAgentResult {
@@ -30,8 +37,8 @@ export interface MultiAgentReviewResult {
 }
 
 function renderOutputInstructions(): string {
-  return renderReviewTemplate(outputInstructionsPrompt, {
-    outputSchema: reviewOutputSchema.trim(),
+  return renderTemplate(outputInstructionsPrompt, {
+    outputSchema: REVIEW_OUTPUT_SCHEMA_TEXT,
   });
 }
 
@@ -41,18 +48,95 @@ export function buildConfiguredAgentPrompt(agent: ConfiguredReviewAgent, scope:
   }
 
   const outputInstructions = renderOutputInstructions();
-  const agentPrompt = renderReviewTemplate(
-    agent.prompt.replaceAll("{output_instructions}", "{{outputInstructions}}"),
-    { outputInstructions },
-  );
+  const agentPrompt = renderTemplate(agent.prompt.replaceAll("{output_instructions}", "{{outputInstructions}}"),
+  { outputInstructions },);
 
-  return renderReviewTemplate(agentReviewWrapperPrompt, {
+  return renderTemplate(agentReviewWrapperPrompt, {
     agent,
     agentPrompt,
     scope,
   });
 }
 
+interface PeerCoordinationIdentity {
+  agent: ConfiguredReviewAgent;
+  id: string;
+  displayName: string;
+}
+
+const PEER_COORDINATION_AGENT_ID_PREFIX = "supi-review";
+
+function normalizePeerCoordinationIdSegment(name: string, fallbackIndex: number): string {
+  const normalized = name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return normalized || `agent-${fallbackIndex + 1}`;
+}
+
+function normalizePeerCoordinationDisplayName(name: string, fallbackIndex: number): string {
+  const normalized = name.trim().replace(/\s+/g, " ");
+  return normalized || `review-agent-${fallbackIndex + 1}`;
+}
+
+export function buildPeerCoordinationIdentities(
+  agents: ConfiguredReviewAgent[],
+): PeerCoordinationIdentity[] {
+  const countsByBaseId = new Map<string, number>();
+  return agents.map((agent, index) => {
+    const segment = normalizePeerCoordinationIdSegment(agent.name, index);
+    const baseId = `${PEER_COORDINATION_AGENT_ID_PREFIX}-${segment}`;
+    const previousCount = countsByBaseId.get(baseId) ?? 0;
+    countsByBaseId.set(baseId, previousCount + 1);
+    return {
+      agent,
+      id: previousCount === 0 ? baseId : `${baseId}-${previousCount + 1}`,
+      displayName: normalizePeerCoordinationDisplayName(agent.name, index),
+    };
+  });
+}
+
+/**
+ * Build the IRC peer-coordination prompt block for one agent.
+ *
+ * Returns `null` when peer coordination is disabled, the host runtime does not
+ * expose the `irc` tool, or the agent has no peers (single-agent run, or only
+ * itself opted in).
+ */
+export function buildPeerCoordinationPromptBlock(
+  agent: ConfiguredReviewAgent,
+  peers: ConfiguredReviewAgent[],
+  activeTools: string[],
+  identities: PeerCoordinationIdentity[] = buildPeerCoordinationIdentities(peers),
+): string | null {
+  if (agent.peerCoordination !== true) return null;
+  if (!activeTools.includes("irc")) return null;
+
+  const self = identities.find((identity) => identity.agent === agent);
+  if (!self) return null;
+
+  const otherPeers = identities.filter(
+    (identity) => identity.agent.peerCoordination === true && identity.agent !== agent,
+  );
+  if (otherPeers.length === 0) return null;
+
+  return [
+    "## IRC peer coordination",
+    "",
+    `You are running as \`${self.id}\` in a multi-agent review. Other reviewers also opted into peer coordination:`,
+    ...otherPeers.map((peer) => `- \`${peer.id}\` — ${peer.displayName}`),
+    "",
+    "Use the OMP `irc` tool when continuing alone is wasteful or wrong:",
+    "- Send a DM with `irc({ op: \"send\", to: \"<peer-id>\", message: \"...\" })` when you spot work a peer is already filing, when you need their finding for context, or when you would otherwise duplicate analysis.",
+    "- Reply in plain prose. Do **NOT** send JSON status payloads. Do **NOT** quote the message you are replying to.",
+    "- One DM is one round-trip. Do **NOT** follow up with \"did you get my message?\".",
+    "- Use exactly the peer ids listed above. Do **NOT** invent ids from agent names, and do **NOT** broadcast unless you genuinely need every peer.",
+    "- If a peer has already filed an equivalent finding, do **NOT** file a duplicate; defer to theirs.",
+    "",
+  ].join("\n");
+}
+
 function aggregateAgentOutputs(results: MultiAgentAgentResult[]): ReviewOutput {
   const findings = results.flatMap((result) =>
     result.output.findings.map((finding) => ({
@@ -73,13 +157,25 @@ function aggregateAgentOutputs(results: MultiAgentAgentResult[]): ReviewOutput {
 async function runConfiguredAgent(
   input: Omit<MultiAgentReviewInput, "agents">,
   agent: ConfiguredReviewAgent,
+  peers: ConfiguredReviewAgent[],
+  peerIdentities: PeerCoordinationIdentity[],
 ): Promise<MultiAgentAgentResult> {
   input.onAgentStart?.(agent);
 
+  const identity = peerIdentities.find((peer) => peer.agent === agent);
+  const basePrompt = buildConfiguredAgentPrompt(agent, input.scope);
+  const peerBlock = buildPeerCoordinationPromptBlock(
+    agent,
+    peers,
+    input.activeTools ?? [],
+    peerIdentities,
+  );
+  const prompt = peerBlock ? `${peerBlock}\n${basePrompt}` : basePrompt;
+
   const result = await runWithOutputValidation(input.createAgentSession, {
     cwd: input.cwd,
-    prompt: buildConfiguredAgentPrompt(agent, input.scope),
-    schema: reviewOutputSchema.trim(),
+    prompt,
+    schema: REVIEW_OUTPUT_SCHEMA_TEXT,
     parse(raw) {
       const output = parseReviewOutput(raw);
       return {
@@ -88,8 +184,12 @@ async function runConfiguredAgent(
       };
     },
     model: agent.model ?? input.model,
-    thinkingLevel: input.thinkingLevel ?? null,
+    thinkingLevel: agent.thinkingLevel ?? input.thinkingLevel ?? null,
+    ...(peerBlock && identity
+      ? { agentId: identity.id, agentDisplayName: identity.displayName }
+      : {}),
     timeoutMs: input.timeoutMs ?? 120_000,
+    reliability: input.reliability,
   });
 
   if (result.status === "blocked") {
@@ -124,8 +224,9 @@ async function runConfiguredAgent(
 }
 
 export async function runMultiAgentReview(input: MultiAgentReviewInput): Promise<MultiAgentReviewResult> {
+  const peerIdentities = buildPeerCoordinationIdentities(input.agents);
   const results = await Promise.all(
-    input.agents.map((agent) => runConfiguredAgent(input, agent)),
+    input.agents.map((agent) => runConfiguredAgent(input, agent, input.agents, peerIdentities)),
   );
 
   return {

package/src/review/output.ts

@@ -1,80 +1,15 @@
-import type { TSchema } from "@sinclair/typebox";
-import { Value } from "@sinclair/typebox/value";
-import invalidOutputRetryPrompt from "./prompts/invalid-output-retry.md" with { type: "text" };
-import { runStructuredAgentSession } from "../quality/ai-session.js";
-import { stripMarkdownCodeFence } from "../text.js";
-import type { GateExecutionContext, ReviewOutput } from "../types.js";
-import {
-  ReviewOutputSchema,
-  collectReviewValidationErrors,
-  formatReviewValidationErrors,
-} from "./types.js";
-import { renderReviewTemplate } from "./template.js";
-
-export interface StructuredParseResult<T> {
-  output: T | null;
-  error: string | null;
-}
-
-export interface OutputValidationRunOptions<T> {
-  cwd: string;
-  prompt: string;
-  schema: string;
-  parse: (raw: string) => StructuredParseResult<T>;
-  model?: string;
-  thinkingLevel?: string | null;
-  timeoutMs?: number;
-  maxAttempts?: number;
-}
-
-export type OutputValidationRunResult<T> =
-  | {
-      status: "ok";
-      output: T;
-      rawOutput: string;
-      attempts: number;
-    }
-  | {
-      status: "blocked";
-      error: string;
-      rawOutputs: string[];
-      attempts: number;
-    };
-
-function truncateForPrompt(text: string, maxLength = 1200): string {
-  const normalized = text.trim();
-  if (normalized.length <= maxLength) {
-    return normalized;
-  }
-
-  return `${normalized.slice(0, maxLength - 1)}…`;
-}
-
-export function parseStructuredOutput<T>(raw: string, schema: TSchema): StructuredParseResult<T> {
-  let parsed: unknown;
-
-  try {
-    parsed = JSON.parse(stripMarkdownCodeFence(raw));
-  } catch (error) {
-    return {
-      output: null,
-      error: error instanceof Error ? `Invalid JSON: ${error.message}` : "Invalid JSON.",
-    };
-  }
-
-  if (!Value.Check(schema, parsed)) {
-    const errors = formatReviewValidationErrors(collectReviewValidationErrors(schema, parsed));
-    return {
-      output: null,
-      error: errors.length > 0 ? errors.join("; ") : "Output does not match the required schema.",
-    };
-  }
-
-  return {
-    output: parsed as T,
-    error: null,
-  };
-}
+// src/review/output.ts
+//
+// Review-specific thin wrappers over the shared structured-output foundation.
+// Everything generic (parseStructuredOutput<T>, runWithOutputValidation<T>,
+// StructuredOutputResult<T>, validation-error helpers) lives in
+// src/ai/structured-output.ts. This module exists only so review callers can
+// parse a raw model response into ReviewOutput without rewriting the schema
+// reference at every site.
+
+import { parseStructuredOutput } from "../ai/structured-output.js";
+import type { ReviewOutput } from "../types.js";
+import { ReviewOutputSchema } from "./types.js";
 
 export function parseReviewOutput(raw: string): ReviewOutput | null {
   return parseStructuredOutput<ReviewOutput>(raw, ReviewOutputSchema).output;
@@ -83,65 +18,3 @@ export function parseReviewOutput(raw: string): ReviewOutput | null {
 export function explainReviewOutputFailure(raw: string): string | null {
   return parseStructuredOutput<ReviewOutput>(raw, ReviewOutputSchema).error;
 }
-
-export async function runWithOutputValidation<T>(
-  createAgentSession: GateExecutionContext["createAgentSession"],
-  options: OutputValidationRunOptions<T>,
-): Promise<OutputValidationRunResult<T>> {
-  const maxAttempts = Math.max(1, options.maxAttempts ?? 3);
-  const rawOutputs: string[] = [];
-  let prompt = options.prompt;
-
-  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
-    const result = await runStructuredAgentSession(createAgentSession, {
-      cwd: options.cwd,
-      prompt,
-      model: options.model,
-      thinkingLevel: options.thinkingLevel ?? null,
-      timeoutMs: options.timeoutMs,
-    });
-
-    if (result.status !== "ok") {
-      return {
-        status: "blocked",
-        error: result.error,
-        rawOutputs,
-        attempts: attempt,
-      };
-    }
-
-    rawOutputs.push(result.finalText);
-    const parsed = options.parse(result.finalText);
-    if (parsed.output) {
-      return {
-        status: "ok",
-        output: parsed.output,
-        rawOutput: result.finalText,
-        attempts: attempt,
-      };
-    }
-
-    if (attempt === maxAttempts) {
-      return {
-        status: "blocked",
-        error: parsed.error ?? "Agent output was invalid.",
-        rawOutputs,
-        attempts: attempt,
-      };
-    }
-
-    prompt = renderReviewTemplate(invalidOutputRetryPrompt, {
-      prompt: options.prompt,
-      error: parsed.error ?? "Agent output was invalid.",
-      previousOutput: truncateForPrompt(result.finalText),
-      schema: options.schema,
-    });
-  }
-
-  return {
-    status: "blocked",
-    error: "Output validation exhausted without producing a valid result.",
-    rawOutputs,
-    attempts: maxAttempts,
-  };
-}

package/src/review/runner.ts

@@ -1,8 +1,12 @@
-import reviewOutputSchema from "./prompts/review-output-schema.md" with { type: "text" };
 import singleReviewPrompt from "./prompts/single-review.md" with { type: "text" };
 import type { GateExecutionContext, ReviewLevel, ReviewOutput, ReviewScope } from "../types.js";
-import { explainReviewOutputFailure, parseReviewOutput, runWithOutputValidation } from "./output.js";
-import { renderReviewTemplate } from "./template.js";
+import { runWithOutputValidation, type ReliabilityReporter } from "../ai/structured-output.js";
+import { renderSchemaText } from "../ai/schema-text.js";
+import { explainReviewOutputFailure, parseReviewOutput } from "./output.js";
+import { renderTemplate } from "../ai/template.js";
+import { ReviewOutputSchema } from "./types.js";
+
+const REVIEW_OUTPUT_SCHEMA_TEXT = renderSchemaText(ReviewOutputSchema);
 
 export type SingleReviewLevel = Extract<ReviewLevel, "quick" | "deep">;
 
@@ -14,6 +18,7 @@ export interface SingleReviewRunnerInput {
   model?: string;
   thinkingLevel?: string | null;
   timeoutMs?: number;
+  reliability?: ReliabilityReporter;
 }
 
 export interface SingleReviewRunResult {
@@ -70,12 +75,12 @@ export function normalizeReviewOutput(output: ReviewOutput): ReviewOutput {
 }
 
 export function buildSingleReviewPrompt(scope: ReviewScope, level: SingleReviewLevel): string {
-  return renderReviewTemplate(singleReviewPrompt, {
+  return renderTemplate(singleReviewPrompt, {
     level,
     scope,
     isQuick: level === "quick",
     isDeep: level === "deep",
-    outputSchema: reviewOutputSchema.trim(),
+    outputSchema: REVIEW_OUTPUT_SCHEMA_TEXT,
   });
 }
 
@@ -83,7 +88,7 @@ export async function runSingleReview(input: SingleReviewRunnerInput): Promise<S
   const result = await runWithOutputValidation(input.createAgentSession, {
     cwd: input.cwd,
     prompt: buildSingleReviewPrompt(input.scope, input.level),
-    schema: reviewOutputSchema.trim(),
+    schema: REVIEW_OUTPUT_SCHEMA_TEXT,
     parse(raw) {
       const output = parseReviewOutput(raw);
       return {
@@ -94,6 +99,7 @@ export async function runSingleReview(input: SingleReviewRunnerInput): Promise<S
     model: input.model,
     thinkingLevel: input.thinkingLevel ?? null,
     timeoutMs: input.timeoutMs ?? 120_000,
+    reliability: input.reliability,
   });
 
   if (result.status === "blocked") {

package/src/review/scope.ts

@@ -1,5 +1,7 @@
 import type { Platform, PlatformContext } from "../platform/types.js";
-import type { ReviewScope, ReviewScopeFile, ReviewScopeStats } from "../types.js";
+import type { ReviewScope, ReviewScopeFile, ReviewScopeStats, WorkspaceTarget } from "../types.js";
+import { filterGitLogOnelineToWorkspaceTarget } from "../workspace/git-scope.js";
+import { findWorkspaceTargetForPath } from "../workspace/path-mapping.js";
 
 interface ExcludedReviewScopeFile {
   path: string;
@@ -14,6 +16,11 @@ export interface ParsedReviewDiff {
   stats: ReviewScopeStats;
 }
 
+export interface ReviewWorkspaceSelection {
+  target: WorkspaceTarget;
+  targets: WorkspaceTarget[];
+}
+
 export const EXCLUDED_PATTERNS: Array<{ pattern: RegExp; reason: string }> = [
   { pattern: /\.lock$/, reason: "lock file" },
   { pattern: /-lock\.(json|yaml|yml)$/, reason: "lock file" },
@@ -200,6 +207,51 @@ function ensureReviewableScope(scope: ReviewScope, message: string): ReviewScope
   return scope;
 }
 
+function buildTargetLabel(selection: ReviewWorkspaceSelection): string {
+  return `${selection.target.name} (${selection.target.relativeDir})`;
+}
+
+function appendTargetContext(description: string, selection?: ReviewWorkspaceSelection | null): string {
+  return selection ? `${description} for ${buildTargetLabel(selection)}` : description;
+}
+
+function buildEmptyScopeMessage(baseMessage: string, selection?: ReviewWorkspaceSelection | null): string {
+  return selection
+    ? `${baseMessage} for ${buildTargetLabel(selection)}.`
+    : `${baseMessage}.`;
+}
+
+function ensureTargetScopeHasDiff(
+  diff: string,
+  emptyScopeMessage: string,
+  selection?: ReviewWorkspaceSelection | null,
+): void {
+  if (selection && !diff.trim()) {
+    throw new Error(emptyScopeMessage);
+  }
+}
+
+function filterDiffToWorkspaceTarget(diffOutput: string, selection?: ReviewWorkspaceSelection | null): string {
+  if (!selection || !diffOutput.trim()) {
+    return diffOutput;
+  }
+
+  return diffOutput
+    .split(/^diff --git /m)
+    .filter(Boolean)
+    .map((chunk) => `diff --git ${chunk}`)
+    .filter((chunk) => {
+      const headerMatch = chunk.match(/^diff --git a\/(.+?) b\/(.+)/m);
+      const repoRelativePath = headerMatch?.[2]?.trim();
+      if (!repoRelativePath) {
+        return false;
+      }
+
+      return findWorkspaceTargetForPath(selection.targets, repoRelativePath)?.id === selection.target.id;
+    })
+    .join("\n");
+}
+
 export async function listReviewBaseBranches(platform: Pick<Platform, "exec">, cwd: string): Promise<string[]> {
   const output = await execGit(platform, cwd, ["branch", "--all", "--format=%(refname:short)"]);
   return [...new Set(
@@ -220,9 +272,18 @@ export async function listRecentReviewCommits(
   platform: Pick<Platform, "exec">,
   cwd: string,
   count = 20,
+  selection?: ReviewWorkspaceSelection | null,
 ): Promise<string[]> {
-  const output = await execGit(platform, cwd, ["log", "--oneline", `-${count}`]);
-  return output
+  if (!selection) {
+    const output = await execGit(platform, cwd, ["log", "--oneline", `-${count}`]);
+    return output
+      .split("\n")
+      .map((line) => line.trim())
+      .filter((line) => line.length > 0);
+  }
+
+  const output = await execGit(platform, cwd, ["log", `-${count}`, "--format=%H%x1f%s%x1e", "--name-only"]);
+  return filterGitLogOnelineToWorkspaceTarget(output, selection.targets, selection.target)
     .split("\n")
     .map((line) => line.trim())
     .filter((line) => line.length > 0);
@@ -233,63 +294,120 @@ export async function loadPullRequestScope(
   cwd: string,
   baseBranch: string,
   currentBranch?: string,
+  selection?: ReviewWorkspaceSelection | null,
 ): Promise<ReviewScope> {
   const branch = currentBranch ?? await getCurrentReviewBranch(platform, cwd);
-  const diff = await execGit(platform, cwd, ["diff", "--no-ext-diff", "--binary", `${baseBranch}...${branch}`]);
+  const rawDiff = await execGit(platform, cwd, ["diff", "--no-ext-diff", "--binary", `${baseBranch}...${branch}`]);
+  const diff = filterDiffToWorkspaceTarget(rawDiff, selection);
+  ensureTargetScopeHasDiff(
+    diff,
+    buildEmptyScopeMessage("No reviewable files remain after filtering PR-style changes", selection),
+    selection,
+  );
   const scope = createScope(
     "pull-request",
-    `Reviewing changes between ${baseBranch} and ${branch}`,
+    appendTargetContext(`Reviewing changes between ${baseBranch} and ${branch}`, selection),
     diff,
     { baseBranch },
   );
-  return ensureReviewableScope(scope, "No reviewable files remain after filtering PR-style changes.");
+  return ensureReviewableScope(
+    scope,
+    buildEmptyScopeMessage("No reviewable files remain after filtering PR-style changes", selection),
+  );
 }
 
-export async function loadUncommittedScope(platform: Pick<Platform, "exec">, cwd: string): Promise<ReviewScope> {
+export async function loadUncommittedScope(
+  platform: Pick<Platform, "exec">,
+  cwd: string,
+  selection?: ReviewWorkspaceSelection | null,
+): Promise<ReviewScope> {
   const [unstaged, staged, untracked] = await Promise.all([
     execGit(platform, cwd, ["diff", "--no-ext-diff", "--binary"]),
     execGit(platform, cwd, ["diff", "--cached", "--no-ext-diff", "--binary"]),
     buildUntrackedDiff(platform, cwd),
   ]);
-  const diff = [unstaged, staged, untracked].filter((chunk) => chunk.trim().length > 0).join("\n");
-  const scope = createScope("uncommitted", "Reviewing uncommitted changes", diff);
-  return ensureReviewableScope(scope, "No reviewable files remain after filtering uncommitted changes.");
+  const rawDiff = [unstaged, staged, untracked].filter((chunk) => chunk.trim().length > 0).join("\n");
+  const diff = filterDiffToWorkspaceTarget(rawDiff, selection);
+  ensureTargetScopeHasDiff(
+    diff,
+    buildEmptyScopeMessage("No reviewable files remain after filtering uncommitted changes", selection),
+    selection,
+  );
+  const scope = createScope(
+    "uncommitted",
+    appendTargetContext("Reviewing uncommitted changes", selection),
+    diff,
+  );
+  return ensureReviewableScope(
+    scope,
+    buildEmptyScopeMessage("No reviewable files remain after filtering uncommitted changes", selection),
+  );
 }
 
 export async function loadCommitScope(
   platform: Pick<Platform, "exec">,
   cwd: string,
   commit: string,
+  selection?: ReviewWorkspaceSelection | null,
 ): Promise<ReviewScope> {
-  const diff = await execGit(platform, cwd, ["show", "--format=", "--no-ext-diff", "--binary", commit]);
-  const scope = createScope("commit", `Reviewing commit ${commit}`, diff, { commit });
-  return ensureReviewableScope(scope, "No reviewable files remain after filtering commit changes.");
+  const rawDiff = await execGit(platform, cwd, ["show", "--format=", "--no-ext-diff", "--binary", commit]);
+  const diff = filterDiffToWorkspaceTarget(rawDiff, selection);
+  ensureTargetScopeHasDiff(
+    diff,
+    buildEmptyScopeMessage("No reviewable files remain after filtering commit changes", selection),
+    selection,
+  );
+  const scope = createScope(
+    "commit",
+    appendTargetContext(`Reviewing commit ${commit}`, selection),
+    diff,
+    { commit },
+  );
+  return ensureReviewableScope(
+    scope,
+    buildEmptyScopeMessage("No reviewable files remain after filtering commit changes", selection),
+  );
 }
 
 export async function loadCustomReviewScope(
   platform: Pick<Platform, "exec">,
   cwd: string,
   instructions: string,
+  selection?: ReviewWorkspaceSelection | null,
 ): Promise<ReviewScope> {
-  let diff = "";
+  let rawDiff = "";
 
   try {
-    diff = await execGit(platform, cwd, ["diff", "--no-ext-diff", "--binary", "HEAD"]);
+    rawDiff = await execGit(platform, cwd, ["diff", "--no-ext-diff", "--binary", "HEAD"]);
   } catch {
-    diff = "";
+    rawDiff = "";
   }
 
-  return createScope(
+  const diff = filterDiffToWorkspaceTarget(rawDiff, selection);
+  ensureTargetScopeHasDiff(
+    diff,
+    buildEmptyScopeMessage("No reviewable files remain after filtering custom review changes", selection),
+    selection,
+  );
+  const scope = createScope(
     "custom",
-    `Custom review: ${instructions.slice(0, 60)}`,
+    appendTargetContext(`Custom review: ${instructions.slice(0, 60)}`, selection),
     diff,
     { customInstructions: instructions },
   );
+
+  return selection
+    ? ensureReviewableScope(
+        scope,
+        buildEmptyScopeMessage("No reviewable files remain after filtering custom review changes", selection),
+      )
+    : scope;
 }
 
 export async function selectReviewScope(
   platform: Pick<Platform, "exec">,
   ctx: Pick<PlatformContext, "cwd" | "ui">,
+  selection?: ReviewWorkspaceSelection | null,
 ): Promise<ReviewScope | null> {
   const choice = await ctx.ui.select(
     "What should /supi:review inspect?",
@@ -317,17 +435,19 @@ export async function selectReviewScope(
     if (!selected) {
       return null;
     }
-    return loadPullRequestScope(platform, ctx.cwd, selected);
+    return loadPullRequestScope(platform, ctx.cwd, selected, undefined, selection);
   }
 
   if (choice.startsWith("Uncommitted changes")) {
-    return loadUncommittedScope(platform, ctx.cwd);
+    return loadUncommittedScope(platform, ctx.cwd, selection);
   }
 
   if (choice.startsWith("Specific commit")) {
-    const commits = await listRecentReviewCommits(platform, ctx.cwd);
+    const commits = await listRecentReviewCommits(platform, ctx.cwd, 20, selection);
     if (commits.length === 0) {
-      throw new Error("No commits found.");
+      throw new Error(selection
+        ? `No commits found for ${buildTargetLabel(selection)}.`
+        : "No commits found.");
     }
     const selected = await ctx.ui.select("Commit to review", commits, {
       helpText: "Select a recent commit · Esc to cancel",
@@ -339,7 +459,7 @@ export async function selectReviewScope(
     if (!commit) {
       throw new Error("Could not determine the selected commit hash.");
     }
-    return loadCommitScope(platform, ctx.cwd, commit);
+    return loadCommitScope(platform, ctx.cwd, commit, selection);
   }
 
   const instructions = await ctx.ui.input("Custom review focus", {
@@ -349,5 +469,5 @@ export async function selectReviewScope(
   if (!instructions?.trim()) {
     return null;
   }
-  return loadCustomReviewScope(platform, ctx.cwd, instructions.trim());
+  return loadCustomReviewScope(platform, ctx.cwd, instructions.trim(), selection);
 }