hermes-workflow 0.1.3__tar.gz

hermes_workflow-0.1.3/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carlos Raphael
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hermes_workflow-0.1.3/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: hermes-workflow
+Version: 0.1.3
+Summary: Declarative multi-stage workflow primitive over the Hermes Kanban board.
+Author: Carlos Raphael
+License: MIT
+Project-URL: Homepage, https://github.com/carlosraphael/hermes-workflow
+Project-URL: Repository, https://github.com/carlosraphael/hermes-workflow
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML<7,>=6
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8; extra == "dev"
+Dynamic: license-file
+
+# hermes-workflow
+
+A declarative, versioned, multi-stage workflow primitive over the Hermes Kanban board.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Python: >=3.11](https://img.shields.io/badge/python-%3E%3D3.11-blue.svg)](pyproject.toml)
+[![CI](https://github.com/carlosraphael/hermes-workflow/actions/workflows/ci.yml/badge.svg)](https://github.com/carlosraphael/hermes-workflow/actions)
+
+A `*.workflow.yaml` template — params, abstract roles bound to lanes, stages with
+`needs`, a single-level `expand` fan-out plus an `expand_out` shape gate, a human
+`gate`, and workspaces — is instantiated into a Kanban card-graph that Hermes'
+existing dispatcher and worker lanes execute. It turns "hand-wire an orchestrator
+from scratch every run" into a repeatable, durable, inspectable run on the board
+you already use.
+
+## What it is
+
+A template compiles to a linked card-graph. Materialization is **lazy and
+single-level**:
+
+- `workflow_start` validates the template + bindings, runs a per-profile
+  pre-flight, and creates the **dynamic-free prefix** (the static stages up to
+  the first fan-out) plus a write-once compiled-snapshot **blackboard root**.
+- The `post_tool_call` **fan-out hook** fires as stages complete: when a source
+  stage finishes, it creates that fan-out's children **and** its join in one
+  atomic create, wiring the join as a child of every instance.
+
+Completion-gating is **deterministic and injection-free**, enforced by a
+`pre_tool_call` veto: it checks the `expand_out` shape + `max`, and commit-clean
+for worktree stages, before a stage may complete. There is no LLM in the gate.
+
+All state lives on the board — body sentinels, links, and statuses — and the run
+root is a write-once compiled-snapshot blackboard. Nothing touches raw SQLite —
+every mutation goes through Hermes' board APIs (`kanban_*` from workers, `kb.*`
+from the host).
+
+## Requirements
+
+- **Hermes Agent v0.15.x**
+- **Python ≥ 3.11**
+- For any role with `lane: codex`: the `codex` binary on `PATH`, and Hermes'
+  **bundled `kanban-codex-lane` skill** present in that role's bound profile.
+  This plugin **reuses** that skill — it does **not** re-ship it.
+
+## Quick Install
+
+The intended primary path is PyPI:
+
+```sh
+pip install hermes-workflow
+```
+
+From source:
+
+```sh
+git clone https://github.com/carlosraphael/hermes-workflow
+cd hermes-workflow
+pip install -e .
+```
+
+Then **enable it in EVERY bound profile** — not just the orchestrator's. This is
+a pip / entry-point plugin, so `hermes plugins enable` does **not** apply to it
+(that command only sees user-dir and bundled plugins). Instead add
+`hermes-workflow` to the `plugins.enabled` list in each bound profile's
+`config.yaml` — open it with `hermes -p <profile> config edit` (or edit
+`<that profile's HERMES_HOME>/config.yaml` directly) and add:
+
+```yaml
+plugins:
+  enabled:
+    - hermes-workflow
+```
+
+The change takes effect on the **next session**. (Do **not** use
+`hermes config set plugins.enabled …` — it writes a scalar string, which breaks
+the loader's list check.)
+
+**Per-profile enablement is the #1 failure mode.** Workers read the plugin's
+load status from the *assignee profile's* home, so the plugin must be enabled
+**and loadable** in every profile a role binds to. `workflow_start` runs a
+per-profile loadability pre-flight and **fails fast — creating zero cards** —
+with a per-profile remediation map if any bound profile cannot load it (or a
+codex role is missing its `codex` binary / `kanban-codex-lane` skill).
+
+## Quickstart
+
+Using `examples/fix-flaky-tests.workflow.yaml`. There are two surfaces; both take
+the same arguments.
+
+In-session slash command:
+
+```
+/workflow start --template examples/fix-flaky-tests.workflow.yaml \
+  --params '{"repo":"/abs/path/to/repo"}' \
+  --bindings '{"scout":"designer","fixer":"coder","reporter":"writer"}'
+```
+
+CLI:
+
+```sh
+hermes workflow start --template examples/fix-flaky-tests.workflow.yaml \
+  --params '{"repo":"/abs/path/to/repo"}' \
+  --bindings '{"scout":"designer","fixer":"coder","reporter":"writer"}'
+```
+
+### Run lifecycle
+
+1. The `scan` worker (role `scout`) inspects the repo and returns
+   `metadata.flaky = [{test_id, file}, …]`.
+2. The fan-out hook creates one `fix` card per flaky test — each on its own
+   pre-provisioned worktree, gated by commit-clean — and wires the `approve`
+   human gate as a child of all of them.
+3. Once every `fix` card is `done`, the gate promotes to `ready`.
+4. The operator runs `hermes workflow approve <gate_card>`. Find the gate card
+   with `hermes workflow status <root_id>` (it is listed under
+   `awaiting_approval`).
+5. `report` (role `reporter`) then runs, summarizing the fixes from the
+   handoffs and listing the branches.
+
+## Commands
+
+Both surfaces — the CLI (`hermes workflow <cmd>`) and the slash command
+(`/workflow <cmd>`) — dispatch the same tools (`workflow_start` … `workflow_abandon`).
+
+| Command | Form | What it does |
+|---|---|---|
+| `start` | `--template <path> --params <json> --bindings <json> [--board]` | Validate, pre-flight every bound profile, then seed the run (root blackboard + dynamic-free prefix). Fails closed with zero cards if any profile can't load. |
+| `status` | `<root_id> [--board]` | Read-only run summary: per-stage rollup plus `blocked_stages`, `awaiting_approval` (the gate signal), and `review_required`. |
+| `validate` | `--template <path>` | Deterministic, read-only template check. Rejects verify/retry and nested-expand. |
+| `reconcile` | `<root_id> [--board]` | Re-drive a partial fan-out: create missing children, re-link to the join, progress-aware dedup, and surface review-required stalls. |
+| `approve` | `<gate_card> [--board]` | Complete a human gate card so its downstream stages promote natively. |
+| `abandon` | `<root_id> [--board]` | Hazard-free teardown: reclaim running workers, then archive the run reverse-topologically (leaves-first). Worktrees are preserved. |
+
+The four mutating commands (`start`, `reconcile`, `approve`, `abandon`) refuse to
+run inside a dispatcher-spawned worker — they are orchestrator-context only.
+
+## Bundled skills
+
+Two skills are auto-registered on plugin load:
+
+- **`workflow-author`** — how to write a `*.workflow.yaml` template within the
+  0.1.0 constraints; validate it with `workflow_validate`.
+- **`workflow-orchestrator`** — start / status / approve / abandon / reconcile,
+  plus the review-required backstop for recovering a stalled stage.
+
+## 0.1.0 scope
+
+Lanes are `{profile, codex}` only — `claude-code` is deferred to 0.2.x.
+`verify.command` / `retry` and granular `reject` / `modify` are deferred to
+0.2.x. Nested fan-out (an `expand` stage that is itself an `expand` source) is
+**forbidden** in 0.1.0.
+
+## Documentation
+
+| Document | What it covers |
+|---|---|
+| [`AGENTS.md`](AGENTS.md) | Development guide for AI coding assistants and contributors. |
+| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Development setup, PR process, and code style. |
+| [`docs/operations.md`](docs/operations.md) | Upgrade / version-gate procedure and operational caveats. |
+| [`CONTEXT.md`](CONTEXT.md) | The naming taxonomy (distribution / import / plugin / runtime layers). |
+| [`docs/adr/`](docs/adr/) | Architecture decision records. |
+
+## Contributing
+
+Contributions are welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md) for the
+development setup, PR process, and code style.
+
+## License
+
+MIT — Copyright (c) 2026 Carlos Raphael. See [`LICENSE`](LICENSE).

hermes_workflow-0.1.3/README.md

@@ -0,0 +1,170 @@
+# hermes-workflow
+
+A declarative, versioned, multi-stage workflow primitive over the Hermes Kanban board.
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Python: >=3.11](https://img.shields.io/badge/python-%3E%3D3.11-blue.svg)](pyproject.toml)
+[![CI](https://github.com/carlosraphael/hermes-workflow/actions/workflows/ci.yml/badge.svg)](https://github.com/carlosraphael/hermes-workflow/actions)
+
+A `*.workflow.yaml` template — params, abstract roles bound to lanes, stages with
+`needs`, a single-level `expand` fan-out plus an `expand_out` shape gate, a human
+`gate`, and workspaces — is instantiated into a Kanban card-graph that Hermes'
+existing dispatcher and worker lanes execute. It turns "hand-wire an orchestrator
+from scratch every run" into a repeatable, durable, inspectable run on the board
+you already use.
+
+## What it is
+
+A template compiles to a linked card-graph. Materialization is **lazy and
+single-level**:
+
+- `workflow_start` validates the template + bindings, runs a per-profile
+  pre-flight, and creates the **dynamic-free prefix** (the static stages up to
+  the first fan-out) plus a write-once compiled-snapshot **blackboard root**.
+- The `post_tool_call` **fan-out hook** fires as stages complete: when a source
+  stage finishes, it creates that fan-out's children **and** its join in one
+  atomic create, wiring the join as a child of every instance.
+
+Completion-gating is **deterministic and injection-free**, enforced by a
+`pre_tool_call` veto: it checks the `expand_out` shape + `max`, and commit-clean
+for worktree stages, before a stage may complete. There is no LLM in the gate.
+
+All state lives on the board — body sentinels, links, and statuses — and the run
+root is a write-once compiled-snapshot blackboard. Nothing touches raw SQLite —
+every mutation goes through Hermes' board APIs (`kanban_*` from workers, `kb.*`
+from the host).
+
+## Requirements
+
+- **Hermes Agent v0.15.x**
+- **Python ≥ 3.11**
+- For any role with `lane: codex`: the `codex` binary on `PATH`, and Hermes'
+  **bundled `kanban-codex-lane` skill** present in that role's bound profile.
+  This plugin **reuses** that skill — it does **not** re-ship it.
+
+## Quick Install
+
+The intended primary path is PyPI:
+
+```sh
+pip install hermes-workflow
+```
+
+From source:
+
+```sh
+git clone https://github.com/carlosraphael/hermes-workflow
+cd hermes-workflow
+pip install -e .
+```
+
+Then **enable it in EVERY bound profile** — not just the orchestrator's. This is
+a pip / entry-point plugin, so `hermes plugins enable` does **not** apply to it
+(that command only sees user-dir and bundled plugins). Instead add
+`hermes-workflow` to the `plugins.enabled` list in each bound profile's
+`config.yaml` — open it with `hermes -p <profile> config edit` (or edit
+`<that profile's HERMES_HOME>/config.yaml` directly) and add:
+
+```yaml
+plugins:
+  enabled:
+    - hermes-workflow
+```
+
+The change takes effect on the **next session**. (Do **not** use
+`hermes config set plugins.enabled …` — it writes a scalar string, which breaks
+the loader's list check.)
+
+**Per-profile enablement is the #1 failure mode.** Workers read the plugin's
+load status from the *assignee profile's* home, so the plugin must be enabled
+**and loadable** in every profile a role binds to. `workflow_start` runs a
+per-profile loadability pre-flight and **fails fast — creating zero cards** —
+with a per-profile remediation map if any bound profile cannot load it (or a
+codex role is missing its `codex` binary / `kanban-codex-lane` skill).
+
+## Quickstart
+
+Using `examples/fix-flaky-tests.workflow.yaml`. There are two surfaces; both take
+the same arguments.
+
+In-session slash command:
+
+```
+/workflow start --template examples/fix-flaky-tests.workflow.yaml \
+  --params '{"repo":"/abs/path/to/repo"}' \
+  --bindings '{"scout":"designer","fixer":"coder","reporter":"writer"}'
+```
+
+CLI:
+
+```sh
+hermes workflow start --template examples/fix-flaky-tests.workflow.yaml \
+  --params '{"repo":"/abs/path/to/repo"}' \
+  --bindings '{"scout":"designer","fixer":"coder","reporter":"writer"}'
+```
+
+### Run lifecycle
+
+1. The `scan` worker (role `scout`) inspects the repo and returns
+   `metadata.flaky = [{test_id, file}, …]`.
+2. The fan-out hook creates one `fix` card per flaky test — each on its own
+   pre-provisioned worktree, gated by commit-clean — and wires the `approve`
+   human gate as a child of all of them.
+3. Once every `fix` card is `done`, the gate promotes to `ready`.
+4. The operator runs `hermes workflow approve <gate_card>`. Find the gate card
+   with `hermes workflow status <root_id>` (it is listed under
+   `awaiting_approval`).
+5. `report` (role `reporter`) then runs, summarizing the fixes from the
+   handoffs and listing the branches.
+
+## Commands
+
+Both surfaces — the CLI (`hermes workflow <cmd>`) and the slash command
+(`/workflow <cmd>`) — dispatch the same tools (`workflow_start` … `workflow_abandon`).
+
+| Command | Form | What it does |
+|---|---|---|
+| `start` | `--template <path> --params <json> --bindings <json> [--board]` | Validate, pre-flight every bound profile, then seed the run (root blackboard + dynamic-free prefix). Fails closed with zero cards if any profile can't load. |
+| `status` | `<root_id> [--board]` | Read-only run summary: per-stage rollup plus `blocked_stages`, `awaiting_approval` (the gate signal), and `review_required`. |
+| `validate` | `--template <path>` | Deterministic, read-only template check. Rejects verify/retry and nested-expand. |
+| `reconcile` | `<root_id> [--board]` | Re-drive a partial fan-out: create missing children, re-link to the join, progress-aware dedup, and surface review-required stalls. |
+| `approve` | `<gate_card> [--board]` | Complete a human gate card so its downstream stages promote natively. |
+| `abandon` | `<root_id> [--board]` | Hazard-free teardown: reclaim running workers, then archive the run reverse-topologically (leaves-first). Worktrees are preserved. |
+
+The four mutating commands (`start`, `reconcile`, `approve`, `abandon`) refuse to
+run inside a dispatcher-spawned worker — they are orchestrator-context only.
+
+## Bundled skills
+
+Two skills are auto-registered on plugin load:
+
+- **`workflow-author`** — how to write a `*.workflow.yaml` template within the
+  0.1.0 constraints; validate it with `workflow_validate`.
+- **`workflow-orchestrator`** — start / status / approve / abandon / reconcile,
+  plus the review-required backstop for recovering a stalled stage.
+
+## 0.1.0 scope
+
+Lanes are `{profile, codex}` only — `claude-code` is deferred to 0.2.x.
+`verify.command` / `retry` and granular `reject` / `modify` are deferred to
+0.2.x. Nested fan-out (an `expand` stage that is itself an `expand` source) is
+**forbidden** in 0.1.0.
+
+## Documentation
+
+| Document | What it covers |
+|---|---|
+| [`AGENTS.md`](AGENTS.md) | Development guide for AI coding assistants and contributors. |
+| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Development setup, PR process, and code style. |
+| [`docs/operations.md`](docs/operations.md) | Upgrade / version-gate procedure and operational caveats. |
+| [`CONTEXT.md`](CONTEXT.md) | The naming taxonomy (distribution / import / plugin / runtime layers). |
+| [`docs/adr/`](docs/adr/) | Architecture decision records. |
+
+## Contributing
+
+Contributions are welcome — see [`CONTRIBUTING.md`](CONTRIBUTING.md) for the
+development setup, PR process, and code style.
+
+## License
+
+MIT — Copyright (c) 2026 Carlos Raphael. See [`LICENSE`](LICENSE).

hermes_workflow-0.1.3/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hermes-workflow"
+version = "0.1.3"
+description = "Declarative multi-stage workflow primitive over the Hermes Kanban board."
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Carlos Raphael" }]
+dependencies = ["PyYAML>=6,<7"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Operating System :: OS Independent",
+]
+
+[project.urls]
+Homepage = "https://github.com/carlosraphael/hermes-workflow"
+Repository = "https://github.com/carlosraphael/hermes-workflow"
+
+[project.entry-points."hermes_agent.plugins"]
+hermes-workflow = "hermes_workflow"
+
+[project.optional-dependencies]
+dev = ["pytest>=8,<9"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+hermes_workflow = ["plugin.yaml", "skills/*/SKILL.md"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+markers = ["integration: requires a real Hermes board + plugin load (no LLM)"]

hermes_workflow-0.1.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hermes_workflow-0.1.3/src/hermes_workflow/__init__.py

@@ -0,0 +1,37 @@
+# src/hermes_workflow/__init__.py
+"""hermes-workflow: declarative workflow primitive over Hermes Kanban."""
+import pathlib
+
+from hermes_workflow.version import PLUGIN_VERSION
+from hermes_workflow import tools, hooks
+
+
+def register(ctx):
+    """Wire every hermes-workflow surface into the Hermes plugin context.
+
+    Tools + CLI + slash are orchestrator-context mutators (they self-refuse inside
+    a worker). Both hooks are bound to ``ctx`` via a closure because Hermes' hook
+    invoke does NOT pass ctx (post_tool_call fan-out + pre_tool_call completion gate).
+    """
+    for name, fn, schema in tools.TOOL_SPECS:
+        ctx.register_tool(name=name, toolset="workflow", schema=schema,
+                          handler=tools.make_tool_handler(ctx, fn))
+
+    ctx.register_hook("post_tool_call", lambda **kw: hooks.on_tool_done(ctx=ctx, **kw))
+    ctx.register_hook("pre_tool_call", lambda **kw: hooks.on_tool_pre(ctx=ctx, **kw))
+
+    ctx.register_cli_command("workflow", help="manage hermes-workflow runs",
+                             setup_fn=tools.cli_setup,
+                             handler_fn=lambda args: tools.cli_dispatch(ctx, args))
+    ctx.register_command("workflow", lambda raw: tools.slash_dispatch(ctx, raw),
+                         description="Manage hermes-workflow runs",
+                         args_hint="<start|status|validate|reconcile|approve|abandon>")
+
+    # Bundled skills are shipped in Phase 4; guard the (currently absent) dir so
+    # register stays crash-free until then.
+    skills_dir = pathlib.Path(__file__).parent / "skills"
+    if skills_dir.is_dir():
+        for child in sorted(p for p in skills_dir.iterdir() if (p / "SKILL.md").exists()):
+            ctx.register_skill(child.name, child / "SKILL.md")
+
+    getattr(ctx, "log", None) and ctx.log.info("hermes-workflow %s registered", PLUGIN_VERSION)

hermes_workflow-0.1.3/src/hermes_workflow/board.py

@@ -0,0 +1,126 @@
+# src/hermes_workflow/board.py
+"""Board adapter: two surfaces over the Hermes Kanban.
+
+WorkerBoard wraps the worker/hook *model-tool* surface (kanban_create/link/
+comment/show) via ``ctx.dispatch_tool(name, args) -> JSON string``. Every call
+gets an explicit ``board`` injected so it never relies on ambient env routing.
+
+HostBoard wraps the orchestrator/CLI *host* surface (kb.* functions) for the
+operations that have NO model tool — archive/unlink (Hermes finding Y) — plus a
+board-wide list/reclaim. It is constructed with an already board-scoped conn.
+"""
+import json
+
+from hermes_workflow.version import SENTINEL_ROOT_ASSIGNEE
+
+
+class WorkerBoard:
+    """Model-tool surface, reached through a dispatch context.
+
+    ``ctx`` only needs ``dispatch_tool(tool_name, args, **kwargs) -> str``.
+    """
+
+    def __init__(self, ctx, board):
+        self.ctx = ctx
+        self.board = board
+
+    def _call(self, tool, args):
+        """Dispatch a kanban tool with an explicit board, return parsed JSON.
+
+        Immutability: build a NEW args dict — never mutate the caller's.
+        """
+        payload = {**args, "board": self.board}
+        return json.loads(self.ctx.dispatch_tool(tool, payload))
+
+    def create(self, *, title, parents=(), assignee=SENTINEL_ROOT_ASSIGNEE,
+               workspace_kind="scratch", workspace_path=None, body="",
+               skills=None, idempotency_key=None):
+        # Always pass workspace_kind explicitly: if BOTH workspace_kind and
+        # workspace_path are omitted, _handle_create INHERITS the calling
+        # worker's workspace (kanban_tools.py:746-794). Passing them keeps the
+        # child's workspace deterministic.
+        r = self._call("kanban_create", {
+            "title": title,
+            "assignee": assignee,
+            "parents": list(parents) if parents else [],
+            "workspace_kind": workspace_kind,
+            "workspace_path": workspace_path,
+            "body": body,
+            "skills": skills,
+            "idempotency_key": idempotency_key,
+        })
+        if not r.get("ok"):
+            raise BoardError(f"kanban_create failed: {r}")
+        return r["task_id"]
+
+    def link(self, parent_id, child_id):
+        r = self._call("kanban_link", {"parent_id": parent_id, "child_id": child_id})
+        if not r.get("ok"):
+            raise BoardError(f"kanban_link failed: {r}")
+        return r
+
+    def comment(self, task_id, body):
+        r = self._call("kanban_comment", {"task_id": task_id, "body": body})
+        if not r.get("ok"):
+            raise BoardError(f"kanban_comment failed: {r}")
+        return r
+
+    def complete(self, *, task_id, summary=None):
+        r = self._call("kanban_complete", {"task_id": task_id, "summary": summary})
+        if not r.get("ok"):
+            raise BoardError(f"kanban_complete failed: {r}")
+        return r
+
+    def show(self, task_id):
+        """Return a FLAT card dict.
+
+        kanban_show (kanban_tools.py:339-412) returns a NESTED shape:
+        ``{"task": {...}, "parents": [...], "children": [...], "runs": [...],
+        "comments": [...], ...}`` — NOT an _ok envelope. Downstream Phase-2 code
+        (RunView/materializer/hooks) wants a single flat card, so this is the
+        one place we normalize: merge the ``task`` sub-dict up to the top level
+        and re-attach the link/run/comment lists.
+        """
+        raw = self._call("kanban_show", {"task_id": task_id})
+        if "task" not in raw:
+            # Error envelope ({"error": ...}/{"ok": false}) or a missing card.
+            raise BoardError(f"kanban_show returned no task for {task_id!r}: {raw}")
+        task = raw["task"]
+        return {
+            **task,
+            "parents": raw.get("parents", []),
+            "children": raw.get("children", []),
+            "runs": raw.get("runs", []),
+            "comments": raw.get("comments", []),
+            "events": raw.get("events", []),
+        }
+
+
+class HostBoard:
+    """Host kb.* surface for orchestrator/CLI-only operations.
+
+    The ``conn`` is already board-scoped, so kb.* calls take no ``board=``
+    kwarg. ``board`` is retained for identity/logging.
+    """
+
+    def __init__(self, kb, conn, board):
+        self.kb = kb
+        self.conn = conn
+        self.board = board
+
+    def list(self):
+        """Board-wide sweep (the conn is already board-scoped)."""
+        return self.kb.list_tasks(self.conn)
+
+    def archive(self, task_id):
+        return self.kb.archive_task(self.conn, task_id)
+
+    def unlink(self, parent_id, child_id):
+        return self.kb.unlink_tasks(self.conn, parent_id, child_id)
+
+    def reclaim(self, task_id):
+        return self.kb.reclaim_task(self.conn, task_id)
+
+
+class BoardError(RuntimeError):
+    """Raised when a kanban model-tool call returns a non-ok / error payload."""