@hecer/yoke 1.17.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.17.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.17.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,20 @@
 # 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

package/README.md

@@ -1,9 +1,9 @@
 <div align="center">
 
-<h1><img src="https://raw.githubusercontent.com/HECer/yoke/v1.17.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.17.0<!-- yoke:version:end -->
-<!-- yoke:tests:start -->1298<!-- 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-1298%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)
 
@@ -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 |
@@ -939,7 +952,7 @@ release provenance.
 ## 🧪 Development
 
 ```bash
-npm test          # vitest (1298 tests)
+npm test          # vitest (1313 tests)
 npm run build     # tsc, no emit errors
 npm run yoke -- validate canon
 ```

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.17.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,6 +9,7 @@ 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';
@@ -103,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) {
@@ -358,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'),
@@ -414,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);
@@ -543,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': {

package/dist/loop/git.js

@@ -1,6 +1,6 @@
 import { execFileSync } from 'node:child_process';
 import { sanitizeCommitMessage } from './identity.js';
-export const RUNTIME_PATHS = [".yoke/supervision", ".yoke/provider-processes", '.yoke/artifacts', '.yoke/events', '.yoke/history', '.yoke/routing', '.yoke/checks', '.yoke/goal.json', '.yoke/goal.pause', '.yoke/loop-status.json', '.yoke/loop.lock', '.yoke/loop.lock.takeover', '.yoke/loop.lock.takeover.recovery', '.yoke/runner.pid', '.yoke/story-durations.json'];
+export const RUNTIME_PATHS = [".yoke/supervision", ".yoke/provider-processes", '.yoke/artifacts', '.yoke/events', '.yoke/history', '.yoke/routing', '.yoke/checks', '.yoke/goal.json', '.yoke/goal.pause', '.yoke/loop.pause', '.yoke/loop-status.json', '.yoke/loop.lock', '.yoke/loop.lock.takeover', '.yoke/loop.lock.takeover.recovery', '.yoke/runner.pid', '.yoke/story-durations.json'];
 // Directory pathspecs include descendants and also exclude the directory entry.
 export const RUNTIME_EXCLUDES = RUNTIME_PATHS.map(path => `:(exclude)${path}`);
 export function stageImplementation(dir) {

package/dist/loop/loop.js

@@ -1,5 +1,5 @@
 import { knownInfrastructureFailure } from "../routing/capability.js";
-import { existsSync, unlinkSync, readFileSync } from 'node:fs';
+import { existsSync, unlinkSync, readFileSync, mkdirSync, writeFileSync } from 'node:fs';
 import { acceptanceProtectionProblem } from '../check/command.js';
 import { join, relative } from 'node:path';
 import { isAcceptanceCriterion, loadPrd, savePrd, selectNextStory, allPass, progress, storyPathSegment } from './prd.js';
@@ -102,6 +102,18 @@ function runQualityReview(opts, executionDir, story, reporter) {
 export function pauseFilePath(targetDir) {
     return join(targetDir, '.yoke', 'loop.pause');
 }
+/** Request a pause at the next safe story or exploration boundary. */
+export function requestLoopPause(targetDir) {
+    const file = pauseFilePath(targetDir);
+    mkdirSync(join(targetDir, '.yoke'), { recursive: true });
+    try {
+        writeFileSync(file, `${new Date().toISOString()}\n`, { flag: 'wx' });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+}
 function consumePause(targetDir) {
     const file = pauseFilePath(targetDir);
     if (!existsSync(file))

package/dist/loop/prd.js

@@ -11,6 +11,15 @@ export const AcceptanceCriterionSchema = z.object({
     text: z.string().min(1),
     verify: z.array(z.string().min(1)).min(1),
 });
+export const ExplorationOriginSchema = z.object({
+    version: z.literal(1),
+    rationale: z.string().min(1).max(2_000),
+    expectedBenefit: z.string().min(1).max(2_000),
+    confidence: z.number().min(0.8).max(1),
+    risk: z.enum(['low', 'medium']),
+    evidence: z.array(z.object({ path: z.string().min(1).max(500), observation: z.string().min(1).max(1_000) }).strict()).min(1).max(6),
+    discoveredAt: z.string().datetime(),
+}).strict();
 export function criterionCommandProblem(criterion) {
     const normalizedId = criterion.id.toLowerCase().replace(/[^a-z0-9]/g, '');
     for (const raw of criterion.verify) {
@@ -46,6 +55,8 @@ export const StorySchema = z.object({
     agent: AgentSchema.optional(),
     /** Inbox request that created this story. Used for idempotent append-only intake. */
     sourceChange: z.string().min(1).optional(),
+    /** Evidence retained for stories created by opt-in continuous exploration. */
+    exploration: ExplorationOriginSchema.optional(),
     quality: StoryQualityDeclarationSchema.optional(),
     assessment: AssessmentSchema.optional(),
     /** Binding to the task, upstream contracts and approved planning brief. */

package/dist/loop/reporter.js

@@ -220,10 +220,12 @@ export function makeReporter(dir, opts = {}, now = () => new Date()) {
             persist({ ...base, state: 'running', phase: undefined, story: story.id, storyTitle: story.title,
                 progress, ...(eta ? { eta } : {}), updatedAt: now().toISOString() }, 'story-done', `✓ ${story.id} done${took} — ${progress.passed}/${progress.total} (${percentOf(progress)}%)${hint}`);
         },
-        phase(phase) {
-            if (!current)
-                return;
-            persist({ ...current, phase, updatedAt: now().toISOString() }, phase, `  · ${phase}…`);
+        phase(phase, reason, progress) {
+            const status = current ?? emptyStatus(now().toISOString());
+            const base = phase === 'exploring' || phase === 'waiting-exploration' || phase === 'waiting-recovery'
+                ? (({ story: _story, storyTitle: _storyTitle, ...withoutStory }) => withoutStory)(status)
+                : status;
+            persist({ ...base, state: 'running', phase, ...(progress ? { progress } : {}), ...(reason ? { reason } : { reason: undefined }), updatedAt: now().toISOString() }, phase, `  · ${phase}…`);
         },
         blocked(reason) {
             const base = current ?? emptyStatus(now().toISOString());
@@ -237,9 +239,9 @@ export function makeReporter(dir, opts = {}, now = () => new Date()) {
             persist({ ...withoutParallel(current ?? emptyStatus(now().toISOString())), state: 'cap-reached', phase: undefined,
                 progress, updatedAt: now().toISOString() }, 'cap-reached', `◾ iteration cap reached — ${progress.passed}/${progress.total}`);
         },
-        paused(progress) {
+        paused(progress, reason) {
             persist({ ...withoutParallel(current ?? emptyStatus(now().toISOString())), state: 'paused', phase: undefined,
-                progress, updatedAt: now().toISOString() }, 'paused', `⏸ loop paused — ${progress.passed}/${progress.total}`);
+                progress, ...(reason ? { reason } : {}), updatedAt: now().toISOString() }, 'paused', `⏸ loop paused — ${progress.passed}/${progress.total}`);
         },
         quality(status) {
             const base = current ?? emptyStatus(now().toISOString());