@hecer/yoke 1.11.0 → 1.13.0

package/docs/PUBLISHING.md

@@ -1,114 +1,114 @@
-# Publishing channels — status & playbook
-
-Where Yoke is published, and how each channel gets updated. (Reviewed 2026-08-20.)
-
-## Live
-
-| Channel | How | Update path |
-|---|---|---|
-| **npm** — [`@hecer/yoke`](https://www.npmjs.com/package/@hecer/yoke) | GitHub OIDC trusted publishing | every release |
-| **GitHub** — [HECer/yoke](https://github.com/HECer/yoke) | push + tag + GitHub Release | every release |
-| **Claude Code plugin (self-marketplace)** | `.claude-plugin/plugin.json` + `marketplace.json` in this repo; users: `/plugin marketplace add HECer/yoke` → `/plugin install yoke@yoke` | bump `version` in `plugin.json` |
-| **Gemini CLI extension** | `gemini-extension.json` + `GEMINI-EXTENSION.md` at repo root; users: `gemini extensions install https://github.com/HECer/yoke` | bump `version` in the manifest |
-| **Codex project skills** | `npx @hecer/yoke setup .` writes the canon to `.agents/skills/` plus native Codex config/hooks; `.codex-plugin/plugin.json` is bundled for plugin-capable hosts | every npm release |
-
-## GitHub release (required, not just a tag)
-
-Before the release commit, update every user-facing version and README statistic, then require the
-same checks npm will run:
-
-```bash
-npm run docs:update
-npm run docs:check
-npm run prepublishOnly
-```
-
-`docs:update` synchronizes the README's package version, test count, skill count, and supported
-agents from `package.json`, Vitest discovery, and `canon/manifest.yaml`. The version must also be
-kept in sync in `package-lock.json`, `canon/manifest.yaml`, `.claude-plugin/plugin.json`,
-`.codex-plugin/plugin.json`, and `gemini-extension.json`.
-
-A pushed tag appears under **Tags**, but GitHub only shows an entry under **Releases** after a
-release object is created. Use this idempotent check after the version commit reaches `main`:
-
-```bash
-set -euo pipefail
-VERSION=1.6.2
-TARGET=$(git rev-parse HEAD)
-git fetch --tags origin
-
-REMOTE=$(git ls-remote origin "refs/tags/v$VERSION^{}" | awk 'NR == 1 { print $1 }')
-if [ -z "$REMOTE" ]; then
-  REMOTE=$(git ls-remote origin "refs/tags/v$VERSION" | awk 'NR == 1 { print $1 }')
-fi
-if [ -n "$REMOTE" ] && [ "$REMOTE" != "$TARGET" ]; then
-  echo "origin/v$VERSION already points at a different commit" >&2
-  exit 1
-fi
-
-if git rev-parse -q --verify "refs/tags/v$VERSION" >/dev/null; then
-  test "$(git rev-list -n 1 "v$VERSION")" = "$TARGET" || {
-    echo "v$VERSION already points at a different commit" >&2
-    exit 1
-  }
-else
-  git tag "v$VERSION"
-fi
-git push origin "refs/tags/v$VERSION"
-gh release view "v$VERSION" >/dev/null 2>&1 || \
-  gh release create "v$VERSION" --title "Yoke $VERSION" --generate-notes
-```
-
-Verify both surfaces before publishing npm: `gh release view "v$VERSION"` and
-`npm view @hecer/yoke version`.
-
-## npm trusted publishing
-
-The `publish-npm.yml` workflow publishes a stable package automatically when a GitHub Release is
-published. It checks out that exact tag, requires the tag to match the version in `package.json`,
-reruns `prepublishOnly` through `npm publish`, and skips a version that already exists. GitHub OIDC
-provides a short-lived publishing identity; no `NPM_TOKEN` repository secret is used. npm adds
-provenance automatically for this public repository.
-
-One package-owner setup step is required on npmjs.com under the `@hecer/yoke` package settings:
-
-- Publisher: GitHub Actions
-- Organization or user: `HECer`
-- Repository: `yoke`
-- Workflow filename: `publish-npm.yml`
-- Environment: leave empty
-- Allowed action: `npm publish`
-
-After the trusted publisher exists, the next GitHub Release publishes automatically. To publish an
-already-created release such as `v1.6.1`, run the **Publish npm** workflow manually and provide that
-existing tag. The workflow refuses tags without a published GitHub Release and refuses tag/version
-mismatches. After the first successful OIDC publish, disable traditional token publishing and revoke
-obsolete automation tokens in npm package settings.
-
-## Submitted / pending
-
-| Channel | How | Status |
-|---|---|---|
-| **Gemini extensions gallery** (geminicli.com/extensions) | automatic daily crawl: needs `gemini-extension.json` at repo root + `gemini-cli-extension` repo topic — both done | wait for crawler |
-| **Anthropic community plugin directory** (`claude-community`, surfaced in `/plugin > Discover`) | form at **platform.claude.com/plugins/submit** (Console account, Developer role; submit the public repo URL; `claude plugin validate` runs in their pipeline — passes locally). After approval: pinned to a commit SHA, CI auto-bumps on push, catalog syncs nightly | **needs a human login** — see below |
-
-### Anthropic directory submission (manual step)
-
-1. Log in at https://platform.claude.com (free Console account is enough; role Developer+).
-2. Open https://platform.claude.com/plugins/submit
-3. Submit the public repo: `https://github.com/HECer/yoke`
-4. Suggested description: *"Cross-agent coding harness: one curated skill canon (TDD,
-   brainstorming → spec → plan, systematic debugging, cross-model review, design
-   verification) plus mechanical safety gates and an autonomous loop via the yoke CLI."*
-5. Category: development. Plugin name (immutable): `yoke`.
-
-## Worth doing later (community lists, PR/issue-based)
-
-- **awesome-claude-code** (hesreallyhim) — issue-form only, explicitly human-submitted, no PRs.
-- **ComposioHQ/awesome-claude-plugins** — PR per template (high merge latency).
-- **davila7/claude-code-templates** (aitmpl.com) — PR per CONTRIBUTING.md.
-- **Codex plugin directory** — public directory submission remains a separate channel. Codex
-  users do not need it: the npm setup path installs native project skills deterministically.
-- Auto-crawled directories (crossaitools.com etc.) pick the repo up on their own once the
-  marketplace manifest exists.
-- Launch channels (Product Hunt, Show HN, r/ClaudeAI, r/ClaudeCode) — deliberate, human-led.
+# Publishing channels — status & playbook
+
+Where Yoke is published, and how each channel gets updated. (Reviewed 2026-08-20.)
+
+## Live
+
+| Channel | How | Update path |
+|---|---|---|
+| **npm** — [`@hecer/yoke`](https://www.npmjs.com/package/@hecer/yoke) | GitHub OIDC trusted publishing | every release |
+| **GitHub** — [HECer/yoke](https://github.com/HECer/yoke) | push + tag + GitHub Release | every release |
+| **Claude Code plugin (self-marketplace)** | `.claude-plugin/plugin.json` + `marketplace.json` in this repo; users: `/plugin marketplace add HECer/yoke` → `/plugin install yoke@yoke` | bump `version` in `plugin.json` |
+| **Gemini CLI extension** | `gemini-extension.json` + `GEMINI-EXTENSION.md` at repo root; users: `gemini extensions install https://github.com/HECer/yoke` | bump `version` in the manifest |
+| **Codex project skills** | `npx @hecer/yoke setup .` writes the canon to `.agents/skills/` plus native Codex config/hooks; `.codex-plugin/plugin.json` is bundled for plugin-capable hosts | every npm release |
+
+## GitHub release (required, not just a tag)
+
+Before the release commit, update every user-facing version and README statistic, then require the
+same checks npm will run:
+
+```bash
+npm run docs:update
+npm run docs:check
+npm run prepublishOnly
+```
+
+`docs:update` synchronizes the README's package version, test count, skill count, and supported
+agents from `package.json`, Vitest discovery, and `canon/manifest.yaml`. The version must also be
+kept in sync in `package-lock.json`, `canon/manifest.yaml`, `.claude-plugin/plugin.json`,
+`.codex-plugin/plugin.json`, and `gemini-extension.json`.
+
+A pushed tag appears under **Tags**, but GitHub only shows an entry under **Releases** after a
+release object is created. Use this idempotent check after the version commit reaches `main`:
+
+```bash
+set -euo pipefail
+VERSION=1.6.2
+TARGET=$(git rev-parse HEAD)
+git fetch --tags origin
+
+REMOTE=$(git ls-remote origin "refs/tags/v$VERSION^{}" | awk 'NR == 1 { print $1 }')
+if [ -z "$REMOTE" ]; then
+  REMOTE=$(git ls-remote origin "refs/tags/v$VERSION" | awk 'NR == 1 { print $1 }')
+fi
+if [ -n "$REMOTE" ] && [ "$REMOTE" != "$TARGET" ]; then
+  echo "origin/v$VERSION already points at a different commit" >&2
+  exit 1
+fi
+
+if git rev-parse -q --verify "refs/tags/v$VERSION" >/dev/null; then
+  test "$(git rev-list -n 1 "v$VERSION")" = "$TARGET" || {
+    echo "v$VERSION already points at a different commit" >&2
+    exit 1
+  }
+else
+  git tag "v$VERSION"
+fi
+git push origin "refs/tags/v$VERSION"
+gh release view "v$VERSION" >/dev/null 2>&1 || \
+  gh release create "v$VERSION" --title "Yoke $VERSION" --generate-notes
+```
+
+Verify both surfaces before publishing npm: `gh release view "v$VERSION"` and
+`npm view @hecer/yoke version`.
+
+## npm trusted publishing
+
+The `publish-npm.yml` workflow publishes a stable package automatically when a GitHub Release is
+published. It checks out that exact tag, requires the tag to match the version in `package.json`,
+reruns `prepublishOnly` through `npm publish`, and skips a version that already exists. GitHub OIDC
+provides a short-lived publishing identity; no `NPM_TOKEN` repository secret is used. npm adds
+provenance automatically for this public repository.
+
+One package-owner setup step is required on npmjs.com under the `@hecer/yoke` package settings:
+
+- Publisher: GitHub Actions
+- Organization or user: `HECer`
+- Repository: `yoke`
+- Workflow filename: `publish-npm.yml`
+- Environment: leave empty
+- Allowed action: `npm publish`
+
+After the trusted publisher exists, the next GitHub Release publishes automatically. To publish an
+already-created release such as `v1.6.1`, run the **Publish npm** workflow manually and provide that
+existing tag. The workflow refuses tags without a published GitHub Release and refuses tag/version
+mismatches. After the first successful OIDC publish, disable traditional token publishing and revoke
+obsolete automation tokens in npm package settings.
+
+## Submitted / pending
+
+| Channel | How | Status |
+|---|---|---|
+| **Gemini extensions gallery** (geminicli.com/extensions) | automatic daily crawl: needs `gemini-extension.json` at repo root + `gemini-cli-extension` repo topic — both done | wait for crawler |
+| **Anthropic community plugin directory** (`claude-community`, surfaced in `/plugin > Discover`) | form at **platform.claude.com/plugins/submit** (Console account, Developer role; submit the public repo URL; `claude plugin validate` runs in their pipeline — passes locally). After approval: pinned to a commit SHA, CI auto-bumps on push, catalog syncs nightly | **needs a human login** — see below |
+
+### Anthropic directory submission (manual step)
+
+1. Log in at https://platform.claude.com (free Console account is enough; role Developer+).
+2. Open https://platform.claude.com/plugins/submit
+3. Submit the public repo: `https://github.com/HECer/yoke`
+4. Suggested description: *"Cross-agent coding harness: one curated skill canon (TDD,
+   brainstorming → spec → plan, systematic debugging, cross-model review, design
+   verification) plus mechanical safety gates and an autonomous loop via the yoke CLI."*
+5. Category: development. Plugin name (immutable): `yoke`.
+
+## Worth doing later (community lists, PR/issue-based)
+
+- **awesome-claude-code** (hesreallyhim) — issue-form only, explicitly human-submitted, no PRs.
+- **ComposioHQ/awesome-claude-plugins** — PR per template (high merge latency).
+- **davila7/claude-code-templates** (aitmpl.com) — PR per CONTRIBUTING.md.
+- **Codex plugin directory** — public directory submission remains a separate channel. Codex
+  users do not need it: the npm setup path installs native project skills deterministically.
+- Auto-crawled directories (crossaitools.com etc.) pick the repo up on their own once the
+  marketplace manifest exists.
+- Launch channels (Product Hunt, Show HN, r/ClaudeAI, r/ClaudeCode) — deliberate, human-led.

package/docs/QWEN-MODEL-SUPPORT.md

@@ -0,0 +1,142 @@
+# Qwen Code, DeepSeek and Kimi
+
+Validated against Qwen Code 0.23.0 on 2026-09-08. Yoke's execution provider remains
+`qwen`: Qwen Code supplies the coding tools and connects to the selected model API.
+DeepSeek and Kimi do not require imaginary `deepseek` or `kimi` executables.
+
+## Setup
+
+Install Qwen Code and configure/authenticate the account you want to use. For an
+existing Qwen Code model configuration:
+
+```sh
+yoke setup . --yes --agent=qwen
+```
+
+The default `qwen-standard` routing worker uses Qwen Code's configured model. It
+no longer assumes an account can access four particular Qwen API models or calls
+the same model different intelligence tiers. Existing custom workers are kept.
+Use `--routing-preset` to explicitly reset old generated workers; otherwise edit
+`.yoke/config.yaml` to retain your own measured profiles. A single standard profile
+cannot satisfy stronger prepared assessments: add suitable explicit workers before
+running those tasks, or choose an appropriate configured routing fallback.
+
+For the opt-in DeepSeek and/or Kimi API presets:
+
+```sh
+yoke setup . --yes --agent=qwen --runner=qwen --model-provider=deepseek,kimi
+```
+
+Provide `DEEPSEEK_API_KEY` and `MOONSHOT_API_KEY` in the environment of the Qwen
+process. Setup stores only their **variable names**, never key values, in
+`.qwen/settings.json`. These are separate API accounts/billing; the Kimi preset
+uses Moonshot's platform API, not Kimi Code subscription credentials. Select only
+providers whose credentials you have configured. Setup does not contact either API
+or prove authentication. Commit the generated project configuration and skills
+before using isolated Git worktrees so the worker receives them.
+
+| Preset | Models installed | Endpoint | Key variable |
+| --- | --- | --- | --- |
+| `deepseek` | `deepseek-v4-flash`, `deepseek-v4-pro` | `https://api.deepseek.com/v1` | `DEEPSEEK_API_KEY` |
+| `kimi` | `kimi-k2.6`, `kimi-k2.7-code`, `kimi-k3` | `https://api.moonshot.ai/v1` | `MOONSHOT_API_KEY` |
+
+New API workers use `openai::MODEL` in Yoke. The adapter translates this to Qwen's
+`--auth-type openai --model MODEL`, selecting the model's endpoint and environment
+key together even when Qwen's default login uses another protocol. Plain model IDs
+keep their existing behavior. The same explicit selector syntax supports `anthropic`,
+`gemini`, `vertex-ai` and `qwen-oauth` when configured in Qwen Code; only DeepSeek and
+Kimi have new automatic API presets.
+
+Example runner or routing worker:
+
+```yaml
+runner:
+  agent: qwen
+  model: openai::kimi-k3
+routing:
+  enabled: true
+  strategy: capability
+  maxCandidates: 3
+  workers:
+    - id: deepseek-standard
+      agent: qwen
+      model: openai::deepseek-v4-flash
+      tier: standard
+      costTier: low
+      capabilities: [implementation]
+    - id: kimi-frontier
+      agent: qwen
+      model: openai::kimi-k3
+      tier: frontier
+      costTier: high
+      capabilities: [implementation]
+```
+
+Setup preserves existing endpoint/key/generation settings for a matching model ID,
+existing custom worker IDs and an existing runner unless explicitly changed. It
+adds missing preset entries and creates backups for changed settings. Regional or
+self-hosted endpoints can be configured directly in Qwen's `modelProviders.openai`.
+Avoid ambiguous duplicate model IDs across endpoints when selecting with `--model`.
+Worker tiers and cost tiers are editable starting hypotheses, not measured rankings
+or prices. Yoke accepts up to 32 configured profiles; this does not increase the
+parallel execution limit.
+
+## Reasoning and permissions
+
+Yoke does not pass a nonexistent Qwen `--effort` flag. Configure model-specific
+reasoning in the matching Qwen `modelProviders` entry's `generationConfig` using
+Qwen's supported parameters. Qwen Code owns streaming, tool execution and replay
+of `reasoning_content` between tool calls. Supported thinking controls differ by
+model and endpoint; no identical thinking levels or benchmark quality is implied.
+
+- `safe`: `--approval-mode auto-edit --sandbox --allowed-tools run_shell_command`.
+  The explicit shell allowance enables headless test/build commands inside the
+  required Qwen sandbox. It is not a command-by-command human approval flow.
+  A working Qwen sandbox backend must be installed; Yoke never silently removes it.
+- `read-only`: plan approval mode plus sandbox, without the shell allowance.
+- `unsafe`: explicit `--yolo`, with no sandbox requested by Yoke.
+- When Yoke owns worker slots, the Qwen `agent`/legacy `task`, `create_sub_session`,
+  `team_create` and `send_message` tools are excluded. This controls native
+  delegation tools, not arbitrary programs invoked from a permitted shell.
+- `bare`, `reasoningEffort` and enabling native multi-agent execution remain
+  explicitly unsupported selections for Qwen.
+
+The RTK hook uses native `PreToolUse` denial plus a retry instruction for simple,
+supported commands. Qwen's documented `updatedInput` is not consumed by the
+0.23.0 execution path, so the hook does not claim transparent argument rewriting.
+It never executes commands or grants permission. Existing RTK commands and complex
+shell expressions are left alone; the generated context also supplies RTK guidance.
+RTK must be installed in the execution environment, including the sandbox.
+Re-running setup/retrofit removes only the obsolete Yoke `BeforeTool` entry,
+preserves unrelated hooks and backs up the original settings.
+
+## Validation and limits
+
+Regression tests cover native result/text/structured-result envelopes, nested
+results, failures, cumulative token/model statistics, safe invocation and native
+worker exclusions, manual skill policy, host/project detection, automatic review
+selection, hook migration, all-agent configuration and idempotent API setup.
+
+Reproduce the manual transport check after building:
+
+```sh
+node scripts/qwen-contract-smoke.mjs /path/to/installed/qwen-code/cli-entry.js
+```
+
+A manual contract smoke test used the **real Qwen Code 0.23.0 CLI** against a local
+synthetic OpenAI-compatible SSE server. Qwen, DeepSeek and Kimi model selections
+completed a read-file tool roundtrip, preserved reasoning content in the subsequent
+request and returned parseable results with cumulative token usage. This local
+transport check used explicit unsafe mode only in a scratch fixture; it does not
+validate a real provider account, model quality, billing, rate limits, Windows or
+a production sandbox backend. No authenticated provider benchmark was performed.
+
+## Primary references
+
+- [Qwen headless output and permissions](https://qwenlm.github.io/qwen-code-docs/en/users/features/headless/)
+- [Qwen model providers and generation configuration](https://qwenlm.github.io/qwen-code-docs/en/users/configuration/model-providers/)
+- [Qwen source](https://github.com/QwenLM/qwen-code): native output adapters,
+  `toolHookTriggers.ts`, `coreToolScheduler.ts`, configuration and provider presets.
+- [DeepSeek API models and endpoints](https://api-docs.deepseek.com/)
+- [DeepSeek thinking tool calls](https://api-docs.deepseek.com/guides/thinking_mode/)
+- [Kimi API models and endpoints](https://platform.kimi.ai/docs/overview)

package/docs/VERIFIED-PROJECTS-VALIDATION.md

@@ -1,29 +1,29 @@
-# Local implementation validation
-
-This record covers the September 5, 2026 source implementation, not a published release or a competitive benchmark.
-
-## Review and behavioral checks
-
-Independent specification and code-quality reviews identified and drove fixes for mutable acceptance, stale goal success, lost interrupted-attempt accounting, orphaned processes, incomplete workspace identity, missing final protection gates, restart-lost routing escalation, unnecessary provider installation requirements, mixed time accounting, partial cost reporting and linked pause files.
-
-Behavioral regressions cover protected checks, source mutation during verification, truthful unmapped requirements, goal completion from real application changes, tampered tests, bounded retries, interruption recovery, source-bound worktree continuation, routing without controller calls, persisted escalation, deterministic actions, context budgets, dependency/write-scope scheduling, unknown estimates, phase/attempt evidence, local registry and HTTP security boundaries.
-
-Final full suite: **122 test files passed; 1,098 tests passed, 2 skipped (1,100 total)** with a 20-second test timeout on Windows. This timeout accommodates the real-Git integration tests; the earlier baseline already had a 5-second timeout that passed in isolation. TypeScript build/lint, canon validation, release-metadata check and package dry run passed. The package check explicitly confirmed the compiled CLI, check/goal/dashboard modules and Gemini RTK hook are included.
-
-## Browser and provider limits
-
-The local dashboard was rendered and inspected in Chrome on desktop and at 390px mobile width. HTTP tests exercise registered project reads, corrupt/missing/oversized data, hostile Host/Origin headers, token rejection and authorized pause. Browser extension click automation timed out, so a complete interactive click walkthrough is not claimed.
-
-Provider invocation/stream/parser/hook tests are local automated tests. No authenticated cross-provider development benchmark was run. Model quality parity, price superiority, exact deadline prediction and achieved real-project token savings remain unmeasured. Native structured-output adapter support does not imply a provider-native goal API.
-
-## Provenance
-
-Read-only `audit-provenance` scans covered README, the new usage guide and dashboard page source. No supported C2PA structure was found; supported scans completed. README Unicode findings were emoji variation selectors, not evidence of a model watermark. No content or marks were removed.
-
-The audit's unanswered questions remain explicit:
-
-- Verification/trust: “No conforming verifier was supplied.” Cryptographic verification and a named signer trust chain are unknown.
-- Metadata privacy: the text format has no supported metadata parser in this analyzer; no privacy conclusion was produced.
-- Proprietary watermark detection: “Keyed model-level watermarks cannot be checked without the provider's key.” No authorship inference follows from absence of detected marks.
-
-The documentation and implementation were prepared with AI assistance and reviewed/tested as described above.
+# Local implementation validation
+
+This record covers the September 5, 2026 source implementation, not a published release or a competitive benchmark.
+
+## Review and behavioral checks
+
+Independent specification and code-quality reviews identified and drove fixes for mutable acceptance, stale goal success, lost interrupted-attempt accounting, orphaned processes, incomplete workspace identity, missing final protection gates, restart-lost routing escalation, unnecessary provider installation requirements, mixed time accounting, partial cost reporting and linked pause files.
+
+Behavioral regressions cover protected checks, source mutation during verification, truthful unmapped requirements, goal completion from real application changes, tampered tests, bounded retries, interruption recovery, source-bound worktree continuation, routing without controller calls, persisted escalation, deterministic actions, context budgets, dependency/write-scope scheduling, unknown estimates, phase/attempt evidence, local registry and HTTP security boundaries.
+
+Final full suite: **122 test files passed; 1,098 tests passed, 2 skipped (1,100 total)** with a 20-second test timeout on Windows. This timeout accommodates the real-Git integration tests; the earlier baseline already had a 5-second timeout that passed in isolation. TypeScript build/lint, canon validation, release-metadata check and package dry run passed. The package check explicitly confirmed the compiled CLI, check/goal/dashboard modules and Gemini RTK hook are included.
+
+## Browser and provider limits
+
+The local dashboard was rendered and inspected in Chrome on desktop and at 390px mobile width. HTTP tests exercise registered project reads, corrupt/missing/oversized data, hostile Host/Origin headers, token rejection and authorized pause. Browser extension click automation timed out, so a complete interactive click walkthrough is not claimed.
+
+Provider invocation/stream/parser/hook tests are local automated tests. No authenticated cross-provider development benchmark was run. Model quality parity, price superiority, exact deadline prediction and achieved real-project token savings remain unmeasured. Native structured-output adapter support does not imply a provider-native goal API.
+
+## Provenance
+
+Read-only `audit-provenance` scans covered README, the new usage guide and dashboard page source. No supported C2PA structure was found; supported scans completed. README Unicode findings were emoji variation selectors, not evidence of a model watermark. No content or marks were removed.
+
+The audit's unanswered questions remain explicit:
+
+- Verification/trust: “No conforming verifier was supplied.” Cryptographic verification and a named signer trust chain are unknown.
+- Metadata privacy: the text format has no supported metadata parser in this analyzer; no privacy conclusion was produced.
+- Proprietary watermark detection: “Keyed model-level watermarks cannot be checked without the provider's key.” No authorship inference follows from absence of detected marks.
+
+The documentation and implementation were prepared with AI assistance and reviewed/tested as described above.