heggria · heggria · Aug 12, 2026 · Aug 12, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,8 @@ All notable changes to taskflow are documented here. This project follows [Keep
 
 ## [Unreleased]
 
+## [0.2.10] — 2026-08-12
+
 ### Added
 
 - **Organized saved-flow discovery.** Project and user flows may be nested recursively below the bounded `flows/` convention directory (for example `.pi/taskflows/flows/release/publish.json`) while legacy top-level saved flows remain compatible and take same-scope precedence on duplicate names.

diff --git a/README.md b/README.md
@@ -13,7 +13,7 @@
 
 **English** · [简体中文](./README.zh-CN.md)
 
-[Install](#install-on-your-host) · [Quickstart](#60-second-start) · [What's new in 0.2.9](#029-hermes-agent--verify-parity) · [0.2 compiler turn](#02-is-the-compiler-turn) · [Docs](https://heggria.github.io/taskflow/en/docs) · [Examples](./examples)
+[Install](#install-on-your-host) · [Quickstart](#60-second-start) · [What's new in 0.2.10](#0210-organized-portable-saved-flows) · [0.2 compiler turn](#02-is-the-compiler-turn) · [Docs](https://heggria.github.io/taskflow/en/docs) · [Examples](./examples)
 
 </div>
 
@@ -168,6 +168,12 @@ This is real output from a Pi run—not a mock dashboard:
 
 The layout **is** the DAG. Parallel rails expose concurrency; long edges expose dependencies; the gate explains why downstream work stopped. No separate control plane is required to understand the run.
 
+## 0.2.10: organized, portable saved flows
+
+Saved flows can now be organized below the bounded `.pi/taskflows/flows/**` convention while legacy top-level flows keep their existing precedence and behavior. A file-backed flow may opt into `scriptCwd: "flow"`, making adjacent scripts, templates, and fixtures portable as one reviewable directory bundle.
+
+Discovery, provenance, and persistence remain fail-closed: recursion has shared file/entry/directory/byte/depth budgets, symlinked descendants are excluded, source identity survives foreground/background/resume/subflow paths, and nested definition/sidecar writes revalidate the physical parent through atomic promotion. [Full 0.2.10 notes →](./CHANGELOG.md#0210--2026-08-12)
+
 ## 0.2.9: Hermes Agent + verify parity
 
 Taskflow now ships on **Hermes Agent** as `hermes-taskflow`, bringing the same MCP control plane to a sixth host. Hermes children run with an ephemeral home, explicit toolsets, cwd-confined local reads, provider-only credential material, and an explicit opt-in for mutating `--yolo` phases.
@@ -371,7 +377,7 @@ claude plugin install claude-taskflow@taskflow
 
 ```bash
 opencode mcp add taskflow -- \
-  npx -y -p opencode-taskflow@0.2.9 opencode-taskflow-mcp
+  npx -y -p opencode-taskflow@0.2.10 opencode-taskflow-mcp
 ```
 
 [OpenCode guide →](https://heggria.github.io/taskflow/en/docs/guides/opencode)
@@ -380,7 +386,7 @@ opencode mcp add taskflow -- \
 
 ```bash
 grok mcp add taskflow -- \
-  npx -y -p grok-taskflow@0.2.9 grok-taskflow-mcp
+  npx -y -p grok-taskflow@0.2.10 grok-taskflow-mcp
 ```
 
 Grok Build support is new in 0.2. Its CLI stream does not report token/cost usage, so budget-declaring flows are rejected rather than silently running without enforcement.
@@ -390,7 +396,7 @@ Grok Build support is new in 0.2. Its CLI stream does not report token/cost usag
 ### Hermes Agent
 
 ```bash
-hermes mcp add taskflow --command npx --args -y -p hermes-taskflow@0.2.9 hermes-taskflow-mcp
+hermes mcp add taskflow --command npx --args -y -p hermes-taskflow@0.2.10 hermes-taskflow-mcp
 # Prefer env in config.yaml (not CLI --env after args — can be stuffed into argv):
 #   mcp_servers.taskflow.env.PI_TASKFLOW_HERMES_UNSAFE_YOLO: "1"   # mutating only
 ```

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -13,7 +13,7 @@
 
 [English](./README.md) · **简体中文**
 
-[安装](#安装到你的宿主) · [快速开始](#60-秒开始) · [0.2.9 新能力](#029-hermes-agent--verify-对齐) · [0.2 编译器转身](#02-是编译器转身) · [文档](https://heggria.github.io/taskflow/zh-cn/docs) · [示例](./examples)
+[安装](#安装到你的宿主) · [快速开始](#60-秒开始) · [0.2.10 新能力](#0210可组织可携带的-saved-flow) · [0.2 编译器转身](#02-是编译器转身) · [文档](https://heggria.github.io/taskflow/zh-cn/docs) · [示例](./examples)
 
 </div>
 
@@ -168,6 +168,12 @@ pi install npm:pi-taskflow
 
 布局**本身就是 DAG**。并行轨道暴露并发，长边暴露依赖，gate 解释下游为什么停止。你不需要另一套控制平面才能看懂运行状态。
 
+## 0.2.10：可组织、可携带的 saved flow
+
+saved flow 现在可以按受限约定放在 `.pi/taskflows/flows/**` 下分目录管理，同时旧顶层 flow 的优先级和行为保持不变。文件来源可信的 flow 可显式设置 `scriptCwd: "flow"`，让相邻的脚本、模板和 fixtures 作为一个目录整体复制、审阅和版本控制。
+
+发现、来源和持久化继续 fail closed：递归扫描共享文件数、entry、目录数、字节和深度预算；排除边界下的 symlink；来源身份贯穿前台、后台、resume 与 subflow；嵌套 definition/sidecar 在 atomic promotion 各阶段重验物理父目录。[完整 0.2.10 说明 →](./CHANGELOG.md#0210--2026-08-12)
+
 ## 0.2.9：Hermes Agent + verify 对齐
 
 Taskflow 现在通过 `hermes-taskflow` 支持第六个宿主 **Hermes Agent**。Hermes 子代理使用临时 home、显式工具集、cwd 内只读路径边界、仅 provider 凭据，以及对 mutating `--yolo` phase 的明确 opt-in。
@@ -366,7 +372,7 @@ claude plugin install claude-taskflow@taskflow
 
 ```bash
 opencode mcp add taskflow -- \
-  npx -y -p opencode-taskflow@0.2.9 opencode-taskflow-mcp
+  npx -y -p opencode-taskflow@0.2.10 opencode-taskflow-mcp
 ```
 
 [OpenCode 指南 →](https://heggria.github.io/taskflow/zh-cn/docs/guides/opencode)
@@ -375,7 +381,7 @@ opencode mcp add taskflow -- \
 
 ```bash
 grok mcp add taskflow -- \
-  npx -y -p grok-taskflow@0.2.9 grok-taskflow-mcp
+  npx -y -p grok-taskflow@0.2.10 grok-taskflow-mcp
 ```
 
 Grok Build 支持在 0.2 首次加入。其 CLI stream 不返回 token/cost 用量，因此声明了预算的 flow 会被拒绝，而不是在无法执行预算约束时静默运行。
@@ -385,7 +391,7 @@ Grok Build 支持在 0.2 首次加入。其 CLI stream 不返回 token/cost 用
 ### Hermes Agent
 
 ```bash
-hermes mcp add taskflow --command npx --args -y -p hermes-taskflow@0.2.9 hermes-taskflow-mcp
+hermes mcp add taskflow --command npx --args -y -p hermes-taskflow@0.2.10 hermes-taskflow-mcp
 # 优先在 config.yaml 写 env（不要用 CLI --env 塞进 node argv）：
 #   mcp_servers.taskflow.env.PI_TASKFLOW_HERMES_UNSAFE_YOLO: "1"   # 仅 mutating
 ```

diff --git a/RELEASE.md b/RELEASE.md
@@ -82,8 +82,8 @@ the matching annotated tag:
 ```sh
 git switch main
 git pull --ff-only origin main
-git tag -a v0.2.9 -m "Release v0.2.9"
-git push origin v0.2.9
+git tag -a v0.2.10 -m "Release v0.2.10"
+git push origin v0.2.10
 ```
 
 `.github/workflows/publish.yml` then performs the complete release transaction:
@@ -126,16 +126,16 @@ publishing missing packages manually.
 
 ## Upgrade and rollback
 
-- Upgrade all host package pins as one transaction to `0.2.9`, restart/reload the
-  host's MCP/plugin registration, and verify `taskflow_version` reports `0.2.9`.
+- Upgrade all host package pins as one transaction to `0.2.10`, restart/reload the
+  host's MCP/plugin registration, and verify `taskflow_version` reports `0.2.10`.
 - This patch does not introduce a run-state migration. Keep `.pi/taskflows/` and
   existing run history in place when upgrading or rolling back.
-- Pi, Codex, Claude Code, OpenCode, and Grok users can roll back by pinning their
-  delivery package to `0.2.8` and restarting the host. Keep all taskflow package
-  versions aligned; do not mix a `0.2.9` adapter with `0.2.8` shared packages.
-- Hermes support begins in `0.2.9`; there is no `hermes-taskflow@0.2.8`. To roll
-  Hermes back, disable/remove its Taskflow MCP entry and restart Hermes rather
-  than attempting to install a nonexistent older package.
+- All six hosts can roll back by pinning their delivery package to `0.2.9` and
+  restarting/reloading the host. Keep all taskflow package versions aligned; do
+  not mix a `0.2.10` adapter with `0.2.9` shared packages.
+- Before rolling back, move any definitions from `.pi/taskflows/flows/**` back to
+  the legacy top-level taskflows directory and remove `scriptCwd: "flow"`; 0.2.9
+  does not discover the nested convention or understand that field.
 
 ## Install (end users)
 
@@ -155,8 +155,8 @@ claude plugin install claude-taskflow@taskflow
 opencode mcp add taskflow -- npx -y -p opencode-taskflow opencode-taskflow-mcp
 
 # Grok Build (published MCP package)
-grok mcp add taskflow -- npx -y -p grok-taskflow@0.2.9 grok-taskflow-mcp
+grok mcp add taskflow -- npx -y -p grok-taskflow@0.2.10 grok-taskflow-mcp
 # or: grok mcp add taskflow -- npx -y -p grok-taskflow grok-taskflow-mcp
 
-hermes mcp add taskflow --command npx --args -y -p hermes-taskflow@0.2.9 hermes-taskflow-mcp
+hermes mcp add taskflow --command npx --args -y -p hermes-taskflow@0.2.10 hermes-taskflow-mcp
 ```
diff --git a/SECURITY.md b/SECURITY.md
@@ -27,7 +27,7 @@ The runtime has intentional hardening: `realpath`-based path containment, runId
 
 | Version | Support |
 |---------|---------|
-| Latest npm release (`v0.2.9` for this release) | ✅ Active |
+| Latest npm release (`v0.2.10` for this release) | ✅ Active |
 | Earlier versions | ❌ Unsupported — upgrade to the latest npm release |
 
 ## Disclosure

diff --git a/docs/claude-mcp.md b/docs/claude-mcp.md
@@ -35,7 +35,7 @@ Verify:
 
 ```sh
 claude plugin list   # → claude-taskflow@taskflow  installed, enabled
-claude mcp list      # → taskflow … (npx -y -p claude-taskflow@0.2.9 claude-taskflow-mcp)
+claude mcp list      # → taskflow … (npx -y -p claude-taskflow@0.2.10 claude-taskflow-mcp)
 ```
 
 The bundled skill tells Claude Code *when* to reach for the tools (multi-phase

diff --git a/docs/codex-mcp.md b/docs/codex-mcp.md
@@ -31,7 +31,7 @@ globally, and the plugin version binds the exact code that runs. Verify:
 
 ```sh
 codex plugin list   # → taskflow@taskflow  installed, enabled
-codex mcp list      # → taskflow … enabled  (npx -y -p codex-taskflow@0.2.9 codex-taskflow-mcp)
+codex mcp list      # → taskflow … enabled  (npx -y -p codex-taskflow@0.2.10 codex-taskflow-mcp)
 ```
 
 The bundled skill tells Codex *when* to reach for the tools (multi-phase or
@@ -70,7 +70,7 @@ To stop large flows from being cut off, the plugin's `.mcp.json` ships a
   "mcpServers": {
     "taskflow": {
       "command": "npx",
-      "args": ["-y", "-p", "codex-taskflow@0.2.9", "codex-taskflow-mcp"],
+      "args": ["-y", "-p", "codex-taskflow@0.2.10", "codex-taskflow-mcp"],
       "tool_timeout_sec": 1800
     }
   }

diff --git a/docs/grok-mcp.md b/docs/grok-mcp.md
@@ -27,7 +27,7 @@ Official Grok docs used for this integration:
 ## Install (recommended): register the published MCP server
 
 ```sh
-grok mcp add taskflow -- npx -y -p grok-taskflow@0.2.9 grok-taskflow-mcp
+grok mcp add taskflow -- npx -y -p grok-taskflow@0.2.10 grok-taskflow-mcp
 ```
 
 A public Grok plugin marketplace/source is not published yet. Do not substitute
@@ -179,7 +179,7 @@ grok mcp add taskflow -- grok-taskflow-mcp
 Or with npx (no global install):
 
 ```sh
-grok mcp add taskflow -- npx -y -p grok-taskflow@0.2.9 grok-taskflow-mcp
+grok mcp add taskflow -- npx -y -p grok-taskflow@0.2.10 grok-taskflow-mcp
 ```
 
 Verify:

diff --git a/docs/hermes-mcp.md b/docs/hermes-mcp.md
@@ -15,7 +15,7 @@ Or paste into `~/.hermes/config.yaml` (see `packages/hermes-taskflow/plugin/herm
 mcp_servers:
   taskflow:
     command: "npx"
-    args: ["-y", "-p", "hermes-taskflow@0.2.9", "hermes-taskflow-mcp"]
+    args: ["-y", "-p", "hermes-taskflow@0.2.10", "hermes-taskflow-mcp"]
     env:
       # PI_TASKFLOW_HERMES_UNSAFE_YOLO: "1"  # required for mutating agent phases
     timeout: 600

diff --git a/docs/i18n/README.ar.md b/docs/i18n/README.ar.md
@@ -2,7 +2,7 @@
 
 > ⚠️ **هذه الترجمة قديمة.** يُرجى مراجعة [README بالإنجليزية](../../README.md) للحصول على أحدث المعلومات.
 
-taskflow رسم بياني تصريحي وقابل للتحقق للمهام على Pi وCodex وClaude Code وOpenCode وGrok Build وHermes Agent. خط 0.2.9 يتطلب Node.js ≥ 22.19.0 ويضم 12 نوعًا من المراحل وأكثر من 1500 اختبار. طبقة MCP لا تعتمد على MCP SDK؛ يستخدم core ‏`typebox` كـ peer ويعتمد DSL على TypeScript.
+taskflow رسم بياني تصريحي وقابل للتحقق للمهام على Pi وCodex وClaude Code وOpenCode وGrok Build وHermes Agent. خط 0.2.10 يتطلب Node.js ≥ 22.19.0 ويضم 12 نوعًا من المراحل وأكثر من 1500 اختبار. طبقة MCP لا تعتمد على MCP SDK؛ يستخدم core ‏`typebox` كـ peer ويعتمد DSL على TypeScript.
 
 > **لماذا "taskflow" وليس "workflow"؟** الـ *workflow* (بنمط code-mode) هو برنامج أمري *يتدفق*، ورسمه البياني مخبأ داخل تدفق التحكم. أما الـ *taskflow* فينقل الخطة إلى رسم بياني تصريحي من عقد مهام منفصلة — يمكن التحقق منه ساكنًا وعرضه واستئنافه وحفظه كأمر. نحن نستبدل القدرة التعبيرية بالقابلية للتحقق، عن قصد.
 
@@ -22,7 +22,7 @@ claude plugin install claude-taskflow@taskflow
 opencode mcp add taskflow -- npx -y -p opencode-taskflow opencode-taskflow-mcp
 
 # Grok Build (from monorepo checkout pre-publish, or published source)
-grok mcp add taskflow -- npx -y -p grok-taskflow@0.2.9 grok-taskflow-mcp
+grok mcp add taskflow -- npx -y -p grok-taskflow@0.2.10 grok-taskflow-mcp
 # or: grok mcp add taskflow -- npx -y -p grok-taskflow grok-taskflow-mcp
 ```
 

diff --git a/docs/i18n/README.bn.md b/docs/i18n/README.bn.md
@@ -2,7 +2,7 @@
 
 > ⚠️ **এই অনুবাদটি পুরোনো।** অনুগ্রহ করে সর্বশেষ তথ্যের জন্য [ইংরেজি README](../../README.md) দেখুন।
 
-taskflow Pi, Codex, Claude Code, OpenCode, Grok Build ও Hermes Agent-এর জন্য একটি ডিক্লারেটিভ, যাচাইযোগ্য টাস্ক গ্রাফ। 0.2.9 লাইনে Node.js ≥ 22.19.0, 12টি phase kind এবং 1500+ পরীক্ষা রয়েছে। MCP layer-এর MCP SDK dependency নেই; core-এর peer `typebox`, আর DSL TypeScript-এর উপর নির্ভরশীল।
+taskflow Pi, Codex, Claude Code, OpenCode, Grok Build ও Hermes Agent-এর জন্য একটি ডিক্লারেটিভ, যাচাইযোগ্য টাস্ক গ্রাফ। 0.2.10 লাইনে Node.js ≥ 22.19.0, 12টি phase kind এবং 1500+ পরীক্ষা রয়েছে। MCP layer-এর MCP SDK dependency নেই; core-এর peer `typebox`, আর DSL TypeScript-এর উপর নির্ভরশীল।
 
 > **কেন "taskflow", "workflow" নয় কেন?** একটি *workflow* (code-mode) হল একটি ইম্পারেটিভ স্ক্রিপ্ট যা *প্রবাহিত হয়*, যার গ্রাফ কন্ট্রোল ফ্লোর মধ্যে লুকানো। একটি *taskflow* পরিকল্পনাকে পৃথক টাস্ক নোডের একটি ডিক্লারেটিভ গ্রাফে সরিয়ে নেয় — যা স্থিরভাবে যাচাই, দৃশ্যমান, পুনরারম্ভ এবং একটি কমান্ড হিসেবে সংরক্ষণ করা যায়। আমরা ইচ্ছাকৃতভাবে এক্সপ্রেসিভনেসকে যাচাইযোগ্যতার বিনিময়ে দিই।
 
@@ -22,7 +22,7 @@ claude plugin install claude-taskflow@taskflow
 opencode mcp add taskflow -- npx -y -p opencode-taskflow opencode-taskflow-mcp
 
 # Grok Build (from monorepo checkout pre-publish, or published source)
-grok mcp add taskflow -- npx -y -p grok-taskflow@0.2.9 grok-taskflow-mcp
+grok mcp add taskflow -- npx -y -p grok-taskflow@0.2.10 grok-taskflow-mcp
 # or: grok mcp add taskflow -- npx -y -p grok-taskflow grok-taskflow-mcp
 ```
 

diff --git a/docs/i18n/README.es.md b/docs/i18n/README.es.md
@@ -2,7 +2,7 @@
 
 > ⚠️ **Esta traducción está desactualizada.** Consulta el [README en inglés](../../README.md) para obtener la información más reciente.
 
-taskflow es un *grafo de tareas* declarativo y verificable para agentes de codificación — funciona en Pi, Codex, Claude Code, OpenCode, Grok Build y Hermes Agent. Línea 0.2.9: Node.js ≥ 22.19.0, 12 tipos de fase y más de 1500 pruebas. La capa MCP no depende de un SDK MCP; core usa `typebox` como peer y el DSL depende de TypeScript.
+taskflow es un *grafo de tareas* declarativo y verificable para agentes de codificación — funciona en Pi, Codex, Claude Code, OpenCode, Grok Build y Hermes Agent. Línea 0.2.10: Node.js ≥ 22.19.0, 12 tipos de fase y más de 1500 pruebas. La capa MCP no depende de un SDK MCP; core usa `typebox` como peer y el DSL depende de TypeScript.
 
 > **¿Por qué "taskflow" y no "workflow"?** Un *workflow* (estilo code-mode) es un script imperativo que *fluye*, con el grafo oculto en el control de flujo. Un *taskflow* mueve el plan a un grafo declarativo de nodos de tarea discretos — que se puede verificar estáticamente, visualizar, reanudar y guardar como un comando. Cambiamos expresividad por verificabilidad, a propósito.
 
@@ -22,7 +22,7 @@ claude plugin install claude-taskflow@taskflow
 opencode mcp add taskflow -- npx -y -p opencode-taskflow opencode-taskflow-mcp
 
 # Grok Build (from monorepo checkout pre-publish, or published source)
-grok mcp add taskflow -- npx -y -p grok-taskflow@0.2.9 grok-taskflow-mcp
+grok mcp add taskflow -- npx -y -p grok-taskflow@0.2.10 grok-taskflow-mcp
 # or: grok mcp add taskflow -- npx -y -p grok-taskflow grok-taskflow-mcp
 ```
 

diff --git a/docs/i18n/README.hi.md b/docs/i18n/README.hi.md
@@ -2,7 +2,7 @@
 
 > ⚠️ **यह अनुवाद पुराना है।** कृपया नवीनतम जानकारी के लिए [अंग्रेज़ी README](../../README.md) देखें।
 
-taskflow Pi, Codex, Claude Code, OpenCode, Grok Build और Hermes Agent के लिए एक घोषणात्मक, सत्यापन-योग्य टास्क ग्राफ है। 0.2.9 लाइन में Node.js ≥ 22.19.0, 12 phase kinds और 1500+ परीक्षण हैं। MCP layer किसी MCP SDK पर निर्भर नहीं है; core का peer `typebox` है और DSL TypeScript पर निर्भर है।
+taskflow Pi, Codex, Claude Code, OpenCode, Grok Build और Hermes Agent के लिए एक घोषणात्मक, सत्यापन-योग्य टास्क ग्राफ है। 0.2.10 लाइन में Node.js ≥ 22.19.0, 12 phase kinds और 1500+ परीक्षण हैं। MCP layer किसी MCP SDK पर निर्भर नहीं है; core का peer `typebox` है और DSL TypeScript पर निर्भर है।
 
 > **"taskflow" क्यों, "workflow" क्यों नहीं?** एक *workflow* (code-mode) एक आज्ञात्मक स्क्रिप्ट है जो *बहता* है, जिसका ग्राफ कंट्रोल फ़्लो में छिपा होता है। एक *taskflow* योजना को अलग-अलग टास्क नोड्स के एक घोषणात्मक ग्राफ में ले जाता है — जिसे स्थिर रूप से सत्यापित, दृश्य, पुनः शुरू और एक कमांड के रूप में सहेजा जा सकता है। हम जान-बूझकर अभिव्यक्ति को सत्यापन-योग्यता से बदलते हैं।
 
@@ -22,7 +22,7 @@ claude plugin install claude-taskflow@taskflow
 opencode mcp add taskflow -- npx -y -p opencode-taskflow opencode-taskflow-mcp
 
 # Grok Build (from monorepo checkout pre-publish, or published source)
-grok mcp add taskflow -- npx -y -p grok-taskflow@0.2.9 grok-taskflow-mcp
+grok mcp add taskflow -- npx -y -p grok-taskflow@0.2.10 grok-taskflow-mcp
 # or: grok mcp add taskflow -- npx -y -p grok-taskflow grok-taskflow-mcp
 ```