pi-taskflow 0.0.23 → 0.0.25

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 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.24] — 2026-06-23
+
+> Feature release: **`/tf compile`** — turn the declared DAG into a Mermaid
+> diagram plus a verification overlay for 0 tokens. A picture of the plan, a
+> structural audit of the plan, and a GitHub-pastable artifact — all from the
+> same JSON.
+
+### Added
+- **`compile` action** for the `taskflow` tool and the `/tf compile <name>`
+  command. Renders the flow as a Mermaid `flowchart`, overlays verification
+  issues onto the nodes (red = error, amber = warning, green border = final),
+  and emits a markdown document suitable for READMEs / issues / PRs.
+- Distinct shapes for every phase kind: agent ▭, parallel/map/flow ⊐, reduce ▽,
+  gate ◇, approval ⏸, loop ↻, tournament ⬡. Guards become edge labels;
+  `join: "any"` becomes dotted edges.
+- Reuses the existing `verifyTaskflow` graph analysis, so every dead-end,
+  unreachable node, gate-exhaustion, budget overflow, concurrency warning, and
+  guard contradiction is painted directly on the diagram.
+- Zero runtime dependencies; the compiler is a pure function with no LLM calls.
+- Tests: 670 → 702 (+32) in `test/compile.test.ts` — structural assertions on
+  the emitted Mermaid tokens (no third-party parser dependency; render-
+  correctness is validated by shape/edge/class assertions).
+
+### Fixed
+- **Id collisions no longer merge nodes.** Two distinct phase ids that
+  sanitize to the same Mermaid token (e.g. `audit-each` and `audit_each`) are
+  now disambiguated with a `_2` suffix instead of collapsing into one node with
+  an accidental self-loop.
+- **Markdown-injection hardening.** Free-form strings (flow name, description,
+  verification messages) are neutralized before interpolation, so a
+  multi-line / bracket-laden name can no longer break out of the H1 heading or
+  spawn a second blockquote.
+- **`/tf compile <name>` now schema-validates first**, matching the tool action
+  — a malformed saved flow yields a clean error instead of a half-rendered
+  diagram. An optional `lr`/`td` suffix selects diagram direction.
+- Backslashes are now escaped inside Mermaid labels.
+
 ## [0.0.23] — 2026-06-11
 
 > Feature release: the **Shared Context Tree** — an opt-in mechanism that gives

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-670-6E8BFF?style=flat-square" alt="670 tests"></a>
+  <a href="#whats-inside"><img src="https://img.shields.io/badge/tests-702-6E8BFF?style=flat-square" alt="702 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>
@@ -508,12 +508,13 @@ Saved flows become CLI shortcuts. All commands run in the Pi session:
 | `/tf list` | List all saved flows |
 | `/tf run <name> [args]` | Run a saved flow (e.g. `/tf run summarize-files dir=src`) |
 | `/tf show <name>` | Print a flow's definition |
+| `/tf compile <name> [lr\|td]` | **Render the flow as a Mermaid diagram + verification overlay** — 0 tokens, no LLM; paste into a README/issue/PR |
 | `/tf runs` | Browse recent run history (interactive TUI — **live auto-refreshes** while any run is active) |
 | `/tf resume <runId>` | Continue a paused/failed run — cached phases skip automatically |
 | `/tf init` | **Interactively map model roles** to your enabled models (writes `~/.pi/agent/settings.json`) |
 | `/tf:<name> [args]` | Shortcut — runs the flow in one tap |
 
-Tool actions (used by the model): `run` (inline `define` or saved `name`), `save`, `resume`, `list`, `agents`, `init`, `verify`, `cache-clear`.
+Tool actions (used by the model): `run` (inline `define` or saved `name`), `save`, `resume`, `list`, `agents`, `init`, `verify`, `compile`, `cache-clear`.
 
 ## Background (detached) execution
 
@@ -727,12 +728,12 @@ Copy one into `.pi/taskflows/<name>.json` (or `~/.pi/agent/taskflows/`) and it r
 
 <div align="center">
 
-**0 runtime dependencies** · **670 tests** · **9 phase types** · **shared context tree** · **cross-session resume** · **cross-run memoization** · **detached execution** · **~9k LOC runtime**
+**0 runtime dependencies** · **702 tests** · **9 phase types** · **shared context tree** · **cross-session resume** · **cross-run memoization** · **detached execution** · **`compile` Mermaid renderer** · **~9k 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.
-- **670 tests across 33 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, the shared context tree (blackboard reuse, supervision spawn, subflow validation/nesting), workspace isolation (temp/dedicated/worktree lifecycle, fail-open degrade, dynamic-flow rejection), dynamic sub-flow security hardening, detached execution (PID persistence, stale detection, crash→failed, resume after failure), live run-history refresh, callback isolation, the idle watchdog, model-role init config, parseModelFromLabel with parenthesized-model-name regression, and multi-fence `safeParse` recovery.
+- **702 tests across 34 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, the shared context tree (blackboard reuse, supervision spawn, subflow validation/nesting), workspace isolation (temp/dedicated/worktree lifecycle, fail-open degrade, dynamic-flow rejection), dynamic sub-flow security hardening, detached execution (PID persistence, stale detection, crash→failed, resume after failure), live run-history refresh, callback isolation, the idle watchdog, model-role init config, parseModelFromLabel with parenthesized-model-name regression, and multi-fence `safeParse` recovery, plus the `compile` Mermaid renderer (id-collision disambiguation, markdown-injection hardening, and full verify-overlay category coverage).
 - **Hardened by design.** Path-traversal defense (lexical + `realpath` containment check), runId validation, HTML/error sanitization, atomic writes, stale-lock stealing via `rename`, and an idle watchdog that kills wedged subagents (SIGTERM → SIGKILL after 5 minutes of silence). Dynamic sub-flows additionally get breadth caps, `cwd` containment, budget clamping, nesting depth caps, and prototype-pollution defense.
 - **Dogfooded.** Every new feature has to survive the project's own `self-improve` taskflow before it ships.
 

package/README.zh-CN.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-702-6E8BFF?style=flat-square" alt="702 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>

package/extensions/cache.ts

@@ -17,7 +17,7 @@ import { execFileSync } from "node:child_process";
 import * as crypto from "node:crypto";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { cacheDir, withLock, writeFileAtomic } from "./store.ts";
+import { cacheDir, withLock, writeFileAtomic, type PhaseState } from "./store.ts";
 
 // ---------------------------------------------------------------------------
 // Fingerprint resolution
@@ -144,6 +144,11 @@ export interface CacheEntry {
 	output?: string;
 	json?: unknown;
 	model?: string;
+	/** Full PhaseState payload preserved so cross-run reuse is semantically
+	 *  equivalent to within-run resume. Storing only output/json would drop
+	 *  `gate`, `approval`, `reads`, `loop`, `tournament`, `warnings`, etc.,
+	 *  breaking recompute soundness and gate-block detection. */
+	state?: PhaseState;
 	/** Provenance for audit / cleanup. */
 	flowName?: string;
 	phaseId?: string;

package/extensions/compile.ts

@@ -0,0 +1,371 @@
+/**
+ * Compile a taskflow DAG to portable artifacts — zero-token, no LLM.
+ *
+ * `compileTaskflow` turns the declarative graph into:
+ *   - a **Mermaid `flowchart`** that GitHub / GitLab / many markdown viewers
+ *     render natively, so the DAG you declared can be screenshotted, pasted
+ *     into a PR/issue/README, and diffed as text;
+ *   - a **verification report** (the existing `verifyTaskflow` passes) whose
+ *     issues are *overlaid onto the diagram* — a phase with an error is painted
+ *     red, a warning amber — so the picture and the problems are one artifact.
+ *
+ * This is the visualization leg of the project thesis ("the plan is data, so it
+ * can be verified, visualized, and replayed"): the same JSON renders a graph and
+ * a structural audit without spending a token. It is a pure function — no I/O.
+ */
+
+import type { Phase, Taskflow } from "./schema.ts";
+import {
+	LOOP_DEFAULT_MAX_ITERATIONS,
+	TOURNAMENT_DEFAULT_VARIANTS,
+} from "./schema.ts";
+import { verifyTaskflow, type VerificationIssue, type VerificationResult } from "./verify.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface CompileResult {
+	/** A Mermaid `flowchart` source block (no fences). */
+	mermaid: string;
+	/** The static verification result the diagram is annotated with. */
+	verification: VerificationResult;
+	/** A self-contained markdown document: diagram (fenced) + verification report. */
+	markdown: string;
+}
+
+export interface CompileOptions {
+	/** Diagram direction. Default "TD" (top-down). "LR" for wide fan-outs. */
+	direction?: "TD" | "LR";
+	/** Document title (defaults to the flow name). */
+	title?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Label / id sanitization
+// ---------------------------------------------------------------------------
+
+/** Mermaid node ids must be free of spaces and syntax chars. Phase ids are
+ *  already `[A-Za-z0-9_-]`-ish, but we defensively map anything else to `_`. */
+function nodeId(phaseId: string): string {
+	const cleaned = phaseId.replace(/[^A-Za-z0-9_]/g, "_");
+	// A leading digit is legal in Mermaid ids, but prefix to avoid edge-case
+	// parsers and keep ids stable/unique.
+	return /^[A-Za-z_]/.test(cleaned) ? cleaned : `p_${cleaned}`;
+}
+
+/** Build a stable, collision-free mapping from raw phase ids to Mermaid node
+ *  ids. Two distinct raw ids can sanitize to the same node id (e.g.
+ *  `audit-each` and `audit_each` both collapse to `audit_each`); we
+ *  disambiguate by appending `_<n>` so every phase renders as its own node and
+ *  edges never form accidental self-loops. The map covers every phase id plus
+ *  every id referenced in `dependsOn`, so an edge resolves to the same node as
+ *  the definition. Deterministic — input order is preserved. */
+function buildNodeIds(phases: Phase[]): Map<string, string> {
+	const idMap = new Map<string, string>();
+	const used = new Set<string>();
+	const ordered: string[] = [];
+	const seen = new Set<string>();
+	for (const p of phases) {
+		if (seen.has(p.id)) continue;
+		seen.add(p.id);
+		ordered.push(p.id);
+	}
+	for (const p of phases) {
+		for (const d of p.dependsOn ?? []) {
+			if (!seen.has(d)) {
+				seen.add(d);
+				ordered.push(d);
+			}
+		}
+	}
+	for (const raw of ordered) {
+		const base = nodeId(raw);
+		let safe = base;
+		let n = 2;
+		while (used.has(safe)) {
+			safe = `${base}_${n}`;
+			n++;
+		}
+		used.add(safe);
+		idMap.set(raw, safe);
+	}
+	return idMap;
+}
+
+/** Escape text for use inside a Mermaid double-quoted label. Mermaid uses HTML
+ *  entities inside quoted strings; quotes and angle brackets must be encoded,
+ *  and newlines become `<br/>`. */
+function label(text: string): string {
+	return text
+		.replace(/&/g, "&amp;")
+		.replace(/"/g, "&quot;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/\\/g, "&#92;")
+		.replace(/\r?\n/g, "<br/>");
+}
+
+/** Truncate a task prompt to a single readable line for the node body. */
+function summarize(text: string | undefined, max = 48): string {
+	if (!text) return "";
+	const firstLine = text.replace(/\s+/g, " ").trim();
+	return firstLine.length > max ? `${firstLine.slice(0, max - 1)}…` : firstLine;
+}
+
+/** Escape a free-form string for use as inline markdown text (titles,
+ *  descriptions, report fields). Collapses whitespace to a single space so a
+ *  multi-line name/description can't break out of a heading or blockquote, and
+ *  neutralizes characters that start markdown constructs: backticks (code
+ *  spans), brackets (links/images), angle brackets (raw HTML), and backslashes
+ *  (escape sequences). */
+function mdInline(text: string | undefined): string {
+	if (!text) return "";
+	return text
+		.replace(/\s+/g, " ")
+		.trim()
+		.replace(/\\/g, "\\\\")
+		.replace(/`/g, "\\`")
+		.replace(/\[/g, "\\[")
+		.replace(/\]/g, "\\]")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;");
+}
+
+// ---------------------------------------------------------------------------
+// Per-type node rendering
+// ---------------------------------------------------------------------------
+
+/** A short type tag shown above the task summary so the shape is unambiguous
+ *  even in monochrome renders. */
+function typeTag(p: Phase): string {
+	switch (p.type) {
+		case "parallel":
+			return `▦ parallel ×${p.branches?.length ?? 0}`;
+		case "map":
+			return `⇉ map over ${p.over ?? "?"}`;
+		case "gate":
+			return p.eval?.length ? `◇ gate (+${p.eval.length} eval)` : "◇ gate";
+		case "reduce":
+			return `▽ reduce ←${p.from?.length ?? 0}`;
+		case "approval":
+			return "⏸ approval";
+		case "flow":
+			return p.use ? `⊞ flow: ${p.use}` : "⊞ flow (inline)";
+		case "loop":
+			return `↻ loop ≤${p.maxIterations ?? LOOP_DEFAULT_MAX_ITERATIONS}`;
+		case "tournament":
+			return `🏆 tournament ×${p.variants ?? (p.branches?.length || TOURNAMENT_DEFAULT_VARIANTS)}`;
+		default:
+			return "▸ agent";
+	}
+}
+
+/** The body text inside a node: id, type tag, a task summary, agent. */
+function nodeBody(p: Phase): string {
+	const lines: string[] = [];
+	lines.push(`<b>${label(p.id)}</b>${p.final ? " ★" : ""}`);
+	lines.push(label(typeTag(p)));
+	const summary =
+		p.type === "reduce" || p.type === "parallel"
+			? summarize(p.task) // may be empty for these
+			: summarize(p.task ?? p.judge);
+	if (summary) lines.push(label(summary));
+	if (p.agent) lines.push(label(`@${p.agent}`));
+	return lines.join("<br/>");
+}
+
+/** Wrap the body in the Mermaid shape that matches the phase kind. Distinct
+ *  shapes make the control-flow role readable at a glance:
+ *   - agent      → rectangle
+ *   - parallel   → subroutine (parallel fan-out)
+ *   - map        → subroutine (dynamic fan-out)
+ *   - flow       → subroutine (nested DAG)
+ *   - reduce     → trapezoid (many → one)
+ *   - gate       → rhombus (decision)
+ *   - approval   → double-circle (human stop)
+ *   - loop       → stadium (cyclic)
+ *   - tournament → hexagon (compete)
+ */
+function nodeShape(p: Phase, idMap: Map<string, string>): string {
+	const id = idMap.get(p.id) ?? p.id;
+	const body = `"${nodeBody(p)}"`;
+	switch (p.type) {
+		case "parallel":
+		case "map":
+		case "flow":
+			return `${id}[[${body}]]`;
+		case "reduce":
+			return `${id}[/${body}\\]`;
+		case "gate":
+			return `${id}{${body}}`;
+		case "approval":
+			return `${id}(((${body})))`;
+		case "loop":
+			return `${id}([${body}])`;
+		case "tournament":
+			return `${id}{{${body}}}`;
+		default:
+			return `${id}[${body}]`;
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Edge rendering
+// ---------------------------------------------------------------------------
+
+/** Build the directed edges from `dependsOn`. A `when` guard becomes an edge
+ *  label; a `join: "any"` dependency is drawn dotted (races, not waits-all). */
+function edges(phases: Phase[], idMap: Map<string, string>): string[] {
+	const known = new Set(phases.map((p) => p.id));
+	const out: string[] = [];
+	for (const p of phases) {
+		const deps = p.dependsOn ?? [];
+		for (const d of deps) {
+			if (!known.has(d)) continue; // dangling ref — schema/verify reports it
+			const from = idMap.get(d) ?? d;
+			const to = idMap.get(p.id) ?? p.id;
+			const guard = p.when ? `|"${label(summarize(p.when, 40))}"|` : "";
+			// 'any' join: this phase fires on the FIRST dep — draw dotted so the
+			// race semantics are visible.
+			const arrow = p.join === "any" ? "-.->" : "-->";
+			out.push(`${from} ${arrow}${guard} ${to}`);
+		}
+	}
+	return out;
+}
+
+// ---------------------------------------------------------------------------
+// Issue overlay
+// ---------------------------------------------------------------------------
+
+const CLASS_ERROR = "tfError";
+const CLASS_WARN = "tfWarn";
+const CLASS_FINAL = "tfFinal";
+
+/** Map each phase id to its worst severity so the node can be painted. */
+function severityByPhase(issues: VerificationIssue[]): Map<string, "error" | "warning"> {
+	const m = new Map<string, "error" | "warning">();
+	for (const i of issues) {
+		if (!i.phaseId) continue;
+		const prev = m.get(i.phaseId);
+		if (i.severity === "error" || prev === undefined) m.set(i.phaseId, i.severity);
+	}
+	return m;
+}
+
+// ---------------------------------------------------------------------------
+// Mermaid assembly
+// ---------------------------------------------------------------------------
+
+function buildMermaid(flow: Taskflow, verification: VerificationResult, opts: CompileOptions): string {
+	const phases = flow.phases ?? [];
+	const dir = opts.direction ?? "TD";
+	const idMap = buildNodeIds(phases);
+	const sev = severityByPhase(verification.issues);
+
+	const lines: string[] = [];
+	lines.push(`flowchart ${dir}`);
+
+	// Nodes
+	for (const p of phases) lines.push(`\t${nodeShape(p, idMap)}`);
+
+	// Edges
+	const e = edges(phases, idMap);
+	if (e.length) {
+		lines.push("");
+		for (const edge of e) lines.push(`\t${edge}`);
+	}
+
+	// Class definitions (issue overlay + final marker). Colors are chosen to
+	// read on both light and dark GitHub themes.
+	lines.push("");
+	lines.push(`\tclassDef ${CLASS_ERROR} fill:#3b0d0d,stroke:#ef4444,stroke-width:2px,color:#fecaca;`);
+	lines.push(`\tclassDef ${CLASS_WARN} fill:#3a2e05,stroke:#f59e0b,stroke-width:2px,color:#fde68a;`);
+	lines.push(`\tclassDef ${CLASS_FINAL} stroke:#43d9ad,stroke-width:3px;`);
+
+	// Final phases get a distinct border (unless they already carry an issue,
+	// where the issue color wins — a final node that's broken should read red).
+	const finals = phases.filter((p) => p.final && !sev.has(p.id)).map((p) => idMap.get(p.id) ?? p.id);
+	if (finals.length) lines.push(`\tclass ${finals.join(",")} ${CLASS_FINAL};`);
+
+	const errNodes = [...sev].filter(([, s]) => s === "error").map(([id]) => idMap.get(id) ?? id);
+	const warnNodes = [...sev].filter(([, s]) => s === "warning").map(([id]) => idMap.get(id) ?? id);
+	if (errNodes.length) lines.push(`\tclass ${errNodes.join(",")} ${CLASS_ERROR};`);
+	if (warnNodes.length) lines.push(`\tclass ${warnNodes.join(",")} ${CLASS_WARN};`);
+
+	return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Verification report (markdown)
+// ---------------------------------------------------------------------------
+
+function buildReport(flow: Taskflow, verification: VerificationResult): string {
+	const lines: string[] = [];
+	const errors = verification.issues.filter((i) => i.severity === "error");
+	const warnings = verification.issues.filter((i) => i.severity === "warning");
+	const phaseCount = flow.phases?.length ?? 0;
+
+	lines.push(`**Phases:** ${phaseCount}  ·  **Errors:** ${errors.length}  ·  **Warnings:** ${warnings.length}  ·  **Status:** ${verification.ok ? "✅ PASS" : "❌ FAIL"}`);
+
+	if (verification.issues.length === 0) {
+		lines.push("");
+		lines.push("✅ No structural issues found — the DAG is well-formed (no cycles, dead-ends, gate exhaustion, ref or budget problems).");
+		return lines.join("\n");
+	}
+
+	if (errors.length) {
+		lines.push("");
+		lines.push(`### ❌ Errors (${errors.length})`);
+		for (const e of errors)
+			lines.push(`- **${e.category}**${e.phaseId ? ` \`${mdInline(e.phaseId)}\`` : ""}: ${mdInline(e.message)}`);
+	}
+	if (warnings.length) {
+		lines.push("");
+		lines.push(`### ⚠️ Warnings (${warnings.length})`);
+		for (const w of warnings)
+			lines.push(`- **${w.category}**${w.phaseId ? ` \`${mdInline(w.phaseId)}\`` : ""}: ${mdInline(w.message)}`);
+	}
+	return lines.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Entry point
+// ---------------------------------------------------------------------------
+
+/**
+ * Compile a (already schema-valid) taskflow into a Mermaid diagram + verification
+ * report. Pure function — zero tokens, no LLM, no I/O.
+ */
+export function compileTaskflow(flow: Taskflow, opts: CompileOptions = {}): CompileResult {
+	const verification = verifyTaskflow({
+		name: flow.name ?? "taskflow",
+		phases: flow.phases ?? [],
+		budget: flow.budget,
+		concurrency: flow.concurrency,
+	});
+
+	const mermaid = buildMermaid(flow, verification, opts);
+	const report = buildReport(flow, verification);
+	const title = opts.title ?? flow.name ?? "taskflow";
+
+	const mdLines: string[] = [];
+	mdLines.push(`# Taskflow: ${mdInline(title)}`);
+	mdLines.push("");
+	if (flow.description) mdLines.push(`> ${mdInline(flow.description)}`);
+	mdLines.push("```mermaid");
+	mdLines.push(mermaid);
+	mdLines.push("```");
+	mdLines.push("");
+	mdLines.push("## Verification");
+	mdLines.push("");
+	mdLines.push(report);
+	mdLines.push("");
+	mdLines.push(
+		"> Legend: ▸ agent · ▦ parallel · ⇉ map · ◇ gate · ▽ reduce · ⏸ approval · ⊞ flow · ↻ loop · 🏆 tournament · ★ final. Red = error, amber = warning, green border = final. Dotted edge = `join:any`. Generated by `pi-taskflow compile` — 0 tokens.",
+	);
+	const markdown = mdLines.join("\n");
+
+	return { mermaid, verification, markdown };
+}

package/extensions/flowir/hash.ts

@@ -0,0 +1,97 @@
+/**
+ * Content-addressed hashing for flow definitions.
+ *
+ * The canonical-JSON + SHA-256-truncation algorithm here is **vendored from
+ * overstory `packages/core/src/ir/hash.ts`** (pinned commit) so that
+ * pi-taskflow and overstory share one byte-identical hashing contract. This is
+ * the `M1` slice of the overstory-convergence roadmap: we are *not* compiling
+ * to overstory FlowIR yet (the IR compiler expects an explicit inject/emits
+ * model pi-taskflow doesn't have), but we share the **hash algorithm** now —
+ * the cheapest, lowest-risk piece of the contract — and put it to immediate
+ * work folding the flow *definition* into the cross-run cache key (M2).
+ *
+ * Why this matters: previously the cache key folded only the flow **name**
+ * (`flow:${flowName}`), so two structurally-different flows that happened to
+ * share a name + phase id + task could collide in the cross-run cache, and a
+ * flow that changed structure (but not name) could serve a stale hit. Folding
+ * `flowDefHash` (a content fingerprint of the desugared definition) closes
+ * that hole and is the foundation of "identical re-run is free ($0.00)".
+ *
+ * Pure module: no IO. Uses Web Crypto (`globalThis.crypto.subtle`) — therefore
+ * async — exactly like overstory's `hashIR`, so the contract is identical.
+ *
+ * @see docs/internal/overstory-convergence-roadmap.md §3 (M1, "cut B")
+ * @see docs/internal/rfc-flowir-compilation.md
+ */
+
+import type { Taskflow } from "../schema.ts";
+
+// ---------------------------------------------------------------------------
+// Canonical JSON (vendored from overstory ir/hash.ts — byte-identical)
+// ---------------------------------------------------------------------------
+
+/**
+ * Deterministic JSON: recursively key-sorted (UTF-16 code units), no
+ * whitespace, `undefined` values dropped. Arrays keep their order (the
+ * desugared Taskflow is already in a canonical shape). Byte-identical to
+ * overstory's `canonicalJson` — do not diverge without bumping the contract
+ * and updating the parity test.
+ */
+export function canonicalJson(value: unknown): string {
+	if (value === null || typeof value === "number" || typeof value === "boolean") {
+		return JSON.stringify(value);
+	}
+	if (typeof value === "string") {
+		return JSON.stringify(value);
+	}
+	if (Array.isArray(value)) {
+		return `[${value.map((item) => canonicalJson(item === undefined ? null : item)).join(",")}]`;
+	}
+	if (typeof value === "object") {
+		const record = value as Record<string, unknown>;
+		const keys = Object.keys(record)
+			.filter((key) => record[key] !== undefined)
+			.sort();
+		const body = keys.map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`);
+		return `{${body.join(",")}}`;
+	}
+	// undefined / function / symbol at the top level — not representable.
+	return "null";
+}
+
+// ---------------------------------------------------------------------------
+// Hashing (vendored from overstory ir/hash.ts — byte-identical)
+// ---------------------------------------------------------------------------
+
+/** SHA-256 of the canonical serialization, first 16 bytes, lowercase hex.
+ *  Same shape as overstory's `hashCanonical` / RFC-001 content hashes. */
+export async function hashCanonical(canonical: string): Promise<string> {
+	const bytes = new TextEncoder().encode(canonical);
+	const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+	const view = new Uint8Array(digest).slice(0, 16);
+	let hex = "";
+	for (const byte of view) {
+		hex += byte.toString(16).padStart(2, "0");
+	}
+	return hex;
+}
+
+// ---------------------------------------------------------------------------
+// Flow-definition fingerprint
+// ---------------------------------------------------------------------------
+
+/**
+ * Content fingerprint of a desugared `Taskflow` definition.
+ *
+ * Hashes the **definition** (structure + task text + declared deps), NOT the
+ * runtime `args` values — args vary per invocation and are already folded into
+ * each phase's `inputHash` via the interpolated task. `flowDefHash` answers a
+ * different question: "did the flow *itself* change?" Two flows are
+ * definitionally identical ⟺ this hash matches (key order / whitespace /
+ * optional-field presence do not affect it).
+ *
+ * Deterministic and async (Web Crypto), matching overstory's `hashIR` shape.
+ */
+export async function flowDefHash(def: Taskflow): Promise<string> {
+	return hashCanonical(canonicalJson(def));
+}