pi-taskflow 0.0.20 → 0.0.21

package/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to pi-taskflow are documented here. This project follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
 
+## [0.0.21] — 2026-06-10
+
+### Added
+- **Per-step context pre-read in shorthand modes.** Single, chain, and tasks shorthand steps now accept `context` (file paths) and `contextLimit`, desugared directly onto the generated phases. This eliminates `O(N²)` file exploration without writing the full DSL. In parallel `tasks` mode all branches share the deduped union of step contexts; chain steps each carry their own context. A top-level `context` in chain mode produces a warning (no unsupported flow-level default). Context-file changes automatically invalidate phase caches.
+
+### Fixed
+- **Headless approval safety.** Approval phases now auto-reject (not auto-approve) when running in detached/background/CI mode, preventing silent bypass of human gates.
+- **Step-reference validator accepts transitive ancestors.** The step-reference checker previously raised false positives on valid DAGs where dependencies span multiple levels of ancestry. Ancestor transitive closure is now fully resolved.
+
 ## [0.0.20] — 2026-06-10
 
 ### Added

package/README.md

@@ -8,7 +8,7 @@
   <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="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-535-6E8BFF?style=flat-square" alt="535 tests"></a>
+  <a href="#whats-inside"><img src="https://img.shields.io/badge/tests-601-6E8BFF?style=flat-square" alt="601 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>
@@ -304,7 +304,7 @@ Flow-level keys: `name`, `description`, `args`, `concurrency` (default 8), `agen
 - **`when`** — skip a phase unless an expression is truthy. Supports `{refs}`, `== != < > <= >=`, `&& || !`, parentheses, and quoted strings/numbers. Pair with `join: "any"` on the merge phase for real if/else routing. Parse errors **fail open**.
 - **`join: "any"`** — an OR-join: the phase runs as soon as *one* dependency completes (default `"all"` waits for all).
 - **`retry`** — `{ "max": 2, "backoffMs": 500, "factor": 2 }` retries a failing subagent with fixed or exponential backoff; usage is summed and the attempt count shows as `↻N` in the TUI. Transient provider errors (rate-limit / 5xx / timeout) **auto-retry even without an explicit policy**; hard errors don't.
-- **`approval`** — pause for a human (Approve / Reject / Edit). Reject halts the flow; Edit injects the typed note as the phase output for downstream steps. Non-interactive runs auto-approve.
+- **`approval`** — pause for a human (Approve / Reject / Edit). Reject halts the flow; Edit injects the typed note as the phase output for downstream steps. Non-interactive runs auto-reject (safety: approval gates are never bypassed).
 - **`flow`** — `{ "type": "flow", "use": "deep-research", "with": { "topic": "{item}" } }` runs a **saved** flow as a phase (recursion is detected and rejected). Or **generate the sub-flow at runtime**: `{ "type": "flow", "def": "{steps.plan.json}" }` resolves an upstream phase's JSON output into a sub-flow, **validates it (cycles / dangling refs / duplicate ids), then runs it** — the number and shape of the generated phases is decided at runtime, not authored in advance. A malformed plan fails *open* (the phase is skipped with a `defError`, the run continues). This is how a planner decides *at runtime* what work to spawn — the declarative answer to a code-mode `for` loop, with each generated plan checked before it spends a token. Pair it with `loop` for **data-dependent iterative replanning** (round N's plan depends on round N-1's result). See [`examples/dynamic-plan-execute.json`](./examples/dynamic-plan-execute.json) and [`examples/iterative-replan.json`](./examples/iterative-replan.json).
 
 ### Loop-until-done (`loop`)
@@ -434,7 +434,7 @@ Resume is keyed on each phase's input hash — if an upstream output changed, de
 ```
 .pi/taskflows/<name>.json          # project-scoped definitions (commit to share)
 ~/.pi/agent/taskflows/<name>.json  # user-scoped definitions
-.pi/taskflows/runs/<runId>.json    # run state for resume (gitignore this)
+.pi/taskflows/runs/<flowName>/<runId>.json  # run state for resume (gitignore this)
 ```
 
 > Commit `.pi/taskflows/` and your whole team shares the pipelines — no config sync, no onboarding doc. Run state is written atomically and guarded by a zero-dependency file lock, so concurrent runs never corrupt the index.
@@ -608,12 +608,12 @@ Copy one into `.pi/taskflows/<name>.json` (or `~/.pi/agent/taskflows/`) and it r
 
 <div align="center">
 
-**0 runtime dependencies** · **535 tests** · **9 phase types** · **cross-session resume** · **cross-run memoization** · **~5.4k LOC runtime**
+**0 runtime dependencies** · **601 tests** · **9 phase types** · **cross-session resume** · **cross-run memoization** · **~7.7k LOC runtime**
 
 </div>
 
 - **Zero runtime dependencies.** No `dependencies` field — the runtime is built entirely on Node built-ins (`fs` / `path` / `os` / `child_process` / `crypto`). The file lock is `fs.openSync("wx")`, not a third-party library.
-- **535 tests across 21 test files** covering concurrency, atomic file locking (8-process race regressions), path-traversal hardening, cross-session resume, cross-run cache freshness (flow/thinking/tools key isolation, fingerprint invalidation, TTL/LRU eviction), gate verdicts, budget caps, retry/backoff, approval flows, loop termination, tournament judging, sub-flow composition, callback isolation, the idle watchdog, model-role init config, and parseModelFromLabel with parenthesized-model-name regression.
+- **601 tests across 25 test files** covering concurrency, atomic file locking (8-process race regressions), path-traversal hardening, cross-session resume, cross-run cache freshness (flow/thinking/tools key isolation, fingerprint invalidation, TTL/LRU eviction), gate verdicts, budget caps, retry/backoff, approval flows, loop termination, tournament judging, sub-flow composition, callback isolation, the idle watchdog, model-role init config, and parseModelFromLabel with parenthesized-model-name regression.
 - **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.
 
@@ -637,7 +637,7 @@ Our `self-improve` flow is a 10-phase DAG — it audits the codebase, patches de
 
 ## Status & limits
 
-**v0.0.17** — loop-until-done (`loop` phase: iterate to a condition, convergence, or cap), tournament (best-of-N with a judge), cross-run memoization (content-addressed cache with git/file/glob/env fingerprints and TTL), interactive `/tf init` with role-aware model pickers + diff preview + atomic merge-write, configurable built-in agents, 18 built-in agents with 6 model roles. Full control-flow & reliability layer (`when` guards, `join: any`, `retry`/backoff, `approval`, `flow` composition, `budget` caps, idle watchdog) on top of the DSL + DAG runtime (`agent`/`parallel`/`map`/`gate`/`reduce`). Inline + saved flows, cross-session resume, live progress, and isolated context. A run executes as one streaming tool call.
+**v0.0.20** — loop-until-done (`loop` phase: iterate to a condition, convergence, or cap), tournament (best-of-N with a judge), cross-run memoization (content-addressed cache with git/file/glob/env fingerprints and TTL), interactive `/tf init` with role-aware model pickers + diff preview + atomic merge-write, configurable built-in agents, 18 built-in agents with 6 model roles. Full control-flow & reliability layer (`when` guards, `join: any`, `retry`/backoff, `approval`, `flow` composition, `budget` caps, idle watchdog) on top of the DSL + DAG runtime (`agent`/`parallel`/`map`/`gate`/`reduce`). Inline + saved flows, cross-session resume, live progress, and isolated context. A run executes as one streaming tool call.
 
 Known boundaries (tracked, bounded — no surprises mid-flow):
 

package/extensions/agents.ts

@@ -74,6 +74,7 @@ export interface AgentConfig {
 	filePath: string;
 }
 
+/** @internal */
 export interface AgentDiscoveryResult {
 	agents: AgentConfig[];
 	projectAgentsDir: string | null;
@@ -224,7 +225,13 @@ export interface SubagentSettings {
  * E.g. `{{fast}}` → `openrouter/deepseek/deepseek-v4-flash` if modelRoles.fast is set.
  * Returns undefined if the value is not a role reference or the role is unmapped.
  */
-export function resolveModelRole(model: string | undefined, roles?: Record<string, string>): string | undefined {
+/**
+ * Resolve `{{roleName}}` model references against a role→model mapping.
+ * E.g. `{{fast}}` → `openrouter/deepseek/deepseek-v4-flash` if modelRoles.fast is set.
+ * Returns undefined if the value is not a role reference or the role is unmapped.
+ * @internal
+ */
+function resolveModelRole(model: string | undefined, roles?: Record<string, string>): string | undefined {
 	if (!model || !roles) return model;
 	const match = model.match(/^\{\{(\w+)\}\}$/);
 	if (!match) return model;

package/extensions/cache.ts

@@ -135,6 +135,7 @@ export function resolveFingerprint(entries: string[] | undefined, cwd: string):
 // Cross-run cache store
 // ---------------------------------------------------------------------------
 
+/** @internal */
 export interface CacheEntry {
 	/** The full cache key (== phase inputHash incl. fingerprint). */
 	key: string;

package/extensions/detached-runner.ts

@@ -56,8 +56,8 @@ try {
 		agents,
 		globalThinking: settings.globalThinking,
 		persist: (s) => saveRun(s, cleanupConfig),
-		// No requestApproval — approval phases auto-reject in detached mode
-		// (fail-open: phase records the rejection, run continues).
+		// No requestApproval — approval phases auto-reject in detached/CI mode
+		// (safety: approval gates are never bypassed; the run records the rejection).
 		loadFlow: (name: string) => getFlow(ctx.cwd, name)?.def,
 	});
 

package/extensions/index.ts

@@ -59,6 +59,15 @@ const ShorthandStep = Type.Object(
 	{
 		agent: Type.Optional(Type.String({ description: "Agent for this step (defaults to the first available agent)" })),
 		task: Type.String({ description: "Task prompt for this step (supports {previous.output} in chains)" }),
+		context: Type.Optional(
+			Type.Array(Type.String(), {
+				description:
+					"File paths to pre-read and inject before this step's task (same as Phase.context). In parallel `tasks` mode all branches SHARE the union of step contexts.",
+			}),
+		),
+		contextLimit: Type.Optional(
+			Type.Number({ description: "Max characters to read per context file (default 8000)." }),
+		),
 	},
 	{ additionalProperties: false },
 );
@@ -82,6 +91,15 @@ const TaskflowParams = Type.Object({
 	task: Type.Optional(
 		Type.String({ description: "Shorthand single mode: the task prompt (like subagent single mode)" }),
 	),
+	context: Type.Optional(
+		Type.Array(Type.String(), {
+			description:
+				"Shorthand single mode: file paths to pre-read and inject before the task (same as Phase.context).",
+		}),
+	),
+	contextLimit: Type.Optional(
+		Type.Number({ description: "Shorthand single mode: max characters to read per context file (default 8000)." }),
+	),
 	tasks: Type.Optional(
 		Type.Array(ShorthandStep, {
 			description: "Shorthand parallel mode: run these tasks concurrently and merge results (like subagent parallel)",
@@ -573,7 +591,7 @@ export default function (pi: ExtensionAPI) {
 					: params.tasks
 						? { tasks: params.tasks, name: params.name }
 						: params.task
-							? { task: params.task, agent: params.agent, name: params.name }
+							? { task: params.task, agent: params.agent, name: params.name, context: params.context, contextLimit: params.contextLimit }
 							: undefined);
 
 			if (shorthandSpec !== undefined) {

package/extensions/runner.ts

@@ -69,7 +69,7 @@ export interface RunOptions {
  * 5 minutes is generous enough for slow reasoning/long tool calls while still
  * bounding a true hang.
  */
-export const DEFAULT_IDLE_TIMEOUT_MS = 5 * 60_000;
+const DEFAULT_IDLE_TIMEOUT_MS = 5 * 60_000;
 
 export function isFailed(r: RunResult): boolean {
 	return r.exitCode !== 0 || r.stopReason === "error" || r.stopReason === "aborted";

package/extensions/runtime.ts

@@ -47,7 +47,7 @@ export interface RuntimeDeps {
 	onProgress?: (state: RunState) => void;
 	/** Injectable task runner (defaults to spawning a real subagent). Enables testing. */
 	runTask?: typeof runAgentTask;
-	/** Resolve an `approval` phase. Omit for non-interactive runs (auto-approve). */
+	/** Resolve an `approval` phase. Omit for non-interactive runs (auto-reject). */
 	requestApproval?: (req: ApprovalRequest) => Promise<ApprovalDecision>;
 	/** Resolve a saved taskflow by name for `flow` (sub-workflow) phases. */
 	loadFlow?: (name: string) => Taskflow | undefined;
@@ -392,6 +392,7 @@ async function executePhase(
 		runId: state.runId,
 		thinking: phase.thinking,
 		tools: phase.tools,
+		preRead,
 	};
 
 	const baseRun = (agentName: string, task: string, onLive?: (l: LiveUpdate) => void) =>
@@ -700,13 +701,16 @@ async function executePhase(
 		const cached = cachedPhase(cc, inputHash);
 		if (cached) return cached;
 
-		// Non-interactive (headless/CI/tests): auto-approve, fail-open, but record it.
+		// Non-interactive (headless/CI/detached): auto-REJECT, fail-open, but record it.
+		// Approval gates are safety boundaries — bypassing them silently in CI would
+		// let unreviewed work ship. Detached/CI runs must not bypass approval gates.
 		if (!deps.requestApproval) {
 			return {
 				id: phase.id,
 				status: "done",
-				output: "(auto-approved: no interactive approver available)",
-				approval: { decision: "approve", auto: true },
+				output: "(auto-rejected: no interactive approver available)",
+				approval: { decision: "reject", auto: true },
+				gate: { verdict: "block", reason: "(auto-rejected: no interactive approver available)" },
 				usage: emptyUsage(),
 				inputHash,
 				endedAt: Date.now(),
@@ -1185,15 +1189,26 @@ interface PhaseCacheCtx {
 	 *  silently serve a stale cross-run hit). */
 	thinking?: string;
 	tools?: string[];
+	/** Resolved `context` pre-read content. Explicitly part of the cache identity
+	 *  so a context-file change always invalidates the phase — independent of
+	 *  whether a given branch happens to fold preRead into its task string
+	 *  (previously this was only incidentally true via `fullTask`). */
+	preRead?: string;
 }
 
 /** Fold the phase fingerprint into the base hash parts to form the final cache key. */
 function cacheKey(cc: PhaseCacheCtx, baseParts: string[]): string {
 	// Fold the full cache identity into the hash: flow name (prevents collisions
 	// across different flows that share a phase.id + task + model), the per-phase
-	// thinking/tools config (changing either changes the subagent's output), and
-	// the resolved world-state fingerprint.
-	const parts = [`flow:${cc.flowName}`, ...baseParts, `think:${cc.thinking ?? ""}`, `tools:${JSON.stringify(cc.tools ?? [])}`];
+	// thinking/tools config (changing either changes the subagent's output), the
+	// resolved context pre-read content, and the world-state fingerprint.
+	const parts = [
+		`flow:${cc.flowName}`,
+		...baseParts,
+		`think:${cc.thinking ?? ""}`,
+		`tools:${JSON.stringify(cc.tools ?? [])}`,
+		`ctx:${cc.preRead ?? ""}`,
+	];
 	return cc.fingerprint ? hashInput(...parts, cc.fingerprint) : hashInput(...parts);
 }
 

package/extensions/schema.ts

@@ -13,8 +13,8 @@ import { Type, type Static } from "typebox";
 // Phase types
 // ---------------------------------------------------------------------------
 
-export const PHASE_TYPES = ["agent", "parallel", "map", "gate", "reduce", "approval", "flow", "loop", "tournament"] as const;
-export type PhaseType = (typeof PHASE_TYPES)[number];
+const PHASE_TYPES = ["agent", "parallel", "map", "gate", "reduce", "approval", "flow", "loop", "tournament"] as const;
+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;
@@ -36,17 +36,18 @@ export const MAX_DYNAMIC_CONCURRENCY = 16;
 /** Tournament competitor bounds. */
 export const TOURNAMENT_DEFAULT_VARIANTS = 3;
 export const TOURNAMENT_HARD_MAX_VARIANTS = 20;
-export const TOURNAMENT_MODES = ["best", "aggregate"] as const;
+const TOURNAMENT_MODES = ["best", "aggregate"] as const;
+/** @internal */
 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;
+const OUTPUT_FORMATS = ["text", "json"] as const;
+const JOIN_MODES = ["all", "any"] as const;
+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;
+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 CACHE_CROSS_RUN_BLOCKED_TYPES = ["gate", "approval", "loop", "tournament"] as const;
 
 const ParallelTaskSchema = Type.Object(
 	{
@@ -282,7 +283,7 @@ 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];
+type JoinMode = (typeof JOIN_MODES)[number];
 
 // ---------------------------------------------------------------------------
 // Shorthand (non-DAG) specs — subagent-style ergonomics
@@ -302,6 +303,10 @@ export type JoinMode = (typeof JOIN_MODES)[number];
 export interface ShorthandStep {
 	agent?: string;
 	task: string;
+	/** Files to pre-read and inject before the task (pass-through to Phase.context). */
+	context?: string[];
+	/** Max characters per context file (pass-through to Phase.contextLimit). */
+	contextLimit?: number;
 }
 
 /** True when `def` is a shorthand spec (no `phases`, but a task/tasks/chain field). */
@@ -316,11 +321,22 @@ export function isShorthand(def: unknown): boolean {
 	);
 }
 
+/** Coerce an unknown value into a non-empty list of non-empty strings (or undefined). */
+function readContextList(v: unknown): string[] | undefined {
+	if (!Array.isArray(v)) return undefined;
+	const list = v.filter((x): x is string => typeof x === "string" && x.trim().length > 0);
+	return list.length ? list : undefined;
+}
+
 function readStep(s: unknown): ShorthandStep {
 	if (typeof s === "string") return { task: s };
 	if (s && typeof s === "object") {
 		const o = s as Record<string, unknown>;
-		return { agent: typeof o.agent === "string" ? o.agent : undefined, task: String(o.task ?? "") };
+		const step: ShorthandStep = { agent: typeof o.agent === "string" ? o.agent : undefined, task: String(o.task ?? "") };
+		const ctx = readContextList(o.context);
+		if (ctx) step.context = ctx;
+		if (typeof o.contextLimit === "number") step.contextLimit = o.contextLimit;
+		return step;
 	}
 	return { task: "" };
 }
@@ -345,10 +361,19 @@ export function desugar(def: unknown): Taskflow {
 
 	// chain → sequential agent phases
 	if (Array.isArray(d.chain) && d.chain.length > 0) {
+		// Spec-level context in chain mode would be a flow-level default (every
+		// step), which is deliberately NOT supported — declare it per step instead.
+		if (d.context !== undefined || d.contextLimit !== undefined) {
+			console.warn(
+				"[taskflow] Shorthand chain ignores top-level 'context'/'contextLimit' — put them on individual steps instead.",
+			);
+		}
 		const steps = d.chain.map(readStep);
 		const phases: Phase[] = steps.map((s, i) => {
 			const phase: Phase = { id: `step${i + 1}`, type: "agent", task: s.task };
 			if (s.agent) phase.agent = s.agent;
+			if (s.context) phase.context = s.context;
+			if (s.contextLimit !== undefined) phase.contextLimit = s.contextLimit;
 			if (i > 0) phase.dependsOn = [`step${i}`];
 			if (i === steps.length - 1) phase.final = true;
 			return phase;
@@ -356,16 +381,30 @@ export function desugar(def: unknown): Taskflow {
 		return { name: nameOf("chain"), ...meta, phases };
 	}
 
-	// tasks → one parallel phase (fan-out + merge), no extra aggregation agent
+	// tasks → one parallel phase (fan-out + merge), no extra aggregation agent.
+	// Context is SHARED across all branches (the runtime pre-reads per phase, not
+	// per branch): spec-level context plus the union of step-level contexts.
 	if (Array.isArray(d.tasks) && d.tasks.length > 0) {
-		const branches: ParallelTask[] = d.tasks.map(readStep).map((s) => (s.agent ? { task: s.task, agent: s.agent } : { task: s.task }));
-		return { name: nameOf("parallel"), ...meta, phases: [{ id: "parallel", type: "parallel", branches, final: true }] };
+		const steps = d.tasks.map(readStep);
+		const branches: ParallelTask[] = steps.map((s) => (s.agent ? { task: s.task, agent: s.agent } : { task: s.task }));
+		const phase: Phase = { id: "parallel", type: "parallel", branches, final: true };
+		const shared = [...(readContextList(d.context) ?? []), ...steps.flatMap((s) => s.context ?? [])];
+		if (shared.length) phase.context = Array.from(new Set(shared));
+		const limits = [
+			typeof d.contextLimit === "number" ? d.contextLimit : undefined,
+			...steps.map((s) => s.contextLimit),
+		].filter((n): n is number => typeof n === "number");
+		if (limits.length) phase.contextLimit = Math.max(...limits);
+		return { name: nameOf("parallel"), ...meta, phases: [phase] };
 	}
 
-	// single task → one agent phase
+	// single task → one agent phase (the spec itself is the step)
 	if (typeof d.task === "string") {
 		const phase: Phase = { id: "main", type: "agent", task: d.task, final: true };
 		if (typeof d.agent === "string") phase.agent = d.agent;
+		const ctx = readContextList(d.context);
+		if (ctx) phase.context = ctx;
+		if (typeof d.contextLimit === "number") phase.contextLimit = d.contextLimit;
 		return { name: nameOf("task"), ...meta, phases: [phase] };
 	}
 
@@ -376,6 +415,7 @@ export function desugar(def: unknown): Taskflow {
 // Validation (beyond schema: DAG integrity, phase-type requirements)
 // ---------------------------------------------------------------------------
 
+/** @internal */
 export interface ValidationResult {
 	ok: boolean;
 	errors: string[];
@@ -618,16 +658,41 @@ export function validateTaskflow(def: unknown, opts: ValidationOptions = {}): Va
 	// placeholder string. The runtime can't infer the intent — fail fast at
 	// validation time so the mistake is caught before the run starts.
 	//
+	// The check uses TRANSITIVE ancestors: if phase B depends on A, and C depends
+	// on B, then C may reference {steps.A.*} transitively. Only truly unreachable
+	// refs are errors.
+	//
 	// Phases with `join: "any"` are exempt: by design they only need ONE of
 	// their declared deps to complete, and may reference other phases as
 	// informational context (not as true dependencies).
 	if (errors.length === 0) {
 		const idToPhase = new Map((flow.phases as Phase[]).map((p) => [p.id, p]));
+		// Precompute transitive ancestors for every phase via BFS over dependsOn.
+		const transitiveCache = new Map<string, Set<string>>();
+		const transitiveAncestors = (phaseId: string): Set<string> => {
+			const cached = transitiveCache.get(phaseId);
+			if (cached) return cached;
+			const result = new Set<string>();
+			const queue = [...(idToPhase.get(phaseId)?.dependsOn ?? []), ...(idToPhase.get(phaseId)?.from ?? [])];
+			while (queue.length) {
+				const id = queue.shift()!;
+				if (result.has(id)) continue;
+				result.add(id);
+				const dep = idToPhase.get(id);
+				if (dep) {
+					for (const d of [...(dep.dependsOn ?? []), ...(dep.from ?? [])]) {
+						if (!result.has(d)) queue.push(d);
+					}
+				}
+			}
+			transitiveCache.set(phaseId, result);
+			return result;
+		};
 		for (const p of flow.phases as Phase[]) {
 			if (!p?.id) continue;
 			const isJoinAny = p.join === "any";
 			if (isJoinAny) continue;
-			const deps = new Set(dependenciesOf(p));
+			const transitive = transitiveAncestors(p.id);
 			const refs = collectRefs(p);
 			for (const ref of refs.steps) {
 				if (ref === p.id) {
@@ -640,9 +705,9 @@ export function validateTaskflow(def: unknown, opts: ValidationOptions = {}): Va
 					// double-warn — the dependsOn loop above already flags it.
 					continue;
 				}
-				if (!deps.has(ref)) {
+				if (!transitive.has(ref)) {
 					errors.push(
-						`Phase '${p.id}': task references {steps.${ref}.*} but '${ref}' is not in dependsOn. ` +
+						`Phase '${p.id}': task references {steps.${ref}.*} but '${ref}' is not reachable via dependsOn. ` +
 							`The phase will run in parallel with '${ref}' and see the literal placeholder. ` +
 							`Add "dependsOn": ["${ref}"] (or include '${ref}' transitively).`,
 					);

package/extensions/store.ts

@@ -29,6 +29,7 @@ export interface SavedFlow {
 	def: Taskflow;
 }
 
+/** @internal */
 export type PhaseStatus = "pending" | "running" | "done" | "failed" | "skipped";
 
 export interface PhaseState {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-taskflow",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "description": "A declarative, verifiable graph of task nodes for the Pi coding agent — not a workflow you script, but a DAG you declare: statically verified before it runs, with dynamic fan-out, gates, isolated subagent context, resumable runs, and saveable commands.",
   "keywords": [
     "pi-package",

package/skills/taskflow/SKILL.md

@@ -43,10 +43,25 @@ proper flow, so you still get progress, persistence, resume, and `save`.
 ```
 
 - `agent` is optional (defaults to the first available agent).
+- `context` (optional, per step or top-level in single mode): file paths to
+  pre-read and inject before the task — same as the full-DSL `Phase.context`
+  (per-file `contextLimit`, default 8000 chars). In **parallel `tasks` mode**
+  all branches SHARE the union of step contexts (the runtime pre-reads per
+  phase, not per branch). In **chain mode** declare `context` on individual
+  steps; a top-level `context` is ignored (with a warning).
 - Add `name` to label the run (and to `save` it as a `/tf:<name>` command).
 - Precedence if several are given: `chain` > `tasks` > `task`.
 - You can pass these as top-level tool params **or** inside `define`.
 
+```jsonc
+// context pre-read in shorthand — the file content is injected before the task
+{ "chain": [
+  { "task": "Map the public API of src/lib", "agent": "scout" },
+  { "task": "Write docs for:\n{previous.output}", "agent": "doc-writer",
+    "context": ["AGENTS.md", "docs/style-guide.md"] }
+] }
+```
+
 ## How to author a taskflow
 
 Call the `taskflow` tool. To run a brand-new flow you write inline, pass
@@ -128,7 +143,7 @@ deciding. The (interpolated) `task` is the prompt shown.
 - **Reject** → halt the flow (same mechanism as a blocking gate).
 - **Edit** → the typed note becomes this phase's `output`, so you can inject
   guidance mid-run: reference it downstream with `{steps.<id>.output}`.
-- **Non-interactive** runs (headless/CI/print mode) **auto-approve** and record it.
+- **Non-interactive** runs (headless/CI/print mode) **auto-reject** and record it — approval gates are safety boundaries that must never be silently bypassed.
 - **Background (detached)** runs **auto-reject** (no interactive approver) — downstream sees the rejection; the flow continues (fail-open).
 
 ```jsonc
@@ -170,9 +185,10 @@ Use hyphens in ids, never underscores. Sub-flow phases reference each other in
 their **own** `{steps.x.output}` namespace (no parent-id prefixing needed).
 
 **Fail-open & limits:** if the `def` doesn't parse, has the wrong shape, or fails
-validation, the phase fails *open* — it's marked failed with a `defError`, the
-upstream output is preserved, and the run continues (use `optional: true` on the
-flow phase so a bad plan never aborts the run). An **empty** `phases` array is a
+validation, the phase completes with `status: "done"` and carries a `defError`
+diagnostic field; downstream phases receive empty output. Authors who want a
+hard failure can add a gate that checks for `defError`. The run continues
+(add `optional: true` on the flow phase so a bad plan never aborts the run). An **empty** `phases` array is a
 valid no-op (the planner decided there's nothing to do). Inline nesting is capped
 at `MAX_DYNAMIC_NESTING` (5) to bound runaway self-spawning.
 
@@ -217,7 +233,7 @@ A `tournament` phase runs `variants` competing attempts in parallel, then a
 (`mode: "aggregate"`). Use it when one shot is unreliable and you want the best
 of several drafts, or a synthesis of diverse approaches.
 
-- `variants` — the competing attempts: a number (run the same `task` N times) or an array of `{task, agent?}` for genuinely different approaches.
+- `variants` — a number specifying how many competing variants to spawn from 'task' (default 3, max 20). For genuinely different approaches, use the `branches` field instead — an explicit array of `{task, agent?}` definitions.
 - `mode` — `"best"` (judge picks one winner, default) or `"aggregate"` (judge merges all into one output).
 - `judge` — the judge's rubric/instructions (how to choose or merge).
 - `judgeAgent` — *(optional)* the agent that runs the judge step; defaults to the phase `agent`.
@@ -450,12 +466,13 @@ Add `detach: true` to `action: "run"` to spawn the flow in a detached child proc
 
 ## Operating a run (lifecycle, resume, inspection)
 
-A run moves through: **running →** `completed` (a `final` phase produced output) **/** `blocked` (a gate emitted BLOCK, an `approval` was rejected, or the `budget` cap was hit) **/** `failed` (a non-`optional` phase errored) **/** `paused` (the run was aborted). `failed` and `paused` runs are resumable; `blocked` is terminal (fix the gate/budget and re-run).
+A run moves through: **running →** `completed` (a `final` phase produced output) **/** `blocked` (a gate emitted BLOCK, an `approval` was rejected, or the `budget` cap was hit) **/** `failed` (a non-`optional` phase errored) **/** `paused` (the run was aborted). `failed` and `paused` runs are resumable.
 
-- **Resume is cache-aware.** `action: "resume"` re-runs only what didn't finish: every phase already `done` is reused from its recorded output (within-run cache), so resuming after a crash or a `blocked`/`failed` stop never repeats completed work. A phase that was mid-flight is re-executed cleanly (stale `error`/`endedAt` are cleared first).
+- **`blocked` runs:** a blocked status halts the current run — the flow status is set to `blocked` and remaining phases are skipped. Re-running the flow resumes from the last completed state: `done` phases with matching input hashes are skipped; blocked/failed/skipped phases are re-attempted. Fix the gate condition or budget before re-running.
+- **Resume is cache-aware.** `action: "resume"` re-runs only what didn't finish: every phase already `done` is reused from its recorded output (within-run cache), so resuming after a crash or a failed/blocked stop never repeats completed work. A phase that was mid-flight is re-executed cleanly (stale `error`/`endedAt` are cleared first).
 - **When to resume vs. re-run.** Resume when the inputs are unchanged and you just want to continue/retry the tail (fixed a gate, raised the budget, approved a checkpoint). Re-run from scratch when the task or upstream inputs changed — resume would reuse now-stale outputs. (For reuse *across* runs, opt a phase into `cache: {scope:"cross-run"}` — see configuration.md.)
 - **Budget mid-run.** When the run-wide `budget` is exceeded, remaining phases are skipped and an in-flight `map`/`parallel` stops spawning new items; the run ends `blocked` with the partial outputs preserved.
-- **Inspect runs.** `/tf runs` lists recent runs with status; `/tf show <name>` prints a saved flow's definition. Run state lives at `<project .pi>/taskflows/runs/<runId>.json` (gitignored).
+- **Inspect runs.** `/tf runs` lists recent runs with status; `/tf show <name>` prints a saved flow's definition. Run state lives at `<project .pi>/taskflows/runs/<flowName>/<runId>.json` (gitignored).
 
 ## User commands
 

package/skills/taskflow/configuration.md

@@ -286,7 +286,7 @@ for the design.
 ### `ttl` (cross-run only)
 
 Max age before a cross-run hit is treated as a miss: e.g. `"30m"`, `"6h"`, `"7d"`.
-Omit for no time bound. A hit older than the TTL re-executes the phase.
+Omit for no time bound. A hit older than the TTL re-executes the phase. Cross-run cache entries are hard-evicted after 90 days regardless of per-entry TTL. This ceiling is not configurable.
 
 ### `fingerprint` (cross-run only)
 
@@ -298,7 +298,7 @@ Each entry is one of:
 | Entry | Becomes a miss when… | Resolves to |
 |-------|----------------------|-------------|
 | `git:HEAD` / `git:<ref>` | the commit moves | the resolved SHA (30s timeout → `<timeout>`; no git → `<no-git>`) |
-| `glob:<pattern>` | the **set of matching paths** changes | sorted path list (mtime-free) |
+| `glob:<pattern>` | the **set of matching paths** or their metadata changes | sorted path list with size + mtime (content-hashed globs use `glob!:` instead, which is mtime-independent) |
 | `glob!:<pattern>` | the **contents** of matching files change | content hashes (capped at 5000 matches) |
 | `file:<path>` | that file's content changes | sha256 of the file (>10 MB or missing → `<skip>`/`<missing>`) |
 | `env:<NAME>` | the env var changes | the env value |
@@ -333,7 +333,7 @@ Each entry is one of:
 |------|------|---------|
 | User-scoped flow | `~/.pi/agent/taskflows/<name>.json` | personal |
 | Project-scoped flow | `<nearest .pi>/taskflows/<name>.json` | ✅ commit to share |
-| Run state (resume) | `<project .pi>/taskflows/runs/<runId>.json` | ❌ gitignore |
+| Run state (resume) | `<project .pi>/taskflows/runs/<flowName>/<runId>.json` | ❌ gitignore |
 
 - `action: "save"` takes `scope: "project"` (default) or `"user"`.
 - Saved flows auto-register as `/tf:<name>` (immediately for the current session,