pi-taskflow 0.0.12 → 0.0.14

package/extensions/schema.ts

@@ -13,11 +13,27 @@ import { Type, type Static } from "typebox";
 // Phase types
 // ---------------------------------------------------------------------------
 
-export const PHASE_TYPES = ["agent", "parallel", "map", "gate", "reduce", "approval", "flow"] as const;
+export const PHASE_TYPES = ["agent", "parallel", "map", "gate", "reduce", "approval", "flow", "loop", "tournament"] as const;
 export type PhaseType = (typeof PHASE_TYPES)[number];
 
+/** Loop iteration bounds. Authors may lower the max; the hard cap is a runaway guard. */
+export const LOOP_DEFAULT_MAX_ITERATIONS = 10;
+export const LOOP_HARD_MAX_ITERATIONS = 100;
+
+/** Tournament competitor bounds. */
+export const TOURNAMENT_DEFAULT_VARIANTS = 3;
+export const TOURNAMENT_HARD_MAX_VARIANTS = 20;
+export const TOURNAMENT_MODES = ["best", "aggregate"] as const;
+export type TournamentMode = (typeof TOURNAMENT_MODES)[number];
+
 export const OUTPUT_FORMATS = ["text", "json"] as const;
 export const JOIN_MODES = ["all", "any"] as const;
+export const CACHE_SCOPES = ["run-only", "cross-run", "off"] as const;
+export type CacheScope = (typeof CACHE_SCOPES)[number];
+/** Allowed fingerprint entry prefixes. `glob!:` = content-hash variant of `glob:`. */
+export const CACHE_FINGERPRINT_PREFIXES = ["git:", "glob:", "glob!:", "file:", "env:"] as const;
+/** Phase types that must NOT be cached across runs (a fresh result is required each run). */
+export const CACHE_CROSS_RUN_BLOCKED_TYPES = ["gate", "approval", "loop", "tournament"] as const;
 
 const ParallelTaskSchema = Type.Object(
 	{
@@ -39,6 +55,36 @@ const RetrySchema = Type.Object(
 	{ additionalProperties: false },
 );
 
+/**
+ * Per-phase cache policy. Defaults to `run-only` which is exactly the historical
+ * behavior (within-run resume only). `cross-run` opts a phase into the persistent
+ * cross-run memoization store; see docs/rfc-cross-run-memoization.md.
+ */
+const CacheSchema = Type.Object(
+	{
+		scope: Type.Optional(
+			StringEnum(CACHE_SCOPES, {
+				description:
+					"Cache reuse scope. 'run-only' (default) = within-run resume only (historical behavior); 'cross-run' = reuse identical-input results from any prior run; 'off' = never reuse (even within-run).",
+				default: "run-only",
+			}),
+		),
+		ttl: Type.Optional(
+			Type.String({
+				description:
+					"Max cache age before a cross-run hit is treated as a miss, e.g. '30m', '6h', '7d'. Omit for no time bound.",
+			}),
+		),
+		fingerprint: Type.Optional(
+			Type.Array(Type.String(), {
+				description:
+					"Extra freshness inputs folded into the cache key so 'the world changed' becomes a cache miss. Each entry: 'git:HEAD' | 'glob:<pattern>' | 'glob!:<pattern>' (content-hash) | 'file:<path>' | 'env:<NAME>'.",
+			}),
+		),
+	},
+	{ additionalProperties: false },
+);
+
 /** Run-wide cost / token ceiling. Exceeding it halts the run (remaining phases skipped). */
 const BudgetSchema = Type.Object(
 	{
@@ -79,6 +125,51 @@ const PhaseSchema = Type.Object(
 			}),
 		),
 
+		// loop-until-done
+		until: Type.Optional(
+			Type.String({
+				description:
+					"[loop] Stop condition evaluated after each iteration. The iteration's output is exposed as {steps.<thisId>.output}/.json. Supports the same operators as `when`. The loop stops when this is truthy, on convergence, or at maxIterations. A parse error stops the loop (fail-safe).",
+			}),
+		),
+		maxIterations: Type.Optional(
+			Type.Number({
+				description: `[loop] Hard cap on iterations (default ${LOOP_DEFAULT_MAX_ITERATIONS}, max ${LOOP_HARD_MAX_ITERATIONS}). The loop always terminates within this bound even if 'until' never becomes truthy.`,
+				default: LOOP_DEFAULT_MAX_ITERATIONS,
+			}),
+		),
+		convergence: Type.Optional(
+			Type.Boolean({
+				description:
+					"[loop] When true (default), stop early if an iteration's output is identical to the previous one (a fixed point — further iterations would not change anything).",
+				default: true,
+			}),
+		),
+
+		// tournament: N variants compete, a judge picks the best (or aggregates)
+		variants: Type.Optional(
+			Type.Number({
+				description: `[tournament] Number of competing variants to spawn from 'task' (default ${TOURNAMENT_DEFAULT_VARIANTS}, max ${TOURNAMENT_HARD_MAX_VARIANTS}). Ignored when 'branches' is provided (those become the variants instead).`,
+				default: TOURNAMENT_DEFAULT_VARIANTS,
+			}),
+		),
+		judge: Type.Optional(
+			Type.String({
+				description:
+					"[tournament] Judge prompt. The numbered variant outputs are injected before it. To pick a winner, end with a line like 'WINNER: <n>' or return JSON {\"winner\": <n>}. Defaults to a sensible built-in rubric.",
+			}),
+		),
+		judgeAgent: Type.Optional(
+			Type.String({ description: "[tournament] Agent that runs the judge step (defaults to the phase 'agent')." }),
+		),
+		mode: Type.Optional(
+			StringEnum(TOURNAMENT_MODES, {
+				description:
+					"[tournament] 'best' (default): output is the winning variant verbatim. 'aggregate': output is the judge's synthesized answer combining the variants.",
+				default: "best",
+			}),
+		),
+
 		dependsOn: Type.Optional(Type.Array(Type.String(), { description: "Phase ids this phase depends on" })),
 		join: Type.Optional(
 			StringEnum(JOIN_MODES, {
@@ -115,6 +206,20 @@ 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 },
 );
@@ -157,6 +262,7 @@ export type Taskflow = Static<typeof TaskflowSchema>;
 export type ArgSpec = Static<typeof ArgSpecSchema>;
 export type RetryPolicy = Static<typeof RetrySchema>;
 export type Budget = Static<typeof BudgetSchema>;
+export type CachePolicy = Static<typeof CacheSchema>;
 export type JoinMode = (typeof JOIN_MODES)[number];
 
 // ---------------------------------------------------------------------------
@@ -260,6 +366,21 @@ export interface ValidationResult {
 	warnings: string[];
 }
 
+/**
+ * Parse a TTL string like '30m', '6h', '7d', '500ms', '90s' into milliseconds.
+ * Returns null for malformed or non-positive values. Plain integers = ms.
+ */
+export function parseTtlMs(ttl: string): number | null {
+	if (typeof ttl !== "string") return null;
+	const m = ttl.trim().match(/^(\d+(?:\.\d+)?)\s*(ms|s|m|h|d)?$/i);
+	if (!m) return null;
+	const n = Number(m[1]);
+	if (!Number.isFinite(n) || n <= 0) return null;
+	const unit = (m[2] ?? "ms").toLowerCase();
+	const mult: Record<string, number> = { ms: 1, s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+	return n * mult[unit];
+}
+
 export interface ValidationOptions {
 	/** Resolved invocation args, used for runtime checks like missing `{args.X}`. */
 	args?: Record<string, unknown>;
@@ -320,6 +441,36 @@ export function validateTaskflow(def: unknown, opts: ValidationOptions = {}): Va
 		if (type === "flow") {
 			if (!p.use) errors.push(`Phase '${p.id}' (flow) requires 'use' (a saved flow name)`);
 		}
+		if (type === "loop") {
+			if (!p.task) errors.push(`Phase '${p.id}' (loop) requires 'task' (the iteration body)`);
+			if (!p.until) errors.push(`Phase '${p.id}' (loop) requires 'until' (the stop condition)`);
+			if (p.maxIterations !== undefined) {
+				if (typeof p.maxIterations !== "number" || !Number.isFinite(p.maxIterations) || p.maxIterations < 1) {
+					errors.push(`Phase '${p.id}' (loop): maxIterations must be a number >= 1`);
+				} else if (p.maxIterations > LOOP_HARD_MAX_ITERATIONS) {
+					errors.push(`Phase '${p.id}' (loop): maxIterations must be <= ${LOOP_HARD_MAX_ITERATIONS}`);
+				}
+			}
+		}
+		if (type === "tournament") {
+			const hasBranches = Array.isArray(p.branches) && p.branches.length > 0;
+			if (!hasBranches && !p.task) {
+				errors.push(`Phase '${p.id}' (tournament) requires 'task' (the competitor prompt) or non-empty 'branches'`);
+			}
+			if (p.variants !== undefined) {
+				if (typeof p.variants !== "number" || !Number.isFinite(p.variants) || p.variants < 2) {
+					errors.push(`Phase '${p.id}' (tournament): variants must be a number >= 2`);
+				} else if (p.variants > TOURNAMENT_HARD_MAX_VARIANTS) {
+					errors.push(`Phase '${p.id}' (tournament): variants must be <= ${TOURNAMENT_HARD_MAX_VARIANTS}`);
+				}
+			}
+			if (hasBranches && p.branches!.length < 2) {
+				errors.push(`Phase '${p.id}' (tournament): 'branches' needs at least 2 competitors`);
+			}
+			if (p.mode && !TOURNAMENT_MODES.includes(p.mode as TournamentMode)) {
+				errors.push(`Phase '${p.id}' (tournament): unknown mode '${p.mode}'`);
+			}
+		}
 		if (p.retry) {
 			if (typeof p.retry.max !== "number" || p.retry.max < 0) {
 				errors.push(`Phase '${p.id}': retry.max must be a number >= 0`);
@@ -337,6 +488,33 @@ export function validateTaskflow(def: unknown, opts: ValidationOptions = {}): Va
 			errors.push(`Phase '${p.id}': unknown join mode '${p.join}'`);
 		}
 
+		// Cache policy validation (cross-run memoization).
+		if (p.cache) {
+			const scope = p.cache.scope ?? "run-only";
+			if (!CACHE_SCOPES.includes(scope as CacheScope)) {
+				errors.push(`Phase '${p.id}': unknown cache.scope '${scope}' (expected one of ${CACHE_SCOPES.join(", ")})`);
+			}
+			// Gate B: gate/approval phases must produce a fresh result every run.
+			if (scope === "cross-run" && (CACHE_CROSS_RUN_BLOCKED_TYPES as readonly string[]).includes(type)) {
+				errors.push(
+					`Phase '${p.id}' (${type}): cache.scope 'cross-run' is not allowed for ${CACHE_CROSS_RUN_BLOCKED_TYPES.join("/")} phases — they must produce a fresh result each run. Use 'run-only'.`,
+				);
+			}
+			// Gate C: every fingerprint entry must use a known prefix (fail closed).
+			for (const fp of p.cache.fingerprint ?? []) {
+				const ok = CACHE_FINGERPRINT_PREFIXES.some((pre) => fp.startsWith(pre) && fp.length > pre.length);
+				if (!ok) {
+					errors.push(
+						`Phase '${p.id}': invalid cache.fingerprint entry '${fp}' (expected '<prefix><value>' with prefix one of ${CACHE_FINGERPRINT_PREFIXES.join(", ")})`,
+					);
+				}
+			}
+			// Gate D: TTL must parse to a positive duration when present.
+			if (p.cache.ttl !== undefined && parseTtlMs(p.cache.ttl) === null) {
+				errors.push(`Phase '${p.id}': invalid cache.ttl '${p.cache.ttl}' (expected e.g. '30m', '6h', '7d')`);
+			}
+		}
+
 		// Agent name convention: hyphens only (per AGENTS.md naming convention)
 		if (p.agent && typeof p.agent === "string" && p.agent.includes("_")) {
 			errors.push(`Phase '${p.id}': agent name '${p.agent}' uses underscores — use hyphens (e.g. 'executor-code' not 'executor_code')`);

package/extensions/store.ts

@@ -40,6 +40,10 @@ export interface PhaseState {
 	model?: string;
 	error?: string;
 	inputHash?: string;
+	/** When this result was served from cache: 'cross-run' for the persistent
+	 *  cross-run store. (Within-run resume reuses prior state verbatim and is not
+	 *  flagged here.) */
+	cacheHit?: "cross-run";
 	startedAt?: number;
 	endedAt?: number;
 	/** Live fan-out progress for map/parallel phases. */
@@ -54,6 +58,10 @@ export interface PhaseState {
 	budgetTruncated?: boolean;
 	/** Human-in-the-loop outcome (approval phases only). */
 	approval?: { decision: "approve" | "reject" | "edit"; note?: string; auto?: boolean };
+	/** Loop iteration accounting (loop phases only). */
+	loop?: { iterations: number; stop: "until" | "converged" | "maxIterations" | "failed" };
+	/** Tournament outcome (tournament phases only). */
+	tournament?: { variants: number; winner: number; mode: "best" | "aggregate"; reason?: string };
 	/** Non-fatal diagnostic warnings accumulated during this phase (e.g.
 	 *  unresolved interpolation placeholders, suspicious templates). */
 	warnings?: string[];
@@ -249,7 +257,7 @@ function releaseLock(lockPath: string): void {
 /**
  * Execute `fn` while holding a file lock.  Guarantees release even on throw.
  */
-function withLock<T>(lockPath: string, fn: () => T): T {
+export function withLock<T>(lockPath: string, fn: () => T): T {
 	acquireLock(lockPath);
 	try {
 		return fn();
@@ -560,6 +568,12 @@ function runsDir(cwd: string): string {
 	return path.join(projDir, "runs");
 }
 
+/** Root dir for the cross-run memoization cache (sibling of `runs`). */
+export function cacheDir(cwd: string): string {
+	const projDir = findProjectFlowsDir(cwd, true)!;
+	return path.join(projDir, "cache");
+}
+
 export function newRunId(flowName: string): string {
 	const safe = flowName.replace(/[^\w.-]+/g, "_").slice(0, 24);
 	return `${safe}-${Date.now().toString(36)}-${crypto.randomBytes(3).toString("hex")}`;
@@ -743,7 +757,7 @@ export function hashInput(...parts: string[]): string {
  * then rename over the target (rename is atomic on the same filesystem). Prevents
  * a crash or concurrent write from leaving a half-written, corrupt JSON file.
  */
-function writeFileAtomic(filePath: string, data: string): void {
+export function writeFileAtomic(filePath: string, data: string): void {
 	// Ensure parent directory exists.
 	fs.mkdirSync(path.dirname(filePath), { recursive: true });
 	const tmp = `${filePath}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`;

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.12",
+  "version": "0.0.14",
   "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,8 +36,9 @@
   ],
   "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/render.test.ts test/desugar.test.ts",
-    "test:e2e": "PI_TASKFLOW_PI_BIN=pi node --experimental-strip-types test/e2e.mts"
+    "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"
   },
   "pi": {
     "extensions": [