@hecer/yoke 1.5.1 → 1.6.1

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

@@ -1,46 +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
-}
+{
+  "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

@@ -1,26 +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)
-}
+#!/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,35 +1,35 @@
-#!/usr/bin/env node
-// Yoke benchmark harness.
-//
+#!/usr/bin/env node
+// Yoke benchmark harness.
+//
 //   node bench/run.mjs --runner=claude [--fixture=string-kit] [--routing=on|off|config]
-//
-// 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
+//
+// 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
 // provider telemetry when available, 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'
+// pre-written tests — run per story AFTER the loop finishes, on the final tree.
+import { spawn, spawnSync } from 'node:child_process'
 import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, statSync } from 'node:fs'
-import { join, dirname } from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { validateResult } from './result-schema.mjs'
 import { parse } from 'yaml'
-
-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)) {
+
+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> [--fixture=string-kit] [--routing=on|off|config] [--run-root=path] [--unsafe] [--max=6] [--timeout=10] [--label=note]')
-  process.exit(2)
-}
+  process.exit(2)
+}
 const max = Number(args.max ?? 6)
 const timeout = Number(args.timeout ?? 10)
 const fixture = String(args.fixture ?? 'string-kit')
@@ -49,100 +49,100 @@ const runRoot = args['run-root'] ? String(args['run-root']) : join(benchDir, '.r
 const runDir = join(runRoot, `${fixture}-${runner}-routing-${routing}-${stamp}`)
 mkdirSync(runDir, { recursive: true })
 cpSync(fixtureDir, 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]
-
+
+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} · fixture=${fixture} · routing=${routing} → ${runDir}`)
-const t0 = Date.now()
-const events = []
+const t0 = Date.now()
+const events = []
 const routingFlag = routing === 'on' ? ['--routing'] : routing === 'off' ? ['--no-routing'] : []
 const permissionFlag = args.unsafe ? ['--unsafe'] : []
 const child = spawn(process.execPath, [cli, 'loop', 'run', runDir, '--json', `--runner=${runner}`, `--max=${max}`, `--timeout=${timeout}`, ...routingFlag, ...permissionFlag], {
-  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).
+  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 prd = parse(readFileSync(join(runDir, '.yoke', 'prd.yaml'), 'utf8'))
 const storyIds = Array.isArray(prd) ? prd.map(story => String(story.id)) : []
 const benchConfig = parse(readFileSync(join(runDir, '.yoke', 'config.yaml'), 'utf8'))
 const requestedParentModel = benchConfig?.runner?.model ?? null
-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,
+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: `${fixture}@1`,
-  runner,
-  sampleLabel: String(args.label ?? `${runner}-${stamp}`),
-  permissionProfile: args.unsafe ? 'unsafe' : 'safe',
-  yokeVersion: JSON.parse(readFileSync(join(repoRoot, 'package.json'), 'utf8')).version,
+  runner,
+  sampleLabel: String(args.label ?? `${runner}-${stamp}`),
+  permissionProfile: args.unsafe ? 'unsafe' : 'safe',
+  yokeVersion: JSON.parse(readFileSync(join(repoRoot, 'package.json'), 'utf8')).version,
   fixture,
   routing,
-  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,
+  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>') || requestedParentModel !== null,
   requestedParentModel,
   tokens: status.tokens ?? null,
   modelCalls: status.tokens?.calls ?? [],
-  stories,
-  srcLoc: loc(join(runDir, 'src')),
-}
-validateResult(result)
-
-mkdirSync(join(benchDir, 'results'), { recursive: true })
+  stories,
+  srcLoc: loc(join(runDir, 'src')),
+}
+validateResult(result)
+
+mkdirSync(join(benchDir, 'results'), { recursive: true })
 const out = join(benchDir, 'results', `${fixture}-${runner}-routing-${routing}-${stamp}.json`)
-writeFileSync(out, JSON.stringify(result, null, 2) + '\n')
-console.error(`[bench] done: ${out}`)
-console.log(JSON.stringify(result, null, 2))
+writeFileSync(out, JSON.stringify(result, null, 2) + '\n')
+console.error(`[bench] done: ${out}`)
+console.log(JSON.stringify(result, null, 2))

package/canon/AGENTS.md

@@ -1,30 +1,30 @@
-# Yoke Harness — Agent Baseline
-
-You are operating in a project retrofitted by Yoke. Follow these always:
-
-- **Quality first:** Test-driven development is the default. No production code without a failing test first. See skill `tdd`.
-- **Stop-the-Line:** Do not start implementation until Definition of Done / Acceptance Criteria are written. See `policy/gates.md`.
-- **Role separation:** The agent that implements does not self-review, self-merge, or self-audit security. See `policy/roles.md`.
-- **Context efficiency:** Prefer the wired tools (rtk for command output, the code-graph for symbol lookup) over reading whole files. See `tools/`.
-
-This file is the portable baseline. Agent-specific instructions are generated alongside it (CLAUDE.md, GEMINI.md).
-
-## Skill routing & precedence
-
-When several skills could match the same task, resolve deterministically:
-
-1. **Methodology before role.** Skills that decide *how* to work (`brainstorming`, `writing-plans`,
-   `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)
-   - Requesting a review (dispatch a reviewer) → `requesting-code-review`
-   - Handling review feedback → `receiving-code-review`
-   - Overall order of operations (idea → deploy) → `workflow`
-3. **Don't double-run.** These skills declare their own triggers aggressively; when more than one
-   matches, the precedence above and the most-specific entrypoint decide. Do not run two skills
-   that serve the same concern on the same task.
+# Yoke Harness — Agent Baseline
+
+You are operating in a project retrofitted by Yoke. Follow these always:
+
+- **Quality first:** Test-driven development is the default. No production code without a failing test first. See skill `tdd`.
+- **Stop-the-Line:** Do not start implementation until Definition of Done / Acceptance Criteria are written. See `policy/gates.md`.
+- **Role separation:** The agent that implements does not self-review, self-merge, or self-audit security. See `policy/roles.md`.
+- **Context efficiency:** Prefer the wired tools (rtk for command output, the code-graph for symbol lookup) over reading whole files. See `tools/`.
+
+This file is the portable baseline. Agent-specific instructions are generated alongside it (CLAUDE.md, GEMINI.md).
+
+## Skill routing & precedence
+
+When several skills could match the same task, resolve deterministically:
+
+1. **Methodology before role.** Skills that decide *how* to work (`brainstorming`, `writing-plans`,
+   `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)
+   - Requesting a review (dispatch a reviewer) → `requesting-code-review`
+   - Handling review feedback → `receiving-code-review`
+   - Overall order of operations (idea → deploy) → `workflow`
+3. **Don't double-run.** These skills declare their own triggers aggressively; when more than one
+   matches, the precedence above and the most-specific entrypoint decide. Do not run two skills
+   that serve the same concern on the same task.

package/canon/context/DECISIONS.md

@@ -1,4 +1,4 @@
-# Decisions
-
-> Append-only ledger. The Yoke loop adds an entry per completed story; agents add
-> entries for non-obvious calls made during interactive work. Newest at the bottom.
+# Decisions
+
+> Append-only ledger. The Yoke loop adds an entry per completed story; agents add
+> entries for non-obvious calls made during interactive work. Newest at the bottom.

package/canon/context/GLOSSARY.md

@@ -0,0 +1,11 @@
+# Glossary
+
+Record canonical project-specific domain terms here when they are settled.
+
+## Language
+
+<!--
+**Canonical term**
+: One or two sentences defining what the term is in this project.
+  _Avoid_: ambiguous alias, rejected synonym
+-->

package/canon/context/KNOWLEDGE.md

@@ -1,4 +1,4 @@
-# Knowledge
-
-> Reusable gotchas, conventions, and learnings. Add a bullet whenever you discover
-> something a future agent would waste time rediscovering.
+# Knowledge
+
+> Reusable gotchas, conventions, and learnings. Add a bullet whenever you discover
+> something a future agent would waste time rediscovering.

package/canon/context/PROJECT.md

@@ -1,15 +1,15 @@
-# Project — North Star
-
-> Edit this file. It is the durable goal every Yoke agent reads before implementing.
-
-## Goal
-<!-- One paragraph: what this project is and the outcome it must produce. -->
-
-## Constraints
-<!-- Hard limits: stack, platforms, performance, compliance. -->
-
-## Non-goals
-<!-- Explicitly out of scope. The most valuable section for preventing drift. -->
-
-## Success criteria
-<!-- How we know it works. -->
+# Project — North Star
+
+> Edit this file. It is the durable goal every Yoke agent reads before implementing.
+
+## Goal
+<!-- One paragraph: what this project is and the outcome it must produce. -->
+
+## Constraints
+<!-- Hard limits: stack, platforms, performance, compliance. -->
+
+## Non-goals
+<!-- Explicitly out of scope. The most valuable section for preventing drift. -->
+
+## Success criteria
+<!-- How we know it works. -->