@hecer/yoke 0.9.0 → 1.0.0

package/dist/loop/runner.js

@@ -1,8 +1,11 @@
 import { execFileSync, execSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, mkdirSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadContext, formatForPrompt, contextDir } from '../context/context.js';
+import { buildProviderInvocation } from '../agents/providers.js';
+import { parseProviderTelemetry } from '../agents/telemetry.js';
+import { formatReviewContract, readReviewVerdict, reviewVerdictPath } from '../review/verdict.js';
 export function contextBlockFor(targetDir) {
     return formatForPrompt(loadContext(contextDir(targetDir)));
 }
@@ -23,7 +26,7 @@ export function buildClaudePrompt(story, context, onAmbiguity = 'resolve', perfC
     lines.push('- Keep your final message to a few short sentences: what changed and what you verified.');
     return lines.join('\n');
 }
-export function buildReviewPrompt(story, context) {
+export function buildReviewPrompt(story, context, verdictPath) {
     const criteria = story.acceptance.map(a => `- ${a}`).join('\n');
     const lines = [
         'You are an independent reviewer inside the Yoke loop. You did NOT implement this change.',
@@ -31,10 +34,12 @@ export function buildReviewPrompt(story, context) {
     ];
     if (context)
         lines.push('', context);
-    lines.push('', `Story ${story.id}: ${story.title}`, 'Acceptance criteria:', criteria, '', 'Approve by exiting 0 ONLY if every acceptance criterion is met and the change is sound.', 'If you find ANY blocking issue (an unmet criterion, a bug, a missing test), exit non-zero to reject.', 'Base your verdict only on what the diff and test runs actually show — never assume unverified behavior.', 'Do not modify files. Do not commit.', 'Keep your verdict to a few short sentences.');
+    lines.push('', `Story ${story.id}: ${story.title}`, 'Acceptance criteria:', criteria, '', 'Approve ONLY if every acceptance criterion is met and the change is sound.', 'If you find ANY blocking issue (an unmet criterion, a bug, a missing test), reject.', 'Base your verdict only on what the diff and test runs actually show — never assume unverified behavior.', 'Do not modify files. Do not commit.', 'Keep your verdict to a few short sentences.');
+    if (verdictPath)
+        lines.push('', formatReviewContract(verdictPath));
     return lines.join('\n');
 }
-export function buildStandaloneReviewPrompt(scope, focus) {
+export function buildStandaloneReviewPrompt(scope, focus, verdictPath) {
     const lines = [
         'You are an independent reviewer. You did NOT write this change.',
         `Review ${scope}. Run git yourself to see the diff (e.g. \`git diff\`, or \`git diff <base>..HEAD\`).`,
@@ -43,6 +48,8 @@ export function buildStandaloneReviewPrompt(scope, focus) {
     if (focus)
         lines.push(`Pay particular attention to: ${focus}.`);
     lines.push('', 'Approve by exiting 0 ONLY if the change is sound and complete.', 'If you find ANY blocking issue, exit non-zero to reject and explain what is wrong.', 'Base your verdict only on what the diff and test runs actually show — never assume unverified behavior.', 'Do not modify files. Do not commit.', 'Keep your verdict to a few short sentences.');
+    if (verdictPath)
+        lines.push('', formatReviewContract(verdictPath));
     return lines.join('\n');
 }
 // Headless agents must run non-interactively: with plain `-p` the CLI denies
@@ -51,16 +58,8 @@ export function buildStandaloneReviewPrompt(scope, focus) {
 // and falsely marks the story done. Granting autonomous permissions makes the
 // implementer actually able to write files and run the verify command.
 // (The loop is opt-in and scoped to the target project dir.)
-const AGENT_SPECS = {
-    claude: { command: 'claude', baseArgs: ['-p', '--dangerously-skip-permissions'] },
-    codex: { command: 'codex', baseArgs: ['exec', '--dangerously-bypass-approvals-and-sandbox'] },
-    // gemini: no `-p` — current Gemini CLI (0.33+) requires a value after -p, and
-    // piped (non-TTY) stdin already selects headless mode on its own.
-    gemini: { command: 'gemini', baseArgs: ['--yolo'] },
-};
-export function agentInvocation(agent, prompt, cwd) {
-    const spec = AGENT_SPECS[agent];
-    return { command: spec.command, args: spec.baseArgs, input: prompt, cwd };
+export function agentInvocation(agent, prompt, cwd, permissions = 'safe') {
+    return buildProviderInvocation(agent, prompt, cwd, permissions);
 }
 export function claudeInvocation(prompt, cwd) {
     return agentInvocation('claude', prompt, cwd);
@@ -69,7 +68,7 @@ export function claudeInvocation(prompt, cwd) {
 // (--verbose is required by the CLI for stream-json in -p mode). Prompt still via stdin.
 // Derived from the base spec so the headless permission-bypass flag rides along.
 export function claudeStreamJsonInvocation(prompt, cwd) {
-    return { command: 'claude', args: [...AGENT_SPECS.claude.baseArgs, '--output-format', 'stream-json', '--verbose'], input: prompt, cwd };
+    return buildProviderInvocation('claude', prompt, cwd, 'safe');
 }
 // Pick the runner invocation. Claude ALWAYS runs in stream-json mode: plain `-p`
 // prints nothing until the run finishes, so the idle watchdog saw a healthy
@@ -77,10 +76,8 @@ export function claudeStreamJsonInvocation(prompt, cwd) {
 // the user saw dead air the whole time. stream-json emits per-message output,
 // which doubles as liveness. Token usage rides along for free. Other agents
 // keep their plain invocation (no machine-readable stream to gain).
-export function runnerInvocation(agent, prompt, cwd, _tokenReport = false) {
-    if (agent === 'claude')
-        return claudeStreamJsonInvocation(prompt, cwd);
-    return agentInvocation(agent, prompt, cwd);
+export function runnerInvocation(agent, prompt, cwd, _tokenReport = false, permissions = 'safe') {
+    return buildProviderInvocation(agent, prompt, cwd, permissions);
 }
 // Parse claude stream-json output into cumulative token usage. Defensive by design:
 // non-JSON lines and unknown message shapes are ignored. The final "result" message
@@ -230,20 +227,21 @@ export function makeRunner(agent, idleTimeoutMs = 0, opts = {}) {
     // Claude always streams (see runnerInvocation) — capture the stream so tokens are
     // always reported; other agents keep inherit stdio. opts.tokenReport is now
     // redundant for claude and meaningless elsewhere; kept for caller compatibility.
-    const captureTokens = agent === 'claude';
+    const captureTokens = true;
     return (ctx) => {
-        const base = runnerInvocation(agent, buildClaudePrompt(ctx.story, contextBlockFor(ctx.targetDir), opts.onAmbiguity, opts.perfCommand), ctx.targetDir, captureTokens);
+        const base = runnerInvocation(agent, buildClaudePrompt(ctx.story, contextBlockFor(ctx.targetDir), opts.onAmbiguity, opts.perfCommand), ctx.targetDir, captureTokens, opts.permissions ?? 'safe');
         const inv = buildWatchdogInvocation(base, idleTimeoutMs);
         if (captureTokens) {
             const capture = opts.execCapture ?? runCliCapture;
             try {
                 const out = capture(inv);
-                return { success: true, summary: `${agent} implemented ${ctx.story.id}`, tokens: parseClaudeStreamUsage(out.split(/\r?\n/)) };
+                const telemetry = parseProviderTelemetry(agent, out.split(/\r?\n/));
+                return { success: true, summary: `${agent} implemented ${ctx.story.id}`, tokens: telemetry.tokens };
             }
             catch (e) {
                 // Salvage usage from whatever the agent streamed before dying — those tokens were spent.
                 const partial = e.stdout;
-                const tokens = partial == null ? undefined : parseClaudeStreamUsage(String(partial).split(/\r?\n/));
+                const tokens = partial == null ? undefined : parseProviderTelemetry(agent, String(partial).split(/\r?\n/)).tokens;
                 return { success: false, summary: `${agent} failed on ${ctx.story.id}: ${e.message}`, tokens };
             }
         }
@@ -260,21 +258,35 @@ export function makeRunner(agent, idleTimeoutMs = 0, opts = {}) {
     };
 }
 export const claudeRunner = makeRunner('claude');
-export function makeReviewRunner(agent, idleTimeoutMs = 0) {
+export function makeReviewRunner(agent, idleTimeoutMs = 0, exec = runCli) {
     return (ctx) => {
-        const base = agentInvocation(agent, buildReviewPrompt(ctx.story, contextBlockFor(ctx.targetDir)), ctx.targetDir);
+        const verdictPath = reviewVerdictPath(ctx.targetDir);
+        mkdirSync(join(ctx.targetDir, '.yoke'), { recursive: true });
+        rmSync(verdictPath, { force: true });
+        const base = agentInvocation(agent, buildReviewPrompt(ctx.story, contextBlockFor(ctx.targetDir), verdictPath), ctx.targetDir, 'safe');
         const inv = buildWatchdogInvocation(base, idleTimeoutMs);
+        let processFailure;
         try {
-            runCli(inv);
-            return { success: true, summary: `${agent} approved ${ctx.story.id}` };
+            exec(inv);
         }
         catch (e) {
-            return { success: false, summary: `${agent} rejected ${ctx.story.id}: ${e.message}` };
+            processFailure = e.message;
+        }
+        try {
+            const verdict = readReviewVerdict(verdictPath);
+            if (processFailure)
+                return { success: false, summary: `review process failed: ${processFailure}; verdict: ${verdict.summary}` };
+            return verdict.approved
+                ? { success: true, summary: `${agent} approved ${ctx.story.id}: ${verdict.summary}` }
+                : { success: false, summary: `${agent} rejected ${ctx.story.id}: ${verdict.summary}` };
+        }
+        catch (e) {
+            return { success: false, summary: `${processFailure ? `review process failed: ${processFailure}; ` : ''}${e.message}` };
         }
     };
 }
 // Probe whether the agent's CLI is on PATH (so the loop can refuse upfront with a
 // clear message instead of failing mid-run with spawn ENOENT). Never throws.
 export function isAgentAvailable(agent) {
-    return probeVersion(AGENT_SPECS[agent].command);
+    return probeVersion(agent);
 }

package/dist/loop/scheduler.js

@@ -0,0 +1,8 @@
+export function readyStories(stories, opts = {}) {
+    const passed = new Set(stories.filter(story => story.passes).map(story => story.id));
+    return stories
+        .filter(story => !story.passes)
+        .filter(story => (story.needs ?? []).every(id => passed.has(id)))
+        .filter(story => !story.area || !opts.activeAreas?.has(story.area))
+        .sort((a, b) => a.priority - b.priority || Number(b.agent === opts.agent) - Number(a.agent === opts.agent) || a.id.localeCompare(b.id));
+}

package/dist/prd/command.js

@@ -9,6 +9,9 @@ export const PRD_TEMPLATE = `# Yoke PRD — the loop picks the lowest-priority o
 # - id: STORY-1
 #   title: scaffold the project with a runnable test suite
 #   priority: 1
+#   needs: []             # optional story IDs that must pass first
+#   area: foundation      # optional collision domain for parallel runs
+#   agent: codex          # optional claude|codex|gemini affinity
 #   acceptance:
 #     - "the verify command exits 0"
 #     - "a placeholder test exists and passes"
@@ -26,6 +29,9 @@ export function buildPrdDraftPrompt(idea) {
         '- id: STORY-1, STORY-2, ... (unique)',
         '- title: one imperative sentence',
         '- priority: dense integers from 1 (lower = built first)',
+        '- needs: optional list of story IDs that must pass first; the graph must be acyclic',
+        '- area: optional collision domain for safe parallel scheduling',
+        '- agent: optional claude|codex|gemini affinity',
         '- acceptance: 2-5 testable, behavioral criteria (observable outcomes, never implementation steps)',
         '- passes: false',
         '',

package/dist/retrofit/config.js

@@ -16,6 +16,18 @@ export const YokeConfigSchema = z.object({
         // or 'abort' (agent stops the story via .yoke/ambiguity.md for a human decision).
         onAmbiguity: z.enum(['resolve', 'abort']).optional(),
     }),
+    runner: z.object({ permissions: z.enum(['safe', 'unsafe', 'read-only']) }).optional(),
+    commit: z.object({
+        authorName: z.string().min(1).optional(),
+        authorEmail: z.string().email().optional(),
+        allowCoAuthors: z.boolean().optional(),
+    }).optional(),
+    audit: z.object({
+        enabled: z.boolean(),
+        command: z.string().min(1).optional(),
+        suppressionsVersion: z.literal(1).optional(),
+        suppressions: z.array(z.object({ ruleId: z.string().min(1), file: z.string().min(1).optional(), reason: z.string(), expires: z.string().optional() })).optional(),
+    }).optional(),
     verify: z.object({ command: z.string().min(1), retries: z.number().int().nonnegative().optional() }).optional(),
     // Optional performance budget gate: a benchmark command that must exit 0 for a
     // story to land (runs after verify). Benchmarks are noisy → retried like verify.

package/dist/retrofit/planners/codex.js

@@ -1,5 +1,6 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { loadManifest } from '../../canon/manifest.js';
 import { mcpServers, rtkInstruction } from '../tools.js';
 function tomlMcp(codeGraph) {
     const servers = mcpServers(codeGraph);
@@ -13,24 +14,68 @@ function tomlMcp(codeGraph) {
         .join('\n');
 }
 export function planCodex(canonDir, _targetDir, codeGraph = 'graphify') {
-    return [
-        {
-            kind: 'write',
-            target: 'AGENTS.md',
-            content: readFileSync(join(canonDir, 'AGENTS.md'), 'utf8'),
-            reason: 'baseline instructions (Codex reads AGENTS.md natively)',
-        },
-        {
-            kind: 'write',
-            target: '.codex/config.toml',
-            content: `# Yoke: MCP servers for Codex. Merge into ~/.codex/config.toml.\n\n${tomlMcp(codeGraph)}`,
-            reason: 'MCP servers (code-graph + playwright)',
-        },
-        {
-            kind: 'write',
-            target: 'RTK.md',
-            content: rtkInstruction() + '\n',
-            reason: 'rtk instruction (Codex has no rewrite hook)',
-        },
+    const manifest = loadManifest(join(canonDir, 'manifest.yaml'));
+    const baseline = readFileSync(join(canonDir, 'AGENTS.md'), 'utf8');
+    const actions = manifest.skills.map(skill => ({
+        kind: 'write',
+        target: `.agents/skills/${skill.id}/SKILL.md`,
+        content: readFileSync(join(canonDir, skill.path, 'SKILL.md'), 'utf8'),
+        reason: `skill: ${skill.id}`,
+    }));
+    const roles = [
+        ['implementer', 'Implementation specialist for one scoped story.', 'workspace-write', 'Implement only the assigned scope. Use tests first, run verification, and do not review or commit your own work.'],
+        ['reviewer', 'Read-only reviewer for correctness and acceptance criteria.', 'read-only', 'Review observed diffs and test evidence. Do not modify files. Return only findings grounded in evidence.'],
+        ['security', 'Read-only security reviewer for changed code.', 'read-only', 'Inspect changed code for exploitable security regressions. Do not modify files and avoid speculative findings.'],
+        ['docs', 'Documentation specialist for release and API consistency.', 'workspace-write', 'Update only documentation required by the assigned change. Verify commands and version references against the repository.'],
     ];
+    actions.push({
+        kind: 'write',
+        target: 'AGENTS.md',
+        content: `${baseline.trimEnd()}\n\n@RTK.md\n`,
+        reason: 'baseline instructions (Codex reads AGENTS.md natively)',
+    }, {
+        kind: 'write',
+        target: '.codex/config.toml',
+        content: `# Yoke project configuration. Codex loads this in trusted repositories.\n\n[features]\nhooks = true\n\n${tomlMcp(codeGraph)}`,
+        reason: 'MCP servers (code-graph + playwright)',
+    }, {
+        kind: 'write',
+        target: '.codex/hooks.json',
+        merge: true,
+        content: JSON.stringify({
+            description: 'Yoke command compression for Codex',
+            hooks: {
+                PreToolUse: [{
+                        matcher: '^Bash$',
+                        hooks: [{
+                                type: 'command',
+                                command: 'node "$(git rev-parse --show-toplevel)/.codex/hooks/rtk.mjs"',
+                                commandWindows: 'powershell -NoProfile -ExecutionPolicy Bypass -Command "$root = git rev-parse --show-toplevel; node (Join-Path $root \'.codex/hooks/rtk.mjs\')"',
+                                timeout: 5,
+                                statusMessage: 'Compressing command output with RTK',
+                            }],
+                    }],
+            },
+        }, null, 2) + '\n',
+        reason: 'rtk PreToolUse hook adapter',
+    }, {
+        kind: 'write',
+        target: '.codex/hooks/rtk.mjs',
+        content: readFileSync(join(canonDir, 'tools', 'codex-rtk-hook.mjs'), 'utf8'),
+        reason: 'rtk Codex hook adapter',
+    }, {
+        kind: 'write',
+        target: 'RTK.md',
+        content: rtkInstruction() + '\n',
+        reason: 'rtk instruction (Codex has no rewrite hook)',
+    });
+    for (const [name, description, sandbox, instructions] of roles) {
+        actions.push({
+            kind: 'write',
+            target: `.codex/agents/${name}.toml`,
+            content: `name = "${name}"\ndescription = "${description}"\nsandbox_mode = "${sandbox}"\ndeveloper_instructions = """\n${instructions}\n"""\n`,
+            reason: `Codex role agent: ${name}`,
+        });
+    }
+    return actions;
 }

package/dist/review/command.js

@@ -1,43 +1,83 @@
 import { agentInvocation, buildStandaloneReviewPrompt, buildWatchdogInvocation, runAgent, isAgentAvailable, } from '../loop/runner.js';
 import { resolveIdleMs } from '../loop/run-command.js';
+import { existsSync, mkdirSync, rmSync, rmdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadConfig } from '../retrofit/config.js';
+import { readReviewVerdict, reviewVerdictPath } from './verdict.js';
 // Resolve to the first available agent, preferring a *second* model so the review
 // is genuinely cross-model. claude last => a Claude-only box degrades to self-review.
 const RESOLUTION_ORDER = ['codex', 'gemini', 'claude'];
 export function runReview(targetDir, opts = {}) {
     const available = opts.isAvailable ?? isAgentAvailable;
+    const implementer = opts.implementer ?? loadConfig(targetDir)?.agents[0] ?? 'claude';
     let reviewer = opts.reviewer;
     if (reviewer) {
         if (!available(reviewer)) {
             console.error(`Reviewer agent CLI "${reviewer}" was not found on PATH. Install it, or pick another with --reviewer=<claude|codex|gemini>.`);
             return 2;
         }
+        if (reviewer === implementer && !opts.allowSelfReview) {
+            console.error(`Reviewer "${reviewer}" is also the implementer. Pick another agent or pass --allow-self-review explicitly.`);
+            return 2;
+        }
     }
     else {
-        reviewer = RESOLUTION_ORDER.find(a => available(a));
+        reviewer = RESOLUTION_ORDER.find(a => a !== implementer && available(a));
+        if (!reviewer && opts.allowSelfReview && available(implementer))
+            reviewer = implementer;
         if (!reviewer) {
-            console.error('No agent CLI (claude|codex|gemini) found on PATH. Install one to run a review.');
+            console.error('No independent reviewer CLI is available. Install a second agent, select one with --reviewer, or pass --allow-self-review explicitly.');
             return 2;
         }
-        if (reviewer === 'claude') {
-            console.log('Note: only Claude is available — this is a self-review, not cross-model.');
-        }
     }
     const scope = opts.base
         ? `the diff ${opts.base}..HEAD`
         : 'the uncommitted working-tree changes (working tree + staged)';
-    const prompt = buildStandaloneReviewPrompt(scope, opts.focus);
+    const verdictPath = reviewVerdictPath(targetDir);
+    const yokeDir = join(targetDir, '.yoke');
+    const createdYokeDir = !existsSync(yokeDir);
+    mkdirSync(yokeDir, { recursive: true });
+    rmSync(verdictPath, { force: true });
+    const prompt = buildStandaloneReviewPrompt(scope, opts.focus, verdictPath);
     const idleMs = resolveIdleMs(opts.timeoutMinutes, undefined);
     // Pass the *agent* invocation to the runner so callers (and tests) see the
     // reviewer command. The default runner adds the watchdog wrapper before exec;
     // an injected run() gets the raw invocation.
-    const inv = agentInvocation(reviewer, prompt, targetDir);
-    console.log(`Reviewing ${scope} with ${reviewer}...`);
+    const inv = agentInvocation(reviewer, prompt, targetDir, 'safe');
+    const say = opts.json ? console.error : console.log;
+    say(`Reviewing ${scope} with ${reviewer}...`);
     const run = opts.run ?? ((i) => runAgent(buildWatchdogInvocation(i, idleMs)));
-    const result = run(inv);
-    if (result.success) {
-        console.log(`✓ ${reviewer} approved`);
+    const processResult = run(inv);
+    let verdict;
+    try {
+        verdict = readReviewVerdict(verdictPath);
+    }
+    catch (error) {
+        say(`✗ ${reviewer} produced no valid verdict (${error.message})${processResult.success ? '' : `; process: ${processResult.summary}`}`);
+        if (createdYokeDir) {
+            try {
+                rmdirSync(yokeDir);
+            }
+            catch { }
+        }
+        return 1;
+    }
+    if (createdYokeDir) {
+        try {
+            rmdirSync(yokeDir);
+        }
+        catch { }
+    }
+    if (opts.json)
+        console.log(JSON.stringify({ reviewer, process: processResult, verdict }));
+    if (!processResult.success) {
+        say(`✗ ${reviewer} process failed (${processResult.summary}); verdict: ${verdict.summary}`);
+        return 1;
+    }
+    if (verdict.approved) {
+        say(`✓ ${reviewer} approved: ${verdict.summary}`);
         return 0;
     }
-    console.log(`✗ ${reviewer} found issues (${result.summary})`);
+    say(`✗ ${reviewer} rejected: ${verdict.summary}`);
     return 1;
 }

package/dist/review/verdict.js

@@ -0,0 +1,45 @@
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { z } from 'zod';
+export const ReviewFindingSchema = z.object({
+    severity: z.enum(['blocking', 'warning', 'info']),
+    message: z.string().min(1),
+    file: z.string().min(1).optional(),
+    line: z.number().int().positive().optional(),
+});
+export const ReviewVerdictSchema = z.object({
+    approved: z.boolean(),
+    summary: z.string().min(1),
+    findings: z.array(ReviewFindingSchema),
+});
+export function reviewVerdictPath(targetDir) {
+    return resolve(join(targetDir, '.yoke', 'review-verdict.json'));
+}
+export function readReviewVerdict(path) {
+    if (!existsSync(path))
+        throw new Error(`Review verdict is missing: ${path}`);
+    try {
+        let value;
+        try {
+            value = JSON.parse(readFileSync(path, 'utf8'));
+        }
+        catch (error) {
+            throw new Error(`Review verdict is malformed JSON: ${error.message}`);
+        }
+        const result = ReviewVerdictSchema.safeParse(value);
+        if (!result.success)
+            throw new Error(`Review verdict is invalid: ${result.error.message}`);
+        return result.data;
+    }
+    finally {
+        rmSync(path, { force: true });
+    }
+}
+export function formatReviewContract(path) {
+    return [
+        `Write your final verdict to this absolute path: ${path}`,
+        'The file must contain exactly one JSON object with this contract:',
+        '{"approved":boolean,"summary":"non-empty string","findings":[{"severity":"blocking|warning|info","message":"non-empty string","file":"optional path","line":1}]}',
+        'Set approved=false when any blocking finding exists. Create the file even when the process also exits non-zero.',
+    ].join('\n');
+}

package/docs/MIGRATING-TO-1.0.md

@@ -0,0 +1,33 @@
+# Migrating to Yoke 1.0
+
+Yoke 1.0 changes unsafe implicit behavior into explicit policy.
+
+## Runner permissions
+
+The default is `runner.permissions: safe`. Automation that intentionally requires a full
+sandbox bypass must pass `--unsafe` or configure `runner.permissions: unsafe`. Use
+`read-only` for planning and probing.
+
+## Reviews
+
+Reviewers write `.yoke/review-verdict.json`; Yoke validates and consumes it. The reviewer must
+differ from the implementer unless `--allow-self-review` is explicit. CI can add `--json`.
+
+## Commit ownership
+
+Yoke resolves identity before implementation. Configure it when Git has no identity:
+
+```yaml
+commit:
+  authorName: HECer
+  authorEmail: hec_er@web.de
+  allowCoAuthors: false
+```
+
+## PRDs, audit, and cleanup
+
+Existing PRDs remain valid. Optional `needs`, `area`, and `agent` fields add dependencies,
+collision domains, and affinity. Enable the story audit gate with `audit.enabled: true` and
+version suppressions with `suppressionsVersion: 1`.
+
+`yoke loop cleanup` now reports retained worktrees. Add `--remove-worktrees` for deletion.