@hecer/yoke 0.8.0 → 1.0.0

package/bench/README.md

@@ -1,42 +1,45 @@
-# Yoke benchmark — tokens · speed · quality
-
-Reproducible cross-runner benchmark for the Yoke loop. One fixed fixture project, the same
-PRD for every runner, three measured dimensions:
-
-| Dimension | How it is measured |
-|---|---|
-| **Tokens** | The loop's own token hook (`.yoke/loop-status.json`, claude runner via `--output-format stream-json`; model id included). Gemini/Codex runners do not report usage yet — recorded as `null`, a documented gap. |
-| **Speed** | Wall-clock, measured by the harness from outside: total run + per-story (from `--json` NDJSON event timestamps). The loop itself stores no durations. |
-| **Quality** | Objective, not judged by any model: the fixture ships **pre-written tests** the agent never has to write (only satisfy). After the run, each story's test file is executed against the final tree. `srcLoc` (non-empty lines in `src/`) is a code-economy proxy. |
-
-## The fixture (`fixtures/string-kit`)
-
-A dependency-free ESM library with 3 stories (`slugify`, `truncate`, `titleCase`) and 16
-`node:test` assertions total. `bench-verify.mjs` is cumulative: story N runs the tests of
-stories 1…N (the loop exports `YOKE_STORY`), so later stories cannot break earlier work; the
-final quality check runs everything. No npm installs, so results measure the agent — not the
-network.
-
-## Running it
-
-```bash
-npm run build
-node bench/run.mjs --runner=claude   # or gemini / codex
-```
-
-Each run copies the fixture to `bench/.runs/<runner>-<stamp>` (git-ignored), git-inits it,
-drives `yoke loop run --json --max=6 --timeout=10`, and writes a result JSON to
-`bench/results/`. Runs are billed against your own accounts for the agent CLIs involved.
-
-## Caveats (read before quoting numbers)
-
-- **N=1 per run.** Agent runs are stochastic; treat single runs as indicative, not
-  statistically robust. Re-run and compare.
-- Model identity matters more than CLI identity: `tokens.model` records what actually served
-  the run. Different default models per CLI make "claude vs gemini" really "model X vs model Y".
-- The fixture is deliberately small (a loop-overhead + basic-competence probe, minutes not
-  hours). It does not measure large-context refactoring, UI work, or long-horizon planning.
-- Cumulative verify means a story's duration includes fixing any regressions it caused.
-
-Results live in [`results/`](results/) — one JSON per run, summarized in
-[`RESULTS.md`](RESULTS.md).
+# Yoke benchmark — tokens · speed · quality
+
+Reproducible cross-runner benchmark for the Yoke loop. One fixed fixture project, the same
+PRD for every runner, three measured dimensions:
+
+| Dimension | How it is measured |
+|---|---|
+| **Tokens** | The loop's own token hook (`.yoke/loop-status.json`, claude runner via `--output-format stream-json`; model id included). Gemini/Codex runners do not report usage yet — recorded as `null`, a documented gap. |
+| **Speed** | Wall-clock, measured by the harness from outside: total run + per-story (from `--json` NDJSON event timestamps). The loop itself stores no durations. |
+| **Quality** | Objective, not judged by any model: the fixture ships **pre-written tests** the agent never has to write (only satisfy). After the run, each story's test file is executed against the final tree. `srcLoc` (non-empty lines in `src/`) is a code-economy proxy. |
+
+## The fixture (`fixtures/string-kit`)
+
+A dependency-free ESM library with 3 stories (`slugify`, `truncate`, `titleCase`) and 16
+`node:test` assertions total. `bench-verify.mjs` is cumulative: story N runs the tests of
+stories 1…N (the loop exports `YOKE_STORY`), so later stories cannot break earlier work; the
+final quality check runs everything. No npm installs, so results measure the agent — not the
+network.
+
+## Running it
+
+```bash
+npm run build
+node bench/run.mjs --runner=claude   # or gemini / codex
+node bench/run-matrix.mjs --label=release-1.0
+```
+
+Each run copies the fixture to `bench/.runs/<runner>-<stamp>` (git-ignored), git-inits it,
+drives `yoke loop run --json --max=6 --timeout=10`, and writes a result JSON to
+`bench/results/`. Runs are billed against your own accounts for the agent CLIs involved.
+The matrix is sequential to avoid cross-provider load distortion. Missing CLIs and authentication
+failures are stored as honest `unavailable`/`auth-failed` rows and never presented as quality measurements.
+
+## Caveats (read before quoting numbers)
+
+- **N=1 per run.** Agent runs are stochastic; treat single runs as indicative, not
+  statistically robust. Re-run and compare.
+- Model identity matters more than CLI identity: `tokens.model` records what actually served
+  the run. Different default models per CLI make "claude vs gemini" really "model X vs model Y".
+- The fixture is deliberately small (a loop-overhead + basic-competence probe, minutes not
+  hours). It does not measure large-context refactoring, UI work, or long-horizon planning.
+- Cumulative verify means a story's duration includes fixing any regressions it caused.
+
+Results live in [`results/`](results/) — one JSON per run, summarized in
+[`RESULTS.md`](RESULTS.md).

package/bench/RESULTS.md

@@ -1,36 +1,46 @@
-# Benchmark results
-
-Fixture `string-kit` (3 stories, 16 pre-written assertions). Methodology and caveats:
-[README.md](README.md). One row per run — raw JSON in [`results/`](results/).
-
-## Runs
-
-| Date | Runner | Model (reported) | Result | Wall-clock | Input tok | Output tok | First-pass stories | src LOC |
-|---|---|---|---|---|---|---|---|---|
-| 2026-07-10 | claude | claude-opus-4-8 | ✅ 3/3 complete | 4 m 28 s | 42 957 | 9 817 | 3/3 (1 iteration each) | 39 |
-| 2026-07-10 | gemini | — | ⛔ blocked: CLI not authenticated on the bench machine (headless needs `GEMINI_API_KEY` or configured OAuth) | — | — | — | — | — |
-| — | codex | — | ⛔ not installed on the bench machine | — | — | — | — | — |
-
-Per-story wall-clock (claude run): STORY-1 72 s · STORY-2 114 s · STORY-3 81 s. Every story
-passed verify on the first iteration; the final quality check (all 16 assertions on the final
-tree, outside the loop) is green.
-
-## What the harness caught before producing a single number
-
-Building an honest benchmark is itself a verification pass. The first runs found two real
-Yoke bugs, both fixed in 0.3.0:
-
-1. **Availability-probe timeout** — `gemini --version` cold-starts in ~5.8 s on Windows; the
-   5 s probe timeout misreported an installed CLI as "not found on PATH". Now 20 s.
-2. **Gemini invocation** — Gemini CLI 0.33+ requires a value after `-p`; the runner's bare
-   `-p --yolo` died with "Not enough arguments following: p". The runner now relies on piped
-   stdin (which selects headless mode) and passes only `--yolo`.
-
-## Reading the numbers
-
-- Tokens come from the loop's own hook (claude runner only — gemini/codex reporting is an
-  open gap, see the multi-agent design doc).
-- N=1: indicative, not statistics. Re-run with `node bench/run.mjs --runner=<agent>` and
-  compare rows.
-- ~53 k tokens / ~4.5 minutes for a 3-story micro-backlog is the current price of the full
-  gate pipeline (fresh headless session per story + verify + atomic commit) on this fixture.
+# Benchmark results
+
+Result schema v1 records fixture version, sample label, permission profile, telemetry/model
+availability, verdict/blocker, conflicts, wall time, iterations, and final fixture-test status.
+
+Fixture `string-kit` (3 stories, 16 pre-written assertions). Methodology and caveats:
+[README.md](README.md). One row per run — raw JSON in [`results/`](results/).
+
+## Runs
+
+| Date | Runner | Model (reported) | Result | Wall-clock | Input tok | Output tok | First-pass stories | src LOC |
+|---|---|---|---|---|---|---|---|---|
+| 2026-07-27 | claude | unavailable | ⛔ blocked before implementation; zero synthetic usage is not counted | 11 s | — | — | 0/3 | 3 |
+| 2026-07-27 | codex | unavailable | ⛔ CLI probe failed on Windows with access denied | — | — | — | — | — |
+| 2026-07-27 | gemini | unavailable | ⛔ runner exited before implementation | 14 s | — | — | 0/3 | 3 |
+| 2026-07-10 | claude | claude-opus-4-8 | ✅ 3/3 complete | 4 m 28 s | 42 957 | 9 817 | 3/3 (1 iteration each) | 39 |
+| 2026-07-10 | gemini | — | ⛔ blocked: CLI not authenticated on the bench machine (headless needs `GEMINI_API_KEY` or configured OAuth) | — | — | — | — | — |
+| — | codex | — | ⛔ not installed on the bench machine | — | — | — | — | — |
+
+Per-story wall-clock (claude run): STORY-1 72 s · STORY-2 114 s · STORY-3 81 s. Every story
+passed verify on the first iteration; the final quality check (all 16 assertions on the final
+tree, outside the loop) is green.
+
+The 2026-07-27 release matrix produced no quality measurement: Claude and Gemini exited
+before changing the fixture, and the Codex executable could not be probed in this Windows
+environment. Raw rows preserve the exact runner diagnostics; no scores were inferred.
+
+## What the harness caught before producing a single number
+
+Building an honest benchmark is itself a verification pass. The first runs found two real
+Yoke bugs, both fixed in 0.3.0:
+
+1. **Availability-probe timeout** — `gemini --version` cold-starts in ~5.8 s on Windows; the
+   5 s probe timeout misreported an installed CLI as "not found on PATH". Now 20 s.
+2. **Gemini invocation** — Gemini CLI 0.33+ requires a value after `-p`; the runner's bare
+   `-p --yolo` died with "Not enough arguments following: p". The runner now relies on piped
+   stdin (which selects headless mode) and passes only `--yolo`.
+
+## Reading the numbers
+
+- Tokens come from the loop's own hook (claude runner only — gemini/codex reporting is an
+  open gap, see the multi-agent design doc).
+- N=1: indicative, not statistics. Re-run with `node bench/run.mjs --runner=<agent>` and
+  compare rows.
+- ~53 k tokens / ~4.5 minutes for a 3-story micro-backlog is the current price of the full
+  gate pipeline (fresh headless session per story + verify + atomic commit) on this fixture.

package/bench/result-schema.mjs

@@ -0,0 +1,12 @@
+export const requiredResultFields = [
+  'schemaVersion', 'fixtureVersion', 'runner', 'sampleLabel', 'permissionProfile',
+  'usageAvailable', 'modelAvailable', 'verdict', 'conflicts', 'wallClockMs',
+  'iterations', 'finalTestsPass',
+]
+
+export function validateResult(result) {
+  const missing = requiredResultFields.filter(key => !(key in result))
+  if (missing.length) throw new Error(`benchmark result missing: ${missing.join(', ')}`)
+  if (!['completed', 'blocked', 'unavailable', 'auth-failed'].includes(result.verdict)) throw new Error(`invalid verdict: ${result.verdict}`)
+  return result
+}

package/bench/results/claude-2026-07-27T18-03-26.json

@@ -0,0 +1,50 @@
+{
+  "schemaVersion": 1,
+  "fixtureVersion": "string-kit@1",
+  "runner": "claude",
+  "sampleLabel": "matrix-2026-07-27T18:03:26.202Z",
+  "permissionProfile": "safe",
+  "yokeVersion": "1.0.0",
+  "fixture": "string-kit",
+  "startedAt": "2026-07-27T18:03:26.598Z",
+  "wallClockMs": 11345,
+  "exitCode": 1,
+  "finalState": "blocked",
+  "verdict": "blocked",
+  "blocker": "Claude runner exited before implementation; fixture verification remained red.",
+  "conflicts": 0,
+  "iterations": 1,
+  "finalTestsPass": false,
+  "progress": {
+    "passed": 0,
+    "total": 3
+  },
+  "usageAvailable": false,
+  "modelAvailable": false,
+  "tokens": {
+    "inputTokens": 0,
+    "outputTokens": 0,
+    "model": "<synthetic>"
+  },
+  "stories": [
+    {
+      "id": "STORY-1",
+      "durationMs": 10954,
+      "iterations": 1,
+      "finalTestsPass": false
+    },
+    {
+      "id": "STORY-2",
+      "durationMs": null,
+      "iterations": 0,
+      "finalTestsPass": false
+    },
+    {
+      "id": "STORY-3",
+      "durationMs": null,
+      "iterations": 0,
+      "finalTestsPass": false
+    }
+  ],
+  "srcLoc": 3
+}

package/bench/results/codex-unavailable-1785175418318.json

@@ -0,0 +1,15 @@
+{
+  "schemaVersion": 1,
+  "fixtureVersion": "string-kit@1",
+  "runner": "codex",
+  "sampleLabel": "matrix-2026-07-27T18:03:26.202Z",
+  "permissionProfile": "safe",
+  "usageAvailable": false,
+  "modelAvailable": false,
+  "verdict": "unavailable",
+  "blocker": "Zugriff verweigert",
+  "conflicts": 0,
+  "wallClockMs": null,
+  "iterations": 0,
+  "finalTestsPass": false
+}

package/bench/results/gemini-2026-07-27T18-03-44.json

@@ -0,0 +1,46 @@
+{
+  "schemaVersion": 1,
+  "fixtureVersion": "string-kit@1",
+  "runner": "gemini",
+  "sampleLabel": "matrix-2026-07-27T18:03:26.202Z",
+  "permissionProfile": "safe",
+  "yokeVersion": "1.0.0",
+  "fixture": "string-kit",
+  "startedAt": "2026-07-27T18:03:45.223Z",
+  "wallClockMs": 13844,
+  "exitCode": 1,
+  "finalState": "blocked",
+  "verdict": "blocked",
+  "blocker": "Gemini runner exited before implementation; fixture verification remained red.",
+  "conflicts": 0,
+  "iterations": 1,
+  "finalTestsPass": false,
+  "progress": {
+    "passed": 0,
+    "total": 3
+  },
+  "usageAvailable": false,
+  "modelAvailable": false,
+  "tokens": null,
+  "stories": [
+    {
+      "id": "STORY-1",
+      "durationMs": 7040,
+      "iterations": 1,
+      "finalTestsPass": false
+    },
+    {
+      "id": "STORY-2",
+      "durationMs": null,
+      "iterations": 0,
+      "finalTestsPass": false
+    },
+    {
+      "id": "STORY-3",
+      "durationMs": null,
+      "iterations": 0,
+      "finalTestsPass": false
+    }
+  ],
+  "srcLoc": 3
+}

package/bench/run-matrix.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process'
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { validateResult } from './result-schema.mjs'
+
+const benchDir = dirname(fileURLToPath(import.meta.url))
+if (process.argv.includes('--help')) {
+  console.log('usage: node bench/run-matrix.mjs [--label=sample]')
+  process.exit(0)
+}
+const label = process.argv.find(arg => arg.startsWith('--label='))?.slice(8) ?? `matrix-${new Date().toISOString()}`
+mkdirSync(join(benchDir, 'results'), { recursive: true })
+for (const runner of ['claude', 'codex', 'gemini']) {
+  const probe = spawnSync(runner, ['--version'], { encoding: 'utf8', shell: process.platform === 'win32', timeout: 20_000 })
+  if (probe.status !== 0) {
+    const row = validateResult({ schemaVersion: 1, fixtureVersion: 'string-kit@1', runner, sampleLabel: label, permissionProfile: 'safe', usageAvailable: false, modelAvailable: false, verdict: 'unavailable', blocker: (probe.stderr || probe.error?.message || 'CLI unavailable').trim(), conflicts: 0, wallClockMs: null, iterations: 0, finalTestsPass: false })
+    const out = join(benchDir, 'results', `${runner}-unavailable-${Date.now()}.json`)
+    writeFileSync(out, JSON.stringify(row, null, 2) + '\n')
+    console.log(JSON.stringify(row))
+    continue
+  }
+  const run = spawnSync(process.execPath, [join(benchDir, 'run.mjs'), `--runner=${runner}`, `--label=${label}`], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'inherit'] })
+  if (run.stdout) process.stdout.write(run.stdout)
+}

package/bench/run.mjs

@@ -1,115 +1,127 @@
-#!/usr/bin/env node
-// Yoke benchmark harness.
-//
-//   node bench/run.mjs --runner=claude [--max=6] [--timeout=10] [--label=note]
-//
-// Copies the fixture into bench/.runs/<runner>-<stamp>, git-inits it, then drives
-// `yoke loop run --json` and measures from the OUTSIDE (the loop itself records no
-// durations): per-story wall-clock from NDJSON event timestamps, tokens/model from
-// the loop's token hook (claude runner only), and quality as the fixture's own
-// pre-written tests — run per story AFTER the loop finishes, on the final tree.
-import { spawn, spawnSync } from 'node:child_process'
-import { cpSync, mkdirSync, readFileSync, writeFileSync, readdirSync, statSync } from 'node:fs'
-import { join, dirname } from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-const benchDir = dirname(fileURLToPath(import.meta.url))
-const repoRoot = dirname(benchDir)
-const cli = join(repoRoot, 'dist', 'cli.js')
-
-const args = Object.fromEntries(
-  process.argv.slice(2).filter(a => a.startsWith('--')).map(a => {
-    const [k, v] = a.slice(2).split('=')
-    return [k, v ?? true]
-  }),
-)
-const runner = args.runner
-if (!['claude', 'codex', 'gemini'].includes(runner)) {
-  console.error('usage: node bench/run.mjs --runner=<claude|codex|gemini> [--max=6] [--timeout=10] [--label=note]')
-  process.exit(2)
-}
-const max = Number(args.max ?? 6)
-const timeout = Number(args.timeout ?? 10)
-
-const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)
-const runDir = join(benchDir, '.runs', `${runner}-${stamp}`)
-mkdirSync(runDir, { recursive: true })
-cpSync(join(benchDir, 'fixtures', 'string-kit'), runDir, { recursive: true })
-
-const git = (...a) => {
-  const r = spawnSync('git', ['-C', runDir, ...a], { encoding: 'utf8' })
-  if (r.status !== 0) throw new Error(`git ${a.join(' ')} failed: ${r.stderr}`)
-}
-git('init', '-q')
-git('-c', 'user.name=bench', '-c', 'user.email=bench@yoke', 'add', '-A')
-git('-c', 'user.name=bench', '-c', 'user.email=bench@yoke', 'commit', '-q', '-m', 'bench: fixture baseline')
-
-// A nested Claude Code session refuses some operations; scrub session markers.
-const env = { ...process.env }
-for (const k of Object.keys(env)) if (k.startsWith('CLAUDE_CODE') || k === 'CLAUDECODE') delete env[k]
-
-console.error(`[bench] ${runner} → ${runDir}`)
-const t0 = Date.now()
-const events = []
-const child = spawn(process.execPath, [cli, 'loop', 'run', runDir, '--json', `--runner=${runner}`, `--max=${max}`, `--timeout=${timeout}`], {
-  env, stdio: ['ignore', 'pipe', 'inherit'],
-})
-let buf = ''
-child.stdout.on('data', d => {
-  buf += d
-  let i
-  while ((i = buf.indexOf('\n')) >= 0) {
-    const line = buf.slice(0, i).trim()
-    buf = buf.slice(i + 1)
-    if (!line) continue
-    try { events.push({ at: Date.now(), ...JSON.parse(line) }) } catch { /* non-JSON noise */ }
-  }
-})
-const exitCode = await new Promise(res => child.on('close', res))
-const wallClockMs = Date.now() - t0
-
-// Per-story duration: first event mentioning the story -> first event mentioning the next story (or end).
-const storyIds = ['STORY-1', 'STORY-2', 'STORY-3']
-const firstSeen = {}
-for (const e of events) if (e.story && !(e.story in firstSeen)) firstSeen[e.story] = e.at
-const stories = storyIds.map((id, idx) => {
-  const start = firstSeen[id]
-  const next = storyIds.slice(idx + 1).map(n => firstSeen[n]).find(v => v !== undefined)
-  const durationMs = start === undefined ? null : (next ?? t0 + wallClockMs) - start
-  const iterations = new Set(events.filter(e => e.story === id).map(e => e.iteration)).size
-  // Quality: the fixture's own tests for this story, on the final tree.
-  const q = spawnSync(process.execPath, ['--test', `tests/${id}.test.mjs`], { cwd: runDir, encoding: 'utf8' })
-  return { id, durationMs, iterations, finalTestsPass: q.status === 0 }
-})
-
-const last = events[events.length - 1] ?? {}
-let status = {}
-try { status = JSON.parse(readFileSync(join(runDir, '.yoke', 'loop-status.json'), 'utf8')) } catch { /* loop may have refused before writing status */ }
-
-// Source size (LOC in src/) as a code-economy proxy.
-const loc = (dir) => readdirSync(dir).reduce((n, f) => {
-  const p = join(dir, f)
-  if (statSync(p).isDirectory()) return n + loc(p)
-  return n + readFileSync(p, 'utf8').split('\n').filter(l => l.trim() !== '').length
-}, 0)
-
-const result = {
-  runner,
-  label: args.label ?? null,
-  yokeVersion: JSON.parse(readFileSync(join(repoRoot, 'package.json'), 'utf8')).version,
-  fixture: 'string-kit',
-  startedAt: new Date(t0).toISOString(),
-  wallClockMs,
-  exitCode,
-  finalState: last.state ?? null,
-  progress: last.progress ?? null,
-  tokens: status.tokens ?? null, // claude runner only; gemini/codex report none (documented gap)
-  stories,
-  srcLoc: loc(join(runDir, 'src')),
-}
-
-mkdirSync(join(benchDir, 'results'), { recursive: true })
-const out = join(benchDir, 'results', `${runner}-${stamp}.json`)
-writeFileSync(out, JSON.stringify(result, null, 2) + '\n')
-console.error(`[bench] done: ${out}`)
-console.log(JSON.stringify(result, null, 2))
+#!/usr/bin/env node
+// Yoke benchmark harness.
+//
+//   node bench/run.mjs --runner=claude [--max=6] [--timeout=10] [--label=note]
+//
+// Copies the fixture into bench/.runs/<runner>-<stamp>, git-inits it, then drives
+// `yoke loop run --json` and measures from the OUTSIDE (the loop itself records no
+// durations): per-story wall-clock from NDJSON event timestamps, tokens/model from
+// the loop's token hook (claude runner only), and quality as the fixture's own
+// pre-written tests — run per story AFTER the loop finishes, on the final tree.
+import { spawn, spawnSync } from 'node:child_process'
+import { cpSync, mkdirSync, readFileSync, writeFileSync, readdirSync, statSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { validateResult } from './result-schema.mjs'
+
+const benchDir = dirname(fileURLToPath(import.meta.url))
+const repoRoot = dirname(benchDir)
+const cli = join(repoRoot, 'dist', 'cli.js')
+
+const args = Object.fromEntries(
+  process.argv.slice(2).filter(a => a.startsWith('--')).map(a => {
+    const [k, v] = a.slice(2).split('=')
+    return [k, v ?? true]
+  }),
+)
+const runner = args.runner
+if (!['claude', 'codex', 'gemini'].includes(runner)) {
+  console.error('usage: node bench/run.mjs --runner=<claude|codex|gemini> [--max=6] [--timeout=10] [--label=note]')
+  process.exit(2)
+}
+const max = Number(args.max ?? 6)
+const timeout = Number(args.timeout ?? 10)
+
+const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)
+const runDir = join(benchDir, '.runs', `${runner}-${stamp}`)
+mkdirSync(runDir, { recursive: true })
+cpSync(join(benchDir, 'fixtures', 'string-kit'), runDir, { recursive: true })
+
+const git = (...a) => {
+  const r = spawnSync('git', ['-C', runDir, ...a], { encoding: 'utf8' })
+  if (r.status !== 0) throw new Error(`git ${a.join(' ')} failed: ${r.stderr}`)
+}
+git('init', '-q')
+git('-c', 'user.name=bench', '-c', 'user.email=bench@yoke', 'add', '-A')
+git('-c', 'user.name=bench', '-c', 'user.email=bench@yoke', 'commit', '-q', '-m', 'bench: fixture baseline')
+
+// A nested Claude Code session refuses some operations; scrub session markers.
+const env = { ...process.env }
+for (const k of Object.keys(env)) if (k.startsWith('CLAUDE_CODE') || k === 'CLAUDECODE') delete env[k]
+
+console.error(`[bench] ${runner} → ${runDir}`)
+const t0 = Date.now()
+const events = []
+const child = spawn(process.execPath, [cli, 'loop', 'run', runDir, '--json', `--runner=${runner}`, `--max=${max}`, `--timeout=${timeout}`], {
+  env, stdio: ['ignore', 'pipe', 'inherit'],
+})
+let buf = ''
+child.stdout.on('data', d => {
+  buf += d
+  let i
+  while ((i = buf.indexOf('\n')) >= 0) {
+    const line = buf.slice(0, i).trim()
+    buf = buf.slice(i + 1)
+    if (!line) continue
+    try { events.push({ at: Date.now(), ...JSON.parse(line) }) } catch { /* non-JSON noise */ }
+  }
+})
+const exitCode = await new Promise(res => child.on('close', res))
+const wallClockMs = Date.now() - t0
+
+// Per-story duration: first event mentioning the story -> first event mentioning the next story (or end).
+const storyIds = ['STORY-1', 'STORY-2', 'STORY-3']
+const firstSeen = {}
+for (const e of events) if (e.story && !(e.story in firstSeen)) firstSeen[e.story] = e.at
+const stories = storyIds.map((id, idx) => {
+  const start = firstSeen[id]
+  const next = storyIds.slice(idx + 1).map(n => firstSeen[n]).find(v => v !== undefined)
+  const durationMs = start === undefined ? null : (next ?? t0 + wallClockMs) - start
+  const iterations = new Set(events.filter(e => e.story === id).map(e => e.iteration)).size
+  // Quality: the fixture's own tests for this story, on the final tree.
+  const q = spawnSync(process.execPath, ['--test', `tests/${id}.test.mjs`], { cwd: runDir, encoding: 'utf8' })
+  return { id, durationMs, iterations, finalTestsPass: q.status === 0 }
+})
+
+const last = events[events.length - 1] ?? {}
+let status = {}
+try { status = JSON.parse(readFileSync(join(runDir, '.yoke', 'loop-status.json'), 'utf8')) } catch { /* loop may have refused before writing status */ }
+
+// Source size (LOC in src/) as a code-economy proxy.
+const loc = (dir) => readdirSync(dir).reduce((n, f) => {
+  const p = join(dir, f)
+  if (statSync(p).isDirectory()) return n + loc(p)
+  return n + readFileSync(p, 'utf8').split('\n').filter(l => l.trim() !== '').length
+}, 0)
+
+const result = {
+  schemaVersion: 1,
+  fixtureVersion: 'string-kit@1',
+  runner,
+  sampleLabel: String(args.label ?? `${runner}-${stamp}`),
+  permissionProfile: args.unsafe ? 'unsafe' : 'safe',
+  yokeVersion: JSON.parse(readFileSync(join(repoRoot, 'package.json'), 'utf8')).version,
+  fixture: 'string-kit',
+  startedAt: new Date(t0).toISOString(),
+  wallClockMs,
+  exitCode,
+  finalState: last.state ?? null,
+  verdict: exitCode === 0 ? 'completed' : (/api key|login|auth/i.test(String(status.reason ?? '')) ? 'auth-failed' : 'blocked'),
+  blocker: exitCode === 0 ? null : (status.reason ?? 'runner exited without a diagnostic'),
+  conflicts: events.filter(e => /conflict/i.test(String(e.reason ?? e.summary ?? ''))).length,
+  iterations: stories.reduce((sum, story) => sum + story.iterations, 0),
+  finalTestsPass: stories.every(story => story.finalTestsPass),
+  progress: last.progress ?? null,
+  usageAvailable: Number(status.tokens?.inputTokens ?? 0) + Number(status.tokens?.outputTokens ?? 0) > 0,
+  modelAvailable: typeof status.tokens?.model === 'string' && status.tokens.model !== '<synthetic>',
+  tokens: status.tokens ?? null,
+  stories,
+  srcLoc: loc(join(runDir, 'src')),
+}
+validateResult(result)
+
+mkdirSync(join(benchDir, 'results'), { recursive: true })
+const out = join(benchDir, 'results', `${runner}-${stamp}.json`)
+writeFileSync(out, JSON.stringify(result, null, 2) + '\n')
+console.error(`[bench] done: ${out}`)
+console.log(JSON.stringify(result, null, 2))

package/canon/loop/prd.schema.md

@@ -6,9 +6,14 @@ The loop is driven by a versioned PRD file. Each story:
 - id: STORY-1
   title: Short imperative description
   priority: 1            # lower = higher priority
+  needs: []              # optional dependency IDs; no unknown IDs, self-links, or cycles
+  area: api              # optional collision domain for parallel scheduling
+  agent: codex           # optional claude|codex|gemini affinity
   acceptance:            # Definition of Done (required before implementation)
     - The endpoint returns 200 for a valid request.
   passes: false          # set true only when acceptance is met and tests are green
 ```
 
 Stop condition: every story has `passes: true`.
+
+Stories without `needs`, `area`, or `agent` retain the serial pre-1.0 behavior. A story is ready only when every ID in `needs` passes. The scheduler orders ready work by priority, avoids simultaneously active areas, and uses `agent` as an affinity hint.

package/canon/manifest.yaml

@@ -1,5 +1,5 @@
 name: yoke-canon
-version: 0.1.0
+version: 1.0.0
 agents: [claude, codex, gemini]
 skills:
   - { id: tdd, path: skills/tdd, kind: methodology }
@@ -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 }