@hecer/yoke 1.10.0 → 1.11.0

package/docs/VERIFIED-PROJECTS.md

@@ -1,167 +1,167 @@
-# Verified projects, goals and measured execution
-
-Available in Yoke 1.7.0. These additions do not require a cloud account or replace your provider CLI. Model availability, reasoning controls, structured output and telemetry depend on the selected provider; unknown usage is never a measured zero. Live authenticated provider comparison and calibrated time/cost benchmarks remain separate validation work.
-
-## Check an existing project
-
-```sh
-yoke check .
-yoke check . --json
-yoke check . --requirement="Guest checkout completes"
-```
-
-Checks run without retrofit. Exit codes: `0` passed, `1` failed, `2` unverified or unavailable. A free-text requirement stays unverified until you map its behavior to an executable acceptance contract. Passing a project suite does not establish arbitrary product correctness.
-
-Create `.yoke/acceptance.yaml` with tests that inspect application behavior:
-
-```yaml
-version: 1
-protected:
-  - tests/acceptance/checkout.test.mjs
-  - tests/acceptance/helpers.mjs
-criteria:
-  - id: guest-checkout
-    text: A guest can complete checkout and receives one order confirmation.
-    commands:
-      - node --test tests/acceptance/checkout.test.mjs
-```
-
-List every local test helper, fixture and configuration file whose modification could weaken this contract. Paths must resolve inside the project. `yoke check . --protect` pins the manifest, listed files and existing package manifests/lockfiles outside the worker checkout. Autonomous goals require explicit protected test infrastructure and establish this pin automatically. Protection is change detection within the local execution model, not an OS security boundary against a hostile process using your account. Review the contract before running a goal.
-
-After intentionally editing protected tests, use `yoke check . --protect --refresh` to approve the new baseline. Ordinary checks and retries never refresh it. Source, acceptance and configuration identity are checked before and after verification; changed inputs invalidate evidence. Gitlinks/submodule directories currently fail closed because recursive identity is not implemented. Evidence is stored in `.yoke/checks/<id>.json`; it describes that checked snapshot and is not a permanent success certificate.
-
-## Durable goals across providers
-
-```sh
-yoke goal set . --objective="Finish guest checkout" --attempts=3 --minutes=30
-yoke goal run . --runner=codex
-yoke goal resume . --runner=claude --model=<installed-model-id>
-yoke goal resume . --runner=gemini --model=<installed-model-id>
-yoke goal status .
-yoke goal handoff .
-yoke goal pause .
-```
-
-Goals keep objective, attempts, failure context and check IDs in `.yoke/goal.json`. They share the story-loop lock. Each implementation attempt is followed by independent executable acceptance. A completed goal is checked again on a later run. Failed work stays in the project; goal execution itself does not commit or publish it. Goal handoff is readable context for native agent goal facilities; Yoke does not invent or call an undocumented native goal API.
-
-`--minutes` limits cumulative agent execution time. Verification is measured separately and commands retain their verification timeout. `--tokens=N` is a checkpoint budget: it prevents another attempt when measured consumption is exhausted or unknown, but cannot promise a hard token cap within a single provider call. An interrupted attempt is persisted before dispatch; recovery accounts for it conservatively and reconciles recorded provider processes before continuing. Unknown process ownership blocks execution. Pause takes effect at an attempt boundary; it does not instantly kill an in-flight agent.
-
-Explicitly extend total budgets without deleting history:
-
-```sh
-yoke goal budget . --attempts=5 --minutes=60
-yoke goal budget . --tokens=200000
-# Only if you deliberately want to remove the checkpoint token limit:
-yoke goal budget . --clear-token-budget
-```
-
-Unknown historical token usage cannot be made known by increasing its limit. Inspect interrupted work and keep that limitation visible.
-
-## Recover an isolated story
-
-Failed or paused isolated story worktrees are retained. Resume the same story with:
-
-```sh
-yoke loop run . --isolate --resume-worktree --parallel=1 --candidates=1
-```
-
-Yoke validates the registered worktree, repository, original target commit and PRD digest. Changed target/PRD state is refused; inspect retained edits and reconcile deliberately. This flag is for serial isolated recovery; parallel workers retain their existing coordinator lifecycle. `yoke loop cleanup` remains an explicit cleanup operation; inspect its removal flags before discarding unfinished work. Existing projects should rerun retrofit to add ignore entries for checks, events and goals.
-
-## Spend fewer model calls
-
-Add explicit project rules to `.yoke/config.yaml`:
-
-```yaml
-routing:
-  enabled: true
-  strategy: cost
-  maxCandidates: 2
-  workers:
-    - id: fast
-      agent: claude
-      model: <your-fast-model-id>
-      costTier: low
-      capabilities: [docs, tests]
-    - id: strong
-      agent: codex
-      model: <your-strong-model-id>
-      costTier: high
-      capabilities: [implementation]
-  rules:
-    - area: docs
-      worker: fast
-      escalateTo: strong
-```
-
-The first matching rule bypasses the routing controller. Its optional area and story ID selectors both have to match when supplied. Independent gate failure escalates the next attempt, including after loop restart; an unavailable or unknown worker falls back to the parent. Without an explicit escalation target the parent handles the failed rule. Other stories retain adaptive routing. Gate-driven routing observations are local and bounded when read. These are measured outcomes, not guarantees that a named inexpensive model can handle every task.
-
-For deterministic operations, configure exact executable arguments:
-
-```yaml
-actions:
-  - storyId: regenerate-types
-    file: node
-    args: [scripts/generate-types.mjs]
-    timeoutMs: 60000
-```
-
-Actions use no model, run without a shell, have bounded output/time and still pass the ordinary story gates before commit. They currently require serial execution with one candidate. On Windows use an executable such as `node` and its script path; shell-only `.cmd` wrappers are not automatically enabled. Commands are project-authored configuration, never free-form model-generated commands. Projects consisting entirely of configured actions do not need a model CLI unless they enable a model-based review or planning workflow.
-
-Implementation/review prompts now select task-relevant project context deterministically within a 6,000-character budget. A stable project/glossary prefix precedes ranked historical references with source paths and content hashes. Excerpts point back to complete files. This does not claim a fixed token count or guaranteed provider cache hit. Mandatory verification always reruns; no broad result cache or selective-test bypass was introduced.
-
-## Parallelism and time estimates
-
-Stories can declare relative file/directory scopes:
-
-```yaml
-- id: api-types
-  title: Update API types
-  priority: 1
-  area: api
-  writes: [src/api, tests/api]
-  needs: []
-  acceptance: ["Replace with executable structured criteria in strict projects"]
-  passes: false
-```
-
-Overlapping declared scopes cannot run simultaneously, including while integration is pending. Dependencies, areas, explicit priorities and concurrency limits also apply. Equal-priority work that unlocks a longer dependency chain is scheduled first. Declarations are advisory scheduling input, not filesystem write enforcement; absent declarations preserve previous behavior. Final integrated gates remain mandatory.
-
-Versioned local events record status, phase duration, attempts and available usage. Retention is bounded to 1,000 events. Estimates combine historical and current durations, preserve failed-attempt cost and expose sample counts and empirical ranges. Schedule estimates simulate dependency, scope and concurrency constraints. Predictions and later errors are attached to completed attempt events so accuracy can be evaluated. Ranges describe observed data; they are not calibrated probabilities or exact deadlines. No history means no justified time estimate.
-
-## Local project dashboard
-
-### Execution defaults in 1.8.0
-
-New setups enable routing, `loop.parallel: auto` and `loop.isolate: true`. Existing explicit settings remain authoritative. At execution time, automatic routing uses configured profiles; without profiles it keeps the selected parent. Explicit `--routing` without profiles still reports a configuration error. Routing rules bypass the controller and can escalate following failed independent gates, including across worktrees and restarts. Routing now also runs asynchronously inside parallel workers. An explicit task provider affinity takes precedence over routing.
-
-Automatic parallelism allows at most three Yoke workers when every pending task declares nonempty write scopes. Dependencies and overlapping scopes still constrain dispatch. Unknown scopes, configured tool actions and worktree recovery select serial execution. Use `--parallel=N`, `--parallel=auto`, `--no-routing` or `--no-isolate` to override defaults. Serial worktrees retain failed work and require deliberate recovery; the default does not discard an existing recovery tree. Quality repair budgets and opt-in competing candidates retain their existing policies.
-
-Integration retains an execution slot until its candidate lands. Yoke loop runners disable native delegation so it cannot multiply the default worker budget: Codex disables multi_agent; Claude disallows Agent, Task, TeamCreate and SendMessage; Gemini uses a separate temporary system-settings copy that disables experimental agents and its always-on investigator/help overrides. Existing Gemini system policy and system-default paths are preserved; unreadable or malformed policy blocks launch. Original settings are never overwritten. The temporary copy is removed on normal exit; forced process termination may leave a private temporary directory. Explicit competing candidate counts remain a separate opt-in workload.
-
-### Dashboard views
-
-- **Now:** reported task and worker activity, requested provider/model, elapsed worker time, phase, integration, blockers, status age, backlog and empirical remaining-time ranges. The view refreshes every five seconds while visible and not being operated with keyboard focus. A stale status is marked rather than asserted to be live.
-- **Usage & time:** last 24 hours, 7/30/90/365 days or custom dates, grouped by UTC day, Monday-based week or month. Displays reported input/output and cache categories, cost coverage, consumption charts, per-model time buckets, per-task usage and summed phase/call durations. The overview also compares projects for the same period.
-- **Results:** recorded acceptances, ended attempts, explicitly successful outcomes, repair phases, rule-driven escalations and recorded tokens/time per acceptance. Saved acceptance evidence and goal attempts remain available; their timestamps may fall outside the statistics period.
-
-The short activity list still retains at most 1,000 events. Compact measurements now also persist under `.yoke/history/YYYY-MM-DD/` independently of that retention and across runs. They contain identifiers, model/provider evidence and measurements, not prompts or full status snapshots. Runtime history is excluded from Yoke commits and added to new project ignore rules. Available reviewer, quality critic and repair usage is recorded separately; absent usage is counted as unknown. Recent and archived records are deduplicated by event ID.
-
-Dates and buckets use UTC. The custom end date is inclusive; the API uses an exclusive upper timestamp. Usage belongs to the time the provider reports it, and durations to their end time. Tokens per elapsed minute divide recorded input/output by the full selected interval. Tokens per call minute use summed reported call duration, which can overlap across workers. Neither is measured generation speed. Cache categories are shown separately without adding them to input again.
-
-Historical activity that was never recorded or already expired cannot be reconstructed. Queue/human waiting time that lacks measurements remains unknown; phase and attempt durations are summed worker time, not automatically elapsed project time. Queries allow at most 366 days and bounded reads (8 MiB per shard, 32 MiB overall, 50,000 records); skipped, malformed or oversized history is reported as incomplete. History currently requires local disk retention rather than automatic monthly compaction. Unknown model identity is never replaced by a requested model, and missing charges are not estimated from token counts.
-
-```sh
-yoke projects add /path/to/project
-yoke projects list
-yoke dashboard .
-yoke dashboard --no-register --port=4100
-yoke projects remove <opaque-project-id>
-```
-
-Open the printed loopback URL. The dashboard displays project goals, backlog, worker/status data, evidence, blockers, events, usage availability and schedule ranges. It can request a goal pause through the same service as the CLI. Start, resume and budget changes remain explicit CLI operations. Removing registration only removes the registry reference.
-
-The HTTP service binds to `127.0.0.1`, validates Host/Origin, requires a per-session token for pause, sends a restrictive CSP and renders project strings as text. It does not serve arbitrary local files or allow remote registration. Missing/corrupt/oversized project data is shown as unavailable. Shared project registration and protected acceptance live under `YOKE_STATE_DIR` or `~/.yoke/state`; existing routing history retains its `YOKE_REGISTRY_DIR` location. The dashboard is local, not a hosted multi-user service.
-
-## Remaining validation and product work
-
-Live Codex/Claude/Gemini comparisons, measured competitive development-time/cost studies and estimate calibration require representative real projects and authenticated runs. Equal adapter contracts do not imply equal model capability. Cloud/team access, automatic selective test reuse, web-based start/resume controls and commercial rollout are not included in this local foundation. The complete saved direction is in [PRODUCT-DIRECTION-2026-09-05.md](PRODUCT-DIRECTION-2026-09-05.md).
+# Verified projects, goals and measured execution
+
+Available in Yoke 1.7.0. These additions do not require a cloud account or replace your provider CLI. Model availability, reasoning controls, structured output and telemetry depend on the selected provider; unknown usage is never a measured zero. Live authenticated provider comparison and calibrated time/cost benchmarks remain separate validation work.
+
+## Check an existing project
+
+```sh
+yoke check .
+yoke check . --json
+yoke check . --requirement="Guest checkout completes"
+```
+
+Checks run without retrofit. Exit codes: `0` passed, `1` failed, `2` unverified or unavailable. A free-text requirement stays unverified until you map its behavior to an executable acceptance contract. Passing a project suite does not establish arbitrary product correctness.
+
+Create `.yoke/acceptance.yaml` with tests that inspect application behavior:
+
+```yaml
+version: 1
+protected:
+  - tests/acceptance/checkout.test.mjs
+  - tests/acceptance/helpers.mjs
+criteria:
+  - id: guest-checkout
+    text: A guest can complete checkout and receives one order confirmation.
+    commands:
+      - node --test tests/acceptance/checkout.test.mjs
+```
+
+List every local test helper, fixture and configuration file whose modification could weaken this contract. Paths must resolve inside the project. `yoke check . --protect` pins the manifest, listed files and existing package manifests/lockfiles outside the worker checkout. Autonomous goals require explicit protected test infrastructure and establish this pin automatically. Protection is change detection within the local execution model, not an OS security boundary against a hostile process using your account. Review the contract before running a goal.
+
+After intentionally editing protected tests, use `yoke check . --protect --refresh` to approve the new baseline. Ordinary checks and retries never refresh it. Source, acceptance and configuration identity are checked before and after verification; changed inputs invalidate evidence. Gitlinks/submodule directories currently fail closed because recursive identity is not implemented. Evidence is stored in `.yoke/checks/<id>.json`; it describes that checked snapshot and is not a permanent success certificate.
+
+## Durable goals across providers
+
+```sh
+yoke goal set . --objective="Finish guest checkout" --attempts=3 --minutes=30
+yoke goal run . --runner=codex
+yoke goal resume . --runner=claude --model=<installed-model-id>
+yoke goal resume . --runner=gemini --model=<installed-model-id>
+yoke goal status .
+yoke goal handoff .
+yoke goal pause .
+```
+
+Goals keep objective, attempts, failure context and check IDs in `.yoke/goal.json`. They share the story-loop lock. Each implementation attempt is followed by independent executable acceptance. A completed goal is checked again on a later run. Failed work stays in the project; goal execution itself does not commit or publish it. Goal handoff is readable context for native agent goal facilities; Yoke does not invent or call an undocumented native goal API.
+
+`--minutes` limits cumulative agent execution time. Verification is measured separately and commands retain their verification timeout. `--tokens=N` is a checkpoint budget: it prevents another attempt when measured consumption is exhausted or unknown, but cannot promise a hard token cap within a single provider call. An interrupted attempt is persisted before dispatch; recovery accounts for it conservatively and reconciles recorded provider processes before continuing. Unknown process ownership blocks execution. Pause takes effect at an attempt boundary; it does not instantly kill an in-flight agent.
+
+Explicitly extend total budgets without deleting history:
+
+```sh
+yoke goal budget . --attempts=5 --minutes=60
+yoke goal budget . --tokens=200000
+# Only if you deliberately want to remove the checkpoint token limit:
+yoke goal budget . --clear-token-budget
+```
+
+Unknown historical token usage cannot be made known by increasing its limit. Inspect interrupted work and keep that limitation visible.
+
+## Recover an isolated story
+
+Failed or paused isolated story worktrees are retained. Resume the same story with:
+
+```sh
+yoke loop run . --isolate --resume-worktree --parallel=1 --candidates=1
+```
+
+Yoke validates the registered worktree, repository, original target commit and PRD digest. Changed target/PRD state is refused; inspect retained edits and reconcile deliberately. This flag is for serial isolated recovery; parallel workers retain their existing coordinator lifecycle. `yoke loop cleanup` remains an explicit cleanup operation; inspect its removal flags before discarding unfinished work. Existing projects should rerun retrofit to add ignore entries for checks, events and goals.
+
+## Spend fewer model calls
+
+Add explicit project rules to `.yoke/config.yaml`:
+
+```yaml
+routing:
+  enabled: true
+  strategy: cost
+  maxCandidates: 2
+  workers:
+    - id: fast
+      agent: claude
+      model: <your-fast-model-id>
+      costTier: low
+      capabilities: [docs, tests]
+    - id: strong
+      agent: codex
+      model: <your-strong-model-id>
+      costTier: high
+      capabilities: [implementation]
+  rules:
+    - area: docs
+      worker: fast
+      escalateTo: strong
+```
+
+The first matching rule bypasses the routing controller. Its optional area and story ID selectors both have to match when supplied. Independent gate failure escalates the next attempt, including after loop restart; an unavailable or unknown worker falls back to the parent. Without an explicit escalation target the parent handles the failed rule. Other stories retain adaptive routing. Gate-driven routing observations are local and bounded when read. These are measured outcomes, not guarantees that a named inexpensive model can handle every task.
+
+For deterministic operations, configure exact executable arguments:
+
+```yaml
+actions:
+  - storyId: regenerate-types
+    file: node
+    args: [scripts/generate-types.mjs]
+    timeoutMs: 60000
+```
+
+Actions use no model, run without a shell, have bounded output/time and still pass the ordinary story gates before commit. They currently require serial execution with one candidate. On Windows use an executable such as `node` and its script path; shell-only `.cmd` wrappers are not automatically enabled. Commands are project-authored configuration, never free-form model-generated commands. Projects consisting entirely of configured actions do not need a model CLI unless they enable a model-based review or planning workflow.
+
+Implementation/review prompts now select task-relevant project context deterministically within a 6,000-character budget. A stable project/glossary prefix precedes ranked historical references with source paths and content hashes. Excerpts point back to complete files. This does not claim a fixed token count or guaranteed provider cache hit. Mandatory verification always reruns; no broad result cache or selective-test bypass was introduced.
+
+## Parallelism and time estimates
+
+Stories can declare relative file/directory scopes:
+
+```yaml
+- id: api-types
+  title: Update API types
+  priority: 1
+  area: api
+  writes: [src/api, tests/api]
+  needs: []
+  acceptance: ["Replace with executable structured criteria in strict projects"]
+  passes: false
+```
+
+Overlapping declared scopes cannot run simultaneously, including while integration is pending. Dependencies, areas, explicit priorities and concurrency limits also apply. Equal-priority work that unlocks a longer dependency chain is scheduled first. Declarations are advisory scheduling input, not filesystem write enforcement; absent declarations preserve previous behavior. Final integrated gates remain mandatory.
+
+Versioned local events record status, phase duration, attempts and available usage. Retention is bounded to 1,000 events. Estimates combine historical and current durations, preserve failed-attempt cost and expose sample counts and empirical ranges. Schedule estimates simulate dependency, scope and concurrency constraints. Predictions and later errors are attached to completed attempt events so accuracy can be evaluated. Ranges describe observed data; they are not calibrated probabilities or exact deadlines. No history means no justified time estimate.
+
+## Local project dashboard
+
+### Execution defaults in 1.8.0
+
+New setups enable routing, `loop.parallel: auto` and `loop.isolate: true`. Existing explicit settings remain authoritative. At execution time, automatic routing uses configured profiles; without profiles it keeps the selected parent. Explicit `--routing` without profiles still reports a configuration error. Routing rules bypass the controller and can escalate following failed independent gates, including across worktrees and restarts. Routing now also runs asynchronously inside parallel workers. An explicit task provider affinity takes precedence over routing.
+
+Automatic parallelism allows at most three Yoke workers when every pending task declares nonempty write scopes. Dependencies and overlapping scopes still constrain dispatch. Unknown scopes, configured tool actions and worktree recovery select serial execution. Use `--parallel=N`, `--parallel=auto`, `--no-routing` or `--no-isolate` to override defaults. Serial worktrees retain failed work and require deliberate recovery; the default does not discard an existing recovery tree. Quality repair budgets and opt-in competing candidates retain their existing policies.
+
+Integration retains an execution slot until its candidate lands. Yoke loop runners disable native delegation so it cannot multiply the default worker budget: Codex disables multi_agent; Claude disallows Agent, Task, TeamCreate and SendMessage; Gemini uses a separate temporary system-settings copy that disables experimental agents and its always-on investigator/help overrides. Existing Gemini system policy and system-default paths are preserved; unreadable or malformed policy blocks launch. Original settings are never overwritten. The temporary copy is removed on normal exit; forced process termination may leave a private temporary directory. Explicit competing candidate counts remain a separate opt-in workload.
+
+### Dashboard views
+
+- **Now:** reported task and worker activity, requested provider/model, elapsed worker time, phase, integration, blockers, status age, backlog and empirical remaining-time ranges. The view refreshes every five seconds while visible and not being operated with keyboard focus. A stale status is marked rather than asserted to be live.
+- **Usage & time:** last 24 hours, 7/30/90/365 days or custom dates, grouped by UTC day, Monday-based week or month. Displays reported input/output and cache categories, cost coverage, consumption charts, per-model time buckets, per-task usage and summed phase/call durations. The overview also compares projects for the same period.
+- **Results:** recorded acceptances, ended attempts, explicitly successful outcomes, repair phases, rule-driven escalations and recorded tokens/time per acceptance. Saved acceptance evidence and goal attempts remain available; their timestamps may fall outside the statistics period.
+
+The short activity list still retains at most 1,000 events. Compact measurements now also persist under `.yoke/history/YYYY-MM-DD/` independently of that retention and across runs. They contain identifiers, model/provider evidence and measurements, not prompts or full status snapshots. Runtime history is excluded from Yoke commits and added to new project ignore rules. Available reviewer, quality critic and repair usage is recorded separately; absent usage is counted as unknown. Recent and archived records are deduplicated by event ID.
+
+Dates and buckets use UTC. The custom end date is inclusive; the API uses an exclusive upper timestamp. Usage belongs to the time the provider reports it, and durations to their end time. Tokens per elapsed minute divide recorded input/output by the full selected interval. Tokens per call minute use summed reported call duration, which can overlap across workers. Neither is measured generation speed. Cache categories are shown separately without adding them to input again.
+
+Historical activity that was never recorded or already expired cannot be reconstructed. Queue/human waiting time that lacks measurements remains unknown; phase and attempt durations are summed worker time, not automatically elapsed project time. Queries allow at most 366 days and bounded reads (8 MiB per shard, 32 MiB overall, 50,000 records); skipped, malformed or oversized history is reported as incomplete. History currently requires local disk retention rather than automatic monthly compaction. Unknown model identity is never replaced by a requested model, and missing charges are not estimated from token counts.
+
+```sh
+yoke projects add /path/to/project
+yoke projects list
+yoke dashboard .
+yoke dashboard --no-register --port=4100
+yoke projects remove <opaque-project-id>
+```
+
+Open the printed loopback URL. The dashboard displays project goals, backlog, worker/status data, evidence, blockers, events, usage availability and schedule ranges. It can request a goal pause through the same service as the CLI. Start, resume and budget changes remain explicit CLI operations. Removing registration only removes the registry reference.
+
+The HTTP service binds to `127.0.0.1`, validates Host/Origin, requires a per-session token for pause, sends a restrictive CSP and renders project strings as text. It does not serve arbitrary local files or allow remote registration. Missing/corrupt/oversized project data is shown as unavailable. Shared project registration and protected acceptance live under `YOKE_STATE_DIR` or `~/.yoke/state`; existing routing history retains its `YOKE_REGISTRY_DIR` location. The dashboard is local, not a hosted multi-user service.
+
+## Remaining validation and product work
+
+Live Codex/Claude/Gemini comparisons, measured competitive development-time/cost studies and estimate calibration require representative real projects and authenticated runs. Equal adapter contracts do not imply equal model capability. Cloud/team access, automatic selective test reuse, web-based start/resume controls and commercial rollout are not included in this local foundation. The complete saved direction is in [PRODUCT-DIRECTION-2026-09-05.md](PRODUCT-DIRECTION-2026-09-05.md).

package/docs/community-outreach-2026-08-20.md

@@ -0,0 +1,85 @@
+# Yoke community outreach — 2026-08-20
+
+These posts are intentionally feedback-first. They disclose the creator relationship, avoid vote requests, and link directly to the free MIT-licensed project.
+
+## Hacker News — Show HN
+
+**Title**
+
+Show HN: Yoke – safety-gated autonomous coding loops for Claude, Codex, and Gemini
+
+**URL**
+
+https://github.com/HECer/yoke
+
+**First comment**
+
+Hi HN — I built Yoke after repeatedly seeing the same failure mode in long-running coding-agent loops: the agent says a task is done, but the tests were not actually run, the working tree is inconsistent, or a later iteration breaks earlier work.
+
+Yoke is an MIT-licensed TypeScript CLI that puts mechanical gates around those loops. A story only passes after the configured verification command succeeds, review approves it, and the commit lands. Stories run in isolated worktrees, and optional Playwright evidence can attach screenshots to acceptance criteria. It generates native project instructions for Claude Code, Codex CLI, and Gemini CLI from one canon rather than asking all three tools to interpret the same generic prompt.
+
+You can try it without signing up:
+
+    npm i -g @hecer/yoke
+    yoke new my-app
+
+I would especially value feedback from people who already run Ralph-style or overnight agent loops: which gate feels essential, which feels like ceremony, and what would stop you from trying this on a real repository?
+
+I am the creator and will be around to answer technical questions.
+
+## Reddit — r/ClaudeCodeTLDR weekly showcase (English)
+
+I built **Yoke**, a free MIT-licensed harness for running Claude Code, Codex CLI, or Gemini CLI in autonomous coding loops with mechanical safety gates.
+
+The problem I wanted to solve was the gap between an agent saying “done” and the repository actually being in a verified state. Yoke uses isolated worktrees and only marks a story complete after the configured tests pass, review approves it, and the commit lands. It can also require Playwright screenshot evidence for visual acceptance criteria.
+
+Claude Code was both a target runtime and part of the development/review workflow; the project also generates native instructions for Codex and Gemini from the same canon.
+
+It is free to use, requires no account, and the quickstart is:
+
+    npm i -g @hecer/yoke
+    yoke new my-app
+
+Repo: https://github.com/HECer/yoke
+
+I’m the creator. I’d love blunt feedback from people who already use long-running Claude Code loops: would these gates make you trust an overnight run more, or does the workflow look too heavy? If you try it, which part is confusing first?
+
+## Reddit — r/ChatGPTCoding self-promotion thread (English)
+
+I built **Yoke**, an MIT-licensed CLI for people using Claude Code, Codex CLI, or Gemini CLI for longer autonomous coding runs.
+
+Instead of trusting the agent’s “done” message, Yoke gates each story on a real verification command, review approval, and an atomic commit. It also isolates stories in worktrees and can collect Playwright screenshots as acceptance evidence.
+
+Install and try it without an account:
+
+    npm i -g @hecer/yoke
+    yoke new my-app
+
+https://github.com/HECer/yoke
+
+I’m the creator. I’m mainly looking for honest feedback: if you already run coding agents for more than one task at a time, what would make you try this, and what looks like unnecessary process?
+
+## German-language developer communities (draft for communities that explicitly permit project showcases)
+
+**Titel**
+
+Feedback gesucht: Yoke – abgesicherte autonome Coding-Loops für Claude, Codex und Gemini
+
+**Text**
+
+Ich habe **Yoke** gebaut, ein kostenloses, MIT-lizenziertes CLI für längere autonome Coding-Läufe mit Claude Code, Codex CLI oder Gemini CLI.
+
+Der Auslöser war die Lücke zwischen „der Agent sagt, er sei fertig“ und einem tatsächlich verifizierten Repository. Yoke markiert eine Story erst dann als erledigt, wenn der konfigurierte Test-/Verify-Befehl erfolgreich war, ein Review zugestimmt hat und der Commit sauber gelandet ist. Einzelne Stories laufen isoliert in Worktrees; für visuelle Akzeptanzkriterien können Playwright-Screenshots als Nachweis verlangt werden.
+
+Ausprobieren ohne Account:
+
+    npm i -g @hecer/yoke
+    yoke new meine-app
+
+Repo: https://github.com/HECer/yoke
+
+Ich bin der Entwickler des Projekts. Mich interessiert vor allem ehrliches Feedback von Leuten, die Coding-Agents länger oder autonom laufen lassen: Würden solche Gates euer Vertrauen erhöhen, oder wirkt der Ablauf zu schwergewichtig? Was wäre beim ersten Ausprobieren vermutlich die größte Hürde?
+
+## Disclosure note
+
+The outreach copy in this file was drafted with AI assistance on the creator's instructions. Add a human-readable AI-assistance disclosure wherever a community's rules require it; do not infer human authorship from the absence of machine-readable provenance.

package/docs/launch-copy-2026-08-21.md

@@ -0,0 +1,193 @@
+# Yoke launch copy
+
+## 1. Show HN
+
+### Title
+
+Show HN: Yoke – gated coding-agent loops for Claude, Codex, and Gemini
+
+### URL
+
+https://github.com/HECer/yoke
+
+### First comment
+
+I built Yoke after seeing coding agents report that a task was finished when the repository told a different story: tests had not run, the working tree contained unrelated changes, or a later iteration had broken earlier work.
+
+Yoke is an MIT-licensed TypeScript CLI for running coding-agent work as a sequence of verifiable stories. It supports Claude Code, Codex CLI, and Gemini CLI.
+
+The runner, rather than the agent, decides whether a story passed. It checks the configured verification command's exit code, requires review approval, and confirms that the commit landed. Stories run in isolated Git worktrees. For visual acceptance criteria, a run can require Playwright screenshots or video as evidence.
+
+Yoke also generates native project instructions for each supported agent from one versioned skill canon. That part is Markdown. The state transitions, worktree lifecycle, process supervision, gates, and run state are executable TypeScript.
+
+The closest comparison I know is WorkOS Case. Both projects treat the harness as the reliability boundary. Case is focused on turning GitHub or Linear issues into reviewed pull requests. Yoke includes greenfield and retrofit setup, PRD-to-story execution, and portable project configuration across three coding agents.
+
+You can try it without an account:
+
+    npm install -g @hecer/yoke
+    yoke new my-app
+
+I am looking for two kinds of feedback:
+
+1. Which gate would you remove because it adds more process than safety?
+2. What failure from a real autonomous run would Yoke still miss?
+
+I am the maintainer and will be around to answer questions.
+
+## 2. DEV Community (`#showdev`)
+
+### Title
+
+I moved coding-agent verification out of the prompt
+
+### Tags
+
+`showdev`, `ai`, `opensource`, `typescript`
+
+### Article
+
+A coding agent can agree to run the tests and still fail to run them. It can also run the wrong command, overlook a dirty working tree, or declare success before the result is committed.
+
+Adding another sentence to the prompt does not change who controls the completion decision. The same model doing the work still decides whether it followed the instruction.
+
+I built Yoke to put that decision in a TypeScript runner.
+
+Yoke executes work as a sequence of stories. For each story, the runner creates an isolated Git worktree, starts a fresh agent session, runs the configured verification command, requests a separate review, and checks that the resulting commit landed. A story is not marked as passed because the agent says it is done.
+
+For user-interface work, the acceptance criteria can require Playwright screenshots or video. The evidence belongs to the story instead of living in a chat transcript.
+
+Yoke supports Claude Code, Codex CLI, and Gemini CLI. A versioned canon generates the native instructions each agent expects, so a project can keep one methodology without pretending that all three tools use identical configuration formats.
+
+Some of Yoke is Markdown. The skills, policies, and project context should be readable and editable. The enforcement layer is code: process supervision, worktree isolation, persisted run state, verification exit codes, review gates, and commit checks.
+
+The closest existing project is WorkOS Case. Case uses a deterministic TypeScript pipeline to turn issues into reviewed pull requests with evidence. Yoke covers a somewhat different workflow: creating or retrofitting a project, converting a PRD into ordered stories, and running those stories across Claude, Codex, or Gemini. The projects share more philosophy than I realized when I first described Yoke, and I now call that out directly.
+
+Yoke is MIT-licensed and does not require an account.
+
+    npm install -g @hecer/yoke
+    yoke new my-app
+
+Repository: https://github.com/HECer/yoke
+
+I would value examples of failures that prompts and skills do not handle reliably. I am also interested in the opposite feedback: which Yoke gate feels unnecessary in normal development?
+
+Disclosure: I used AI assistance while drafting and editing this article. The product description and technical claims were checked against the repository by the maintainer.
+
+## 3. DevHunt
+
+### Name
+
+Yoke
+
+### Tagline
+
+Run coding agents with tests, review, and commit gates outside the model.
+
+### Short description
+
+Yoke is an MIT-licensed TypeScript CLI for autonomous coding loops with Claude Code, Codex CLI, and Gemini CLI. It runs stories in isolated Git worktrees and only records a pass after the configured verification command succeeds, review approves the change, and the commit lands. Visual stories can require Playwright screenshot or video evidence.
+
+### Maker comment
+
+I built Yoke because instructions such as “run the tests before finishing” leave the completion decision with the same agent doing the work. Yoke moves that decision into an executable runner.
+
+I would like feedback from developers who already run agents unattended: which gate earns its cost, and what would prevent you from using Yoke on an existing repository?
+
+Source: https://github.com/HECer/yoke
+
+## 4. Uneed
+
+### Title
+
+Yoke
+
+### Tagline
+
+A safety-gated coding harness for Claude, Codex, and Gemini.
+
+### Description
+
+Yoke runs autonomous coding work as verifiable stories. Each story gets an isolated Git worktree and must pass the project's real verification command, an independent review, and a commit check. User-interface stories can also require Playwright screenshots or video.
+
+The CLI can create a new project or retrofit an existing one. It generates native instructions for Claude Code, Codex CLI, and Gemini CLI from one versioned canon.
+
+Yoke is open source under the MIT license and requires no account.
+
+### Launch comment
+
+I am the maintainer. I am looking for concrete failure cases from people who use coding agents for long or unattended runs. If Yoke would not catch one of yours, please tell me what happened.
+
+https://github.com/HECer/yoke
+
+## 5. Product Hunt
+
+### Name
+
+Yoke
+
+### Tagline
+
+Mechanical safety gates for autonomous coding agents
+
+### Description
+
+Run Claude Code, Codex CLI, or Gemini CLI through isolated worktrees, real test commands, independent review, commit checks, and optional visual evidence. Open source and local-first.
+
+### First maker comment
+
+Hi Product Hunt,
+
+I built Yoke for developers who let coding agents work through more than one task at a time.
+
+The failure I wanted to address was straightforward: an agent could say that tests passed without giving the repository a reliable completion boundary. Yoke makes the runner responsible for that boundary. A story passes only after the configured verification command exits successfully, review approves the change, and the commit lands.
+
+Yoke supports Claude Code, Codex CLI, and Gemini CLI. It can bootstrap a new project or retrofit an existing repository, and it keeps stories isolated in Git worktrees.
+
+The project is MIT-licensed, runs locally, and requires no account:
+
+https://github.com/HECer/yoke
+
+I would appreciate feedback from anyone already running coding agents unattended. What evidence do you need before trusting the result?
+
+## 6. Peerlist Launchpad
+
+### Project summary
+
+Yoke is an open-source TypeScript CLI for running Claude Code, Codex CLI, and Gemini CLI with completion gates outside the model.
+
+It breaks a PRD into stories, runs each story in an isolated Git worktree, and checks the project's verification command, review result, and final commit before recording a pass. Visual acceptance criteria can require Playwright screenshots or video.
+
+I built it after finding that prompt-level instructions were useful guidance but a weak enforcement boundary for unattended work. The readable methodology lives in versioned Markdown; the enforcement lives in the runner.
+
+Try it:
+
+    npm install -g @hecer/yoke
+    yoke new my-app
+
+Source: https://github.com/HECer/yoke
+
+I am looking for developers willing to try it on an existing repository and report the first confusing or unnecessary step.
+
+## 7. Indie Hackers
+
+### Title
+
+I built a coding-agent harness, then learned that “it is just Markdown” was the right criticism to answer
+
+### Post
+
+I recently shared Yoke, an open-source harness for autonomous coding agents, and received a blunt question: why not encode the workflow in one skill or even one sentence?
+
+That criticism exposed a problem in how I described the project. The interesting part is not the workflow advice. Agents can read instructions telling them to plan, test, review, and commit.
+
+The product decision is who controls the pass condition.
+
+Yoke puts that condition in a TypeScript runner. It creates isolated worktrees, executes the configured verification command, requests review, checks the commit, and persists story state. The agent produces the change, but it cannot mark its own story as passed merely by saying the work is complete.
+
+The skills and policies are Markdown because users should be able to read and change them. If someone only needs those instructions, a skill is enough and Yoke is unnecessary.
+
+I also learned that WorkOS Case already takes a closely related approach. Case focuses on moving an issue through a multi-agent pipeline into a reviewed pull request. Yoke focuses on creating or retrofitting projects, turning PRDs into stories, and running them across Claude Code, Codex CLI, or Gemini CLI. I now describe that overlap directly instead of pretending the category is empty.
+
+The project is MIT-licensed: https://github.com/HECer/yoke
+
+My question for other builders is about scope. Would you keep the product narrow around enforced story completion, or is cross-agent project setup a meaningful part of the value?