@hecer/yoke 1.15.0 → 1.16.0

package/.claude-plugin/plugin.json

@@ -2,12 +2,12 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "yoke",
   "displayName": "Yoke",
-  "version": "1.13.0",
-  "description": "Cross-agent coding harness for Claude, Codex, Gemini, Qwen, OpenCode, Kilo and Pi: one curated skill canon plus mechanical safety gates and an autonomous loop via the yoke CLI.",
+  "version": "1.16.0",
+  "description": "Cross-agent coding harness for Claude, Codex, Gemini, Qwen, OpenCode, Kilo, Pi and Hermes: one curated skill canon plus mechanical safety gates and an autonomous loop via the yoke CLI.",
   "author": { "name": "HECer", "url": "https://github.com/HECer" },
   "homepage": "https://github.com/HECer/yoke#readme",
   "repository": "https://github.com/HECer/yoke",
   "license": "MIT",
-  "keywords": ["harness", "cross-agent", "tdd", "code-review", "autonomous-loop", "codex", "gemini-cli", "qwen-code", "opencode", "kilo", "pi"],
+  "keywords": ["harness", "cross-agent", "tdd", "code-review", "autonomous-loop", "codex", "gemini-cli", "qwen-code", "opencode", "kilo", "pi", "hermes"],
   "skills": "./canon/skills/"
 }

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "yoke",
-  "version": "1.13.0",
-  "description": "Cross-agent coding discipline, mechanical gates, and release workflows for seven supported harnesses",
+  "version": "1.16.0",
+  "description": "Cross-agent coding discipline, mechanical gates, and release workflows for eight supported harnesses",
   "skills": "./canon/skills/",
   "hooks": "./hooks/hooks.json"
 }

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 1.16.0 — 2026-09-17
+
+### Added
+- Add first-class adapter support for Nous Research's Hermes Agent (`hermes` CLI) as the eighth supported harness.
+- Add non-interactive execution for Hermes via `hermes chat --format stream-json --query-file -`.
+- Map permission profiles to Hermes toolset flags: `safe` to `--toolsets file,terminal`, `read-only` to `--toolsets file`, and `unsafe` to `--yolo`.
+- Add telemetry extraction for Hermes `stream-json` streams: assistant text deltas, token usage (`input`, `output`, `cache_read`, `cache_write`), total cost USD, and active model identities.
+- Recognize successful Hermes `tool_result` events as watchdog progress activity.
+- Add Hermes project marker detection (`.hermes`, `HERMES.md`, `hermes.yaml`, `hermes.json`) and host environment marker detection (`HERMES_SESSION_ID`, `HERMES_CONFIG`, `HERMES_HOME`).
+- Add Hermes retrofit planner generating complete skill packages under `.hermes/skills/`, shared `AGENTS.md` instructions, and a read-only reviewer agent (`.hermes/agents/yoke-reviewer.md`).
+- Add `hermes` to setup CLI options, routing worker presets (`hermes-standard`), fallback review providers, and runner affinity validation.
+- Add Hermes integration documentation in `docs/HARNESSES.md`.
+
+### Changed
+- Update README, package metadata, and manifests to reflect eight supported harnesses across invocation, routing, and retrofit architecture.
+- Synchronize Claude plugin, Codex plugin, Gemini extension, Canon, and npm package versions to 1.16.0.
+
+### Migration and validation limits
+- Run `yoke retrofit . --agent=hermes` or `yoke retrofit . --agent=all` to install native Hermes artifacts. External `hermes` CLI must be installed and configured separately; Yoke does not bundle runtimes or credentials.
+- Hermes runner does not support bare startup mode or native multi-agent delegation; Yoke enforces managed worker and single-flight execution boundaries.
+- Local verification: 1,285 tests passed, two platform-specific tests skipped, 141 test files passed; TypeScript lint/build, Canon validation, documentation metadata check, package dry run, and dependency audit passed.
+
+## 1.15.1 — 2026-09-16
+
+### Fixed
+- Sum finalized Pi assistant-turn usage without counting streamed snapshots or replayed transcripts twice; preserve missing measurements and multiple model identities.
+- Recognize successful Pi/OpenCode/Kilo tool events as watchdog progress without relaxing execution budgets.
+- Reject structured verdicts followed by terminal provider errors, reject errored/aborted Pi verdicts, and exclude Claude child-agent verdicts/usage from parent results.
+- Validate OpenCode/Kilo effort aliases consistently; emit a single variant flag.
+- Correct Pi settings-relative skill discovery and enforce manual-only skill invocation using Pi's native frontmatter.
+- Estimate schedule ranges from per-story scenarios and retain low confidence for sparse task-specific evidence.
+- Ship eight missing delegation/review/debugging/testing resources and clarify host capability, worker-budget and verification rules in the shared skills; remove unsupported quality/speed claims.
+- Keep coordinator unit tests offline by stubbing the separate preview backend; verify actual isolated edits and preservation of the source project.
+- Synchronize previously stale Claude/Codex plugin, Gemini extension and Canon versions with the npm package.
+
+### Migration and validation limits
+- Refresh generated skills with a reviewed `yoke retrofit . --agent=all` (or the selected agent). Current Pi requires explicit project trust to load project-local resources; Yoke does not grant it automatically. See [harness setup](docs/HARNESSES.md).
+- Existing custom configuration remains authoritative. No timeout or acceptance-gate defaults were weakened. Time ranges remain empirical, not guaranteed deadlines.
+- See the [audit and validation limits](docs/AGENT-HARDENING-2026-09-16.md). No authenticated seven-agent benchmark or guaranteed speed/quality improvement is claimed.
+- Local verification: 1,281 tests passed, two platform-specific tests skipped; TypeScript lint/build, Canon validation, documentation metadata, package dry run and dependency audit passed.
+
 ## 1.15.0 — 2026-09-09
 
 ### Added

package/README.md

@@ -1,15 +1,15 @@
 <div align="center">
 
-<h1><img src="https://raw.githubusercontent.com/HECer/yoke/v1.15.0/docs/assets/yoke-logo.png" alt="Yoke" width="100" height="63"></h1>
+<h1><img src="https://raw.githubusercontent.com/HECer/yoke/v1.16.0/docs/assets/yoke-logo.png" alt="Yoke" width="100" height="63"></h1>
 
-<!-- yoke:version:start -->1.15.0<!-- yoke:version:end -->
-<!-- yoke:tests:start -->1268<!-- yoke:tests:end -->
+<!-- yoke:version:start -->1.16.0<!-- yoke:version:end -->
+<!-- yoke:tests:start -->1287<!-- yoke:tests:end -->
 <!-- yoke:skills:start -->34<!-- yoke:skills:end -->
-<!-- yoke:agents:start -->Claude | Codex | Gemini | Qwen | OpenCode | Kilo | Pi<!-- yoke:agents:end -->
+<!-- yoke:agents:start -->Claude | Codex | Gemini | Qwen | OpenCode | Kilo | Pi | Hermes<!-- yoke:agents:end -->
 
-### One harness, seven agents — and zero trust in "done."
+### One harness, eight agents — and zero trust in "done."
 
-**Yoke** installs one curated canon of skills, **mechanical safety gates**, and tool wiring into any project — natively for **Claude Code, OpenAI Codex CLI, Gemini CLI, Qwen Code, OpenCode, Kilo, and Pi coding agent**. Its opt-in loop implements and verifies stories before committing. Independent review and browser proofs run when configured; screenshots and videos require the browser smoke gate.
+**Yoke** installs one curated canon of skills, **mechanical safety gates**, and tool wiring into any project — natively for **Claude Code, OpenAI Codex CLI, Gemini CLI, Qwen Code, OpenCode, Kilo, Pi coding agent, and Hermes Agent**. Its opt-in loop implements and verifies stories before committing. Independent review and browser proofs run when configured; screenshots and videos require the browser smoke gate.
 
 [![npm](https://img.shields.io/npm/v/%40hecer%2Fyoke?logo=npm&color=CB3837)](https://www.npmjs.com/package/@hecer/yoke)
 [![npm downloads](https://img.shields.io/npm/dm/%40hecer%2Fyoke?logo=npm)](https://www.npmjs.com/package/@hecer/yoke)
@@ -17,8 +17,8 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](#-license)
 ![Node](https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js&logoColor=white)
 ![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)
-![Tests](https://img.shields.io/badge/tests-1268%20defined-blue.svg)
-![Agents](https://img.shields.io/badge/agents-Claude%20%7C%20Codex%20%7C%20Gemini%20%7C%20Qwen%20%7C%20OpenCode%20%7C%20Kilo%20%7C%20Pi-8A2BE2)
+![Tests](https://img.shields.io/badge/tests-1287%20defined-blue.svg)
+![Agents](https://img.shields.io/badge/agents-Claude%20%7C%20Codex%20%7C%20Gemini%20%7C%20Qwen%20%7C%20OpenCode%20%7C%20Kilo%20%7C%20Pi%20%7C%20Hermes-8A2BE2)
 ![Built with TDD](https://img.shields.io/badge/built%20with-TDD%20%2B%20review-ff69b4.svg)
 
 **Install:** [`npm i -g @hecer/yoke`](https://www.npmjs.com/package/@hecer/yoke)
@@ -31,6 +31,8 @@
 
 OpenCode, Kilo and Pi are real CLI integrations, not bundled runtimes or credentials. OpenCode/Kilo use their JSON headless modes and local MCP configuration; Pi uses JSONL and explicit tool allowlists, but has no native MCP, sub-agent or plan layer. Read the [integration guide](docs/HARNESSES.md) before selecting a permission profile.
 
+**Fixed in 1.15.1:** multi-turn Pi usage accounting, provider error/progress handling, task-specific time ranges and missing skill resources. Pi has been supported since **1.13.0**; current Pi versions require explicit project trust for project-local skills in headless runs. The [agent/skill hardening audit](docs/AGENT-HARDENING-2026-09-16.md) documents the fixes, migration notes and validation limits.
+
 ### One dashboard, multiple projects
 
 ```sh
@@ -102,7 +104,7 @@ Agentic coding in 2026 fails in four well-documented ways. Yoke answers each one
 | 🌀 **Overnight loops going off the rails** | Raw Ralph-loop users "wake up to broken codebases that don't compile" | Yoke is **"Ralph, but with gates"**: clean-worktree gate, acceptance-criteria gate, green-tests gate, review gate, per-story worktree isolation, idle-timeout watchdog, single-flight lock, commit integrity. |
 | 😵 **Review fatigue** | AI adoption nearly doubles PR volume and review time; humans start skimming | **`yoke review`**: a second model writes a schema-validated pass/fail verdict — chainable into verify, pre-push, or CI. Cross-model review catches what self-review misses. |
 
-**Who it's for:** anyone driving Claude Code, Codex CLI, Gemini CLI, Qwen Code, OpenCode, Kilo or Pi on real projects — especially if you use more than one, want autonomous runs you can trust, or are tired of "done" meaning "probably". Greenfield (`yoke new`) and brownfield (`yoke retrofit`) both work.
+**Who it's for:** anyone driving Claude Code, Codex CLI, Gemini CLI, Qwen Code, OpenCode, Kilo, Pi or Hermes on real projects — especially if you use more than one, want autonomous runs you can trust, or are tired of "done" meaning "probably". Greenfield (`yoke new`) and brownfield (`yoke retrofit`) both work.
 
 **Who it's not for:** if you want a chat pair-programmer with no process, you don't need a harness. Yoke is for shipping with discipline.
 
@@ -157,7 +159,7 @@ The canon is also packaged as a Claude Code plugin — the repo is its own marke
 /plugin install yoke@yoke
 ```
 
-That gives you all canon skills under the `yoke:` namespace (e.g. `yoke:tdd`, `yoke:review`) inside Claude Code — no retrofit needed. The `yoke` CLI (loop, gates, retrofit for Codex/Gemini/Qwen/OpenCode/Kilo/Pi) still comes from `npm i -g @hecer/yoke`. Gemini CLI users can likewise `gemini extensions install https://github.com/HECer/yoke`.
+That gives you all canon skills under the `yoke:` namespace (e.g. `yoke:tdd`, `yoke:review`) inside Claude Code — no retrofit needed. The `yoke` CLI (loop, gates, retrofit for Codex/Gemini/Qwen/OpenCode/Kilo/Pi/Hermes) still comes from `npm i -g @hecer/yoke`. Gemini CLI users can likewise `gemini extensions install https://github.com/HECer/yoke`.
 
 For Codex, no preinstalled skill is required: run `npx @hecer/yoke setup .` in a terminal, or
 ask Codex to run the six-question Yoke setup flow. The retrofit writes native skills to
@@ -184,7 +186,7 @@ Auto-upgrade is deliberately **not** the default: a gate harness shouldn't chang
 
 ## 🤖 Driving it through an agent
 
-Yoke is meant to be operated *by* your coding agent — after a retrofit, the agent has the skills, the safety policy, and the routing, so it knows the methodology. Copy-paste prompts (identical wording works for Claude Code, Codex CLI, Gemini CLI, Qwen Code, OpenCode, Kilo, and Pi):
+Yoke is meant to be operated *by* your coding agent — after a retrofit, the agent has the skills, the safety policy, and the routing, so it knows the methodology. Copy-paste prompts (identical wording works for Claude Code, Codex CLI, Gemini CLI, Qwen Code, OpenCode, Kilo, Pi, and Hermes):
 
 > **Set it up** — *"Set up Yoke in this project. Ask me the Yoke setup questions one at a time with your recommendation, then run `yoke setup . --yes` with the selected host, agents, code graph, loop, runner, and decision policy. Commit in my configured identity."*
 
@@ -208,11 +210,11 @@ Yoke's CLI is deterministic and chainable by design: an agent (or a shell `&&`)
 | `yoke projects add\|list\|remove` | Register a project, list registrations or remove a reference by ID | `0` · `2` invalid/unavailable |
 | `yoke check [dir] [--json] [--requirement=] [--protect [--refresh]]` | Execute acceptance checks or explicitly pin their infrastructure | `0` passed/pinned · `1` failed · `2` unverified/unavailable |
 | `yoke goal set\|run\|resume\|pause\|status\|handoff\|budget [dir]` | Durable objectives, provider handoff, protected checks and checkpoint budgets | run/resume: `0` complete · `1` unfinished · `2` unavailable |
-| `yoke setup [dir] [--yes] [--host=] [--agent=] [--runner=] [--code-graph=] [--code-intelligence=off\|shadow\|active] [--decision-policy=] [--loop\|--no-loop] [--routing\|--no-routing] [--model-provider=deepseek,kimi]` | Shared setup for all seven harnesses; optional federated code intelligence and DeepSeek/Kimi API profiles | `0` · `1` invalid setup |
+| `yoke setup [dir] [--yes] [--host=] [--agent=] [--runner=] [--code-graph=] [--code-intelligence=off\|shadow\|active] [--decision-policy=] [--loop\|--no-loop] [--routing\|--no-routing] [--model-provider=deepseek,kimi]` | Shared setup for all eight harnesses; optional federated code intelligence and DeepSeek/Kimi API profiles | `0` · `1` invalid setup |
 | `yoke code-intelligence-server [--workspace=] [--mode=off\|shadow\|active]` | Serve the single Yoke-controlled MCP facade for federated code intelligence | `0` · `1` invalid/unavailable |
 | `yoke validate [canonDir]` | Validate the canon (schema, frontmatter, templates) | `0` valid · `1` errors |
 | `yoke new <dir> [--idea=] [--agent=] [--runner=] [--loop]` | Greenfield bootstrap: git init → scaffold → retrofit → context → PRD (drafted from `--idea`) → committed | `0` · `1` usage / non-empty dir / draft failed (scaffold survives) · `2` draft agent unavailable |
-| `yoke retrofit [dir] [--agent=claude,codex,gemini,qwen,opencode,kilo,pi\|all] [--code-graph=graphify\|serena] [--code-intelligence=off\|shadow\|active] [--loop]` | Install/update the harness for the selected agents, non-destructively | `0` |
+| `yoke retrofit [dir] [--agent=claude,codex,gemini,qwen,opencode,kilo,pi,hermes\|all] [--code-graph=graphify\|serena] [--code-intelligence=off\|shadow\|active] [--loop]` | Install/update the harness for the selected agents, non-destructively | `0` |
 | `yoke prd draft [dir] --idea= [--runner=] [--force]` | Idea → 5–12 stories with testable acceptance criteria | `0` · `1` invalid/guarded · `2` agent unavailable |
 | `yoke prd check [dir]` | PRD lint gate (schema, dependencies, cycles, duplicate ids, acceptance) | `0` valid · `1` violations |
 | `yoke change add\|status [dir] [--idea=]` | Queue a change at any time; the loop turns it into append-only stories at the next safe boundary | `0` · `1` invalid inbox/request |
@@ -232,7 +234,7 @@ Three excellent projects, three different jobs. Honest version:
 | | [superpowers](https://github.com/obra/superpowers) (obra) | [gstack](https://github.com/garrytan/gstack) (Garry Tan) | **Yoke** |
 |---|---|---|---|
 | **What it is** | The canonical *skills methodology*: brainstorm → plan → TDD → review as composable skills | A *software factory* for Claude Code: ~40 role skills (QA, CSO, ship…) + a real Chromium browser layer | A *cross-agent harness*: one canon → native installs, plus a gated autonomous loop |
-| **Agents** | Claude Code first | Claude Code + hosts like Codex/Cursor/Kiro — **no Gemini CLI** | **Claude Code, Codex CLI, Gemini CLI, Qwen Code, OpenCode, Kilo, Pi** from one source of truth |
+| **Agents** | Claude Code first | Claude Code + hosts like Codex/Cursor/Kiro — **no Gemini CLI** | **Claude Code, Codex CLI, Gemini CLI, Qwen Code, OpenCode, Kilo, Pi, Hermes** from one source of truth |
 | **Enforcement** | Advisory — skills *describe* the discipline; following them is up to the agent | Skill-driven; browser QA is genuinely real | **Mechanical** — gates live in code: clean tree, acceptance criteria, green tests, review verdict, commit integrity |
 | **Autonomy** | Interactive sessions | Interactive slash-commands (`/qa`, `/ship`, …) | Opt-in **Ralph loop** with watchdog, worktree isolation, single-flight lock, per-story proofs |
 | **Visual QA** | — | **Best-in-class**: live browser daemon (Chromium/CDP) with deep interactive QA | Built-in `flow-smoke` gate: screenshots always, video on failure, labelled per story — lighter, but *enforced* and cross-agent |
@@ -240,7 +242,7 @@ Three excellent projects, three different jobs. Honest version:
 | **Footprint** | Markdown skills (plugin) | ~230 MB with browser runtime; hourly auto-update | Node CLI + markdown canon; Playwright only if you use flow-smoke, resolved **from your project** |
 | **License** | MIT | MIT | MIT |
 
-**They compose — use all three where they're strongest.** Yoke's canon *ships* the superpowers methodology natively for all seven agents (13 skills, [attributed](canon/skills/ATTRIBUTION.md)). And if gstack is installed, `yoke retrofit` detects it and adds a routing note to `CLAUDE.md` telling Claude to prefer gstack's live-browser `/qa`, `/cso`, and ship pipeline for what Yoke deliberately doesn't bundle — no dependency, no conflict, and non-Claude artifacts stay uniform.
+**They compose — use all three where they're strongest.** Yoke's canon *ships* the superpowers methodology natively for all eight agents (13 skills, [attributed](canon/skills/ATTRIBUTION.md)). And if gstack is installed, `yoke retrofit` detects it and adds a routing note to `CLAUDE.md` telling Claude to prefer gstack's live-browser `/qa`, `/cso`, and ship pipeline for what Yoke deliberately doesn't bundle — no dependency, no conflict, and non-Claude artifacts stay uniform.
 
 **Choose Yoke when** you run more than one agent, want autonomy you can audit (gates + proofs + logs), or want one place to maintain your team's methodology. **Choose gstack when** you live 100% in Claude Code and want the deepest interactive browser QA. **Choose superpowers when** you want the methodology alone, interactively, in Claude Code — or just use it *through* Yoke.
 
@@ -260,6 +262,7 @@ flowchart TD
     Skill --> OpenCode["OpenCode<br/>AGENTS.md · opencode.json · .opencode/skills"]
     Skill --> Kilo["Kilo<br/>AGENTS.md · kilo.jsonc · .kilo/skills"]
     Skill --> Pi["Pi<br/>AGENTS.md · .pi/settings.json · .pi/skills"]
+    Skill --> Hermes["Hermes<br/>AGENTS.md · .hermes/skills · yoke-reviewer.md"]
     Loop["🤖 yoke loop — autonomous Ralph loop<br/>gates · verify · review · isolation · proofs"]
     Claude -. drives .-> Loop
     Codex -. drives .-> Loop
@@ -268,6 +271,7 @@ flowchart TD
     OpenCode -. drives .-> Loop
     Kilo -. drives .-> Loop
     Pi -. drives .-> Loop
+    Hermes -. drives .-> Loop
 ```
 
 Three layers — **Canon** (`yoke validate`) → **Retrofit** (`yoke retrofit`) → **Loop** (`yoke loop`) — on top of a durable **Context layer** (`yoke context`).
@@ -283,6 +287,7 @@ Three layers — **Canon** (`yoke validate`) → **Retrofit** (`yoke retrofit`)
 | **OpenCode** | Complete skill packages under `.opencode/skills/`, shared `AGENTS.md`, merged `opencode.json` (instructions + local MCP), and `.opencode/agents/yoke-reviewer.md` |
 | **Kilo** | Complete skill packages under `.kilo/skills/`, shared `AGENTS.md`, merged `kilo.jsonc` (instructions + local MCP), and `.kilo/agents/yoke-reviewer.md` |
 | **Pi** | Complete skill packages under `.pi/skills/`, shared `AGENTS.md`, and merged `.pi/settings.json`; Pi's tool allowlists are applied at invocation time |
+| **Hermes** | Complete skill packages under `.hermes/skills/`, shared `AGENTS.md`, and `.hermes/agents/yoke-reviewer.md` |
 
 > **rtk integration:** Claude receives its PreToolUse hook; Codex receives a native hook adapter around `rtk hook check`; Gemini retains instruction-mode fallback where its CLI has no equivalent command-rewrite lifecycle.
 
@@ -299,11 +304,11 @@ Three layers — **Canon** (`yoke validate`) → **Retrofit** (`yoke retrofit`)
 
 `yoke retrofit` installs all of these into each selected agent natively. Provenance is credited in [`canon/skills/ATTRIBUTION.md`](canon/skills/ATTRIBUTION.md).
 
-To stop overlapping skills from auto-invoking against each other, `canon/AGENTS.md` carries a **skill routing & precedence** block (methodology before role; one canonical entrypoint per concern — e.g. pre-merge code review is always `review`), emitted into all seven agents.
+To stop overlapping skills from auto-invoking against each other, `canon/AGENTS.md` carries a **skill routing & precedence** block (methodology before role; one canonical entrypoint per concern — e.g. pre-merge code review is always `review`), emitted into all eight agents.
 
 Each manifest entry also declares `invocation: auto|manual`. Retrofit translates that intent into
 the provider's native controls: Claude and Qwen disable model invocation for manual skills, Codex writes
-`agents/openai.yaml`, Gemini lists only automatic skills in its generated index, and OpenCode/Kilo/Pi
+`agents/openai.yaml`, Gemini lists only automatic skills in its generated index, and OpenCode/Kilo/Pi/Hermes
 receive complete project-local skill packages. Validation
 rejects conflicting package metadata and broken local Markdown links before anything is installed.
 
@@ -606,8 +611,8 @@ Loop runners disable native delegation in Codex, Claude, Gemini, Qwen, OpenCode
 the Yoke worker budget. Integration retains its execution slot until the candidate lands.
 
 **Provider support:** adaptive routing uses Yoke's shared provider adapter and works with Claude
-Code, Codex CLI, Gemini CLI, Qwen Code, OpenCode, Kilo and Pi, including mixed-provider worker lists.
-Internal contract tests cover invocation and routing behavior for all seven providers. The measured
+Code, Codex CLI, Gemini CLI, Qwen Code, OpenCode, Kilo, Pi, and Hermes, including mixed-provider worker lists.
+Internal contract tests cover invocation and routing behavior for all eight providers. The measured
 performance evidence below is intentionally **Codex-only**; it does not claim equivalent savings
 until authenticated, repeated in-the-wild runs exist for each provider.
 
@@ -908,7 +913,7 @@ src/
   canon/          # manifest schema + validator (yoke validate)
   code-intelligence/ # federated MCP facade, adapters, snapshots and guarded edits
   change/         # append-only change inbox · planning · independent coverage review
-  retrofit/       # detect · plan · apply · planners (all seven harnesses) · tools
+  retrofit/       # detect · plan · apply · planners (all eight harnesses) · tools
   loop/           # prd · gates · runner · verify · git/worktree · loop · run-command · lock · cleanup
   quality/        # reference collection · blind critic · bounded repair · candidate comparison
   new/            # yoke new — greenfield bootstrap
@@ -929,7 +934,7 @@ release provenance.
 ## 🧪 Development
 
 ```bash
-npm test          # vitest (1268 tests)
+npm test          # vitest (1287 tests)
 npm run build     # tsc, no emit errors
 npm run yoke -- validate canon
 ```

package/canon/AGENTS.md

@@ -9,6 +9,13 @@ You are operating in a project retrofitted by Yoke. Follow these always:
 
 This file is the portable baseline. Agent-specific instructions are generated alongside it (CLAUDE.md, GEMINI.md).
 
+## Host capabilities and execution budgets
+
+- Use only tools and skills actually installed in the host. Legacy `superpowers:` references in adapted skills refer to the corresponding local skill; `test-driven-development` maps to `tdd`. Do not install another plugin just to resolve a namespace.
+- When Yoke owns the loop, worker concurrency, verification, and integration remain under its control. Do not start nested loops or native subagents from a worker. Without native delegation, work serially and expose missing independent-review evidence.
+- Run focused checks for quick feedback, but never skip required acceptance, protected, integration, or release gates. Cache evidence only when code, configuration, and environment still match.
+- Distinguish observed durations from future estimates. Report the sample count, empirical range, and unknown waiting time; a timeout is a budget, not a promised completion time. Do not reduce reasoning or test scope merely to meet an estimate.
+
 ## Skill routing & precedence
 
 When several skills could match the same task, resolve deterministically:

package/canon/manifest.yaml

@@ -1,6 +1,6 @@
 name: yoke-canon
-version: 1.14.0
-agents: [claude, codex, gemini, qwen, opencode, kilo, pi]
+version: 1.16.0
+agents: [claude, codex, gemini, qwen, opencode, kilo, pi, hermes]
 skills:
   - { id: tdd, path: skills/tdd, kind: methodology, invocation: auto }
   - { id: yoke-retrofit, path: skills/yoke-retrofit, kind: methodology, invocation: auto }

package/canon/skills/executing-plans/SKILL.md

@@ -11,7 +11,7 @@ Load plan, review critically, execute all tasks, report when complete.
 
 **Announce at start:** "I'm using the executing-plans skill to implement this plan."
 
-**Note:** Tell your human partner that Superpowers works much better with access to subagents. The quality of its work will be significantly higher if run on a platform with subagent support (such as Claude Code or Codex). If subagents are available, use superpowers:subagent-driven-development instead of this skill.
+Use `subagent-driven-development` only when the host exposes delegation and the current run permits it. Inside a Yoke worker, execute the assigned task without launching nested workers; Yoke owns concurrency and independent review. Without delegation, execute serially and report any unavailable independent review explicitly. Subagents alone do not guarantee better quality or faster completion.
 
 ## The Process
 

package/canon/skills/requesting-code-review/SKILL.md

@@ -31,7 +31,7 @@ HEAD_SHA=$(git rev-parse HEAD)
 
 **2. Dispatch code-reviewer subagent:**
 
-Use Task tool with superpowers:code-reviewer type, fill template at `code-reviewer.md`
+Use the host's available read-only reviewer mechanism and fill the [review template](code-reviewer.md). Do not assume a `Task` tool exists. Inside a Yoke worker, hand evidence to Yoke's configured reviewer instead of launching nested agents. If independent review is unavailable, report that limitation; self-review is not an equivalent substitute.
 
 **Placeholders:**
 - `{WHAT_WAS_IMPLEMENTED}` - What you just built
@@ -102,4 +102,4 @@ You: [Fix progress indicators]
 - Show code/tests that prove it works
 - Request clarification
 
-See template at: requesting-code-review/code-reviewer.md
+See the [review template](code-reviewer.md).

package/canon/skills/requesting-code-review/code-reviewer.md

@@ -0,0 +1,12 @@
+# Code review request
+
+- Implementation: {WHAT_WAS_IMPLEMENTED}
+- Acceptance criteria and requirements: {PLAN_OR_REQUIREMENTS}
+- Base commit: {BASE_SHA}
+- Candidate commit: {HEAD_SHA}
+- Context and constraints: {DESCRIPTION}
+- Permitted read scope, available checks, artifacts and known validation gaps: fill explicitly.
+
+Independently inspect the actual candidate against requirements. Check correctness, failure handling, security, concurrency, maintainability and meaningful regression tests. Do not edit the candidate, weaken tests, merge or publish.
+
+Return evidence-backed critical/important findings separately from minor suggestions. Each finding needs a location, failure scenario and validation approach. Distinguish verified, failed and unverified criteria. State limitations and whether unresolved blockers prevent acceptance; a test summary alone is insufficient.

package/canon/skills/subagent-driven-development/SKILL.md

@@ -5,6 +5,10 @@ description: Use when executing implementation plans with independent tasks in t
 
 # Subagent-Driven Development
 
+## Host capability and budget check
+
+Use this workflow only if native delegation is available and authorized. Do not invent a `Task` or `TodoWrite` tool on hosts that lack it. Pi has no built-in subagents; use Yoke's scheduler or `executing-plans` instead. When running inside an existing Yoke worker, do not start nested agents or another loop: return evidence to the controlling runner. Independent review must not be replaced by claiming a self-review was independent.
+
 Execute plan by dispatching fresh subagent per task, with two-stage review after each: spec compliance review first, then code quality review.
 
 **Why subagents:** You delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed at their task. They should never inherit your session's context or history — you construct exactly what they need. This also preserves your own context for coordination work.
@@ -119,9 +123,9 @@ Implementer subagents report one of four statuses. Handle each appropriately:
 
 ## Prompt Templates
 
-- `./implementer-prompt.md` - Dispatch implementer subagent
-- `./spec-reviewer-prompt.md` - Dispatch spec compliance reviewer subagent
-- `./code-quality-reviewer-prompt.md` - Dispatch code quality reviewer subagent
+- [Implementer prompt](./implementer-prompt.md) - Dispatch implementer subagent
+- [Spec reviewer prompt](./spec-reviewer-prompt.md) - Dispatch spec compliance reviewer subagent
+- [Code quality reviewer prompt](./code-quality-reviewer-prompt.md) - Dispatch code quality reviewer subagent
 
 ## Example Workflow
 

package/canon/skills/subagent-driven-development/code-quality-reviewer-prompt.md

@@ -0,0 +1,7 @@
+# Code quality reviewer handoff
+
+Supply the task, Acceptance criteria, base and candidate commits, architecture constraints, test evidence, and known risks. Review with read-only permissions after the specification review.
+
+Inspect correctness, error paths, concurrency, resource cleanup, security boundaries, compatibility, and regression coverage. Prioritize reproducible defects over stylistic preferences. Check that optimizations preserve required gates and that unknown usage or timing evidence is not reported as zero or certainty.
+
+Return severity-ranked findings with precise locations, failure scenarios, and suggested regression tests. Separate required fixes from optional improvements. State validation limits even when no defects are found. Never edit the candidate, self-merge, or infer release readiness solely from a green test summary.

package/canon/skills/subagent-driven-development/implementer-prompt.md

@@ -0,0 +1,7 @@
+# Implementer handoff
+
+Supply the task, repository/worktree path, base commit, allowed write scope, relevant interfaces, and Acceptance criteria with their required checks. Include only relevant context and previous failure evidence.
+
+Implement only the assigned task. Preserve unrelated changes. Reproduce defects with a failing test before fixing them; do not weaken protected tests or acceptance checks. Run focused checks during iteration and all required gates before handoff. Do not spawn nested workers, publish, merge, or expand permissions. Commit only if the controller explicitly delegates that responsibility.
+
+Return: outcome, changed files, exact checks and exit results, remaining risks, blockers, and artifact paths. Report incomplete work as incomplete. If blocked by a product decision or missing credentials, retain the work and explain what is needed; do not repeat the same failing action indefinitely.

package/canon/skills/subagent-driven-development/spec-reviewer-prompt.md

@@ -0,0 +1,7 @@
+# Specification reviewer handoff
+
+Supply the original task, Acceptance criteria, base and candidate commits, allowed read scope, and validation commands. Review independently from the implementer, with read-only permissions.
+
+Compare the actual diff and observable behavior to each criterion. Check omissions, unauthorized additions, weakened tests, and whether evidence applies to the candidate being reviewed. Do not rely on the implementer's completion claim. Run permitted non-mutating checks where feasible; mark unavailable checks as unverified.
+
+Return one disposition per criterion: verified, failed, or unverified, with file/line or command evidence. Give actionable defects and distinguish blockers from optional suggestions. Do not modify files, approve an unverified requirement, merge, or publish.

package/canon/skills/systematic-debugging/SKILL.md

@@ -111,7 +111,7 @@ You MUST complete each phase before proceeding to the next.
 
    **WHEN error is deep in call stack:**
 
-   See `root-cause-tracing.md` in this directory for the complete backward tracing technique.
+   See [root-cause tracing](root-cause-tracing.md) for the backward tracing technique.
 
    **Quick version:**
    - Where does bad value originate?
@@ -273,24 +273,20 @@ If systematic investigation reveals issue is truly environmental, timing-depende
 3. Implement appropriate handling (retry, timeout, error message)
 4. Add monitoring/logging for future investigation
 
-**But:** 95% of "no root cause" cases are incomplete investigation.
+Before declaring the cause unknowable, record what was ruled out and which observations are still missing.
 
 ## Supporting Techniques
 
 These techniques are part of systematic debugging and available in this directory:
 
-- **`root-cause-tracing.md`** - Trace bugs backward through call stack to find original trigger
-- **`defense-in-depth.md`** - Add validation at multiple layers after finding root cause
-- **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling
+- [Root-cause tracing](root-cause-tracing.md) - Trace bugs backward to the original trigger
+- [Defense in depth](defense-in-depth.md) - Validate relevant trust boundaries after finding the cause
+- [Condition-based waiting](condition-based-waiting.md) - Replace arbitrary sleeps with bounded condition waits
 
 **Related skills:**
 - **superpowers:test-driven-development** - For creating failing test case (Phase 4, Step 1)
 - **superpowers:verification-before-completion** - Verify fix worked before claiming success
 
-## Real-World Impact
+## Measuring impact
 
-From debugging sessions:
-- Systematic approach: 15-30 minutes to fix
-- Random fixes approach: 2-3 hours of thrashing
-- First-time fix rate: 95% vs 40%
-- New bugs introduced: Near zero vs common
+Record time to reproduce, time to a verified fix, retries and escaped regressions for the actual project. No fixed speedup, success rate or absence of new bugs is guaranteed by this workflow.

package/canon/skills/systematic-debugging/condition-based-waiting.md

@@ -0,0 +1,7 @@
+# Condition-based waiting
+
+Prefer a completion event or promise over sleeping for an assumed duration. Subscribe before starting work so a fast completion is not missed. Handle success, failure, cancellation and timeout, and remove listeners/timers in every terminal path.
+
+If polling is unavoidable, choose a measurable condition, bounded deadline and modest interval. Preserve the last observed state in the timeout error. Do not treat repeated log output as successful progress.
+
+Tests should control time or use an explicit readiness signal. Keep one real process integration test where needed. A larger timeout is justified only by measured runtime and does not repair a race or an unintended network call.

package/canon/skills/systematic-debugging/defense-in-depth.md

@@ -0,0 +1,7 @@
+# Defense in depth
+
+Fix the originating contract violation first. Then identify independent trust boundaries where malformed or stale data could enter again: configuration, external process output, persisted state and public interfaces.
+
+Validate at those boundaries with explicit errors and preserve unknown values. Avoid scattering duplicate checks through code that already has a validated type. Do not catch every exception and return success or zero.
+
+Test malformed input, missing evidence, stale state, cancellation and cleanup. For destructive operations verify target scope and authority independently of the requesting model. Protection layers must not weaken acceptance tests or convert a blocked action into an automatic permission bypass.

package/canon/skills/systematic-debugging/root-cause-tracing.md

@@ -0,0 +1,9 @@
+# Root-cause tracing
+
+Capture the smallest failing command, inputs, expected/actual behavior, environment and code revision. Reproduce before changing code.
+
+Trace backward from the first observed invalid value or state transition to its producer. At each boundary, record the input, output and contract without logging credentials. Distinguish a downstream symptom from the earliest violated invariant.
+
+Form one falsifiable hypothesis and choose an observation that separates it from alternatives. Change one factor at a time. If reproduction depends on concurrency, preserve scheduling and cancellation evidence rather than adding arbitrary delays.
+
+Write a regression test at the violated boundary, demonstrate its failure, fix the cause and run dependent checks. Document remaining uncertainty instead of attributing an intermittent pass to a fix without evidence.

package/canon/skills/tdd/SKILL.md

@@ -356,7 +356,7 @@ Never fix bugs without a test.
 
 ## Testing Anti-Patterns
 
-When adding mocks or test utilities, read @testing-anti-patterns.md to avoid common pitfalls:
+When adding mocks or test utilities, read [testing anti-patterns](testing-anti-patterns.md) to avoid common pitfalls:
 - Testing mock behavior instead of real behavior
 - Adding test-only methods to production classes
 - Mocking without understanding dependencies

package/canon/skills/tdd/testing-anti-patterns.md

@@ -0,0 +1,9 @@
+# Testing anti-patterns
+
+- Test observable behavior, not that a mock returned the value you supplied. Assert resulting state and failure behavior as well as calls.
+- Mock external boundaries deliberately. If production constructs a second client for an isolated workspace, replace that constructor too; a unit test must not silently invoke a real network backend.
+- Do not mock the implementation under test or delete assertions to make a change pass. Keep at least one contract/integration check for important boundaries.
+- Demonstrate that the regression test fails for the original defect and passes after the fix. A new green test alone does not establish that it detects the bug.
+- Avoid arbitrary sleeps and broad timeout increases. Use readiness events, controlled clocks and bounded cancellation.
+- Preserve protected acceptance tests and required gates. Focused tests speed feedback but do not replace release validation.
+- Report skipped tests, unavailable platforms and missing credentials separately from passing checks. Never convert absent measurements into measured zero.

package/canon/skills/yoke-retrofit/SKILL.md

@@ -7,7 +7,7 @@ description: Use when asked to "retrofit", "yoke this project", or set up the Yo
 
 Set up or update Yoke through the shared `yoke setup` contract.
 
-1. Inspect the project and identify the current host (`claude`, `codex`, `gemini`, `qwen`, `opencode`, `kilo`, or `pi`).
+1. Inspect the project and identify the current host (`claude`, `codex`, `gemini`, `qwen`, `opencode`, `kilo`, `pi`, or `hermes`).
 2. Ask these setup questions one at a time and give a direct recommendation:
    - target agents (recommend the current host; use `all` for deliberately cross-agent projects),
    - code-graph tool,

package/dist/agents/contracts.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-export const AgentSchema = z.enum(['claude', 'codex', 'gemini', 'qwen', 'opencode', 'kilo', 'pi']);
+export const AgentSchema = z.enum(['claude', 'codex', 'gemini', 'qwen', 'opencode', 'kilo', 'pi', 'hermes']);
 export const PermissionProfileSchema = z.enum(['safe', 'unsafe', 'read-only']);
 export const ModelSelectionSchema = z.object({
     provider: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/).optional(),

package/dist/agents/host.js

@@ -13,6 +13,8 @@ export function detectHostAgent(env = process.env) {
         return 'opencode';
     if (env.KILO_CLIENT || env.KILO_CONFIG || env.KILO_CONFIG_DIR)
         return 'kilo';
+    if (env.HERMES_SESSION_ID || env.HERMES_CONFIG)
+        return 'hermes';
     if (env.CODEX_HOME)
         return 'codex';
     if (env.CLAUDE_CONFIG_DIR)
@@ -21,6 +23,8 @@ export function detectHostAgent(env = process.env) {
         return 'gemini';
     if (env.QWEN_CLI_HOME)
         return 'qwen';
+    if (env.HERMES_HOME)
+        return 'hermes';
     return undefined;
 }
 export function resolveRunnerAgent(config, explicit, host) {

package/dist/agents/pi-telemetry.js

@@ -0,0 +1,53 @@
+const record = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const finite = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0;
+/** Pi usage is per assistant message, not cumulative across a run. */
+export function createPiTelemetry() {
+    const totals = {};
+    const counts = {};
+    const models = new Set();
+    let turns = 0;
+    let legacyUsage;
+    const add = (usage) => {
+        turns++;
+        const fields = {
+            inputTokens: usage?.input, outputTokens: usage?.output,
+            cachedInputTokens: usage?.cacheRead, cacheWriteInputTokens: usage?.cacheWrite,
+            reasoningOutputTokens: usage?.reasoning,
+            totalCostUsd: record(usage?.cost) ? usage.cost.total : undefined,
+        };
+        for (const [key, value] of Object.entries(fields))
+            if (finite(value)) {
+                totals[key] = (totals[key] ?? 0) + value;
+                counts[key] = (counts[key] ?? 0) + 1;
+            }
+    };
+    return {
+        consume(event) {
+            // Compatibility with earlier top-level snapshots; never override a final usage.
+            if (event.type === 'message_update' && record(event.usage))
+                legacyUsage = event.usage;
+            if (event.type !== 'message_end' || !record(event.message) || event.message.role !== 'assistant')
+                return;
+            if (typeof event.message.model === 'string' && event.message.model)
+                models.add(event.message.model);
+            add(record(event.message.usage) ? event.message.usage : legacyUsage);
+            legacyUsage = undefined;
+        },
+        finish() {
+            const reportedModels = [...models];
+            const complete = turns > 0 && counts.inputTokens === turns && counts.outputTokens === turns;
+            if (complete) {
+                // Optional totals must also cover every turn; omitted is not measured zero.
+                const measured = Object.fromEntries(Object.entries(totals).filter(([key]) => counts[key] === turns));
+                return { usageAvailable: true, tokens: {
+                        ...measured, inputTokens: totals.inputTokens, outputTokens: totals.outputTokens,
+                        ...(reportedModels.length === 1 ? { model: reportedModels[0] } : {}),
+                    }, ...(reportedModels.length > 1 ? { reportedModels } : {}) };
+            }
+            return { usageAvailable: false,
+                ...(Object.keys(totals).length ? { partialUsage: { ...totals } } : {}),
+                ...(reportedModels.length ? { reportedModels } : {}),
+            };
+        },
+    };
+}

package/dist/agents/process-streams.js

@@ -1,4 +1,5 @@
 import { parseProviderTelemetry } from './telemetry.js';
+import { createPiTelemetry } from './pi-telemetry.js';
 export function createBoundedOutput(limitBytes) {
     let text = '';
     let truncated = false;
@@ -17,6 +18,7 @@ export function createBoundedOutput(limitBytes) {
     };
 }
 export function createTelemetryAccumulator(agent) {
+    const pi = agent === 'pi' ? createPiTelemetry() : undefined;
     let trailing = '';
     let telemetry = { usageAvailable: false };
     let reportedModels = [];
@@ -25,6 +27,15 @@ export function createTelemetryAccumulator(agent) {
         : undefined;
     const update = (lines) => {
         for (const line of lines) {
+            if (pi) {
+                try {
+                    const event = JSON.parse(line);
+                    if (event && typeof event === 'object' && !Array.isArray(event))
+                        pi.consume(event);
+                }
+                catch { /* non-JSON diagnostics carry no usage */ }
+                continue;
+            }
             const next = parseProviderTelemetry(agent, [line]);
             if (next.reportedModels)
                 reportedModels = next.reportedModels;
@@ -75,6 +86,8 @@ export function createTelemetryAccumulator(agent) {
             if (trailing)
                 update([trailing]);
             trailing = '';
+            if (pi)
+                return pi.finish();
             if (stepTotals && (stepTotals.hasInput || stepTotals.hasOutput)) {
                 const latest = telemetry.tokens;
                 const inputTokens = stepTotals.hasInput ? stepTotals.input : latest?.inputTokens;