@hecer/yoke 0.9.0 → 1.0.0

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 }

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

@@ -29,6 +29,9 @@ good stories (small, testable, ordered) let it run overnight.
    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`).
+8. **Model real dependencies.** Add `needs` only for hard prerequisites, `area` for files or
+   subsystems that must not be edited concurrently, and `agent` only as an affinity hint.
+   Dependency IDs must exist; self-dependencies and cycles are invalid.
 
 ## Format (`.yoke/prd.yaml`)
 
@@ -43,6 +46,9 @@ good stories (small, testable, ordered) let it run overnight.
 - id: STORY-2
   title: add the sum command
   priority: 2
+  needs: [STORY-1]
+  area: cli
+  agent: codex
   acceptance:
     - "cli sum 1 2 prints 3"
     - "non-numeric input exits 1 with an error message"

package/canon/skills/ship/SKILL.md

@@ -526,15 +526,10 @@ Analyze the diff and group changes into logical commits. Each commit should repr
 
 **Each commit must be independently valid** — no broken imports, no references to code that doesn't exist yet.
 
-The **final commit** (VERSION + CHANGELOG) gets the version tag and co-author trailer:
+The **final commit** contains VERSION + CHANGELOG. The project's commit identity and co-author policy always wins; never add an AI co-author trailer unless the project explicitly allows it.
 
 ```bash
-git commit -m "$(cat <<'EOF'
-chore: bump version and changelog (vX.Y.Z.W)
-
-Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
-EOF
-)"
+git commit -m "chore: bump version and changelog (vX.Y.Z.W)"
 ```
 
 ---

package/canon/tools/codex-rtk-hook.mjs

@@ -0,0 +1,36 @@
+import { spawnSync } from 'node:child_process'
+import { resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+function rtkCheck(command) {
+  const result = spawnSync('rtk', ['hook', 'check', command], { encoding: 'utf8', timeout: 3000 })
+  return result.status === 0 ? result.stdout.trim() : ''
+}
+
+export function rewriteHookInput(input, check = rtkCheck) {
+  if (input?.tool_name !== 'Bash' && input?.toolName !== 'Bash') return null
+  const toolInput = input.tool_input ?? input.toolInput
+  const command = toolInput?.command
+  if (typeof command !== 'string' || command.trim() === '') return null
+  const rewritten = check(command)
+  if (!rewritten || rewritten === command) return null
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      updatedInput: { ...toolInput, command: rewritten },
+    },
+  }
+}
+
+async function main() {
+  let raw = ''
+  for await (const chunk of process.stdin) raw += chunk
+  try {
+    const output = rewriteHookInput(JSON.parse(raw))
+    if (output) process.stdout.write(JSON.stringify(output))
+  } catch {
+    // Compression is an optimization. Malformed input must never block Codex.
+  }
+}
+
+if (process.argv[1] && pathToFileURL(resolve(process.argv[1])).href === import.meta.url) await main()

package/dist/agents/providers.js

@@ -0,0 +1,23 @@
+const argsFor = (agent, permissions) => {
+    if (agent === 'claude') {
+        const mode = permissions === 'unsafe' ? 'bypassPermissions' : permissions === 'read-only' ? 'plan' : 'auto';
+        const args = ['-p', '--permission-mode', mode];
+        if (permissions === 'unsafe')
+            args.push('--dangerously-skip-permissions');
+        return [...args, '--output-format', 'stream-json', '--verbose'];
+    }
+    if (agent === 'codex') {
+        if (permissions === 'unsafe')
+            return ['exec', '--dangerously-bypass-approvals-and-sandbox', '--json'];
+        if (permissions === 'read-only')
+            return ['exec', '--sandbox', 'read-only', '--json'];
+        return ['exec', '--full-auto', '--json'];
+    }
+    if (permissions === 'unsafe')
+        return ['--yolo', '--output-format', 'stream-json'];
+    const approval = permissions === 'read-only' ? 'plan' : 'auto_edit';
+    return ['--approval-mode', approval, '--sandbox', '--output-format', 'stream-json'];
+};
+export function buildProviderInvocation(agent, prompt, cwd, permissions = 'safe') {
+    return { command: agent, args: argsFor(agent, permissions), input: prompt, cwd };
+}