pi-workflow-engine 0.12.0 → 0.13.0

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

@@ -1,26 +1,21 @@
+import { challengeFindings, parseChallengeArgs } from "../src/advisory-challenge.ts";
 import { Type } from "typebox";
 import {
-  AdvisoryCandidatesSchema,
-  AdvisoryReportSchema,
-  AdvisoryVerdictSchema,
-  type AdvisoryCandidate,
-  type AdvisoryVerdict,
-} from "../src/advisory-schema.ts";
-import {
-  backfillAdvisoryFindings,
+  type AdvisoryVerified,
+  type AdvisoryLens,
+  synthesizeAdvisoryReport,
+  finishAdvisoryReport,
   formatEvidence,
   formatLocation,
   normalizePath,
-  primaryLocation,
   publishVerifiedKeptProgress,
-  recordVerdictProgress,
+  runLensVerificationPipeline,
   verdictConfidence,
   DEFAULT_ADVISORY_TOOL_HINTS,
   DEFAULT_ADVISORY_TOOLS,
 } from "../src/workflow-advisory-utils.ts";
-import { compactResults } from "../src/concurrency.ts";
 import { formatReviewDiffTarget, parseAllowedDiffCommand } from "../src/review-diff-target.ts";
-import { buildCodeReviewScopeBlock, dedupeCodeReviewCandidates } from "../src/review/code-review-orchestration.ts";
+import { buildCodeReviewScopeBlock } 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";
@@ -28,7 +23,7 @@ import type { WorkflowApi, WorkflowMeta, WorkflowRunStats } from "../src/types.t
 export const meta: WorkflowMeta = {
   name: "code-review",
   description: "Fan-out review of the branch's open PR (or branch vs main): scope → per-angle find → independent verify → synthesize.",
-  phases: [{ title: "Scope" }, { title: "Find" }, { title: "Verify" }, { title: "Synthesize" }],
+  phases: [{ title: "Scope" }, { title: "Find" }, { title: "Verify" }, { title: "Challenge" }, { title: "Synthesize" }],
 };
 
 // ─── Schemas (the contracts that make orchestration plain code) ───
@@ -39,30 +34,15 @@ const ScopeSchema = Type.Object({
   conventions: Type.Optional(Type.String({ description: "Relevant AGENTS.md / project conventions" })),
 });
 
-type Candidate = AdvisoryCandidate;
-
-interface Angle {
-  label: string;
-  kind: "bug" | "cleanup";
-  text: string;
-}
-interface Verified extends Candidate {
-  verdict: AdvisoryVerdict["verdict"];
-  evidence: string[];
-  kind: "bug" | "cleanup";
-}
-
 // The review lenses — this is the part you customise to your codebase's real failure modes.
-const ANGLES: Angle[] = [
-  { label: "logic-bugs", kind: "bug", text: "Off-by-one errors, wrong conditionals, incorrect return values, broken control flow." },
-  { label: "error-paths", kind: "bug", text: "Unhandled errors, swallowed exceptions, missing awaits, partial failure leaving inconsistent state." },
-  { label: "edge-cases", kind: "bug", text: "Empty/null inputs, boundary values, concurrency races, resource leaks." },
-  { label: "simplification", kind: "cleanup", text: "Dead code, needless complexity, duplicated logic, clearer equivalents." },
-  { label: "conventions", kind: "cleanup", text: "Violations of the project conventions noted in scope (naming, idioms, banned patterns)." },
+const ANGLES: AdvisoryLens[] = [
+  { label: "logic-bugs", category: "bug", text: "Off-by-one errors, wrong conditionals, incorrect return values, broken control flow." },
+  { label: "error-paths", category: "bug", text: "Unhandled errors, swallowed exceptions, missing awaits, partial failure leaving inconsistent state." },
+  { label: "edge-cases", category: "bug", text: "Empty/null inputs, boundary values, concurrency races, resource leaks." },
+  { label: "simplification", category: "cleanup", text: "Dead code, needless complexity, duplicated logic, clearer equivalents." },
+  { label: "conventions", category: "cleanup", text: "Violations of the project conventions noted in scope (naming, idioms, banned patterns)." },
 ];
 
-const TOOLS = DEFAULT_ADVISORY_TOOLS;
-const TOOL_HINTS = DEFAULT_ADVISORY_TOOL_HINTS;
 const PER_ANGLE = 6;
 
 /** Parse a unified diff into the set of added/changed new-file line numbers per file. */
@@ -106,8 +86,9 @@ export interface CodeReviewDependencies {
 }
 
 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();
+  const { agent, phase, log, progress, args, cwd, signal } = api;
+  const challengeConfig = parseChallengeArgs(args);
+  const target = challengeConfig.args.trim();
   let fileCount = 0;
   let rawCandidateCount = 0;
   let droppedCandidateCount = 0;
@@ -138,7 +119,7 @@ export default async function run(api: WorkflowApi, dependencies: CodeReviewDepe
       "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, profile: "medium", schema: ScopeSchema },
+    { phase: "Scope", label: "scope", tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS, profile: "medium", schema: ScopeSchema },
   );
 
   if (!scope) {
@@ -184,7 +165,7 @@ export default async function run(api: WorkflowApi, dependencies: CodeReviewDepe
       : {}),
   };
 
-  const scopeBlock = buildCodeReviewScopeBlock({
+  const scopeBlock = `Reviewed snapshot identity: ${JSON.stringify(reviewContext.snapshot ?? "unavailable")}\n` + buildCodeReviewScopeBlock({
     diffCommand,
     files: scope.files,
     summary: scope.summary,
@@ -193,113 +174,59 @@ export default async function run(api: WorkflowApi, dependencies: CodeReviewDepe
     target,
   });
 
-  // ─── Find barrier → dedup → Verify ───
-  phase("Find");
-  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. 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, 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 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 });
-        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 };
-    }),
-  );
-
-  // 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(
-    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,
-          toolHints: TOOL_HINTS,
-          profile: "small",
-          schema: AdvisoryVerdictSchema,
-        },
-      );
-      if (!judged) return null;
-      recordVerdictProgress(progress, candidate, judged);
-      return { ...candidate, verdict: judged.verdict, evidence: judged.evidence, kind: angle.kind };
-    }),
-  );
-
-  const verified = compactResults(verdicts);
+  const pipelineResult = await runLensVerificationPipeline({
+    api,
+    lenses: ANGLES,
+    perLens: PER_ANGLE,
+    boundCandidate: (candidate, lens) => {
+      const anchor = candidate.reviewAnchor ?? candidate.locations.find((location) => inDiff(changed, location.file, location.line));
+      return anchor && inDiff(changed, anchor.file, anchor.line)
+        ? { ...candidate, category: lens.category, reviewAnchor: anchor } : undefined;
+    },
+    finderPrompt: (lens) =>
+      `## Code-review finder — ${lens.label}\n\n${scopeBlock}\n` +
+      `Review the change through ONLY this lens:\n${lens.text}\n` +
+      "Only flag issues on lines that are part of the diff above (run the diff command if it is not shown). " +
+      "Set reviewAnchor to the changed line causing the issue; locations and discoveryEvidence may include unchanged callers and other files. " +
+      `Surface up to ${PER_ANGLE} candidates. Use category exactly "${lens.category}". Each candidate must include a one-line summary, ` +
+      "locations with the changed file and a line that appears in the diff, and impact describing the concrete failure or maintenance scenario. " +
+      "Pass through anything with a nameable impact — a separate verifier judges them next. Structured output only.",
+    verifierPrompt: (candidate) =>
+      `## Code-review verifier\n\n${scopeBlock}\n## Candidate\n` +
+      `Location: ${formatLocation(candidate)}\n` +
+      `Category: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}\n\n` +
+      "Run the diff command, read the relevant file(s), and return exactly one verdict (CONFIRMED / PLAUSIBLE / NOT_SUBSTANTIATED / REFUTED) " +
+      "with evidence quoting the line(s). Use NOT_SUBSTANTIATED when evidence is insufficient; use REFUTED only for concrete disproof. Structured output only.",
+  });
+  rawCandidateCount += pipelineResult.rawCandidates;
+  droppedCandidateCount += pipelineResult.dropped;
+  const { coverage } = pipelineResult;
+  const verified = await challengeFindings(api, pipelineResult.verified, scopeBlock, challengeConfig.options, coverage);
   const surviving = verified.filter((finding) => finding.verdict !== "REFUTED");
   const stats = makeStats(verified.length, surviving.length);
   publishVerifiedKeptProgress({ progress, log }, verified.length, surviving.length);
 
   if (surviving.length === 0) {
-    return { summary: "No findings survived verification.", findings: [], nextSteps: ["No code-review action is recommended from this workflow run."], stats, reviewContext };
+    return finishAdvisoryReport({ summary: "No findings survived verification.", findings: [], nextSteps: ["No code-review action is recommended from this workflow run."], stats, reviewContext }, coverage, verified);
   }
 
   // ─── Synthesize: rank, merge, report ───
-  phase("Synthesize");
-  const rank = (finding: Verified): number => (finding.kind === "cleanup" ? 2 : 0) + (finding.verdict === "PLAUSIBLE" ? 1 : 0);
+  const rank = (finding: AdvisoryVerified): number => (finding.category === "cleanup" ? 2 : 0) + (finding.verdict !== "CONFIRMED" ? 1 : 0);
   const ranked = [...surviving].sort((a, b) => rank(a) - rank(b));
   const block = ranked
     .map(
       (finding, index) =>
-        `### [${index}] ${formatLocation(finding)} (${finding.verdict}${finding.kind === "cleanup" ? ", cleanup" : ""})\n` +
-        `Category: ${finding.kind}\nConfidence: ${verdictConfidence(finding.verdict)}\n` +
+        `### [${index}] IDs: ${finding.sourceCandidateIds.join(", ")} ${formatLocation(finding)} (${finding.verdict}${finding.category === "cleanup" ? ", cleanup" : ""})\n` +
+        `Category: ${finding.category}\nConfidence: ${verdictConfidence(finding.verdict)}\n` +
         `${finding.summary}\nImpact: ${finding.impact}\nEvidence: ${formatEvidence(finding.evidence)}`,
     )
     .join("\n\n");
 
-  const report = await agent(
+  const resolved = await synthesizeAdvisoryReport(api,
     `## Synthesis: final code-review report\n\n${ranked.length} findings survived independent verification.\n\n${block}\n\n` +
       "Merge findings with the same root cause, rank most-severe first (correctness bugs above cleanups), and produce the final advisory report. " +
-      "Return summary, 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",
-      tools: [],
-      profile: "medium",
-      resume: "read-only",
-      schema: AdvisoryReportSchema,
-    },
+      "Return summary, ID selections with severity (low/medium/high) and advisory recommendation, and nextSteps. Evidence and confidence are reconstructed from verified records. Structured output only.",
+    ranked, coverage,
   );
-
-  if (!report) return { summary: "Synthesis produced no output.", findings: [], nextSteps: ["Re-run the workflow or inspect verifier evidence manually."], stats, reviewContext };
-
-  const findings = backfillAdvisoryFindings(report.findings, ranked, {
-    impact: "Impact not restated by synthesis.",
-  });
-  return { ...report, findings, stats, reviewContext };
+  return finishAdvisoryReport({ ...resolved, stats: { ...stats, kept: resolved.findings.length }, reviewContext }, coverage, verified);
 }

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

@@ -1,30 +1,24 @@
+import { challengeFindings, parseChallengeArgs } from "../src/advisory-challenge.ts";
 import { Type } from "typebox";
 import {
-  AdvisoryCandidatesSchema,
-  AdvisoryReportSchema,
-  AdvisoryVerdictSchema,
-  type AdvisoryCandidate,
-  type AdvisoryVerdict,
-} from "../src/advisory-schema.ts";
-import {
-  advisoryDedupKey as dedupKey,
-  backfillAdvisoryFindings,
+  type AdvisoryVerified,
+  type AdvisoryLens,
+  synthesizeAdvisoryReport,
+  finishAdvisoryReport,
   emptyAdvisoryReport,
   formatEvidence,
   formatLocation,
-  primaryLocation,
   publishVerifiedKeptProgress,
-  recordVerdictProgress,
+  runLensVerificationPipeline,
   DEFAULT_ADVISORY_TOOL_HINTS,
   DEFAULT_ADVISORY_TOOLS,
 } from "../src/workflow-advisory-utils.ts";
-import { compactResults } from "../src/concurrency.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" }],
+  phases: [{ title: "Scope" }, { title: "Hypothesize" }, { title: "Verify" }, { title: "Challenge" }, { title: "Synthesize" }],
 };
 
 const ScopeSchema = Type.Object({
@@ -35,25 +29,7 @@ const ScopeSchema = Type.Object({
   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[] = [
+const HYPOTHESIS_LENSES: AdvisoryLens[] = [
   { label: "recent-change", category: "regression", text: "A recent code change broke a previously working path or changed an implicit contract." },
   { label: "control-flow", category: "root-cause", text: "Incorrect branching, ordering, async flow, data flow, or state transition causes the symptom." },
   { label: "configuration", category: "configuration", text: "Configuration, environment, package scripts, or runtime assumptions differ from what the code expects." },
@@ -61,13 +37,12 @@ const HYPOTHESIS_LENSES: HypothesisLens[] = [
   { 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 = DEFAULT_ADVISORY_TOOLS;
-const TOOL_HINTS = DEFAULT_ADVISORY_TOOL_HINTS;
 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();
+  const { agent, phase, log, progress, args } = api;
+  const challengeConfig = parseChallengeArgs(args);
+  const symptom = challengeConfig.args.trim();
   let fileCount = 0;
   let rawCandidateCount = 0;
   let droppedCandidateCount = 0;
@@ -90,15 +65,15 @@ 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, profile: "medium", schema: ScopeSchema },
+    { phase: "Scope", label: "scope", tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS, profile: "medium", schema: ScopeSchema },
   );
 
   if (!scope) {
-    return emptyAdvisoryReport(
+    return finishAdvisoryReport(emptyAdvisoryReport(
       "Diagnosis could not establish a scope.",
       ["Provide the failing command, error message, or regression description and rerun diagnose."],
       makeStats(0, 0),
-    );
+    ), []);
   }
 
   fileCount = scope.files.length;
@@ -113,88 +88,48 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
     `## 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, toolHints: TOOL_HINTS, profile: "small", 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(compactResults(perLens).flat(), (dropped) => {
-    droppedCandidateCount += dropped;
-    progress({ type: "counter_delta", key: "dropped", label: "dropped", delta: dropped });
+  const pipelineResult = await runLensVerificationPipeline({
+    api,
+    lenses: HYPOTHESIS_LENSES,
+    perLens: PER_LENS,
+    finderPhase: "Hypothesize",
+    finderPrompt: (lens) =>
+      `## Diagnose hypothesis generator — ${lens.label}\n\n${scopeBlock}\n` +
+      "This workflow is advisory-only: diagnose and recommend validation/fix plans, but do not edit files.\n" +
+      `Consider ONLY this hypothesis lens:\n${lens.text}\n\n` +
+      `Surface up to ${PER_LENS} root-cause hypotheses. Use category exactly "${lens.category}". ` +
+      "Each hypothesis must include a one-line summary, locations, impact explaining how it produces the symptom, and an optional recommendation for the next validation step. Structured output only.",
+    verifierPrompt: (candidate) =>
+      `## Diagnose verifier\n\n${scopeBlock}\n## Hypothesis\n` +
+      `Location: ${formatLocation(candidate)}\nCategory: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}\n` +
+      `Recommended validation: ${candidate.recommendation ?? "(none supplied)"}\n\n` +
+      "Read relevant files and, when useful, run only safe read-only diagnostic commands from the scoped command list or commands explicitly requested by the user. " +
+      "Do not run mutation, install, commit, network, or destructive commands. Return CONFIRMED, PLAUSIBLE, NOT_SUBSTANTIATED, or REFUTED with evidence. " +
+      "Use NOT_SUBSTANTIATED when evidence is missing; REFUTED requires disproof. Structured output only.",
   });
-
-  phase("Verify");
-  const verified = compactResults(
-    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,
-            toolHints: TOOL_HINTS,
-            profile: "small",
-            schema: AdvisoryVerdictSchema,
-          },
-        );
-        if (!judged) return null;
-        recordVerdictProgress(progress, hypothesis, judged, () => {
-          refutedCandidateCount += 1;
-        });
-        return { ...hypothesis, verdict: judged.verdict, evidence: judged.evidence, confidence: judged.confidence };
-      }),
-    ),
-  );
-
+  rawCandidateCount += pipelineResult.rawCandidates;
+  droppedCandidateCount += pipelineResult.dropped;
+  refutedCandidateCount += pipelineResult.refuted;
+  const { coverage } = pipelineResult;
+  const verified = await challengeFindings(api, pipelineResult.verified, scopeBlock, challengeConfig.options, coverage);
   const surviving = verified.filter((finding) => finding.verdict !== "REFUTED");
   const refuted = verified.filter((finding) => finding.verdict === "REFUTED");
   const stats = makeStats(verified.length, surviving.length);
   publishVerifiedKeptProgress({ progress, log }, verified.length, surviving.length);
 
   if (surviving.length === 0) {
-    return emptyAdvisoryReport(
+    return finishAdvisoryReport(emptyAdvisoryReport(
       "No root-cause hypothesis survived verification.",
       ["Capture the exact failing command and error output.", "Rerun diagnose with a narrower symptom or more evidence."],
       stats,
-    );
+    ), coverage, verified);
   }
 
-  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` +
+        `### [${index}] IDs: ${finding.sourceCandidateIds.join(", ")} ${formatLocation(finding)} (${finding.verdict}, ${finding.category})\n` +
         `${finding.summary}\nImpact: ${finding.impact}\nEvidence: ${formatEvidence(finding.evidence)}\nValidation/fix plan: ${finding.recommendation ?? "(none supplied)"}`,
     )
     .join("\n\n");
@@ -203,46 +138,17 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
     .map((finding) => `- ${finding.summary} — REFUTED because ${formatEvidence(finding.evidence)}`)
     .join("\n");
 
-  const report = await agent(
+  const resolved = await synthesizeAdvisoryReport(api,
     `## Synthesis: final diagnosis report\n\n${ranked.length} hypotheses survived independent verification.\n\n${block}\n\n` +
       `## Refuted hypotheses for context\n${refutedBlock || "(none recorded)"}\n\n` +
-      "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. " +
+      "Select confirmed, plausible or explicitly unresolved root causes by ID. " +
       "Recommendation must be a validation/fix plan, not a patch. nextSteps must be the minimum commands or code inspections needed to confirm the top diagnosis. Structured output only.",
-    {
-      phase: "Synthesize",
-      label: "synthesize",
-      tools: [],
-      profile: "medium",
-      resume: "read-only",
-      schema: AdvisoryReportSchema,
-    },
+    ranked, coverage,
   );
-
-  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.",
-    recommendation: "Validate this diagnosis with the smallest safe reproduction command.",
-  });
-  return { ...report, findings, 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;
+  return finishAdvisoryReport({ ...resolved, stats: { ...stats, kept: resolved.findings.length } }, coverage, verified);
 }
 
-function rank(finding: Verified): number {
+function rank(finding: AdvisoryVerified): number {
   if (finding.verdict === "CONFIRMED") return 0;
   return 1;
 }