pi-workflow-engine 0.2.0 → 0.4.0

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

@@ -1,5 +1,21 @@
-import { execSync } from "node:child_process";
 import { Type } from "typebox";
+import {
+  AdvisoryCandidatesSchema,
+  AdvisoryReportSchema,
+  AdvisoryVerdictSchema,
+  type AdvisoryCandidate,
+  type AdvisoryVerdict,
+} from "../src/advisory-schema.ts";
+import {
+  backfillAdvisoryFindings,
+  formatEvidence,
+  formatLocation,
+  normalizePath,
+  primaryLocation,
+  recordVerdictProgress,
+  verdictConfidence,
+} from "../src/workflow-advisory-utils.ts";
+import { captureDiff } from "../src/diff-capture.ts";
 import type { WorkflowApi, WorkflowMeta, WorkflowRunStats } from "../src/types.ts";
 
 export const meta: WorkflowMeta = {
@@ -13,54 +29,19 @@ 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 CLAUDE.md / project conventions" })),
+  conventions: Type.Optional(Type.String({ description: "Relevant AGENTS.md / project conventions" })),
 });
 
-const CandidatesSchema = Type.Object({
-  candidates: Type.Array(
-    Type.Object({
-      file: Type.String(),
-      line: Type.Optional(Type.Number()),
-      summary: Type.String({ description: "One-line description of the issue" }),
-      failure_scenario: Type.String({ description: "Concrete scenario where this causes a problem" }),
-    }),
-  ),
-});
-
-const VerdictSchema = Type.Object({
-  verdict: Type.Union([Type.Literal("CONFIRMED"), Type.Literal("PLAUSIBLE"), Type.Literal("REFUTED")]),
-  evidence: Type.String({ description: "Quote or cite the relevant line(s)" }),
-});
-
-const ReportSchema = Type.Object({
-  summary: Type.String(),
-  findings: Type.Array(
-    Type.Object({
-      file: Type.String(),
-      line: Type.Optional(Type.Number()),
-      severity: Type.Union([Type.Literal("bug"), Type.Literal("cleanup")]),
-      verdict: Type.Union([Type.Literal("CONFIRMED"), Type.Literal("PLAUSIBLE")]),
-      summary: Type.String(),
-      evidence: Type.Optional(Type.String()),
-      failure_scenario: Type.Optional(Type.String()),
-    }),
-  ),
-});
+type Candidate = AdvisoryCandidate;
 
-interface Candidate {
-  file: string;
-  line?: number;
-  summary: string;
-  failure_scenario: string;
-}
 interface Angle {
   label: string;
   kind: "bug" | "cleanup";
   text: string;
 }
 interface Verified extends Candidate {
-  verdict: "CONFIRMED" | "PLAUSIBLE" | "REFUTED";
-  evidence: string;
+  verdict: AdvisoryVerdict["verdict"];
+  evidence: string[];
   kind: "bug" | "cleanup";
 }
 
@@ -77,11 +58,6 @@ const TOOLS = ["read", "bash"];
 const PER_ANGLE = 6;
 const DIFF_EMBED_CAP = 60_000;
 
-/** Strip leading "./", "a/", "b/" so diff paths and finder-reported paths compare equal. */
-export function normalizePath(path: string): string {
-  return path.replace(/^\.\//, "").replace(/^[ab]\//, "");
-}
-
 /** 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>>();
@@ -115,7 +91,7 @@ export function inDiff(changed: Map<string, Set<number>>, file: string, line?: n
 }
 
 export default async function run(api: WorkflowApi): Promise<unknown> {
-  const { agent, parallel, pipeline, phase, log, progress, args, cwd } = api;
+  const { agent, parallel, phase, log, progress, args, cwd, signal } = api;
   const target = args.trim();
   let fileCount = 0;
   let rawCandidateCount = 0;
@@ -144,13 +120,13 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       "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 CLAUDE.md noting conventions a reviewer should know.\n" +
+      "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, thinkingLevel: "medium", schema: ScopeSchema },
   );
 
   if (!scope) {
-    return { summary: "No changes found to review.", findings: [], stats: makeStats(0, 0) };
+    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;
@@ -159,22 +135,20 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
   progress({ type: "counter", key: "files", label: "files", value: fileCount });
 
   if (scope.files.length === 0) {
-    return { summary: "No changes found to review.", findings: [], stats: makeStats(0, 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.
   let changed: Map<string, Set<number>> | null = null;
   let diffText = "";
-  if (/^(git diff|gh pr diff)\b/.test(scope.diffCommand)) {
-    try {
-      diffText = execSync(scope.diffCommand, { cwd, encoding: "utf8", maxBuffer: 16 << 20 });
-      changed = changedLines(diffText);
-    } catch (error) {
-      log(`diff capture failed (${error instanceof Error ? error.message : String(error)}) — reviewing without the line gate`);
-    }
+  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("diffCommand not in the git/gh allowlist — reviewing without the line gate");
+    log(`diff capture failed (${capturedDiff.error ?? "unknown error"}) — reviewing without the line gate`);
   }
 
   const diffBlock = diffText
@@ -191,32 +165,33 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
     diffBlock +
     (target ? `\n## User instructions (verbatim)\n${target}\n` : "");
 
-  // Dedup state accumulates as finders complete (the pipeline has no barrier).
+  // 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 =>
-    `${candidate.file}:${candidate.line != null ? Math.round(candidate.line / 5) * 5 : candidate.summary.slice(0, 40).toLowerCase()}`;
+  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}`;
+  };
 
-  // ─── Find → dedup → Verify (no barrier between stages) ───
+  // ─── Find barrier → dedup → Verify ───
   phase("Find");
-  const perAngle = await pipeline(
-    ANGLES,
-    // Stage 1: each angle finds candidates through its single lens.
-    async (_prev, item) => {
-      const angle = item as Angle;
+  const perAngle = await parallel(
+    ANGLES.map((angle) => async () => {
       const found = await agent(
         `## Code-review finder — ${angle.label}\n\n${scopeBlock}\n` +
           `Review the change through ONLY this lens:\n${angle.text}\n` +
           "Only flag issues on lines that are part of the diff above (run the diff command if it is not shown). " +
           "You may read surrounding files for context, but never report issues in unchanged code. " +
-          `Surface up to ${PER_ANGLE} candidates, each with file, a line that appears in the diff, a one-line summary, and a concrete failure_scenario. ` +
-          "Pass through anything with a nameable failure scenario — a separate verifier judges them next. Structured output only.",
-        { phase: "Find", label: `find:${angle.label}`, tools: TOOLS, thinkingLevel: "low", schema: CandidatesSchema },
+          `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, thinkingLevel: "low", 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, candidate.file, candidate.line)) : raw;
+      const bounded = gate ? raw.filter((candidate) => inDiff(gate, primaryLocation(candidate).file, primaryLocation(candidate).line)) : raw;
       const dropped = raw.length - bounded.length;
       if (dropped > 0) {
         droppedCandidateCount += dropped;
@@ -232,48 +207,49 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
           title: candidate.summary,
           subtitle: formatLocation(candidate),
           status: "pending",
-          details: candidate.failure_scenario,
+          details: candidate.impact,
         });
       }
       return { angle, candidates: bounded };
-    },
-    // Stage 2: dedup against the shared set, then verify survivors concurrently.
-    async (prev) => {
-      const { angle, candidates } = prev as { angle: Angle; candidates: Candidate[] };
-      const novel = candidates.filter((candidate) => {
+    }),
+  );
+
+  const novel = perAngle.flatMap(({ angle, candidates }) =>
+    candidates
+      .filter((candidate) => {
         const key = dedupKey(candidate);
         if (seen.has(key)) return false;
         seen.add(key);
         return true;
-      });
-      const verdicts = await parallel(
-        novel.map((candidate) => async (): Promise<Verified | null> => {
-          const judged = await agent(
-            `## Code-review verifier\n\n${scopeBlock}\n## Candidate\n` +
-              `File: ${candidate.file}${candidate.line != null ? `:${candidate.line}` : ""}\n` +
-              `Summary: ${candidate.summary}\nFailure scenario: ${candidate.failure_scenario}\n\n` +
-              "Run the diff command, read the relevant file(s), and return exactly one verdict (CONFIRMED / PLAUSIBLE / REFUTED) " +
-              "with evidence quoting the line(s). Default toward REFUTED if you cannot substantiate it. Structured output only.",
-            { phase: "Verify", label: `verify:${candidate.file.split("/").pop() ?? candidate.file}`, tools: TOOLS, thinkingLevel: "low", schema: VerdictSchema },
-          );
-          if (!judged) return null;
-          progress({ type: "counter_delta", key: `verdict.${judged.verdict.toLowerCase()}`, label: judged.verdict, delta: 1 });
-          progress({
-            type: "lane_item",
-            lane: verdictLane(judged.verdict),
-            title: candidate.summary,
-            subtitle: formatLocation(candidate),
-            status: verdictStatus(judged.verdict),
-            details: judged.evidence,
-          });
-          return { ...candidate, verdict: judged.verdict, evidence: judged.evidence, kind: angle.kind };
-        }),
+      })
+      .map((candidate) => ({ angle, candidate })),
+  );
+
+  phase("Verify");
+  const verdicts = await parallel(
+    novel.map(({ angle, candidate }) => async (): Promise<Verified | null> => {
+      const location = primaryLocation(candidate);
+      const judged = await agent(
+        `## 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 / REFUTED) " +
+          "with evidence quoting the line(s). Default toward REFUTED if you cannot substantiate it. Structured output only.",
+        {
+          phase: "Verify",
+          label: `verify:${location.file.split("/").pop() ?? location.file}`,
+          tools: TOOLS,
+          thinkingLevel: "low",
+          schema: AdvisoryVerdictSchema,
+        },
       );
-      return verdicts.filter((value): value is Verified => value !== null);
-    },
+      if (!judged) return null;
+      recordVerdictProgress(progress, candidate, judged);
+      return { ...candidate, verdict: judged.verdict, evidence: judged.evidence, kind: angle.kind };
+    }),
   );
 
-  const verified = (perAngle as Verified[][]).flat();
+  const verified = verdicts.filter((value): value is Verified => value !== null);
   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 });
@@ -283,7 +259,7 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
   log(`${verified.length} verified → ${surviving.length} kept`);
 
   if (surviving.length === 0) {
-    return { summary: "No findings survived verification.", findings: [], stats };
+    return { summary: "No findings survived verification.", findings: [], nextSteps: ["No code-review action is recommended from this workflow run."], stats };
   }
 
   // ─── Synthesize: rank, merge, report ───
@@ -293,56 +269,24 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
   const block = ranked
     .map(
       (finding, index) =>
-        `### [${index}] ${finding.file}${finding.line != null ? `:${finding.line}` : ""} (${finding.verdict}${finding.kind === "cleanup" ? ", cleanup" : ""})\n` +
-        `${finding.summary}\nFailure: ${finding.failure_scenario}\nEvidence: ${finding.evidence}`,
+        `### [${index}] ${formatLocation(finding)} (${finding.verdict}${finding.kind === "cleanup" ? ", cleanup" : ""})\n` +
+        `Category: ${finding.kind}\nConfidence: ${verdictConfidence(finding.verdict)}\n` +
+        `${finding.summary}\nImpact: ${finding.impact}\nEvidence: ${formatEvidence(finding.evidence)}`,
     )
     .join("\n\n");
 
   const report = await agent(
     `## 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 report. Include evidence and failure_scenario for each finding when available. Structured output only.",
-    { phase: "Synthesize", label: "synthesize", thinkingLevel: "medium", schema: ReportSchema },
+      "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 },
   );
 
-  if (!report) return { summary: "Synthesis produced no output.", findings: [], stats };
+  if (!report) return { summary: "Synthesis produced no output.", findings: [], nextSteps: ["Re-run the workflow or inspect verifier evidence manually."], stats };
 
-  const findings = report.findings.map((finding) => {
-    const source = ranked.find((candidate) => sameFinding(candidate, finding));
-    return {
-      ...finding,
-      evidence: finding.evidence ?? source?.evidence,
-      failure_scenario: finding.failure_scenario ?? source?.failure_scenario,
-    };
+  const findings = backfillAdvisoryFindings(report.findings, ranked, {
+    impact: "Impact not restated by synthesis.",
   });
   return { ...report, findings, stats };
 }
-
-function formatLocation(candidate: Pick<Candidate, "file" | "line">): string {
-  return `${candidate.file}${candidate.line != null ? `:${candidate.line}` : ""}`;
-}
-
-function verdictLane(verdict: Verified["verdict"]): string {
-  switch (verdict) {
-    case "CONFIRMED":
-      return "Confirmed";
-    case "PLAUSIBLE":
-      return "Plausible";
-    case "REFUTED":
-      return "Refuted";
-  }
-}
-
-function verdictStatus(verdict: Verified["verdict"]): "success" | "warning" | "error" {
-  switch (verdict) {
-    case "CONFIRMED":
-      return "success";
-    case "PLAUSIBLE":
-      return "warning";
-    case "REFUTED":
-      return "error";
-  }
-}
-
-function sameFinding(candidate: Verified, finding: { file: string; line?: number; summary: string }): boolean {
-  return normalizePath(candidate.file) === normalizePath(finding.file) && candidate.line === finding.line;
-}

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

@@ -0,0 +1,244 @@
+import { Type } from "typebox";
+import {
+  AdvisoryCandidatesSchema,
+  AdvisoryReportSchema,
+  AdvisoryVerdictSchema,
+  type AdvisoryCandidate,
+  type AdvisoryReport,
+  type AdvisoryVerdict,
+} from "../src/advisory-schema.ts";
+import {
+  advisoryDedupKey as dedupKey,
+  backfillAdvisoryFindings,
+  formatEvidence,
+  formatLocation,
+  primaryLocation,
+  recordVerdictProgress,
+} from "../src/workflow-advisory-utils.ts";
+import type { WorkflowApi, WorkflowMeta, WorkflowRunStats } from "../src/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: "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." })),
+});
+
+interface HypothesisLens {
+  label: string;
+  category: string;
+  text: string;
+}
+
+type Candidate = AdvisoryCandidate;
+
+interface Hypothesis extends Candidate {
+  lens: HypothesisLens;
+}
+
+interface Verified extends Hypothesis {
+  verdict: AdvisoryVerdict["verdict"];
+  evidence: string[];
+  confidence?: AdvisoryVerdict["confidence"];
+}
+
+const HYPOTHESIS_LENSES: HypothesisLens[] = [
+  { 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 TOOLS = ["read", "bash"];
+const PER_LENS = 4;
+
+export default async function run(api: WorkflowApi): Promise<unknown> {
+  const { agent, parallel, phase, log, progress, args } = api;
+  const symptom = 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: TOOLS, thinkingLevel: "medium", schema: ScopeSchema },
+  );
+
+  if (!scope) {
+    return emptyReport(
+      "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`;
+
+  phase("Hypothesize");
+  const perLens = await parallel(
+    HYPOTHESIS_LENSES.map((lens) => async (): Promise<Hypothesis[]> => {
+      const found = await agent(
+        `## 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.",
+        { phase: "Hypothesize", label: `hypothesize:${lens.label}`, tools: TOOLS, thinkingLevel: "low", schema: AdvisoryCandidatesSchema },
+      );
+      const candidates = (found?.candidates ?? []).slice(0, PER_LENS).map((candidate) => ({ ...candidate, lens }));
+      rawCandidateCount += candidates.length;
+      progress({ type: "counter_delta", key: "candidates", label: "candidates", delta: candidates.length });
+      for (const candidate of candidates) {
+        progress({
+          type: "lane_item",
+          lane: "Hypotheses",
+          title: candidate.summary,
+          subtitle: formatLocation(candidate),
+          status: "pending",
+          details: candidate.impact,
+        });
+      }
+      return candidates;
+    }),
+  );
+
+  const hypotheses = dedupe(perLens.flat(), (dropped) => {
+    droppedCandidateCount += dropped;
+    progress({ type: "counter_delta", key: "dropped", label: "dropped", delta: dropped });
+  });
+
+  phase("Verify");
+  const verified = (
+    await parallel(
+      hypotheses.map((hypothesis) => async (): Promise<Verified | null> => {
+        const location = primaryLocation(hypothesis);
+        const judged = await agent(
+          `## Diagnose verifier\n\n${scopeBlock}\n## Hypothesis\n` +
+            `Location: ${formatLocation(hypothesis)}\nCategory: ${hypothesis.category}\nSummary: ${hypothesis.summary}\nImpact: ${hypothesis.impact}\n` +
+            `Recommended validation: ${hypothesis.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, or REFUTED with evidence. " +
+            "Default toward REFUTED if evidence does not connect the hypothesis to the symptom. Structured output only.",
+          {
+            phase: "Verify",
+            label: `verify:${location.file.split("/").pop() ?? location.file}`,
+            tools: TOOLS,
+            thinkingLevel: "low",
+            schema: AdvisoryVerdictSchema,
+          },
+        );
+        if (!judged) return null;
+        recordVerdictProgress(progress, hypothesis, judged, () => {
+          refutedCandidateCount += 1;
+        });
+        return { ...hypothesis, verdict: judged.verdict, evidence: judged.evidence, confidence: judged.confidence };
+      }),
+    )
+  ).filter((value): value is Verified => value !== null);
+
+  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`);
+
+  if (surviving.length === 0) {
+    return emptyReport(
+      "No root-cause hypothesis survived verification.",
+      ["Capture the exact failing command and error output.", "Rerun diagnose with a narrower symptom or more evidence."],
+      stats,
+    );
+  }
+
+  phase("Synthesize");
+  const ranked = [...surviving].sort((a, b) => rank(a) - rank(b));
+  const block = ranked
+    .map(
+      (finding, index) =>
+        `### [${index}] ${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 report = await agent(
+    `## 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` +
+      "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 },
+  );
+
+  if (!report) return emptyReport("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.",
+    recommendation: "Validate this diagnosis with the smallest safe reproduction command.",
+  });
+  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[] = [];
+  for (const candidate of candidates) {
+    const key = dedupKey(candidate);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    novel.push(candidate);
+  }
+  const dropped = candidates.length - novel.length;
+  if (dropped > 0) onDropped(dropped);
+  return novel;
+}
+
+function rank(finding: Verified): number {
+  if (finding.verdict === "CONFIRMED") return 0;
+  return 1;
+}
+