@hecer/yoke 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.8.0 — 2026-07-20
+
+### Added
+- **Live progress + ETA.** Story completions are now first-class events: the console shows
+  `✓ S6 done in 4m28s — 20/45 (44%) · ~1h40m left`, every status (file, NDJSON stream,
+  `yoke loop status`) carries `percent` and an `eta` block. The estimate averages the
+  durations of stories completed **in this run** (current velocity) and falls back to the
+  persisted history of previous runs (`.yoke/story-durations.json`, last 50, gitignored).
+  No data → no estimate, never an invented one.
+- **Ambiguity policy** (`loop.onAmbiguity` / `--on-ambiguity=<resolve|abort>`). The runner
+  prompt now always forbids asking questions (a loop run has nobody to answer). Default
+  `resolve`: the agent settles ambiguous criteria itself, states the interpretation, and the
+  loop never stops. Opt-in `abort`: the agent writes its open questions to
+  `.yoke/ambiguity.md` and stops; the loop consumes the file, skips verify (an unimplemented
+  story would otherwise pass on pre-existing green tests), and blocks with the question as
+  the reason. Companion principle: clarifying questions belong in the planning round, before
+  the loop starts.
+
 ## 0.7.0 — 2026-07-17
 
 ### Added

package/README.md

@@ -323,12 +323,18 @@ The loop stops when every story is `passes: true`. State lives **outside the mod
 
 Every iteration emits token-free, harness-side feedback (Node console + local files — **zero agent tokens**):
 
-- **Live console** — `▶ S6 (19/45) — implementing… · verifying… ✔ committed → 20/45`.
-- **`.yoke/loop-status.json`** — the current state; read it any time with `yoke loop status`:
+- **Live console with progress + ETA** —
+  `▶ S6 (19/45 · 42%) — implementing… · ~1h44m left (Ø 4m/story)` … `✓ S6 done in 4m28s — 20/45 (44%) · ~1h40m left`.
+  The estimate uses the **average duration of stories completed in this run** (current
+  velocity); before the first story lands it falls back to the recorded history of previous
+  runs (`.yoke/story-durations.json`, last 50 stories, gitignored). No data yet → no estimate,
+  never a made-up one.
+- **`.yoke/loop-status.json`** — the current state (now including `percent` and an `eta`
+  block); read it any time with `yoke loop status`:
   ```
-  Loop: BLOCKED on S5 "Segment schemas"
-    verifying · iteration 19 · 18/45 · updated 2026-06-29T10:00:00.000Z
-    reason: story did not verify (working tree has uncommitted changes — review/clean before re-running)
+  Loop: RUNNING on S6 "Weekly digest"
+    implementing · iteration 20 · 19/45 (42%) · updated 30s ago
+    ~1h44m remaining (Ø 4m/story)
   ```
 - **`.yoke/loop.log`** — an append-only timeline of every phase transition.
 - **`--json`** — machine mode for supervisors: every status write is *also* emitted as one
@@ -355,14 +361,34 @@ A per-iteration **idle timeout** guards against a genuinely hung agent: if the a
 output is **never** killed — the output stream *is* the liveness signal. Set a project default
 with `loop.timeoutMinutes` in `.yoke/config.yaml`.
 
+### Ambiguous stories: questions belong in planning
+
+A loop run has nobody to ask, so the runner prompt always forbids questions. What the agent
+does when an acceptance criterion is genuinely ambiguous is configurable:
+
+- **Default (`resolve`) — never stop:** the agent picks the interpretation most consistent
+  with the other criteria and the existing code, states it in its final message, and the loop
+  keeps going.
+- **Strict (`abort`):** the agent must not guess — it writes its open question(s) to
+  `.yoke/ambiguity.md` and stops. The loop consumes that file, skips verify (an unimplemented
+  story would otherwise sail through on pre-existing green tests), and blocks with the
+  question in the reason, e.g.
+  `story S6 stopped: ambiguous acceptance criteria — Which auth provider should S6 use?`
+  Answer by sharpening the story's acceptance criteria, then re-run.
+
+Enable strict mode per run with `yoke loop run . --on-ambiguity=abort` or per project with
+`loop.onAmbiguity: abort` in `.yoke/config.yaml`. Either way, the cheapest fix is upstream:
+put every clarifying question into the PRD **before** the loop starts (`yoke prd draft`
+criteria must be testable and decision-free).
+
 The loop trusts **verify**, not the agent's exit code: a story whose tests are green is
 committed even if the agent process exited non-zero (a common Windows `.cmd`-wrapper ghost).
 A failing verify is retried up to `verify.retries` times (default 1) so a transient flake
 self-heals while a real failure still blocks.
 
-`.yoke/loop-status.json`, `.yoke/loop.log`, and `.yoke/loop.lock` are runtime artifacts;
-`yoke retrofit` gitignores them (along with `.yoke/worktrees/`, `.yoke/backup/`, and
-`.yoke/proof/`) so they never trip the clean-tree gate.
+`.yoke/loop-status.json`, `.yoke/loop.log`, `.yoke/loop.lock`, `.yoke/story-durations.json`,
+and `.yoke/ambiguity.md` are runtime artifacts; `yoke retrofit` gitignores them (along with
+`.yoke/worktrees/`, `.yoke/backup/`, and `.yoke/proof/`) so they never trip the clean-tree gate.
 
 ### Single-flight guard + cleanup
 

package/dist/cli.js

@@ -127,9 +127,14 @@ function main(argv) {
                     }
                     timeoutMinutes = v;
                 }
-                return runLoopCommand(targetDir, { maxIterations: rawMax, agent, isolate, reviewer, review, timeoutMinutes, json });
+                const oaArg = rest.find(a => a.startsWith('--on-ambiguity='))?.slice('--on-ambiguity='.length);
+                if (oaArg && oaArg !== 'resolve' && oaArg !== 'abort') {
+                    console.error(`Invalid --on-ambiguity value: ${oaArg} (expected resolve|abort)`);
+                    return 1;
+                }
+                return runLoopCommand(targetDir, { maxIterations: rawMax, agent, isolate, reviewer, review, timeoutMinutes, json, onAmbiguity: oaArg });
             }
-            console.log('usage: yoke loop <on|off|status|cleanup|run [--max=N] [--runner=<claude|codex|gemini>] [--reviewer=<claude|codex|gemini>] [--review] [--isolate] [--timeout=<minutes>] [--json]> [targetDir]');
+            console.log('usage: yoke loop <on|off|status|cleanup|run [--max=N] [--runner=<claude|codex|gemini>] [--reviewer=<claude|codex|gemini>] [--review] [--isolate] [--timeout=<minutes>] [--on-ambiguity=<resolve|abort>] [--json]> [targetDir]');
             return 1;
         }
         case 'new': {

package/dist/loop/loop.js

@@ -1,4 +1,4 @@
-import { existsSync, unlinkSync } from 'node:fs';
+import { existsSync, unlinkSync, readFileSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import { loadPrd, savePrd, selectNextStory, allPass, progress } from './prd.js';
 import { stopTheLineGate, preDispatchGate } from './gates.js';
@@ -19,6 +19,29 @@ function blockReason(base, targetDir, git) {
 export function pauseFilePath(targetDir) {
     return join(targetDir, '.yoke', 'loop.pause');
 }
+// Abort channel for an agent that hits genuinely undecidable acceptance criteria
+// (only instructed to use it under loop.onAmbiguity: abort). Honoured whenever
+// present: without this check, an agent that stopped without changes would sail
+// through verify on pre-existing green tests and be falsely marked done.
+export function ambiguityFilePath(dir) {
+    return join(dir, '.yoke', 'ambiguity.md');
+}
+function consumeAmbiguity(dir) {
+    const file = ambiguityFilePath(dir);
+    if (!existsSync(file))
+        return null;
+    let content = '';
+    try {
+        content = readFileSync(file, 'utf8');
+    }
+    catch { /* the signal alone still blocks */ }
+    try {
+        unlinkSync(file);
+    }
+    catch { /* best-effort consume */ }
+    const compact = content.replace(/\s+/g, ' ').trim().slice(0, 500);
+    return compact || 'agent reported ambiguous acceptance criteria without details';
+}
 export function runLoop(opts) {
     let iterations = 0;
     const reporter = opts.reporter ?? noopReporter;
@@ -67,12 +90,19 @@ export function runLoop(opts) {
         if (opts.isolate) {
             const wt = join(opts.targetDir, '.yoke', 'worktrees', story.id);
             const wtPrd = join(wt, relative(opts.targetDir, opts.prdPath));
+            let landed = null;
             try {
                 opts.git.addWorktree(opts.targetDir, wt);
                 const result = opts.runner({ targetDir: wt, story });
                 iterations++;
                 if (result.tokens)
                     reporter.addTokens(result.tokens);
+                const ambiguity = consumeAmbiguity(wt);
+                if (ambiguity) {
+                    const reason = `story ${story.id} stopped: ambiguous acceptance criteria — ${ambiguity}`;
+                    reporter.blocked(reason);
+                    return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                }
                 // Verify is the source of truth — NOT the runner's exit code. A spurious non-zero
                 // exit (e.g. a Windows .cmd wrapper ghost) must not block a story whose tests are green.
                 reporter.phase('verifying');
@@ -121,6 +151,7 @@ export function runLoop(opts) {
                 savePrd(wtPrd, updated);
                 opts.git.commitAll(wt, `yoke: complete ${story.id} ${story.title}`);
                 opts.git.integrate(opts.targetDir, wt);
+                landed = progress(updated);
             }
             catch (e) {
                 const reason = blockReason(`isolated iteration failed for ${story.id}: ${e.message}`, opts.targetDir, opts.git);
@@ -133,12 +164,20 @@ export function runLoop(opts) {
                 }
                 catch { /* cleanup is best-effort */ }
             }
+            if (landed)
+                reporter.storyDone({ id: story.id, title: story.title }, landed);
             continue;
         }
         const result = opts.runner({ targetDir: opts.targetDir, story });
         iterations++;
         if (result.tokens)
             reporter.addTokens(result.tokens);
+        const ambiguity = consumeAmbiguity(opts.targetDir);
+        if (ambiguity) {
+            const reason = `story ${story.id} stopped: ambiguous acceptance criteria — ${ambiguity}`;
+            reporter.blocked(reason);
+            return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+        }
         // Verify is the source of truth — NOT the runner's exit code. A spurious non-zero
         // exit (e.g. a Windows .cmd wrapper ghost) must not block a story whose tests are green.
         reporter.phase('verifying');
@@ -211,5 +250,6 @@ export function runLoop(opts) {
                 finalProgress: progress(stories),
             };
         }
+        reporter.storyDone({ id: story.id, title: story.title }, progress(updated));
     }
 }

package/dist/loop/reporter.js

@@ -23,6 +23,39 @@ export function appendLog(dir, line, capBytes = LOG_CAP_BYTES) {
     const trimmed = nl >= 0 ? tail.slice(nl + 1) : tail;
     writeFileSync(file, `# … loop.log truncated …\n${trimmed}`);
 }
+export function fmtDuration(ms) {
+    const s = Math.max(0, Math.round(ms / 1000));
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return s % 60 > 0 ? `${m}m${s % 60}s` : `${m}m`;
+    const h = Math.floor(m / 60);
+    return m % 60 > 0 ? `${h}h${m % 60}m` : `${h}h`;
+}
+export const DURATION_HISTORY_CAP = 50;
+function durationsPath(dir) {
+    return join(dir, '.yoke', 'story-durations.json');
+}
+export function readDurations(dir) {
+    try {
+        const arr = JSON.parse(readFileSync(durationsPath(dir), 'utf8'));
+        if (!Array.isArray(arr))
+            return [];
+        return arr.filter((d) => typeof d?.ms === 'number' && d.ms > 0);
+    }
+    catch {
+        return [];
+    }
+}
+function appendDuration(dir, d) {
+    const all = [...readDurations(dir), d].slice(-DURATION_HISTORY_CAP);
+    try {
+        mkdirSync(join(dir, '.yoke'), { recursive: true });
+        writeFileSync(durationsPath(dir), JSON.stringify(all));
+    }
+    catch { /* observability must never abort the loop */ }
+}
 function statusPath(dir) {
     return join(dir, '.yoke', 'loop-status.json');
 }
@@ -50,8 +83,23 @@ export function makeReporter(dir, opts = {}, now = () => new Date()) {
         sink(line); };
     let current = null;
     let tokens;
+    // ETA source: durations of stories completed in THIS run beat the persisted
+    // history of earlier runs (current velocity over old experience).
+    const history = readDurations(dir).map(h => h.ms);
+    const runDurations = [];
+    let storyStartedAt = null;
+    const percentOf = (p) => (p.total > 0 ? Math.round((p.passed / p.total) * 100) : 0);
+    const etaFor = (p) => {
+        const pool = runDurations.length > 0 ? runDurations : history;
+        if (pool.length === 0)
+            return undefined;
+        const avg = pool.reduce((a, b) => a + b, 0) / pool.length;
+        const remainingStories = Math.max(0, p.total - p.passed);
+        return { avgStoryMs: Math.round(avg), remainingStories, etaMs: Math.round(avg * remainingStories) };
+    };
     const persist = (status, logLabel, consoleLine) => {
-        const next = tokens ? { ...status, tokens: { ...tokens } } : status;
+        const withPercent = { ...status, percent: percentOf(status.progress) };
+        const next = tokens ? { ...withPercent, tokens: { ...tokens } } : withPercent;
         current = next;
         try {
             writeStatus(dir, next);
@@ -67,8 +115,26 @@ export function makeReporter(dir, opts = {}, now = () => new Date()) {
     return {
         storyStart(story, iteration, progress) {
             const ts = now().toISOString();
+            storyStartedAt = now().getTime();
+            const eta = etaFor(progress);
+            const hint = eta ? ` · ~${fmtDuration(eta.etaMs)} left (Ø ${fmtDuration(eta.avgStoryMs)}/story)` : '';
             persist({ state: 'running', phase: 'implementing', story: story.id, storyTitle: story.title,
-                iteration, progress, startedAt: ts, updatedAt: ts }, 'implementing', `▶ ${story.id} (${progress.passed}/${progress.total}) — implementing…`);
+                iteration, progress, ...(eta ? { eta } : {}), startedAt: ts, updatedAt: ts }, 'implementing', `▶ ${story.id} (${progress.passed}/${progress.total} · ${percentOf(progress)}%) — implementing…${hint}`);
+        },
+        storyDone(story, progress) {
+            const t = now().getTime();
+            const ms = storyStartedAt !== null ? Math.max(0, t - storyStartedAt) : undefined;
+            storyStartedAt = null;
+            if (ms !== undefined) {
+                runDurations.push(ms);
+                appendDuration(dir, { storyId: story.id, ms });
+            }
+            const eta = etaFor(progress);
+            const base = current ?? emptyStatus(now().toISOString());
+            const took = ms !== undefined ? ` in ${fmtDuration(ms)}` : '';
+            const hint = eta && eta.remainingStories > 0 ? ` · ~${fmtDuration(eta.etaMs)} left` : '';
+            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)
@@ -105,5 +171,5 @@ function emptyStatus(ts) {
     return { state: 'running', iteration: 0, progress: { passed: 0, total: 0 }, startedAt: ts, updatedAt: ts };
 }
 export const noopReporter = {
-    storyStart() { }, phase() { }, blocked() { }, complete() { }, capReached() { }, paused() { }, addTokens() { },
+    storyStart() { }, storyDone() { }, phase() { }, blocked() { }, complete() { }, capReached() { }, paused() { }, addTokens() { },
 };

package/dist/loop/run-command.js

@@ -6,7 +6,7 @@ import { runLoop } from './loop.js';
 import { realGitOps } from './git.js';
 import { makeRunner, makeReviewRunner, isAgentAvailable } from './runner.js';
 import { commandVerifier, retryingVerifier } from './verify.js';
-import { readStatus, makeReporter } from './reporter.js';
+import { readStatus, makeReporter, fmtDuration } from './reporter.js';
 import { acquireLock, releaseLock } from './lock.js';
 import { maybeAutoUpgrade } from '../update/upgrade.js';
 export const DEFAULT_IDLE_MINUTES = 20;
@@ -46,9 +46,13 @@ export function loopStatus(targetDir, now = () => new Date()) {
     if (!st)
         return `Loop: ${enabled ? 'enabled' : 'disabled'}\nPRD: ${prog}`;
     const head = `Loop: ${st.state.toUpperCase()}${st.story ? ` on ${st.story}${st.storyTitle ? ` "${st.storyTitle}"` : ''}` : ''}`;
-    const meta = [st.phase, `iteration ${st.iteration}`, `${st.progress.passed}/${st.progress.total}`, `updated ${relativeTime(st.updatedAt, now())}`]
+    const pct = st.percent !== undefined ? ` (${st.percent}%)` : '';
+    const meta = [st.phase, `iteration ${st.iteration}`, `${st.progress.passed}/${st.progress.total}${pct}`, `updated ${relativeTime(st.updatedAt, now())}`]
         .filter(Boolean).join(' · ');
     const lines = [head, `  ${meta}`];
+    if (st.state === 'running' && st.eta && st.eta.remainingStories > 0) {
+        lines.push(`  ~${fmtDuration(st.eta.etaMs)} remaining (Ø ${fmtDuration(st.eta.avgStoryMs)}/story)`);
+    }
     if (st.reason)
         lines.push(`  reason: ${st.reason}`);
     const ageMs = now().getTime() - Date.parse(st.updatedAt);
@@ -95,7 +99,7 @@ export function runLoopCommand(targetDir, opts) {
         }
         // Token reporting is part of the machine interface: in --json mode a claude
         // runner switches to stream-json so cumulative usage rides on every status.
-        runner = makeRunner(runnerAgent, idleMs, { tokenReport: opts.json === true });
+        runner = makeRunner(runnerAgent, idleMs, { tokenReport: opts.json === true, onAmbiguity: opts.onAmbiguity ?? config.loop.onAmbiguity });
     }
     let review = opts.reviewRunner;
     if (!review && (opts.review || opts.reviewer)) {

package/dist/loop/runner.js

@@ -6,7 +6,7 @@ import { loadContext, formatForPrompt, contextDir } from '../context/context.js'
 export function contextBlockFor(targetDir) {
     return formatForPrompt(loadContext(contextDir(targetDir)));
 }
-export function buildClaudePrompt(story, context) {
+export function buildClaudePrompt(story, context, onAmbiguity = 'resolve') {
     const criteria = story.acceptance.map(a => `- ${a}`).join('\n');
     const lines = [
         'You are an autonomous coding agent running inside the Yoke loop.',
@@ -14,7 +14,9 @@ export function buildClaudePrompt(story, context) {
     ];
     if (context)
         lines.push('', context);
-    lines.push('', `Story ${story.id}: ${story.title}`, 'Acceptance criteria (Definition of Done):', criteria, '', "When done, ensure the project's full test suite passes.", 'Do NOT commit — the loop commits on your behalf after verifying.', '', 'Working rules:', '- Add nothing beyond what the story requires: no extra features, abstractions, comments, or defensive code for cases that cannot happen.', '- Do not create summary, plan, or analysis documents — only files the story itself needs.', '- If a check fails, fix the root cause; never bypass it (e.g. --no-verify) or pass by weakening tests.', '- Report the outcome faithfully: if a criterion is unmet or tests fail, say so plainly instead of claiming success.', '- Keep your final message to a few short sentences: what changed and what you verified.');
+    lines.push('', `Story ${story.id}: ${story.title}`, 'Acceptance criteria (Definition of Done):', criteria, '', "When done, ensure the project's full test suite passes.", 'Do NOT commit — the loop commits on your behalf after verifying.', '', 'Working rules:', '- Add nothing beyond what the story requires: no extra features, abstractions, comments, or defensive code for cases that cannot happen.', '- Do not create summary, plan, or analysis documents — only files the story itself needs.', '- If a check fails, fix the root cause; never bypass it (e.g. --no-verify) or pass by weakening tests.', '- Report the outcome faithfully: if a criterion is unmet or tests fail, say so plainly instead of claiming success.', '- Never ask questions or wait for input — you run unattended and nobody can answer.', onAmbiguity === 'abort'
+        ? '- If an acceptance criterion is genuinely undecidable, do NOT guess: write the open question(s) to .yoke/ambiguity.md, change nothing else, and stop.'
+        : '- If an acceptance criterion is ambiguous, resolve it yourself in the way most consistent with the other criteria and the existing code, and state your interpretation in your final message.', '- Keep your final message to a few short sentences: what changed and what you verified.');
     return lines.join('\n');
 }
 export function buildReviewPrompt(story, context) {
@@ -226,7 +228,7 @@ export function makeRunner(agent, idleTimeoutMs = 0, opts = {}) {
     // redundant for claude and meaningless elsewhere; kept for caller compatibility.
     const captureTokens = agent === 'claude';
     return (ctx) => {
-        const base = runnerInvocation(agent, buildClaudePrompt(ctx.story, contextBlockFor(ctx.targetDir)), ctx.targetDir, captureTokens);
+        const base = runnerInvocation(agent, buildClaudePrompt(ctx.story, contextBlockFor(ctx.targetDir), opts.onAmbiguity), ctx.targetDir, captureTokens);
         const inv = buildWatchdogInvocation(base, idleTimeoutMs);
         if (captureTokens) {
             const capture = opts.execCapture ?? runCliCapture;

package/dist/retrofit/config.js

@@ -9,7 +9,13 @@ const SmokeSchema = z.object({ baseUrl: z.string().min(1), flows: z.array(SmokeF
 export const YokeConfigSchema = z.object({
     canonVersion: z.string().min(1),
     agents: z.array(AgentSchema),
-    loop: z.object({ enabled: z.boolean(), timeoutMinutes: z.number().optional() }),
+    loop: z.object({
+        enabled: z.boolean(),
+        timeoutMinutes: z.number().optional(),
+        // Ambiguous acceptance criteria: 'resolve' (default — agent decides and continues)
+        // or 'abort' (agent stops the story via .yoke/ambiguity.md for a human decision).
+        onAmbiguity: z.enum(['resolve', 'abort']).optional(),
+    }),
     verify: z.object({ command: z.string().min(1), retries: z.number().int().nonnegative().optional() }).optional(),
     codeGraph: CodeGraphSchema.optional(),
     smoke: SmokeSchema.optional(),

package/dist/retrofit/gitignore.js

@@ -8,6 +8,8 @@ export const YOKE_IGNORE_LINES = [
     '.yoke/loop.lock',
     '.yoke/loop.pause',
     '.yoke/runner.pid',
+    '.yoke/ambiguity.md',
+    '.yoke/story-durations.json',
     '.yoke/proof/',
 ];
 const HEADER = '# Yoke runtime artifacts (managed by yoke retrofit)';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hecer/yoke",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "One harness, three agents, zero trust in \"done\" — cross-agent coding harness for Claude Code, Codex CLI, and Gemini CLI: one skill canon, mechanical safety gates, an autonomous loop with screenshot/video proofs.",
   "type": "module",
   "bin": {