@hecer/yoke 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 0.9.0 — 2026-07-22
+
+### Added
+- **Performance budget gate** (`perf.command` in `.yoke/config.yaml`, optional `perf.retries`).
+  A benchmark command with the same contract as verify (exit 0 = within budget) runs **after
+  verify** on every story — new loop phase `perf`, `YOKE_STORY` exposed, worktree-aware in
+  `--isolate` mode. A red benchmark blocks the story
+  (`story S6 exceeded its performance budget: …`) no matter how clean the diff is. When the
+  gate is configured, the implementer prompt names the budget command so agents keep hot
+  paths efficient and never "simplify away" an optimization without re-running the benchmark.
+- **`performance` canon skill** (28 skills now): efficiency as a measured requirement —
+  clean-by-default with the decision ladder (minimal-code → measurable acceptance criterion →
+  project perf gate), profile-first, optimize leaves not boundaries, benchmarks committed as
+  tests, the *why* of every optimization versioned so future agents don't clean fast code
+  back to slow.
+- **`authoring-prd` guidance**: performance requirements belong in acceptance criteria as
+  numbers ("imports 1M rows in < 2s"), and every clarifying question belongs in the planning
+  round — a criterion still needing a decision is not loop-ready.
+
+## 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

@@ -6,14 +6,18 @@
 
 **Yoke** installs one curated canon of skills, **mechanical safety gates**, and tool wiring into any project — natively for **Claude Code, OpenAI Codex CLI, and Gemini CLI**. Then, when you want it, an opt-in autonomous loop ships your spec story-by-story: tested, cross-model-reviewed, committed — **with a screenshot to prove every story and a video for every failure**.
 
+[![npm](https://img.shields.io/npm/v/%40hecer%2Fyoke?logo=npm&color=CB3837)](https://www.npmjs.com/package/@hecer/yoke)
+[![npm downloads](https://img.shields.io/npm/dm/%40hecer%2Fyoke?logo=npm)](https://www.npmjs.com/package/@hecer/yoke)
 [![CI](https://github.com/HECer/yoke/actions/workflows/ci.yml/badge.svg)](https://github.com/HECer/yoke/actions/workflows/ci.yml)
 [![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-322%20passing-brightgreen.svg)
+![Tests](https://img.shields.io/badge/tests-439%20passing-brightgreen.svg)
 ![Agents](https://img.shields.io/badge/agents-Claude%20%7C%20Codex%20%7C%20Gemini-8A2BE2)
 ![Built with TDD](https://img.shields.io/badge/built%20with-TDD%20%2B%20review-ff69b4.svg)
 
+**Install:** [`npm i -g @hecer/yoke`](https://www.npmjs.com/package/@hecer/yoke)
+
 </div>
 
 > **TL;DR** — `yoke new my-app --idea="..."` scaffolds a git repo, installs the harness for all three agents, and drafts a story backlog from your idea. `yoke loop run my-app --isolate --review` then implements it story by story behind hard gates: **clean tree → acceptance criteria → your real tests green → an independent model approves → commit**. If any gate is red, nothing is committed. When a story is done, there's a photo of it in `.yoke/proof/<story>/`.
@@ -46,16 +50,18 @@ $ yoke prd check reading-app
 
 $ yoke loop on reading-app
 $ yoke loop run reading-app --isolate --review --max=10
-▶ STORY-1 (0/8) — implementing… · verifying… · reviewing… ✔ committed → 1/8
-▶ STORY-2 (1/8) — implementing… · verifying… ✔ committed → 2/8
-▶ STORY-3 (2/8) — implementing… · verifying… ✘ blocked: story did not verify (tests red)
+▶ STORY-1 (0/8 · 0%) — implementing… · verifying… · reviewing… · committing…
+✓ STORY-1 done in 3m12s — 1/8 (13%) · ~22m left
+▶ STORY-2 (1/8 · 13%) — implementing… · ~22m left (Ø 3m12s/story)
+✓ STORY-2 done in 2m48s — 2/8 (25%) · ~18m left
+▶ STORY-3 (2/8 · 25%) — implementing… ✘ blocked: story did not verify (tests red)
                                               # nothing was committed. fix, then re-run.
 
 $ ls reading-app/.yoke/proof/STORY-2/
 home.png  list.png                            # photographic evidence, labelled per story
 ```
 
-Every claim in that transcript is enforced by code paths with tests behind them — 322 of them, and this repo was built by its own loop and gates ([how it was built](#-why--how-it-was-built)).
+Every claim in that transcript is enforced by code paths with tests behind them — 439 of them, and this repo was built by its own loop and gates ([how it was built](#-why--how-it-was-built)).
 
 ## 🚀 Quickstart
 
@@ -197,7 +203,7 @@ Three layers — **Canon** (`yoke validate`) → **Retrofit** (`yoke retrofit`)
 > instructions (tech stack, workflow, `@`-includes) inside it. Works in any yoke-written file;
 > content *outside* the markers is still replaced (and backed up under `.yoke/backup/`).
 
-## 🧰 What's in the canon — 27 skills
+## 🧰 What's in the canon — 28 skills
 
 `yoke retrofit` installs all of these into each agent natively. Provenance is credited in [`canon/skills/ATTRIBUTION.md`](canon/skills/ATTRIBUTION.md).
 
@@ -233,13 +239,14 @@ To stop overlapping skills from auto-invoking against each other, `canon/AGENTS.
 | `retro` | Engineering retrospective from commit history |
 | `document-release` | Post-ship documentation sync (README / CHANGELOG / …) |
 
-**Yoke-native** — *authored or adapted for this harness (7)*
+**Yoke-native** — *authored or adapted for this harness (8)*
 
 | Skill | What it does |
 |---|---|
 | `yoke-retrofit` | Set up the Yoke harness in a project (detect → plan → apply) |
 | `authoring-prd` | Slice a product idea into loop-ready stories with testable acceptance criteria |
 | `minimal-code` | Write the least code that solves the task (YAGNI; ponytail-derived) |
+| `performance` | Efficiency as a measured requirement: benchmarks as tests, budgets as gates, optimizations local + documented |
 | `maintaining-context` | Keep `.yoke/context/` the durable source of truth (the Context layer) |
 | `workflow` | The default order of operations, from idea to deploy |
 | `unslop-ui` | Detect & remove AI-slop design tells (purple gradients, neon glow, emoji-icons…) |
@@ -302,6 +309,7 @@ yoke loop run . \
   --runner=codex \               # implement with Codex…
   --reviewer=claude \            # …review with Claude (role separation)
   --isolate \                    # each story in a throwaway git worktree
+  --on-ambiguity=abort \         # strict: stop on undecidable criteria instead of guessing
   --max=20
 yoke loop off .                 # disable
 ```
@@ -323,12 +331,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 +369,58 @@ 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).
+
+### Performance budgets: efficiency as a gate, not a style
+
+Clean code is the default (the `minimal-code` skill) — but when efficiency matters, "should
+be fast" is a vibe the loop cannot enforce. Yoke makes it mechanical, at two levels:
+
+- **Per story:** write the requirement as a **measurable acceptance criterion**
+  ("imports 1M rows in < 2s, asserted by the bench test") and let your verify tests measure
+  it — no new machinery needed.
+- **Per project:** wire a benchmark as a standing **perf gate** in `.yoke/config.yaml`:
+
+  ```yaml
+  perf:
+    command: node bench/check-budget.mjs   # exit 0 = within budget
+    retries: 1                             # benchmarks are noisy; same retry logic as verify
+  ```
+
+  The loop runs it **after verify** on every story (phase `perf`, with `YOKE_STORY` set); a
+  red benchmark blocks the story — `story S6 exceeded its performance budget: p95 62ms > budget 50ms` —
+  no matter how clean the diff was. The implementer prompt names the budget command, so the
+  agent knows not to trade hot-path efficiency for style and never "simplifies away" an
+  optimization without re-running the benchmark. The `performance` canon skill carries the
+  method: profile first, optimize leaves not boundaries, commit benchmarks as tests, version
+  the *why* of every optimization in `context/DECISIONS.md`.
+
 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/canon/manifest.yaml

@@ -34,6 +34,8 @@ skills:
   - { id: visual-verification, path: skills/visual-verification, kind: methodology }
   # zero-to-100 bootstrap (kind: methodology)
   - { id: authoring-prd, path: skills/authoring-prd, kind: methodology }
+  # measured efficiency (kind: methodology)
+  - { id: performance, path: skills/performance, kind: methodology }
 policy:
   - { path: policy/gates.md }
   - { path: policy/roles.md }

package/canon/skills/authoring-prd/SKILL.md

@@ -21,6 +21,14 @@ good stories (small, testable, ordered) let it run overnight.
 5. **Greenfield: STORY-1 scaffolds.** Project skeleton + runnable test suite + a criterion
    that the verify command (`verify.command` in `.yoke/config.yaml`) exits 0. Every later
    story stands on a green pipeline.
+6. **Performance requirements are acceptance criteria — with numbers.** "Should be fast" is
+   a vibe the loop cannot gate; "imports 1M rows in < 2s (asserted by the bench test)" is a
+   criterion. If the whole project has a budget, wire `perf.command` in `.yoke/config.yaml`
+   (see the `performance` skill) instead of repeating it per story.
+7. **Ask everything now.** Clarifying questions belong in this planning round — a loop run
+   has nobody to ask. A criterion that still needs a decision ("TBD", "choose a provider")
+   is not loop-ready; resolve it here or the agent will either guess (default) or block
+   (`--on-ambiguity=abort`).
 
 ## Format (`.yoke/prd.yaml`)
 

package/canon/skills/performance/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: performance
+description: Use when a task has efficiency requirements or touches a hot path — make performance a measured requirement (benchmarks as tests, budgets as gates), keep interfaces clean and optimizations local, and version the WHY so future agents don't "clean up" fast code back to slow.
+---
+
+# Performance (measured, not vibed)
+
+"Efficient" is a requirement, not a code style. Untested performance claims rot exactly like
+untested behavior claims. This skill makes efficiency mechanical — the same move Yoke makes
+for everything else.
+
+## The decision ladder
+
+1. **Default: clean + minimal.** For ~90% of code, the `minimal-code` rules ARE the
+   performance strategy — less code, fewer layers, no speculative abstraction. Do not
+   micro-optimize code that no measurement flagged (premature optimization).
+2. **Performance requirement? Make it an acceptance criterion.** A number, not an adjective:
+   - Good: "imports 1M rows in < 2s", "p95 request latency < 50ms in the bench test",
+     "no allocation inside the render loop (verified by the bench assertion)"
+   - Bad: "should be fast", "optimize the importer"
+3. **Whole-project budget? Use the perf gate.** Set `perf.command` in `.yoke/config.yaml`
+   (a benchmark script; exit 0 = within budget). The loop runs it after verify — a story
+   that breaks the budget is blocked, no matter how clean its diff is.
+
+## Writing efficient code that agents can maintain
+
+- **Clean at the boundaries, aggressive in the leaves.** Interfaces, data flow, and names
+  stay simple and obvious. Optimization lives inside a few clearly-bounded leaf functions
+  whose contracts are pinned by tests. An ugly-fast function is maintainable; an
+  ugly-fast architecture is not.
+- **Profile before optimizing.** Find the actual hot 5% (a profiler, a timing harness, the
+  bench script) — never optimize from intuition. Record the measurement in the PR/commit.
+- **Benchmarks are tests. Commit them.** An optimization without a committed benchmark is
+  one refactor away from silently disappearing. The bench script doubles as `perf.command`.
+- **Version the WHY.** Every non-obvious optimization gets a one-line comment
+  (`perf: avoids N+1 — see bench/import.mjs`) and, if it shaped a design, a line in
+  `context/DECISIONS.md`. The most common AI maintenance accident is a later agent
+  "simplifying" fast code back to slow because nothing said why it was shaped that way.
+- **Know the classics before reaching for cleverness:** right data structure (map vs list
+  scan), batching over per-item round trips (N+1), streaming over buffering, avoiding
+  repeated work in loops, caching only with a measured hit rate and an invalidation story.
+
+## Red flags
+
+- Optimizing without a measurement or a budget → stop, measure first.
+- A "refactor" or "cleanup" story touching code with `perf:` comments → re-run the bench
+  before AND after; keep the numbers in the story outcome.
+- Hand-rolled cleverness where the stdlib is already O(right) → `minimal-code` wins.

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,44 @@ 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');
+}
+// Run a gate command with the story id exposed via YOKE_STORY (restored after),
+// so cumulative fixtures and story-aware benchmarks know which story is on trial.
+function runGate(gate, dir, storyId) {
+    const prev = process.env.YOKE_STORY;
+    process.env.YOKE_STORY = storyId;
+    try {
+        return gate(dir);
+    }
+    finally {
+        if (prev === undefined)
+            delete process.env.YOKE_STORY;
+        else
+            process.env.YOKE_STORY = prev;
+    }
+}
+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,27 +105,23 @@ 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');
-                const prevStory = process.env.YOKE_STORY;
-                process.env.YOKE_STORY = story.id;
-                let verdict;
-                try {
-                    verdict = opts.verify(wt);
-                }
-                finally {
-                    if (prevStory === undefined)
-                        delete process.env.YOKE_STORY;
-                    else
-                        process.env.YOKE_STORY = prevStory;
-                }
+                const verdict = runGate(opts.verify, wt, story.id);
                 if (!verdict.passed) {
                     const base = result.success
                         ? `story ${story.id} did not verify: ${verdict.summary}`
@@ -96,6 +130,15 @@ export function runLoop(opts) {
                     reporter.blocked(reason);
                     return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
                 }
+                if (opts.perf) {
+                    reporter.phase('perf');
+                    const perfVerdict = runGate(opts.perf, wt, story.id);
+                    if (!perfVerdict.passed) {
+                        const reason = blockReason(`story ${story.id} exceeded its performance budget: ${perfVerdict.summary}`, opts.targetDir, opts.git);
+                        reporter.blocked(reason);
+                        return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                    }
+                }
                 const summary = result.success
                     ? result.summary
                     : `${result.summary} (runner exited non-zero but verify is green)`;
@@ -121,6 +164,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,27 +177,24 @@ 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');
-        const prevStory = process.env.YOKE_STORY;
-        process.env.YOKE_STORY = story.id;
-        let verdict;
-        try {
-            verdict = opts.verify(opts.targetDir);
-        }
-        finally {
-            if (prevStory === undefined)
-                delete process.env.YOKE_STORY;
-            else
-                process.env.YOKE_STORY = prevStory;
-        }
+        const verdict = runGate(opts.verify, opts.targetDir, story.id);
         if (!verdict.passed) {
             const base = result.success
                 ? `story ${story.id} did not verify: ${verdict.summary}`
@@ -167,6 +208,15 @@ export function runLoop(opts) {
                 finalProgress: progress(stories),
             };
         }
+        if (opts.perf) {
+            reporter.phase('perf');
+            const perfVerdict = runGate(opts.perf, opts.targetDir, story.id);
+            if (!perfVerdict.passed) {
+                const reason = blockReason(`story ${story.id} exceeded its performance budget: ${perfVerdict.summary}`, opts.targetDir, opts.git);
+                reporter.blocked(reason);
+                return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+            }
+        }
         const summary = result.success
             ? result.summary
             : `${result.summary} (runner exited non-zero but verify is green)`;
@@ -211,5 +261,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);
@@ -81,6 +85,12 @@ export function runLoopCommand(targetDir, opts) {
         }
         verify = retryingVerifier(commandVerifier(command), config.verify?.retries ?? 1);
     }
+    // Optional performance budget gate: same contract as verify (exit 0 = within
+    // budget), same flake tolerance (benchmarks are noisy).
+    let perf = opts.perf;
+    if (!perf && config.perf?.command) {
+        perf = retryingVerifier(commandVerifier(config.perf.command), config.perf.retries ?? 1);
+    }
     // Opt-in self-update, loop START only — this run keeps executing the version
     // it started with; a fetched upgrade applies from the next invocation.
     maybeAutoUpgrade(config.update?.auto);
@@ -95,7 +105,11 @@ 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,
+            perfCommand: config.perf?.command,
+        });
     }
     let review = opts.reviewRunner;
     if (!review && (opts.review || opts.reviewer)) {
@@ -121,6 +135,7 @@ export function runLoopCommand(targetDir, opts) {
             runner,
             git: opts.git ?? realGitOps,
             verify,
+            perf,
             maxIterations: opts.maxIterations,
             isolate: opts.isolate ?? false,
             review,

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', perfCommand) {
     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,13 @@ 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.');
+    if (perfCommand) {
+        lines.push(`- This project enforces a performance budget: \`${perfCommand}\` must exit 0 or the story is blocked. Keep hot paths efficient, and never simplify away an existing optimization without re-running that benchmark.`);
+    }
+    lines.push('- 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 +232,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, opts.perfCommand), ctx.targetDir, captureTokens);
         const inv = buildWatchdogInvocation(base, idleTimeoutMs);
         if (captureTokens) {
             const capture = opts.execCapture ?? runCliCapture;

package/dist/retrofit/config.js

@@ -9,8 +9,17 @@ 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(),
+    // Optional performance budget gate: a benchmark command that must exit 0 for a
+    // story to land (runs after verify). Benchmarks are noisy → retried like verify.
+    perf: z.object({ command: z.string().min(1), retries: z.number().int().nonnegative().optional() }).optional(),
     codeGraph: CodeGraphSchema.optional(),
     smoke: SmokeSchema.optional(),
     // Opt-in: upgrade yoke at loop START when a newer version is cached (never mid-run).

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.9.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": {