pi-workflow-engine 0.12.0 → 1.0.0

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

@@ -1,25 +1,24 @@
+import { challengeFindings, parseChallengeArgs } from "../src/advisory-challenge.ts";
 import { Type } from "typebox";
 import {
-  AdvisoryReportSchema,
-  type AdvisoryCandidate,
-  type AdvisoryVerdict,
-} from "../src/advisory-schema.ts";
-import {
-  backfillAdvisoryFindings,
+  type AdvisoryVerified,
+  type AdvisoryLens,
+  concludeLensReview,
+  finishAdvisoryReport,
   emptyAdvisoryReport,
-  formatEvidence,
+  EMPTY_LENS_REVIEW_STATS,
   formatLocation,
-  publishVerifiedKeptProgress,
+  formatRankedFinding,
   runLensVerificationPipeline,
   DEFAULT_ADVISORY_TOOL_HINTS,
   DEFAULT_ADVISORY_TOOLS,
 } from "../src/workflow-advisory-utils.ts";
-import type { WorkflowApi, WorkflowMeta, WorkflowRunStats } from "../src/types.ts";
+import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
 
 export const meta: WorkflowMeta = {
   name: "refactor-scout",
   description: "Advisory-only refactor scout: scope → per-lens find → independent verify → synthesize safe refactor opportunities.",
-  phases: [{ title: "Scope" }, { title: "Find" }, { title: "Verify" }, { title: "Synthesize" }],
+  phases: [{ title: "Scope" }, { title: "Find" }, { title: "Verify" }, { title: "Challenge" }, { title: "Synthesize" }],
 };
 
 const ScopeSchema = Type.Object({
@@ -29,22 +28,7 @@ const ScopeSchema = Type.Object({
   conventions: Type.Optional(Type.String({ description: "Relevant project conventions from AGENTS.md / docs." })),
 });
 
-interface RefactorLens {
-  label: string;
-  category: string;
-  text: string;
-}
-
-type Candidate = AdvisoryCandidate;
-
-interface Verified extends Candidate {
-  verdict: AdvisoryVerdict["verdict"];
-  evidence: string[];
-  confidence?: AdvisoryVerdict["confidence"];
-  lens: RefactorLens;
-}
-
-const REFACTOR_LENSES: RefactorLens[] = [
+const REFACTOR_LENSES: AdvisoryLens[] = [
   { label: "duplication", category: "duplication", text: "Repeated logic, copy-pasted structures, or near-duplicate flows that could share one clearer implementation." },
   { label: "complexity", category: "complexity", text: "Oversized functions, tangled control flow, or abstractions that make local reasoning harder than necessary." },
   { label: "type-safety", category: "type-safety", text: "Weak typing, avoidable casts, unchecked shapes, or places stronger types would prevent mistakes." },
@@ -53,25 +37,12 @@ const REFACTOR_LENSES: RefactorLens[] = [
   { label: "conventions", category: "conventions", text: "Departures from project conventions, naming, dependency rules, or local idioms." },
 ];
 
-const TOOLS = DEFAULT_ADVISORY_TOOLS;
-const TOOL_HINTS = DEFAULT_ADVISORY_TOOL_HINTS;
 const PER_LENS = 5;
 
 export default async function run(api: WorkflowApi): Promise<unknown> {
-  const { agent, parallel, pipeline, phase, log, progress, args } = api;
-  const target = 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,
-  });
+  const { agent, phase, log, progress, args } = api;
+  const challengeConfig = parseChallengeArgs(args);
+  const target = challengeConfig.args || ".";
 
   phase("Scope");
   const scope = await agent(
@@ -80,35 +51,30 @@ 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, profile: "medium", schema: ScopeSchema },
+    { phase: "Scope", label: "scope", tools: DEFAULT_ADVISORY_TOOLS, toolHints: DEFAULT_ADVISORY_TOOL_HINTS, profile: "medium", schema: ScopeSchema },
   );
 
-  if (!scope || scope.files.length === 0) {
-    return emptyAdvisoryReport(
+  if (scope.files.length === 0) {
+    return finishAdvisoryReport(emptyAdvisoryReport(
       "No files were identified for refactor scouting.",
       ["Provide a target path, module, or subsystem to scout for refactor opportunities."],
-      makeStats(0, 0),
-    );
+      EMPTY_LENS_REVIEW_STATS,
+    ), []);
   }
 
-  fileCount = scope.files.length;
-  progress({ type: "counter", key: "files", label: "files", value: fileCount });
+  progress({ type: "counter", key: "files", label: "files", value: scope.files.length });
   progress({ type: "summary", key: "files", value: scope.files.join(", ") });
   log(`${scope.files.length} files scoped for refactor scouting`);
 
   const scopeBlock =
     `## Target\n${scope.target}\n\n## Files in scope\n${scope.files.map((file) => `- ${file}`).join("\n")}\n\n` +
     `## Summary\n${scope.summary}\n\n## Conventions\n${scope.conventions ?? "(none noted)"}\n` +
-    (args.trim() ? `\n## User instructions (verbatim)\n${args.trim()}\n` : "");
+    (challengeConfig.args ? `\n## User instructions (verbatim)\n${challengeConfig.args}\n` : "");
 
-  phase("Find");
   const pipelineResult = await runLensVerificationPipeline({
-    api: { agent, parallel, pipeline, progress, log },
+    api,
     lenses: REFACTOR_LENSES,
-    schedulingMode: "finder-barrier",
     perLens: PER_LENS,
-    tools: TOOLS,
-    toolHints: TOOL_HINTS,
     finderPrompt: (lens) =>
       `## Refactor-scout finder — ${lens.label}\n\n${scopeBlock}\n` +
       "This workflow is advisory-only: do not edit files and do not propose broad rewrites.\n" +
@@ -120,65 +86,29 @@ export default async function run(api: WorkflowApi): Promise<unknown> {
       `## Refactor-scout verifier\n\n${scopeBlock}\n## Candidate\n` +
       `Location: ${formatLocation(candidate)}\nCategory: ${candidate.category}\nSummary: ${candidate.summary}\nImpact: ${candidate.impact}\n` +
       `Recommendation: ${candidate.recommendation ?? "(none supplied)"}\n\n` +
-      "Read the relevant files and return CONFIRMED, PLAUSIBLE, or REFUTED. " +
+      "Read the relevant files and return CONFIRMED, PLAUSIBLE, NOT_SUBSTANTIATED, or REFUTED. " +
       "Default toward REFUTED if the opportunity is generic, too broad, not evidenced by code, or lacks a safe first step. " +
       "Evidence must quote or cite code. Structured output only.",
-    makeVerified: (candidate, lens, judged): Verified => ({
-      ...candidate,
-      verdict: judged.verdict,
-      evidence: judged.evidence,
-      confidence: judged.confidence,
-      lens,
-    }),
   });
-  rawCandidateCount += pipelineResult.rawCandidates;
-  droppedCandidateCount += pipelineResult.dropped;
-  refutedCandidateCount += pipelineResult.refuted;
-  const verified = pipelineResult.verified;
-  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 emptyAdvisoryReport("No refactor opportunities survived verification.", ["Leave the scoped code unchanged unless a human reviewer has additional context."], 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)}\nSafe first step: ${finding.recommendation ?? "(none supplied)"}`,
-    )
-    .join("\n\n");
-
-  const report = await agent(
-    `## Synthesis: final refactor-scout report\n\n${ranked.length} opportunities survived independent verification.\n\n${block}\n\n` +
+  const verified = await challengeFindings(api, pipelineResult.verified, scopeBlock, challengeConfig.options, pipelineResult.coverage);
+  return concludeLensReview(api, pipelineResult, verified, {
+    files: scope.files.length,
+    rank,
+    formatFinding: (finding, index) => formatRankedFinding(finding, index, "Safe first step"),
+    empty: {
+      summary: "No refactor opportunities survived verification.",
+      nextSteps: ["Leave the scoped code unchanged unless a human reviewer has additional context."],
+    },
+    synthesisPrompt: (block, ranked) =>
+      `## Synthesis: final refactor-scout report\n\n${ranked.length} opportunities survived independent verification.\n\n${block}\n\n` +
       "Merge findings with the same root cause and rank highest leverage / lowest risk first. " +
-      "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. " +
+      "Select findings by ID. " +
+      "Severity is maintenance or future-correctness impact. " +
       "Recommendations must be safe first refactor steps, not rewrites. Include concrete nextSteps for the host developer. Structured output only.",
-    {
-      phase: "Synthesize",
-      label: "synthesize",
-      tools: [],
-      profile: "medium",
-      resume: "read-only",
-      schema: AdvisoryReportSchema,
-    },
-  );
-
-  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.",
-    recommendation: "Choose a small, behavior-preserving refactor first step.",
   });
-  return { ...report, findings, stats };
 }
 
-function rank(finding: Verified): number {
+function rank(finding: AdvisoryVerified): number {
   const verdictRank = finding.verdict === "CONFIRMED" ? 0 : 1;
   const categoryRank = finding.category === "dead-code" || finding.category === "conventions" ? 2 : 0;
   return verdictRank + categoryRank;

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

@@ -1,4 +1,3 @@
-import { compactResults } from "../src/concurrency.ts";
 import {
   MAX_RESEARCH_LANES,
   ResearchLaneResultSchema,
@@ -7,18 +6,17 @@ import {
   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 { isFatalWorkflowError } from "../src/cancellation.ts";
 import { WorkflowToolHintUnavailableError } from "../src/tool-capabilities.ts";
 import type { WorkflowApi, WorkflowMeta } from "../src/types.ts";
 
@@ -32,7 +30,7 @@ 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 { agent, parallel, phase, log, progress, args, signal } = api;
   const question = args.trim();
   if (!question) return unavailableResearchReport("empty-question");
 
@@ -61,54 +59,54 @@ export default async function run(api: WorkflowApi): Promise<ResearchReport> {
     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 gatherResults = 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: ${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,
+          // The prompt embeds lane text planned by a web-enabled agent; never infer skills (and the read tool) from it.
+          skills: [],
+          profile: "small",
+          resume: "off",
+          schema: ResearchLaneResultSchema,
+        },
+      );
+      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;
+    }),
+    { settled: true },
   );
+  const gathered = gatherResults.flatMap((result) => (result.ok ? [result.value] : []));
+  const failedLanes = lanes.filter((_, index) => !gatherResults[index]!.ok);
 
-  const laneResults = sanitizeLaneResults(gathered);
-  const candidates = buildClaimCandidates(laneResults);
-  if (candidates.length === 0) return unavailableResearchReport("no-evidence");
+  const candidates = buildClaimCandidates(gathered);
+  if (candidates.length === 0) return unavailableResearchReport(failedLanes.length > 0 ? "lanes-failed" : "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`);
 
@@ -121,11 +119,13 @@ export default async function run(api: WorkflowApi): Promise<ResearchReport> {
         tools: EXTERNAL_TOOLS,
         toolHints: EXTERNAL_TOOL_HINTS,
         requireToolHints: true,
+        // The prompt embeds web-derived evidence; never infer skills (and the read tool) from it.
+        skills: [],
         profile: "medium",
         resume: "off",
         schema: ResearchVerificationSchema,
       });
-      return result ? sanitizeVerification(result, candidate) : null;
+      return sanitizeVerification(result, candidate);
     }),
   );
   const verifications = verificationResults.map((result, index) => result ?? unavailableVerification(candidates[index]!));
@@ -135,28 +135,36 @@ export default async function run(api: WorkflowApi): Promise<ResearchReport> {
   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,
-    },
-  );
+  let synthesis: ResearchReport;
+  try {
+    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: [],
+        // The prompt embeds web-derived claims; never infer skills (and the read tool) from them.
+        skills: [],
+        profile: "medium",
+        resume: "off",
+        schema: ResearchReportSchema,
+      },
+    );
+  } catch (error) {
+    if (isFatalWorkflowError(error, signal)) throw error;
+    synthesis = fallbackResearchReport(synthesisInputs);
+  }
 
-  return sanitizeResearchReport(
-    synthesis ?? fallbackResearchReport(synthesisInputs, "The model did not return a structured synthesis."),
-    synthesisInputs,
-  );
+  const report = sanitizeResearchReport(synthesis, synthesisInputs);
+  if (failedLanes.length === 0) return report;
+  const laneGap = `${failedLanes.length} of ${lanes.length} research lane(s) failed (${failedLanes.map((lane) => lane.title).join(", ")}); coverage is incomplete.`;
+  return { ...report, limitations: [...report.limitations, laneGap] };
 }
 
 function verificationPrompt(question: string, candidate: ResearchClaimCandidate): string {