@mediadatafusion/pi-workflow-suite 0.0.1

package/extensions/workflow-tool-guard.ts

@@ -0,0 +1,302 @@
+import { existsSync, realpathSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { isAbsolute, resolve } from "node:path";
+import { getAgentDir, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadWorkflowSettings } from "./workflow-model-router.js";
+import type { WorkflowState } from "./workflow-state.js";
+
+export const PLAN_TOOLS = ["read", "grep", "find", "ls"];
+export const WORKFLOW_PROGRESS_TOOL = "workflow_progress";
+export const WORKFLOW_DIAGRAM_TOOL = "workflow_diagram";
+export const WORKFLOW_PLAN_RESULT_TOOL = "workflow_plan_result";
+export const WORKFLOW_REVIEW_RESULT_TOOL = "workflow_review_result";
+export const WORKFLOW_EXECUTION_RESULT_TOOL = "workflow_execution_result";
+export const WORKFLOW_VALIDATION_RESULT_TOOL = "workflow_validation_result";
+export const WORKFLOW_REPAIR_RESULT_TOOL = "workflow_repair_result";
+export const MISSION_PLAN_RESULT_TOOL = "mission_plan_result";
+export const MISSION_MILESTONE_RESULT_TOOL = "mission_milestone_result";
+export const STANDARD_HANDOFF_RESULT_TOOL = "standard_handoff_result";
+export const PLAN_RESULT_TOOLS = [WORKFLOW_PLAN_RESULT_TOOL, MISSION_PLAN_RESULT_TOOL];
+export const REVIEW_RESULT_TOOLS = [WORKFLOW_REVIEW_RESULT_TOOL];
+export const EXECUTION_RESULT_TOOLS = [WORKFLOW_EXECUTION_RESULT_TOOL, MISSION_MILESTONE_RESULT_TOOL];
+export const VALIDATION_RESULT_TOOLS = [WORKFLOW_VALIDATION_RESULT_TOOL];
+export const REPAIR_RESULT_TOOLS = [WORKFLOW_REPAIR_RESULT_TOOL];
+export const STANDARD_RESULT_TOOLS = [STANDARD_HANDOFF_RESULT_TOOL];
+export const BASE_EXECUTE_TOOLS = ["read", "grep", "find", "ls", "edit", "write", "bash", WORKFLOW_PROGRESS_TOOL, WORKFLOW_DIAGRAM_TOOL];
+export const EXECUTE_TOOLS = [...BASE_EXECUTE_TOOLS, ...EXECUTION_RESULT_TOOLS, ...REPAIR_RESULT_TOOLS];
+export const VALIDATOR_TOOLS = ["read", "grep", "find", "ls", "bash", WORKFLOW_DIAGRAM_TOOL, ...REVIEW_RESULT_TOOLS, ...VALIDATION_RESULT_TOOLS];
+
+
+const PATH_SCOPED_TOOLS = new Set(["read", "grep", "find", "ls", "edit", "write"]);
+
+function safeRealpath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+
+function repoRootForCwd(cwd: string): string {
+  try {
+    const root = execFileSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+    return safeRealpath(root || cwd);
+  } catch {
+    return safeRealpath(cwd);
+  }
+}
+
+function resolveCandidatePath(pathValue: string, cwd: string): string {
+  const expanded = pathValue === "~" || pathValue.startsWith("~/") ? resolve(process.env.HOME || cwd, pathValue.slice(2)) : pathValue;
+  const resolved = isAbsolute(expanded) ? resolve(expanded) : resolve(cwd, expanded || ".");
+  if (existsSync(resolved)) return safeRealpath(resolved);
+  const existingParent = safeRealpath(resolve(resolved, ".."));
+  return resolve(existingParent, resolved.split(/[\\/]/).pop() || "");
+}
+
+function pathInsideRoot(candidate: string, root: string): boolean {
+  return candidate === root || candidate.startsWith(`${root}/`);
+}
+
+function piRuntimeRoot(): string {
+  return safeRealpath(getAgentDir());
+}
+
+function pathInsideRepoOrPiRuntime(candidate: string, root: string): boolean {
+  const piRoot = piRuntimeRoot();
+  return pathInsideRoot(candidate, root) || pathInsideRoot(candidate, piRoot);
+}
+
+function repoLockPathBlock(pathValue: unknown, cwd: string): string | undefined {
+  const root = repoRootForCwd(cwd);
+  const candidate = resolveCandidatePath(typeof pathValue === "string" && pathValue.trim() ? pathValue.trim() : ".", cwd);
+  if (!pathInsideRepoOrPiRuntime(candidate, root)) return `Repo Lock blocked path outside current repository or Pi runtime: ${candidate} (repo root: ${root}; Pi runtime: ${piRuntimeRoot()})`;
+  return undefined;
+}
+
+function repoLockBashBlock(command: string, cwd: string): string | undefined {
+  const trimmed = command.trim();
+  if (!trimmed) return undefined;
+  const root = repoRootForCwd(cwd);
+  const pathCandidates = Array.from(trimmed.matchAll(/(?:^|[\s=:'"`])((?:\.{1,2}|~|\/)[^\s'"`;&|)]*)/g)).map((match) => match[1]).filter(Boolean);
+  for (const raw of pathCandidates) {
+    if (raw === "." || raw === "./") continue;
+    const cleaned = raw.replace(/[),]+$/, "");
+    if (!cleaned || cleaned.startsWith("./node_modules/.bin")) continue;
+    const candidate = resolveCandidatePath(cleaned, cwd);
+    if (!pathInsideRepoOrPiRuntime(candidate, root)) return `Repo Lock blocked bash path outside current repository or Pi runtime: ${cleaned} -> ${candidate} (repo root: ${root}; Pi runtime: ${piRuntimeRoot()})`;
+  }
+  return undefined;
+}
+
+function repoLockEnabled(settings: ReturnType<typeof loadWorkflowSettings>): boolean {
+  return settings.safety.repoLockEnabled === true;
+}
+
+const BLOCKED_EXECUTE_BASH: RegExp[] = [
+  /\brm\s+-[^\n;|&]*r[^\n;|&]*f\b/i,
+  /\bsudo\b/i,
+  /\bchmod\s+-R\b/i,
+  /\bchown\s+-R\b/i,
+  /\bgit\s+reset\b/i,
+  /\bgit\s+clean\b/i,
+  /\bgit\s+push\b/i,
+  /\bgit\s+checkout\b/i,
+  /\bgit\s+switch\b/i,
+  /\bnpm\s+install\b/i,
+  /\bpnpm\s+add\b/i,
+  /\byarn\s+add\b/i,
+  /\bpip\s+install\b/i,
+  /\bcurl\b[^\n]*\|\s*sh\b/i,
+  /\bwget\b[^\n]*\|\s*sh\b/i,
+  /\bvercel\s+deploy\b/i,
+  /\bdeploy\b/i,
+  /\bsupabase\s+db\s+push\b/i,
+  /\bsupabase\s+migration\s+up\b/i,
+  /\bmigration\b[^\n]*(run|up|execute)/i,
+];
+
+export function isBlockedExecuteCommand(command: string): boolean {
+  return BLOCKED_EXECUTE_BASH.some((pattern) => pattern.test(command));
+}
+
+function isPlanMode(mode: WorkflowState["mode"]): boolean {
+  return mode === "awaiting_plan_input" || mode === "awaiting_clarification" || mode === "planning" || mode === "plan_draft" || mode === "plan_approved";
+}
+
+function isValidatorMode(mode: WorkflowState["mode"]): boolean {
+  return mode === "reviewing" || mode === "reviewed" || mode === "validating" || mode === "revalidating" || mode === "validated" || mode === "mission_validating" || mode === "mission_revalidating" || mode === "mission_final_validating";
+}
+
+function isValidationResultMode(mode: WorkflowState["mode"]): boolean {
+  return mode === "validating" || mode === "revalidating" || mode === "mission_validating" || mode === "mission_revalidating" || mode === "mission_final_validating";
+}
+
+function isExecutionMode(mode: WorkflowState["mode"]): boolean {
+  return mode === "executing" || mode === "repairing" || mode === "mission_running" || mode === "mission_repairing";
+}
+
+function isSubagentWorker(): boolean {
+  return process.env.PI_SUBAGENT_WORKER === "1";
+}
+
+function commandBlocked(command: string, cwd?: string): boolean {
+  const settings = loadWorkflowSettings(cwd);
+  return settings.safety.blockDestructiveCommands !== false && isBlockedExecuteCommand(command);
+}
+
+function standardTodoMode(settings: ReturnType<typeof loadWorkflowSettings>): "off" | "manual" | "auto" | "required" {
+  return settings.standard.autoTodoEnabled === false || settings.standard.todoTriggerMode === "off"
+    ? "off"
+    : settings.standard.todoTriggerMode === "manual"
+      ? "manual"
+      : settings.standard.todoTriggerMode === "required"
+        ? "required"
+        : "auto";
+}
+
+function standardTaskLooksSubstantive(task: string | undefined): boolean {
+  const text = task?.trim() ?? "";
+  if (!text || text.startsWith("/")) return false;
+  if (/^(?:hi|hello|hey|thanks|thank you|ok|okay|yes|no|status|help)$/i.test(text)) return false;
+  return text.length >= 8 || text.split(/\s+/).filter(Boolean).length >= 2;
+}
+
+function standardSafeReadOnlyBash(command: string): boolean {
+  const trimmed = command.trim();
+  if (!trimmed || isBlockedExecuteCommand(trimmed)) return false;
+  return /^(?:git\s+(?:status|log|diff|show|branch|rev-parse)\b|python3?\s+-m\s+json\.tool\b|npm\s+run\s+(?:lint|test)\b|npx\s+tsc\s+--noEmit\b|tsc\s+--noEmit\b)/i.test(trimmed);
+}
+
+function validatorSafeEvidenceBash(command: string): boolean {
+  const trimmed = command.trim();
+  if (!trimmed || isBlockedExecuteCommand(trimmed)) return false;
+  if (/\b(?:install|add|update|upgrade|publish|deploy|push|reset|clean|checkout|switch|commit|merge|rebase|stash|tag|apply|am|restore|rm|mv|cp|mkdir|touch|sed\s+-i|perl\s+-pi|tee|chmod|chown|kill|open)\b/i.test(trimmed)) return false;
+  return /^(?:git\s+(?:status|log|diff|show|branch|rev-parse|ls-files)\b|npm\s+run\s+(?:typecheck|check:ts|lint|test|build)\b|npx\s+tsc\s+--noEmit\b|tsc\s+--noEmit\b|python3?\s+-m\s+json\.tool\b)/i.test(trimmed);
+}
+
+function standardTodoTitleLooksGeneric(title: string): boolean {
+  const text = title.trim().toLowerCase();
+  if (!text) return true;
+  return /^(?:understand|analy[sz]e|clarify|assess|inspect)\s+(?:the\s+)?(?:request|task|requirements?|assumptions?|context)$/.test(text)
+    || /^summari[sz]e\s+(?:the\s+)?(?:outcome|result|work)(?:\s+and\s+(?:the\s+)?(?:next\s+)?actions?)?$/.test(text)
+    || /^(?:finish|complete|finali[sz]e)$/.test(text);
+}
+
+function standardTodoLooksGeneric(todo: WorkflowState["standardTodo"]): boolean {
+  if (!todo?.items.length) return false;
+  return todo.items.length <= 3 && todo.items.every((item) => standardTodoTitleLooksGeneric(item.title));
+}
+
+function standardRequiredTodoMissing(state: WorkflowState, settings: ReturnType<typeof loadWorkflowSettings>): boolean {
+  const task = state.task ?? state.originalTask;
+  return standardTodoMode(settings) === "required"
+    && (!state.standardTodo?.items.length || standardTodoLooksGeneric(state.standardTodo))
+    && !state.standardClarificationPending
+    && state.standardClarificationStage !== "drafting"
+    && state.standardClarificationStage !== "awaiting_answer"
+    && standardTaskLooksSubstantive(task);
+}
+
+export function registerToolGuard(pi: ExtensionAPI, getState: () => WorkflowState): void {
+  pi.on("tool_call", async (event, ctx) => {
+    const state = getState();
+    const tool = event.toolName;
+    const settings = loadWorkflowSettings(ctx.cwd);
+
+    // Sub-agent child processes should obey their own --tools allow-list from the
+    // agent file. Parent workflow phase guards must not remove bash/read tools.
+    // Destructive bash remains blocked when global safety requires it.
+    if (isSubagentWorker()) {
+      if (tool === "bash") {
+        const command = String((event.input as { command?: unknown }).command ?? "");
+        if (commandBlocked(command, ctx.cwd)) return { block: true, reason: `Workflow safety blocked destructive sub-agent bash command: ${command}` };
+      }
+      return;
+    }
+
+    if (repoLockEnabled(settings)) {
+      if (PATH_SCOPED_TOOLS.has(tool)) {
+        const reason = repoLockPathBlock((event.input as { path?: unknown }).path, ctx.cwd);
+        if (reason) return { block: true, reason };
+      }
+      if (tool === "bash") {
+        const command = String((event.input as { command?: unknown }).command ?? "");
+        const reason = repoLockBashBlock(command, ctx.cwd);
+        if (reason) return { block: true, reason };
+      }
+      if (tool === "subagent") {
+        const reason = repoLockPathBlock(".", ctx.cwd);
+        if (reason) return { block: true, reason };
+      }
+    }
+
+    if (tool === STANDARD_HANDOFF_RESULT_TOOL && state.mode !== "standard") return { block: true, reason: "Standard handoff result is only available while Standard Mode is active." };
+
+    if ((tool === WORKFLOW_PLAN_RESULT_TOOL && state.mode !== "planning") || (tool === MISSION_PLAN_RESULT_TOOL && state.mode !== "mission_planning")) return { block: true, reason: `${tool} is only available during its planning phase.` };
+    if (tool === WORKFLOW_REVIEW_RESULT_TOOL && state.mode !== "reviewing" && state.mode !== "mission_plan_ready") return { block: true, reason: "workflow_review_result is only available during review phases." };
+    if (tool === WORKFLOW_EXECUTION_RESULT_TOOL && state.mode !== "executing") return { block: true, reason: "workflow_execution_result is only available during Plan execution." };
+    if (tool === MISSION_MILESTONE_RESULT_TOOL && state.mode !== "mission_running") return { block: true, reason: "mission_milestone_result is only available during Mission execution." };
+    if (tool === WORKFLOW_VALIDATION_RESULT_TOOL && !isValidationResultMode(state.mode)) return { block: true, reason: "workflow_validation_result is only available during validation phases." };
+    if (tool === WORKFLOW_REPAIR_RESULT_TOOL && state.mode !== "repairing" && state.mode !== "mission_repairing") return { block: true, reason: "workflow_repair_result is only available during repair phases." };
+
+    if (tool === "standard_todo") {
+      if (state.mode !== "standard") return { block: true, reason: "Standard Mode To Do is only available while Standard Mode is active." };
+      if (state.standardClarificationPending || state.standardClarificationStage === "drafting" || state.standardClarificationStage === "awaiting_answer") return { block: true, reason: "Standard Mode To Do is blocked until the pending Standard clarification is answered." };
+    }
+
+    if (state.mode === "standard" && tool !== "standard_todo" && standardRequiredTodoMissing(state, settings)) {
+      if (tool === "edit" || tool === "write" || tool === "subagent") return { block: true, reason: `Standard Mode ${tool} is blocked until required dynamic task-specific To Do tracking is initialized with standard_todo.` };
+      if (tool === "bash") {
+        const command = String((event.input as { command?: unknown }).command ?? "");
+        if (!standardSafeReadOnlyBash(command)) return { block: true, reason: "Standard Mode bash is blocked until required dynamic task-specific To Do tracking is initialized with standard_todo." };
+      }
+    }
+
+    if (isPlanMode(state.mode)) {
+      if (tool === "edit" || tool === "write") return { block: true, reason: `Workflow Plan Mode blocks ${tool}. Allowed tools: ${PLAN_TOOLS.join(", ")}${settings.safety.disableBashInPlanMode === false ? ", bash (safe commands)" : ""}` };
+      if (tool === "bash" && settings.safety.disableBashInPlanMode !== false) return { block: true, reason: `Workflow Plan Mode blocks bash. Allowed tools: ${PLAN_TOOLS.join(", ")}` };
+    }
+
+    if (isValidatorMode(state.mode)) {
+      if (tool === "edit" || tool === "write") return { block: true, reason: `Workflow Review/Validator Mode blocks ${tool}. Allowed tools: ${VALIDATOR_TOOLS.join(", ")}` };
+      if (tool === "bash") {
+        const command = String((event.input as { command?: unknown }).command ?? "");
+        if (!validatorSafeEvidenceBash(command)) return { block: true, reason: `Workflow Review/Validator Mode blocks unsafe bash. Allowed bash is limited to safe read-only evidence commands.` };
+      }
+    }
+
+    if ((isExecutionMode(state.mode) || isPlanMode(state.mode) || isValidatorMode(state.mode)) && tool === "bash") {
+      const command = String((event.input as { command?: unknown }).command ?? "");
+      if (commandBlocked(command, ctx.cwd)) return { block: true, reason: `Workflow safety blocked destructive or out-of-scope bash command: ${command}` };
+    }
+  });
+
+  pi.on("user_bash", (event, ctx) => {
+    const state = getState();
+    const settings = loadWorkflowSettings(ctx.cwd);
+
+    if (isSubagentWorker()) {
+      if (commandBlocked(event.command, ctx.cwd)) return { result: { output: `Workflow safety blocked destructive sub-agent command: ${event.command}`, exitCode: 1, cancelled: false, truncated: false } };
+      return;
+    }
+
+    if (repoLockEnabled(settings)) {
+      const reason = repoLockBashBlock(event.command, ctx.cwd);
+      if (reason) return { result: { output: reason, exitCode: 1, cancelled: false, truncated: false } };
+    }
+
+    if (isPlanMode(state.mode) && settings.safety.disableBashInPlanMode !== false) {
+      return { result: { output: `Workflow ${state.mode} blocks user bash: ${event.command}`, exitCode: 1, cancelled: false, truncated: false } };
+    }
+    if (isValidatorMode(state.mode) && !validatorSafeEvidenceBash(event.command)) {
+      return { result: { output: `Workflow ${state.mode} blocks unsafe user bash: ${event.command}`, exitCode: 1, cancelled: false, truncated: false } };
+    }
+    if ((isExecutionMode(state.mode) || isPlanMode(state.mode) || isValidatorMode(state.mode)) && commandBlocked(event.command, ctx.cwd)) {
+      return { result: { output: `Workflow safety blocked destructive command: ${event.command}`, exitCode: 1, cancelled: false, truncated: false } };
+    }
+  });
+}
+
+// No-op default export so this helper module can be safely auto-discovered as a Pi extension.
+export default function workflowSuiteNoopExtension(): void {}

package/extensions/workflow-validation-classifier.ts

@@ -0,0 +1,102 @@
+/**
+ * Validation failure classification for Pi Workflow Suite.
+ *
+ * Determines whether a validation failure is repairable by code changes,
+ * manual-only (visual/browser QA), or ambiguous.
+ *
+ * Extracted from workflow-modes.ts for independent testability.
+ */
+
+import type { PlanValidationStatus, WorkflowState } from "./workflow-state.js";
+
+export type ValidationFailureClassification = "manual_only" | "repairable" | "ambiguous";
+
+function structuredValidationField(text: string, label: string): string | undefined {
+  const match = text.match(new RegExp(`(?:^|\\n)\\s*(?:[-*]\\s*)?(?:\\*\\*)?${label}(?:\\*\\*)?\\s*:\\s*([^\\n]+)`, "i"));
+  return match?.[1]?.trim().toLowerCase();
+}
+
+function structuredValidationYes(text: string, label: string): boolean | undefined {
+  const value = structuredValidationField(text, label);
+  if (!value) return undefined;
+  if (/^(yes|true|y)\b/.test(value)) return true;
+  if (/^(no|false|n)\b/.test(value)) return false;
+  return undefined;
+}
+
+/**
+ * Check whether a validation report contains concrete repairable issues.
+ *
+ * Uses generic software-validation keywords only. The regex looks for
+ * build errors, type errors, test failures, missing requirements,
+ * regressions, and similar actionable findings. It deliberately
+ * excludes project-specific or content-specific keywords so the
+ * classifier works correctly across any codebase.
+ */
+export function validationReportHasRepairableIssue(text?: string): boolean {
+  if (structuredValidationYes(text ?? "", "Concrete Repairable Issue") === false) return false;
+  if (structuredValidationYes(text ?? "", "Concrete Repairable Issue") === true) return true;
+  const normalized = (text ?? "").toLowerCase();
+  if (!normalized.trim()) return false;
+  const actionable = normalized
+    .replace(/\bno (actual |concrete )?(code |repairable )?(failure|failures|issue|issues|defect|defects)\b/g, " ")
+    .replace(/\bno automated repair is needed\b/g, " ")
+    .replace(/\bno specific missing requirements? (?:is |are )?identified\b/g, " ")
+    .replace(/\bmanual[-\s]only\b/g, " ");
+  return /\b(needs? repair|needs? revision|repair pass|repairable (issue|failure|defect)|concrete (issue|failure|defect|regression)|critical issues?|must fix|required fixes|fixes required|missing requirements?|not fully meet|does not fully meet|not (a )?full final artifact|acceptable as (a )?checkpoint baseline but not (a )?(full )?final artifact|unexpected changes?|regression introduced|build (failed|error)|type error|tests? failed|new lint error|incomplete (file|artifact|implementation|coverage)|persistent artifact|structured artifact|risk register artifact|artifact required|(?:produce|create|add|write) (a )?(structured |persistent )?(risk register )?artifact|missing (file|config|import|export|declaration|function|module|dependency))\b/.test(actionable);
+}
+
+export function validationReportIsEvidenceGap(text?: string): boolean {
+  const report = text ?? "";
+  const evidenceGap = structuredValidationYes(report, "Evidence Gap");
+  const repairable = structuredValidationYes(report, "Concrete Repairable Issue");
+  if (evidenceGap === true && repairable !== true) return true;
+  const normalized = report.toLowerCase();
+  return /\b(evidence gap|evidence unavailable|insufficient evidence|could not verify|cannot verify|unable to verify|not enough evidence|provenance could not be proven)\b/.test(normalized)
+    && !validationReportHasRepairableIssue(report);
+}
+
+/**
+ * Check whether a validation report represents only a manual/visual QA caveat
+ * with no concrete repairable code issue.
+ */
+export function validationReportIsManualOnlyCaveat(text?: string): boolean {
+  const report = text ?? "";
+  const manual = structuredValidationYes(report, "Manual Verification Required");
+  const repairable = structuredValidationYes(report, "Concrete Repairable Issue");
+  if (manual === true && repairable === false) return true;
+  const normalized = report.toLowerCase();
+  if (!normalized.trim()) return false;
+  const manualCaveat = /(manual|visual|browser).{0,50}(verification|qa|inspection|confirmation)|visual[-\s]?verification caveat|pass with.{0,40}caveat|manual verification needed/.test(normalized);
+  const noConcreteRepairableIssue = /no (actual |concrete )?(code |repairable )?(failure|failures|issue|issues|defect|defects)|no (code |repairable )?failures exist|no concrete (code |repairable )?issues?|only remaining validation item is manual|only incomplete item is manual|cannot be performed through (code )?repair|out of scope for (code )?repair/.test(normalized);
+  return manualCaveat && noConcreteRepairableIssue && !validationReportHasRepairableIssue(normalized);
+}
+
+/**
+ * Classify a validation failure as manual-only, repairable, or ambiguous.
+ */
+export function classifyValidationFailure(verdict: WorkflowState["validationVerdict"], report: string): ValidationFailureClassification {
+  if (validationReportIsManualOnlyCaveat(report)) return "manual_only";
+  if (validationReportIsEvidenceGap(report)) return "ambiguous";
+  if (verdict === "FAIL" || validationReportHasRepairableIssue(report)) return "repairable";
+  return "ambiguous";
+}
+
+/**
+ * Normalize a validation verdict. A FAIL with only manual/visual QA caveats
+ * is upgraded to PARTIAL PASS because there is no concrete repairable defect.
+ */
+export function normalizeValidationVerdict(verdict: WorkflowState["validationVerdict"], report: string): WorkflowState["validationVerdict"] {
+  if (verdict === "FAIL" && validationReportIsManualOnlyCaveat(report)) return "PARTIAL PASS";
+  return verdict;
+}
+
+// Re-export the verdict-to-status helper so consumers do not need workflow-parsers.
+export function planValidationStatusForVerdict(verdict: WorkflowState["validationVerdict"]): PlanValidationStatus {
+  if (verdict === "PASS") return "pass";
+  if (verdict === "UNKNOWN" || verdict === "PARTIAL PASS") return "unknown";
+  return "fail";
+}
+
+// No-op default export so this helper module can be safely auto-discovered as a Pi extension.
+export default function workflowSuiteNoopExtension(): void {}