@hecer/yoke 1.16.0 → 1.18.0

package/dist/retrofit/config.js

@@ -56,7 +56,7 @@ export const YokeConfigSchema = z.object({
     agents: z.array(AgentSchema),
     loop: z.object({
         enabled: z.boolean(),
-        parallel: z.union([z.literal('auto'), z.number().int().positive()]).optional(),
+        parallel: z.union([z.literal('auto'), z.number().int().min(1).max(8)]).optional(),
         isolate: z.boolean().optional(),
         timeoutMinutes: z.number().optional(),
         maxCallMinutes: z.number().positive().max(1440).optional(),

package/docs/CONTINUOUS-EXPLORATION.md

@@ -0,0 +1,67 @@
+# Continuous autonomous exploration
+
+The normal loop stops after every accepted PRD story passes and the optional completion gate is
+green. `--explore` opts into a supervisor that keeps the loop alive after that point and looks for
+the next evidence-backed improvement. Exploration is off by default.
+
+```powershell
+yoke loop run . --explore --parallel=auto
+yoke loop run . --explore --explore-interval=10
+yoke loop run . --explore --explore-limit=3d
+yoke loop status .
+yoke loop pause .
+```
+
+## Discovery and implementation
+
+After the current backlog drains, a configured planning provider inspects the read-only repository
+and returns either a short wait decision or up to three independent tasks. Yoke accepts a proposal
+only when it has at least 0.8 declared confidence, low or medium risk, existing-file evidence,
+non-overlapping relative write scopes, and two to five structured acceptance criteria. Every
+criterion must contain an approved test command that names its criterion ID. Paths, duplicate
+contracts, dependencies and the combined PRD are validated mechanically.
+
+Accepted tasks are appended to `.yoke/prd.yaml` and committed with the configured commit identity
+before implementation. Stories always run in isolated worktrees through the project's existing
+acceptance, verify, completion, review, audit, quality and commit gates. `--parallel` works as usual
+for independent tasks. When the optional integrated completion gate fails after every story passes,
+the explorer receives that failure as context and can propose work to resolve it; the gate itself is
+never skipped.
+
+Completed auto-generated stories are compacted out of the active PRD before the next exploration
+pass, so the working backlog does not grow forever. Up to 100 recent task fingerprints, IDs and
+criterion IDs remain in `.yoke/exploration-recent.json` for duplicate avoidance. Older PRD states and
+their full acceptance contracts remain in Git history.
+
+## Waiting, recovery and stopping
+
+The default no-op interval is 30 minutes. Set `--explore-interval=N` to an integer from 1 to 1440
+minutes. If a provider fails, returns an invalid proposal, or a story is blocked, the supervisor
+keeps running, rotates through available configured providers and retries with exponential backoff
+up to 15 minutes. A task that requires a human decision remains pending; the supervisor waits for
+the decision instead of declaring completion. During long waits, status heartbeats keep
+`yoke loop status` accurate.
+
+`yoke loop pause .` requests a pause at the next safe story or exploration boundary. It exits with
+code `3`; start `yoke loop run . --explore` again to resume. An explicit `--max=N` remains a deliberate
+story-attempt cap and exits with code `1` if work remains. Without that flag, reaching the end of a
+PRD is not a stop condition.
+
+Exploration has no time limit by default. Set `--explore-limit=12h`, `--explore-limit=3d`, or
+`--explore-limit=2w` to set a positive duration in hours, days, or weeks. Full unit names also work
+when quoted, for example `--explore-limit="2 days"`. When it expires, Yoke pauses automatically at a safe boundary and exits with
+code `3`. It stops launching new workers, lets already active workers finish their acceptance,
+verification and integration gates, and preserves resumable work. Finite runs process bounded task
+batches so an unfinished large backlog does not run past the deadline by draining the whole PRD.
+Omitting `--explore-limit` keeps the supervisor unbounded; a later resume starts a new duration if
+one is supplied.
+
+The supervisor can retry failures while its process remains alive. Run it in a background process
+for long sessions. An operating-system shutdown, forced process termination, exhausted credentials
+or unavailable machine cannot be prevented by an in-process loop; after a crash, inspect
+`yoke loop status .`, recover retained work if needed, then restart with `yoke loop run . --explore`.
+
+The explorer is a proposal filter, not a guarantee of product maturity. It uses repository evidence
+and strict contracts to limit speculative work; implementation still depends on the project's real
+tests and any enabled independent review or quality gates. The user decides when the project is
+mature enough and can stop the supervisor with `yoke loop pause .`.

package/docs/VERIFIED-PROJECTS.md

@@ -134,9 +134,11 @@ Versioned local events record status, phase duration, attempts and available usa
 
 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.
+Automatic parallelism uses up to the shared worker limit when every pending task declares nonempty write scopes. The shared default is three units across concurrent Yoke projects; `YOKE_MAX_PARALLEL_WORKERS=1..8` sets the user-level ceiling. Dependencies, areas 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 isolated work uses the same dispatcher and shared pool; legacy in-place work reserves one shared unit around each agent call. Failed work remains recoverable; the default does not discard an existing recovery tree. Quality repair budgets and opt-in competing candidates retain their existing policies, and each simultaneous candidate consumes one worker unit.
 
-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.
+Implementation slots and integration are separate lanes. A completed candidate frees its implementation slot, while its area and declared write scopes remain reserved until rebase, integrated-tree gates, commit and cleanup finish. The integration lane is serialized per project and also consumes one shared worker unit. 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.
+
+See [parallel execution and safe task decomposition](parallel-execution.md) for the shared-pool limits, recovery steps, integration lane, task-split constraints and synthetic benchmark.
 
 ### Dashboard views
 

package/docs/parallel-execution.md

@@ -0,0 +1,130 @@
+# Parallel execution
+
+## Continuous discovery
+
+`yoke loop run . --explore --parallel=auto` applies the same scheduler and shared-pool limits to
+newly discovered stories after each accepted backlog drains. Exploration itself is a single
+read-only planning call. Accepted tasks need repository-file evidence, disjoint write scopes and
+criterion-specific executable checks; implementation then uses the normal isolated workers and
+integration lane. A no-op scan waits 30 minutes by default (`--explore-interval=1..1440`). Continuous
+exploration is unbounded by default; `--explore-limit=12h|3d|2w` pauses it at a safe boundary after
+the chosen duration and lets active workers finish their gates and integration.
+`yoke loop pause .` stops at a safe boundary. See the [continuous exploration guide](CONTINUOUS-EXPLORATION.md)
+for retries, stop detection, PRD history compaction and recovery.
+
+Yoke parallelizes independent PRD stories. The scheduler respects declared dependencies, collision
+areas and overlapping `writes` scopes. Each worker edits an isolated worktree; its result still has
+to pass the integrated-tree gates before Yoke commits it.
+
+## Worker limits
+
+The shared pool admits at most **three worker units by default** across Yoke loop processes running
+under the same user account. Set `YOKE_MAX_PARALLEL_WORKERS` to an integer from 1 to 8 to change the
+ceiling. For example:
+
+```powershell
+$env:YOKE_MAX_PARALLEL_WORKERS = '6'
+yoke loop run . --parallel=auto
+```
+
+The environment setting is read when each Yoke process starts. Active and waiting pool records
+advertise their configured ceiling; while those processes are alive, the smallest advertised limit
+is used for new admissions. Lowering a limit does not cancel running work: Yoke waits for active
+units to drain before admitting more. Set the same value for all long-lived Yoke processes when a
+consistent ceiling is desired.
+
+`--parallel=N` and `loop.parallel` accept values from 1 to 8. This is the per-project maximum for
+simultaneous implementations; the shared pool can lower actual activity across projects. `auto`
+uses up to the shared limit when every pending story has a nonempty `writes` declaration. Dependency
+readiness, areas and overlapping scopes still decide which stories can start. If scopes are missing,
+automatic execution uses one local implementation slot. Competing candidate runs spend one unit per
+candidate, so `--candidates=3` requires a shared limit of at least three.
+
+The pool keeps small user-local lease records under:
+
+- Windows: `%LOCALAPPDATA%\Yoke\parallel-pool`
+- Linux/macOS: `$XDG_STATE_HOME/Yoke/parallel-pool`, or `~/.yoke/Yoke/parallel-pool` when
+  `XDG_STATE_HOME` is unset
+
+Records contain process identity, provider and role, worker weight, timestamps, and truncated hashes
+of project and story identifiers. They do not contain prompts, file contents or absolute project
+paths. They are coordinated through atomic file operations. The owner process must be known dead
+before its lease is reclaimed; process identity and a 30-second stale window protect against PID
+reuse and short interruptions. Admission fails closed if a record is malformed or ownership cannot
+be checked. On a corruption error, stop all Yoke processes first, make a backup of the pool directory,
+then inspect or move the stale pool aside before restarting. Never remove a record while its owner is
+alive.
+
+Adaptive routing can select a different provider after dispatch, so Yoke records provider use but
+does not claim a hard per-provider cap. Native subagent delegation remains disabled inside loop
+workers so nested agents cannot multiply the shared budget.
+
+## Implementation and integration lanes
+
+`--parallel` counts implementation slots. A finished candidate releases its implementation unit
+while it waits in the project's FIFO integration queue. The integration lane reserves one shared
+unit while it rebases, reruns integrated-tree gates, commits, checks cleanliness and cleans up. Its
+area and `writes` scopes remain reserved until that sequence ends, so overlapping or dependent work
+cannot start early. Independent stories can use the freed implementation slot during integration.
+
+The worker pool is shared across projects; each project's integration queue is serialized. A global
+limit of three therefore caps combined implementation and integration work, even if several project
+loops are active. Cancellation removes a waiting reservation and leaves existing recovery behavior
+unchanged.
+
+`yoke loop status` and the dashboard's **Now** view report local slots, workers waiting for capacity,
+the shared active-unit count, integration activity and queued integrations. Event history records
+implementation/integration resource waits, integration queue wait, integration duration and the
+existing worker phases. The schedule forecast simulates dependency-aware implementation slots plus
+one serial integration lane when integration measurements exist. Older runs without those events
+remain visible as missing integration history; forecasts are empirical ranges, not deadlines, and do
+not predict future contention from other projects.
+
+## Safe task decomposition
+
+Make a preview with:
+
+```sh
+yoke prd decompose . --story=API-1 --runner=codex
+```
+
+The planner proposes two ordinary child stories and changes no PRD data. Applying requires the
+explicit flag:
+
+```sh
+yoke prd decompose . --story=API-1 --runner=codex --apply
+```
+
+Yoke only accepts a split when the unfinished parent has at least four structured acceptance
+criteria, at least two valid non-overlapping declared write scopes, and no shared `area`. The
+proposal must allocate every original criterion and every declared scope exactly once, with 2–3
+criteria per child and no overlap. Children preserve their exact criterion text and verification
+commands, inherit upstream dependencies and agent affinity, and cannot depend on each other. A
+parent with an area or too few scopes/criteria is refused; refine the task contract first or keep it
+serial.
+
+`--apply` acquires the project loop lock, rechecks hashes of the PRD and approved planning brief,
+validates the resulting dependency graph, then atomically replaces the parent. Stories that depended
+on the parent are updated to depend on both children. Task-specific assessments and quality
+declarations are not copied to different work contracts: reassess with `yoke prd assess`, and add a
+child-specific quality declaration before using competing candidates. A stale input or invalid
+proposal is rejected without applying the split.
+
+Write scopes remain advisory scheduling information, not filesystem permissions. A good split must
+also keep each child independently verifiable and avoid hidden shared interfaces. Yoke does not
+claim that splitting a task improves model quality or lowers token spend.
+
+## Synthetic efficiency benchmark
+
+After building Yoke, run:
+
+```sh
+npm run build
+node bench/run-parallel-matrix.mjs
+```
+
+The matrix uses the real dispatcher with a local deterministic runner and fixed implementation and
+integration delays. It compares one, two and three implementation slots over a dependency chain,
+independent scopes and conflicting scopes. It reports wall time, summed worker time, integration
+queue wait, integration time, attempts and accepted stories. It makes no provider, token, quality or
+large-repository claims.

package/docs/superpowers/plans/2026-09-27-parallel-task-efficiency.md

@@ -0,0 +1,65 @@
+# Parallel Task Efficiency Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make Yoke's independent-task execution safer under load, easier to parallelize, less blocked by integration, and measurable by accepted result.
+
+**Architecture:** Keep the PRD dependency graph and FIFO integration gate as the source of correctness. Add bounded cross-project worker admission, let PRD planning propose safe task splits that become ordinary stories, and separate implementation slots from the serialized integration lane while retaining scope reservations through integration. Extend event-based measurements and schedule forecasts to account for both lanes.
+
+**Tech Stack:** TypeScript, Node.js filesystem/process APIs, Zod, YAML, current Yoke CLI and dashboard.
+
+---
+
+## File map
+
+- `src/loop/resource-pool.ts`: user-local, cross-process weighted leases with FIFO fairness, owner identity, stale-owner recovery, and owner-checked release.
+- `src/loop/run-command.ts`, `src/loop/parallel-command.ts`, `src/loop/dispatcher.ts`: bounded configuration, lease acquisition, lane scheduling, and lifecycle reporting.
+- `src/retrofit/config.ts`, `src/cli.ts`, `src/prd/command.ts`, `src/prd/decompose.ts`, `src/loop/prd.ts`: bounded worker schema and safe PRD decomposition command.
+- `src/observability/events.ts`, `src/loop/reporter.ts`, `src/estimation/schedule.ts`, `src/dashboard/server.ts`, `src/dashboard/panels.ts`: stage and wait measurements, resource status, and two-lane ETA.
+- `bench/run-parallel-matrix.mjs`, `bench/fixtures/parallel-work/`: repeatable synthetic serial/parallel comparisons with fixed work and no paid model calls.
+- `README.md`, `docs/VERIFIED-PROJECTS.md`, `docs/parallel-execution.md`, `CHANGELOG.md`: user-facing defaults, limits, recovery, and validation boundaries.
+
+## Task 1: Bound shared execution capacity
+
+- [x] Cap explicit and configured per-project concurrency at eight; reject larger values with a clear limit.
+- [x] Add a user-local shared pool that coordinates concurrent Yoke loop processes across projects and hosts no model prompts or project contents.
+- [x] Track total active worker weight. Default to three total worker units; allow a bounded override through `YOKE_MAX_PARALLEL_WORKERS`. Provider-specific hard limits are not reliable while adaptive routing can change the selected backend after dispatch, so provider use is recorded as evidence instead of guessed.
+- [x] Implement weighted FIFO admission with bounded overtakes, cancellable waits, owner process identity, atomic records, stale-owner recovery, and token-checked release. Fail closed on corrupt ownership state or unsupported atomic filesystem operations.
+- [x] Reserve candidate races by the number of simultaneous candidate workers. Release implementation permits before integration and acquire a separate permit for integration/review.
+- [x] Keep `auto` conservative at the shared limit only when all pending tasks declare write scopes; the shared pool may lower simultaneous work across projects.
+
+## Task 2: Improve task decomposition safely
+
+- [x] Add `yoke prd decompose --story=<id>` to request a bounded child-story proposal from the configured planner.
+- [x] Require structured executable acceptance criteria and nonempty, valid, pairwise-disjoint write scopes for each child; preserve the original criteria exactly as a complete union.
+- [x] Keep preview as the default. `--apply` acquires the project lock, rechecks PRD/brief hashes, replaces the parent with child tasks, and rewrites downstream dependencies to require every child.
+- [x] Validate IDs, story schema, dependency references, and cycles before the atomic write. Stale assessment bindings are removed. Planner output never becomes executable shell text.
+- [x] Include the proposal format and refusal cases in CLI help and documentation.
+
+## Task 3: Pipeline implementation and integration
+
+- [x] Count only active implementations against implementation slots; keep completed candidates in the serial integration lane without blocking unrelated, dependency-ready work.
+- [x] Keep their areas and declared write scopes reserved until integration finishes, so dependent or overlapping stories cannot start early.
+- [x] Keep the existing rebase, integrated-tree gates, commit, post-integration cleanliness check, cancellation, and cleanup ordering.
+- [x] Report implementation activity, global-pool wait, integration queue wait, and integration duration separately in status and immutable events.
+
+## Task 4: Measure end-to-end efficiency
+
+- [x] Extend event aggregation with accepted-result wall time, implementation work, queue wait, integration time, attempts, reported usage, and measurement coverage.
+- [x] Update schedule simulation to model weighted implementation workers and one serialized integration lane; preserve empirical ranges and unknowns.
+- [x] Show local/global capacity, resource waits, and lane utilization in CLI/dashboard status.
+- [x] Add a synthetic benchmark matrix comparing one, two, and three workers over serial chains, independent scopes, and conflicting scopes. Record wall time, worker time, integration wait, total attempts, and accepted results. The fixture uses a deterministic local runner; no provider costs or model-quality claims are implied.
+
+## Task 5: Document operation and limits
+
+- [x] Document bounded overrides, global environment settings, pool location/recovery, task-split preview/application, pipeline behavior, and telemetry coverage.
+- [x] Add a dated unreleased changelog entry; do not change package versions, tag, publish, or claim external benchmark results.
+- [x] Run TypeScript build and release documentation checks. No tests are added or run in this execution.
+
+**Execution record:** TypeScript build and `docs:check` passed on the first run. A later check retry could not enumerate tests because Vitest's `list --json` command ran out of WebAssembly memory; no tests were executed. The synthetic matrix is recorded in `bench/RESULTS.md`.
+
+## Self-review
+
+- Coverage: hard concurrency bounds, shared resource accounting, safe task decomposition, integration overlap, measurement, estimation, dashboard, benchmark harness, and documentation each have an implementation task.
+- Safety: PRD writes remain lock-protected and atomic; acceptance and dependency validation remain mandatory; write scopes stay advisory scheduling inputs; pool leases are owner-bound and never reclaimed from a live process.
+- Compatibility: existing serial mode and existing PRDs remain valid; new decomposition and resource overrides are opt-in or bounded defaults; no release/version change is part of this task.

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "yoke",
-  "version": "1.16.0",
+  "version": "1.18.0",
   "description": "Cross-agent coding harness for eight supported CLIs: curated skill canon, mechanical safety gates, autonomous loop with proof artifacts. CLI: npm i -g @hecer/yoke",
   "contextFileName": "GEMINI-EXTENSION.md"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hecer/yoke",
-  "version": "1.16.0",
+  "version": "1.18.0",
   "description": "One harness, eight agents, zero trust in \"done\" — cross-agent coding harness for Claude Code, Codex CLI, Gemini CLI, Qwen Code, OpenCode, Kilo, Pi and Hermes: one skill canon, mechanical safety gates, an autonomous loop with screenshot/video proofs.",
   "type": "module",
   "bin": {
@@ -21,6 +21,7 @@
     "bench/run.mjs",
     "bench/run-large.mjs",
     "bench/run-matrix.mjs",
+    "bench/run-parallel-matrix.mjs",
     "bench/analyze-routing-study.mjs",
     "bench/fixtures",
     "bench/results",