pi-taskflow 0.0.25 → 0.0.26

package/CHANGELOG.md

@@ -2,6 +2,116 @@
 
 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.26] — 2026-06-25
+
+> Foundation release: **the convergence roadmap's H1 lands** — a real FlowIR
+> compile seam (M1), a declared dependency plane (M2), and a
+> backward-compatible cache-key migration. v0.0.25 made incremental recompute
+> *trustworthy*; this release makes the contract underneath it *real*: the
+> recompute frontier now reasons over **observed ∪ declared** dependencies, the
+> flow definition compiles through a typed IR surface instead of an inlined
+> hash, and folding the definition into the cache key no longer evicts every
+> pre-existing cross-run entry.
+
+### Added
+- **FlowIR compile seam (M1).** New `extensions/flowir/{index,translate,meta}.ts`
+  exposes `compileTaskflowToIR(def) → { ir, meta, hash, usedFallbackHash,
+  warnings, errors }` — a typed, never-throwing projection of a desugared flow
+  into a content-addressed IR. The runtime now routes `flowDefHash` through this
+  seam instead of inlining it. `translate` is currently a 1:1 stub projection
+  (so `usedFallbackHash` is `true` and the hash equals the vendored
+  `flowDefHash`); it becomes the genuine overstory compiler once that kernel is
+  vendored, at which point the cache-key version advances `v2: → v3:`.
+- **`/tf ir <flow>` command + `ir` tool action.** Renders the compiled IR plus
+  its hash and any structured `CompileError[]` — zero tokens, no LLM.
+- **Declared dependency plane (M2).** `compileTaskflowToIR` synthesizes per-phase
+  `DeclaredDeps { reads, writes }` from interpolation refs
+  (`task`/`over`/`when`/`until`/`eval`/`branches`/`with`/`context`) and
+  `dependsOn`, attaches them to `ir.meta.declaredDeps`, and persists them to
+  `RunState`. `/tf recompute` now computes its stale frontier over
+  **union(observed ∪ declared)** rather than observed-only — a dependency that
+  was declared but never interpolated at runtime is no longer missed.
+- **Tests: 753 → 802** (+49) across new suites: `flowir.test.ts`,
+  `flowir-declared.test.ts`, `stale-union.test.ts` (incl. a 500-iteration
+  property test proving the union frontier is never narrower than observed-only),
+  `recompute-union.test.ts`, `cache-migration.test.ts`, plus `e2e-flowir.mts`
+  and `e2e-cache-migration.mts`.
+
+### Fixed
+- **Cache-key migration no longer evicts existing cross-run entries.** Folding
+  `flowdef:` into the key previously invalidated every pre-existing cross-run
+  cache entry on upgrade (a one-time miss-storm). `cacheKey` is now versioned
+  (`v2:flowdef:`) with a **3-tier lookup**: new key → bare `flowdef:` key →
+  legacy (no-flowdef) key. Old entries still hit for one release cycle; there is
+  no write-through on a fallback hit (legacy entries age out naturally), and
+  every tier still includes `flow:${name}` so two different flows can never
+  collide.
+- **Declared plane and recompute guard now see `loop.until` and `gate.eval`.**
+  `collectRefs` skipped `until` (loop convergence) and `eval[]` (gate zero-token
+  checks), so a dependency expressed only in those fields was absent from the
+  declared plane and from the `dryRun:false` unobserved-dependency guard. Both
+  are now scanned. (Closes the two MEDIUM findings from the H1 risk review.)
+
+### Compatibility
+- **Backward compatible.** `RunState.flowDefHash` and `RunState.declaredDeps`
+  are optional — pre-0.0.26 run states load unchanged. A compile/hash failure
+  fails open: `usedFallbackHash` stays set, cross-run cache is disabled for that
+  run, and the key degrades to a flow-scoped (collision-free) form. The one
+  observable change on upgrade is a single re-execution of in-flight phases
+  whose stored `inputHash` predates the `v2:` prefix.
+
+## [0.0.25] — 2026-06-24
+
+> Correctness release: **incremental recompute is now trustworthy.** `/tf
+> recompute` shipped in the prior line as a promising idea — force-rerun a seed,
+> walk its stale frontier, let the cache cut off untouched downstreams. But the
+> dependency graph it walked was a half-truth: reads observed only inside a
+> `when` guard or an `eval` gate were never recorded, a loop that read its own
+> output **deadlocked the scheduler**, and a `{previous.output}` chain could be
+> silently skipped — each one a path where "only rerun what changed" quietly
+> reused **stale** upstream state and returned a wrong answer that *looked*
+> incrementally correct. This release closes all of them: the observed readSet
+> is now complete, the recompute order unions declared **and** observed edges,
+> and real (`dryRun:false`) recomputation refuses to run when it cannot prove
+> the frontier is sound. The headline feature finally earns its safety claim —
+> the difference between *looks* incremental and *provably* incremental.
+
+### Added
+- **Safety guard for real recomputation.** `recomputeTaskflow` with `dryRun:false`
+  now refuses to run flows whose dependencies cannot be fully observed through
+  the captured readSet: Shared Context Tree (`shareContext` / `contextSharing`),
+  `flow` phases, `context:` file pre-reads, and interpolation placeholders such
+  as `{previous.output}`, `{args.X}`, or `{item.X}`. This prevents silently
+  reusing stale upstream state.
+- **Regression tests** in `test/recompute.test.ts`:
+  - observed-read edges still order recomputation even without an explicit
+    `dependsOn` declaration;
+  - `{previous.output}` chains are rejected for real recomputation;
+  - `recomputeTaskflow` returns a fresh `RunState` and does not mutate the
+    caller's state.
+
+### Fixed
+- **Loop self-read no longer deadlocks recompute.** A loop whose `until`
+  condition references its own prior output (e.g. `{steps.refine.output}`)
+  produced a self-edge in the observed-dependency graph, causing `topoLayers` to
+  schedule the phase with a permanently non-zero indegree. `observedDeps()` now
+  filters self-references so scheduling remains sound.
+- **`when` condition upstream reads are captured.** Conditions are now evaluated
+  inside `executePhaseInner` with the same `onRead` hook used by the phase task,
+  so upstream refs observed only in a `when` guard are recorded in
+  `PhaseState.reads`.
+- **Gate `eval` upstream reads are captured.** The machine-check `eval` branch
+  now receives the shared `onRead` hook, and the resulting readSet is persisted
+  when an eval-only gate skips the LLM call.
+- **Recompute topo-order now unions declared and observed edges.** Previously
+  the recompute order only respected declared `dependsOn`, which could place a
+  downstream phase before its observed-but-not-declared upstream refreshed and
+  cause false early-cutoff. The scheduling graph now merges both edge sets.
+- **Recompute no longer mutates the caller's RunState.** `recomputeTaskflow`
+  clones the input state via `structuredClone` before modifying it.
+- **Help text accuracy.** `/tf` command and tool-action descriptions updated to
+  match the new `recompute` and provenance behavior.
+
 ## [0.0.24] — 2026-06-23
 
 > Feature release: **`/tf compile`** — turn the declared DAG into a Mermaid

package/extensions/flowir/index.ts

@@ -0,0 +1,73 @@
+/**
+ * Public entry point for the FlowIR compile seam.
+ *
+ * `compileTaskflowToIR` is the read-only, content-addressed IR projection used
+ * by:
+ *   - `/tf ir <flow>` / `action=ir`     — render the compiled IR + hash (0 tokens)
+ *   - the runtime (`runTaskflowLayers`) — fold `ir.hash` into the cache key
+ *     (== `flowDefHash` in the stub; the overstory-canonical hash once the
+ *     genuine compiler is vendored) and persist `ir.meta.declaredDeps` to
+ *     `RunState` (M2 declared plane).
+ *
+ * The stub hash reuses the already-vendored overstory `flowDefHash` algorithm
+ * (./hash.ts) so pi-taskflow and overstory share one byte-identical hashing
+ * contract today. `usedFallbackHash` is `true` in the stub (the genuine
+ * overstory `hashIR` is not yet wired); it flips to `false` once the compiler
+ * is vendored, at which point the cache key's `v2:` prefix advances to `v3:`
+ * (see docs/internal/cache-migration.md).
+ *
+ * Pure + async (Web Crypto). Never throws — a hash failure leaves `hash`
+ * unset and `usedFallbackHash` true; the runtime degrades to the safe
+ * flowName-only cache key (cross-run disabled for that run).
+ *
+ * @see docs/internal/overstory-convergence-roadmap.md §3 (M1)
+ * @see docs/internal/rfc-flowir-compilation.md
+ */
+
+import type { Taskflow } from "../schema.ts";
+import { flowDefHash } from "./hash.ts";
+import { translateTaskflow } from "./translate.ts";
+import type { TaskflowIR } from "./meta.ts";
+
+/**
+ * Compile a (desugared) `Taskflow` into its content-addressed IR.
+ *
+ * The returned `hash` is, in the stub, exactly `flowDefHash(def)` — the
+ * overstory-vendored canonical-JSON + SHA-256-truncation contract. The
+ * `usedFallbackHash` flag records that this is the *fallback* hash (non-IR-
+ * canonical): it is `true` whenever the stub cannot guarantee IR-canonicity
+ * (any phase with a `when`, or any hash-compute failure).
+ *
+ * Never throws. Returns structured diagnostics so `/tf ir` on a broken flow
+ * yields a clean error table instead of crashing.
+ */
+export async function compileTaskflowToIR(def: Taskflow): Promise<TaskflowIR> {
+	const t = translateTaskflow(def);
+	let hash: string | undefined;
+	try {
+		hash = await flowDefHash(def);
+	} catch {
+		hash = undefined;
+	}
+	return {
+		ir: t.ir,
+		meta: t.meta,
+		hash,
+		warnings: t.warnings,
+		errors: t.errors,
+		// Stub: the fallback hash is used whenever (a) any phase has a `when`
+		// (translateTaskflow flags it) OR (b) the hash computation itself failed.
+		// Once the genuine overstory compiler is vendored, condition (a) drops.
+		usedFallbackHash: t.usedFallbackHash || hash === undefined,
+	};
+}
+
+export type {
+	CompileError,
+	CompileWarning,
+	DeclaredDeps,
+	FlowIR,
+	FlowIRNode,
+	TaskflowIR,
+	TaskflowIRMeta,
+} from "./meta.ts";

package/extensions/flowir/meta.ts

@@ -0,0 +1,126 @@
+/**
+ * Type definitions for the FlowIR compile seam.
+ *
+ * This is the **stub/projection** layer of the overstory-convergence roadmap's
+ * M1 slice: we project a pi-taskflow `Taskflow` into a `FlowIR` shape that
+ * mirrors overstory's IR contract *structurally* (nodes with `inject`/`emits`)
+ * without yet compiling to overstory's native inject/emits model. The hash
+ * contract (overstory's `hashIR` algorithm) is shared via `flowDefHash` — see
+ * `./hash.ts`. When the genuine overstory compiler is vendored later, the
+ * `usedFallbackHash` flag flips to `false` and `ir` becomes the canonical IR;
+ * until then this seam is read-only, pure, and never throws.
+ *
+ * Pure module: no IO, no Date, no randomness. Type-only where possible.
+ *
+ * @see docs/internal/overstory-convergence-roadmap.md §3 (M1)
+ * @see docs/internal/rfc-flowir-compilation.md
+ */
+
+import type { Budget, Taskflow } from "../schema.ts";
+
+// ---------------------------------------------------------------------------
+// Declared dependency plane (compile-time, M2)
+// ---------------------------------------------------------------------------
+
+/**
+ * A phase's *declared* (static) dependency footprint, synthesized at compile
+ * time from `{steps.X}` interpolation refs (via `collectRefs`) plus `dependsOn`.
+ * `reads` = the upstream step ids this phase's task/when/branches/with/context
+ * statically reference; `writes` = the step id this phase emits (itself).
+ *
+ * This is the *declared* plane — distinct from the *observed* readSet captured
+ * at runtime (M3 `PhaseState.reads`). The two are reconciled by a **union**
+ * (`observed ∪ declared`) in `computeStaleFrontier` / `recomputeTaskflow` so a
+ * declared-but-unobserved edge (e.g. a `when` ref that never fired) is still
+ * treated as a dependency for staleness propagation. JSON-safe `Record` shape
+ * (not `Map`) so it round-trips through `RunState` persistence.
+ */
+export interface DeclaredDeps {
+	/** Upstream step ids statically referenced by this phase's interpolation. */
+	reads: string[];
+	/** Step id(s) this phase emits — currently `[phase.id]` (1:1 projection). */
+	writes: string[];
+}
+
+// ---------------------------------------------------------------------------
+// FlowIR (1:1 projection of a Taskflow)
+// ---------------------------------------------------------------------------
+
+/**
+ * A single IR node — one per pi-taskflow phase. `kind` is the native phase type
+ * (a 1:1 projection; the overstory-native kind lowering is deferred per roadmap
+ * §6.1). `inject`/`emits` mirror overstory's contract: a node *injects*
+ * (reads) the outputs of its upstream nodes and *emits* (writes) its own.
+ */
+export interface FlowIRNode {
+	id: string;
+	/** pi-taskflow phase type (1:1 projection; `agent`|`parallel`|`map`|…). */
+	kind: string;
+	/** Synthesized declared reads: the `{steps.X}` refs this node's task
+	 *  interpolates. (overstory-native `inject` lowering is deferred.) */
+	inject: string[];
+	/** What this node emits — currently `[id]` (1:1 projection). */
+	emits: string[];
+	/** Raw `when` guard passthrough (stub: not rewritten to IR conditions). */
+	when?: string;
+}
+
+/** The compiled IR: a flat list of nodes plus flow-level metadata. */
+export interface FlowIR {
+	name: string;
+	nodes: FlowIRNode[];
+	args?: Taskflow["args"];
+	budget?: Budget;
+	concurrency?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Compile diagnostics
+// ---------------------------------------------------------------------------
+
+/** A hard compile error (none in the stub; reserved for the genuine compiler). */
+export interface CompileError {
+	phaseId?: string;
+	code: string;
+	message: string;
+}
+
+/** A non-fatal advisory (e.g. a `{steps.X}` ref not reachable via dependsOn). */
+export interface CompileWarning {
+	phaseId?: string;
+	message: string;
+}
+
+// ---------------------------------------------------------------------------
+// Meta + composite return type
+// ---------------------------------------------------------------------------
+
+/**
+ * Compile-time metadata attached to the IR. `declaredDeps` is the M2 declared
+ * plane (per-phase `DeclaredDeps`); `sidecar` carries every pi-taskflow-specific
+ * field not represented in `FlowIRNode` so the projection is lossless and can
+ * round-trip back to a runnable `Taskflow`.
+ */
+export interface TaskflowIRMeta {
+	sourceFlowName: string;
+	/** Per-phase declared dependency footprint (M2). JSON-safe. */
+	declaredDeps: Record<string, DeclaredDeps>;
+	/** Pi-taskflow-specific fields preserved verbatim for round-trip. */
+	sidecar: Record<string, unknown>;
+}
+
+/**
+ * The composite compile result (RFC §5). `ir`/`hash` are present unless
+ * synthesis failed (stub never fails). `usedFallbackHash` is `true` whenever
+ * the stub cannot produce an overstory-canonical hash (always, in the stub:
+ * the hash is the `flowDefHash` fallback; flips to `false` once the genuine
+ * compiler is vendored).
+ */
+export interface TaskflowIR {
+	ir?: FlowIR;
+	meta: TaskflowIRMeta;
+	hash?: string;
+	warnings: CompileWarning[];
+	errors: CompileError[];
+	usedFallbackHash: boolean;
+}

package/extensions/flowir/translate.ts

@@ -0,0 +1,163 @@
+/**
+ * FlowIR translation — the 1:1 projection of a pi-taskflow `Taskflow` into the
+ * `FlowIR` shape.
+ *
+ * **Stub/projection** (M1): this is a *structural* mirror, NOT a compile to
+ * overstory's native inject/emits model (which expects an explicit emit
+ * declaration pi-taskflow doesn't have — see roadmap §6.1). Each phase becomes
+ * one `FlowIRNode`; `inject` is synthesized from `{steps.X}` interpolation refs
+ * (`collectRefs`), `emits` is `[phase.id]`. The overstory-native `kind` lowering
+ * is deliberately deferred.
+ *
+ * Pure, synchronous, never throws. Used by `compileTaskflowToIR` (./index.ts).
+ *
+ * @see docs/internal/overstory-convergence-roadmap.md §3 (M1)
+ */
+
+import { collectRefs, type Phase, type Taskflow } from "../schema.ts";
+import type {
+	CompileError,
+	CompileWarning,
+	DeclaredDeps,
+	FlowIR,
+	FlowIRNode,
+	TaskflowIRMeta,
+} from "./meta.ts";
+
+// ---------------------------------------------------------------------------
+// Sidecar: the pi-taskflow-specific fields not represented in FlowIRNode.
+// Everything preserved verbatim so the projection is lossless and can
+// round-trip back to a runnable Taskflow. Defined as a list so the sidecar
+// never silently drops a field when the DSL grows (a new field is carried
+// automatically through `Phase` indexing).
+// ---------------------------------------------------------------------------
+
+const SIDECAR_PHASE_FIELDS = [
+	"task",
+	"over",
+	"as",
+	"branches",
+	"from",
+	"use",
+	"def",
+	"with",
+	"until",
+	"maxIterations",
+	"convergence",
+	"variants",
+	"judge",
+	"judgeAgent",
+	"mode",
+	"dependsOn",
+	"join",
+	"when",
+	"retry",
+	"output",
+	"model",
+	"thinking",
+	"tools",
+	"cwd",
+	"context",
+	"contextLimit",
+	"onBlock",
+	"eval",
+	"cache",
+	"shareContext",
+	"optional",
+	"final",
+	"concurrency",
+] as const;
+
+/** Build the per-phase sidecar record (verbatim copy of non-IR fields). */
+function sidecarForPhase(phase: Phase): Record<string, unknown> {
+	const out: Record<string, unknown> = {};
+	const rec = phase as Record<string, unknown>;
+	for (const k of SIDECAR_PHASE_FIELDS) {
+		if (k in rec && rec[k] !== undefined) out[k] = rec[k];
+	}
+	return out;
+}
+
+/**
+ * Translate a desugared `Taskflow` into a 1:1 `FlowIR` projection + declared
+ * dependency metadata. Never throws: malformed input yields warnings/errors in
+ * the return value, not an exception (so `/tf ir` on a broken flow still
+ * produces a structured diagnostic rather than crashing the tool).
+ *
+ * `usedFallbackHash` is `true` unconditionally in the stub: the hash produced
+ * is `flowDefHash` (the definition fingerprint), NOT the overstory-IR-canonical
+ * hash, so callers can never mistake a stub hash for a canonical one. It flips
+ * to `false` only once the genuine overstory compiler is vendored and the hash
+ * is IR-canonical; a `when` guard remains a *future* fallback driver then.
+ */
+export function translateTaskflow(def: Taskflow): {
+	ir: FlowIR;
+	meta: TaskflowIRMeta;
+	warnings: CompileWarning[];
+	errors: CompileError[];
+	usedFallbackHash: boolean;
+} {
+	const warnings: CompileWarning[] = [];
+	const errors: CompileError[] = [];
+	const declaredDeps: Record<string, DeclaredDeps> = {};
+	const sidecarPhases: Record<string, unknown> = {};
+
+	// In the stub the hash is ALWAYS the fallback (flowDefHash — the definition
+	// fingerprint, not the overstory-IR-canonical hash). The `when` guard is a
+	// *future* driver (the genuine compiler can't lower conditions → fallback);
+	// today the stub unconditionally uses the fallback so callers can never
+	// mistake a stub hash for a canonical one. Flips to `false` only once the
+	// genuine overstory compiler is vendored and the hash is IR-canonical.
+	const usedFallbackHash = true;
+
+	const nodes: FlowIRNode[] = def.phases.map((phase) => {
+		const refs = collectRefs(phase);
+		// declared reads: the {steps.X} refs this phase statically references.
+		const reads = refs.steps.filter((id) => id !== phase.id);
+		declaredDeps[phase.id] = { reads, writes: [phase.id] };
+
+		// Advisory: a {steps.X} ref whose target doesn't exist (mirrors the
+		// validation check but non-fatal here — validation is the source of
+		// truth; this is a read-only diagnostic).
+		const knownIds = new Set(def.phases.map((p) => p.id));
+		for (const r of refs.steps) {
+			if (r !== phase.id && !knownIds.has(r)) {
+				warnings.push({
+					phaseId: phase.id,
+					message: `references {steps.${r}.*} but no phase '${r}' exists`,
+				});
+			}
+		}
+
+		if (phase.when !== undefined) {
+			// `when` is a future fallback driver; today the stub is always fallback.
+			// (Kept as a structural marker on the node for round-trip.)
+		}
+
+		sidecarPhases[phase.id] = sidecarForPhase(phase);
+
+		return {
+			id: phase.id,
+			kind: phase.type ?? "agent",
+			inject: reads,
+			emits: [phase.id],
+			when: phase.when,
+		} satisfies FlowIRNode;
+	});
+
+	const ir: FlowIR = {
+		name: def.name,
+		nodes,
+		args: def.args,
+		budget: def.budget,
+		concurrency: def.concurrency,
+	};
+
+	const meta: TaskflowIRMeta = {
+		sourceFlowName: def.name,
+		declaredDeps,
+		sidecar: { phases: sidecarPhases },
+	};
+
+	return { ir, meta, warnings, errors, usedFallbackHash };
+}

package/extensions/index.ts

@@ -45,7 +45,8 @@ import {
 } from "./store.ts";
 import { CacheStore } from "./cache.ts";
 import { safeParse } from "./interpolate.ts";
-import { formatWhyStale, readMapOf } from "./stale.ts";
+import { declaredReadMapOfDef, formatWhyStale, readMapOf } from "./stale.ts";
+import type { TaskflowIR } from "./flowir/index.ts";
 import {
 	isValidKey,
 	queueSpawn,
@@ -86,8 +87,8 @@ const ShorthandStep = Type.Object(
 );
 
 const TaskflowParams = Type.Object({
-	action: StringEnum(["run", "save", "resume", "list", "agents", "init", "verify", "compile", "provenance", "why-stale", "recompute", "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, verify the DAG, compile the DAG to a Mermaid diagram + verification report, show observed readSet provenance, explain why a run is stale, minimally recompute a stale run, or clear the cross-run memoization cache",
+	action: StringEnum(["run", "save", "resume", "list", "agents", "init", "verify", "compile", "ir", "provenance", "why-stale", "recompute", "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, verify the DAG, compile the DAG to a Mermaid diagram + verification report, compile to FlowIR + content hash, show observed readSet provenance, explain why a run is stale, minimally recompute a stale run, or clear the cross-run memoization cache",
 		default: "run",
 	}),
 	name: Type.Optional(Type.String({ description: "Name of a saved flow (for run/save without inline define)" })),
@@ -151,6 +152,43 @@ const TaskflowParams = Type.Object({
 	),
 });
 
+function formatFlowIR(ir: TaskflowIR): string {
+	const lines: string[] = [];
+	lines.push(`# FlowIR — "${ir.meta.sourceFlowName}"`);
+	lines.push("");
+	if (ir.hash) {
+		lines.push(`**content hash:** \`${ir.hash}\`${ir.usedFallbackHash ? "  (fallback — stub projection)" : "  (overstory-canonical)"}`);
+		lines.push("");
+	} else {
+		lines.push("**content hash:** _(unavailable — computation failed)_");
+		lines.push("");
+	}
+	if (ir.errors.length) {
+		lines.push(`## Errors (${ir.errors.length})`);
+		for (const e of ir.errors) lines.push(`- [${e.code}]${e.phaseId ? ` [${e.phaseId}]` : ""}: ${e.message}`);
+		lines.push("");
+	}
+	if (ir.warnings.length) {
+		lines.push(`## Warnings (${ir.warnings.length})`);
+		for (const w of ir.warnings) lines.push(`- ${w.phaseId ? `[${w.phaseId}] ` : ""}${w.message}`);
+		lines.push("");
+	}
+	lines.push("## Nodes (1:1 projection)");
+	lines.push("");
+	for (const n of ir.ir?.nodes ?? []) {
+		lines.push(`- **${n.id}** (kind: \`${n.kind}\`)  inject:[${n.inject.join(", ") || ""}]  emits:[${n.emits.join(", ")}]${n.when ? `  when: \`${n.when}\`` : ""}`);
+	}
+	lines.push("");
+	lines.push("## Declared dependencies (M2)");
+	lines.push("");
+	lines.push("| phase | reads | writes |");
+	lines.push("|-------|-------|--------|");
+	for (const [id, deps] of Object.entries(ir.meta.declaredDeps)) {
+		lines.push(`| ${id} | ${deps.reads.join(", ") || "—"} | ${deps.writes.join(", ")} |`);
+	}
+	return lines.join("\n");
+}
+
 function formatProvenance(run: RunState): string {
 	const lines: string[] = [];
 	lines.push(`Provenance — run ${run.runId} · flow "${run.flowName}" · ${run.status}`);
@@ -666,6 +704,46 @@ export default function (pi: ExtensionAPI) {
 				};
 			}
 
+			if (action === "ir") {
+				const { compileTaskflowToIR } = await import("./flowir/index.ts");
+				// Resolve definition: inline define (object or JSON/fenced string), shorthand,
+				// or saved name. Mirrors action=compile / action=verify.
+				let def: Taskflow | undefined;
+				let resolvedDefine: unknown = params.define;
+				if (typeof resolvedDefine === "string") {
+					const parsed = safeParse(resolvedDefine);
+					if (parsed && typeof parsed === "object") resolvedDefine = parsed;
+				}
+				if (resolvedDefine) {
+					const d = resolvedDefine as Record<string, unknown>;
+					if (typeof d === "object" && d !== null && Array.isArray(d.phases)) {
+						def = d as unknown as Taskflow;
+					} else if (isShorthand(resolvedDefine)) {
+						try {
+							def = desugar(resolvedDefine) as Taskflow;
+						} catch (e) {
+							return errorResult(action, `Invalid shorthand: ${e instanceof Error ? e.message : String(e)}`);
+						}
+					}
+				} 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 compile to IR.");
+				}
+				// Schema validation first so a malformed graph gives a clean error.
+				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 ir = await compileTaskflowToIR(def) as TaskflowIR;
+				return {
+					content: [{ type: "text", text: formatFlowIR(ir) }],
+					details: { action } satisfies TaskflowDetails,
+				};
+			}
+
 			if (action === "cache-clear") {
 				const removed = new CacheStore(ctx.cwd).clear();
 				return {
@@ -701,9 +779,10 @@ export default function (pi: ExtensionAPI) {
 				const run = loadRun(ctx.cwd, params.runId);
 				if (!run) return errorResult(action, `Run not found: ${params.runId}`);
 				const reads = readMapOf(run.phases);
+				const declared = declaredReadMapOfDef(run.def);
 				const seeds = params.phaseId ? [String(params.phaseId)] : [];
 				return {
-					content: [{ type: "text", text: formatWhyStale(run.runId, run.flowName, reads, seeds) }],
+					content: [{ type: "text", text: formatWhyStale(run.runId, run.flowName, reads, seeds, declared) }],
 					details: { action } satisfies TaskflowDetails,
 				};
 			}
@@ -931,7 +1010,7 @@ export default function (pi: ExtensionAPI) {
 	pi.registerCommand("tf", {
 		description: "Taskflow: list | run <name> | show <name> | compile <name> | runs | init",
 		getArgumentCompletions: (prefix) => {
-			const subs = ["list", "run", "show", "runs", "resume", "init", "save", "verify", "compile", "provenance", "why-stale", "recompute"];
+			const subs = ["list", "run", "show", "runs", "resume", "init", "save", "verify", "compile", "ir", "provenance", "why-stale", "recompute"];
 			const items = subs.map((s) => ({ value: s, label: s }));
 			const filtered = items.filter((i) => i.value.startsWith(prefix));
 			return filtered.length > 0 ? filtered : null;
@@ -987,6 +1066,30 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 
+			if (sub === "ir") {
+				if (!arg) {
+					ctx.ui.notify("Usage: /tf ir <name>", "warning");
+					return;
+				}
+				const flowName = arg.trim().split(/\s+/)[0];
+				const flow = getFlow(ctx.cwd, flowName);
+				if (!flow) {
+					ctx.ui.notify(`Flow not found: ${flowName}`, "error");
+					return;
+				}
+				// Schema-validate before compiling so a malformed saved flow yields a
+				// clean error rather than a half-rendered report (mirrors action=ir).
+				const vr = validateTaskflow(flow.def, { cwd: ctx.cwd ? String(ctx.cwd) : undefined });
+				if (!vr.ok) {
+					ctx.ui.notify(`Schema validation failed:\n${vr.errors.join("\n")}`, "error");
+					return;
+				}
+				const { compileTaskflowToIR } = await import("./flowir/index.ts");
+				const ir = await compileTaskflowToIR(flow.def);
+				ctx.ui.notify(formatFlowIR(ir), "info");
+				return;
+			}
+
 			if (sub === "provenance") {
 				if (!arg) {
 					ctx.ui.notify("Usage: /tf provenance <runId>", "warning");
@@ -1013,7 +1116,8 @@ export default function (pi: ExtensionAPI) {
 					return;
 				}
 				const reads = readMapOf(run.phases);
-				ctx.ui.notify(formatWhyStale(run.runId, run.flowName, reads, rest), "info");
+				const declared = declaredReadMapOfDef(run.def);
+				ctx.ui.notify(formatWhyStale(run.runId, run.flowName, reads, rest, declared), "info");
 				return;
 			}
 

package/extensions/runtime.ts

@@ -20,8 +20,8 @@ import { type Budget, type CacheScope, dependenciesOf, finalPhase, LOOP_DEFAULT_
 import { verifyTaskflow } from "./verify.ts";
 import { hashInput, newRunId, type PhaseState, type RunState, runsDir } from "./store.ts";
 import { CacheStore, resolveFingerprint } from "./cache.ts";
-import { flowDefHash } from "./flowir/hash.ts";
-import { computeStaleFrontier, readMapOf } from "./stale.ts";
+import { compileTaskflowToIR } from "./flowir/index.ts";
+import { computeStaleFrontier, declaredReadMapOfDef, readMapOf } from "./stale.ts";
 import { ctxDirFor, drainPendingSpawns, initCtxDir, registerNode, setNodeStatus, type SpawnAssignment } from "./context-store.ts";
 import { allocateWorkspace, isWorkspaceKeyword, type Workspace } from "./workspace.ts";
 
@@ -923,7 +923,7 @@ async function executePhaseInner(
 			}
 			if (allPassed) {
 				// All evals passed — skip the LLM gate, return an auto-pass.
-				const inputHash = cacheKey(cc, [phase.id, "eval-skip"]);
+				const inputHash = cacheKeys(cc, [phase.id, "eval-skip"]).key;
 				const ps: PhaseState = {
 					id: phase.id,
 					status: "done",
@@ -943,8 +943,9 @@ async function executePhaseInner(
 		const refWarning = warnUnresolvedRefs(phase.id, interp.missing);
 		const fullTask = preRead + text;
 		const agentName = resolveAgent(phase.agent, deps, state);
-		const inputHash = cacheKey(cc, [phase.id, agentName, phase.model ?? "", fullTask]);
-		const cached = cachedPhase(cc, inputHash);
+		const ck = cacheKeys(cc, [phase.id, agentName, phase.model ?? "", fullTask]);
+		const inputHash = ck.key;
+		const cached = cachedPhase(cc, ck);
 		if (cached) return cached;
 
 		const r = await runOne(agentName, fullTask, liveSink(state, phase.id, emitProgress), nodeIdFor());
@@ -1003,7 +1004,7 @@ async function executePhaseInner(
 				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 retryIH = cacheKeys(cc, [phase.id, agentName, phase.model ?? "", retryTask]).key;
 				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);
@@ -1025,8 +1026,9 @@ async function executePhaseInner(
 				task: preRead + r.text,
 			};
 		});
-		const inputHash = cacheKey(cc, [phase.id, phase.model ?? "", JSON.stringify(branches)]);
-		const cached = cachedPhase(cc, inputHash);
+		const ck = cacheKeys(cc, [phase.id, phase.model ?? "", JSON.stringify(branches)]);
+		const inputHash = ck.key;
+		const cached = cachedPhase(cc, ck);
 		if (cached) return cached;
 
 		const results = await runFanout(branches);
@@ -1066,8 +1068,9 @@ async function executePhaseInner(
 				task: preRead + interpolate(phase.task ?? "", localCtx).text,
 			};
 		});
-		const inputHash = cacheKey(cc, [phase.id, phase.model ?? "", JSON.stringify(tasks)]);
-		const cached = cachedPhase(cc, inputHash);
+		const ck = cacheKeys(cc, [phase.id, phase.model ?? "", JSON.stringify(tasks)]);
+		const inputHash = ck.key;
+		const cached = cachedPhase(cc, ck);
 		if (cached) return cached;
 
 		const results = await runFanout(tasks);
@@ -1087,8 +1090,9 @@ async function executePhaseInner(
 		const readRefs: string[] = [];
 		const ctx = buildInterpolationContext(state, previousOutput, undefined, (ref) => readRefs.push(ref));
 		const message = interpolate(phase.task ?? "Approve to continue?", ctx).text;
-		const inputHash = cacheKey(cc, [phase.id, phase.model ?? "", "approval", message]);
-		const cached = cachedPhase(cc, inputHash);
+		const ck = cacheKeys(cc, [phase.id, phase.model ?? "", "approval", message]);
+		const inputHash = ck.key;
+		const cached = cachedPhase(cc, ck);
 		if (cached) return cached;
 
 		// Non-interactive (headless/CI/detached): auto-REJECT, fail-open, but record it.
@@ -1232,8 +1236,9 @@ async function executePhaseInner(
 		// that a different generated plan yields a different key (and an identical plan
 		// hits cache). For saved flows the name is the identity (historical behavior).
 		const flowIdentity = hasDef ? `def:${JSON.stringify(subDef)}` : `flow:${name}`;
-		const inputHash = cacheKey(cc, [phase.id, flowIdentity, preRead, JSON.stringify(subArgs)]);
-		const cached = cachedPhase(cc, inputHash);
+		const ck = cacheKeys(cc, [phase.id, flowIdentity, preRead, JSON.stringify(subArgs)]);
+		const inputHash = ck.key;
+		const cached = cachedPhase(cc, ck);
 		if (cached) return cached;
 
 		const live = state.phases[phase.id];
@@ -1607,7 +1612,7 @@ function lastCompletedOutput(state: RunState, phase: Phase): string | undefined
  * scope, optional TTL, and a pre-resolved fingerprint string so each phase-type
  * branch can fold it into its inputHash and consult the cross-run store uniformly.
  */
-interface PhaseCacheCtx {
+export interface PhaseCacheCtx {
 	scope: CacheScope;
 	ttlMs?: number;
 	fingerprint: string;
@@ -1638,20 +1643,50 @@ interface PhaseCacheCtx {
 }
 
 /** Fold the phase fingerprint into the base hash parts to form the final cache key. */
-function cacheKey(cc: PhaseCacheCtx, baseParts: string[]): string {
+/** A computed cache identity: the new (versioned) key plus the read-only
+ *  fallback keys used to honor entries written by older releases. The `key`
+ *  is what we WRITE under and what `PhaseState.inputHash` carries; the
+ *  `legacyKey`/`bareKey` are consulted READ-ONLY on a miss so an upgrade
+ *  never produces a miss-storm. See docs/internal/cache-migration.md. */
+export interface CacheKeys {
+	/** Current key: folds `v2:flowdef:<hash>` (the overstory content fingerprint). */
+	key: string;
+	/** Pre-flowDefHash-era key: the flowdef line OMITTED entirely. Read-only. */
+	legacyKey: string;
+	/** Bare (unversioned) `flowdef:` key — written by pre-H1 code that folded
+	 *  the hash without a `v2:` prefix. Read-only. Removed in v0.1.0. */
+	bareKey: string;
+}
+
+/** Fold the phase fingerprint into the base hash parts to form the cache keys.
+ *
+ *  Three keys are produced for backward compatibility (see
+ *  docs/internal/cache-migration.md):
+ *    - `key`      : `v2:flowdef:<hash>` — the current write key.
+ *    - `legacyKey`: the flowdef line omitted — pre-flowDefHash entries.
+ *    - `bareKey`  : bare `flowdef:<hash>` (unversioned) — pre-H1 entries that
+ *      folded the hash without the `v2:` prefix.
+ *  `cachedPhase` consults all three READ-ONLY on a miss; `recordCache` writes
+ *  only `key`. This means an upgrade never produces a miss-storm: existing
+ *  entries (whichever shape) still hit, and new writes converge on `key`. */
+export function cacheKeys(cc: PhaseCacheCtx, baseParts: string[]): CacheKeys {
 	// 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), the
 	// resolved context pre-read content, and the world-state fingerprint.
-	const parts = [
-		`flow:${cc.flowName}`,
-		`flowdef:${cc.flowDefHash ?? ""}`,
+	const tail = [
 		...baseParts,
 		`think:${cc.thinking ?? ""}`,
 		`tools:${JSON.stringify(cc.tools ?? [])}`,
 		`ctx:${cc.preRead ?? ""}`,
 	];
-	return cc.fingerprint ? hashInput(...parts, cc.fingerprint) : hashInput(...parts);
+	const fold = (parts: string[]): string =>
+		cc.fingerprint ? hashInput(...parts, cc.fingerprint) : hashInput(...parts);
+	return {
+		key: fold([`flow:${cc.flowName}`, `v2:flowdef:${cc.flowDefHash ?? ""}`, ...tail]),
+		legacyKey: fold([`flow:${cc.flowName}`, ...tail]),
+		bareKey: fold([`flow:${cc.flowName}`, `flowdef:${cc.flowDefHash ?? ""}`, ...tail]),
+	};
 }
 
 /**
@@ -1660,31 +1695,39 @@ function cacheKey(cc: PhaseCacheCtx, baseParts: string[]): string {
  *   - "run-only": within-run resume only (historical behavior).
  *   - "cross-run": within-run first, then the persistent cross-run store.
  * On a cross-run hit, usage is zeroed and `cacheHit` records the source.
+ *
+ * The cross-run read is THREE-TIER and READ-ONLY for fallback keys: it tries
+ * `keys.key` (current `v2:flowdef:` shape) first, then `keys.bareKey` (pre-H1
+ * bare `flowdef:`), then `keys.legacyKey` (pre-flowDefHash, no flowdef line).
+ * A hit on ANY tier is restored as a cache hit; we do NOT write-through (no
+ * re-store under the new key) so the cache size stays stable and the legacy
+ * entry ages out naturally. See docs/internal/cache-migration.md.
  */
-function cachedPhase(cc: PhaseCacheCtx, inputHash: string): PhaseState | null {
+function cachedPhase(cc: PhaseCacheCtx, keys: CacheKeys): PhaseState | null {
 	if (cc.scope === "off") return null;
 	if (cc.forceRerun) return null;
 
 	// 1. within-run resume (fastest; always allowed unless scope is off)
-	if (cc.prior && cc.prior.status === "done" && cc.prior.inputHash === inputHash) {
+	if (cc.prior && cc.prior.status === "done" && cc.prior.inputHash === keys.key) {
 		return { ...cc.prior, status: "done" };
 	}
 
-	// 2. cross-run memoization (opt-in)
+	// 2. cross-run memoization (opt-in) — three-tier read-only fallback.
 	if (cc.scope === "cross-run") {
-		const e = cc.store.get(inputHash, cc.ttlMs);
-		if (e) {
+		for (const k of [keys.key, keys.bareKey, keys.legacyKey]) {
+			const e = cc.store.get(k, cc.ttlMs);
+			if (!e) continue;
 			// If we stored the full PhaseState, restore it (preserving gate,
 			// approval, reads, loop/tournament metadata, warnings) and just mark
 			// the cache hit + zero usage. Fallback to the legacy trimmed surface
 			// for entries written before this change.
 			if (e.state) {
-				return { ...e.state, inputHash, usage: emptyUsage(), cacheHit: "cross-run", endedAt: Date.now() };
+				return { ...e.state, inputHash: keys.key, usage: emptyUsage(), cacheHit: "cross-run", endedAt: Date.now() };
 			}
 			return {
 				id: cc.phaseId,
 				status: "done",
-				inputHash,
+				inputHash: keys.key,
 				output: e.output,
 				json: e.json,
 				model: e.model,
@@ -1868,6 +1911,7 @@ function hasUnobservedDependencies(state: RunState): boolean {
 		if (p.context && p.context.length > 0) return true;
 		if (scan(p.task ?? "")) return true;
 		if (p.when && scan(p.when)) return true;
+		if (p.until && scan(p.until)) return true;
 		if (Array.isArray(p.eval) && p.eval.some(scan)) return true;
 	}
 	return false;
@@ -1893,7 +1937,12 @@ export async function recomputeTaskflow(
 	// replay; only the caller decides whether to persist the new state.
 	const newState = structuredClone(state) as RunState;
 	const reads = readMapOf(newState.phases);
-	const frontier = computeStaleFrontier(reads, seeds);
+	// M2: derive the declared read-map fresh from the def so the frontier uses
+	// the UNION (observed ∪ declared). Derived here (not read from the persisted
+	// `RunState.declaredDeps`) so old runs — pre-H1, no persisted declaredDeps —
+	// also get union semantics. The persisted field is audit/provenance only.
+	const declared = declaredReadMapOfDef(newState.def);
+	const frontier = computeStaleFrontier(reads, seeds, declared);
 	const allIds = Object.keys(newState.phases);
 
 	if (opts.dryRun) {
@@ -1927,20 +1976,26 @@ export async function recomputeTaskflow(
 
 	// Real recompute: topological order over the frontier so a downstream always
 	// sees its (already-refreshed) upstreams when it re-evaluates its cache key.
-	// The order must respect both declared dependsOn AND observed reads, because
-	// pi-taskflow allows interpolation refs without an explicit dependsOn edge.
+	// The order must respect declared dependsOn, observed reads, AND declared
+	// reads (M2 union): pi-taskflow allows interpolation refs without an
+	// explicit dependsOn edge, and a declared-but-unobserved edge (e.g. a `when`
+	// ref that never fired) must still order the reader after its upstream so
+	// the reader evaluates its cache key against the refreshed upstream (no
+	// false early-cutoff).
 	const seedSet = new Set(seeds);
-	function observedDeps(phaseId: string): string[] {
+	function depsFor(phaseId: string): string[] {
 		// A phase reading its own prior output (e.g. a loop `until` checking
 		// `{steps.thisId.output}`) must not create a self-edge in the scheduling
 		// graph — otherwise topoLayers would deadlock on the self-loop.
-		return (newState.phases[phaseId]?.reads ?? [])
+		const observed = (newState.phases[phaseId]?.reads ?? [])
 			.map((r) => r.stepId)
 			.filter((id) => id !== phaseId);
+		const declared_ = (declared.get(phaseId) ?? []).filter((id) => id !== phaseId);
+		return [...new Set([...observed, ...declared_])];
 	}
 	const augmentedPhases = newState.def.phases.map((p) => ({
 		...p,
-		dependsOn: [...new Set([...(p.dependsOn ?? []), ...observedDeps(p.id)])],
+		dependsOn: [...new Set([...(p.dependsOn ?? []), ...depsFor(p.id)])],
 	}));
 	const order = topoLayers(augmentedPhases)
 		.flat()
@@ -2016,9 +2071,23 @@ async function runTaskflowLayers(state: RunState, deps: RuntimeDeps): Promise<Ru
 	// Reused by every phase, persisted on the RunState for audit/resume.
 	// Never throws into the run — a hash failure leaves the field unset and the
 	// cache key degrades to the legacy flowName-only shape.
+	//
+	// Routed through the FlowIR compile seam (M1): `compileTaskflowToIR`
+	// produces the content-addressed IR whose `hash` (== flowDefHash in the
+	// stub) folds into the cache key, and whose `meta.declaredDeps` (M2 declared
+	// plane) is persisted for audit/provenance. The declared plane is also
+	// derived fresh from `def` in recompute (so old runs get union semantics
+	// too); the persisted copy is for display.
 	if (state.flowDefHash === undefined) {
 		try {
-			state.flowDefHash = await flowDefHash(def);
+			const ir = await compileTaskflowToIR(def);
+			state.flowDefHash = ir.hash ?? "failed";
+			state.declaredDeps = ir.meta.declaredDeps;
+			if (ir.errors.length) {
+				console.warn(
+					`[taskflow] IR compile errors for '${def.name}': ${ir.errors.map((e) => e.message).join("; ")}`,
+				);
+			}
 		} catch (e) {
 			// Fail-safe: warn loudly rather than silently degrading to the legacy
 			// flowName-only key, which would reopen the cross-flow collision hole.

package/extensions/schema.ts

@@ -781,7 +781,7 @@ export function validateTaskflow(def: unknown, opts: ValidationOptions = {}): Va
 	return { ok: errors.length === 0, errors, warnings };
 }
 
-function collectRefs(phase: Phase): { steps: string[]; args: string[] } {
+export function collectRefs(phase: Phase): { steps: string[]; args: string[] } {
 	const steps = new Set<string>();
 	const args = new Set<string>();
 	const scan = (s: string | undefined) => {
@@ -795,6 +795,8 @@ function collectRefs(phase: Phase): { steps: string[]; args: string[] } {
 	scan(phase.task);
 	scan(phase.over);
 	scan(phase.when);
+	scan(phase.until);
+	for (const e of phase.eval ?? []) scan(e);
 	for (const b of phase.branches ?? []) scan(b.task);
 	for (const v of Object.values(phase.with ?? {})) if (typeof v === "string") scan(v);
 	for (const c of phase.context ?? []) scan(c);

package/extensions/stale.ts

@@ -23,6 +23,7 @@
  */
 
 import type { PhaseState } from "./store.ts";
+import { collectRefs, type Taskflow } from "./schema.ts";
 
 // ---------------------------------------------------------------------------
 // Read graph
@@ -41,13 +42,24 @@ export function readMapOf(phases: Record<string, PhaseState>): ReadMap {
 	return m;
 }
 
-/** Phases that directly read `phaseId` (its immediate dependents). */
-export function dependentsOf(reads: ReadMap, phaseId: string): string[] {
-	const out: string[] = [];
+/** Phases that directly read `phaseId` (its immediate dependents).
+ *
+ *  When `declared` is provided, the dependent set is the **union** of
+ *  observed dependents (from `reads`) and declared dependents (from
+ *  `declared`) — a declared-but-unobserved edge (e.g. a `when` ref that never
+ *  fired) still counts as a dependency for staleness propagation (M2 union).
+ *  `declared` undefined → observed-only (backward-compatible). */
+export function dependentsOf(reads: ReadMap, phaseId: string, declared?: ReadMap): string[] {
+	const out = new Set<string>();
 	for (const [reader, deps] of reads) {
-		if (deps.includes(phaseId)) out.push(reader);
+		if (deps.includes(phaseId)) out.add(reader);
+	}
+	if (declared) {
+		for (const [reader, deps] of declared) {
+			if (deps.includes(phaseId)) out.add(reader);
+		}
 	}
-	return out;
+	return [...out];
 }
 
 // ---------------------------------------------------------------------------
@@ -56,27 +68,53 @@ export function dependentsOf(reads: ReadMap, phaseId: string): string[] {
 
 /**
  * The set of phases that are stale if `seeds` change, transitively. A reader
- * is stale if ANY phase it observed-reading is stale (union/I5: when in doubt,
- * assume dependency). Includes the seeds themselves.
+ * is stale if ANY phase it (observed- OR declared-)reading is stale
+ * (union/I5: when in doubt, assume dependency). Includes the seeds themselves.
+ *
+ * When `declared` is provided, the read graph used for propagation is the
+ * **union** of `reads` (observed, M3) and `declared` (M2 compile-time refs):
+ * a declared-but-unobserved edge still propagates staleness. `declared`
+ * undefined → observed-only (backward-compatible, identical to pre-M2).
  *
  * Deterministic. O(phases + read-edges). Cycles in the read graph (which a
  * correct DAG can't produce, but a pathological one could) terminate because a
  * phase is enqueued at most once.
  */
-export function computeStaleFrontier(reads: ReadMap, seeds: Iterable<string>): Set<string> {
+export function computeStaleFrontier(reads: ReadMap, seeds: Iterable<string>, declared?: ReadMap): Set<string> {
 	const stale = new Set<string>();
 	const queue: string[] = [...seeds];
 	while (queue.length) {
 		const s = queue.shift() as string;
 		if (stale.has(s)) continue;
 		stale.add(s);
-		for (const dep of dependentsOf(reads, s)) {
+		for (const dep of dependentsOf(reads, s, declared)) {
 			if (!stale.has(dep)) queue.push(dep);
 		}
 	}
 	return stale;
 }
 
+// ---------------------------------------------------------------------------
+// Declared-plane derivation (M2)
+// ---------------------------------------------------------------------------
+
+/** Build a declared ReadMap from a flow definition: each phase's `collectRefs`
+ *  `{steps.X}` refs become its declared reads (self-refs excluded so a loop
+ *  `until` checking `{steps.thisId.output}` doesn't create a self-edge).
+ *
+ *  Pure. Used by `recomputeTaskflow` and `/tf why-stale` so union (observed ∪
+ *  declared) semantics apply to old runs too (pre-H1 runs have no persisted
+ *  `RunState.declaredDeps` — deriving from `def` keeps recompute sound). */
+export function declaredReadMapOfDef(def: Taskflow): ReadMap {
+	const m: ReadMap = new Map();
+	for (const p of def.phases) {
+		const refs = collectRefs(p);
+		const reads = refs.steps.filter((id) => id !== p.id);
+		if (reads.length) m.set(p.id, reads);
+	}
+	return m;
+}
+
 // ---------------------------------------------------------------------------
 // Rendering
 // ---------------------------------------------------------------------------
@@ -85,12 +123,18 @@ export function computeStaleFrontier(reads: ReadMap, seeds: Iterable<string>): S
  * Render either the full observed dependency graph (no seeds) or the stale
  * frontier given assumed-changed seeds. Each stale phase lists the stale
  * upstreams that caused it (its "why").
+ *
+ * When `declared` is provided, the frontier is the **union** (observed ∪
+ * declared) and a stale phase's "why" annotates edges present only in the
+ * declared plane (not observed at runtime) with `(declared)`. `declared`
+ * undefined → observed-only rendering (backward-compatible).
  */
 export function formatWhyStale(
 	runId: string,
 	flowName: string,
 	reads: ReadMap,
 	seeds: readonly string[],
+	declared?: ReadMap,
 ): string {
 	const lines: string[] = [];
 	lines.push(`why-stale — run ${runId} · flow "${flowName}"`);
@@ -98,26 +142,32 @@ export function formatWhyStale(
 
 	if (seeds.length === 0) {
 		// No seeds → show the full observed dependency graph (who reads what).
-		if (reads.size === 0) {
+		if (reads.size === 0 && (!declared || declared.size === 0)) {
 			lines.push("(No observed readSets in this run — provenance is empty.)");
 			return lines.join("\n");
 		}
 		lines.push("Observed dependency graph (who reads what):");
 		lines.push("");
-		for (const [reader, deps] of reads) {
-			lines.push(`■ ${reader}  reads: ${deps.join(", ")}`);
+		const allReaders = new Set<string>([...reads.keys(), ...(declared?.keys() ?? [])]);
+		for (const reader of allReaders) {
+			const obs = reads.get(reader) ?? [];
+			const dec = declared?.get(reader) ?? [];
+			const parts: string[] = [];
+			for (const d of obs) parts.push(d);
+			for (const d of dec) if (!obs.includes(d)) parts.push(`${d} (declared)`);
+			lines.push(`■ ${reader}  reads: ${parts.join(", ") || "(none)"}`);
 		}
 		lines.push("");
 		lines.push("Pass a phase id to compute its stale frontier: /tf why-stale <runId> <phaseId>");
 		return lines.join("\n");
 	}
 
-	const frontier = computeStaleFrontier(reads, seeds);
+	const frontier = computeStaleFrontier(reads, seeds, declared);
 	const seedSet = new Set(seeds);
 	lines.push(`Assuming changed: ${[...seedSet].join(", ")}`);
 	lines.push("");
 	if (frontier.size <= seedSet.size) {
-		lines.push(`Stale frontier: only the seed(s) themselves — nothing else observed-reading them.`);
+		lines.push(`Stale frontier: only the seed(s) themselves — nothing else reads them.`);
 		return lines.join("\n");
 	}
 	lines.push(`Stale frontier (transitive, ${frontier.size} phases):`);
@@ -127,10 +177,16 @@ export function formatWhyStale(
 		if (seedSet.has(id)) {
 			lines.push(`  ■ ${id}  (changed — seed)`);
 		} else {
-			// Why is it stale? The stale upstreams it read.
-			const deps = reads.get(id) ?? [];
-			const causes = deps.filter((d) => frontier.has(d));
-			lines.push(`  ■ ${id}  ← reads ${causes.length ? causes.join(", ") : "(nothing stale?)"}`);
+			// Why is it stale? The stale upstreams it read (observed ∪ declared).
+			const obs = reads.get(id) ?? [];
+			const dec = declared?.get(id) ?? [];
+			const obsCauses = obs.filter((d) => frontier.has(d));
+			const decCauses = dec.filter((d) => frontier.has(d) && !obs.includes(d));
+			const causeStr = [
+				...obsCauses,
+				...decCauses.map((d) => `${d} (declared)`),
+			].join(", ");
+			lines.push(`  ■ ${id}  ← reads ${causeStr || "(nothing stale?)"}`);
 		}
 	}
 	return lines.join("\n");

package/extensions/store.ts

@@ -21,6 +21,7 @@ import * as path from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import type { Taskflow } from "./schema.ts";
 import type { UsageStats } from "./usage.ts";
+import type { DeclaredDeps } from "./flowir/meta.ts";
 
 export interface SavedFlow {
 	name: string;
@@ -103,6 +104,16 @@ export interface RunState {
 	 *  re-run always reuses them. Filled once at run start; persisted for
 	 *  audit/resume consistency. */
 	flowDefHash?: string | "failed";
+	/** Per-phase *declared* dependency footprint (M2), synthesized at compile
+	 *  time from `{steps.X}` interpolation refs via `compileTaskflowToIR`.
+	 *  This is the *declared* plane — distinct from the *observed* readSet
+	 *  (`PhaseState.reads`, captured at runtime). Recompute staleness uses the
+	 *  **union** (observed ∪ declared) so a declared-but-unobserved edge (e.g.
+	 *  a `when` ref that never fired) still propagates. JSON-safe `Record`
+	 *  shape so it round-trips through persistence. Audit/provenance only —
+	 *  recompute derives this fresh from `def` so old runs (pre-H1) also get
+	 *  union semantics. */
+	declaredDeps?: Record<string, DeclaredDeps>;
 }
 
 // ---------------------------------------------------------------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-taskflow",
-  "version": "0.0.25",
+  "version": "0.0.26",
   "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",