@yycholla/pi-dynamic-workflows 3.3.0

package/src/builtin-commands.ts

@@ -0,0 +1,286 @@
+/**
+ * Bundled workflow commands: `/deep-research`, `/adversarial-review`,
+ * `/multi-perspective`, `/code-review`, and `/codebase-audit`.
+ *
+ * Each command starts its generated workflow through the WorkflowManager's
+ * background path — the command returns immediately, progress is visible in
+ * the task panel and `/workflows` (pause/stop work like any managed run), and
+ * the report is delivered back into the conversation on completion by
+ * installResultDelivery. Running inline in the handler instead would block the
+ * whole session until the workflow finished (#104).
+ */
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import type { ExtensionAPI, ExtensionCommandContext, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { BuiltinWorkflowInvocation } from "./builtin-workflows.js";
+import { findBuiltinWorkflow } from "./builtin-workflows.js";
+import { MAX_DIFF_CHARS } from "./code-review.js";
+import { parseCommandArgs } from "./saved-commands.js";
+import type { WorkflowManager } from "./workflow-manager.js";
+import { createWorkflowStorage, type WorkflowStorage } from "./workflow-saved.js";
+
+const execFileAsync = promisify(execFile);
+
+/**
+ * Cap on the diff-source exec's stdout+stderr buffer. Node's default (1 MB)
+ * throws on anything but a small diff — `gh pr diff` on a sizeable PR routinely
+ * exceeds it. 64 MB comfortably covers any realistic diff while still bounding
+ * worst-case memory; the prompt-side cap (code-review.ts's MAX_DIFF_CHARS) is
+ * what actually protects the review from a huge diff, not this buffer.
+ */
+const DIFF_EXEC_MAX_BUFFER = 64 * 1024 * 1024;
+
+function alreadyRegistered(pi: ExtensionAPI, name: string): boolean {
+  try {
+    return (pi.getCommands?.() ?? []).some((c: { name: string }) => c.name === name);
+  } catch {
+    return false;
+  }
+}
+
+/** Split a command argument string into tokens, respecting single/double quotes. */
+function tokenizeArgs(input: string): string[] {
+  const tokens: string[] = [];
+  for (const m of input.matchAll(/"([^"]*)"|'([^']*)'|(\S+)/g)) {
+    tokens.push(m[1] ?? m[2] ?? m[3] ?? "");
+  }
+  return tokens;
+}
+
+/**
+ * Start a built-in workflow through the manager's background path and tell the
+ * user where to watch it. startInBackground can throw synchronously (script
+ * parse, run lease) — surface that as a notify instead of an unhandled error.
+ * Async failures are handled by the manager's generic delivery ("✗ Background
+ * workflow … failed"), so no handler-side await is needed — that await is
+ * exactly what used to hang the session (#104).
+ */
+function startBackground(
+  manager: WorkflowManager,
+  ctx: ExtensionCommandContext,
+  name: string,
+  script: string,
+  args?: unknown,
+  exec?: { tools?: ToolDefinition[]; toolset?: string },
+): void {
+  try {
+    const { runId } = manager.startInBackground(script, args, exec ?? {});
+    ctx.ui.notify(
+      `/${name} running in the background (${runId}) — watch the task panel or /workflows; the report is posted here when it finishes.`,
+      "info",
+    );
+  } catch (error) {
+    ctx.ui.notify(`${name} failed to start: ${error instanceof Error ? error.message : error}`, "error");
+  }
+}
+
+/**
+ * Look up a built-in descriptor by its fixed, hardcoded name. Every call site
+ * below passes one of the 5 literal names in BUILTIN_WORKFLOWS, so this can
+ * only throw if that registry and this file's command names fall out of sync
+ * — a programming error, not a user-input problem (tests pin the names stay
+ * in sync, see builtin-commands.test.ts).
+ */
+function requireBuiltin(name: string) {
+  const found = findBuiltinWorkflow(name);
+  if (!found) throw new Error(`internal error: no built-in workflow registered for "${name}"`);
+  return found;
+}
+
+/**
+ * Resolve a built-in's script/exec context for the given args, surfacing an
+ * invalid-args error (e.g. a whitespace-only string that passes the handler's
+ * cheap `!value` check but fails the registry's real validation) as the same
+ * kind of warning notify the handlers already use for their own validation,
+ * rather than an uncaught rejection.
+ */
+function resolveBuiltinOrNotify(
+  name: string,
+  cwd: string,
+  args: unknown,
+  ctx: ExtensionCommandContext,
+): BuiltinWorkflowInvocation | undefined {
+  try {
+    return requireBuiltin(name).resolve(cwd, args);
+  } catch (error) {
+    ctx.ui.notify(`/${name}: ${error instanceof Error ? error.message : String(error)}`, "warning");
+    return undefined;
+  }
+}
+
+export function registerBuiltinWorkflows(
+  pi: ExtensionAPI,
+  opts: { cwd: string; manager: WorkflowManager; storage?: WorkflowStorage },
+): void {
+  const { cwd, manager } = opts;
+  const storage = opts.storage ?? createWorkflowStorage(cwd);
+
+  /**
+   * A project/user saved workflow always takes precedence over a built-in of
+   * the same name — on every path, not just the `workflow` tool's `name`
+   * input. Builtins are registered as commands before saved workflows
+   * (registerAllSavedWorkflows skips a name that's already registered), so
+   * without this dynamic check a same-named saved workflow would silently
+   * never run from its slash command. Checking here, at invocation time
+   * rather than registration time, makes "saved wins" hold regardless of
+   * registration order. Mirrors registerSavedWorkflow's own handler exactly
+   * (same parseCommandArgs call, same startBackground path, no builtin exec
+   * context) so a shadowed command behaves identically to how it would if the
+   * saved workflow itself had been registered under this name.
+   */
+  function runSavedShadowIfPresent(name: string, rawArgs: string, ctx: ExtensionCommandContext): boolean {
+    const saved = storage.load(name);
+    if (!saved) return false;
+    startBackground(manager, ctx, name, saved.script, parseCommandArgs(rawArgs, saved.parameters));
+    return true;
+  }
+
+  if (!alreadyRegistered(pi, "deep-research")) {
+    pi.registerCommand("deep-research", {
+      description: "Research a question across the web with cross-checked sources",
+      async handler(args: string, ctx: ExtensionCommandContext) {
+        if (runSavedShadowIfPresent("deep-research", args, ctx)) return;
+        const question = args.trim();
+        if (!question) return ctx.ui.notify("Usage: /deep-research <question>", "warning");
+        // Resolve through the shared builtin registry (builtin-workflows.ts) so
+        // this command and the workflow tool's `name` input always run the exact
+        // same generated script and exec context (tools/toolset) for this pattern.
+        const resolved = resolveBuiltinOrNotify("deep-research", cwd, { question }, ctx);
+        if (!resolved) return;
+        startBackground(
+          manager,
+          ctx,
+          "deep-research",
+          resolved.script,
+          { question },
+          {
+            tools: resolved.tools,
+            toolset: resolved.toolset,
+          },
+        );
+      },
+    });
+  }
+
+  if (!alreadyRegistered(pi, "adversarial-review")) {
+    pi.registerCommand("adversarial-review", {
+      description: "Investigate a task, then cross-check each finding with skeptical reviewers",
+      async handler(args: string, ctx: ExtensionCommandContext) {
+        if (runSavedShadowIfPresent("adversarial-review", args, ctx)) return;
+        const task = args.trim();
+        if (!task) return ctx.ui.notify("Usage: /adversarial-review <task or question>", "warning");
+        const resolved = resolveBuiltinOrNotify("adversarial-review", cwd, { task }, ctx);
+        if (!resolved) return;
+        startBackground(manager, ctx, "adversarial-review", resolved.script, { task });
+      },
+    });
+  }
+
+  if (!alreadyRegistered(pi, "code-review")) {
+    pi.registerCommand("code-review", {
+      description:
+        "Multi-angle parallel code review: 7 specialized finders (correctness, reuse, simplification, efficiency, altitude) + verify pass → ranked findings",
+      async handler(args: string, ctx: ExtensionCommandContext) {
+        if (runSavedShadowIfPresent("code-review", args, ctx)) return;
+        const input = args.trim();
+        let diffSource = "git diff HEAD";
+        let diff = "";
+
+        try {
+          let cmd: string;
+          let cmdArgs: string[];
+          if (!input) {
+            diffSource = "git diff HEAD";
+            cmd = "git";
+            cmdArgs = ["diff", "HEAD"];
+          } else if (/^\d+$/.test(input)) {
+            diffSource = `gh pr diff ${input}`;
+            cmd = "gh";
+            cmdArgs = ["pr", "diff", input];
+          } else if (input.includes("..")) {
+            diffSource = `git diff ${input}`;
+            cmd = "git";
+            cmdArgs = ["diff", input];
+          } else {
+            diffSource = `git diff HEAD -- ${input}`;
+            cmd = "git";
+            cmdArgs = ["diff", "HEAD", "--", input];
+          }
+          // execFile (not exec/shell) + array args: input can't break out into a
+          // shell command. maxBuffer raised well past Node's 1MB default so a
+          // large `gh pr diff` doesn't throw ERR_CHILD_PROCESS_STDOUT_MAXBUFFER.
+          const { stdout } = await execFileAsync(cmd, cmdArgs, { cwd, maxBuffer: DIFF_EXEC_MAX_BUFFER });
+          diff = stdout;
+          if (!diff.trim()) {
+            return ctx.ui.notify(`No diff output from: ${diffSource}`, "warning");
+          }
+        } catch (err) {
+          const code = (err as NodeJS.ErrnoException | undefined)?.code;
+          if (code === "ERR_CHILD_PROCESS_STDOUT_MAXBUFFER") {
+            return ctx.ui.notify(
+              `Diff from ${diffSource} exceeds the ${Math.floor(DIFF_EXEC_MAX_BUFFER / (1024 * 1024))}MB capture limit — ` +
+                `narrow the target (e.g. a specific file or path) and try again.`,
+              "error",
+            );
+          }
+          return ctx.ui.notify(
+            `Failed to get diff (${diffSource}): ${err instanceof Error ? err.message : err}`,
+            "error",
+          );
+        }
+
+        // The workflow itself also caps prompt size (MAX_DIFF_CHARS), but truncating
+        // here lets us tell the user clearly rather than have it happen silently deep
+        // inside the generated script.
+        const originalLength = diff.length;
+        if (originalLength > MAX_DIFF_CHARS) {
+          diff = diff.slice(0, MAX_DIFF_CHARS);
+          ctx.ui.notify(
+            `Diff is ${originalLength.toLocaleString()} characters — truncated to the first ` +
+              `${MAX_DIFF_CHARS.toLocaleString()} for the review. Findings past the cut are not covered.`,
+            "warning",
+          );
+        }
+
+        const resolved = resolveBuiltinOrNotify("code-review", cwd, { diff, diffSource }, ctx);
+        if (!resolved) return;
+        startBackground(manager, ctx, "code-review", resolved.script, { diff, diffSource });
+      },
+    });
+  }
+
+  if (!alreadyRegistered(pi, "multi-perspective")) {
+    pi.registerCommand("multi-perspective", {
+      description: "Analyze a topic from several independent perspectives in parallel, then synthesize",
+      async handler(args: string, ctx: ExtensionCommandContext) {
+        if (runSavedShadowIfPresent("multi-perspective", args, ctx)) return;
+        const [topic, ...rest] = tokenizeArgs(args);
+        if (!topic) {
+          return ctx.ui.notify('Usage: /multi-perspective "<topic>" [perspective1] [perspective2] …', "warning");
+        }
+        // resolve() falls back to a broadly-useful default set when fewer than
+        // two perspectives are given (see builtin-workflows.ts).
+        const resolved = resolveBuiltinOrNotify("multi-perspective", cwd, { topic, perspectives: rest }, ctx);
+        if (!resolved) return;
+        startBackground(manager, ctx, "multi-perspective", resolved.script);
+      },
+    });
+  }
+
+  if (!alreadyRegistered(pi, "codebase-audit")) {
+    pi.registerCommand("codebase-audit", {
+      description: "Run parallel checks against a codebase scope, then cross-validate and report",
+      async handler(args: string, ctx: ExtensionCommandContext) {
+        if (runSavedShadowIfPresent("codebase-audit", args, ctx)) return;
+        const [scope, ...checks] = tokenizeArgs(args);
+        if (!scope || checks.length === 0) {
+          return ctx.ui.notify('Usage: /codebase-audit <scope> "<check1>" ["<check2>" …]', "warning");
+        }
+        const resolved = resolveBuiltinOrNotify("codebase-audit", cwd, { scope, checks }, ctx);
+        if (!resolved) return;
+        startBackground(manager, ctx, "codebase-audit", resolved.script);
+      },
+    });
+  }
+}

package/src/builtin-workflows.ts

@@ -0,0 +1,155 @@
+/**
+ * Shared registry of the 5 curated built-in workflow patterns
+ * (`deep-research`, `adversarial-review`, `code-review`, `multi-perspective`,
+ * `codebase-audit`).
+ *
+ * This is the single place that turns a pattern's name + caller-supplied args
+ * into a runnable script (and, where a pattern needs it, an exec context such
+ * as web tools). Both entry points a model or user can reach a built-in
+ * through — the `/deep-research`-style slash commands (builtin-commands.ts)
+ * and the `workflow` tool's `name` input (workflow-tool.ts) — resolve through
+ * this one registry, so the two paths can never drift apart and the
+ * per-pattern generator scripts are written exactly once.
+ */
+
+import { createCodingTools, type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { generateAdversarialReviewWorkflow, generateMultiPerspectiveWorkflow } from "./adversarial-review.js";
+import { generateCodeReviewWorkflow } from "./code-review.js";
+import { generateCodebaseAuditWorkflow, generateDeepResearchWorkflow } from "./deep-research.js";
+import { createWebTools } from "./web-tools.js";
+import type { WorkflowStorage } from "./workflow-saved.js";
+
+/** Default perspective set used when a caller gives fewer than two. */
+export const DEFAULT_MULTI_PERSPECTIVES: readonly string[] = [
+  "technical",
+  "product",
+  "security",
+  "user experience",
+  "maintainability",
+];
+
+/** A resolved, ready-to-run script plus the exec context it needs (if any). */
+export interface BuiltinWorkflowInvocation {
+  script: string;
+  tools?: ToolDefinition[];
+  toolset?: string;
+}
+
+export interface BuiltinWorkflowDescriptor {
+  /** Also the slash-command name (without the leading `/`). */
+  name: string;
+  description: string;
+  /** Build the script (and exec context) for one invocation; throws on invalid `args`. */
+  resolve(cwd: string, args: unknown): BuiltinWorkflowInvocation;
+}
+
+function asRecord(args: unknown): Record<string, unknown> {
+  return args && typeof args === "object" ? (args as Record<string, unknown>) : {};
+}
+
+function requireNonEmptyString(value: unknown, argName: string, patternName: string): string {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`Built-in workflow "${patternName}" requires args.${argName} to be a non-empty string.`);
+  }
+  return value;
+}
+
+function requireStringArray(value: unknown, argName: string, patternName: string): string[] {
+  if (!Array.isArray(value) || value.length === 0 || !value.every((v) => typeof v === "string" && v.trim())) {
+    throw new Error(
+      `Built-in workflow "${patternName}" requires args.${argName} to be a non-empty array of non-empty strings.`,
+    );
+  }
+  return value;
+}
+
+/** The 5 curated built-in workflow patterns, keyed by their stable name. */
+export const BUILTIN_WORKFLOWS: readonly BuiltinWorkflowDescriptor[] = [
+  {
+    name: "deep-research",
+    description: "Research a question across the web with cross-checked sources. args: { question: string }.",
+    resolve(cwd, args) {
+      requireNonEmptyString(asRecord(args).question, "question", "deep-research");
+      return {
+        script: generateDeepResearchWorkflow(),
+        // Research agents need real web access on top of the coding tools; the
+        // "web-research" tag is what a resumed run re-resolves (see
+        // WorkflowManagerOptions.toolsets).
+        tools: [...createCodingTools(cwd), ...createWebTools()],
+        toolset: "web-research",
+      };
+    },
+  },
+  {
+    name: "adversarial-review",
+    description:
+      "Investigate a task, then cross-check each finding with skeptical reviewers. args: { task: string, reviewers?: number, threshold?: number }.",
+    resolve(_cwd, args) {
+      requireNonEmptyString(asRecord(args).task, "task", "adversarial-review");
+      return { script: generateAdversarialReviewWorkflow() };
+    },
+  },
+  {
+    name: "code-review",
+    description:
+      "Multi-angle parallel code review: 7 specialized finders (correctness, reuse, simplification, efficiency, altitude) + verify pass → ranked findings. args: { diff: string, diffSource?: string }.",
+    resolve(_cwd, args) {
+      // Truncation past MAX_DIFF_CHARS already happens inside the generated
+      // script at runtime (see code-review.ts); a caller invoking by name is
+      // responsible for supplying `diff` (e.g. by running `git diff` itself),
+      // unlike the /code-review slash command, which fetches it automatically.
+      requireNonEmptyString(asRecord(args).diff, "diff", "code-review");
+      return { script: generateCodeReviewWorkflow() };
+    },
+  },
+  {
+    name: "multi-perspective",
+    description:
+      "Analyze a topic from several independent perspectives in parallel, then synthesize. args: { topic: string, perspectives?: string[] }.",
+    resolve(_cwd, args) {
+      const record = asRecord(args);
+      const topic = requireNonEmptyString(record.topic, "topic", "multi-perspective");
+      const perspectives =
+        Array.isArray(record.perspectives) && record.perspectives.length >= 2
+          ? requireStringArray(record.perspectives, "perspectives", "multi-perspective")
+          : [...DEFAULT_MULTI_PERSPECTIVES];
+      return { script: generateMultiPerspectiveWorkflow(topic, perspectives) };
+    },
+  },
+  {
+    name: "codebase-audit",
+    description:
+      "Run parallel checks against a codebase scope, then cross-validate and report. args: { scope: string, checks: string[] }.",
+    resolve(_cwd, args) {
+      const record = asRecord(args);
+      const scope = requireNonEmptyString(record.scope, "scope", "codebase-audit");
+      const checks = requireStringArray(record.checks, "checks", "codebase-audit");
+      return { script: generateCodebaseAuditWorkflow(scope, checks) };
+    },
+  },
+];
+
+/** Stable list of built-in workflow pattern names, in registry order. */
+export const BUILTIN_WORKFLOW_NAMES: readonly string[] = BUILTIN_WORKFLOWS.map((w) => w.name);
+
+export function findBuiltinWorkflow(name: string): BuiltinWorkflowDescriptor | undefined {
+  return BUILTIN_WORKFLOWS.find((w) => w.name === name);
+}
+
+/**
+ * Resolve a name to a runnable invocation, checking project/user saved
+ * workflows first and falling back to the built-in patterns — the same
+ * precedence `workflow-saved.ts` already uses internally (project > user), one
+ * level up: saved workflows (of either scope) beat a built-in of the same name.
+ */
+export function resolveWorkflowInvocation(
+  name: string,
+  args: unknown,
+  ctx: { storage: WorkflowStorage; cwd: string },
+): BuiltinWorkflowInvocation | undefined {
+  const saved = ctx.storage.load(name);
+  if (saved) return { script: saved.script };
+  const builtin = findBuiltinWorkflow(name);
+  if (builtin) return builtin.resolve(ctx.cwd, args);
+  return undefined;
+}

package/src/code-review.ts

@@ -0,0 +1,183 @@
+/**
+ * Multi-angle parallel code review workflow.
+ * 7 specialized finder agents → verify pass → ranked report.
+ */
+
+/**
+ * Hard cap on diff characters fed into the review. This bounds worst-case
+ * prompt size across 7 parallel finders + a per-candidate verify pass, even
+ * when the diff-source exec step (see builtin-commands.ts) already raised its
+ * own maxBuffer and successfully read a very large diff. Oversized diffs are
+ * truncated rather than rejected — findings in the untruncated prefix still
+ * have value — and the truncation is surfaced to the user, not silent.
+ */
+export const MAX_DIFF_CHARS = 200_000;
+
+/**
+ * Generate a code-review workflow script.
+ *
+ * The workflow expects `args` to be passed with shape:
+ *   { diff: string, diffSource: string }
+ *
+ * Model tier routing follows the spec:
+ *   Finders A/B/C → medium (correctness)
+ *   Finders D/E/F → small  (cleanup)
+ *   Finder  G     → big    (altitude / abstraction)
+ *   Synthesis     → big
+ */
+export function generateCodeReviewWorkflow(): string {
+  return `export const meta = {
+  name: 'code_review',
+  description: 'Multi-angle parallel code review: 7 finder angles + verify pass → ranked findings',
+  phases: [
+    { title: 'Find' },
+    { title: 'Verify' },
+    { title: 'Report' },
+  ],
+}
+
+const MAX_DIFF_CHARS = ${MAX_DIFF_CHARS}
+const rawDiff = (args && args.diff) || ''
+const diffSource = (args && args.diffSource) || 'git diff HEAD'
+const diffTruncated = rawDiff.length > MAX_DIFF_CHARS
+const diff = diffTruncated ? rawDiff.slice(0, MAX_DIFF_CHARS) : rawDiff
+if (diffTruncated) {
+  log(
+    'Diff truncated for review: showing the first ' + MAX_DIFF_CHARS + ' of ' + rawDiff.length +
+    ' characters (' + (rawDiff.length - MAX_DIFF_CHARS) + ' omitted). Findings past the cut are not covered.'
+  )
+}
+const candidateSchema = {
+  type: 'object',
+  properties: {
+    candidates: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          file: { type: 'string' },
+          line: { type: 'number' },
+          summary: { type: 'string' },
+          failure_scenario: { type: 'string' },
+        },
+        required: ['file', 'line', 'summary', 'failure_scenario'],
+      },
+    },
+  },
+  required: ['candidates'],
+}
+
+const diffBlock = '\\n\\n<diff source=\\"' + diffSource + '\\"' + (diffTruncated ? ' truncated=\\"true\\"' : '') + '>\\n' +
+  diff + (diffTruncated ? '\\n\\n[... diff truncated: ' + (rawDiff.length - MAX_DIFF_CHARS) + ' more characters omitted ...]' : '') +
+  '\\n</diff>\\n'
+const base = 'Use the read/grep tools to pull in any additional file context you need.' + diffBlock
+
+phase('Find')
+const finders = await parallel([
+  () => agent(
+    'You are a line-by-line correctness scanner. Hunt ONLY for: inverted conditions, off-by-one errors, ' +
+    'null/nil dereferences, wrong variable used, swallowed errors. For each candidate name the exact file, ' +
+    'line number, a one-line summary, and the concrete failure scenario. Return ONLY issues you can justify ' +
+    'with a line in the diff.' + base,
+    { label: 'A-line-scan', tier: 'medium', schema: candidateSchema }
+  ),
+  () => agent(
+    'You are a removed-behavior auditor. For every deleted line or block in the diff: name the invariant ' +
+    'or contract it enforced, then find where (or prove) that contract is re-established elsewhere. ' +
+    'Report only gaps where the invariant is NOT re-established.' + base,
+    { label: 'B-removed-behavior', tier: 'medium', schema: candidateSchema }
+  ),
+  () => agent(
+    'You are a cross-file call-site tracer. For each function/method whose signature or behavior changed ' +
+    'in the diff: grep the codebase for callers, then check whether each call site is still correct after ' +
+    'the change. Report only call sites that are now broken or need updating.' + base,
+    { label: 'C-cross-file-tracer', tier: 'medium', schema: candidateSchema }
+  ),
+  () => agent(
+    'You are a reuse finder. Identify new code in the diff that duplicates existing helpers, utilities, ' +
+    'or patterns already present in the codebase. Propose the existing symbol that should be used instead.' + base,
+    { label: 'D-reuse', tier: 'small', schema: candidateSchema }
+  ),
+  () => agent(
+    'You are a simplification finder. Look for: redundant state that could be derived, copy-paste ' +
+    'variation that could be a shared function, and dead code introduced by the diff.' + base,
+    { label: 'E-simplification', tier: 'small', schema: candidateSchema }
+  ),
+  () => agent(
+    'You are an efficiency finder. Identify: redundant I/O or network calls, sequential work that could ' +
+    'be parallel, and blocking operations on the startup or hot path introduced by the diff.' + base,
+    { label: 'F-efficiency', tier: 'small', schema: candidateSchema }
+  ),
+  () => agent(
+    'You are an altitude reviewer. Assess whether the change is made at the RIGHT abstraction level. ' +
+    'Look for: bandaids on shared infrastructure that should be fixed at the root, fixes in the wrong ' +
+    'layer (e.g. compensating in the UI for a data model problem), or the change solving a symptom ' +
+    'rather than the cause.' + base,
+    { label: 'G-altitude', tier: 'big', schema: candidateSchema }
+  ),
+])
+
+// Collect and deduplicate candidates across all finders
+const allRaw = finders.flatMap((r, fi) => {
+  const label = ['A','B','C','D','E','F','G'][fi]
+  return ((r && r.candidates) || []).map((c) => ({ ...c, angle: label }))
+})
+
+// Deduplicate: same file + line + first 40 chars of summary → keep first
+const seen = new Set()
+const allCandidates = allRaw.filter((c) => {
+  const key = (c.file || '') + ':' + (c.line || 0) + ':' + (c.summary || '').slice(0, 40)
+  if (seen.has(key)) return false
+  seen.add(key)
+  return true
+})
+
+phase('Verify')
+// NOTE: deliberately NOT using the verify() stdlib helper here. verify() only
+// returns a boolean real/not-real vote; this phase needs the 3-way
+// CONFIRMED/PLAUSIBLE/REFUTED verdict so the synthesis report can hedge
+// ("worth a second look" vs "will break"). Since only REFUTED is filtered out
+// below, verify()'s boolean would collapse CONFIRMED and PLAUSIBLE into one
+// bucket and lose that signal for no behavioral gain — verify({reviewers: 1})
+// is already a single agent() call under the hood, same as this.
+const verdicts = allCandidates.length > 0
+  ? await parallel(allCandidates.map((c, i) => () =>
+      agent(
+        'You are a verifier. Determine whether this code review finding is CONFIRMED, PLAUSIBLE, or REFUTED. ' +
+        'CONFIRMED = you can trace the exact failure in the diff. PLAUSIBLE = concern is valid but not certain. ' +
+        'REFUTED = finding is wrong or already handled.\\n\\n' +
+        'FINDING:\\nFile: ' + c.file + '\\nLine: ' + c.line + '\\nSummary: ' + c.summary + '\\n' +
+        'Failure scenario: ' + c.failure_scenario + diffBlock,
+        {
+          label: 'verify-' + (i + 1),
+          schema: {
+            type: 'object',
+            properties: { verdict: { type: 'string', enum: ['CONFIRMED', 'PLAUSIBLE', 'REFUTED'] }, reason: { type: 'string' } },
+            required: ['verdict'],
+          },
+        }
+      )
+    ))
+  : []
+
+const surviving = allCandidates
+  .map((c, i) => ({ ...c, verdict: (verdicts[i] && verdicts[i].verdict) || 'PLAUSIBLE', verifyReason: (verdicts[i] && verdicts[i].reason) || '' }))
+  .filter((c) => c.verdict !== 'REFUTED')
+
+// Rank: correctness (A/B/C) before cleanup (D/E/F) before altitude (G), cap at 10
+const rankAngle = (a) => ['A','B','C'].includes(a) ? 0 : ['D','E','F'].includes(a) ? 1 : 2
+surviving.sort((a, b) => rankAngle(a.angle) - rankAngle(b.angle))
+const top = surviving.slice(0, 10)
+
+phase('Report')
+const synthesis = await agent(
+  'You are a senior code reviewer writing the final report. Below are the verified findings from a ' +
+  'multi-angle code review (already ranked by severity). Write a concise markdown report: ' +
+  '1 sentence per finding with file, line, and the failure scenario. Note the total found vs shown. ' +
+  'Correctness issues (A/B/C) come first, then cleanup (D/E/F), then altitude (G).\\n\\n' +
+  'FINDINGS JSON:\\n' + JSON.stringify(top, null, 2),
+  { label: 'synthesis', tier: 'big' }
+)
+
+return { total: allCandidates.length, surviving: surviving.length, findings: top, report: synthesis, diffTruncated }`;
+}

package/src/config.ts

@@ -0,0 +1,55 @@
+/**
+ * Configuration constants for pi-dynamic-workflows.
+ */
+
+/** Maximum number of agents allowed per workflow run. */
+export const MAX_AGENTS_PER_RUN = 1000;
+
+/** Default timeout for a single agent in milliseconds. null means no hard timeout. */
+export const DEFAULT_AGENT_TIMEOUT_MS = null;
+
+/** Maximum concurrent agents (matches Claude Code limit). */
+export const MAX_CONCURRENCY = 16;
+
+/** Maximum automatic retry attempts after a recoverable agent failure. */
+export const MAX_AGENT_RETRIES = 3;
+
+/** Default token budget if none specified. */
+export const DEFAULT_TOKEN_BUDGET = null;
+
+/** Legacy project-relative directory for persisted workflow run state. New writes use workflowProjectPaths(). */
+export const WORKFLOW_RUNS_DIR = ".pi/workflows/runs";
+
+/** Legacy project-relative directory for saved workflow commands. New writes use workflowProjectPaths(). */
+export const WORKFLOW_SAVED_DIR = ".pi/workflows/saved";
+
+/** User-level saved workflows directory. */
+export const USER_WORKFLOW_SAVED_DIR = "~/.pi/workflows/saved";
+
+/** User-level model tiers config file, relative to the home directory. */
+export const MODEL_TIERS_FILE = ".pi/workflows/model-tiers.json";
+
+/** User-level workflow extension settings file, relative to the home directory. */
+export const WORKFLOW_SETTINGS_FILE = ".pi/workflows/settings.json";
+
+/** Default keyword that arms workflows mode from interactive input. */
+export const DEFAULT_KEYWORD_TRIGGER_WORD = "workflow";
+
+/** Normalize a user-configured keyword trigger word. */
+export function normalizeKeywordTriggerWord(value: unknown): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const word = value.trim();
+  if (!word || word.startsWith("/") || /\s/.test(word)) return undefined;
+  return word;
+}
+
+/**
+ * Named workflow subagent definitions directory. Resolved project-relative
+ * (cwd/.pi/agents), plus user-level at `~/.pi/agent/agents/` (the primary
+ * location, via `getAgentDir()` in agent-registry.ts) with the legacy
+ * `~/.pi/agents/` (this constant, home-relative) scanned as a deprecated
+ * fallback. Project entries win on name collision, then the primary user
+ * location, then the legacy one. Each `*.md` file is an agent definition
+ * (frontmatter + body prompt).
+ */
+export const AGENTS_DIR = ".pi/agents";