pi-taskflow 0.0.23 → 0.0.24

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/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/index.ts

@@ -83,8 +83,8 @@ const ShorthandStep = Type.Object(
 );
 
 const TaskflowParams = Type.Object({
-	action: StringEnum(["run", "save", "resume", "list", "agents", "init", "verify", "cache-clear"] as const, {
-		description: "What to do: run a flow, save a definition, resume a paused run, list saved flows, list available agents, init model role configuration, or clear the cross-run memoization cache",
+	action: StringEnum(["run", "save", "resume", "list", "agents", "init", "verify", "compile", "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, 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)" })),
@@ -402,6 +402,7 @@ export default function (pi: ExtensionAPI) {
 			"Every delegation is tracked (runId), resumable across sessions, and saveable as /tf:<name> via action=save.",
 			"Use action=agents to list the 18 built-in agents (executor, scout, planner, analyst, critic, reviewer, risk-reviewer, security-reviewer, plan-arbiter, final-arbiter, test-engineer, doc-writer, executor-code, executor-fast, executor-ui, recover, verifier, visual-explorer). Do NOT invent agent names.",
 			"Phase types: agent, parallel (static branches), map (dynamic fan-out over array), gate (VERDICT: PASS/BLOCK), reduce (aggregate from N), approval (human-in-the-loop), flow (run saved sub-flow), loop (iterate until condition/convergence/cap), tournament (N variants, judge picks best/aggregate).",
+			"Use action=compile to generate a Mermaid diagram + verification report from a saved or inline flow — 0 tokens.",
 			"Interpolation: {args.X}, {steps.ID.output}, {steps.ID.json}, {item} (map), {previous.output}.",
 		].join(" "),
 		parameters: TaskflowParams,
@@ -570,6 +571,46 @@ export default function (pi: ExtensionAPI) {
 				return { content: [{ type: "text", text: lines.join("\n") }], details: { action } satisfies TaskflowDetails };
 			}
 
+			if (action === "compile") {
+				const { compileTaskflow } = await import("./compile.ts");
+				// Resolve definition: inline define (object or JSON/fenced string) then saved name.
+				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.");
+				}
+				// Schema validation first so a malformed graph gives a clean error
+				// rather than a half-rendered diagram.
+				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 compiled = compileTaskflow(def);
+				return {
+					content: [{ type: "text", text: compiled.markdown }],
+					details: { action } satisfies TaskflowDetails,
+				};
+			}
+
 			if (action === "cache-clear") {
 				const removed = new CacheStore(ctx.cwd).clear();
 				return {
@@ -779,9 +820,9 @@ export default function (pi: ExtensionAPI) {
 
 	// ---- The /tf user command ----
 	pi.registerCommand("tf", {
-		description: "Taskflow: list | run <name> | show <name> | runs | init",
+		description: "Taskflow: list | run <name> | show <name> | compile <name> | runs | init",
 		getArgumentCompletions: (prefix) => {
-			const subs = ["list", "run", "show", "runs", "resume", "init", "save", "verify"];
+			const subs = ["list", "run", "show", "runs", "resume", "init", "save", "verify", "compile"];
 			const items = subs.map((s) => ({ value: s, label: s }));
 			const filtered = items.filter((i) => i.value.startsWith(prefix));
 			return filtered.length > 0 ? filtered : null;
@@ -810,6 +851,33 @@ export default function (pi: ExtensionAPI) {
 				return;
 			}
 
+			if (sub === "compile") {
+				if (!arg) {
+					ctx.ui.notify("Usage: /tf compile <name> [lr|td]", "warning");
+					return;
+				}
+				// `arg` may carry an optional direction suffix: "<name> lr" / "<name> td".
+				const parts = arg.trim().split(/\s+/);
+				const flowName = parts[0];
+				const direction = parts[1]?.toLowerCase() === "lr" ? "LR" : "TD";
+				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 diagram (mirrors the tool action).
+				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 { compileTaskflow } = await import("./compile.ts");
+				const compiled = compileTaskflow(flow.def, { direction });
+				ctx.ui.notify(compiled.markdown, compiled.verification.ok ? "info" : "warning");
+				return;
+			}
+
 			if (sub === "runs") {
 				const runs = listRuns(ctx.cwd, 50);
 				if (runs.length === 0) {

package/package.json

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

@@ -558,7 +558,7 @@ Quick reference:
 - `action: "run"` — run an inline `define` (a one-off DAG) **or** a saved `name` (with optional `args`). Use `define` for an ad-hoc flow; use `name` to invoke something previously saved. Add `detach: true` to run in the background (returns immediately with the runId; poll the store for status).
 - `action: "save"` — persist `define` (scope `project` — default, committed/shared — or `user`); it becomes `/tf:<name>`. On a name collision, project overrides user.
 - `action: "resume"` — continue a paused/failed run by `runId`.
-- `action: "list"` — list saved flows. `action: "verify"` — static-check a `define` (zero tokens). `action: "agents"` — list available agents.
+- `action: "list"` — list saved flows. `action: "verify"` — static-check a `define` (zero tokens). `action: "compile"` — render a saved or inline flow as a Mermaid diagram + verification report (zero tokens, no LLM). `action: "agents"` — list available agents.
 
 ## Background (detached) runs
 
@@ -580,5 +580,5 @@ A run moves through: **running →** `completed` (a `final` phase produced outpu
 
 ## User commands
 
-- `/tf list` · `/tf run <name> [args]` · `/tf show <name>` · `/tf runs` · `/tf resume <runId>`
+- `/tf list` · `/tf run <name> [args]` · `/tf show <name>` · `/tf compile <name> [lr|td]` · `/tf runs` · `/tf resume <runId>`
 - `/tf:<name> [args]` — shortcut for each saved flow