@hecer/yoke 1.14.0 → 1.15.1

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "yoke",
   "displayName": "Yoke",
-  "version": "1.13.0",
+  "version": "1.15.1",
   "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.",
   "author": { "name": "HECer", "url": "https://github.com/HECer" },
   "homepage": "https://github.com/HECer/yoke#readme",

package/.codex-plugin/plugin.json

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

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 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
+- Add opt-in federated Code Intelligence that composes Graft, Graphify and Serena behind one Yoke-controlled MCP facade with six stable tools for context, symbols, traces, impact and edit workflows.
+- Add pinned backend adapters, explicit coverage/provenance/freshness evidence, content-addressed workspace snapshots and bounded local policy checks.
+- Add isolated edit previews and guarded apply transactions with approval, snapshot freshness, exclusive locking and idempotency checks; Yoke's existing review, verify and commit gates remain authoritative.
+
+### Changed
+- Add `off`, `shadow` and `active` Code Intelligence modes to setup and retrofit. `off` preserves the legacy `codeGraph` path unchanged; `shadow` is read-only; `active` enables preview and approved edits.
+- Keep backend runtimes external and configurable instead of vendoring or silently installing them. Pin the validated integration targets to Graft `0.17.0`, Graphify `0.9.56` and Serena `1.7.1-dev`.
+- Add the [Code Intelligence guide](docs/CODE-INTELLIGENCE.md), including setup, backend requirements, safety boundaries, limitations and the Pi integration note.
+
+### Migration and validation limits
+- No migration is required. Existing projects remain on the legacy path until `yoke setup` or `yoke retrofit` is run with `--code-intelligence=shadow` or `--code-intelligence=active`.
+- Validated with the Code Intelligence contract/coordinator/snapshot/MCP tests, TypeScript lint/build, documentation metadata, package dry run and the facade MCP handshake. The full suite retains one pre-existing provider-process timing failure; it is reproduced independently and is not caused by this release.
+- This release does not claim that every language or backend is available in every environment. Backend failures are surfaced as partial coverage or an explicit unavailable capability, never silently treated as complete evidence.
+
 ## 1.14.0 — 2026-09-09
 
 ### Added

package/README.md

@@ -1,9 +1,9 @@
 <div align="center">
 
-<h1><img src="https://raw.githubusercontent.com/HECer/yoke/v1.14.0/docs/assets/yoke-logo.png" alt="Yoke" width="100" height="63"></h1>
+<h1><img src="https://raw.githubusercontent.com/HECer/yoke/v1.15.1/docs/assets/yoke-logo.png" alt="Yoke" width="100" height="63"></h1>
 
-<!-- yoke:version:start -->1.14.0<!-- yoke:version:end -->
-<!-- yoke:tests:start -->1258<!-- yoke:tests:end -->
+<!-- yoke:version:start -->1.15.1<!-- yoke:version:end -->
+<!-- yoke:tests:start -->1283<!-- yoke:tests:end -->
 <!-- yoke:skills:start -->34<!-- yoke:skills:end -->
 <!-- yoke:agents:start -->Claude | Codex | Gemini | Qwen | OpenCode | Kilo | Pi<!-- yoke:agents:end -->
 
@@ -17,7 +17,7 @@
 [![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-1258%20defined-blue.svg)
+![Tests](https://img.shields.io/badge/tests-1283%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)
 ![Built with TDD](https://img.shields.io/badge/built%20with-TDD%20%2B%20review-ff69b4.svg)
 
@@ -27,10 +27,12 @@
 
 > **TL;DR** — `yoke setup .` asks six questions and installs the native harness for your agent. `yoke new my-app --idea="..."` bootstraps a project and drafts its story backlog. `yoke loop run my-app --isolate --review` then implements it behind hard gates: **clean tree → acceptance criteria → your real tests green → an independent model approves → commit**. Add `--parallel=N` for dependency-aware workers, or declare a reference and add `--quality` for a bounded critic/repair gauntlet. If any blocking gate is red, nothing is committed. Proof lives in `.yoke/proof/<story>/`.
 
-**New in 1.13.0:** first-class [OpenCode, Kilo and Pi integrations](docs/HARNESSES.md), including native headless invocation, provider/model/variant routing, retrofit artifacts, role configuration and provider telemetry. [Qwen Code hardening and explicit DeepSeek/Kimi API model profiles](docs/QWEN-MODEL-SUPPORT.md) remain available. Since 1.10.0, Yoke also includes [dashboard search, filters and period comparisons](docs/DASHBOARD-EVOLUTION.md), [batch task assessments with separate planning models](docs/CAPABILITY-ROUTING.md), and [Windows sandbox preflight and process supervision](docs/WINDOWS-RUNNER-VALIDATION.md). Existing routing settings remain authoritative. See the [changelog](CHANGELOG.md) and the [harness integration guide](docs/HARNESSES.md) for limitations and setup.
+**New in 1.15.0:** federated [Code Intelligence](docs/CODE-INTELLIGENCE.md) composes Graft, Graphify and Serena behind one Yoke-controlled MCP surface, with structural and semantic evidence, content-addressed snapshots, partial-coverage reporting and isolated edit previews. It is opt-in: use `off` for the unchanged legacy path, `shadow` for read-only canaries, or `active` for previews and approved edits. The [1.14.0 dashboard overhaul](docs/DASHBOARD-OVERHAUL.md) and first-class [OpenCode, Kilo and Pi integrations](docs/HARNESSES.md) remain available. See the [changelog](CHANGELOG.md) and [Code Intelligence guide](docs/CODE-INTELLIGENCE.md) for setup and limitations.
 
 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
@@ -208,10 +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=] [--decision-policy=] [--loop\|--no-loop] [--routing\|--no-routing] [--model-provider=deepseek,kimi]` | Shared setup for all seven harnesses; optional DeepSeek/Kimi API profiles run through Qwen | `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 seven 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] [--loop]` | Install/update the harness for the selected agents, non-destructively | `0` |
+| `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 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 |
@@ -852,7 +855,7 @@ Yoke's guardrails are **mechanical, not advisory** — the loop blocks on a dirt
 
 ## 🧠 Choose your code-graph
 
-`yoke retrofit --code-graph=graphify|serena` (default `graphify`, remembered per project). The `yoke-retrofit` skill asks and recommends based on the project.
+`yoke retrofit --code-graph=graphify|serena` (default `graphify`, remembered per project) selects the legacy single graph. For complete code intelligence, enable the federated facade with `yoke retrofit --code-intelligence=active` (or `shadow` for a read-only canary). See the [Code Intelligence guide](docs/CODE-INTELLIGENCE.md).
 
 | | **graphify** | **Serena** |
 |---|---|---|
@@ -862,6 +865,8 @@ Yoke's guardrails are **mechanical, not advisory** — the loop blocks on a dirt
 | Best for | rapid exploration / migration / onboarding | systematic refactoring in typed codebases |
 | Caveat | heuristic edges; static index can go stale | one language server per language |
 
+The federated mode composes both structural and semantic evidence and adds Graphify's architecture/document graph. It exposes one Yoke-controlled MCP surface, content-addressed snapshots, partial-coverage reporting and isolated edit previews; the legacy `codeGraph` setting remains valid and unchanged when code intelligence is `off`.
+
 ## 🪙 Token efficiency
 
 Yoke attacks tokens on two complementary surfaces:
@@ -903,6 +908,7 @@ canon/            # the source of truth — harness-agnostic
   AGENTS.md  skills/  policy/  loop/  tools/  manifest.yaml
 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
   loop/           # prd · gates · runner · verify · git/worktree · loop · run-command · lock · cleanup
@@ -925,7 +931,7 @@ release provenance.
 ## 🧪 Development
 
 ```bash
-npm test          # vitest (1258 tests)
+npm test          # vitest (1283 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,5 +1,5 @@
 name: yoke-canon
-version: 1.14.0
+version: 1.15.1
 agents: [claude, codex, gemini, qwen, opencode, kilo, pi]
 skills:
   - { id: tdd, path: skills/tdd, 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/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;

package/dist/agents/providers.js

@@ -45,6 +45,9 @@ const argsFor = (agent, permissions) => {
 };
 export function buildProviderInvocation(agent, prompt, cwd, permissions = 'safe', selection = {}, output = {}) {
     const parsedSelection = ModelSelectionSchema.parse(selection);
+    if (['opencode', 'kilo', 'pi'].includes(agent) && parsedSelection.reasoningEffort && parsedSelection.variant && parsedSelection.reasoningEffort !== parsedSelection.variant) {
+        throw new Error(`${agent} reasoningEffort and variant selections must match`);
+    }
     if (agent === 'gemini' && parsedSelection.bare)
         throw new Error('Gemini does not support the bare startup selection');
     if (agent === 'gemini' && parsedSelection.reasoningEffort)
@@ -106,7 +109,7 @@ export function buildProviderInvocation(agent, prompt, cwd, permissions = 'safe'
             args.push('--thinking', parsedSelection.reasoningEffort);
     }
     if (parsedSelection.variant) {
-        if (agent === 'opencode' || agent === 'kilo')
+        if ((agent === 'opencode' || agent === 'kilo') && !parsedSelection.reasoningEffort)
             args.push('--variant', parsedSelection.variant);
         else if (agent === 'pi') {
             if (parsedSelection.reasoningEffort && parsedSelection.reasoningEffort !== parsedSelection.variant)

package/dist/agents/supervision.js

@@ -36,6 +36,8 @@ export function inspectProviderEvent(line) {
             return { failure: 'provider-terminal-error' };
     }
     return { progress: (event.type === 'item.completed' && ((item?.type === 'command_execution' && item.exit_code === 0) || (item?.type === 'file_change' && item.status === 'completed')))
+            || (event.type === 'tool_execution_end' && event.isError === false)
+            || (event.type === 'tool_use' && event.part?.type === 'tool' && event.part.state?.status === 'completed')
             || (event.type === 'tool_result' && event.status === 'success')
             || (event.type === 'user' && Array.isArray(event.message?.content) && event.message.content.some((part) => part.type === 'tool_result' && part.is_error === false)) };
 }

package/dist/agents/telemetry.js

@@ -1,3 +1,4 @@
+import { createPiTelemetry } from './pi-telemetry.js';
 const finite = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
 function parseJson(value) {
     try {
@@ -32,15 +33,21 @@ export function parseProviderResult(agent, output) {
     if (agent === 'qwen')
         return parseQwenResult(output);
     const fragments = [];
+    let structuredResult;
     for (const line of output.split(/\r?\n/u)) {
         const parsed = parseJson(line);
         if (!parsed.ok || !isRecord(parsed.value))
             continue;
         const event = parsed.value;
+        if (agent === 'claude' && event.parent_tool_use_id != null)
+            continue;
+        if (event.type === 'error' || event.type === 'turn.failed' ||
+            (event.type === 'result' && (event.is_error === true || event.status === 'error')))
+            return null;
         switch (agent) {
             case 'claude':
                 if (event.type === 'result' && directMachineResult(event.structured_output) !== undefined)
-                    return event.structured_output;
+                    structuredResult = event.structured_output;
                 if (event.type === 'result' && typeof event.result === 'string')
                     fragments.push(event.result);
                 break;
@@ -63,6 +70,8 @@ export function parseProviderResult(agent, output) {
             }
             case 'pi':
                 if (event.type === 'message_end' && isRecord(event.message) && event.message.role === 'assistant') {
+                    if (event.message.stopReason === 'error' || event.message.stopReason === 'aborted')
+                        return null;
                     const text = textContent(event.message.content);
                     if (text)
                         fragments.push(text);
@@ -70,6 +79,8 @@ export function parseProviderResult(agent, output) {
                 break;
         }
     }
+    if (structuredResult !== undefined)
+        return structuredResult;
     const joined = parseJson(fragments.join(''));
     if (joined.ok) {
         const direct = directMachineResult(joined.value);
@@ -115,6 +126,15 @@ function parseQwenResult(output) {
     return candidate;
 }
 export function parseProviderTelemetry(agent, lines) {
+    if (agent === 'pi') {
+        const accumulator = createPiTelemetry();
+        for (const line of lines) {
+            const parsed = parseJson(line);
+            if (parsed.ok && isRecord(parsed.value))
+                accumulator.consume(parsed.value);
+        }
+        return accumulator.finish();
+    }
     let inputTokens;
     let cachedInputTokens;
     let cacheWriteInputTokens;
@@ -126,7 +146,6 @@ export function parseProviderTelemetry(agent, lines) {
     const harnessTotals = agent === 'opencode' || agent === 'kilo'
         ? { input: 0, output: 0, cached: 0, cacheWrite: 0, reasoning: 0, cost: 0, hasInput: false, hasOutput: false, hasCached: false, hasCacheWrite: false, hasReasoning: false, hasCost: false }
         : undefined;
-    let piUsage;
     for (const line of lines) {
         let parsed;
         try {
@@ -138,7 +157,7 @@ export function parseProviderTelemetry(agent, lines) {
         if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
             continue;
         const event = parsed;
-        if (agent === 'qwen' && event.parent_tool_use_id != null)
+        if ((agent === 'qwen' || agent === 'claude') && event.parent_tool_use_id != null)
             continue;
         const message = event.message && typeof event.message === 'object' ? event.message : undefined;
         const stats = event.stats && typeof event.stats === 'object' ? event.stats : undefined;
@@ -177,8 +196,6 @@ export function parseProviderTelemetry(agent, lines) {
                 harnessTotals.hasCost = true;
             }
         }
-        if (agent === 'pi' && event.type === 'message_update' && event.usage && typeof event.usage === 'object')
-            piUsage = event.usage;
         const usage = (event.usage && typeof event.usage === 'object'
             ? event.usage
             : message?.usage && typeof message.usage === 'object'
@@ -247,26 +264,6 @@ export function parseProviderTelemetry(agent, lines) {
         if (typeof eventModel === 'string' && eventModel && reportedModels.length <= 1)
             model = eventModel;
     }
-    if (piUsage) {
-        const piInput = finite(piUsage.input);
-        const piOutput = finite(piUsage.output);
-        const piCached = finite(piUsage.cacheRead);
-        const piCacheWrite = finite(piUsage.cacheWrite);
-        const piReasoning = finite(piUsage.reasoning);
-        const piCost = isRecord(piUsage.cost) ? finite(piUsage.cost.total) : undefined;
-        if (piInput !== undefined)
-            inputTokens = piInput;
-        if (piOutput !== undefined)
-            outputTokens = piOutput;
-        if (piCached !== undefined)
-            cachedInputTokens = piCached;
-        if (piCacheWrite !== undefined)
-            cacheWriteInputTokens = piCacheWrite;
-        if (piReasoning !== undefined)
-            reasoningOutputTokens = piReasoning;
-        if (piCost !== undefined)
-            totalCostUsd = piCost;
-    }
     if (harnessTotals) {
         if (harnessTotals.hasInput)
             inputTokens = harnessTotals.input;