@hecer/yoke 1.16.0 → 1.18.0

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "yoke",
   "displayName": "Yoke",
-  "version": "1.16.0",
+  "version": "1.18.0",
   "description": "Cross-agent coding harness for Claude, Codex, Gemini, Qwen, OpenCode, Kilo, Pi and Hermes: one curated skill canon plus mechanical safety gates and an autonomous loop via the yoke CLI.",
   "author": { "name": "HECer", "url": "https://github.com/HECer" },
   "homepage": "https://github.com/HECer/yoke#readme",

package/.codex-plugin/plugin.json

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

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # Changelog
 
+## 1.18.0 — 2026-09-27
+
+### Added
+- Add opt-in continuous exploration with evidence-filtered task discovery, validated PRD additions, isolated implementation, bounded history compaction, automatic provider recovery, stop detection, and `yoke loop pause`.
+- Add optional `--explore-limit=<Nh|Nd|Nw>` durations. Exploration remains unbounded when omitted; when the limit expires, Yoke stops launching work and pauses after active workers finish their normal gates and integration.
+
+### Changed
+- Keep exploration status and narrative focused on newly accepted work, the next planned action, provider recovery, and safe stop state.
+- Process finite-duration runs in bounded task batches so the supervisor can honor the deadline while retaining configured parallel workers.
+
+### Migration and validation limits
+- Exploration is opt-in and requires isolated story worktrees. Use `--explore-limit=12h`, `3d`, or `2w` to bound one invocation; expiry exits with code `3`, and a later resume starts a new duration. Without a limit or a user pause, it continues while the process and machine remain available.
+- Auto-discovered work is limited to repository-evidenced proposals that pass confidence, risk, write-scope, acceptance-criteria and criterion-test checks. This does not guarantee project maturity or model quality; provider credentials, configured gates and machine availability still determine progress.
+- A time limit does not interrupt an active story or integration. Active work finishes through the normal gates before the loop stops, so wall-clock completion can exceed the requested duration by the time needed for that safe boundary.
+
+## 1.17.0 — 2026-09-27
+
+### Added
+- Coordinate weighted worker reservations across concurrent Yoke projects under a user-local pool. The default is three units, `YOKE_MAX_PARALLEL_WORKERS` accepts 1–8, and candidate races consume one unit per simultaneous candidate.
+- Add `yoke prd decompose --story=<id>` as a preview-first planner for splitting eligible stories into two independently scheduled children; `--apply` atomically replaces the parent and rewrites downstream dependencies after hash and schema checks.
+- Report shared capacity and resource waits in loop status and the dashboard. Record integration queue wait and duration, and forecast dependency-aware implementation work alongside a serialized integration lane.
+- Add a deterministic local dispatcher benchmark matrix for dependency chains, independent scopes and conflicting scopes.
+
+### Changed
+- Separate implementation slots from each project's integration queue. A completed candidate frees its implementation slot while retaining collision areas and write scopes through rebase, integrated-tree gates, commit and cleanup.
+- Keep single-worker runs on the serial path and reserve a shared unit around each agent invocation; use the dispatcher for multiple workers and competing candidate runs.
+- Cap explicit and configured per-project concurrency at eight. Automatic concurrency remains conservative and is now bounded by the shared cross-project limit.
+
+### Fixed
+- Release the shared claim-operation lease when pool-state parsing throws, so corrupt records fail closed without leaving later pool access stuck behind a leaked lock.
+
+### Migration and validation limits
+- Existing `loop.parallel` values above 8 must be lowered. The default shared cap can queue previously simultaneous project loops; set `YOKE_MAX_PARALLEL_WORKERS` to 1–8 for the desired user-level ceiling. Existing active workers are not cancelled when the cap is lowered.
+- Decomposition requires at least four structured criteria, at least two non-overlapping write scopes and no shared area. Child assessments/quality declarations need task-specific refresh; write scopes remain advisory.
+- Synthetic benchmark results use fixed local delays and make no model quality, token or provider-cost claims. Local release checks: 1,296 tests passed, two skipped across 143 files; lint/build, docs checks, package dry run, Canon validation and dependency audit passed.
+
 ## 1.16.0 — 2026-09-17
 
 ### Added

package/README.md

@@ -1,9 +1,9 @@
 <div align="center">
 
-<h1><img src="https://raw.githubusercontent.com/HECer/yoke/v1.16.0/docs/assets/yoke-logo.png" alt="Yoke" width="100" height="63"></h1>
+<h1><img src="https://raw.githubusercontent.com/HECer/yoke/v1.18.0/docs/assets/yoke-logo.png" alt="Yoke" width="100" height="63"></h1>
 
-<!-- yoke:version:start -->1.16.0<!-- yoke:version:end -->
-<!-- yoke:tests:start -->1287<!-- yoke:tests:end -->
+<!-- yoke:version:start -->1.18.0<!-- yoke:version:end -->
+<!-- yoke:tests:start -->1313<!-- yoke:tests:end -->
 <!-- yoke:skills:start -->34<!-- yoke:skills:end -->
 <!-- yoke:agents:start -->Claude | Codex | Gemini | Qwen | OpenCode | Kilo | Pi | Hermes<!-- yoke:agents:end -->
 
@@ -17,7 +17,7 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](#-license)
 ![Node](https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js&logoColor=white)
 ![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)
-![Tests](https://img.shields.io/badge/tests-1287%20defined-blue.svg)
+![Tests](https://img.shields.io/badge/tests-1313%20defined-blue.svg)
 ![Agents](https://img.shields.io/badge/agents-Claude%20%7C%20Codex%20%7C%20Gemini%20%7C%20Qwen%20%7C%20OpenCode%20%7C%20Kilo%20%7C%20Pi%20%7C%20Hermes-8A2BE2)
 ![Built with TDD](https://img.shields.io/badge/built%20with-TDD%20%2B%20review-ff69b4.svg)
 
@@ -69,7 +69,7 @@ in private, content-addressed local artifacts. Existing projects keep their seri
 safe 2 KiB preview / 8 KiB artifact defaults unless configured otherwise.
 
 Yoke 1.4 introduced opt-in parallel workers and a bounded, reference-driven quality gauntlet.
-Yoke 1.8.0 uses automatic parallelism for tasks with declared write scopes. See [the 1.4 migration guide](docs/MIGRATING-TO-1.4.md)
+Automatic parallelism was introduced in Yoke 1.8.0. This unreleased branch adds a shared cross-project worker pool. See [the 1.4 migration guide](docs/MIGRATING-TO-1.4.md)
 for the new flags, configuration, cleanup behavior, and review-verdict contract.
 
 Yoke 1.1 is safe-by-default: provider CLIs use autonomous sandbox profiles unless `--unsafe`
@@ -198,6 +198,19 @@ Yoke is meant to be operated *by* your coding agent — after a retrofit, the ag
 
 > ⚠️ **Long runs from inside an agent session:** `yoke loop run` has no story cap by default; it continues until every planned story passes or a gate blocks. A multi-story run can therefore outlive most agents' shell-tool timeouts (Claude Code's Bash tool defaults to 2 minutes). If the outer tool call is killed mid-run, you get a stale lock and possibly half-finished state — which *looks* like a hang. Run the loop **in the background** (e.g. Claude Code's `run_in_background`), use `--max=3..5` only when you intentionally want a bounded batch, poll with `yoke loop status`, and after any interrupted run do `yoke loop cleanup` before the next one. A `running` status with no update for 20+ minutes on a claude runner is worth checking — since 0.5.0 the runner streams continuously, so prolonged true silence is no longer normal.
 
+### Optional continuous exploration
+
+`yoke loop run . --explore` keeps the supervisor alive after the PRD drains. It periodically scans
+for evidence-backed, testable improvements, adds only bounded tasks that pass strict contract checks,
+then implements them through the same isolated loop gates. `--explore-interval=10` changes the
+default 30-minute rescan interval. Exploration runs indefinitely by default; set `--explore-limit=12h`,
+`--explore-limit=3d`, or `--explore-limit=2w` to stop automatically after hours, days, or weeks. At
+expiry, Yoke pauses at a safe task boundary, lets active workers finish their gates and integration,
+and exits with code `3`; run it again to resume. `yoke loop pause .` also stops at a safe boundary.
+Failed providers or stories are retried with backoff, and live status heartbeats while the supervisor
+waits. Use `--max=N` for an intentional story-attempt cap. See the [continuous exploration guide](docs/CONTINUOUS-EXPLORATION.md)
+for task validation, history compaction, recovery and process-lifetime limits.
+
 > ⚠️ **Never kill agent processes by name or command-line pattern** (e.g. every process matching `dangerously-skip-permissions`): on a machine running several yoke projects, that takes down the *healthy* runners of the other projects mid-story — they stall and their loops block. `yoke loop cleanup` is the scoped alternative: each watchdog records its pids in the project's `.yoke/runner.pid`, and cleanup kills exactly those recorded trees — nothing else on the machine.
 
 ### Agent cheat sheet — every command is an exit-code contract
@@ -219,7 +232,7 @@ Yoke's CLI is deterministic and chainable by design: an agent (or a shell `&&`)
 | `yoke prd check [dir]` | PRD lint gate (schema, dependencies, cycles, duplicate ids, acceptance) | `0` valid · `1` violations |
 | `yoke change add\|status [dir] [--idea=]` | Queue a change at any time; the loop turns it into append-only stories at the next safe boundary | `0` · `1` invalid inbox/request |
 | `yoke context init\|status [dir]` | Durable context layer (`PROJECT/DECISIONS/KNOWLEDGE/GLOSSARY.md`, optional `CONTEXT-MAP.md`) | `0` |
-| `yoke loop on\|off\|status\|decision\|answer\|resume\|run\|cleanup [dir]` | Autonomous loop; `run` supports `--parallel=N`, bounded reference-driven `--quality`, and blind `--candidates=N` selection; `--max=N` creates an intentional batch cap; `cleanup` retains worktrees unless `--remove-worktrees` is explicit | run: `0` complete · `1` blocked/cap · `2` not runnable / already locked · `3` paused |
+| `yoke loop on\|off\|status\|pause\|decision\|answer\|resume\|run\|cleanup [dir]` | Autonomous loop; `run --explore` opts into continuous discovery, implementation and recovery after a backlog drains; `--parallel=N`, bounded reference-driven `--quality`, and blind `--candidates=N` selection remain available; `--max=N` is an intentional cap; `pause` requests a safe-boundary stop | run: `0` complete · `1` blocked/cap · `2` not runnable / already locked · `3` paused |
 | `yoke review [dir] [--reviewer=] [--base=] [--focus=] [--json] [--allow-self-review]` | An independent model writes a schema-valid verdict | `0` approved · `1` findings/invalid verdict · `2` no independent reviewer |
 | `yoke audit [dir] [--json]` | Dependency, high-confidence secret, and sensitive-change audit | `0` green · `1` blocking findings · `2` not runnable |
 | `yoke design-scan [dir] [--max=N] [--report]` | Static AI-slop design gate | `0` within budget · `1` over |
@@ -464,11 +477,15 @@ observability.
 
 ### Parallel workers and the quality gauntlet
 
-`--parallel=N` dispatches dependency-ready stories concurrently. Claims carry leases, workers use
-isolated worktrees, collision areas are serialized, and only a mechanically green candidate enters
-the FIFO integration queue. Integration repeats the project gates against the merged tree; a worker
-success can never bypass a red integrated result. `yoke loop status` reports the dispatcher,
-workers, providers, worktrees, lifecycle, queue, integrations, and reopened stories.
+`--parallel=N` dispatches dependency-ready stories concurrently. The default maximum is three
+shared worker units across Yoke projects; set `YOKE_MAX_PARALLEL_WORKERS=1..8` to change it.
+`--parallel` and `loop.parallel` accept 1–8. Candidate races consume one unit per simultaneous
+candidate. Claims carry leases, workers use isolated worktrees, collision areas and write scopes stay
+reserved through integration, and only a mechanically green candidate enters the FIFO integration
+queue. Integration has its own serialized lane, so it does not occupy an implementation slot while
+unrelated work proceeds. Integrated-tree gates remain mandatory. `yoke loop status` reports local
+workers, resource waits, shared capacity, integrations, and reopened stories. See
+[parallel execution and safe task decomposition](docs/parallel-execution.md).
 
 Quality is reference-driven and opt-in. Declare what one story should match:
 
@@ -655,8 +672,9 @@ cannot overwrite a shared registry file.
 
 Routing is not free: stories without a matching rule can add a controller call. Measure it
 on your own backlog rather than assuming a win. Routing now also runs within asynchronous
-parallel workers. Automatic parallelism starts at up to three workers when pending tasks declare
-write scopes; unknown scopes and configured tool actions keep execution serial. Isolation is
+parallel workers. Automatic parallelism uses up to the shared worker limit when pending tasks declare
+write scopes; the scheduler still serializes dependencies, collision areas, and overlapping scopes.
+Unknown scopes and configured tool actions keep automatic execution serial. Isolation is
 on by default. Explicit `--parallel=N`, `--no-routing` and `--no-isolate` remain available.
 See [execution defaults and dashboard measurement details](docs/VERIFIED-PROJECTS.md#execution-defaults-in-180).
 
@@ -934,7 +952,7 @@ release provenance.
 ## 🧪 Development
 
 ```bash
-npm test          # vitest (1287 tests)
+npm test          # vitest (1313 tests)
 npm run build     # tsc, no emit errors
 npm run yoke -- validate canon
 ```

package/bench/README.md

@@ -42,6 +42,7 @@ node bench/run-large.mjs --seed=G:\NN-Developed\Yoke-Testground\yoke-codex-study
 node bench/analyze-routing-study.mjs
 node bench/run-matrix.mjs --label=release-1.0
 node bench/output-compaction.mjs  # deterministic local gate-output benchmark; no provider call
+node bench/run-parallel-matrix.mjs # synthetic dispatcher; deterministic local delays, no provider call
 ```
 
 Each run copies the fixture to `bench/.runs/<fixture>-<runner>-<routing>-<stamp>` (or the
@@ -66,6 +67,15 @@ visible test from turning into false benchmark evidence. A seed can provide `ben
 to declare its fixture identity and hidden-test files. `analyze-routing-study.mjs` validates and
 aggregates the checked-in three-pair Codex-only study.
 
+### Parallel dispatcher matrix
+
+`run-parallel-matrix.mjs` exercises the real dispatcher with a deterministic local worker over a
+dependency chain, independent write scopes and conflicting scopes at concurrency 1, 2 and 3. It
+reports wall time, summed worker time, integration queue wait, integration time, attempts and
+accepted results. Fixed delays make scheduler comparisons repeatable; these rows do not measure
+provider latency, token cost, model quality, global cross-project contention or large-repository
+work. Run `npm run build` first so `dist/loop/dispatcher.js` exists.
+
 ## Caveats (read before quoting numbers)
 
 - Agent runs are stochastic. Older rows are N=1; the 2026-08-02 Codex-only study uses three

package/bench/RESULTS.md

@@ -6,6 +6,29 @@ availability, verdict/blocker, conflicts, wall time, iterations, and final fixtu
 Fixture `string-kit` (3 stories, 16 pre-written assertions). Methodology and caveats:
 [README.md](README.md). One row per run — raw JSON in [`results/`](results/).
 
+## Synthetic dispatcher matrix (2026-09-27)
+
+One local run of `node bench/run-parallel-matrix.mjs` after the shared integration pipeline was
+implemented. Each case uses four stories, fixed 120 ms worker and 60 ms integration delays, and no
+provider calls. The measurements exercise dispatcher scheduling only; they are not model or
+repository performance evidence.
+
+| Scenario | Slots | Wall ms | Worker ms (summed) | Integration queue wait ms | Integration ms | Attempts | Accepted |
+|---|---:|---:|---:|---:|---:|---:|---:|
+| Dependency chain | 1 | 788 | 511 | 0 | 271 | 4 | 4 |
+| Dependency chain | 2 | 762 | 498 | 0 | 262 | 4 | 4 |
+| Dependency chain | 3 | 766 | 501 | 0 | 262 | 4 | 4 |
+| Independent scopes | 1 | 566 | 494 | 0 | 274 | 4 | 4 |
+| Independent scopes | 2 | 396 | 512 | 170 | 274 | 4 | 4 |
+| Independent scopes | 3 | 397 | 492 | 258 | 272 | 4 | 4 |
+| Conflicting scopes | 1 | 743 | 492 | 0 | 251 | 4 | 4 |
+| Conflicting scopes | 2 | 753 | 492 | 0 | 262 | 4 | 4 |
+| Conflicting scopes | 3 | 742 | 493 | 0 | 247 | 4 | 4 |
+
+The independent-scope case was about 30% shorter at two or three slots in this one synthetic run.
+Dependency and conflict cases remained effectively serial, as their constraints require. Repeat the
+matrix before drawing conclusions from small timing differences.
+
 ## Runs
 
 | Date | Runner | Model (reported) | Result | Wall-clock | Input tok | Output tok | First-pass stories | src LOC |

package/bench/fixtures/parallel-work/scenarios.json

@@ -0,0 +1,33 @@
+{
+  "workerDurationMs": 120,
+  "integrationDurationMs": 60,
+  "scenarios": [
+    {
+      "id": "dependency-chain",
+      "stories": [
+        { "id": "chain-1", "writes": ["src/chain/one.ts"] },
+        { "id": "chain-2", "needs": ["chain-1"], "writes": ["src/chain/two.ts"] },
+        { "id": "chain-3", "needs": ["chain-2"], "writes": ["src/chain/three.ts"] },
+        { "id": "chain-4", "needs": ["chain-3"], "writes": ["src/chain/four.ts"] }
+      ]
+    },
+    {
+      "id": "independent-scopes",
+      "stories": [
+        { "id": "independent-1", "writes": ["src/independent/one.ts"] },
+        { "id": "independent-2", "writes": ["src/independent/two.ts"] },
+        { "id": "independent-3", "writes": ["src/independent/three.ts"] },
+        { "id": "independent-4", "writes": ["src/independent/four.ts"] }
+      ]
+    },
+    {
+      "id": "conflicting-scopes",
+      "stories": [
+        { "id": "conflict-1", "writes": ["src/shared/registry.ts"] },
+        { "id": "conflict-2", "writes": ["src/shared/registry.ts"] },
+        { "id": "conflict-3", "writes": ["src/shared/registry.ts"] },
+        { "id": "conflict-4", "writes": ["src/shared/registry.ts"] }
+      ]
+    }
+  ]
+}

package/bench/run-parallel-matrix.mjs

@@ -0,0 +1,71 @@
+import { readFileSync } from 'node:fs'
+import { performance } from 'node:perf_hooks'
+import { createDispatcher } from '../dist/loop/dispatcher.js'
+
+const fixture = JSON.parse(readFileSync(new URL('./fixtures/parallel-work/scenarios.json', import.meta.url), 'utf8'))
+const delay = milliseconds => new Promise(resolve => setTimeout(resolve, milliseconds))
+
+async function runCase(scenario, maxConcurrency) {
+  let workerTimeMs = 0
+  let integrationQueueWaitMs = 0
+  let integrationTimeMs = 0
+  const dispatcher = createDispatcher({
+    targetDir: process.cwd(),
+    stories: scenario.stories.map(story => ({ priority: 1, acceptance: [], passes: false, ...story })),
+    maxConcurrency,
+    maxIterations: Infinity,
+    worker: async input => {
+      const started = performance.now()
+      await delay(fixture.workerDurationMs)
+      workerTimeMs += performance.now() - started
+      return {
+        kind: 'candidate',
+        storyId: input.story.id,
+        worktree: input.worktree.path,
+        baseCommit: input.worktree.baseCommit,
+        provider: input.provider,
+        summary: 'synthetic worker complete',
+        evidence: { criteria: [], verify: { passed: true, summary: 'synthetic' } },
+        routing: { outcome: 'pending-integration', recordOutcome() {} },
+      }
+    },
+    claims: { acquire: () => true, heartbeat() {}, release: () => true },
+    worktrees: {
+      create: input => ({ path: `virtual/${input.story.id}`, baseCommit: `base-${input.story.id}` }),
+      remove() {},
+    },
+    git: {
+      isClean: () => true,
+      rebase: () => ({ kind: 'rebased', expectedHead: 'synthetic-head' }),
+      commit() {},
+      integrate: async () => { await delay(fixture.integrationDurationMs) },
+    },
+    gates: { verify: () => ({ passed: true, summary: 'synthetic gate passed' }) },
+    onIntegrationMetrics: (_worker, queueWait, integrationMs) => {
+      if (integrationMs === undefined) integrationQueueWaitMs += queueWait
+      else integrationTimeMs += integrationMs
+    },
+  })
+  const started = performance.now()
+  const result = await dispatcher.run()
+  return {
+    scenario: scenario.id,
+    workers: maxConcurrency,
+    wallMs: Math.round(performance.now() - started),
+    workerMs: Math.round(workerTimeMs),
+    queueWaitMs: Math.round(integrationQueueWaitMs),
+    integrationMs: Math.round(integrationTimeMs),
+    attempts: result.iterations,
+    accepted: result.integrated.length,
+    status: result.status,
+  }
+}
+
+console.log('Synthetic dispatcher matrix; fixed local delays, no model calls or provider quality claims.')
+console.log('scenario,workers,wall_ms,worker_ms,integration_queue_wait_ms,integration_ms,attempts,accepted,status')
+for (const scenario of fixture.scenarios) {
+  for (const workers of [1, 2, 3]) {
+    const result = await runCase(scenario, workers)
+    console.log([result.scenario, result.workers, result.wallMs, result.workerMs, result.queueWaitMs, result.integrationMs, result.attempts, result.accepted, result.status].join(','))
+  }
+}

package/canon/loop/loop-spec.md

@@ -4,7 +4,8 @@ The autonomous loop is optional and toggle-able:
 
 - `yoke loop on` / `yoke loop off` — enable or disable it in `.yoke/config.yaml`.
 - `yoke loop status` — show enabled state and backlog progress.
-- `yoke loop run [--max=N] [--parallel=N] [--isolate] [--decision-policy=auto|critical] [--quality|--no-quality] [--quality-rounds=N] [--quality-minutes=N] [--quality-policy=blocking|advisory] [--quality-unbounded] [--candidates=N]` — run until the current backlog is green or a gate blocks.
+- `yoke loop run [--max=N] [--parallel=N] [--isolate] [--explore] [--explore-interval=N] [--decision-policy=auto|critical] [--quality|--no-quality] [--quality-rounds=N] [--quality-minutes=N] [--quality-policy=blocking|advisory] [--quality-unbounded] [--candidates=N]` — run until the backlog is green or a gate blocks; `--explore` opts into persistent discovery and recovery after each backlog drains.
+- `yoke loop pause` — request a safe-boundary pause from a running loop or exploration supervisor.
 - `yoke change add --idea="..."` — queue a product change at any time, including while the loop is running.
 - `yoke loop decision` / `yoke loop answer --choice=<id>` — inspect and answer a structured critical stop.
 
@@ -13,6 +14,10 @@ story is fast-forwarded to the main tree. Pass `--review` or `--reviewer=<provid
 a separate, schema-validated review. Pass `--parallel=N` to dispatch ready, non-colliding stories
 concurrently. Pass `--json` for NDJSON status on stdout.
 
+With `--explore`, `--explore-limit=12h|3d|2w` optionally stops one invocation after the selected
+duration. The default is unbounded. Expiry stops new work and pauses after active stories complete
+their normal gates and integration; exit code `3` can be resumed with another `yoke loop run`.
+
 Stories may declare a reference, candidate artifact, rubric, and blocking/advisory quality policy.
 `--quality` runs a read-only blind critic plus bounded repair before review; every repair reruns the
 mechanical gates. `--candidates=N` requires quality declarations and dispatches multiple isolated
@@ -48,12 +53,24 @@ For each story:
 7. Only after all gates pass, mark the story `passes: true`, log the decision, and commit
    atomically. A failed commit restores the PRD state.
 8. When all current stories pass, run optional `completion.command` against the integrated
-   system. Only a green result reports `complete`; otherwise the loop blocks. This readiness
-   result is ephemeral, not a release and not a freeze on future changes.
+   system. Only a green result reports `complete`; otherwise the loop blocks. In `--explore` mode
+   a green result starts a read-only exploration pass instead of ending the supervisor. A red
+   completion gate is supplied as evidence to the explorer so it can propose work to resolve the
+   blocker; the gate is never skipped.
+9. Exploration proposals require repository-file evidence, confidence of at least 0.8, low/medium
+   risk, disjoint declared write scopes, and two to five structured acceptance criteria with
+   criterion-targeted approved test commands. Yoke validates and commits accepted PRD changes
+   before isolated implementation. Passed exploration stories are compacted from the active PRD;
+   their full prior contracts remain in Git history and a bounded recent fingerprint ledger
+   prevents near-term duplication.
 
 A supervisor can pause the loop by creating `.yoke/loop.pause`. The running story finishes;
 the dispatcher latches the signal, stops launching new workers, lets active workers reach safe
 terminal proof/cleanup, and exits with code `3` before another story is integrated.
+`--explore` also checks this signal while waiting between scans and during retry backoff. Without
+an explicit `--max` cap, draining the current PRD does not stop exploration; the supervisor waits,
+retries recoverable failures with backoff, and reports the next action. It cannot survive forced
+process or machine termination.
 
 State lives outside model context: PRD, git, and the ignored `.yoke/changes/` inbox. All are
 re-read at story boundaries, so a request queued mid-run becomes additional stories without a

package/canon/manifest.yaml

@@ -1,5 +1,5 @@
 name: yoke-canon
-version: 1.16.0
+version: 1.18.0
 agents: [claude, codex, gemini, qwen, opencode, kilo, pi, hermes]
 skills:
   - { id: tdd, path: skills/tdd, kind: methodology, invocation: auto }

package/dist/cli.js

@@ -9,12 +9,14 @@ import { createProjectGoal, readProjectGoal, runProjectGoal, pauseProjectGoal, g
 import { validateCanon } from './canon/validate.js';
 import { runRetrofit } from './retrofit/command.js';
 import { setLoopEnabled, loopStatus, runLoopCommand } from './loop/run-command.js';
+import { requestLoopPause } from './loop/loop.js';
 import { runContextInit, runContextStatus } from './context/command.js';
 import { runReview } from './review/command.js';
 import { scanDir } from './scan/design.js';
 import { runNew } from './new/command.js';
 import { runPrdDraft, runPrdCheck } from './prd/command.js';
 import { runPrdAssess } from './prd/assess.js';
+import { runPrdDecompose } from './prd/decompose.js';
 import { runLoopCleanup } from './loop/cleanup.js';
 import { runFlowSmoke } from './smoke/command.js';
 import { maybeNotifyUpdate, currentYokeVersion } from './update/check.js';
@@ -102,6 +104,33 @@ export function parseQualityFlags(args) {
         },
     };
 }
+export function parseExploreLimit(value) {
+    const match = /^(\d+)\s*(h|hours?|d|days?|w|weeks?)$/i.exec(value.trim());
+    if (!match)
+        return { ok: false, error: `Invalid --explore-limit value: ${value} (expected a positive duration such as 12h, 3d, or 2w)` };
+    const amount = Number(match[1]);
+    const unit = match[2].toLowerCase();
+    const unitMs = unit.startsWith('h') ? 60 * 60_000 : unit.startsWith('d') ? 24 * 60 * 60_000 : 7 * 24 * 60 * 60_000;
+    const milliseconds = amount * unitMs;
+    if (!Number.isSafeInteger(amount) || amount <= 0 || !Number.isSafeInteger(milliseconds) || Date.now() + milliseconds > 8_640_000_000_000_000) {
+        return { ok: false, error: `Invalid --explore-limit value: ${value} (duration must be positive and within the supported date range)` };
+    }
+    return { ok: true, milliseconds };
+}
+function parseExploreLimitFlag(args, explore) {
+    const values = args.filter(arg => arg.startsWith('--explore-limit='));
+    if (args.includes('--explore-limit'))
+        return { ok: false, error: '--explore-limit requires a duration, for example --explore-limit=12h' };
+    if (values.length > 1)
+        return { ok: false, error: 'Use --explore-limit only once per invocation' };
+    const raw = values[0];
+    if (!raw)
+        return { ok: true };
+    if (!explore)
+        return { ok: false, error: '--explore-limit requires --explore' };
+    const parsed = parseExploreLimit(raw.slice('--explore-limit='.length));
+    return parsed.ok ? { ok: true, milliseconds: parsed.milliseconds } : parsed;
+}
 export function main(argv) {
     const [cmd, ...rest] = argv;
     switch (cmd) {
@@ -357,6 +386,11 @@ export function main(argv) {
                 console.log(loopStatus(targetDir));
                 return 0;
             }
+            if (sub === 'pause') {
+                requestLoopPause(targetDir);
+                console.log('Pause requested at the next safe story or exploration boundary.');
+                return 0;
+            }
             if (sub === 'cleanup')
                 return runLoopCleanup(targetDir, {
                     removeWorktrees: rest.includes('--remove-worktrees'),
@@ -413,7 +447,23 @@ export function main(argv) {
                     console.error(qualityFlags.error);
                     return 1;
                 }
-                return runLoopCommand(targetDir, { ...resumeOptions, ...qualityFlags.options });
+                const explore = rest.includes('--explore');
+                const exploreLimit = parseExploreLimitFlag(rest, explore);
+                if (!exploreLimit.ok) {
+                    console.error(exploreLimit.error);
+                    return 1;
+                }
+                const exploreArg = rest.find(a => a.startsWith('--explore-interval='));
+                if (exploreArg && !explore) {
+                    console.error('--explore-interval requires --explore');
+                    return 1;
+                }
+                const exploreIntervalMinutes = exploreArg ? Number(exploreArg.slice('--explore-interval='.length)) : undefined;
+                if (exploreIntervalMinutes !== undefined && (!Number.isInteger(exploreIntervalMinutes) || exploreIntervalMinutes < 1 || exploreIntervalMinutes > 1_440)) {
+                    console.error(`Invalid --explore-interval value: ${exploreArg} (expected 1..1440 minutes)`);
+                    return 1;
+                }
+                return runLoopCommand(targetDir, { ...resumeOptions, ...qualityFlags.options, ...(explore ? { explore: true } : {}), ...(exploreIntervalMinutes !== undefined ? { exploreIntervalMinutes } : {}), ...(exploreLimit.milliseconds !== undefined ? { exploreLimitMs: exploreLimit.milliseconds } : {}) });
             }
             if (sub === 'answer') {
                 const choice = rest.find(a => a.startsWith('--choice='))?.slice('--choice='.length);
@@ -511,8 +561,8 @@ export function main(argv) {
                 const permissions = rest.includes('--unsafe') ? 'unsafe' : undefined;
                 const parallelArg = rest.find(a => a.startsWith('--parallel='));
                 const parallel = parallelArg && parallelArg !== '--parallel=auto' ? Number(parallelArg.slice('--parallel='.length)) : undefined;
-                if (parallel !== undefined && (!Number.isInteger(parallel) || parallel < 1)) {
-                    console.error(`Invalid --parallel value: ${parallelArg}`);
+                if (parallel !== undefined && (!Number.isInteger(parallel) || parallel < 1 || parallel > 8)) {
+                    console.error(`Invalid --parallel value: ${parallelArg} (expected 1..8)`);
                     return 1;
                 }
                 const json = rest.includes('--json');
@@ -542,9 +592,29 @@ export function main(argv) {
                     console.error(qualityFlags.error);
                     return 1;
                 }
-                return runLoopCommand(targetDir, { maxIterations: rawMax, agent, isolate, resumeWorktree: rest.includes('--resume-worktree'), parallel, parallelAuto: parallelArg === '--parallel=auto', reviewer, review, allowSelfReview, timeoutMinutes, json, routing, onAmbiguity: oaArg, decisionPolicy: dpArg, permissions, ...qualityFlags.options });
+                const explore = rest.includes('--explore');
+                const exploreLimit = parseExploreLimitFlag(rest, explore);
+                if (!exploreLimit.ok) {
+                    console.error(exploreLimit.error);
+                    return 1;
+                }
+                const exploreArg = rest.find(a => a.startsWith('--explore-interval='));
+                if (exploreArg && !explore) {
+                    console.error('--explore-interval requires --explore');
+                    return 1;
+                }
+                const exploreIntervalMinutes = exploreArg ? Number(exploreArg.slice('--explore-interval='.length)) : undefined;
+                if (exploreIntervalMinutes !== undefined && (!Number.isInteger(exploreIntervalMinutes) || exploreIntervalMinutes < 1 || exploreIntervalMinutes > 1_440)) {
+                    console.error(`Invalid --explore-interval value: ${exploreArg} (expected 1..1440 minutes)`);
+                    return 1;
+                }
+                if (explore && rest.includes('--resume-worktree')) {
+                    console.error('--explore starts its own safe resume cycle; remove --resume-worktree and re-run it after resolving the retained story.');
+                    return 1;
+                }
+                return runLoopCommand(targetDir, { maxIterations: rawMax, agent, isolate, resumeWorktree: rest.includes('--resume-worktree'), parallel, parallelAuto: parallelArg === '--parallel=auto', reviewer, review, allowSelfReview, timeoutMinutes, json, routing, onAmbiguity: oaArg, decisionPolicy: dpArg, permissions, ...(explore ? { explore: true } : {}), ...(exploreIntervalMinutes !== undefined ? { exploreIntervalMinutes } : {}), ...(exploreLimit.milliseconds !== undefined ? { exploreLimitMs: exploreLimit.milliseconds } : {}), ...qualityFlags.options });
             }
-            console.log(`usage: yoke loop <on|off|status|decision|answer|resume [--discard] [--quality|--no-quality] [--quality-rounds=N] [--quality-minutes=N] [--quality-policy=<blocking|advisory>] [--quality-unbounded] [--candidates=N]|cleanup [--remove-worktrees] [--discard-stale-recovery]|run [--max=N] [--parallel=<auto|N>] [--runner=<${AGENT_LIST}>] [--reviewer=<${AGENT_LIST}>] [--review] [--allow-self-review] [--routing|--no-routing] [--isolate|--no-isolate] [--unsafe] [--timeout=<minutes>] [--decision-policy=<auto|critical>] [--quality|--no-quality] [--quality-rounds=N] [--quality-minutes=N] [--quality-policy=<blocking|advisory>] [--quality-unbounded] [--candidates=N] [--json]> [targetDir]`);
+            console.log(`usage: yoke loop <on|off|status|pause|decision|answer|resume [--discard] [--explore] [--explore-interval=<minutes>] [--explore-limit=<Nh|Nd|Nw>] [--quality|--no-quality] [--quality-rounds=N] [--quality-minutes=N] [--quality-policy=<blocking|advisory>] [--quality-unbounded] [--candidates=N]|cleanup [--remove-worktrees] [--discard-stale-recovery]|run [--max=N] [--explore] [--explore-interval=<minutes>] [--explore-limit=<Nh|Nd|Nw>] [--parallel=<auto|N>] [--runner=<${AGENT_LIST}>] [--reviewer=<${AGENT_LIST}>] [--review] [--allow-self-review] [--routing|--no-routing] [--isolate|--no-isolate] [--unsafe] [--timeout=<minutes>] [--decision-policy=<auto|critical>] [--quality|--no-quality] [--quality-rounds=N] [--quality-minutes=N] [--quality-policy=<blocking|advisory>] [--quality-unbounded] [--candidates=N] [--json]> [targetDir]`);
             return 1;
         }
         case 'new': {
@@ -581,6 +651,25 @@ export function main(argv) {
                 }
                 return runPrdAssess(targetDir, { runner: runner, story: rest.find(a => a.startsWith('--story='))?.slice('--story='.length), reassess: rest.includes('--reassess') });
             }
+            if (sub === 'decompose') {
+                const story = rest.find(a => a.startsWith('--story='))?.slice('--story='.length);
+                if (!story) {
+                    console.error('usage: yoke prd decompose [dir] --story=<id> [--apply] [--runner=<agent>] [--timeout=<minutes>]');
+                    return 1;
+                }
+                const runner = rest.find(a => a.startsWith('--runner='))?.slice('--runner='.length);
+                if (runner && !SUPPORTED_AGENTS.includes(runner)) {
+                    console.error('Invalid planning runner');
+                    return 1;
+                }
+                const timeoutArg = rest.find(a => a.startsWith('--timeout='));
+                const timeoutMinutes = timeoutArg ? Number(timeoutArg.slice('--timeout='.length)) : undefined;
+                if (timeoutMinutes !== undefined && (!Number.isFinite(timeoutMinutes) || timeoutMinutes < 0)) {
+                    console.error(`Invalid --timeout value: ${timeoutArg}`);
+                    return 1;
+                }
+                return runPrdDecompose(targetDir, { story, apply: rest.includes('--apply'), runner: runner, timeoutMinutes });
+            }
             if (sub === 'draft') {
                 const idea = rest.find(a => a.startsWith('--idea='))?.slice('--idea='.length);
                 if (!idea) {
@@ -607,7 +696,7 @@ export function main(argv) {
             }
             if (sub === 'check')
                 return runPrdCheck(targetDir);
-            console.log(`usage: yoke prd <draft|check|assess> [dir] [--idea="..."] [--runner=<${AGENT_LIST}>] [--story=<id>] [--reassess] [--force] [--timeout=<minutes>]`);
+            console.log(`usage: yoke prd <draft|check|assess|decompose> [dir] [--idea="..."] [--runner=<${AGENT_LIST}>] [--story=<id>] [--apply] [--reassess] [--force] [--timeout=<minutes>]`);
             return 1;
         }
         case 'context': {
@@ -671,7 +760,7 @@ export function main(argv) {
             return runUpgrade();
         default:
             console.log('Project workflows: yoke check [dir] [--json|--protect] | goal set|run|resume|pause|status|handoff|budget [dir] | projects add|list|remove | dashboard [dir] [--port=N]');
-            console.log(`usage: yoke <setup [dir] | new <dir> [--idea="..."] | validate [canonDir] | retrofit [targetDir] [--agent=${AGENT_LIST}|all] [--code-graph=graphify|serena] [--code-intelligence=off|shadow|active] [--loop] | change <add|status> [dir] | code-intelligence-server --workspace=<dir> --mode=<mode> | prd <draft|check|assess> [dir] | loop <on|off|status|decision|answer|resume|run|cleanup> | context <init|status> | review [dir] | design-scan [dir] | flow-smoke [dir] | upgrade>`);
+            console.log(`usage: yoke <setup [dir] | new <dir> [--idea="..."] | validate [canonDir] | retrofit [targetDir] [--agent=${AGENT_LIST}|all] [--code-graph=graphify|serena] [--code-intelligence=off|shadow|active] [--loop] | change <add|status> [dir] | code-intelligence-server --workspace=<dir> --mode=<mode> | prd <draft|check|assess|decompose> [dir] | loop <on|off|status|decision|answer|resume|run|cleanup> | context <init|status> | review [dir] | design-scan [dir] | flow-smoke [dir] | upgrade>`);
             return cmd ? 1 : 0;
     }
 }

package/dist/dashboard/panels.js

@@ -101,7 +101,9 @@ function renderNow(p){
   summary.append(el('p','Last status: '+(status.updatedAt||'Unknown')+(state.stale?' · stale; activity is not confirmed':''),'muted'));
   if(status.progress)summary.append(el('p','Backlog: '+status.progress.passed+'/'+status.progress.total+' tasks accepted · not overall product completion','muted'));
   for(const proc of status.supervision||[])summary.append(row('Provider PID '+(proc.childPid||'not started'),['Attempt: '+((proc.retry||0)+1),'Supervisor heartbeat: '+proc.heartbeatAt,'Last output: '+(proc.lastOutputAt||'none'),'Last successful tool/edit: '+(proc.lastProgressAt||'none'),proc.reason].filter(Boolean).join(' · '),proc.state+' · '+(proc.liveness||'identity unverified')));
-  summary.append(el('p','Reported workers: '+workers.length+' / '+(status.parallel?.maxConcurrency||1)+' · queue: '+tokenText(status.parallel?.queuedCandidates),'muted'));
+  summary.append(el('p','Reported workers: '+workers.length+' / '+(status.parallel?.maxConcurrency||1)+' · '+(status.parallel?.waitingWorkers||0)+' waiting · integrations queued: '+tokenText(status.parallel?.queuedIntegrations??status.parallel?.queuedCandidates),'muted'));
+  const pool=status.parallel?.globalPool;if(pool)summary.append(el('p','Shared worker pool: '+pool.activeUnits+' / '+pool.limit+' units · implementation '+pool.activeByRole.implementation+' · integration '+pool.activeByRole.integration+' · '+pool.waitingWorkers+' waiting across Yoke projects.','muted'));
+  if(p.estimate?.available)summary.append(el('p','Forecast: up to '+p.estimate.maxConcurrency+' implementation slots · '+p.estimate.globalLimit+' shared units · '+p.estimate.workerUnitsPerStory+' unit(s) per story · one serial integration lane · '+duration(p.estimate.implementationWorkMs)+' worker time · '+duration(p.estimate.integrationLaneMs)+' integration · '+duration(p.estimate.integrationQueueWaitMs)+' queue wait'+(p.estimate.integrationSampleCount?' · '+p.estimate.integrationSampleCount+' integration samples':' · integration history unavailable')+'.','muted'));
   if(goal.pendingAttempt)summary.append(row('Goal attempt',goal.pendingAttempt.provider+' · requested model '+(goal.pendingAttempt.model||'provider default')+' · started '+goal.pendingAttempt.startedAt,state.stale?'unconfirmed':'running'));
   if(status.execution&&status.state==='running')summary.append(el('p',state.stale?'Execution was reported but is now unconfirmed.':status.execution.provider+' · requested model '+(status.execution.requestedModel||'provider default')+' · elapsed '+duration(Date.now()-Date.parse(status.execution.startedAt))));
   if(status.story&&!workers.length)summary.append(row(status.storyTitle||status.story,status.phase||'Phase unknown',reportedState));

package/dist/dashboard/server.js

@@ -19,7 +19,8 @@ import { DASHBOARD_LIMITS, DashboardChangePayloadSchema, DashboardControlPayload
 const text = z.string().max(16000);
 const number = z.number().finite().nonnegative();
 const Goal = z.object({ objective: text, status: z.enum(['active', 'running', 'paused', 'blocked', 'complete']), reason: text.optional(), pendingAttempt: z.object({ provider: text, model: text.optional(), startedAt: text }).optional(), attempts: z.array(z.object({ durationMs: number.optional(), provider: text.optional(), success: z.boolean().optional(), summary: text.optional(), inputTokens: number.optional(), outputTokens: number.optional() })).max(200).default([]) });
-const Status = z.object({ state: text, phase: text.optional(), reason: text.optional(), progress: z.object({ passed: number, total: number }).optional(), tokens: z.object({ inputTokens: number, outputTokens: number, totalCostUsd: number.optional(), measurementComplete: z.boolean().optional(), model: text.optional(), calls: z.array(z.object({ usageAvailable: z.boolean().optional() })).max(10000).optional() }).optional(), measurement: z.object({ costAvailable: z.enum(['unknown', 'partial', 'measured']), measuredCalls: number.optional(), unknownCalls: number.optional(), unmeasuredAttempts: number.optional() }).passthrough().optional(), parallel: z.object({ maxConcurrency: number }).passthrough().optional() }).passthrough();
+const PoolStatus = z.object({ limit: number, activeUnits: number, activeWorkers: number, waitingWorkers: number, activeByRole: z.object({ implementation: number, integration: number }), oldestWaitMs: number });
+const Status = z.object({ state: text, phase: text.optional(), reason: text.optional(), progress: z.object({ passed: number, total: number }).optional(), tokens: z.object({ inputTokens: number, outputTokens: number, totalCostUsd: number.optional(), measurementComplete: z.boolean().optional(), model: text.optional(), calls: z.array(z.object({ usageAvailable: z.boolean().optional() })).max(10000).optional() }).optional(), measurement: z.object({ costAvailable: z.enum(['unknown', 'partial', 'measured']), measuredCalls: number.optional(), unknownCalls: number.optional(), unmeasuredAttempts: number.optional() }).passthrough().optional(), parallel: z.object({ maxConcurrency: number, workerUnitsPerStory: number.optional(), globalPool: PoolStatus.optional() }).passthrough().optional() }).passthrough();
 const Stories = z.array(z.object({ id: text, title: text, passes: z.boolean(), priority: number.optional(), area: text.optional(), writes: z.array(text).optional(), needs: z.array(text).optional() })).max(2000);
 const Check = z.object({ id: text, status: z.enum(['passed', 'failed', 'unverified']), generatedAt: text, summary: text, criteria: z.array(z.object({ id: text, text, status: z.enum(['passed', 'failed', 'unverified']), summary: text })).max(500) });
 const Durations = z.array(z.object({ storyId: text, ms: number.positive() })).max(5000);
@@ -122,6 +123,7 @@ function snapshot(project, detail) {
     const status = read('.yoke/loop-status.json', Status);
     const stories = detail ? read('.yoke/prd.yaml', Stories, true) ?? [] : [];
     const history = detail ? read('.yoke/story-durations.json', Durations) ?? [] : [];
+    const events = detail && !project.error ? readEvents(project.root, DASHBOARD_LIMITS.events) : [];
     let check = null;
     if (detail && !project.error) {
         try {
@@ -140,7 +142,14 @@ function snapshot(project, detail) {
                 errors.push(error.message);
         }
     }
-    return { ...project, goal, status, errors, ...(detail ? { stories, check, events: project.error ? [] : readEvents(project.root, DASHBOARD_LIMITS.events), estimate: estimateSchedule(stories, Math.max(1, status?.parallel?.maxConcurrency ?? 1), history) } : {}) };
+    const localCapacity = Math.max(1, status?.parallel?.maxConcurrency ?? 1);
+    const estimate = estimateSchedule(stories, localCapacity, history, {
+        integrationMs: events.filter(event => event.type === 'phase-ended' && event.phase === 'integration').map(event => event.durationMs ?? 0),
+        integrationQueueWaitMs: events.filter(event => event.type === 'phase-ended' && event.phase === 'integration-queue').map(event => event.durationMs ?? 0),
+        globalLimit: Math.max(1, status?.parallel?.globalPool?.limit ?? localCapacity),
+        workerUnitsPerStory: Math.max(1, status?.parallel?.workerUnitsPerStory ?? 1),
+    });
+    return { ...project, goal, status, errors, ...(detail ? { stories, check, events, estimate } : {}) };
 }
 export async function startDashboard(options = {}) {
     const token = randomBytes(32).toString('hex');