@hecer/yoke 0.8.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # 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

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
 ```
@@ -381,6 +389,30 @@ Enable strict mode per run with `yoke loop run . --on-ambiguity=abort` or per pr
 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

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/loop/loop.js

@@ -26,6 +26,21 @@ export function pauseFilePath(targetDir) {
 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))
@@ -106,18 +121,7 @@ export function runLoop(opts) {
                 // 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}`
@@ -126,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)`;
@@ -181,18 +194,7 @@ export function runLoop(opts) {
         // 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}`
@@ -206,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)`;

package/dist/loop/run-command.js

@@ -85,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);
@@ -99,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, onAmbiguity: opts.onAmbiguity ?? config.loop.onAmbiguity });
+        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)) {
@@ -125,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, onAmbiguity = 'resolve') {
+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.',
@@ -16,7 +16,11 @@ export function buildClaudePrompt(story, context, onAmbiguity = 'resolve') {
         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.', '- 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.');
+        : '- 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) {
@@ -228,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), opts.onAmbiguity), 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

@@ -17,6 +17,9 @@ export const YokeConfigSchema = z.object({
         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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hecer/yoke",
-  "version": "0.8.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": {