@hecer/yoke 0.9.0 → 1.1.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)));
 }
@@ -16,14 +19,20 @@ export function buildClaudePrompt(story, context, onAmbiguity = 'resolve', perfC
         lines.push('', context);
     lines.push('', `Story ${story.id}: ${story.title}`, 'Acceptance criteria (Definition of Done):', criteria, '', "When done, ensure the project's full test suite passes.", 'Do NOT commit — the loop commits on your behalf after verifying.', '', 'Working rules:', '- Add nothing beyond what the story requires: no extra features, abstractions, comments, or defensive code for cases that cannot happen.', '- Do not create summary, plan, or analysis documents — only files the story itself needs.', '- If a check fails, fix the root cause; never bypass it (e.g. --no-verify) or pass by weakening tests.', '- Report the outcome faithfully: if a criterion is unmet or tests fail, say so plainly instead of claiming success.', '- Never ask questions or wait for input — you run unattended and nobody can answer.', onAmbiguity === 'abort'
         ? '- If an acceptance criterion is genuinely undecidable, do NOT guess: write the open question(s) to .yoke/ambiguity.md, change nothing else, and stop.'
-        : '- If an acceptance criterion is ambiguous, resolve it yourself in the way most consistent with the other criteria and the existing code, and state your interpretation in your final message.');
+        : onAmbiguity === 'critical'
+            ? [
+                '- Resolve routine ambiguity yourself using the plan, acceptance criteria, existing code, and established project conventions.',
+                '- Stop only for a high-impact decision involving public architecture, security or privacy posture, destructive data migration or data loss, material external cost, legal/compliance exposure, or another irreversible choice.',
+                '- For such a critical decision, change nothing else. Write .yoke/decision-request.yaml with exactly: version: 1, storyId, question, reason, 2-4 options ({id, label, optional tradeoff}), and recommended (an option id). Then stop.',
+            ].join('\n')
+            : '- If an acceptance criterion is ambiguous, resolve it yourself in the way most consistent with the other criteria and the existing code, and state your interpretation in your final message.');
     if (perfCommand) {
         lines.push(`- This project enforces a performance budget: \`${perfCommand}\` must exit 0 or the story is blocked. Keep hot paths efficient, and never simplify away an existing optimization without re-running that benchmark.`);
     }
     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 +40,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 +54,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 +64,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 +74,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 +82,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 +233,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 +264,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

@@ -1,41 +1,37 @@
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { loadConfig } from '../retrofit/config.js';
 import { loadPrd, progress } from '../loop/prd.js';
 import { agentInvocation, buildWatchdogInvocation, runAgent, isAgentAvailable, } from '../loop/runner.js';
 import { resolveIdleMs } from '../loop/run-command.js';
+import { detectHostAgent, resolveRunnerAgent } from '../agents/host.js';
 export const PRD_TEMPLATE = `# Yoke PRD — the loop picks the lowest-priority open story each iteration.
 # Story format (see canon/loop/prd.schema.md):
 # - 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"
 #   passes: false
 []
 `;
-export function buildPrdDraftPrompt(idea) {
-    return [
+export const MAX_PLANNING_BRIEF_CHARS = 20_000;
+export const MAX_PLANNING_BRIEF_BYTES = MAX_PLANNING_BRIEF_CHARS * 4;
+export function buildPrdDraftPrompt(idea, planningBrief) {
+    const lines = [
         'You are drafting a PRD for the Yoke autonomous loop.',
         '',
         `Product idea: ${idea}`,
-        '',
-        'Break the idea into 5-12 small, independently shippable stories; each must fit one loop iteration.',
-        'Each story needs:',
-        '- id: STORY-1, STORY-2, ... (unique)',
-        '- title: one imperative sentence',
-        '- priority: dense integers from 1 (lower = built first)',
-        '- acceptance: 2-5 testable, behavioral criteria (observable outcomes, never implementation steps)',
-        '- passes: false',
-        '',
-        'If the project has no source code yet, STORY-1 must scaffold the project skeleton with a runnable',
-        'test suite, and its acceptance must include that the verify command (verify.command in',
-        '.yoke/config.yaml) exits 0.',
-        '',
-        'Write ONLY the file .yoke/prd.yaml as a YAML array of stories in exactly that shape.',
-        'Do not modify any other file. Do not commit.',
-    ].join('\n');
+    ];
+    if (planningBrief?.trim()) {
+        lines.push('', '## Approved planning brief (treat these decisions as settled)', planningBrief.trim(), '', 'Do not reopen settled choices or invent alternatives that contradict this brief.');
+    }
+    lines.push('', 'Break the idea into 5-12 small, independently shippable stories; each must fit one loop iteration.', 'Each story needs:', '- 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', '', 'If the project has no source code yet, STORY-1 must scaffold the project skeleton with a runnable', 'test suite, and its acceptance must include that the verify command (verify.command in', '.yoke/config.yaml) exits 0.', '', 'Write ONLY the file .yoke/prd.yaml as a YAML array of stories in exactly that shape.', 'Do not modify any other file. Do not commit.');
+    return lines.join('\n');
 }
 export function prdFile(targetDir) {
     return join(targetDir, '.yoke', 'prd.yaml');
@@ -63,13 +59,23 @@ export function runPrdDraft(targetDir, opts) {
     }
     const available = opts.isAvailable ?? isAgentAvailable;
     const config = loadConfig(targetDir);
-    const agent = opts.runner ?? config?.agents[0] ?? 'claude';
+    const agent = resolveRunnerAgent(config, opts.runner, detectHostAgent());
     if (!available(agent)) {
         console.error(`Agent CLI "${agent}" was not found on PATH. Install it, or pick another with --runner=<claude|codex|gemini>.`);
         return 2;
     }
     const idleMs = resolveIdleMs(opts.timeoutMinutes, undefined);
-    const inv = agentInvocation(agent, buildPrdDraftPrompt(idea), targetDir);
+    const planPath = join(targetDir, '.yoke', 'plan.md');
+    if (existsSync(planPath) && statSync(planPath).size > MAX_PLANNING_BRIEF_BYTES) {
+        console.error(`Approved plan is too large (${statSync(planPath).size} bytes; maximum ${MAX_PLANNING_BRIEF_BYTES}). Split or condense .yoke/plan.md before drafting the PRD.`);
+        return 1;
+    }
+    const planningBrief = existsSync(planPath) ? readFileSync(planPath, 'utf8') : undefined;
+    if (planningBrief && planningBrief.length > MAX_PLANNING_BRIEF_CHARS) {
+        console.error(`Approved plan is too large (${planningBrief.length} characters; maximum ${MAX_PLANNING_BRIEF_CHARS}). Split or condense .yoke/plan.md before drafting the PRD.`);
+        return 1;
+    }
+    const inv = agentInvocation(agent, buildPrdDraftPrompt(idea, planningBrief), targetDir);
     console.log(`Drafting PRD with ${agent}...`);
     const run = opts.run ?? ((i) => runAgent(buildWatchdogInvocation(i, idleMs)));
     const result = run(inv);
@@ -117,6 +123,9 @@ export function runPrdCheck(targetDir) {
         // the schema allows [], but the loop's stop-the-line gate blocks it — fail fast here
         if (s.acceptance.length === 0)
             errors.push(`story ${s.id} has no acceptance criteria`);
+        if (s.acceptance.some(criterion => /\b(?:TBD|TODO|TO BE DECIDED|DECIDE LATER)\b|\?\?\?/i.test(criterion))) {
+            errors.push(`story ${s.id} has unresolved planning decisions in acceptance criteria`);
+        }
     }
     if (errors.length > 0) {
         for (const e of errors)

package/dist/retrofit/command.js

@@ -7,13 +7,14 @@ import { detectProject } from './detect.js';
 import { ensureGitignore } from './gitignore.js';
 import { loadConfig, saveConfig, defaultConfig } from './config.js';
 import { loadManifest } from '../canon/manifest.js';
+import { detectHostAgent } from '../agents/host.js';
 export function runRetrofit(targetDir, opts) {
     const canonDir = resolveCanonDir();
     const canonVersion = loadManifest(join(canonDir, 'manifest.yaml')).version;
     const detection = detectProject(targetDir);
     const agents = opts.agents && opts.agents.length > 0
         ? opts.agents
-        : (detection.agents.length > 0 ? detection.agents : ['claude']);
+        : (detection.agents.length > 0 ? detection.agents : [opts.host ?? detectHostAgent() ?? 'claude']);
     const existing = loadConfig(targetDir);
     const codeGraph = opts.codeGraph ?? existing?.codeGraph ?? 'graphify';
     const actions = planRetrofit(canonDir, targetDir, agents, codeGraph);
@@ -28,7 +29,7 @@ export function runRetrofit(targetDir, opts) {
         ...(existing ?? defaultConfig(canonVersion)),
         canonVersion,
         agents: mergedAgents,
-        loop: { enabled: opts.loop },
+        loop: { ...existing?.loop, enabled: opts.loop },
         codeGraph,
     };
     saveConfig(targetDir, config);

package/dist/retrofit/config.js

@@ -12,10 +12,26 @@ export const YokeConfigSchema = z.object({
     loop: z.object({
         enabled: z.boolean(),
         timeoutMinutes: z.number().optional(),
+        decisionPolicy: z.enum(['auto', 'critical']).optional(),
         // Ambiguous acceptance criteria: 'resolve' (default — agent decides and continues)
         // or 'abort' (agent stops the story via .yoke/ambiguity.md for a human decision).
         onAmbiguity: z.enum(['resolve', 'abort']).optional(),
     }),
+    runner: z.object({
+        agent: AgentSchema.optional(),
+        permissions: z.enum(['safe', 'unsafe', 'read-only']).optional(),
+    }).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/gitignore.js

@@ -6,9 +6,17 @@ export const YOKE_IGNORE_LINES = [
     '.yoke/loop-status.json',
     '.yoke/loop.log',
     '.yoke/loop.lock',
+    '.yoke/loop.lock.takeover',
+    '.yoke/loop.lock.takeover.recovery',
+    '.yoke/loop.lock.*.tmp',
     '.yoke/loop.pause',
     '.yoke/runner.pid',
     '.yoke/ambiguity.md',
+    '.yoke/decision-request.yaml',
+    '.yoke/pending-decision.yaml',
+    '.yoke/decision-answering.yaml',
+    '.yoke/decision-resume*.yaml',
+    '.yoke/decision-*.yaml.*.tmp',
     '.yoke/story-durations.json',
     '.yoke/proof/',
 ];

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/retrofit/report.js

@@ -1,7 +1,7 @@
 export function formatReport(applied, meta) {
     const count = (s) => applied.filter(a => a.status === s).length;
     const lines = [];
-    lines.push('Yoke retrofit (Claude Code):');
+    lines.push('Yoke retrofit:');
     for (const a of applied) {
         const note = a.backedUp ? ` (backup: ${a.backedUp})` : '';
         lines.push(`  ${a.status.padEnd(11)} ${a.target}${note}`);

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');
+}