hermes-taskflow 0.2.9 → 0.2.10

package/README.md

@@ -13,7 +13,7 @@
 
 **English** · [简体中文](https://github.com/heggria/taskflow/blob/main/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](https://github.com/heggria/taskflow/blob/main/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](https://github.com/heggria/taskflow/blob/main/examples)
 
 </div>
 
@@ -133,6 +133,22 @@ Save it as `.pi/taskflows/audit-api.json`, then run:
 
 On Codex, Claude Code, OpenCode, Grok Build, and Hermes Agent, run the same saved definition by name through `taskflow_run`. For long DAGs, use `mode: "background"`, then manage the durable run with `taskflow_runs` (`list` / `status` / `wait` / `cancel`); list output reports active concurrency and can filter `running` or `terminal` runs.
 
+Large projects may organize saved definitions recursively below `.pi/taskflows/flows/`, for example `.pi/taskflows/flows/release/audit-api.json`. Legacy `.pi/taskflows/*.json` files remain discoverable and win same-scope name collisions; nested duplicates use locale-independent Unicode-scalar path order. Saving an already-discovered nested flow updates that file and its adjacent metadata in place; new flows still use the legacy top-level location. Discovery uses one shared user/project budget and fails closed if it exceeds 1,000 flows, 10,000 visited entries, 512 directories, 8 MiB of definition data, 1 MiB per definition, or 16 levels. It rejects symlinks below the trusted storage boundary through definition leaves and skips dot paths, metadata (`*.meta.json`), and compiled IR (`*.flowir.json`). The configured agent-directory boundary itself may be a symlink for compatible home-directory relocation. New-flow saves enforce the same storage-boundary policy and revalidate the physical target directory inside the write lock.
+
+A file-backed flow can opt script phases into definition-relative execution:
+
+```json
+{
+  "name": "release",
+  "scriptCwd": "flow",
+  "phases": [
+    { "id": "prepare", "type": "script", "run": ["./scripts/prepare.sh"], "final": true }
+  ]
+}
+```
+
+Here `./scripts/prepare.sh` resolves from the directory containing the saved flow or `defineFile`. The default remains `"invocation"`, and an explicit phase `cwd` still takes precedence. Inline definitions have no trusted file source and therefore fail closed if they request `scriptCwd: "flow"`. If execution inherits a cwd-bridge boundary, the resolved flow source directory must remain inside that boundary.
+
 [Follow the full quickstart →](https://heggria.github.io/taskflow/en/docs/getting-started)
 
 ## See the graph run
@@ -152,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 →](https://github.com/heggria/taskflow/blob/main/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.
@@ -355,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)
@@ -364,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.
@@ -374,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
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hermes-taskflow",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "description": "Run taskflow on Hermes Agent: a Hermes subagent runner plus an MCP server (and a config scaffold) that exposes the taskflow_* tools to Hermes users.",
   "keywords": [
     "hermes",
@@ -50,9 +50,9 @@
     "access": "public"
   },
   "dependencies": {
-    "taskflow-core": "0.2.9",
-    "taskflow-hosts": "0.2.9",
-    "taskflow-mcp-core": "0.2.9"
+    "taskflow-core": "0.2.10",
+    "taskflow-hosts": "0.2.10",
+    "taskflow-mcp-core": "0.2.10"
   },
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json && node ../../scripts/copy-readme.mjs hermes-taskflow"

package/plugin/hermes.config.snippet.yaml

@@ -14,7 +14,7 @@
 
 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:
     # Uncomment for mutating agent phases (terminal / file write).
     # Leave unset for verify/plan/script-only flows.

package/plugin/skills/taskflow/SKILL.md

@@ -487,6 +487,19 @@ output is exact.
 - A non-zero exit fails the phase (stderr captured); stdout capped at 1 MB.
   No `retry`, no `output: "json"`; **excluded from cross-run cache** (may have
   side effects). Not allowed inside LLM-generated dynamic sub-flows (RCE guard).
+- Top-level `scriptCwd: "flow"` makes script phases run from the canonical saved
+  flow/`defineFile` directory. The default is `"invocation"`; explicit phase
+  `cwd` still wins. Inline definitions cannot claim file provenance and fail
+  closed in `"flow"` mode. The source directory identity is checked again just
+  before spawn, and any inherited cwd-bridge boundary still constrains it.
+- Saved flows may live at legacy `.pi/taskflows/*.json` or recursively below
+  `.pi/taskflows/flows/**/*.json`. Legacy files win same-scope duplicate names;
+  nested candidates use deterministic Unicode-scalar path order. Discovery
+  rejects symlinks below trusted storage boundaries and fails closed above 1,000
+  flows, 10,000 entries, 512 directories, 8 MiB total definitions, 1 MiB per
+  definition, or 16 levels. A configured user agent-directory boundary may be a
+  symlink; project `.pi` remains no-follow. New-flow saves enforce the same
+  boundary policy and revalidate the target directory inside the write lock.
 
 ```jsonc
 { "id": "build", "type": "script", "run": "pnpm run build", "timeout": 120000 },

package/plugin/skills/taskflow/configuration.md

@@ -32,6 +32,7 @@ Top-level keys of the taskflow definition object.
   "description": "Audit API auth",  // shown in /tf list and the command palette
   "concurrency": 8,                 // default max concurrent subagents (default: 8)
   "agentScope": "user",             // user | project | both (default: user)
+  "scriptCwd": "invocation",        // invocation | flow (default: invocation)
   "args": { /* see §3 */ },
   // 0.2.7: optional terminal hooks (summary payload only — never transcripts)
   // "hooks": { "onComplete": [{ "type": "file", "path": ".taskflow/hooks/last.json" }] },
@@ -46,11 +47,14 @@ Top-level keys of the taskflow definition object.
 | `concurrency` | number | `8` | Default fan-out / same-layer parallelism cap. See §4. |
 | `idleTimeout` | number | host default (`300000`) | Flow-level idle watchdog in ms (≥ 1000, or `0` to disable) for all agent-running phases that don't set their own. `0` disables the watchdog but then **every** agent-running phase MUST declare a finite wall `timeout` (≥ 1000) so the flow can never hang. A per-phase `idleTimeout` overrides this. |
 | `agentScope` | `user`\|`project`\|`both` | `user` | Which agent dirs to load. See §6. |
+| `scriptCwd` | `invocation`\|`flow` | `invocation` | Default cwd policy for `script` phases. `flow` requires trusted saved-flow/`defineFile` provenance; explicit phase `cwd` wins, and inherited cwd-bridge boundaries still constrain the resolved source directory. |
 | `args` | record | `{}` | Declared invocation arguments. See §3. |
 | `hooks` | object | — | **0.2.7.** Terminal fire-and-forget notifications: `onComplete` / `onFail` / `onBlocked` arrays of `{type:"webhook"\|"file"\|"command", …}`. Payload is summary-only (`taskflow.hook.v1`) — never transcripts. Hook failure never changes run status. `https` or `http://127.0.0.1\|localhost` for webhooks; `command.run` is argv-only (no shell string). |
 | `phases` | array | — | **Required.** The phase DAG. See §2. |
 | `version` | number | `1` | Informational metadata in 0.2.x; it does not select runtime semantics or migrate a flow. |
 
+Saved definitions remain compatible at `.pi/taskflows/*.json` and may also be organized recursively below `.pi/taskflows/flows/**/*.json`. Legacy top-level files win same-scope duplicate names; nested candidates use deterministic Unicode-scalar path order. Discovery has one shared user/project budget and fails closed above 1,000 flows, 10,000 entries, 512 directories, 8 MiB total definition bytes, 1 MiB per definition, or 16 nested levels. Symlinks below trusted storage boundaries are rejected; a configured user agent-directory boundary may itself be a symlink, while project `.pi` remains no-follow. New-flow saves enforce the same boundary policy and revalidate the physical target directory inside the write lock.
+
 ---
 
 ## 2. Phase-level options
@@ -305,7 +309,7 @@ Notes:
   phases fail closed unless `PI_TASKFLOW_HERMES_UNSAFE_YOLO=1`, which enables
   `--yolo`; their default surface is local `file,terminal`, while explicit web
   aliases may add `web`. Delegation, skills, memory, browser, cron, and other
-  control-plane toolsets are denied in 0.2.9. Optional
+  control-plane toolsets are denied in 0.2.10. Optional
   `PI_TASKFLOW_HERMES_MAX_TURNS` caps child loops (default 64). Quiet mode
   does not stream token/cost accounting, so budgeted flows fail closed at the
   MCP adapter the same way other non-accounting hosts do when costs are