@hecer/yoke 1.11.0 → 1.13.0

package/docs/DASHBOARD-EVOLUTION.md

@@ -1,33 +1,33 @@
-# Dashboard evolution
-
-The local dashboard is an actionable workspace for registered Yoke projects. It reads the same saved project, loop, goal, acceptance, and measurement data as the CLI. Project-controlled text is rendered through `textContent`, and the server remains bound to the loopback interface with same-origin authorization for pause requests.
-
-## Overview
-
-Project status is derived from both the saved goal and the latest loop report. A blocked or running loop is not hidden by a completed goal. When goal and loop states differ, the card displays both. Blocked, failed, paused, unavailable, and stale active reports need attention; those projects are ordered before active projects, followed by the remaining projects.
-
-Cards also show the reported current task and saved blocker reason when available, so the overview explains why a project needs attention before opening it.
-
-An active loop report more than 20 minutes old is labeled **unconfirmed**. This means Yoke has an old active report, not evidence that the process is still live. The overview can be searched by project name, canonical path, or goal objective and filtered to All, Active, or Needs attention. A no-match state explains the result and provides a clear action that resets both search and filter.
-
-## Durable navigation
-
-The URL hash stores the current screen, project, project tab, period, UTC grouping, and complete custom date range. Supported screens are the overview, workspace comparison, and project detail. Supported project tabs are Now, Usage & time, and Results; periods are 1, 7, 30, 90, or 365 days; groupings are day, week, or month. Custom dates must be real ISO calendar dates in chronological order and cover at most 366 inclusive days.
-
-Invalid hash state returns to the overview with the 30-day/day defaults. Browser back and forward, a page reload, and Refresh restore the validated state. Refresh reloads data without resetting the selected view or controls. Starting any navigation aborts earlier fetches and changes a request generation, so an older response cannot replace the current screen.
-
-The workspace comparison schedules at most three project analytics requests at once. If navigation changes, in-flight fetches are aborted and no additional obsolete project requests are scheduled. All projects and individual project links remain available in the navigation while viewing the comparison.
-
-## Usage comparisons
-
-Usage & time compares the selected period with the immediately preceding period of exactly the same duration. A single time boundary is captured before either analytics request is made. The comparison covers recorded input plus output tokens, recorded acceptance events, and reported cost.
-
-When the preceding value is zero, the dashboard describes no change or new recorded activity instead of calculating an infinite percentage. A cost percentage is shown only when both periods have fully measured cost. Otherwise the dashboard says the percentage is unavailable. Current and previous missing-usage coverage is displayed from calls with unknown usage and unmeasured attempts. Recorded portions remain recorded portions; missing tokens or charges are not estimated as zero.
-
-Charts and their tables include periods that contain recorded events. Empty UTC calendar buckets are omitted and the chart explains that a gap means no recorded activity, not a measured zero. Detailed provider/model/role, model timeline, task, and phase tables remain below the comparison.
-
-## Design findings and limitations
-
-Goal state and loop state describe different durable facts and need independent presentation. Freshness is also separate from state: a saved `running` value can become unconfirmed without being rewritten. Navigation state belongs in the URL because the dashboard has several independently useful views and time controls. Analytics fan-out needs cancellation as well as a concurrency bound because registered workspaces may contain many projects.
-
-The dashboard combines local saved evidence with process-identity checks for supervised providers (see [Windows runner validation](WINDOWS-RUNNER-VALIDATION.md)). Unverified process identity remains unknown. It does not reconstruct activity that predates retained measurements, estimate missing provider usage or prices, or turn requested model names into proof of models used. Parallel call durations can overlap, so summed call time is consumption intensity rather than generation speed. The 20-minute freshness threshold is a presentation rule, not a process-health guarantee. No provider performance benchmark is implied by these views.
+# Dashboard evolution
+
+The local dashboard is an actionable workspace for registered Yoke projects. It reads the same saved project, loop, goal, acceptance, and measurement data as the CLI. Project-controlled text is rendered through `textContent`, and the server remains bound to the loopback interface with same-origin authorization for pause requests.
+
+## Overview
+
+Project status is derived from both the saved goal and the latest loop report. A blocked or running loop is not hidden by a completed goal. When goal and loop states differ, the card displays both. Blocked, failed, paused, unavailable, and stale active reports need attention; those projects are ordered before active projects, followed by the remaining projects.
+
+Cards also show the reported current task and saved blocker reason when available, so the overview explains why a project needs attention before opening it.
+
+An active loop report more than 20 minutes old is labeled **unconfirmed**. This means Yoke has an old active report, not evidence that the process is still live. The overview can be searched by project name, canonical path, or goal objective and filtered to All, Active, or Needs attention. A no-match state explains the result and provides a clear action that resets both search and filter.
+
+## Durable navigation
+
+The URL hash stores the current screen, project, project tab, period, UTC grouping, and complete custom date range. Supported screens are the overview, workspace comparison, and project detail. Supported project tabs are Now, Usage & time, and Results; periods are 1, 7, 30, 90, or 365 days; groupings are day, week, or month. Custom dates must be real ISO calendar dates in chronological order and cover at most 366 inclusive days.
+
+Invalid hash state returns to the overview with the 30-day/day defaults. Browser back and forward, a page reload, and Refresh restore the validated state. Refresh reloads data without resetting the selected view or controls. Starting any navigation aborts earlier fetches and changes a request generation, so an older response cannot replace the current screen.
+
+The workspace comparison schedules at most three project analytics requests at once. If navigation changes, in-flight fetches are aborted and no additional obsolete project requests are scheduled. All projects and individual project links remain available in the navigation while viewing the comparison.
+
+## Usage comparisons
+
+Usage & time compares the selected period with the immediately preceding period of exactly the same duration. A single time boundary is captured before either analytics request is made. The comparison covers recorded input plus output tokens, recorded acceptance events, and reported cost.
+
+When the preceding value is zero, the dashboard describes no change or new recorded activity instead of calculating an infinite percentage. A cost percentage is shown only when both periods have fully measured cost. Otherwise the dashboard says the percentage is unavailable. Current and previous missing-usage coverage is displayed from calls with unknown usage and unmeasured attempts. Recorded portions remain recorded portions; missing tokens or charges are not estimated as zero.
+
+Charts and their tables include periods that contain recorded events. Empty UTC calendar buckets are omitted and the chart explains that a gap means no recorded activity, not a measured zero. Detailed provider/model/role, model timeline, task, and phase tables remain below the comparison.
+
+## Design findings and limitations
+
+Goal state and loop state describe different durable facts and need independent presentation. Freshness is also separate from state: a saved `running` value can become unconfirmed without being rewritten. Navigation state belongs in the URL because the dashboard has several independently useful views and time controls. Analytics fan-out needs cancellation as well as a concurrency bound because registered workspaces may contain many projects.
+
+The dashboard combines local saved evidence with process-identity checks for supervised providers (see [Windows runner validation](WINDOWS-RUNNER-VALIDATION.md)). Unverified process identity remains unknown. It does not reconstruct activity that predates retained measurements, estimate missing provider usage or prices, or turn requested model names into proof of models used. Parallel call durations can overlap, so summed call time is consumption intensity rather than generation speed. The 20-minute freshness threshold is a presentation rule, not a process-health guarantee. No provider performance benchmark is implied by these views.

package/docs/HARNESSES.md

@@ -0,0 +1,81 @@
+# OpenCode, Kilo and Pi
+
+Yoke 1.13.0 adds first-class adapters for OpenCode, Kilo and Pi coding agent. The adapters share Yoke's invocation, routing, review, quality, telemetry and retrofit contracts, while preserving the controls each harness actually provides.
+
+This is a CLI integration, not an authentication bundle. Install the selected harness, log in or configure its API provider, and verify it independently before starting a Yoke loop.
+
+## Setup and retrofit
+
+Select one of the new harnesses explicitly:
+
+```sh
+yoke setup . --yes --agent=opencode --runner=opencode
+yoke setup . --yes --agent=kilo --runner=kilo
+yoke setup . --yes --agent=pi --runner=pi
+```
+
+To add one to an existing project without changing the other generated artifacts:
+
+```sh
+yoke retrofit . --agent=opencode
+yoke retrofit . --agent=kilo
+yoke retrofit . --agent=pi
+```
+
+`--agent=all` now includes all seven supported harnesses. Retrofit is merge-aware for the native config files and backs up Yoke-managed overwrites under `.yoke/backup/`.
+
+## Native artifacts
+
+| Harness | Generated project artifacts | Native capabilities used by Yoke |
+|---|---|---|
+| OpenCode | `AGENTS.md`, `.opencode/skills/`, `opencode.json`, `.opencode/agents/yoke-reviewer.md` | `run --format json`, provider/model selection, variants, plan agent, local MCP servers |
+| Kilo | `AGENTS.md`, `.kilo/skills/`, `kilo.jsonc`, `.kilo/agents/yoke-reviewer.md` | OpenCode-compatible `run --format json`, provider/model selection, variants, plan agent, local MCP servers |
+| Pi | `AGENTS.md`, `.pi/skills/`, `.pi/settings.json` | JSONL mode, provider/model selection, thinking level, explicit tool allowlists |
+
+All three consume the shared `AGENTS.md` and `.yoke/context/*.md` context. OpenCode and Kilo also receive the configured local MCP servers from the Yoke code-graph choice. Pi has no native MCP or sub-agent layer, so its integration intentionally uses the portable skills and Yoke's own loop rather than pretending those features exist.
+
+## Provider, model and variant selection
+
+Yoke keeps the harness (`agent`) separate from the model provider (`provider`) and model identifier (`model`):
+
+```yaml
+runner:
+  agent: opencode
+  provider: openrouter
+  model: openai/gpt-5.6
+  variant: high
+```
+
+For OpenCode and Kilo this becomes `--model openrouter/openai/gpt-5.6 --variant high`. If no explicit provider is configured, a model string already in the harness's `provider/model` form is passed through unchanged. For Pi the equivalent is:
+
+```yaml
+runner:
+  agent: pi
+  provider: openai
+  model: gpt-5.6
+  reasoningEffort: high
+```
+
+This becomes `--provider openai --model gpt-5.6 --thinking high`. Pi calls `variant` and `reasoningEffort` the same underlying thinking-level selection; configuring both with different values is rejected.
+
+The same fields are available on routing workers and quality critic/repair roles. Routing evidence is keyed by harness, provider, model, reasoning effort and variant, so a model profile does not inherit another profile's success history.
+
+## Permission profiles and honest limits
+
+| Yoke profile | OpenCode / Kilo | Pi |
+|---|---|---|
+| `safe` | Headless `--auto` run; Yoke still verifies the resulting tree and gates the commit | `read,bash,edit,write` tool allowlist so the implementer can test and modify the project |
+| `read-only` | `--agent plan` plus JSON output | `read,grep,find,ls` only |
+| `unsafe` | Explicit `--dangerously-skip-permissions` | Harness default tool set; no Yoke-added allowlist |
+
+OpenCode, Kilo and Pi do not provide the same OS-level sandbox boundary as Codex or Gemini. The Yoke `safe` label therefore describes the selected harness controls and Yoke's mechanical gates, not a universal filesystem sandbox. Use `read-only` for review and do not use `unsafe` unless the project owner accepts the boundary.
+
+The Yoke loop disables native delegation where the harness exposes it, so Yoke's worker budget remains the authority. OpenCode and Kilo native agents are installed as a read-only reviewer artifact; Yoke's review runner still validates the structured verdict itself. Pi has no native sub-agent or plan mode by design.
+
+## Telemetry and validation limits
+
+Yoke parses OpenCode/Kilo JSON text events and `step_finish` token/cost events, and Pi `message_end` plus `message_update.usage` events. Missing provider events produce partial or unknown measurements; they are never reported as zero-cost success. Provider-reported model and usage remain provider claims.
+
+The release test suite covers argument construction, provider/variant propagation, routing and quality configuration, retrofit plans, host detection, JSON result parsing, and representative telemetry fixtures. It does not authenticate against every provider or claim equal model quality. Run a small project-specific smoke task after installing a harness and configuring credentials.
+
+Official CLI references: [OpenCode CLI](https://dev.opencode.ai/docs/cli), [OpenCode configuration](https://opencode.ai/docs/config), [OpenCode skills](https://opencode.ai/docs/skills), [Kilo CLI reference](https://github.com/Kilo-Org/kilocode/blob/main/packages/kilo-docs/pages/code-with-ai/platforms/cli-reference.md), and [Pi coding agent](https://github.com/badlogic/pi-mono/blob/main/packages/coding-agent/README.md).

package/docs/MIGRATING-TO-1.0.md

@@ -1,33 +1,33 @@
-# Migrating to Yoke 1.0
-
-Yoke 1.0 changes unsafe implicit behavior into explicit policy.
-
-## Runner permissions
-
-The default is `runner.permissions: safe`. Automation that intentionally requires a full
-sandbox bypass must pass `--unsafe` or configure `runner.permissions: unsafe`. Use
-`read-only` for planning and probing.
-
-## Reviews
-
-Reviewers write `.yoke/review-verdict.json`; Yoke validates and consumes it. The reviewer must
-differ from the implementer unless `--allow-self-review` is explicit. CI can add `--json`.
-
-## Commit ownership
-
-Yoke resolves identity before implementation. Configure it when Git has no identity:
-
-```yaml
-commit:
-  authorName: HECer
-  authorEmail: hec_er@web.de
-  allowCoAuthors: false
-```
-
-## PRDs, audit, and cleanup
-
-Existing PRDs remain valid. Optional `needs`, `area`, and `agent` fields add dependencies,
-collision domains, and affinity. Enable the story audit gate with `audit.enabled: true` and
-version suppressions with `suppressionsVersion: 1`.
-
-`yoke loop cleanup` now reports retained worktrees. Add `--remove-worktrees` for deletion.
+# Migrating to Yoke 1.0
+
+Yoke 1.0 changes unsafe implicit behavior into explicit policy.
+
+## Runner permissions
+
+The default is `runner.permissions: safe`. Automation that intentionally requires a full
+sandbox bypass must pass `--unsafe` or configure `runner.permissions: unsafe`. Use
+`read-only` for planning and probing.
+
+## Reviews
+
+Reviewers write `.yoke/review-verdict.json`; Yoke validates and consumes it. The reviewer must
+differ from the implementer unless `--allow-self-review` is explicit. CI can add `--json`.
+
+## Commit ownership
+
+Yoke resolves identity before implementation. Configure it when Git has no identity:
+
+```yaml
+commit:
+  authorName: HECer
+  authorEmail: hec_er@web.de
+  allowCoAuthors: false
+```
+
+## PRDs, audit, and cleanup
+
+Existing PRDs remain valid. Optional `needs`, `area`, and `agent` fields add dependencies,
+collision domains, and affinity. Enable the story audit gate with `audit.enabled: true` and
+version suppressions with `suppressionsVersion: 1`.
+
+`yoke loop cleanup` now reports retained worktrees. Add `--remove-worktrees` for deletion.

package/docs/MIGRATING-TO-1.1.md

@@ -1,27 +1,27 @@
-# Migrating to Yoke 1.1
-
-Yoke 1.1 makes Claude, Codex, and Gemini share the same setup, planning, runner-selection, and decision behavior.
-
-Run the setup wizard once in an existing project:
-
-```bash
-npx @hecer/yoke@1.1.0 setup .
-```
-
-It preserves existing Yoke configuration and asks for target agents, code graph, loop state, default runner, and decision mode. A non-interactive agent can apply explicit choices with `--yes`.
-
-The new config fields are optional and backward-compatible:
-
-```yaml
-runner:
-  agent: codex
-  permissions: safe
-loop:
-  enabled: true
-  timeoutMinutes: 30
-  decisionPolicy: critical  # auto | critical
-```
-
-`loop.onAmbiguity: resolve|abort` and `--on-ambiguity=` still work. Prefer `decisionPolicy` for new projects: `auto` resolves routine choices without asking; `critical` pauses only for high-impact decisions and continues after `yoke loop answer`. Resume restores the original isolation, review, runner, permissions, timeout, and policy flags instead of silently weakening the run. If the restart cannot begin, `yoke loop resume` retries from the request-bound state stored under Git's private state directory.
-
-Restart an already-open Codex task after retrofit if it does not discover the newly generated `.agents/skills/yoke-workflow/SKILL.md`.
+# Migrating to Yoke 1.1
+
+Yoke 1.1 makes Claude, Codex, and Gemini share the same setup, planning, runner-selection, and decision behavior.
+
+Run the setup wizard once in an existing project:
+
+```bash
+npx @hecer/yoke@1.1.0 setup .
+```
+
+It preserves existing Yoke configuration and asks for target agents, code graph, loop state, default runner, and decision mode. A non-interactive agent can apply explicit choices with `--yes`.
+
+The new config fields are optional and backward-compatible:
+
+```yaml
+runner:
+  agent: codex
+  permissions: safe
+loop:
+  enabled: true
+  timeoutMinutes: 30
+  decisionPolicy: critical  # auto | critical
+```
+
+`loop.onAmbiguity: resolve|abort` and `--on-ambiguity=` still work. Prefer `decisionPolicy` for new projects: `auto` resolves routine choices without asking; `critical` pauses only for high-impact decisions and continues after `yoke loop answer`. Resume restores the original isolation, review, runner, permissions, timeout, and policy flags instead of silently weakening the run. If the restart cannot begin, `yoke loop resume` retries from the request-bound state stored under Git's private state directory.
+
+Restart an already-open Codex task after retrofit if it does not discover the newly generated `.agents/skills/yoke-workflow/SKILL.md`.

package/docs/MIGRATING-TO-1.4.md

@@ -1,70 +1,70 @@
-# Migrating to Yoke 1.4
-
-Yoke 1.4 adds dependency-aware parallel workers, isolated candidate selection, and a reference-driven quality gauntlet. Existing projects remain serial and skip quality comparison unless you opt in.
-
-Upgrade and refresh generated harness files:
-
-```bash
-npm install -g @hecer/yoke@1.4.0
-yoke retrofit .
-```
-
-## Parallel execution
-
-Run dependency-ready stories concurrently with an explicit worker limit:
-
-```bash
-yoke loop run . --isolate --parallel=3
-```
-
-Parallel runs use isolated worktrees, leased claims, and a FIFO integration queue. Every candidate must pass its worker gates and the merged result must pass the project gates again. Adaptive routing is disabled during parallel and multi-candidate runs so each worker has one auditable provider identity.
-
-Use `--candidates=N` to produce and mechanically gate multiple implementations before an identity-blind comparison selects the winner. Candidate mode supports up to five candidates.
-
-## Reference-driven quality
-
-Quality remains disabled by default. A story must declare a trusted reference, candidate artifacts, and a rubric:
-
-```yaml
-quality:
-  reference: { name: approved-home, source: design/home.png, kind: file }
-  candidate: { kind: screenshots, paths: [.yoke/proof/STORY-1/home.png] }
-  rubric: Match the approved layout, hierarchy, spacing, and states.
-  policy: blocking
-```
-
-Project defaults can bound critic and repair work:
-
-```yaml
-quality:
-  enabled: false
-  policy: blocking
-  maxRounds: 3
-  maxMinutes: 60
-  consistencyChecks: 2
-  maxParallelCandidates: 2
-  critic: { agent: codex, model: gpt-5.6-sol }  # model required for --candidates
-  repair: { agent: claude }
-```
-
-Enable it for one run with:
-
-```bash
-yoke loop run . --quality
-```
-
-`consistencyChecks` is fixed at `2`: Yoke runs the swapped-label pair needed to detect identity-sensitive critic output. Advisory mode records both verdicts without blocking; blocking mode permits bounded repairs and reruns all mechanical gates.
-
-## Cleanup behavior
-
-`yoke loop cleanup` now retains Yoke-created worktrees by default so failed candidates remain inspectable. Remove them explicitly when no longer needed:
-
-```bash
-yoke loop cleanup . --remove-worktrees
-```
-
-Cleanup still reaps only provider processes recorded for the current project and removes stale loop locks. It never kills providers by machine-wide process name.
-
-## Review verdicts
-
-Review verdict files now require `schemaVersion: 1` and provenance containing the provider, provider-reported model, review role, prompt version, and permission profile. Custom reviewer integrations must emit the contract printed in the reviewer prompt. Legacy verdict files without this envelope fail closed.
+# Migrating to Yoke 1.4
+
+Yoke 1.4 adds dependency-aware parallel workers, isolated candidate selection, and a reference-driven quality gauntlet. Existing projects remain serial and skip quality comparison unless you opt in.
+
+Upgrade and refresh generated harness files:
+
+```bash
+npm install -g @hecer/yoke@1.4.0
+yoke retrofit .
+```
+
+## Parallel execution
+
+Run dependency-ready stories concurrently with an explicit worker limit:
+
+```bash
+yoke loop run . --isolate --parallel=3
+```
+
+Parallel runs use isolated worktrees, leased claims, and a FIFO integration queue. Every candidate must pass its worker gates and the merged result must pass the project gates again. Adaptive routing is disabled during parallel and multi-candidate runs so each worker has one auditable provider identity.
+
+Use `--candidates=N` to produce and mechanically gate multiple implementations before an identity-blind comparison selects the winner. Candidate mode supports up to five candidates.
+
+## Reference-driven quality
+
+Quality remains disabled by default. A story must declare a trusted reference, candidate artifacts, and a rubric:
+
+```yaml
+quality:
+  reference: { name: approved-home, source: design/home.png, kind: file }
+  candidate: { kind: screenshots, paths: [.yoke/proof/STORY-1/home.png] }
+  rubric: Match the approved layout, hierarchy, spacing, and states.
+  policy: blocking
+```
+
+Project defaults can bound critic and repair work:
+
+```yaml
+quality:
+  enabled: false
+  policy: blocking
+  maxRounds: 3
+  maxMinutes: 60
+  consistencyChecks: 2
+  maxParallelCandidates: 2
+  critic: { agent: codex, model: gpt-5.6-sol }  # model required for --candidates
+  repair: { agent: claude }
+```
+
+Enable it for one run with:
+
+```bash
+yoke loop run . --quality
+```
+
+`consistencyChecks` is fixed at `2`: Yoke runs the swapped-label pair needed to detect identity-sensitive critic output. Advisory mode records both verdicts without blocking; blocking mode permits bounded repairs and reruns all mechanical gates.
+
+## Cleanup behavior
+
+`yoke loop cleanup` now retains Yoke-created worktrees by default so failed candidates remain inspectable. Remove them explicitly when no longer needed:
+
+```bash
+yoke loop cleanup . --remove-worktrees
+```
+
+Cleanup still reaps only provider processes recorded for the current project and removes stale loop locks. It never kills providers by machine-wide process name.
+
+## Review verdicts
+
+Review verdict files now require `schemaVersion: 1` and provenance containing the provider, provider-reported model, review role, prompt version, and permission profile. Custom reviewer integrations must emit the contract printed in the reviewer prompt. Legacy verdict files without this envelope fail closed.