@jameslovespancakes/pi-plus 1.0.11 → 1.0.13

package/src/domains/workflows/workflows/code-review.ts

@@ -0,0 +1,232 @@
+import { challengeFindings, parseChallengeArgs } from "../runtime/advisory-challenge.ts";
+import { Type } from "typebox";
+import {
+  type AdvisoryVerified,
+  type AdvisoryLens,
+  synthesizeAdvisoryReport,
+  finishAdvisoryReport,
+  formatEvidence,
+  formatLocation,
+  normalizePath,
+  publishVerifiedKeptProgress,
+  runLensVerificationPipeline,
+  verdictConfidence,
+  DEFAULT_ADVISORY_TOOL_HINTS,
+  DEFAULT_ADVISORY_TOOLS,
+} from "../runtime/workflow-advisory-utils.ts";
+import { formatReviewDiffTarget, parseAllowedDiffCommand } from "../runtime/review-diff-target.ts";
+import { buildCodeReviewScopeBlock } from "../runtime/review/code-review-orchestration.ts";
+import type { ReviewContext } from "../runtime/review/review-report.ts";
+import { captureReviewMaterial, type ReviewMaterialCaptureResult } from "../runtime/review/review-snapshot.ts";
+import type { WorkflowApi, WorkflowMeta, WorkflowRunStats } from "../runtime/types.ts";
+
+export const meta: WorkflowMeta = {
+  name: "code-review",
+  description: "Fan-out review of the branch's open PR (or branch vs main): scope → per-angle find → independent verify → synthesize.",
+  phases: [{ title: "Scope" }, { title: "Find" }, { title: "Verify" }, { title: "Challenge" }, { title: "Synthesize" }],
+};
+
+// ─── Schemas (the contracts that make orchestration plain code) ───
+const ScopeSchema = Type.Object({
+  diffCommand: Type.String({ description: "Exact git command that produces the review diff" }),
+  files: Type.Array(Type.String(), { description: "Changed file paths" }),
+  summary: Type.String({ description: "One-paragraph summary of the change" }),
+  conventions: Type.Optional(Type.String({ description: "Relevant AGENTS.md / project conventions" })),
+});
+
+// The review lenses — this is the part you customise to your codebase's real failure modes.
+const ANGLES: AdvisoryLens[] = [
+  { label: "logic-bugs", category: "bug", text: "Off-by-one errors, wrong conditionals, incorrect return values, broken control flow." },
+  { label: "error-paths", category: "bug", text: "Unhandled errors, swallowed exceptions, missing awaits, partial failure leaving inconsistent state." },
+  { label: "edge-cases", category: "bug", text: "Empty/null inputs, boundary values, concurrency races, resource leaks." },
+  { label: "simplification", category: "cleanup", text: "Dead code, needless complexity, duplicated logic, clearer equivalents." },
+  { label: "conventions", category: "cleanup", text: "Violations of the project conventions noted in scope (naming, idioms, banned patterns)." },
+];
+
+const PER_ANGLE = 6;
+
+/** Parse a unified diff into the set of added/changed new-file line numbers per file. */
+export function changedLines(diff: string): Map<string, Set<number>> {
+  const byFile = new Map<string, Set<number>>();
+  let file: string | null = null;
+  let newLine = 0;
+  for (const raw of diff.split("\n")) {
+    if (raw.startsWith("+++ ")) {
+      const path = raw.slice(4).trim();
+      file = path === "/dev/null" ? null : normalizePath(path);
+      if (file && !byFile.has(file)) byFile.set(file, new Set());
+    } else if (raw.startsWith("@@")) {
+      const match = /\+(\d+)/.exec(raw);
+      newLine = match ? Number(match[1]) : 0;
+    } else if (file === null || raw.startsWith("---") || raw.startsWith("\\")) {
+      // file header, deletion, or "No newline" marker — record nothing
+    } else if (raw.startsWith("+")) {
+      byFile.get(file)!.add(newLine++);
+    } else if (!raw.startsWith("-")) {
+      newLine++; // context line advances the new-file counter; deletions do not
+    }
+  }
+  return byFile;
+}
+
+/** Is a finding inside the diff? File-level findings count if the file changed; ±1 line of fuzz. */
+export function inDiff(changed: Map<string, Set<number>>, file: string, line?: number): boolean {
+  const set = changed.get(normalizePath(file));
+  if (!set) return false;
+  if (line == null) return true;
+  return set.has(line) || set.has(line - 1) || set.has(line + 1);
+}
+
+export interface CodeReviewDependencies {
+  readonly captureReviewMaterial?: (
+    target: Parameters<typeof captureReviewMaterial>[0],
+    cwd: string,
+    signal?: AbortSignal,
+  ) => Promise<ReviewMaterialCaptureResult>;
+}
+
+export default async function run(api: WorkflowApi, dependencies: CodeReviewDependencies = {}): Promise<unknown> {
+  const { agent, phase, log, progress, args, cwd, signal } = api;
+  const challengeConfig = parseChallengeArgs(args);
+  const target = challengeConfig.args.trim();
+  let fileCount = 0;
+  let rawCandidateCount = 0;
+  let droppedCandidateCount = 0;
+  const makeStats = (verified: number, kept: number): WorkflowRunStats => ({
+    files: fileCount,
+    candidates: rawCandidateCount,
+    verified,
+    kept,
+    dropped: droppedCandidateCount,
+  });
+
+  // ─── Phase 0: Scope ───
+  phase("Scope");
+  const scope = await agent(
+    "Establish the scope of a code review.\n" +
+      (target
+        ? `Target / instructions (verbatim): "${target}". If it names a PR number, branch, ref range, or files, build the matching diff command (use 'gh pr diff <number>' for a PR). Otherwise use the default selection below.\n`
+        : "No explicit target — select the diff to review using the default below.\n") +
+      "Canonical Git syntax: use `git diff -- <path> [<path>...]` for file paths; use one `A..B` or `A...B` range operand for two revisions. Never emit ambiguous two-operand forms such as `git diff A B`.\n" +
+      "Default selection — run commands to decide, falling through until you get a NON-EMPTY diff:\n" +
+      "1. Get the current branch: `git branch --show-current`.\n" +
+      "2. Check for an OPEN GitHub PR for this branch: `gh pr list --head <branch> --state open --json number,title`. " +
+      "If one exists, the diff command is `gh pr diff <number>` — note the PR number and title in the summary.\n" +
+      "3. If there is no open PR (or `gh` is unavailable / there is no GitHub remote), diff the branch against its base: " +
+      "prefer `git diff main...HEAD`, then `git diff master...HEAD`, then `git diff HEAD~1`. " +
+      "If the branch itself is main/master, use `git diff HEAD~1`.\n" +
+      "4. Run the chosen command to confirm the diff is non-empty.\n\n" +
+      "Then: list the changed files, summarize the change in one paragraph (mention the PR if one was found), " +
+      "and read any relevant AGENTS.md or project docs noting conventions a reviewer should know.\n" +
+      "Return diffCommand exactly as a reviewer should run it. Structured output only.",
+    { phase: "Scope", label: "scope", tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS, profile: "medium", schema: ScopeSchema },
+  );
+
+  if (!scope) {
+    return { summary: "No changes found to review.", findings: [], nextSteps: ["Provide a PR, ref range, or changed files to review."], stats: makeStats(0, 0) };
+  }
+
+  fileCount = scope.files.length;
+  progress({ type: "summary", key: "files", value: scope.files.join(", ") || "(none)" });
+  const diffTarget = parseAllowedDiffCommand(scope.diffCommand);
+  if ("error" in diffTarget) {
+    throw new Error(`Code-review target rejected: ${diffTarget.error}`);
+  }
+  const diffCommand = formatReviewDiffTarget(diffTarget);
+  progress({ type: "summary", key: "diffCommand", value: diffCommand });
+  progress({ type: "counter", key: "files", label: "files", value: fileCount });
+
+  if (scope.files.length === 0) {
+    return { summary: "No changes found to review.", findings: [], nextSteps: ["Provide a PR, ref range, or changed files to review."], stats: makeStats(0, 0) };
+  }
+
+  log(`${scope.files.length} changed files`);
+
+  // Capture the diff once, deterministically, so findings can be bounded to changed lines in code.
+  const reviewMaterial = await (dependencies.captureReviewMaterial ?? captureReviewMaterial)(diffTarget, cwd, signal);
+  if (!reviewMaterial.ok) {
+    throw new Error(`Code-review diff capture failed: ${reviewMaterial.error}`);
+  }
+  const diffText = reviewMaterial.diff;
+  const changed = changedLines(diffText);
+  progress({ type: "summary", key: "diffBytes", value: Buffer.byteLength(diffText) });
+  if (reviewMaterial.snapshot.status === "unavailable") {
+    log(`review snapshot unavailable (${reviewMaterial.snapshot.reason}) — patch previews will be unavailable`);
+  }
+
+  const reviewContext: ReviewContext = {
+    workflowName: "code-review",
+    target,
+    diffTarget,
+    files: scope.files,
+    summary: scope.summary,
+    ...(reviewMaterial.snapshot.status === "verified"
+      ? { snapshot: reviewMaterial.snapshot.identity }
+      : {}),
+  };
+
+  const scopeBlock = `Reviewed snapshot identity: ${JSON.stringify(reviewContext.snapshot ?? "unavailable")}\n` + buildCodeReviewScopeBlock({
+    diffCommand,
+    files: scope.files,
+    summary: scope.summary,
+    conventions: scope.conventions,
+    diffText,
+    target,
+  });
+
+  const pipelineResult = await runLensVerificationPipeline({
+    api,
+    lenses: ANGLES,
+    perLens: PER_ANGLE,
+    boundCandidate: (candidate, lens) => {
+      const anchor = candidate.reviewAnchor ?? candidate.locations.find((location) => inDiff(changed, location.file, location.line));
+      return anchor && inDiff(changed, anchor.file, anchor.line)
+        ? { ...candidate, category: lens.category, reviewAnchor: anchor } : undefined;
+    },
+    finderPrompt: (lens) =>
+      `## Code-review finder — ${lens.label}\n\n${scopeBlock}\n` +
+      `Review the change through ONLY this lens:\n${lens.text}\n` +
+      "Only flag issues on lines that are part of the diff above (run the diff command if it is not shown). " +
+      "Set reviewAnchor to the changed line causing the issue; locations and discoveryEvidence may include unchanged callers and other files. " +
+      `Surface up to ${PER_ANGLE} candidates. Use category exactly "${lens.category}". Each candidate must include a one-line summary, ` +
+      "locations with the changed file and a line that appears in the diff, and impact describing the concrete failure or maintenance scenario. " +
+      "Pass through anything with a nameable impact — a separate verifier judges them next. Structured output only.",
+    verifierPrompt: (candidate) =>
+      `## Code-review verifier\n\n${scopeBlock}\n## Candidate\n` +
+      `Location: ${formatLocation(candidate)}\n` +
+      `Category: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}\n\n` +
+      "Run the diff command, read the relevant file(s), and return exactly one verdict (CONFIRMED / PLAUSIBLE / NOT_SUBSTANTIATED / REFUTED) " +
+      "with evidence quoting the line(s). Use NOT_SUBSTANTIATED when evidence is insufficient; use REFUTED only for concrete disproof. Structured output only.",
+  });
+  rawCandidateCount += pipelineResult.rawCandidates;
+  droppedCandidateCount += pipelineResult.dropped;
+  const { coverage } = pipelineResult;
+  const verified = await challengeFindings(api, pipelineResult.verified, scopeBlock, challengeConfig.options, coverage);
+  const surviving = verified.filter((finding) => finding.verdict !== "REFUTED");
+  const stats = makeStats(verified.length, surviving.length);
+  publishVerifiedKeptProgress({ progress, log }, verified.length, surviving.length);
+
+  if (surviving.length === 0) {
+    return finishAdvisoryReport({ summary: "No findings survived verification.", findings: [], nextSteps: ["No code-review action is recommended from this workflow run."], stats, reviewContext }, coverage, verified);
+  }
+
+  // ─── Synthesize: rank, merge, report ───
+  const rank = (finding: AdvisoryVerified): number => (finding.category === "cleanup" ? 2 : 0) + (finding.verdict !== "CONFIRMED" ? 1 : 0);
+  const ranked = [...surviving].sort((a, b) => rank(a) - rank(b));
+  const block = ranked
+    .map(
+      (finding, index) =>
+        `### [${index}] IDs: ${finding.sourceCandidateIds.join(", ")} ${formatLocation(finding)} (${finding.verdict}${finding.category === "cleanup" ? ", cleanup" : ""})\n` +
+        `Category: ${finding.category}\nConfidence: ${verdictConfidence(finding.verdict)}\n` +
+        `${finding.summary}\nImpact: ${finding.impact}\nEvidence: ${formatEvidence(finding.evidence)}`,
+    )
+    .join("\n\n");
+
+  const resolved = await synthesizeAdvisoryReport(api,
+    `## Synthesis: final code-review report\n\n${ranked.length} findings survived independent verification.\n\n${block}\n\n` +
+      "Merge findings with the same root cause, rank most-severe first (correctness bugs above cleanups), and produce the final advisory report. " +
+      "Return summary, ID selections with severity (low/medium/high) and advisory recommendation, and nextSteps. Evidence and confidence are reconstructed from verified records. Structured output only.",
+    ranked, coverage,
+  );
+  return finishAdvisoryReport({ ...resolved, stats: { ...stats, kept: resolved.findings.length }, reviewContext }, coverage, verified);
+}

package/src/domains/workflows/workflows/diagnose.ts

@@ -0,0 +1,154 @@
+import { challengeFindings, parseChallengeArgs } from "../runtime/advisory-challenge.ts";
+import { Type } from "typebox";
+import {
+  type AdvisoryVerified,
+  type AdvisoryLens,
+  synthesizeAdvisoryReport,
+  finishAdvisoryReport,
+  emptyAdvisoryReport,
+  formatEvidence,
+  formatLocation,
+  publishVerifiedKeptProgress,
+  runLensVerificationPipeline,
+  DEFAULT_ADVISORY_TOOL_HINTS,
+  DEFAULT_ADVISORY_TOOLS,
+} from "../runtime/workflow-advisory-utils.ts";
+import type { WorkflowApi, WorkflowMeta, WorkflowRunStats } from "../runtime/types.ts";
+
+export const meta: WorkflowMeta = {
+  name: "diagnose",
+  description: "Advisory-only bug diagnosis: scope symptoms → competing hypotheses → independent verify → synthesize likely root causes.",
+  phases: [{ title: "Scope" }, { title: "Hypothesize" }, { title: "Verify" }, { title: "Challenge" }, { title: "Synthesize" }],
+};
+
+const ScopeSchema = Type.Object({
+  symptom: Type.String({ description: "Observed bug, failing command, regression, or unclear behavior." }),
+  commands: Type.Array(Type.String(), { description: "Safe read-only or diagnostic commands relevant to the symptom." }),
+  files: Type.Array(Type.String(), { description: "Repository-relative files likely involved." }),
+  observations: Type.Array(Type.String(), { description: "Concrete observations from files, tests, config, or command output." }),
+  constraints: Type.Optional(Type.String({ description: "Safety constraints, missing evidence, or commands intentionally not run." })),
+});
+
+const HYPOTHESIS_LENSES: AdvisoryLens[] = [
+  { label: "recent-change", category: "regression", text: "A recent code change broke a previously working path or changed an implicit contract." },
+  { label: "control-flow", category: "root-cause", text: "Incorrect branching, ordering, async flow, data flow, or state transition causes the symptom." },
+  { label: "configuration", category: "configuration", text: "Configuration, environment, package scripts, or runtime assumptions differ from what the code expects." },
+  { label: "dependency-api", category: "dependency", text: "A dependency API, version, import mode, or bundled peer behavior does not match the implementation." },
+  { label: "test-fixture", category: "test-fixture", text: "The failure is caused by test setup, fixtures, mocks, generated files, or stale local state rather than product code." },
+];
+
+const PER_LENS = 4;
+
+export default async function run(api: WorkflowApi): Promise<unknown> {
+  const { agent, phase, log, progress, args } = api;
+  const challengeConfig = parseChallengeArgs(args);
+  const symptom = challengeConfig.args.trim();
+  let fileCount = 0;
+  let rawCandidateCount = 0;
+  let droppedCandidateCount = 0;
+  let refutedCandidateCount = 0;
+  const makeStats = (verified: number, kept: number): WorkflowRunStats => ({
+    files: fileCount,
+    candidates: rawCandidateCount,
+    verified,
+    kept,
+    dropped: droppedCandidateCount,
+    refuted: refutedCandidateCount,
+  });
+
+  phase("Scope");
+  const scope = await agent(
+    "Establish the scope for an advisory-only diagnosis workflow. Do not edit files.\n" +
+      (symptom
+        ? `Bug / failure description (verbatim): ${symptom}\n\n`
+        : "No explicit symptom was provided. Infer likely failing commands from repository manifests and scripts without running destructive commands.\n\n") +
+      "Inspect relevant files, package/test configuration, and safe diagnostic commands. " +
+      "Safe commands are read-only commands such as status, grep, listing files, typecheck/test commands, or commands explicitly requested by the user. " +
+      "Do not run mutation, install, commit, network, or destructive commands. Return scoped files, observations, and constraints. Structured output only.",
+    { phase: "Scope", label: "scope", tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS, profile: "medium", schema: ScopeSchema },
+  );
+
+  if (!scope) {
+    return finishAdvisoryReport(emptyAdvisoryReport(
+      "Diagnosis could not establish a scope.",
+      ["Provide the failing command, error message, or regression description and rerun diagnose."],
+      makeStats(0, 0),
+    ), []);
+  }
+
+  fileCount = scope.files.length;
+  progress({ type: "counter", key: "files", label: "files", value: fileCount });
+  progress({ type: "summary", key: "symptom", value: scope.symptom });
+  progress({ type: "summary", key: "files", value: scope.files.join(", ") || "(none)" });
+  log(`${scope.files.length} files scoped for diagnosis`);
+
+  const scopeBlock =
+    `## Symptom\n${scope.symptom}\n\n## Relevant commands\n${scope.commands.map((command) => `- ${command}`).join("\n") || "(none)"}\n\n` +
+    `## Files\n${scope.files.map((file) => `- ${file}`).join("\n") || "(none)"}\n\n` +
+    `## Observations\n${scope.observations.map((observation) => `- ${observation}`).join("\n") || "(none)"}\n\n` +
+    `## Constraints\n${scope.constraints ?? "(none noted)"}\n`;
+
+  const pipelineResult = await runLensVerificationPipeline({
+    api,
+    lenses: HYPOTHESIS_LENSES,
+    perLens: PER_LENS,
+    finderPhase: "Hypothesize",
+    finderPrompt: (lens) =>
+      `## Diagnose hypothesis generator — ${lens.label}\n\n${scopeBlock}\n` +
+      "This workflow is advisory-only: diagnose and recommend validation/fix plans, but do not edit files.\n" +
+      `Consider ONLY this hypothesis lens:\n${lens.text}\n\n` +
+      `Surface up to ${PER_LENS} root-cause hypotheses. Use category exactly "${lens.category}". ` +
+      "Each hypothesis must include a one-line summary, locations, impact explaining how it produces the symptom, and an optional recommendation for the next validation step. Structured output only.",
+    verifierPrompt: (candidate) =>
+      `## Diagnose verifier\n\n${scopeBlock}\n## Hypothesis\n` +
+      `Location: ${formatLocation(candidate)}\nCategory: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}\n` +
+      `Recommended validation: ${candidate.recommendation ?? "(none supplied)"}\n\n` +
+      "Read relevant files and, when useful, run only safe read-only diagnostic commands from the scoped command list or commands explicitly requested by the user. " +
+      "Do not run mutation, install, commit, network, or destructive commands. Return CONFIRMED, PLAUSIBLE, NOT_SUBSTANTIATED, or REFUTED with evidence. " +
+      "Use NOT_SUBSTANTIATED when evidence is missing; REFUTED requires disproof. Structured output only.",
+  });
+  rawCandidateCount += pipelineResult.rawCandidates;
+  droppedCandidateCount += pipelineResult.dropped;
+  refutedCandidateCount += pipelineResult.refuted;
+  const { coverage } = pipelineResult;
+  const verified = await challengeFindings(api, pipelineResult.verified, scopeBlock, challengeConfig.options, coverage);
+  const surviving = verified.filter((finding) => finding.verdict !== "REFUTED");
+  const refuted = verified.filter((finding) => finding.verdict === "REFUTED");
+  const stats = makeStats(verified.length, surviving.length);
+  publishVerifiedKeptProgress({ progress, log }, verified.length, surviving.length);
+
+  if (surviving.length === 0) {
+    return finishAdvisoryReport(emptyAdvisoryReport(
+      "No root-cause hypothesis survived verification.",
+      ["Capture the exact failing command and error output.", "Rerun diagnose with a narrower symptom or more evidence."],
+      stats,
+    ), coverage, verified);
+  }
+
+  const ranked = [...surviving].sort((a, b) => rank(a) - rank(b));
+  const block = ranked
+    .map(
+      (finding, index) =>
+        `### [${index}] IDs: ${finding.sourceCandidateIds.join(", ")} ${formatLocation(finding)} (${finding.verdict}, ${finding.category})\n` +
+        `${finding.summary}\nImpact: ${finding.impact}\nEvidence: ${formatEvidence(finding.evidence)}\nValidation/fix plan: ${finding.recommendation ?? "(none supplied)"}`,
+    )
+    .join("\n\n");
+  const refutedBlock = refuted
+    .slice(0, 8)
+    .map((finding) => `- ${finding.summary} — REFUTED because ${formatEvidence(finding.evidence)}`)
+    .join("\n");
+
+  const resolved = await synthesizeAdvisoryReport(api,
+    `## Synthesis: final diagnosis report\n\n${ranked.length} hypotheses survived independent verification.\n\n${block}\n\n` +
+      `## Refuted hypotheses for context\n${refutedBlock || "(none recorded)"}\n\n` +
+      "Select confirmed, plausible or explicitly unresolved root causes by ID. " +
+      "Recommendation must be a validation/fix plan, not a patch. nextSteps must be the minimum commands or code inspections needed to confirm the top diagnosis. Structured output only.",
+    ranked, coverage,
+  );
+  return finishAdvisoryReport({ ...resolved, stats: { ...stats, kept: resolved.findings.length } }, coverage, verified);
+}
+
+function rank(finding: AdvisoryVerified): number {
+  if (finding.verdict === "CONFIRMED") return 0;
+  return 1;
+}

package/src/domains/workflows/workflows/perf-review.ts

@@ -0,0 +1,149 @@
+import { challengeFindings, parseChallengeArgs } from "../runtime/advisory-challenge.ts";
+import { Type } from "typebox";
+import {
+  type AdvisoryVerified,
+  type AdvisoryLens,
+  synthesizeAdvisoryReport,
+  finishAdvisoryReport,
+  emptyAdvisoryReport,
+  formatEvidence,
+  formatLocation,
+  publishVerifiedKeptProgress,
+  runLensVerificationPipeline,
+  DEFAULT_ADVISORY_TOOL_HINTS,
+  DEFAULT_ADVISORY_TOOLS,
+} from "../runtime/workflow-advisory-utils.ts";
+import type { WorkflowApi, WorkflowMeta, WorkflowRunStats } from "../runtime/types.ts";
+
+export const meta: WorkflowMeta = {
+  name: "perf-review",
+  description: "Advisory-only performance review: scope slow path → per-lens bottleneck hypotheses → verify evidence → synthesize measurements and safe optimizations.",
+  phases: [{ title: "Scope" }, { title: "Find" }, { title: "Verify" }, { title: "Challenge" }, { title: "Synthesize" }],
+};
+
+const ScopeSchema = Type.Object({
+  target: Type.String({ description: "Verbatim slow path, workload, command, or performance concern." }),
+  files: Type.Array(Type.String(), { description: "Repository-relative files likely involved in the performance path." }),
+  commands: Type.Array(Type.String(), { description: "Existing benchmark, smoke, or measurement commands relevant to this path." }),
+  summary: Type.String({ description: "One-paragraph summary of the performance-relevant path." }),
+  knownMeasurements: Type.Optional(Type.String({ description: "Existing measurements, timings, or explicit lack of measurements." })),
+});
+
+const PERF_LENSES: AdvisoryLens[] = [
+  { label: "algorithmic", category: "algorithmic", text: "Complexity, repeated scans, avoidable nested loops, or data-structure choices that grow poorly with input size." },
+  { label: "io", category: "io", text: "Filesystem, subprocess, network, or other I/O costs on hot paths or startup paths." },
+  { label: "concurrency", category: "concurrency", text: "Unnecessary serialization, missing batching, excessive fan-out, contention, or concurrency limits." },
+  { label: "startup", category: "startup", text: "Import/module loading, initialization, discovery, or cold-start overhead." },
+  { label: "allocation", category: "allocation", text: "Memory churn, large intermediate strings/objects, repeated serialization, or retained state growth." },
+  { label: "measurement", category: "measurement", text: "Missing, misleading, noisy, or insufficient benchmark/measurement design." },
+];
+
+const PER_LENS = 4;
+
+export default async function run(api: WorkflowApi): Promise<unknown> {
+  const { agent, phase, log, progress, args } = api;
+  const challengeConfig = parseChallengeArgs(args);
+  const target = challengeConfig.args.trim() || "repository performance";
+  let fileCount = 0;
+  let rawCandidateCount = 0;
+  let droppedCandidateCount = 0;
+  let refutedCandidateCount = 0;
+  const makeStats = (verified: number, kept: number): WorkflowRunStats => ({
+    files: fileCount,
+    candidates: rawCandidateCount,
+    verified,
+    kept,
+    dropped: droppedCandidateCount,
+    refuted: refutedCandidateCount,
+  });
+
+  phase("Scope");
+  const scope = await agent(
+    "Establish the scope for an advisory-only performance review. Do not edit files.\n" +
+      `Performance target / concern (verbatim): ${target}\n\n` +
+      "Inspect repository structure, scripts, likely hot-path files, and any existing benchmark or measurement commands. " +
+      "Prefer identifying what to measure before claiming bottlenecks. Return files, commands, summary, and known measurements or the lack of them. " +
+      `This workflow will fan out across ${PERF_LENSES.length} lenses with up to ${PER_LENS} candidates per lens. Structured output only.`,
+    { phase: "Scope", label: "scope", tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS, profile: "medium", schema: ScopeSchema },
+  );
+
+  if (!scope || scope.files.length === 0) {
+    return finishAdvisoryReport(emptyAdvisoryReport(
+      "No performance-relevant files were identified.",
+      ["Provide a slow command, workload, file path, or user-visible latency concern to review."],
+      makeStats(0, 0),
+    ), []);
+  }
+
+  fileCount = scope.files.length;
+  progress({ type: "counter", key: "files", label: "files", value: fileCount });
+  progress({ type: "summary", key: "target", value: scope.target });
+  progress({ type: "summary", key: "files", value: scope.files.join(", ") });
+  log(`${scope.files.length} files scoped for performance review`);
+
+  const scopeBlock =
+    `## Target\n${scope.target}\n\n## Files\n${scope.files.map((file) => `- ${file}`).join("\n")}\n\n` +
+    `## Measurement commands\n${scope.commands.map((command) => `- ${command}`).join("\n") || "(none identified)"}\n\n` +
+    `## Summary\n${scope.summary}\n\n## Known measurements\n${scope.knownMeasurements ?? "(none known)"}\n` +
+    (args.trim() ? `\n## User instructions (verbatim)\n${args.trim()}\n` : "");
+
+  const pipelineResult = await runLensVerificationPipeline({
+    api,
+    lenses: PERF_LENSES,
+    perLens: PER_LENS,
+    finderPrompt: (lens) =>
+      `## Perf-review finder — ${lens.label}\n\n${scopeBlock}\n` +
+      "This workflow is advisory-only: identify bottleneck hypotheses, measurement gaps, and safe optimization directions, but do not edit files.\n" +
+      `Investigate ONLY this lens:\n${lens.text}\n\n` +
+      `Surface up to ${PER_LENS} candidates. Use category exactly "${lens.category}". ` +
+      "Each candidate must include a one-line summary, locations, impact stating the suspected performance consequence and workload where it matters, " +
+      "and an optional recommendation. Prefer measurement recommendations when evidence is weak. Structured output only.",
+    verifierPrompt: (candidate) =>
+      `## Perf-review verifier\n\n${scopeBlock}\n## Candidate\n` +
+      `Location: ${formatLocation(candidate)}\nCategory: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}\n` +
+      `Recommendation: ${candidate.recommendation ?? "(none supplied)"}\n\n` +
+      "Read relevant files and package/scripts. Run only safe read-only measurement or inspection commands when useful. " +
+      "Return CONFIRMED, PLAUSIBLE, NOT_SUBSTANTIATED, or REFUTED with evidence from code, scripts, config, or measurement output. " +
+      "Default toward PLAUSIBLE or REFUTED when no measurement exists; do not overstate a bottleneck. Structured output only.",
+  });
+  rawCandidateCount += pipelineResult.rawCandidates;
+  droppedCandidateCount += pipelineResult.dropped;
+  refutedCandidateCount += pipelineResult.refuted;
+  const { coverage } = pipelineResult;
+  const verified = await challengeFindings(api, pipelineResult.verified, scopeBlock, challengeConfig.options, coverage);
+  const surviving = verified.filter((finding) => finding.verdict !== "REFUTED");
+  const stats = makeStats(verified.length, surviving.length);
+  publishVerifiedKeptProgress({ progress, log }, verified.length, surviving.length);
+
+  if (surviving.length === 0) {
+    return finishAdvisoryReport(emptyAdvisoryReport(
+      "No performance finding survived verification.",
+      ["Add or run a focused measurement for the target workload before optimizing.", "Rerun perf-review with benchmark output or a narrower slow path."],
+      stats,
+    ), coverage, verified);
+  }
+
+  const ranked = [...surviving].sort((a, b) => rank(a) - rank(b));
+  const block = ranked
+    .map(
+      (finding, index) =>
+        `### [${index}] IDs: ${finding.sourceCandidateIds.join(", ")} ${formatLocation(finding)} (${finding.verdict}, ${finding.category})\n` +
+        `${finding.summary}\nImpact: ${finding.impact}\nEvidence: ${formatEvidence(finding.evidence)}\nRecommendation: ${finding.recommendation ?? "(none supplied)"}`,
+    )
+    .join("\n\n");
+
+  const resolved = await synthesizeAdvisoryReport(api,
+    `## Synthesis: final perf-review report\n\n${ranked.length} candidates survived independent verification.\n\n${block}\n\n` +
+      "Select findings by ID. " +
+      "Severity is expected performance impact for the target workload. Prefer measurement recommendations before optimization recommendations when evidence is weak. " +
+      "Recommendations must be safe advisory next actions, not patches. Include risky optimizations to avoid in recommendations or nextSteps when relevant. Structured output only.",
+    ranked, coverage,
+  );
+  return finishAdvisoryReport({ ...resolved, stats: { ...stats, kept: resolved.findings.length } }, coverage, verified);
+}
+
+function rank(finding: AdvisoryVerified): number {
+  const verdictRank = finding.verdict === "CONFIRMED" ? 0 : 1;
+  const measurementPenalty = finding.category === "measurement" ? 1 : 0;
+  return verdictRank + measurementPenalty;
+}