@hecer/yoke 0.8.0 → 1.0.0

package/dist/loop/merge-queue.js

@@ -0,0 +1,20 @@
+export class MergeQueue {
+    tail = Promise.resolve();
+    enqueue(job) {
+        const run = async () => {
+            try {
+                await job.rebase();
+                if (!await job.verify())
+                    return { storyId: job.storyId, integrated: false, reason: 'integrated-tree verification failed' };
+                await job.integrate();
+                return { storyId: job.storyId, integrated: true };
+            }
+            catch (error) {
+                return { storyId: job.storyId, integrated: false, reason: error.message };
+            }
+        };
+        const result = this.tail.then(run, run);
+        this.tail = result.then(() => undefined);
+        return result;
+    }
+}

package/dist/loop/parallel.js

@@ -0,0 +1,39 @@
+import { readyStories } from './scheduler.js';
+export async function runParallelLoop(stories, opts) {
+    const completed = [];
+    const failed = [];
+    const activeAreas = new Set();
+    const active = new Map();
+    let iterations = 0;
+    let agentIndex = 0;
+    const launch = (story) => {
+        iterations++;
+        if (story.area)
+            activeAreas.add(story.area);
+        const affinity = story.agent ?? (opts.agents?.length ? opts.agents[agentIndex++ % opts.agents.length] : undefined);
+        const promise = opts.worker(story, affinity).then(result => {
+            if (result.success) {
+                story.passes = true;
+                completed.push(story.id);
+            }
+            else
+                failed.push(story.id);
+        }).catch(() => { failed.push(story.id); }).finally(() => {
+            active.delete(story.id);
+            if (story.area)
+                activeAreas.delete(story.area);
+        });
+        active.set(story.id, promise);
+    };
+    while (iterations < opts.maxIterations && !opts.paused?.()) {
+        const slots = Math.max(0, opts.maxConcurrency - active.size);
+        const ready = readyStories(stories, { activeAreas }).filter(s => !active.has(s.id) && !failed.includes(s.id)).slice(0, slots);
+        for (const story of ready)
+            launch(story);
+        if (active.size === 0)
+            break;
+        await Promise.race(active.values());
+    }
+    await Promise.all(active.values());
+    return { completed, failed, iterations, paused: opts.paused?.() ?? false };
+}

package/dist/loop/prd.js

@@ -7,20 +7,66 @@ export const StorySchema = z.object({
     priority: z.number(),
     acceptance: z.array(z.string().min(1)),
     passes: z.boolean(),
+    needs: z.array(z.string().min(1)).optional(),
+    area: z.string().min(1).optional(),
+    agent: z.enum(['claude', 'codex', 'gemini']).optional(),
 });
 const PrdSchema = z.array(StorySchema);
 export function loadPrd(file) {
-    return PrdSchema.parse(parse(readFileSync(file, 'utf8')));
+    const stories = PrdSchema.parse(parse(readFileSync(file, 'utf8')));
+    const issues = validateDependencies(stories);
+    if (issues.length)
+        throw new Error(`Invalid PRD dependency graph:\n${issues.join('\n')}`);
+    return stories;
 }
 export function savePrd(file, stories) {
     writeFileSync(file, stringify(stories));
 }
 export function selectNextStory(stories) {
-    const open = stories.filter(s => !s.passes);
+    const passed = new Set(stories.filter(s => s.passes).map(s => s.id));
+    const open = stories.filter(s => !s.passes && (s.needs ?? []).every(id => passed.has(id)));
     if (open.length === 0)
         return null;
     return open.reduce((best, s) => (s.priority < best.priority ? s : best));
 }
+export function validateDependencies(stories) {
+    const issues = [];
+    const counts = new Map();
+    for (const story of stories)
+        counts.set(story.id, (counts.get(story.id) ?? 0) + 1);
+    for (const [id, count] of counts)
+        if (count > 1)
+            issues.push(`duplicate story id: ${id}`);
+    const ids = new Set(stories.map(s => s.id));
+    for (const story of stories) {
+        for (const need of story.needs ?? []) {
+            if (need === story.id)
+                issues.push(`story ${story.id} depends on itself`);
+            else if (!ids.has(need))
+                issues.push(`story ${story.id} has unknown dependency ${need}`);
+        }
+    }
+    const byId = new Map(stories.map(s => [s.id, s]));
+    const visiting = new Set();
+    const visited = new Set();
+    const walk = (id, path) => {
+        if (visiting.has(id)) {
+            issues.push(`dependency cycle: ${[...path, id].join(' -> ')}`);
+            return;
+        }
+        if (visited.has(id))
+            return;
+        visiting.add(id);
+        for (const need of byId.get(id)?.needs ?? [])
+            if (byId.has(need) && need !== id)
+                walk(need, [...path, id]);
+        visiting.delete(id);
+        visited.add(id);
+    };
+    for (const id of byId.keys())
+        walk(id, []);
+    return [...new Set(issues)];
+}
 export function allPass(stories) {
     return stories.length > 0 && stories.every(s => s.passes);
 }

package/dist/loop/run-command.js

@@ -9,6 +9,8 @@ import { commandVerifier, retryingVerifier } from './verify.js';
 import { readStatus, makeReporter, fmtDuration } from './reporter.js';
 import { acquireLock, releaseLock } from './lock.js';
 import { maybeAutoUpgrade } from '../update/upgrade.js';
+import { resolveCommitIdentity } from './identity.js';
+import { runAudit } from '../audit/command.js';
 export const DEFAULT_IDLE_MINUTES = 20;
 const STALE_MINUTES = 20; // a running status older than this likely means the loop died
 export function relativeTime(fromIso, now) {
@@ -66,6 +68,10 @@ export function resolveIdleMs(flagMinutes, configMinutes) {
     return minutes > 0 ? minutes * 60_000 : 0;
 }
 export function runLoopCommand(targetDir, opts) {
+    if ((opts.parallel ?? 1) > 1) {
+        console.error('Parallel CLI workers are not enabled yet. The dependency-aware dispatcher and merge queue are available as APIs; use --parallel=1 for the synchronous provider runner.');
+        return 2;
+    }
     const config = loadConfig(targetDir);
     if (!config?.loop.enabled) {
         console.error('Loop is disabled. Enable it with: yoke loop on');
@@ -85,12 +91,41 @@ export function runLoopCommand(targetDir, opts) {
         }
         verify = retryingVerifier(commandVerifier(command), config.verify?.retries ?? 1);
     }
+    // Optional performance budget gate: same contract as verify (exit 0 = within
+    // budget), same flake tolerance (benchmarks are noisy).
+    let perf = opts.perf;
+    if (!perf && config.perf?.command) {
+        perf = retryingVerifier(commandVerifier(config.perf.command), config.perf.retries ?? 1);
+    }
     // Opt-in self-update, loop START only — this run keeps executing the version
     // it started with; a fetched upgrade applies from the next invocation.
     maybeAutoUpgrade(config.update?.auto);
     const available = opts.isAvailable ?? isAgentAvailable;
     const runnerAgent = opts.agent ?? config.agents[0] ?? 'claude';
+    const git = opts.git ?? realGitOps;
+    let commitIdentity = opts.commitIdentity;
+    if (!commitIdentity && !opts.git) {
+        try {
+            commitIdentity = resolveCommitIdentity(targetDir, config.commit);
+        }
+        catch (error) {
+            console.error(error.message);
+            return 2;
+        }
+    }
+    let audit = opts.audit;
+    if (!audit && config.audit?.enabled) {
+        audit = (dir) => {
+            const result = runAudit(dir, { command: config.audit?.command, suppressions: config.audit?.suppressions });
+            return { passed: result.code === 0, summary: result.error ?? (result.findings.map(f => `${f.ruleId} ${f.file}${f.line ? `:${f.line}` : ''}`).join(', ') || 'audit passed') };
+        };
+    }
+    if (commitIdentity) {
+        const announce = opts.json ? console.error : console.log;
+        announce(`Commits: ${commitIdentity.authorName} <${commitIdentity.authorEmail}> · co-authors: ${commitIdentity.allowCoAuthors ? 'allowed' : 'disabled'}`);
+    }
     const idleMs = resolveIdleMs(opts.timeoutMinutes, config.loop.timeoutMinutes);
+    const permissions = opts.permissions ?? config.runner?.permissions ?? 'safe';
     let runner = opts.runner;
     if (!runner) {
         if (!available(runnerAgent)) {
@@ -99,16 +134,34 @@ export function runLoopCommand(targetDir, opts) {
         }
         // Token reporting is part of the machine interface: in --json mode a claude
         // runner switches to stream-json so cumulative usage rides on every status.
-        runner = makeRunner(runnerAgent, idleMs, { tokenReport: opts.json === true, onAmbiguity: opts.onAmbiguity ?? config.loop.onAmbiguity });
+        runner = makeRunner(runnerAgent, idleMs, {
+            tokenReport: opts.json === true,
+            onAmbiguity: opts.onAmbiguity ?? config.loop.onAmbiguity,
+            perfCommand: config.perf?.command,
+            permissions,
+        });
+        const announce = opts.json ? console.error : console.log;
+        announce(`Runner: ${runnerAgent} · permissions: ${permissions} · cwd: ${targetDir}`);
     }
     let review = opts.reviewRunner;
     if (!review && (opts.review || opts.reviewer)) {
-        const reviewerAgent = opts.reviewer ?? runnerAgent;
-        if (!available(reviewerAgent)) {
-            console.error(`Reviewer agent CLI "${reviewerAgent}" was not found on PATH. Install it, or pick another with --reviewer=<claude|codex|gemini>.`);
+        const reviewerAgent = opts.reviewer ?? ['codex', 'gemini', 'claude'].find(agent => agent !== runnerAgent && available(agent));
+        if (!reviewerAgent) {
+            if (!opts.allowSelfReview) {
+                console.error('No independent reviewer CLI is available. Install or select a second agent, or pass --allow-self-review explicitly.');
+                return 2;
+            }
+        }
+        const resolvedReviewer = reviewerAgent ?? runnerAgent;
+        if (resolvedReviewer === runnerAgent && !opts.allowSelfReview) {
+            console.error(`Reviewer "${resolvedReviewer}" is also the implementer. Pick another agent or pass --allow-self-review explicitly.`);
+            return 2;
+        }
+        if (!available(resolvedReviewer)) {
+            console.error(`Reviewer agent CLI "${resolvedReviewer}" was not found on PATH. Install it, or pick another with --reviewer=<claude|codex|gemini>.`);
             return 2;
         }
-        review = makeReviewRunner(reviewerAgent, idleMs);
+        review = makeReviewRunner(resolvedReviewer, idleMs);
     }
     const lock = acquireLock(targetDir);
     if (!lock.acquired) {
@@ -123,10 +176,13 @@ export function runLoopCommand(targetDir, opts) {
             prdPath: path,
             targetDir,
             runner,
-            git: opts.git ?? realGitOps,
+            git,
+            commitIdentity,
             verify,
+            perf,
+            audit,
             maxIterations: opts.maxIterations,
-            isolate: opts.isolate ?? false,
+            isolate: (opts.parallel ?? 1) > 1 ? true : (opts.isolate ?? false),
             review,
             reporter: opts.reporter ?? makeReporter(targetDir, { json: opts.json }),
         });

package/dist/loop/runner.js

@@ -1,12 +1,15 @@
 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)));
 }
-export function buildClaudePrompt(story, context, onAmbiguity = 'resolve') {
+export function buildClaudePrompt(story, context, onAmbiguity = 'resolve', perfCommand) {
     const criteria = story.acceptance.map(a => `- ${a}`).join('\n');
     const lines = [
         'You are an autonomous coding agent running inside the Yoke loop.',
@@ -16,10 +19,14 @@ export function buildClaudePrompt(story, context, onAmbiguity = 'resolve') {
         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.', '- Keep your final message to a few short sentences: what changed and what you verified.');
+        : '- 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.',
@@ -27,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\`).`,
@@ -39,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
@@ -47,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);
@@ -65,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
@@ -73,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
@@ -226,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), 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 };
             }
         }
@@ -256,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 {
+            exec(inv);
+        }
+        catch (e) {
+            processFailure = e.message;
+        }
         try {
-            runCli(inv);
-            return { success: true, summary: `${agent} approved ${ctx.story.id}` };
+            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: `${agent} rejected ${ctx.story.id}: ${e.message}` };
+            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,7 +16,22 @@ 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.
+    perf: z.object({ command: z.string().min(1), retries: z.number().int().nonnegative().optional() }).optional(),
     codeGraph: CodeGraphSchema.optional(),
     smoke: SmokeSchema.optional(),
     // Opt-in: upgrade yoke at loop START when a newer version is cached (never mid-run).

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;
 }