pi-workflow-engine 0.1.1 → 0.3.0

package/workflows/code-review.ts

@@ -1,6 +1,15 @@
 import { execSync } from "node:child_process";
 import { Type } from "typebox";
-import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
+import {
+  AdvisoryCandidatesSchema,
+  AdvisoryReportSchema,
+  AdvisoryVerdictSchema,
+  type AdvisoryCandidate,
+  type AdvisoryFinding,
+  type AdvisoryLocation,
+  type AdvisoryVerdict,
+} from "../src/advisory-schema.ts";
+import type { WorkflowApi, WorkflowMeta, WorkflowRunStats } from "../src/types.ts";
 
 export const meta: WorkflowMeta = {
   name: "code-review",
@@ -16,49 +25,16 @@ const ScopeSchema = Type.Object({
   conventions: Type.Optional(Type.String({ description: "Relevant CLAUDE.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(),
-    }),
-  ),
-});
+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";
 }
 
@@ -113,8 +89,18 @@ 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, args, cwd } = api;
+  const { agent, parallel, pipeline, phase, log, progress, args, cwd } = api;
   const target = 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");
@@ -137,8 +123,17 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
     { phase: "Scope", label: "scope", tools: TOOLS, thinkingLevel: "medium", schema: ScopeSchema },
   );
 
-  if (!scope || scope.files.length === 0) {
-    return { summary: "No changes found to review.", findings: [], stats: { candidates: 0, verified: 0 } };
+  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)" });
+  progress({ type: "summary", key: "diffCommand", value: scope.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`);
 
@@ -172,8 +167,11 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
 
   // Dedup state accumulates as finders complete (the pipeline has no barrier).
   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) ───
   phase("Find");
@@ -187,15 +185,33 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
           `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;
-      if (gate && raw.length - bounded.length > 0) {
-        log(`find:${angle.label}: dropped ${raw.length - bounded.length} out-of-diff candidate(s)`);
+      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;
+        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) {
+        progress({
+          type: "lane_item",
+          lane: "Candidates",
+          title: candidate.summary,
+          subtitle: formatLocation(candidate),
+          status: "pending",
+          details: candidate.impact,
+        });
       }
       return { angle, candidates: bounded };
     },
@@ -210,15 +226,32 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       });
       const verdicts = await parallel(
         novel.map((candidate) => async (): Promise<Verified | null> => {
+          const location = primaryLocation(candidate);
           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` +
+              `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:${candidate.file.split("/").pop() ?? candidate.file}`, tools: TOOLS, thinkingLevel: "low", schema: VerdictSchema },
+            {
+              phase: "Verify",
+              label: `verify:${location.file.split("/").pop() ?? location.file}`,
+              tools: TOOLS,
+              thinkingLevel: "low",
+              schema: AdvisoryVerdictSchema,
+            },
           );
-          return judged ? { ...candidate, verdict: judged.verdict, evidence: judged.evidence, kind: angle.kind } : null;
+          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: formatEvidence(judged.evidence),
+          });
+          return { ...candidate, verdict: judged.verdict, evidence: judged.evidence, kind: angle.kind };
         }),
       );
       return verdicts.filter((value): value is Verified => value !== null);
@@ -227,10 +260,15 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
 
   const verified = (perAngle as Verified[][]).flat();
   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`);
 
   if (surviving.length === 0) {
-    return { summary: "No findings survived verification.", findings: [], stats: { candidates: seen.size, verified: verified.length } };
+    return { summary: "No findings survived verification.", findings: [], nextSteps: ["No code-review action is recommended from this workflow run."], stats };
   }
 
   // ─── Synthesize: rank, merge, report ───
@@ -240,16 +278,83 @@ 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. 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 },
   );
 
-  return report ?? { summary: "Synthesis produced no output.", findings: [] };
+  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.length > 0 ? finding.evidence : (source?.evidence ?? []),
+      impact: finding.impact || source?.impact || "Impact not restated by synthesis.",
+    };
+  });
+  return { ...report, findings, stats };
+}
+
+function primaryLocation(candidate: Pick<Candidate, "locations">): AdvisoryLocation {
+  return candidate.locations[0] ?? { file: "" };
+}
+
+function formatLocation(candidate: Pick<Candidate, "locations">): string {
+  const location = primaryLocation(candidate);
+  const line = location.line != null ? `:${location.line}` : "";
+  const symbol = location.symbol ? ` (${location.symbol})` : "";
+  return `${location.file}${line}${symbol}`;
+}
+
+function formatEvidence(evidence: string[]): string {
+  return evidence.join("; ");
+}
+
+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 verdictConfidence(verdict: Verified["verdict"]): "high" | "medium" | "low" {
+  switch (verdict) {
+    case "CONFIRMED":
+      return "high";
+    case "PLAUSIBLE":
+      return "medium";
+    case "REFUTED":
+      return "low";
+  }
+}
+
+function sameFinding(candidate: Verified, finding: Pick<AdvisoryFinding, "locations" | "summary">): boolean {
+  const candidateLocation = primaryLocation(candidate);
+  const findingLocation = primaryLocation(finding);
+  return normalizePath(candidateLocation.file) === normalizePath(findingLocation.file) && candidateLocation.line === findingLocation.line;
 }

package/workflows/diagnose.ts

@@ -0,0 +1,305 @@
+import { Type } from "typebox";
+import {
+  AdvisoryCandidatesSchema,
+  AdvisoryReportSchema,
+  AdvisoryVerdictSchema,
+  type AdvisoryCandidate,
+  type AdvisoryFinding,
+  type AdvisoryLocation,
+  type AdvisoryReport,
+  type AdvisoryVerdict,
+} from "../src/advisory-schema.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;
+        progress({ type: "counter_delta", key: `verdict.${judged.verdict.toLowerCase()}`, label: judged.verdict, delta: 1 });
+        if (judged.verdict === "REFUTED") {
+          refutedCandidateCount += 1;
+          progress({ type: "counter_delta", key: "refuted", label: "refuted", delta: 1 });
+        }
+        progress({
+          type: "lane_item",
+          lane: verdictLane(judged.verdict),
+          title: hypothesis.summary,
+          subtitle: formatLocation(hypothesis),
+          status: verdictStatus(judged.verdict),
+          details: formatEvidence(judged.evidence),
+        });
+        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 = report.findings.map((finding) => {
+    const source = ranked.find((candidate) => sameFinding(candidate, finding));
+    return {
+      ...finding,
+      evidence: finding.evidence.length > 0 ? finding.evidence : (source?.evidence ?? []),
+      impact: finding.impact || source?.impact || "Impact not restated by synthesis.",
+      recommendation: finding.recommendation || source?.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 dedupKey(candidate: Candidate): string {
+  const location = primaryLocation(candidate);
+  const lineKey = location.line != null ? Math.round(location.line / 5) * 5 : "file";
+  return `${candidate.category}:${normalizePath(location.file)}:${lineKey}:${candidate.summary.slice(0, 60).toLowerCase()}`;
+}
+
+function primaryLocation(candidate: Pick<Candidate, "locations">): AdvisoryLocation {
+  return candidate.locations[0] ?? { file: "" };
+}
+
+function formatLocation(candidate: Pick<Candidate, "locations">): string {
+  const location = primaryLocation(candidate);
+  const line = location.line != null ? `:${location.line}` : "";
+  const symbol = location.symbol ? ` (${location.symbol})` : "";
+  return `${location.file}${line}${symbol}`;
+}
+
+function formatEvidence(evidence: string[]): string {
+  return evidence.join("; ");
+}
+
+function normalizePath(path: string): string {
+  return path.replace(/^\.\//, "").replace(/^[ab]\//, "");
+}
+
+function rank(finding: Verified): number {
+  if (finding.verdict === "CONFIRMED") return 0;
+  return 1;
+}
+
+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: Pick<AdvisoryFinding, "locations" | "summary">): boolean {
+  const candidateLocation = primaryLocation(candidate);
+  const findingLocation = primaryLocation(finding);
+  return normalizePath(candidateLocation.file) === normalizePath(findingLocation.file) && candidateLocation.line === findingLocation.line;
+}