hermes-taskflow 0.3.0-beta.1.2 → 1.0.0

package/README.md

@@ -11,23 +11,23 @@
 
 **English** · [简体中文](https://github.com/heggria/taskflow/blob/main/README.zh-CN.md)
 
-[0.3 overview](#taskflow-03-trusted-effects) · [Quickstart](#quickstart) · [Docs](https://heggria.github.io/taskflow/en/docs) · [Examples](https://github.com/heggria/taskflow/blob/main/examples) · [Changelog](https://github.com/heggria/taskflow/blob/main/CHANGELOG.md)
+[1.0 overview](#taskflow-10-declarative-coding-agent-workflows) · [Quickstart](#quickstart) · [Docs](https://heggria.github.io/taskflow/en/docs) · [Examples](https://github.com/heggria/taskflow/blob/main/examples) · [Changelog](https://github.com/heggria/taskflow/blob/main/CHANGELOG.md)
 
 </div>
 
 ---
 
-# taskflow 0.3: make agent side effects inspectable
+# taskflow 1.0: declarative coding-agent workflows
 
-**taskflow is a declarative runtime for coding-agent workflows.** It turns a graph into a verifiable execution contract, runs phases in isolation, and keeps intermediate work out of the host conversation. In the 0.3 candidate, the contract also describes the effects a phase is allowed to propose.
+**taskflow is a declarative runtime for coding-agent workflows.** It turns a graph into a verifiable execution contract, runs phases in isolation, and keeps intermediate work out of the host conversation. In Taskflow 1.0, the contract also describes the effects a phase is allowed to propose.
 
-> **Status: 0.3.0-beta.1.2 Trusted Effects beta — beta channel, not GA.** This release candidate is prepared for npm's `beta` channel; the beta ships the Trusted Effects MVP described below. The 0.3-C Control Plane remains a follow-on candidate track; it is not a shipped beta surface.
+> **Taskflow 1.0.0** includes the DAG runtime, trusted filesystem effects and complete Control Plane (CLI/MCP/WebUI). [GitHub Releases](https://github.com/heggria/taskflow/releases) and npm establish publication; see the [acceptance scoreboard](https://github.com/heggria/taskflow/blob/main/docs/internal/1.0.0-ga-scoreboard.md) for verified scope and limits.
 
-## The 0.3 idea
+## The declared-effect contract
 
 An agent can propose content. It should not become the mutation authority merely because it can run a command.
 
-For admitted, declared filesystem-write targets, taskflow 0.3 makes the path explicit and routes the final mutation through the resources transaction:
+For admitted, declared filesystem-write targets, taskflow 1.0 makes the path explicit and routes the final mutation through the resources transaction:
 
 ```text
 flow / .tf.ts
@@ -47,39 +47,40 @@ flow / .tf.ts
 
 This is **not** an OS sandbox. Resolve-only hosts cannot prevent every write to an undeclared path. Secret and service references are typed and fail closed in this cut; they do not imply a vault or network backend.
 
-## What is in the candidate
+## The 1.0 target and current implementation
 
-| Layer | What it does | Candidate status |
+| Layer | What it does | Support boundary |
 |---|---|---|
-| **Taskflow runtime** | Declarative DAGs, 12 phase types, budgets, retries, approvals, isolation, resume, replay, trace, and recompute | Existing 0.2 foundation |
-| **Trusted Effects** | Closed `EffectIR`, `PathRef` / `SecretRef` / `ServiceRef`, confidentiality/integrity labels, effect validation, overlap checks, and ledger-backed `why-*` explainers | 0.3 MVP implementation |
-| **Resource transaction** | Snapshot → lease → durable intent/permit → stage → commit, or restore and reject | 0.3 MVP implementation |
+| **Taskflow runtime** | Declarative DAGs, 12 phase types, budgets, retries, approvals, isolation, resume, replay, trace, and recompute | Stable runtime contract |
+| **Trusted Effects** | Closed `EffectIR`, `PathRef` / `SecretRef` / `ServiceRef`, confidentiality/integrity labels, effect validation, overlap checks, and ledger-backed `why-*` explainers | Declared-target contract |
+| **Resource transaction** | Snapshot → lease → durable intent/permit → stage → commit, or restore and reject | Declared-target contract |
 | **Host adapters** | Pi, Codex, Claude Code, OpenCode, Grok Build, and Hermes Agent use the same flow contract | Existing host surface; support remains host-specific |
-| **Control Plane** | ControlHost scaffold, proposed wire contracts, singleton/fencing, and hello negotiation; future stores, approvals, receipts, and coordination | Active 0.3-C track; not shipped and not the 0.3 MVP GA claim |
-| **WebUI** | Runs, approvals, receipts, and evidence browsing | Planned in the 0.3-C sequence; not shipped in this candidate |
+| **Control Plane** | Authenticated multi-project admission, global concurrency, durable replay, approvals/CAS, Receipts and operator CLI/MCP | Bundled in public `taskflow-mcp-core`; Unix UDS, Windows pipes non-GA |
+| **WebUI** | Runs, approval edits, Receipts and evidence browsing | Local token login, live authorization and project isolation |
 
-The normative MVP definition is [`docs/internal/0.3.0-trusted-effects-mvp.md`](https://github.com/heggria/taskflow/blob/main/docs/internal/0.3.0-trusted-effects-mvp.md). The 0.3-C Control Plane plan is [`docs/internal/0.3-c-control-plane-plan.md`](https://github.com/heggria/taskflow/blob/main/docs/internal/0.3-c-control-plane-plan.md).
+The [1.0 release plan](https://github.com/heggria/taskflow/blob/main/docs/internal/1.0.0-release-plan.md) defines the stable scope and acceptance gates. The filesystem-transaction details are in [`docs/internal/0.3.0-trusted-effects-mvp.md`](https://github.com/heggria/taskflow/blob/main/docs/internal/0.3.0-trusted-effects-mvp.md). The 0.3-C Control Plane plan is [`docs/internal/0.3-c-control-plane-plan.md`](https://github.com/heggria/taskflow/blob/main/docs/internal/0.3-c-control-plane-plan.md).
 
 ## Quickstart
 
-The 0.3 beta can be installed from npm, or exercised from a clean source checkout. Use Node.js **≥ 22.19.0**:
+Use Node.js **≥ 22.19.0**. To run from the 1.0 source checkout:
 
 ```bash
 git clone https://github.com/heggria/taskflow.git
 cd taskflow
-git checkout rc/0.3.0-trusted-effects
+git checkout v1.0.0
 pnpm install
 pnpm run typecheck
 pnpm test
 ```
 
-The beta commands below become usable after the tag workflow completes; until then they are release-target examples, not proof of registry availability.
+Install the matching 1.0.0 package set after confirming the release is available:
+
 ```bash
-npm install --global pi-taskflow@beta
-npm install --global codex-taskflow@beta
+npm install --global pi-taskflow@1.0.0
+npm install --global codex-taskflow@1.0.0
 ```
 
-The host-specific plugin and MCP commands remain in the [host guides](https://heggria.github.io/taskflow/en/docs/guides/). Stable 0.2.x installs remain available through exact stable pins.
+The host-specific plugin and MCP commands remain in the [host guides](https://heggria.github.io/taskflow/en/docs/guides/).
 
 Run the no-LLM Trusted Effects vertical-slice fixture:
 
@@ -88,7 +89,15 @@ pnpm exec node --conditions=development --experimental-strip-types --test \
   packages/taskflow-core/test/effects-e2e-fixture.test.ts
 ```
 
-This exercises the checked-in `examples/trusted-effects-write.json` path without a live LLM. For an interactive run, use the host guide for the adapter you already run. The stable 0.2 installation path remains documented separately in the [host guides](https://heggria.github.io/taskflow/en/docs/guides/).
+This exercises the checked-in `examples/trusted-effects-write.json` path without a live LLM. For an interactive run, use the host guide for the adapter you already run. The [release guide](https://github.com/heggria/taskflow/blob/main/RELEASE.md) covers packed-consumer validation and release gates.
+
+### Local Control Console
+
+In Pi, run `/tf web` to start the bundled local Control Console and open the default browser. If browser opening fails, the command shows a manual loopback URL. Use the one-use token in the reported private (0600) handoff file to log in; tokens are never included in the URL or command notifications.
+
+The console shows Control Plane runs, approvals, Receipts and existing evidence. Legacy Pi run transcripts are outside this view. Repeating the command in the same project reuses its service; changing projects or leaving the Pi session stops only the console process started by that session. Unix local transport is required. If another host already owns the Control home, stop that owner explicitly before launching this console.
+
+See [Pi compatibility](https://github.com/heggria/taskflow/blob/main/docs/pi-compatibility.md) for the tested SDK matrix and the distinction between real-process fixtures and live-provider acceptance.
 
 ## Declare an effect
 
@@ -191,7 +200,7 @@ Host support is not a blanket security guarantee. Read the [host support baselin
 - Writes to undeclared paths remain host-policy dependent under resolve-only execution.
 - `SecretRef` and `ServiceRef` are typed handles only; no vault or live service adapter ships in this cut.
 - There is no FileBroker or full OS sandbox claim in 0.3 MVP.
-- Control Plane stores, approvals, receipts, and WebUI are future 0.3-C stages, not proof that 0.3 is released or GA.
+- Control Plane admission, authorized replay, durable approvals, Receipts, global coordination and WebUI are implemented. Public `taskflow-mcp-core` provides the control binaries; operator actions require an explicitly provisioned separate credential. Request audit fields never grant authority.
 
 ## Development
 
@@ -210,13 +219,13 @@ The monorepo contains the host-neutral `taskflow-core`, Trusted Effects and reso
 
 | Start here | Use it for |
 |---|---|
-| [0.3 overview](https://heggria.github.io/taskflow/en/docs) | Candidate scope, status, and the honest security boundary |
+| [1.0 overview](https://heggria.github.io/taskflow/en/docs) | 1.0 scope, support, and the security boundary |
 | [Getting Started](https://heggria.github.io/taskflow/en/docs/getting-started) | First flow and host setup |
 | [Core Concepts](https://heggria.github.io/taskflow/en/docs/concepts/) | DAGs, isolation, verification, resume, and evidence |
 | [Compiler & Runtime](https://heggria.github.io/taskflow/en/docs/compiler-runtime/) | JSON, TypeScript DSL, FlowIR, replay, and recompute |
 | [Host Guides](https://heggria.github.io/taskflow/en/docs/guides/) | Pi, Codex, Claude Code, OpenCode, Grok, and Hermes |
 | [Examples](https://github.com/heggria/taskflow/blob/main/examples) | Runnable flow definitions, including Trusted Effects |
-| [Changelog](https://github.com/heggria/taskflow/blob/main/CHANGELOG.md) | Release history and candidate notes |
+| [Changelog](https://github.com/heggria/taskflow/blob/main/CHANGELOG.md) | Release history and version notes |
 
 ## License
 
@@ -226,6 +235,6 @@ The monorepo contains the host-neutral `taskflow-core`, Trusted Effects and reso
 
 **Declare the effect. Verify the path. Commit through one authority.**
 
-[Read the docs](https://heggria.github.io/taskflow/en/docs) · [Try the candidate](#quickstart) · [View releases](https://github.com/heggria/taskflow/releases)
+[Read the docs](https://heggria.github.io/taskflow/en/docs) · [Install Taskflow 1.0](#quickstart) · [View releases](https://github.com/heggria/taskflow/releases)
 
 </div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hermes-taskflow",
-  "version": "0.3.0-beta.1.2",
+  "version": "1.0.0",
   "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.3.0-beta.1.2",
-    "taskflow-hosts": "0.3.0-beta.1.2",
-    "taskflow-mcp-core": "0.3.0-beta.1.2"
+    "taskflow-core": "1.0.0",
+    "taskflow-hosts": "1.0.0",
+    "taskflow-mcp-core": "1.0.0"
   },
   "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.3.0-beta.1.2", "hermes-taskflow-mcp"]
+  args: ["-y", "-p", "hermes-taskflow@1.0.0", "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

@@ -147,9 +147,9 @@ For a non-trivial flow you'll iterate on, **write the definition to a file**
 (typically in the OS tmp dir) and point every call at it with `defineFile`:
 
 ```jsonc
-// 1. write /tmp/audit.json with the `write` tool (a full {name, phases:[…]} object)
+// 1. write /tmp/audit.json with the `write` tool (a full {name, phases:[...]} object)
 // 2. verify, iterate, run — all reference the SAME file by path:
-{ "name": "taskflow_plan",   "arguments": { "defineFile": "/tmp/audit.json", "args": { … } } }  // zero tokens: bind + plan + budget bound
+{ "name": "taskflow_plan",   "arguments": { "defineFile": "/tmp/audit.json", "args": { ... } } }  // zero tokens: bind + plan + budget bound
 { "name": "taskflow_verify", "arguments": { "defineFile": "/tmp/audit.json" } }  // zero tokens
 { "name": "taskflow_compile", "arguments": { "defineFile": "/tmp/audit.json" } }  // diagram
 { "name": "taskflow_lint",   "arguments": { "defineFile": "/tmp/audit.json" } }  // script-lint + custom verifiers
@@ -572,7 +572,7 @@ Each effect:
 **Phase output is the payload.** With one declared `fs.write`, the phase's
 output becomes the staged file content (see the example: `process.stdout.write`
 = the report). With several `fs.write` effects, the phase must emit JSON
-mapping each effect id to its content (`{ "report": "…", "backup": "…" }`).
+mapping each effect id to its content (`{ "report": "...", "backup": "..." }`).
 Commit promotes each file atomically; a later failure restores every admitted
 file to its durable pre-state, and a direct write by the agent/script to a
 **declared final path** is detected and restored — only the resource
@@ -624,8 +624,8 @@ more than comparing every approach.
 {
   "id": "quick", "type": "race",
   "branches": [
-    { "task": "Answer with a short heuristic…", "agent": "executor" },
-    { "task": "Answer with a thorough search…", "agent": "researcher" }
+    { "task": "Answer with a short heuristic...", "agent": "executor" },
+    { "task": "Answer with a thorough search...", "agent": "researcher" }
   ],
   "final": true
 }

package/plugin/skills/taskflow/configuration.md

@@ -49,7 +49,7 @@ Top-level keys of the taskflow definition object.
 | `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. `taskFile` is the same class of load-time trusted source (see §2). |
 | `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). |
+| `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. |
 
@@ -66,11 +66,11 @@ Keys of each object in `phases[]`. Some only apply to specific `type`s.
   "id": "audit",            // required, unique — referenced via {steps.audit.output}
   "type": "map",            // agent | parallel | map | gate | reduce | approval | flow | loop | tournament | script | race | expand (default: agent)
   "agent": "analyst",       // agent name to run this phase
-  "task": "Audit {item.route}…",
+  "task": "Audit {item.route}...",
   "dependsOn": ["discover"],// DAG edges
   "over": "{steps.discover.json}",  // [map] array to fan out over
   "as": "item",             // [map] loop var name (default: item)
-  "branches": [ /* … */ ],  // [parallel|race] static task list
+  "branches": [ /* ... */ ],  // [parallel|race] static task list
   "from": ["audit"],        // [reduce] phase ids to aggregate
   "def": "{steps.plan.json}", // [expand|flow] inline fragment / dynamic sub-flow
   "expandMode": "nested",   // [expand] nested | graft
@@ -86,7 +86,7 @@ Keys of each object in `phases[]`. Some only apply to specific `type`s.
 
 | Key | Applies to | Default | Notes |
 |-----|-----------|---------|-------|
-| `id` | all | — | **Required, unique.** Used in `{steps.<id>…}`. |
+| `id` | all | — | **Required, unique.** Used in `{steps.<id>...}`. |
 | `type` | all | `agent` | One of the **12** phase types (agent, parallel, map, gate, reduce, approval, flow, loop, tournament, script, **race**, **expand**). |
 | `agent` | all | first available | Agent name; resolved from the scoped pool. |
 | `task` | agent, gate, map, reduce | — | Prompt; supports interpolation. Required for these types unless `taskFile` is set. |
@@ -268,8 +268,8 @@ There are **two independent concurrency limits**:
   "concurrency": 6,                 // ≤6 sibling phases run at once
   "phases": [
     { "id": "scan", "type": "map", "over": "{steps.list.json}",
-      "concurrency": 3,             // …but this map only fans out 3 at a time
-      "task": "…", "dependsOn": ["list"] }
+      "concurrency": 3,             // ...but this map only fans out 3 at a time
+      "task": "...", "dependsOn": ["list"] }
   ]
 }
 ```
@@ -435,7 +435,7 @@ fingerprint folds **“did the world change?”** signals into that key, so an
 external change becomes a cache **miss** even when the task text is identical.
 Each entry is one of:
 
-| Entry | Becomes a miss when… | Resolves to |
+| Entry | Becomes a miss when... | Resolves to |
 |-------|----------------------|-------------|
 | `git:HEAD` / `git:<ref>` | the commit moves | the resolved SHA (30s timeout → `<timeout>`; no git → `<no-git>`) |
 | `glob:<pattern>` | the **set of matching paths** or their metadata changes | sorted path list with size + mtime (content-hashed globs use `glob!:` instead, which is mtime-independent) |
@@ -497,7 +497,7 @@ Each entry is one of:
 ```jsonc
 { "id": "review", "type": "gate", "agent": "reviewer",
   "model": "claude-opus-4", "thinking": "high",
-  "task": "…\nVERDICT:", "dependsOn": ["audit"] }
+  "task": "...\nVERDICT:", "dependsOn": ["audit"] }
 ```
 
 **Sandbox a phase to read-only in a subdirectory:**
@@ -516,7 +516,7 @@ Each entry is one of:
 
 **Project-only agents:**
 ```jsonc
-{ "name": "ci-audit", "agentScope": "project", "phases": [ /* … */ ] }
+{ "name": "ci-audit", "agentScope": "project", "phases": [ /* ... */ ] }
 ```
 
 ---
@@ -555,22 +555,22 @@ symlinks, and commit atomically; `--emit both` preflights both destinations.
 
 **Authoring notes (kinds ↔ runes)**
 
-Import: `import { flow, agent, map, … } from "taskflow-dsl"`. Runes erase to Taskflow
+Import: `import { flow, agent, map, ... } from "taskflow-dsl"`. Runes erase to Taskflow
 JSON kinds (single source: `PHASE_TYPES` in core + `erase/kinds/*` registry).
 
 | JSON `type` | DSL rune(s) | Notes |
 |-------------|-------------|--------|
 | `agent` | `agent(task, opts?)` | templates → `{steps.*}` / `{item.*}` |
-| `parallel` | `parallel([agent…])` | waits for all branches |
-| `map` | `map(source, item => agent…)` | `over` + `as` |
+| `parallel` | `parallel([agent...])` | waits for all branches |
+| `map` | `map(source, item => agent...)` | `over` + `as` |
 | `gate` | `gate(up, opts?, task?)` · `gate.automated` · `gate.scored` | sugar → `eval` / `score` |
-| `reduce` | `reduce([…], () => agent…)` | `from` |
+| `reduce` | `reduce([...], () => agent...)` | `from` |
 | `approval` | `approval({ request })` | |
 | `flow` | `subflow("name")` · `subflow.def(plan)` | use vs def |
-| `loop` | `loop({ task, until?, … })` | |
-| `tournament` | `tournament({ branches/variants, judge, … })` | |
+| `loop` | `loop({ task, until?, ... })` | |
+| `tournament` | `tournament({ branches/variants, judge, ... })` | |
 | `script` | `script(run, opts?)` | string or argv array |
-| `race` | `race([agent…], { cancelLosers? })` | first **success** wins; cooperative loser usage is counted |
+| `race` | `race([agent...], { cancelLosers? })` | first **success** wins; cooperative loser usage is counted |
 | `expand` | `expand` / `expand.nested` / `expand.graft` | `def` + `expandMode` |
 
 - `const [a,b] = parallel([agent(...), agent(...)])` desugars to **two real agent phases** (`a`, `b`) that run concurrently (no `dependsOn` between them). Prefer this when you need `{steps.a.output}`.