@hecer/yoke 0.9.0 → 1.1.0

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/AGENTS.md

@@ -17,6 +17,8 @@ When several skills could match the same task, resolve deterministically:
    `tdd`, `subagent-driven-development`, `systematic-debugging`, …) take precedence and set the
    process. Role skills (`review`, `ship`, `health`, `retro`, …) add a perspective on top.
 2. **One canonical entrypoint per concern** — pick the most specific:
+   - Set up or update Yoke → `yoke-retrofit`
+   - Yoke-owned planning + autonomous story execution → `yoke-workflow`
    - Plan-time architecture review → `plan-eng-review`
    - Plan-time product / scope review → `plan-ceo-review`
    - **Pre-merge code review → `review`** (the single canonical one)

package/canon/loop/loop-spec.md

@@ -4,7 +4,8 @@ The autonomous loop is OPTIONAL and toggle-able:
 
 - `yoke loop on` / `yoke loop off` — enable/disable (recorded in `.yoke/config.yaml`, default off).
 - `yoke loop status` — show enabled state + PRD progress.
-- `yoke loop run [--max=N] [--isolate]` — run the loop (default cap 25 iterations).
+- `yoke loop run [--max=N] [--isolate] [--decision-policy=auto|critical]` — run the loop (default cap 25 iterations).
+- `yoke loop decision` / `yoke loop answer --choice=<id>` — inspect and answer a structured critical stop; answering records a human-owned, decision-file-only commit and resumes by default with the original runner, isolation, review, permission, timeout, and policy settings. `yoke loop resume` retries a restart that could not begin without weakening those settings.
 
 Pass `--isolate` to run each iteration in a fresh git worktree: the agent works on a throwaway checkout, and only a verified, committed story is fast-forwarded back into the main tree. A failed iteration never touches your working tree. Requires `.yoke/prd.yaml` to be committed to git, since the worktree is a checkout of HEAD.
 
@@ -17,7 +18,8 @@ When enabled and run, each iteration:
 1. Pre-dispatch gate: the git worktree must be clean, else `blocked`.
 2. Pick the highest-priority unfinished PRD story (`.yoke/prd.yaml`).
 3. Stop-the-Line gate: the story must have acceptance criteria, else `blocked`.
-4. Run a fresh agent to implement ONE story. The runner is selected by `--runner=<claude|codex|gemini>` or the first configured agent (default claude); the loop refuses to start if that agent's CLI is not installed.
+4. Run a fresh agent to implement ONE story. Runner precedence is explicit `--runner`, configured `runner.agent`, active agent host, then the first configured agent. The loop refuses to start if that CLI is not installed.
+   With `decisionPolicy: auto`, routine ambiguity is resolved from the approved plan and project conventions. With `critical`, only high-impact architecture, security/privacy, destructive data, material-cost, compliance, or irreversible choices may produce `.yoke/decision-request.yaml`; the loop validates its bounded single-line fields, unique options, and active story ID, blocks before verify, and preserves it for `yoke loop answer`.
 5. Run the project's verify command (config `verify.command`, or detected `npm test`).
    **Verify is the source of truth** — the agent's exit code is advisory, so a spurious
    non-zero exit (e.g. a Windows `.cmd` wrapper) cannot block a story whose tests are green.

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,9 +1,10 @@
 name: yoke-canon
-version: 0.1.0
+version: 1.1.0
 agents: [claude, codex, gemini]
 skills:
   - { id: tdd, path: skills/tdd, kind: methodology }
   - { id: yoke-retrofit, path: skills/yoke-retrofit, kind: methodology }
+  - { id: yoke-workflow, path: skills/yoke-workflow, kind: methodology }
   - { id: minimal-code, path: skills/minimal-code, kind: methodology }
   - { id: maintaining-context, path: skills/maintaining-context, kind: methodology }
   # superpowers skills (kind: methodology)

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

@@ -26,9 +26,13 @@ good stories (small, testable, ordered) let it run overnight.
    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`).
+   is unattended. A criterion that still contains `TBD` or another placeholder is not
+   loop-ready, and `yoke prd check` rejects it. During implementation,
+   `loop.decisionPolicy: auto` resolves routine ambiguity; `critical` pauses only for
+   high-impact choices and resumes after `yoke loop answer` records the answer.
+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 +47,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/skills/workflow/SKILL.md

@@ -7,6 +7,10 @@ description: Use at the start of any non-trivial task — the default order of o
 
 For any non-trivial change, move through these phases in order (skip only what genuinely does not apply):
 
+When `.yoke/config.yaml` exists and the user wants Yoke to own planning plus autonomous
+execution, use `yoke-workflow` as the entrypoint. It adds the approved-plan → PRD → loop
+handoff and the configured critical-decision behavior to the phases below.
+
 1. **Brainstorm** the idea into a clear design — see `brainstorming`.
 2. **Plan** a concrete, testable implementation — see `writing-plans`.
 3. **Understand the code** — map the blast radius with the code-graph before changing anything.

package/canon/skills/yoke-retrofit/SKILL.md

@@ -1,19 +1,26 @@
 ---
 name: yoke-retrofit
-description: Use when asked to "retrofit", "yoke this project", or set up the Yoke harness in a project — runs yoke retrofit, picks a code-graph tool, and asks whether to enable the autonomous loop.
+description: Use when asked to "retrofit", "yoke this project", or set up the Yoke harness in a project — runs the shared setup wizard and configures the same behavior for Claude, Codex, and Gemini.
 ---
 
 # Yoke Retrofit
 
-Set up (or update) the Yoke harness in the current project.
+Set up or update Yoke through the shared `yoke setup` contract.
 
-1. **Choose the code-graph tool.** Ask the user which to wire, and recommend based on the project:
-   - **Serena** (LSP-accurate, symbol-exact refactoring, no stale index) — recommend for large, strongly-typed codebases (TypeScript, Python, Go) doing systematic refactoring, where missing a reference is costly. Needs one language server per language.
-   - **graphify** (fast, multimodal: code + PDFs + diagrams + images; ~70x token reduction on large mixed repos; honest INFERRED/AMBIGUOUS edges) — recommend for rapid exploration / migration / onboarding of large or unfamiliar repos, or repos with mixed non-code content.
-   Make a direct recommendation for THIS project, then run with `--code-graph=serena` or `--code-graph=graphify` (default graphify if the user has no preference). The choice is saved in `.yoke/config.yaml`.
-2. Run `yoke retrofit . --agent=all --code-graph=<choice>` (or a subset of agents). Non-destructive — existing files are backed up under `.yoke/backup/` before any overwrite; `.claude/settings.json` is merged, not replaced. Generated per agent: Claude (`.claude/skills/`, `AGENTS.md`, `CLAUDE.md`, `.mcp.json`, rtk hook when WSL is available); Codex (`AGENTS.md`, `.codex/config.toml`, `RTK.md`); Gemini (`GEMINI.md`, `.gemini/commands/*.toml`, `.gemini/settings.json`).
-3. **Ask whether to enable the autonomous Loop** (default off). If yes, add `--loop`. Toggle any time with `yoke loop on|off`.
-4. Show the printed report (created/overwritten/unchanged/merged + detected agents) and where backups went. Note that the generated MCP launch commands may need adjusting to the user's local tool installs.
-5. **Preserve project content.** If the pre-retrofit `CLAUDE.md`/`GEMINI.md` had project-specific instructions (tech stack, workflow, `@`-includes), move them from the backup into the preserve block the generated file ships (`<!-- yoke:preserve:start -->` … `<!-- yoke:preserve:end -->`). Everything inside these markers survives every future `yoke retrofit` — in any yoke-written file; content outside them is replaced (but backed up).
+1. Inspect the project and identify the current host (`claude`, `codex`, or `gemini`).
+2. Ask these setup questions one at a time and give a direct recommendation:
+   - target agents (recommend the current host; use `all` for deliberately cross-agent projects),
+   - code-graph tool,
+   - autonomous loop on/off,
+   - default runner (recommend the current host),
+   - decision mode: `auto` or `critical`.
+3. Recommend the code graph based on this project:
+   - **Serena** is LSP-accurate and best for large typed codebases or systematic symbol refactors where a missed reference is costly. It needs a language server per language.
+   - **graphify** is fast and multimodal, and is best for exploration, migration, onboarding, or mixed code and document repositories. Its graph is an index and can become stale.
+4. Apply the answers without a second round of prompts:
+   `yoke setup . --yes --host=<host> --agent=<agents> --code-graph=<choice> --runner=<runner> --decision-policy=<auto|critical> --loop|--no-loop`.
+   A human who runs `yoke setup .` directly receives the same five terminal questions.
+5. Show the generated report and backup paths. Existing files are backed up under `.yoke/backup/`; settings are merged where supported.
+6. If an old generated `CLAUDE.md` or `GEMINI.md` contained project-specific instructions, restore them inside its `<!-- yoke:preserve:start -->` / `<!-- yoke:preserve:end -->` block. Preserve blocks survive every later retrofit.
 
-The harness includes a `minimal-code` skill (YAGNI / lazy-senior-dev) that nudges every agent to write the least code that solves the task — saving tokens and reducing maintenance.
+The generated harness includes the provider-neutral `yoke-workflow` skill. It owns the planning questions, approved-plan handoff, autonomous stories, and critical-decision resume flow.

package/canon/skills/yoke-workflow/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: yoke-workflow
+description: Use when the user asks Yoke to plan and build a feature, run stories autonomously, continue a Yoke loop, or only interrupt for major decisions.
+---
+
+# Yoke Workflow
+
+Provide the same interaction contract in Claude, Codex, and Gemini.
+
+1. Read `.yoke/config.yaml`. If it is missing, offer `yoke setup . --host=<current-agent>` and run the setup flow before planning.
+2. Plan before starting the loop. Inspect the project, then ask one focused question at a time only where the answer changes product behavior, scope, architecture, security, data ownership, external cost, or an irreversible choice. Include a recommended answer. Resolve routine implementation details yourself.
+3. Summarize the agreed design in `.yoke/plan.md`, including goals, non-goals, constraints, and decisions. Use the `authoring-prd` skill to turn it into small stories with testable acceptance criteria. Run `yoke prd check .`.
+4. Ask once for approval of the complete plan and story set. Do not begin implementation before that approval.
+5. If `loop.enabled` is true, run the stories without routine follow-up questions using the configured runner. Prefer `yoke loop run . --max=5 --isolate`, report status after each batch, and continue until complete or genuinely blocked.
+6. Respect `loop.decisionPolicy`:
+   - `auto`: choose the most suitable option from the plan, current code, and established conventions. Record the interpretation and continue.
+   - `critical`: routine ambiguity is still resolved automatically. If the loop reports a pending critical decision, run `yoke loop decision .`, present its options and recommendation to the user, ask exactly that question, then run `yoke loop answer . --choice=<id> --rationale="<answer>"`. The answer command records the decision and resumes the same story.
+7. Never ask whether to run tests, review, commit, or continue to the next approved story. Those are part of the approved workflow.
+
+The user's configured commit identity is authoritative. Do not add an AI co-author unless `commit.allowCoAuthors` explicitly permits it.

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()