pi-taskflow 0.0.13 → 0.0.15

package/README.md

@@ -7,7 +7,9 @@
   <a href="https://www.npmjs.com/package/pi-taskflow"><img src="https://img.shields.io/npm/dm/pi-taskflow?style=flat-square&color=6E8BFF&label=downloads" alt="npm downloads"></a>
   <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-43D9AD?style=flat-square" alt="MIT license"></a>
   <a href="#whats-inside"><img src="https://img.shields.io/badge/runtime%20deps-0-43D9AD?style=flat-square" alt="zero runtime dependencies"></a>
-  <a href="#whats-inside"><img src="https://img.shields.io/badge/tests-371-6E8BFF?style=flat-square" alt="371 tests"></a>
+  <a href="https://github.com/heggria/pi-taskflow/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/heggria/pi-taskflow/ci.yml?branch=main&style=flat-square&label=CI" alt="CI status"></a>
+  <a href="#whats-inside"><img src="https://img.shields.io/badge/tests-394-6E8BFF?style=flat-square" alt="394 tests"></a>
+  <a href="#whats-inside"><img src="https://img.shields.io/badge/dogfooded-%E2%9C%93-43D9AD?style=flat-square" alt="dogfooded"></a>
   <a href="https://pi.dev"><img src="https://img.shields.io/badge/for-Pi%20coding%20agent-B692FF?style=flat-square" alt="for the Pi coding agent"></a>
 </p>
 
@@ -574,7 +576,7 @@ Copy one into `.pi/taskflows/<name>.json` (or `~/.pi/agent/taskflows/`) and it r
 
 <div align="center">
 
-**0 runtime dependencies** · **371 tests** · **10 phase types** · **cross-session resume** · **cross-run memoization** · **~4.9k LOC runtime**
+**0 runtime dependencies** · **394 tests** · **10 phase types** · **cross-session resume** · **cross-run memoization** · **~4.9k LOC runtime**
 
 </div>
 
@@ -583,7 +585,21 @@ Copy one into `.pi/taskflows/<name>.json` (or `~/.pi/agent/taskflows/`) and it r
 - **Hardened by design.** Path-traversal defense (lexical + `realpath`), runId validation, HTML/error sanitization, atomic writes, stale-lock stealing via `rename`, and an idle watchdog that kills wedged subagents.
 - **Dogfooded.** Every new feature has to survive the project's own `self-improve` taskflow before it ships.
 
-If this saves you a context window, **drop a ⭐ on [GitHub](https://github.com/heggria/pi-taskflow)** — it genuinely helps.
+## 🍽️ We eat our own dog food
+
+Every feature in `pi-taskflow` ships **through `pi-taskflow`.**
+
+Our `self-improve` flow is a 10-phase DAG — it audits the codebase, patches defects, verifies correctness, gates on quality, and surfaces the report — all declaratively. It's saved as `/tf:self-improve` and run before every release. No other agent orchestrator in the Pi ecosystem builds itself with itself.
+
+| Campaign | Scale | Phases | Outcome |
+|----------|-------|--------|---------|
+| [v0.0.8 dogfood](./docs/dogfooding-v0.0.8-report.md) | Full codebase audit → triage → fix → verify | 10 phases, 234 tests | 13 fixes, all pass |
+| [v0.0.6 self-audit](./docs/self-audit-report.md) | inventory → map audit → gate → approval → map fix → reduce | 9 phases | 11 critical defects fixed |
+| [Cross-run cache dogfood](./docs/rfc-cross-run-memoization.md) | Real runtime + on-disk store | Dedicated test harness | Cache correctness under adversarial fingerprints |
+| [Adversarial cross-review](./docs/brainstorm-adversarial-review-report.md) | Multi-agent adversarial review | `tournament` + `gate` | P0 cache-key fix shipped |
+| [Init redesign review](./docs/issue-necessity-review-report.md) | Necessity audit → parallel checks → verdict | 7 phases | Full redesign plan validated |
+
+> **Meta:** we used `pi-taskflow`'s `map` fan-out, `gate` verdicts, `approval` human-in-the-loop, `tournament` best-of-N, `loop` until-done, and `cross-run` cache — to build `pi-taskflow`.
 
 ## Status & limits
 

package/extensions/agents.ts

@@ -208,3 +208,50 @@ export function readSubagentSettings(): SubagentSettings {
 		return {};
 	}
 }
+
+/**
+ * Copy the 18 built-in agents from extensions/agents/*.md into the project's
+ * .pi/agents/ directory so Pi's native subagent tool (and any other extension)
+ * can discover them. taskflow's own discoverAgents() already reads from this
+ * directory with lower priority than built-in, so the copy is a no-op for
+ * taskflow phases — it only matters for Pi's native agent discovery.
+ *
+ * Idempotent: only copies agents whose built-in source is newer than the
+ * project copy (or that don't exist yet).
+ */
+export function syncBuiltinAgentsToProject(cwd: string): void {
+	const builtInDir = path.resolve(import.meta.dirname, "agents");
+	if (!fs.existsSync(builtInDir)) return;
+
+	const projectAgentsDir = path.join(cwd, ".pi", "agents");
+	fs.mkdirSync(projectAgentsDir, { recursive: true });
+
+	let entries: fs.Dirent[];
+	try {
+		entries = fs.readdirSync(builtInDir, { withFileTypes: true });
+	} catch {
+		return;
+	}
+
+	for (const entry of entries) {
+		if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
+		const src = path.join(builtInDir, entry.name);
+		const dst = path.join(projectAgentsDir, entry.name);
+
+		let srcMtime = 0;
+		try { srcMtime = fs.statSync(src).mtimeMs; } catch { continue; }
+
+		let dstMtime = 0;
+		try { dstMtime = fs.statSync(dst).mtimeMs; } catch { /* dst doesn't exist yet */ }
+
+		// Only copy when the source is newer (or the destination is missing).
+		if (srcMtime <= dstMtime) continue;
+
+		try {
+			const content = fs.readFileSync(src, "utf-8");
+			fs.writeFileSync(dst, content, "utf-8");
+		} catch {
+			// Best-effort: a locked file must not block the sync.
+		}
+	}
+}

package/extensions/index.ts

@@ -24,7 +24,7 @@ import {
 	runInteractiveInit,
 } from "./init.ts";
 import { Type } from "typebox";
-import { type AgentScope, discoverAgents, readSubagentSettings } from "./agents.ts";
+import { type AgentScope, discoverAgents, readSubagentSettings, syncBuiltinAgentsToProject } from "./agents.ts";
 import { renderRunResult, summarizeRun } from "./render.ts";
 import { RunHistoryComponent, type RunHistoryResult } from "./runs-view.ts";
 import { executeTaskflow, type ApprovalDecision, type ApprovalRequest, type RuntimeResult } from "./runtime.ts";
@@ -60,7 +60,7 @@ const ShorthandStep = Type.Object(
 );
 
 const TaskflowParams = Type.Object({
-	action: StringEnum(["run", "save", "resume", "list", "agents", "init", "cache-clear"] as const, {
+	action: StringEnum(["run", "save", "resume", "list", "agents", "init", "verify", "cache-clear"] as const, {
 		description: "What to do: run a flow, save a definition, resume a paused run, list saved flows, list available agents, init model role configuration, or clear the cross-run memoization cache",
 		default: "run",
 	}),
@@ -255,6 +255,16 @@ export default function (pi: ExtensionAPI) {
 	pi.on("session_start", async (_e, ctx) => {
 		registerSavedFlowCommands(ctx);
 
+		// Sync built-in agents into .pi/agents/ so Pi's native subagent tool
+		// (and any other extension) can discover them — taskflow's
+		// extensions/agents/ directory is invisible to the rest of Pi.
+		try {
+			syncBuiltinAgentsToProject(ctx.cwd);
+		} catch {
+			// Best-effort: a locked or readonly .pi/ directory must not block
+			// session startup.
+		}
+
 		// Hint: prompt to configure model roles if not set
 		try {
 			const settings = readSubagentSettings();
@@ -272,20 +282,19 @@ export default function (pi: ExtensionAPI) {
 		name: "taskflow",
 		label: "Taskflow",
 		description: [
-			"Orchestrate a multi-phase workflow of subagents from a declarative definition.",
-			"Phases (agent, parallel, map, gate, reduce, approval, flow) form a DAG; intermediate outputs stay out of your context — only the final phase output is returned.",
-			"Use action=run with an inline `define` (you write the DSL) or a saved `name`.",
-			"For simple non-DAG delegations (like the subagent tool) skip the DSL: pass `task` (+optional `agent`) for one task, `tasks:[{task,agent?}]` to run in parallel, or `chain:[{task,agent?}]` to run sequentially (reference the prior step with {previous.output}).",
-			"Use action=save to persist a definition as a reusable /tf:<name> command. action=resume continues a paused run. action=list shows saved flows. Use action=agents to list available agents — do NOT invent agent names; either use an agent from that list or omit the 'agent' field to auto-select the default agent.",
-			"DSL: {name, args?, concurrency?, budget?:{maxUSD,maxTokens}, phases:[{id, type, agent, task, dependsOn?, join?:'all'|'any', when?, retry?:{max,backoffMs,factor}, over?(map), as?(map), branches?(parallel), from?(reduce), use?(flow), with?(flow), output?:'json', final?}]}.",
-			"Phase types: agent (one subagent), parallel (static branches), map (dynamic fan-out over an array), gate (VERDICT: PASS/BLOCK quality gate), reduce (aggregate from N phases), approval (human-in-the-loop pause), flow (run a saved sub-flow), loop (re-run a task until 'until' is truthy / converged / maxIterations; body reads {loop.iteration} and {loop.lastOutput}), tournament (spawn N variants of 'task' — or distinct 'branches' — then a judge picks the best / aggregates; mode:'best'|'aggregate'). join:'any' is an OR-join; when is a conditional guard; retry adds backoff; budget caps run cost.",
+			"Orchestrate subagents — the ONLY delegation tool. Fully replaces the built-in subagent tool.",
+			"Shorthand (same API as subagent): pass `task` (+optional `agent`) for one task, `tasks:[{task,agent?}]` for parallel, or `chain:[{task,agent?}]` for sequential (use {previous.output}).",
+			"DSL: use action=run with an inline `define` (you write the DAG) or a saved `name`. Phases (agent, parallel, map, gate, reduce, approval, flow, loop, tournament) form a DAG; intermediate outputs stay out of your context — only the final phase output is returned.",
+			"Every delegation is tracked (runId), resumable across sessions, and saveable as /tf:<name> via action=save.",
+			"Use action=agents to list the 18 built-in agents (executor, scout, planner, analyst, critic, reviewer, risk-reviewer, security-reviewer, plan-arbiter, final-arbiter, test-engineer, doc-writer, executor-code, executor-fast, executor-ui, recover, verifier, visual-explorer). Do NOT invent agent names.",
+			"Phase types: agent, parallel (static branches), map (dynamic fan-out over array), gate (VERDICT: PASS/BLOCK), reduce (aggregate from N), approval (human-in-the-loop), flow (run saved sub-flow), loop (iterate until condition/convergence/cap), tournament (N variants, judge picks best/aggregate).",
 			"Interpolation: {args.X}, {steps.ID.output}, {steps.ID.json}, {item} (map), {previous.output}.",
 		].join(" "),
 		parameters: TaskflowParams,
-		promptSnippet: "Orchestrate many subagents over a whole codebase/many items (declarative DAG with map fan-out)",
+		promptSnippet: "Orchestrate subagents — single, parallel, chain, or DAG — with tracking, resume, and context isolation. Replaces the subagent tool.",
 		promptGuidelines: [
-			"Prefer taskflow whenever a request spans a whole project/codebase or many items — e.g. 'explore / 探索 / 审计 / analyze the project', auditing endpoints, reviewing or migrating many files/modules, or cross-checked research. It fans out to many subagents across phases and aggregates the result, keeping intermediate work out of your context.",
-			"Choose taskflow over ad-hoc parallel subagents when the work has multiple phases (discover → work → review → report), needs dynamic fan-out over a discovered list, or should be saved and rerun. For simple single/parallel/chain delegations use the shorthand `task`/`tasks`/`chain` (no DSL) when you want the run tracked, resumable, or saveable; otherwise the plain subagent tool is fine.",
+			"Use taskflow for ALL delegation — single tasks, parallel, chain, or full DAG orchestration. It fully replaces the subagent tool: every delegation is tracked with a runId, resumable across sessions, context-isolated (only final output returns), and saveable as /tf:<name>. Do NOT call the subagent tool directly; use taskflow shorthand (task/tasks/chain) for simple cases instead.",
+			"For complex multi-phase work (explore / 审计 / analyze the project, auditing endpoints, reviewing or migrating many files/modules, cross-checked research), use the full DSL with phases. For taskflow map phases, have the upstream phase emit a JSON array and set output:'json'.",
 			"For taskflow map phases, have the upstream phase emit a JSON array and set output:'json'.",
 		],
 
@@ -394,6 +403,53 @@ export default function (pi: ExtensionAPI) {
 				return { content: [{ type: "text", text }], details: { action } satisfies TaskflowDetails };
 			}
 
+			if (action === "verify") {
+				const { verifyTaskflow } = await import("./verify.ts");
+				// Load definition: inline define takes priority, then saved name
+				let def: Taskflow | undefined;
+				if (params.define) {
+					const d = params.define as Record<string, unknown>;
+					if (typeof d === "object" && d !== null && Array.isArray(d.phases)) {
+						def = d as unknown as Taskflow;
+					} else if (isShorthand(params.define)) {
+						const r = validateTaskflow(params.define);
+						if (r.ok) def = params.define as unknown as Taskflow;
+					}
+				} else if (params.name) {
+					const saved = getFlow(ctx.cwd, params.name);
+					if (saved) def = saved.def;
+				}
+				if (!def) {
+					return errorResult(action, "Provide 'define' (DSL) or 'name' (saved flow) to verify.");
+				}
+				// Schema validation first
+				const vr = validateTaskflow(def, { cwd: ctx.cwd ? String(ctx.cwd) : undefined });
+				if (!vr.ok) {
+					return errorResult(action, `Schema validation failed:\n${vr.errors.join("\n")}`);
+				}
+				const result = verifyTaskflow({ name: def.name!, phases: def.phases!, budget: def.budget, concurrency: def.concurrency });
+				const lines: string[] = [];
+				lines.push(`# Verification of "${def.name}"`);
+				lines.push("");
+				if (result.issues.length === 0) {
+					lines.push("✅ No issues found.");
+				} else {
+					const errors = result.issues.filter((i) => i.severity === "error");
+					const warnings = result.issues.filter((i) => i.severity === "warning");
+					if (errors.length) {
+						lines.push(`## Errors (${errors.length})`);
+						for (const e of errors) lines.push(`- **${e.category}**${e.phaseId ? ` [${e.phaseId}]` : ""}: ${e.message}`);
+					}
+					if (warnings.length) {
+						lines.push(`## Warnings (${warnings.length})`);
+						for (const w of warnings) lines.push(`- ${w.category}${w.phaseId ? ` [${w.phaseId}]` : ""}: ${w.message}`);
+					}
+					lines.push("");
+					lines.push(result.ok ? "Status: PASS (no errors)" : "Status: FAIL (errors found)");
+				}
+				return { content: [{ type: "text", text: lines.join("\n") }], details: { action } satisfies TaskflowDetails };
+			}
+
 			if (action === "cache-clear") {
 				const removed = new CacheStore(ctx.cwd).clear();
 				return {

package/extensions/runtime.ts

@@ -286,6 +286,7 @@ async function executePhase(
 	deps: RuntimeDeps,
 	prior: PhaseState | undefined,
 	emitProgress: () => void,
+	_retryDepth = 0,
 ): Promise<PhaseState> {
 	const type = phase.type ?? "agent";
 	const concurrency = phase.concurrency ?? state.def.concurrency ?? 8;
@@ -454,6 +455,47 @@ async function executePhase(
 	// interpolated task. gate additionally parses a verdict; reduce simply pulls
 	// its inputs from `from` phases (already exposed via interpolation).
 	if (type === "agent" || type === "gate" || type === "reduce") {
+		// Eval gate: zero-token machine checks before the LLM gate.
+		if (type === "gate" && Array.isArray(phase.eval) && phase.eval.length > 0) {
+			const evalCtx = buildInterpolationContext(state, previousOutput);
+			let allPassed = true;
+			for (const check of phase.eval) {
+				let expr = check;
+				// Pre-process `contains` expressions: "{steps.x.output} contains PASS"
+				// Convert to: interpolate LHS, check RHS substring inclusion.
+				const containsIdx = expr.indexOf(" contains ");
+				if (containsIdx > 0) {
+					const lhs = expr.slice(0, containsIdx).trim();
+					const rhs = expr.slice(containsIdx + " contains ".length).trim();
+					const lhsVal = interpolate(lhs, evalCtx);
+					const lhsStr = lhsVal.text;
+					if (!lhsStr.includes(rhs)) {
+						allPassed = false;
+						break;
+					}
+					continue;
+				}
+				if (!evaluateCondition(expr, evalCtx)) {
+					allPassed = false;
+					break;
+				}
+			}
+			if (allPassed) {
+				// All evals passed — skip the LLM gate, return an auto-pass.
+				const inputHash = cacheKey(cc, [phase.id, "eval-skip"]);
+				const ps: PhaseState = {
+					id: phase.id,
+					status: "done",
+					output: "PASS (eval checks passed — no LLM call)",
+					gate: { verdict: "pass" },
+					usage: emptyUsage(),
+					inputHash,
+					endedAt: Date.now(),
+				};
+				recordCache(cc, ps);
+				return ps;
+			}
+		}
 		const { text } = interpolate(phase.task ?? "", ctx);
 		const fullTask = preRead + text;
 		const agentName = resolveAgent(phase.agent, deps, state);
@@ -464,6 +506,40 @@ async function executePhase(
 		const r = await runOne(agentName, fullTask, liveSink(state, phase.id, emitProgress));
 		const ps = resultToPhaseState(phase.id, r, inputHash, parseJson);
 		if (type === "gate" && ps.status === "done") ps.gate = parseGateVerdict(r.output);
+
+		// onBlock:retry — re-execute upstream + gate until pass or max attempts.
+		if (type === "gate" && ps.gate?.verdict === "block") {
+			const onBlockV: string = phase.onBlock ?? "halt";
+			const MAX_RETRY_DEPTH = 3;
+			let attempt = 0;
+			let gatePs = ps;
+			while (onBlockV === "retry" && attempt < (phase.retry?.max ?? 1)) {
+				// H1: guard against unbounded spend and user abort
+				if (deps.signal?.aborted || overBudget(state).over) break;
+				attempt++;
+				// H2: cap nested retry depth to prevent exponential re-execution
+				// when a gate's upstream dependency is itself a gate with onBlock:retry
+				if (_retryDepth < MAX_RETRY_DEPTH) {
+					for (const depId of phase.dependsOn ?? []) {
+						const d = state.def.phases.find((p) => p.id === depId);
+						if (!d) continue;
+						const dPs = await executePhase(d, state, deps, prior, emitProgress, _retryDepth + 1);
+						state.phases[depId] = dPs;
+					}
+				}
+				const retryCtx = buildInterpolationContext(state, lastCompletedOutput(state, phase));
+				const retryText = interpolate(phase.task ?? "", retryCtx).text;
+				const retryTask = preRead + retryText;
+				const retryIH = cacheKey(cc, [phase.id, agentName, phase.model ?? "", retryTask]);
+				const retryR = await runOne(agentName, retryTask, liveSink(state, phase.id, emitProgress));
+				gatePs = resultToPhaseState(phase.id, retryR, retryIH, parseJson);
+				if (gatePs.status === "done") gatePs.gate = parseGateVerdict(retryR.output);
+				if (gatePs.gate?.verdict !== "block" || overBudget(state).over) break;
+			}
+			gatePs.attempts = (ps.attempts ?? 0) + attempt;
+			recordCache(cc, gatePs);
+			return gatePs;
+		}
 		recordCache(cc, ps);
 		return ps;
 	}

package/extensions/schema.ts

@@ -206,6 +206,19 @@ const PhaseSchema = Type.Object(
 				default: 8000,
 			}),
 		),
+		onBlock: Type.Optional(
+			StringEnum(["halt", "retry"] as const, {
+				description:
+					"[gate] What to do when the gate blocks: 'halt' (default, stop the flow) or 'retry' (re-run upstream phases then re-evaluate the gate). Limited by 'retry.max'.",
+				default: "halt",
+			}),
+		),
+		eval: Type.Optional(
+			Type.Array(Type.String(), {
+				description:
+					"[gate] Zero-token machine checks that run BEFORE the LLM gate. If ALL pass, the gate is skipped (PASS). If ANY fail, the LLM gate runs as normal. Each entry is a condition expression like '{steps.x.output} contains PASS' or '{steps.x.json.score} >= 0.8'. Supports same operators as 'when' plus 'contains' for substring checks.",
+			}),
+		),
 		cache: Type.Optional(CacheSchema),
 	},
 	{ additionalProperties: false },

package/extensions/verify.ts

@@ -0,0 +1,367 @@
+/**
+ * Static DAG verification — zero-token structural analysis.
+ *
+ * Runs *before* any agent is spawned. Catches dead-end phases, unreachable
+ * paths, gate exhaustion, budget overflow, and reference integrity issues
+ * purely through graph algorithms on the DAG — no LLM required.
+ */
+
+import type { Phase } from "./schema.ts";
+import { LOOP_DEFAULT_MAX_ITERATIONS } from "./schema.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type IssueCategory =
+	| "dead-end"
+	| "unreachable"
+	| "gate-exhaustion"
+	| "budget-overflow"
+	| "concurrency"
+	| "ref-integrity"
+	| "guard-contradiction";
+
+export interface VerificationIssue {
+	/** Affected phase id, if applicable. */
+	phaseId?: string;
+	message: string;
+	severity: "error" | "warning";
+	category: IssueCategory;
+}
+
+export interface VerificationResult {
+	ok: boolean;
+	issues: VerificationIssue[];
+}
+
+/** A lightweight Taskflow shape for verification (accepts parsed Phase[] + name). */
+export interface VerifiableFlow {
+	name: string;
+	phases: Phase[];
+	budget?: { maxUSD?: number; maxTokens?: number };
+	concurrency?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Graph helpers
+// ---------------------------------------------------------------------------
+
+function successors(phases: Phase[]): Map<string, string[]> {
+	const m = new Map<string, string[]>();
+	for (const p of phases) m.set(p.id, []);
+	for (const p of phases) {
+		for (const d of p.dependsOn ?? []) {
+			const s = m.get(d);
+			if (s) s.push(p.id);
+		}
+	}
+	return m;
+}
+
+function descendants(phaseId: string, succ: Map<string, string[]>): Set<string> {
+	const visited = new Set<string>();
+	const queue = [phaseId];
+	while (queue.length) {
+		const id = queue.shift()!;
+		if (visited.has(id)) continue;
+		visited.add(id);
+		for (const s of succ.get(id) ?? []) queue.push(s);
+	}
+	return visited;
+}
+
+/** Phases with NO `dependsOn` — the DAG entry points. */
+function entryPhases(phases: Phase[]): Phase[] {
+	return phases.filter((p) => !p.dependsOn || p.dependsOn.length === 0);
+}
+
+/** Phases with NO dependents (no one waits for them). */
+function terminalPhases(phases: Phase[], succ: Map<string, string[]>): string[] {
+	const hasDependents = new Set<string>();
+	for (const p of phases) {
+		for (const d of p.dependsOn ?? []) hasDependents.add(d);
+	}
+	return phases.filter((p) => !hasDependents.has(p.id)).map((p) => p.id);
+}
+
+// ---------------------------------------------------------------------------
+// Analyzers
+// ---------------------------------------------------------------------------
+
+/** #1 Dead-end: a phase with no dependents that is neither `final` nor the last phase. */
+function detectDeadEnds(phases: Phase[], succ: Map<string, string[]>): VerificationIssue[] {
+	const issues: VerificationIssue[] = [];
+	const terminal = new Set(terminalPhases(phases, succ));
+	const hasFinal = phases.some((p) => p.final);
+	const lastId = phases[phases.length - 1]?.id;
+
+	for (const p of phases) {
+		if (!terminal.has(p.id)) continue;
+		if (p.final) continue;
+		if (!hasFinal && p.id === lastId) continue;
+
+		issues.push({
+			phaseId: p.id,
+			message:
+				`Phase '${p.id}' is a terminal phase (no dependents) but not marked as 'final'. ` +
+				`Its output will be discarded. Add "final": true or a downstream phase that depends on it.`,
+			severity: "warning",
+			category: "dead-end",
+		});
+	}
+	return issues;
+}
+
+/** #2 Unreachable: phases not in the largest connected component. */
+function detectUnreachable(phases: Phase[], succ: Map<string, string[]>): VerificationIssue[] {
+	const issues: VerificationIssue[] = [];
+
+	// Build undirected adjacency (dependsOn edges are bidirectional for
+	// connectivity analysis).
+	const adj = new Map<string, Set<string>>();
+	for (const p of phases) adj.set(p.id, new Set());
+	for (const p of phases) {
+		for (const d of p.dependsOn ?? []) {
+			if (!adj.has(d)) continue; // ref to non-existent phase (schema catches)
+			adj.get(p.id)!.add(d);
+			adj.get(d)!.add(p.id);
+		}
+	}
+
+	// Find connected components via BFS.
+	const visited = new Set<string>();
+	const components: Set<string>[] = [];
+	for (const p of phases) {
+		if (visited.has(p.id)) continue;
+		const comp = new Set<string>();
+		const queue = [p.id];
+		while (queue.length) {
+			const id = queue.shift()!;
+			if (visited.has(id)) continue;
+			visited.add(id);
+			comp.add(id);
+			for (const nb of adj.get(id) ?? []) {
+				if (!visited.has(nb)) queue.push(nb);
+			}
+		}
+		components.push(comp);
+	}
+
+	if (components.length <= 1) return issues;
+
+	// The largest component is the main DAG; flag the rest — but only if they
+	// have edges (dependsOn or successors). A standalone phase with no edges is
+	// a valid independent entry, not unreachable.
+	const succMap2 = successors(phases);
+	const largest = components.reduce((a, b) => (a.size >= b.size ? a : b));
+	for (const comp of components) {
+		if (comp === largest) continue;
+		for (const id of comp) {
+			const p = phases.find((ph) => ph.id === id);
+			const hasEdges = (p && (p.dependsOn?.length || 0) > 0) || (succMap2.get(id)?.length || 0) > 0;
+			if (!hasEdges) continue; // standalone entry — valid
+			issues.push({
+				phaseId: id,
+				message:
+					`Phase '${id}' is disconnected from the main DAG. ` +
+					`Add a 'dependsOn' edge to connect it, or remove it.`,
+				severity: "error",
+				category: "unreachable",
+			});
+		}
+	}
+	return issues;
+}
+
+/** True if there exists a path from `src` to `dst` that does NOT pass through `avoidId`. */
+function hasBypassPath(
+	src: string,
+	dst: string,
+	avoidId: string,
+	succ: Map<string, string[]>,
+	visited: Set<string>,
+): boolean {
+	if (src === dst) return true;
+	if (visited.has(src)) return false;
+	visited.add(src);
+	for (const s of succ.get(src) ?? []) {
+		if (s === avoidId) continue;
+		if (hasBypassPath(s, dst, avoidId, succ, visited)) return true;
+	}
+	return false;
+}
+
+/** #3 Gate exhaustion: detect gates that are the sole path to a final phase. */
+function detectGateExhaustion(phases: Phase[], succ: Map<string, string[]>): VerificationIssue[] {
+	const issues: VerificationIssue[] = [];
+	const gates = phases.filter((p) => p.type === "gate" || p.type === "approval");
+	const fp = phases.filter((p) => p.final);
+
+	for (const g of gates) {
+		const desc = descendants(g.id, succ);
+		const finalsDownstream = fp.filter((p) => desc.has(p.id));
+		if (finalsDownstream.length === 0) continue;
+
+		// Check: is there at least ONE path from an entry to each final
+		// that BYPASSES this gate?
+		let allBypassable = true;
+		for (const f of finalsDownstream) {
+			const bypassable = entryPhases(phases).some((entry) => {
+				const entryDesc = descendants(entry.id, succ);
+				if (!entryDesc.has(f.id)) return false;
+				return hasBypassPath(entry.id, f.id, g.id, succ, new Set());
+			});
+			if (!bypassable) {
+				allBypassable = false;
+				break;
+			}
+		}
+
+		if (!allBypassable) {
+			issues.push({
+				phaseId: g.id,
+				message:
+					`Gate '${g.id}' is the sole path to final phase(s) ` +
+					`${finalsDownstream.map((p) => "'" + p.id + "'").join(", ")}. ` +
+					`A block here halts the entire flow with no alternative route. ` +
+					`Consider adding a bypass or marking the flow's structure as intentional.`,
+				severity: "warning",
+				category: "gate-exhaustion",
+			});
+		}
+	}
+	return issues;
+}
+
+/** #4 Budget overflow: minimum possible cost exceeds budget. */
+function detectBudgetOverflow(flow: VerifiableFlow): VerificationIssue[] {
+	const issues: VerificationIssue[] = [];
+	const budget = flow.budget;
+	if (!budget) return issues;
+
+	let minTokens = 0;
+	for (const p of flow.phases) {
+		if (p.type === "loop") {
+			const iters = p.maxIterations ?? LOOP_DEFAULT_MAX_ITERATIONS;
+			minTokens += Math.min(iters, 10);
+		} else if (p.type === "tournament") {
+			const variants = p.variants ?? 3;
+			minTokens += Math.min(variants + 1, 10);
+		} else {
+			minTokens += 1;
+		}
+	}
+
+	if (budget.maxTokens !== undefined && budget.maxTokens > 0 && minTokens > budget.maxTokens) {
+		issues.push({
+			message:
+				`Budget cap (${budget.maxTokens} tokens) is below the estimated minimum of ~${minTokens} tokens ` +
+				`for ${flow.phases.length} phase(s). The flow will likely be truncated before completion. ` +
+				`Increase maxTokens or reduce the number of phases.`,
+			severity: "warning",
+			category: "budget-overflow",
+		});
+	}
+
+	return issues;
+}
+
+/** #5 Concurrency warnings. */
+function detectConcurrencyWarnings(flow: VerifiableFlow, _succ: Map<string, string[]>): VerificationIssue[] {
+	const issues: VerificationIssue[] = [];
+
+	for (const p of flow.phases) {
+		if (p.type === "parallel" && p.branches && p.branches.length > (flow.concurrency ?? 8)) {
+			if (!p.concurrency) {
+				issues.push({
+					phaseId: p.id,
+					message:
+						`Parallel phase '${p.id}' has ${p.branches.length} branches but the flow concurrency ` +
+						`is ${flow.concurrency ?? 8}. Consider adding a per-phase 'concurrency' cap.`,
+					severity: "warning",
+					category: "concurrency",
+				});
+			}
+		}
+	}
+
+	// Self-dependency
+	for (const p of flow.phases) {
+		if ((p.dependsOn ?? []).includes(p.id)) {
+			issues.push({
+				phaseId: p.id,
+				message: `Phase '${p.id}' depends on itself — remove self-reference from 'dependsOn'.`,
+				severity: "error",
+				category: "ref-integrity",
+			});
+		}
+	}
+
+	return issues;
+}
+
+/** #6 Guard contradictions (simple static analysis of `when` conditions). */
+function detectGuardContradictions(phases: Phase[]): VerificationIssue[] {
+	const issues: VerificationIssue[] = [];
+
+	const groups = new Map<string, Phase[]>();
+	for (const p of phases) {
+		if (!p.when) continue;
+		const key = (p.dependsOn ?? []).sort().join(",");
+		if (!groups.has(key)) groups.set(key, []);
+		groups.get(key)!.push(p);
+	}
+
+	for (const [, group] of groups) {
+		if (group.length < 2) continue;
+		// Extract the ref keys from when conditions (to check same reference)
+		const refs = group.map((p) => {
+			const m = p.when!.match(/\{([^}]+)\}/g);
+			return m ? m.join(",") : "";
+		});
+		const uniqueRefs = new Set(refs.filter((r) => r.length > 0));
+		if (uniqueRefs.size === 1 && refs.every((r) => r.length > 0)) {
+			// Check the ORIGINAL when strings for opposing operators
+			const hasEq = group.some((p) => p.when!.includes("=="));
+			const hasNeq = group.some((p) => p.when!.includes("!="));
+			if (hasEq && hasNeq) {
+				issues.push({
+					message:
+						`Phases ${group.map((p) => `'${p.id}'`).join(", ")} have ` +
+						`the same dependency set and opposing 'when' conditions. ` +
+						`One branch will always be skipped. Verify this is intentional.`,
+					severity: "warning",
+					category: "guard-contradiction",
+				});
+			}
+		}
+	}
+	return issues;
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Run all static verification passes against a parsed taskflow.
+ *
+ * Returns issues found; `ok === true` means no errors (warnings are ok).
+ * This is a pure function — no I/O, no LLM, zero tokens.
+ */
+export function verifyTaskflow(flow: VerifiableFlow): VerificationResult {
+	const phases = flow.phases;
+	const succ = successors(phases);
+	const issues: VerificationIssue[] = [];
+
+	issues.push(...detectDeadEnds(phases, succ));
+	issues.push(...detectUnreachable(phases, succ));
+	issues.push(...detectGateExhaustion(phases, succ));
+	issues.push(...detectBudgetOverflow(flow));
+	issues.push(...detectConcurrencyWarnings(flow, succ));
+	issues.push(...detectGuardContradictions(phases));
+
+	const ok = !issues.some((i) => i.severity === "error");
+	return { ok, issues };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-taskflow",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "description": "Lightweight workflow orchestration for the Pi coding agent — declarative multi-phase taskflows with dynamic fan-out, isolated subagent context, resumable runs, and saveable commands.",
   "keywords": [
     "pi-package",
@@ -36,7 +36,7 @@
   ],
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "PI_TASKFLOW_BUILTIN_AGENTS_DIR= node --experimental-strip-types --test test/interpolate.test.ts test/condition.test.ts test/schema.test.ts test/usage.test.ts test/runtime.test.ts test/features.test.ts test/runner.test.ts test/store.test.ts test/agents.test.ts test/init.test.ts test/render.test.ts test/desugar.test.ts test/cache.test.ts test/loop.test.ts test/tournament.test.ts",
+    "test": "PI_TASKFLOW_BUILTIN_AGENTS_DIR= node --experimental-strip-types --test test/interpolate.test.ts test/condition.test.ts test/schema.test.ts test/usage.test.ts test/runtime.test.ts test/features.test.ts test/runner.test.ts test/store.test.ts test/agents.test.ts test/init.test.ts test/render.test.ts test/desugar.test.ts test/cache.test.ts test/loop.test.ts test/tournament.test.ts test/verify.test.ts test/gate-eval.test.ts",
     "test:e2e": "PI_TASKFLOW_PI_BIN=pi node --experimental-strip-types test/e2e.mts",
     "test:dogfood-cache": "node --experimental-strip-types test/dogfood-cache.mts"
   },