pi-workflow-engine 0.10.3 → 0.12.0

package/.pi/extensions/pi-workflow-engine/workflows/code-review.ts

@@ -12,14 +12,17 @@ import {
   formatLocation,
   normalizePath,
   primaryLocation,
+  publishVerifiedKeptProgress,
   recordVerdictProgress,
   verdictConfidence,
   DEFAULT_ADVISORY_TOOL_HINTS,
   DEFAULT_ADVISORY_TOOLS,
 } from "../src/workflow-advisory-utils.ts";
 import { compactResults } from "../src/concurrency.ts";
-import { captureDiff } from "../src/diff-capture.ts";
-import type { ReviewContext } from "../src/review/review-issues.ts";
+import { formatReviewDiffTarget, parseAllowedDiffCommand } from "../src/review-diff-target.ts";
+import { buildCodeReviewScopeBlock, dedupeCodeReviewCandidates } from "../src/review/code-review-orchestration.ts";
+import type { ReviewContext } from "../src/review/review-report.ts";
+import { captureReviewMaterial, type ReviewMaterialCaptureResult } from "../src/review/review-snapshot.ts";
 import type { WorkflowApi, WorkflowMeta, WorkflowRunStats } from "../src/types.ts";
 
 export const meta: WorkflowMeta = {
@@ -61,7 +64,6 @@ const ANGLES: Angle[] = [
 const TOOLS = DEFAULT_ADVISORY_TOOLS;
 const TOOL_HINTS = DEFAULT_ADVISORY_TOOL_HINTS;
 const PER_ANGLE = 6;
-const DIFF_EMBED_CAP = 60_000;
 
 /** 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>> {
@@ -95,7 +97,15 @@ export function inDiff(changed: Map<string, Set<number>>, file: string, line?: n
   return set.has(line) || set.has(line - 1) || set.has(line + 1);
 }
 
-export default async function run(api: WorkflowApi): Promise<unknown> {
+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, parallel, phase, log, progress, args, cwd, signal } = api;
   const target = args.trim();
   let fileCount = 0;
@@ -116,6 +126,7 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       (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`. " +
@@ -127,7 +138,7 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       "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: TOOLS, toolHints: TOOL_HINTS, thinkingLevel: "medium", schema: ScopeSchema },
+    { phase: "Scope", label: "scope", tools: TOOLS, toolHints: TOOL_HINTS, profile: "medium", schema: ScopeSchema },
   );
 
   if (!scope) {
@@ -136,56 +147,51 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
 
   fileCount = scope.files.length;
   progress({ type: "summary", key: "files", value: scope.files.join(", ") || "(none)" });
-  progress({ type: "summary", key: "diffCommand", value: scope.diffCommand });
+  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,
-    diffCommand: scope.diffCommand,
+    diffTarget,
     files: scope.files,
     summary: scope.summary,
+    ...(reviewMaterial.snapshot.status === "verified"
+      ? { snapshot: reviewMaterial.snapshot.identity }
+      : {}),
   };
 
-  log(`${scope.files.length} changed files`);
-
-  // Capture the diff once, deterministically, so findings can be bounded to changed lines in code.
-  let changed: Map<string, Set<number>> | null = null;
-  let diffText = "";
-  const capturedDiff = await captureDiff(scope.diffCommand, { cwd, signal, timeoutMs: 30_000, maxBufferBytes: 16 << 20 });
-  if (capturedDiff.ok) {
-    diffText = capturedDiff.stdout;
-    changed = changedLines(diffText);
-    progress({ type: "summary", key: "diffBytes", value: capturedDiff.bytes });
-  } else {
-    log(`diff capture failed (${capturedDiff.error ?? "unknown error"}) — reviewing without the line gate`);
-  }
-
-  const diffBlock = diffText
-    ? `\n## Diff (review is bounded to these changed lines)\n\`\`\`diff\n${
-        diffText.length > DIFF_EMBED_CAP
-          ? `${diffText.slice(0, DIFF_EMBED_CAP)}\n... (truncated — run \`${scope.diffCommand}\` for the full diff)`
-          : diffText
-      }\n\`\`\`\n`
-    : "";
-
-  const scopeBlock =
-    `## Diff command\n${scope.diffCommand}\n\n## Changed files\n${scope.files.map((file) => `- ${file}`).join("\n")}\n\n` +
-    `## Summary\n${scope.summary}\n\n## Conventions\n${scope.conventions ?? "(none noted)"}\n` +
-    diffBlock +
-    (target ? `\n## User instructions (verbatim)\n${target}\n` : "");
-
-  // Dedup after all finders complete so verifier agents cannot consume the global cap before full candidate discovery.
-  const seen = new Set<string>();
-  const dedupKey = (candidate: Candidate): string => {
-    const location = primaryLocation(candidate);
-    const lineKey = location.line != null ? Math.round(location.line / 5) * 5 : candidate.summary.slice(0, 40).toLowerCase();
-    return `${normalizePath(location.file)}:${lineKey}`;
-  };
+  const scopeBlock = buildCodeReviewScopeBlock({
+    diffCommand,
+    files: scope.files,
+    summary: scope.summary,
+    conventions: scope.conventions,
+    diffText,
+    target,
+  });
 
   // ─── Find barrier → dedup → Verify ───
   phase("Find");
@@ -199,19 +205,16 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
           `Surface up to ${PER_ANGLE} candidates. Use category exactly "${angle.kind}". 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.",
-        { phase: "Find", label: `find:${angle.label}`, tools: TOOLS, toolHints: TOOL_HINTS, thinkingLevel: "low", schema: AdvisoryCandidatesSchema },
+        { phase: "Find", label: `find:${angle.label}`, tools: TOOLS, toolHints: TOOL_HINTS, profile: "small", schema: AdvisoryCandidatesSchema },
       );
       const raw = (found?.candidates ?? []).slice(0, PER_ANGLE);
       rawCandidateCount += raw.length;
       progress({ type: "counter_delta", key: "candidates", label: "candidates", delta: raw.length });
-      const gate = changed;
-      const bounded = gate ? raw.filter((candidate) => inDiff(gate, primaryLocation(candidate).file, primaryLocation(candidate).line)) : raw;
+      const bounded = raw.filter((candidate) => inDiff(changed, primaryLocation(candidate).file, primaryLocation(candidate).line));
       const dropped = raw.length - bounded.length;
       if (dropped > 0) {
         droppedCandidateCount += dropped;
         progress({ type: "counter_delta", key: "dropped", label: "dropped", delta: dropped });
-      }
-      if (gate && dropped > 0) {
         log(`find:${angle.label}: dropped ${dropped} out-of-diff candidate(s)`);
       }
       for (const candidate of bounded) {
@@ -228,16 +231,8 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
     }),
   );
 
-  const novel = compactResults(perAngle).flatMap(({ angle, candidates }) =>
-    candidates
-      .filter((candidate) => {
-        const key = dedupKey(candidate);
-        if (seen.has(key)) return false;
-        seen.add(key);
-        return true;
-      })
-      .map((candidate) => ({ angle, candidate })),
-  );
+  // Dedup after all finders complete so verifier agents cannot consume the global cap before full candidate discovery.
+  const novel = dedupeCodeReviewCandidates(compactResults(perAngle));
 
   phase("Verify");
   const verdicts = await parallel(
@@ -254,7 +249,7 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
           label: `verify:${location.file.split("/").pop() ?? location.file}`,
           tools: TOOLS,
           toolHints: TOOL_HINTS,
-          thinkingLevel: "low",
+          profile: "small",
           schema: AdvisoryVerdictSchema,
         },
       );
@@ -267,11 +262,7 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
   const verified = compactResults(verdicts);
   const surviving = verified.filter((finding) => finding.verdict !== "REFUTED");
   const stats = makeStats(verified.length, surviving.length);
-  progress({ type: "counter", key: "verified", label: "verified", value: verified.length });
-  progress({ type: "counter", key: "kept", label: "kept", value: surviving.length });
-  progress({ type: "summary", key: "verified", value: verified.length });
-  progress({ type: "summary", key: "kept", value: surviving.length });
-  log(`${verified.length} verified → ${surviving.length} kept`);
+  publishVerifiedKeptProgress({ progress, log }, verified.length, surviving.length);
 
   if (surviving.length === 0) {
     return { summary: "No findings survived verification.", findings: [], nextSteps: ["No code-review action is recommended from this workflow run."], stats, reviewContext };
@@ -295,7 +286,14 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       "Merge findings with the same root cause, rank most-severe first (correctness bugs above cleanups), and produce the final advisory report. " +
       "Return summary, findings, and nextSteps. For each finding: category must be bug or cleanup; severity is impact level (low/medium/high), not category; " +
       "confidence must be high for CONFIRMED and medium for PLAUSIBLE; copy locations and evidence arrays from the verified finding; impact is the concrete failure or maintenance scenario; recommendation is an advisory fix direction, not an edit. Structured output only.",
-    { phase: "Synthesize", label: "synthesize", thinkingLevel: "medium", schema: AdvisoryReportSchema },
+    {
+      phase: "Synthesize",
+      label: "synthesize",
+      tools: [],
+      profile: "medium",
+      resume: "read-only",
+      schema: AdvisoryReportSchema,
+    },
   );
 
   if (!report) return { summary: "Synthesis produced no output.", findings: [], nextSteps: ["Re-run the workflow or inspect verifier evidence manually."], stats, reviewContext };

package/.pi/extensions/pi-workflow-engine/workflows/diagnose.ts

@@ -4,15 +4,16 @@ import {
   AdvisoryReportSchema,
   AdvisoryVerdictSchema,
   type AdvisoryCandidate,
-  type AdvisoryReport,
   type AdvisoryVerdict,
 } from "../src/advisory-schema.ts";
 import {
   advisoryDedupKey as dedupKey,
   backfillAdvisoryFindings,
+  emptyAdvisoryReport,
   formatEvidence,
   formatLocation,
   primaryLocation,
+  publishVerifiedKeptProgress,
   recordVerdictProgress,
   DEFAULT_ADVISORY_TOOL_HINTS,
   DEFAULT_ADVISORY_TOOLS,
@@ -89,11 +90,11 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       "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: TOOLS, toolHints: TOOL_HINTS, thinkingLevel: "medium", schema: ScopeSchema },
+    { phase: "Scope", label: "scope", tools: TOOLS, toolHints: TOOL_HINTS, profile: "medium", schema: ScopeSchema },
   );
 
   if (!scope) {
-    return emptyReport(
+    return emptyAdvisoryReport(
       "Diagnosis could not establish a scope.",
       ["Provide the failing command, error message, or regression description and rerun diagnose."],
       makeStats(0, 0),
@@ -121,7 +122,7 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
           `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.",
-        { phase: "Hypothesize", label: `hypothesize:${lens.label}`, tools: TOOLS, toolHints: TOOL_HINTS, thinkingLevel: "low", schema: AdvisoryCandidatesSchema },
+        { phase: "Hypothesize", label: `hypothesize:${lens.label}`, tools: TOOLS, toolHints: TOOL_HINTS, profile: "small", schema: AdvisoryCandidatesSchema },
       );
       const candidates = (found?.candidates ?? []).slice(0, PER_LENS).map((candidate) => ({ ...candidate, lens }));
       rawCandidateCount += candidates.length;
@@ -162,7 +163,7 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
             label: `verify:${location.file.split("/").pop() ?? location.file}`,
             tools: TOOLS,
             toolHints: TOOL_HINTS,
-            thinkingLevel: "low",
+            profile: "small",
             schema: AdvisoryVerdictSchema,
           },
         );
@@ -178,14 +179,10 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
   const surviving = verified.filter((finding) => finding.verdict !== "REFUTED");
   const refuted = verified.filter((finding) => finding.verdict === "REFUTED");
   const stats = makeStats(verified.length, surviving.length);
-  progress({ type: "counter", key: "verified", label: "verified", value: verified.length });
-  progress({ type: "counter", key: "kept", label: "kept", value: surviving.length });
-  progress({ type: "summary", key: "verified", value: verified.length });
-  progress({ type: "summary", key: "kept", value: surviving.length });
-  log(`${verified.length} verified → ${surviving.length} kept`);
+  publishVerifiedKeptProgress({ progress, log }, verified.length, surviving.length);
 
   if (surviving.length === 0) {
-    return emptyReport(
+    return 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,
@@ -212,10 +209,17 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       "Produce the shared advisory report shape. Only include confirmed or plausible root causes in findings. " +
       "Use categories such as root-cause, regression, configuration, dependency, or test-fixture. " +
       "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.",
-    { phase: "Synthesize", label: "synthesize", thinkingLevel: "medium", schema: AdvisoryReportSchema },
+    {
+      phase: "Synthesize",
+      label: "synthesize",
+      tools: [],
+      profile: "medium",
+      resume: "read-only",
+      schema: AdvisoryReportSchema,
+    },
   );
 
-  if (!report) return emptyReport("Synthesis produced no output.", ["Inspect verifier evidence manually or rerun diagnose with a narrower symptom."], stats);
+  if (!report) return emptyAdvisoryReport("Synthesis produced no output.", ["Inspect verifier evidence manually or rerun diagnose with a narrower symptom."], stats);
 
   const findings = backfillAdvisoryFindings(report.findings, ranked, {
     impact: "Impact not restated by synthesis.",
@@ -224,10 +228,6 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
   return { ...report, findings, stats };
 }
 
-function emptyReport(summary: string, nextSteps: string[], stats: WorkflowRunStats): AdvisoryReport & { stats: WorkflowRunStats } {
-  return { summary, findings: [], nextSteps, stats };
-}
-
 function dedupe(candidates: Hypothesis[], onDropped: (dropped: number) => void): Hypothesis[] {
   const seen = new Set<string>();
   const novel: Hypothesis[] = [];

package/.pi/extensions/pi-workflow-engine/workflows/perf-review.ts

@@ -2,13 +2,14 @@ import { Type } from "typebox";
 import {
   AdvisoryReportSchema,
   type AdvisoryCandidate,
-  type AdvisoryReport,
   type AdvisoryVerdict,
 } from "../src/advisory-schema.ts";
 import {
   backfillAdvisoryFindings,
+  emptyAdvisoryReport,
   formatEvidence,
   formatLocation,
+  publishVerifiedKeptProgress,
   runLensVerificationPipeline,
   DEFAULT_ADVISORY_TOOL_HINTS,
   DEFAULT_ADVISORY_TOOLS,
@@ -80,11 +81,11 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       "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: TOOLS, toolHints: TOOL_HINTS, thinkingLevel: "medium", schema: ScopeSchema },
+    { phase: "Scope", label: "scope", tools: TOOLS, toolHints: TOOL_HINTS, profile: "medium", schema: ScopeSchema },
   );
 
   if (!scope || scope.files.length === 0) {
-    return emptyReport(
+    return emptyAdvisoryReport(
       "No performance-relevant files were identified.",
       ["Provide a slow command, workload, file path, or user-visible latency concern to review."],
       makeStats(0, 0),
@@ -139,14 +140,10 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
   const verified = pipelineResult.verified;
   const surviving = verified.filter((finding) => finding.verdict !== "REFUTED");
   const stats = makeStats(verified.length, surviving.length);
-  progress({ type: "counter", key: "verified", label: "verified", value: verified.length });
-  progress({ type: "counter", key: "kept", label: "kept", value: surviving.length });
-  progress({ type: "summary", key: "verified", value: verified.length });
-  progress({ type: "summary", key: "kept", value: surviving.length });
-  log(`${verified.length} verified → ${surviving.length} kept`);
+  publishVerifiedKeptProgress({ progress, log }, verified.length, surviving.length);
 
   if (surviving.length === 0) {
-    return emptyReport(
+    return 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,
@@ -168,10 +165,17 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       "Produce the shared advisory report shape. Categories should be algorithmic, io, concurrency, startup, allocation, or measurement when applicable. " +
       "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.",
-    { phase: "Synthesize", label: "synthesize", thinkingLevel: "medium", schema: AdvisoryReportSchema },
+    {
+      phase: "Synthesize",
+      label: "synthesize",
+      tools: [],
+      profile: "medium",
+      resume: "read-only",
+      schema: AdvisoryReportSchema,
+    },
   );
 
-  if (!report) return emptyReport("Synthesis produced no output.", ["Inspect verifier evidence manually or rerun perf-review with a narrower target."], stats);
+  if (!report) return emptyAdvisoryReport("Synthesis produced no output.", ["Inspect verifier evidence manually or rerun perf-review with a narrower target."], stats);
 
   const findings = backfillAdvisoryFindings(report.findings, ranked, {
     impact: "Performance impact not restated by synthesis.",
@@ -180,13 +184,8 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
   return { ...report, findings, stats };
 }
 
-function emptyReport(summary: string, nextSteps: string[], stats: WorkflowRunStats): AdvisoryReport & { stats: WorkflowRunStats } {
-  return { summary, findings: [], nextSteps, stats };
-}
-
 function rank(finding: Verified): number {
   const verdictRank = finding.verdict === "CONFIRMED" ? 0 : 1;
   const measurementPenalty = finding.category === "measurement" ? 1 : 0;
   return verdictRank + measurementPenalty;
 }
-

package/.pi/extensions/pi-workflow-engine/workflows/refactor-scout.ts

@@ -2,13 +2,14 @@ import { Type } from "typebox";
 import {
   AdvisoryReportSchema,
   type AdvisoryCandidate,
-  type AdvisoryReport,
   type AdvisoryVerdict,
 } from "../src/advisory-schema.ts";
 import {
   backfillAdvisoryFindings,
+  emptyAdvisoryReport,
   formatEvidence,
   formatLocation,
+  publishVerifiedKeptProgress,
   runLensVerificationPipeline,
   DEFAULT_ADVISORY_TOOL_HINTS,
   DEFAULT_ADVISORY_TOOLS,
@@ -79,11 +80,11 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       "Inspect repository structure, the target path or module, and relevant AGENTS.md / project docs conventions. " +
       "Return the concrete files that should be considered, a short summary, and any conventions that affect refactor advice. " +
       `This workflow will fan out across ${REFACTOR_LENSES.length} lenses with up to ${PER_LENS} candidates per lens. Structured output only.`,
-    { phase: "Scope", label: "scope", tools: TOOLS, toolHints: TOOL_HINTS, thinkingLevel: "medium", schema: ScopeSchema },
+    { phase: "Scope", label: "scope", tools: TOOLS, toolHints: TOOL_HINTS, profile: "medium", schema: ScopeSchema },
   );
 
   if (!scope || scope.files.length === 0) {
-    return emptyReport(
+    return emptyAdvisoryReport(
       "No files were identified for refactor scouting.",
       ["Provide a target path, module, or subsystem to scout for refactor opportunities."],
       makeStats(0, 0),
@@ -136,14 +137,10 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
   const verified = pipelineResult.verified;
   const surviving = verified.filter((finding) => finding.verdict !== "REFUTED");
   const stats = makeStats(verified.length, surviving.length);
-  progress({ type: "counter", key: "verified", label: "verified", value: verified.length });
-  progress({ type: "counter", key: "kept", label: "kept", value: surviving.length });
-  progress({ type: "summary", key: "verified", value: verified.length });
-  progress({ type: "summary", key: "kept", value: surviving.length });
-  log(`${verified.length} verified → ${surviving.length} kept`);
+  publishVerifiedKeptProgress({ progress, log }, verified.length, surviving.length);
 
   if (surviving.length === 0) {
-    return emptyReport("No refactor opportunities survived verification.", ["Leave the scoped code unchanged unless a human reviewer has additional context."], stats);
+    return emptyAdvisoryReport("No refactor opportunities survived verification.", ["Leave the scoped code unchanged unless a human reviewer has additional context."], stats);
   }
 
   phase("Synthesize");
@@ -162,10 +159,17 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       "Return the shared advisory report shape. Categories should come from the verified candidates. " +
       "Severity is maintenance or future-correctness impact. Confidence is high for CONFIRMED, medium for PLAUSIBLE unless verifier confidence says otherwise. " +
       "Recommendations must be safe first refactor steps, not rewrites. Include concrete nextSteps for the host developer. Structured output only.",
-    { phase: "Synthesize", label: "synthesize", thinkingLevel: "medium", schema: AdvisoryReportSchema },
+    {
+      phase: "Synthesize",
+      label: "synthesize",
+      tools: [],
+      profile: "medium",
+      resume: "read-only",
+      schema: AdvisoryReportSchema,
+    },
   );
 
-  if (!report) return emptyReport("Synthesis produced no output.", ["Inspect verifier evidence manually or rerun the workflow with a narrower target."], stats);
+  if (!report) return emptyAdvisoryReport("Synthesis produced no output.", ["Inspect verifier evidence manually or rerun the workflow with a narrower target."], stats);
 
   const findings = backfillAdvisoryFindings(report.findings, ranked, {
     impact: "Impact not restated by synthesis.",
@@ -174,10 +178,6 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
   return { ...report, findings, stats };
 }
 
-function emptyReport(summary: string, nextSteps: string[], stats: WorkflowRunStats): AdvisoryReport & { stats: WorkflowRunStats } {
-  return { summary, findings: [], nextSteps, stats };
-}
-
 function rank(finding: Verified): number {
   const verdictRank = finding.verdict === "CONFIRMED" ? 0 : 1;
   const categoryRank = finding.category === "dead-code" || finding.category === "conventions" ? 2 : 0;

package/.pi/extensions/pi-workflow-engine/workflows/research.ts

@@ -0,0 +1,170 @@
+import { compactResults } from "../src/concurrency.ts";
+import {
+  MAX_RESEARCH_LANES,
+  ResearchLaneResultSchema,
+  ResearchPlanSchema,
+  ResearchReportSchema,
+  ResearchVerificationSchema,
+  type ResearchClaimCandidate,
+  type ResearchReport,
+  type ResearchVerification,
+} from "../src/research-contract.ts";
+import {
+  buildClaimCandidates,
+  fallbackResearchReport,
+  normalizeResearchLanes,
+  sanitizeLaneResults,
+  sanitizeResearchReport,
+  sanitizeVerification,
+  unavailableResearchReport,
+  unavailableVerification,
+} from "../src/research-evidence.ts";
+import { WorkflowToolHintUnavailableError } from "../src/tool-capabilities.ts";
+import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
+
+export const meta: WorkflowMeta = {
+  name: "research",
+  description: "Source-grounded external research: decompose → gather direct-page evidence → independently verify claims → cited synthesis.",
+  phases: [{ title: "Plan" }, { title: "Gather" }, { title: "Verify" }, { title: "Synthesize" }],
+};
+
+const EXTERNAL_TOOLS: string[] = [];
+const EXTERNAL_TOOL_HINTS = ["external-search"] as const;
+
+export default async function run(api: WorkflowApi): Promise<ResearchReport> {
+  const { agent, parallel, phase, log, progress, args } = api;
+  const question = args.trim();
+  if (!question) return unavailableResearchReport("empty-question");
+
+  phase("Plan");
+  let plan;
+  try {
+    plan = await agent(
+      `Plan bounded, source-grounded research for the user's question and any scope constraints embedded in it.\n\n` +
+        `Question and constraints (verbatim):\n${question}\n\n` +
+        `Create at most ${MAX_RESEARCH_LANES} non-overlapping lanes. Each lane needs a stable short id, title, objective, and 1-4 concrete search queries. ` +
+        "Separate primary-source discovery, current status, counterevidence, or jurisdiction/timeframe only when relevant. " +
+        "Do not claim exhaustive coverage. Structured output only.",
+      {
+        phase: "Plan",
+        label: "plan",
+        tools: EXTERNAL_TOOLS,
+        toolHints: EXTERNAL_TOOL_HINTS,
+        requireToolHints: true,
+        profile: "medium",
+        resume: "off",
+        schema: ResearchPlanSchema,
+      },
+    );
+  } catch (error) {
+    if (error instanceof WorkflowToolHintUnavailableError) return unavailableResearchReport("missing-capability");
+    throw error;
+  }
+
+  if (!plan) return unavailableResearchReport("no-evidence");
+  const lanes = normalizeResearchLanes(plan);
+  if (lanes.length === 0) return unavailableResearchReport("no-evidence");
+  progress({ type: "counter", key: "research.lanes", label: "research lanes", value: lanes.length });
+  progress({ type: "summary", key: "research.question", value: question });
+
+  phase("Gather");
+  const gathered = compactResults(
+    await parallel(
+      lanes.map((lane) => async () => {
+        const result = await agent(
+          `Research one bounded lane using only installed external web-search, browsing, or URL-extraction tools.\n\n` +
+            `Question: ${question}\n` +
+            `Scope constraints: ${plan.scopeConstraints.join("; ") || "(none)"}\n` +
+            `Lane id: ${lane.id}\nLane: ${lane.title}\nObjective: ${lane.objective}\n` +
+            `Queries:\n${lane.queries.map((query) => `- ${query}`).join("\n")}\n\n` +
+            "Open the supporting pages instead of citing a search-results page. Prefer primary and authoritative sources; use independent sources when useful. " +
+            "Return concrete claims with importance, whether each page supports or conflicts with the claim, a short passage or precise paraphrase, and the exact page title and URL. " +
+            "State evidence gaps. Never invent a URL or claim that the opened page does not support. Structured output only.",
+          {
+            phase: "Gather",
+            label: `gather:${lane.id}`,
+            tools: EXTERNAL_TOOLS,
+            toolHints: EXTERNAL_TOOL_HINTS,
+            requireToolHints: true,
+            profile: "small",
+            resume: "off",
+            schema: ResearchLaneResultSchema,
+          },
+        );
+        if (!result) return null;
+        progress({ type: "counter_delta", key: "research.evidence", label: "evidence items", delta: result.evidence.length });
+        progress({
+          type: "lane_item",
+          lane: "Research lanes",
+          title: lane.title,
+          subtitle: `${result.evidence.length} evidence item(s)`,
+          status: result.evidence.length > 0 ? "success" : "warning",
+          details: result.gaps.join("; ") || lane.objective,
+        });
+        return result;
+      }),
+    ),
+  );
+
+  const laneResults = sanitizeLaneResults(gathered);
+  const candidates = buildClaimCandidates(laneResults);
+  if (candidates.length === 0) return unavailableResearchReport("no-evidence");
+  progress({ type: "counter", key: "research.claims", label: "claims to verify", value: candidates.length });
+  log(`${candidates.length} bounded claim(s) selected for independent verification`);
+
+  phase("Verify");
+  const verificationResults = await parallel(
+    candidates.map((candidate, index) => async () => {
+      const result = await agent(verificationPrompt(question, candidate), {
+        phase: "Verify",
+        label: `verify:${index + 1}`,
+        tools: EXTERNAL_TOOLS,
+        toolHints: EXTERNAL_TOOL_HINTS,
+        requireToolHints: true,
+        profile: "medium",
+        resume: "off",
+        schema: ResearchVerificationSchema,
+      });
+      return result ? sanitizeVerification(result, candidate) : null;
+    }),
+  );
+  const verifications = verificationResults.map((result, index) => result ?? unavailableVerification(candidates[index]!));
+  for (const verification of verifications) {
+    progress({ type: "counter_delta", key: `research.${verification.verdict.toLowerCase()}`, label: verification.verdict.toLowerCase(), delta: 1 });
+  }
+  const synthesisInputs = verifications.filter((verification) => verification.verdict !== "REJECTED");
+
+  phase("Synthesize");
+  const synthesis = await agent(
+    `Answer the research question using only the independently verified handoff below.\n\n` +
+      `Question: ${question}\nScope constraints: ${plan.scopeConstraints.join("; ") || "(none)"}\n\n` +
+      `Verified claims JSON:\n${JSON.stringify(synthesisInputs)}\n\n` +
+      "Keep SUPPORTED claims, CONFLICTED evidence, UNCERTAIN claims, and model INFERENCE in their separate fields. Exclude REJECTED claims. " +
+      "Copy each verified claim string exactly so its citations remain bound to that claim during validation. " +
+      "Every supported or conflicting claim must cite exact title/URL objects from its verification; do not add URLs, cite search-results pages, or turn inference into fact. " +
+      "Answer concisely, disclose limited coverage, and provide useful next steps. Structured output only.",
+    {
+      phase: "Synthesize",
+      label: "synthesize",
+      tools: [],
+      profile: "medium",
+      resume: "off",
+      schema: ResearchReportSchema,
+    },
+  );
+
+  return sanitizeResearchReport(
+    synthesis ?? fallbackResearchReport(synthesisInputs, "The model did not return a structured synthesis."),
+    synthesisInputs,
+  );
+}
+
+function verificationPrompt(question: string, candidate: ResearchClaimCandidate): string {
+  return `Independently verify one important research claim using installed external web-search, browsing, or URL-extraction tools.\n\n` +
+    `Question: ${question}\nClaim: ${candidate.claim}\nImportance: ${candidate.importance}\n\n` +
+    `Gather-stage evidence (context only; do not treat it as verified):\n${JSON.stringify(candidate.evidence)}\n\n` +
+    "Search independently and open direct supporting pages. Prefer primary/authoritative sources and actively look for credible counterevidence. " +
+    "Return SUPPORTED only when direct pages substantiate the claim, CONFLICTED when credible sources disagree, UNCERTAIN when evidence is insufficient, " +
+    "INFERENCE when the conclusion is reasoned rather than directly stated, or REJECTED when evidence refutes it. " +
+    "Include exact page titles and direct HTTP(S) URLs, never search-results URLs. Structured output only.";
+}