@hecer/yoke 1.0.0 → 1.1.1

package/dist/loop/loop.js

@@ -4,6 +4,7 @@ import { loadPrd, savePrd, selectNextStory, allPass, progress } from './prd.js';
 import { stopTheLineGate, preDispatchGate } from './gates.js';
 import { appendDecision, contextDir } from '../context/context.js';
 import { noopReporter } from './reporter.js';
+import { consumeDecisionRequest } from './decision.js';
 function blockReason(base, targetDir, git) {
     let dirty = false;
     try {
@@ -112,6 +113,20 @@ export function runLoop(opts) {
                 iterations++;
                 if (result.tokens)
                     reporter.addTokens(result.tokens);
+                let decision;
+                try {
+                    decision = consumeDecisionRequest(wt, opts.targetDir, story.id);
+                }
+                catch (error) {
+                    const reason = `invalid critical decision request for story ${story.id}: ${error.message}`;
+                    reporter.blocked(reason);
+                    return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                }
+                if (decision) {
+                    const reason = `critical decision required for story ${story.id}: ${decision.question}`;
+                    reporter.blocked(reason);
+                    return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+                }
                 const ambiguity = consumeAmbiguity(wt);
                 if (ambiguity) {
                     const reason = `story ${story.id} stopped: ambiguous acceptance criteria — ${ambiguity}`;
@@ -194,6 +209,20 @@ export function runLoop(opts) {
         iterations++;
         if (result.tokens)
             reporter.addTokens(result.tokens);
+        let decision;
+        try {
+            decision = consumeDecisionRequest(opts.targetDir, opts.targetDir, story.id);
+        }
+        catch (error) {
+            const reason = `invalid critical decision request for story ${story.id}: ${error.message}`;
+            reporter.blocked(reason);
+            return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+        }
+        if (decision) {
+            const reason = `critical decision required for story ${story.id}: ${decision.question}`;
+            reporter.blocked(reason);
+            return { status: 'blocked', iterations, reason, finalProgress: progress(stories) };
+        }
         const ambiguity = consumeAmbiguity(opts.targetDir);
         if (ambiguity) {
             const reason = `story ${story.id} stopped: ambiguous acceptance criteria — ${ambiguity}`;

package/dist/loop/run-command.js

@@ -11,6 +11,8 @@ import { acquireLock, releaseLock } from './lock.js';
 import { maybeAutoUpgrade } from '../update/upgrade.js';
 import { resolveCommitIdentity } from './identity.js';
 import { runAudit } from '../audit/command.js';
+import { detectHostAgent, resolveRunnerAgent } from '../agents/host.js';
+import { clearDecisionResume, decisionProcessingExists, decisionRequestId, formatPendingDecision, readPendingDecision, writeDecisionResume, } from './decision.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) {
@@ -32,7 +34,7 @@ export function prdPath(targetDir) {
 export function setLoopEnabled(targetDir, enabled) {
     // TODO(C2): resolve bundled canon version instead of placeholder
     const config = loadConfig(targetDir) ?? defaultConfig('0.0.0');
-    config.loop = { enabled };
+    config.loop = { ...config.loop, enabled };
     saveConfig(targetDir, config);
 }
 export function loopStatus(targetDir, now = () => new Date()) {
@@ -77,6 +79,20 @@ export function runLoopCommand(targetDir, opts) {
         console.error('Loop is disabled. Enable it with: yoke loop on');
         return 2;
     }
+    if (decisionProcessingExists(targetDir)) {
+        console.error(`A critical decision answer needs recovery. Run: yoke loop answer ${targetDir} --choice=<id>`);
+        return 1;
+    }
+    try {
+        if (readPendingDecision(targetDir)) {
+            console.error(`${formatPendingDecision(targetDir)}\nAnswer it with: yoke loop answer ${targetDir} --choice=<id>`);
+            return 1;
+        }
+    }
+    catch (error) {
+        console.error(`Invalid pending Yoke decision: ${error.message}`);
+        return 1;
+    }
     const path = prdPath(targetDir);
     if (!existsSync(path)) {
         console.error(`No PRD found at ${path}. Create one (see canon loop/prd.schema.md).`);
@@ -101,7 +117,7 @@ export function runLoopCommand(targetDir, opts) {
     // 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 runnerAgent = resolveRunnerAgent(config, opts.agent, detectHostAgent());
     const git = opts.git ?? realGitOps;
     let commitIdentity = opts.commitIdentity;
     if (!commitIdentity && !opts.git) {
@@ -136,7 +152,7 @@ export function runLoopCommand(targetDir, opts) {
         // 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,
+            onAmbiguity: opts.decisionPolicy ?? opts.onAmbiguity ?? config.loop.decisionPolicy ?? config.loop.onAmbiguity ?? 'auto',
             perfCommand: config.perf?.command,
             permissions,
         });
@@ -163,7 +179,14 @@ export function runLoopCommand(targetDir, opts) {
         }
         review = makeReviewRunner(resolvedReviewer, idleMs);
     }
-    const lock = acquireLock(targetDir);
+    let lock;
+    try {
+        lock = acquireLock(targetDir);
+    }
+    catch (error) {
+        console.error(`Cannot acquire the Yoke loop lock: ${error.message}`);
+        return 2;
+    }
     if (!lock.acquired) {
         console.error(`Another loop is already running here (pid ${lock.holderPid}). If that is wrong, run: yoke loop cleanup`);
         return 2;
@@ -172,6 +195,7 @@ export function runLoopCommand(targetDir, opts) {
         console.warn(`Took over a stale loop lock (pid ${lock.stalePid} is gone).`);
     }
     try {
+        const reporter = opts.reporter ?? makeReporter(targetDir, { json: opts.json });
         const result = runLoop({
             prdPath: path,
             targetDir,
@@ -184,15 +208,52 @@ export function runLoopCommand(targetDir, opts) {
             maxIterations: opts.maxIterations,
             isolate: (opts.parallel ?? 1) > 1 ? true : (opts.isolate ?? false),
             review,
-            reporter: opts.reporter ?? makeReporter(targetDir, { json: opts.json }),
+            reporter,
         });
+        try {
+            const pendingDecision = readPendingDecision(targetDir);
+            if (pendingDecision) {
+                writeDecisionResume(targetDir, {
+                    version: 1,
+                    storyId: pendingDecision.storyId,
+                    requestId: decisionRequestId(pendingDecision),
+                    answered: false,
+                    maxIterations: opts.maxIterations,
+                    agent: runnerAgent,
+                    isolate: opts.isolate ?? false,
+                    reviewer: opts.reviewer,
+                    review: opts.review === true || opts.reviewRunner !== undefined,
+                    allowSelfReview: opts.allowSelfReview ?? false,
+                    timeoutMinutes: opts.timeoutMinutes ?? config.loop.timeoutMinutes,
+                    json: opts.json ?? false,
+                    onAmbiguity: opts.decisionPolicy
+                        ? undefined
+                        : opts.onAmbiguity === 'resolve' || opts.onAmbiguity === 'abort'
+                            ? opts.onAmbiguity
+                            : (config.loop.decisionPolicy ? undefined : config.loop.onAmbiguity),
+                    decisionPolicy: opts.decisionPolicy
+                        ?? (opts.onAmbiguity
+                            ? (opts.onAmbiguity === 'auto' || opts.onAmbiguity === 'critical' ? opts.onAmbiguity : undefined)
+                            : config.loop.decisionPolicy),
+                    permissions,
+                    parallel: opts.parallel ?? 1,
+                });
+            }
+            else
+                clearDecisionResume(targetDir);
+        }
+        catch (error) {
+            const reason = `could not persist trusted decision resume state: ${error.message}`;
+            reporter.blocked(reason);
+            return 1;
+        }
         // In json mode stdout belongs to the NDJSON stream — route the narrative summary to stderr.
         const say = opts.json ? (line) => console.error(line) : (line) => console.log(line);
         say(`Loop ${result.status} after ${result.iterations} iteration(s): ${result.finalProgress.passed}/${result.finalProgress.total} stories pass`);
         if (result.reason)
             say(`Reason: ${result.reason}`);
-        if (result.reason && /api key|please run \/login|not logged in/i.test(result.reason)) {
-            say('Hint: the agent CLI has no credentials in this environment. Set ANTHROPIC_API_KEY or log the agent in for headless use.');
+        if (result.reason && /api key|please run \/login|not logged in|auth/i.test(result.reason)) {
+            say('Hint: the agent CLI has no credentials in this environment. Set ANTHROPIC_API_KEY, GEMINI_API_KEY, or OPENAI_API_KEY, or log the agent in for headless use.');
         }
         // Exit codes: 0 complete · 1 blocked/cap-reached · 2 config error (handled above) · 3 paused (loop.pause consumed at a story boundary)
         if (result.status === 'complete')
@@ -202,6 +263,6 @@ export function runLoopCommand(targetDir, opts) {
         return 1;
     }
     finally {
-        releaseLock(targetDir);
+        releaseLock(targetDir, lock.ownerToken);
     }
 }

package/dist/loop/runner.js

@@ -19,7 +19,13 @@ 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.`);
     }

package/dist/prd/command.js

@@ -1,9 +1,10 @@
-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
@@ -18,30 +19,19 @@ export const PRD_TEMPLATE = `# Yoke PRD — the loop picks the lowest-priority o
 #   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)',
-        '- 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.',
-    ].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');
@@ -69,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);
@@ -123,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,11 +12,15 @@ 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({ permissions: z.enum(['safe', 'unsafe', 'read-only']) }).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(),

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/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/setup/command.js

@@ -0,0 +1,82 @@
+import { createInterface } from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { detectHostAgent } from '../agents/host.js';
+import { loadConfig, saveConfig } from '../retrofit/config.js';
+import { detectProject } from '../retrofit/detect.js';
+import { runRetrofit } from '../retrofit/command.js';
+const ALL_AGENTS = ['claude', 'codex', 'gemini'];
+function parseAgents(value, fallback) {
+    if (value.trim().toLowerCase() === 'all')
+        return [...ALL_AGENTS];
+    const parsed = value.split(',').map(v => v.trim().toLowerCase()).filter((v) => ALL_AGENTS.includes(v));
+    return parsed.length > 0 ? [...new Set(parsed)] : fallback;
+}
+function yes(value, fallback) {
+    const normalized = value.trim().toLowerCase();
+    if (['y', 'yes', 'j', 'ja', 'true', '1'].includes(normalized))
+        return true;
+    if (['n', 'no', 'nein', 'false', '0'].includes(normalized))
+        return false;
+    return fallback;
+}
+export async function runSetup(targetDir, opts = {}) {
+    const existing = loadConfig(targetDir);
+    const detected = detectProject(targetDir);
+    const host = opts.host ?? detectHostAgent();
+    const configuredAgents = existing?.agents.filter(a => ALL_AGENTS.includes(a)) ?? [];
+    const defaultAgents = opts.agents && opts.agents.length > 0
+        ? opts.agents
+        : configuredAgents.length > 0
+            ? configuredAgents
+            : detected.agents.length > 0
+                ? detected.agents
+                : [host ?? 'claude'];
+    const defaultGraph = opts.codeGraph ?? existing?.codeGraph ?? 'graphify';
+    const defaultLoop = opts.loop ?? existing?.loop.enabled ?? true;
+    const defaultRunner = opts.runner ?? existing?.runner?.agent ?? (host && defaultAgents.includes(host) ? host : defaultAgents[0] ?? host ?? 'claude');
+    const defaultPolicy = opts.decisionPolicy ?? existing?.loop.decisionPolicy ?? (existing?.loop.onAmbiguity === 'abort' ? 'critical' : 'auto');
+    const interactive = opts.interactive ?? (process.stdin.isTTY === true && process.stdout.isTTY === true);
+    let close;
+    let ask = opts.ask;
+    if (interactive && !ask) {
+        const rl = createInterface({ input, output });
+        ask = (question) => rl.question(question);
+        close = () => rl.close();
+    }
+    try {
+        let agents = defaultAgents;
+        let codeGraph = defaultGraph;
+        let loop = defaultLoop;
+        let runner = defaultRunner;
+        let decisionPolicy = defaultPolicy;
+        if (interactive && ask) {
+            agents = parseAgents(await ask(`Agents [${defaultAgents.join(',')}] (claude,codex,gemini|all): `), defaultAgents);
+            const graphAnswer = (await ask(`Code graph [${defaultGraph}] (graphify|serena): `)).trim().toLowerCase();
+            if (graphAnswer === 'graphify' || graphAnswer === 'serena')
+                codeGraph = graphAnswer;
+            loop = yes(await ask(`Enable autonomous loop? [${defaultLoop ? 'yes' : 'no'}]: `), defaultLoop);
+            const runnerAnswer = (await ask(`Default runner [${runner}] (claude|codex|gemini): `)).trim().toLowerCase();
+            if (ALL_AGENTS.includes(runnerAnswer))
+                runner = runnerAnswer;
+            const policyAnswer = (await ask(`Decision mode [${decisionPolicy}] (auto|critical): `)).trim().toLowerCase();
+            if (policyAnswer === 'auto' || policyAnswer === 'critical')
+                decisionPolicy = policyAnswer;
+        }
+        if (!agents.includes(runner))
+            agents = [...agents, runner];
+        const code = runRetrofit(targetDir, { loop, agents, codeGraph, host });
+        if (code !== 0)
+            return code;
+        const config = loadConfig(targetDir);
+        if (!config)
+            return 1;
+        config.loop = { ...config.loop, enabled: loop, decisionPolicy };
+        config.runner = { ...config.runner, agent: runner };
+        saveConfig(targetDir, config);
+        console.log(`Yoke setup complete: agents=${agents.join(',')} · runner=${runner} · loop=${loop ? 'on' : 'off'} · decisions=${decisionPolicy}`);
+        return 0;
+    }
+    finally {
+        close?.();
+    }
+}

package/docs/MIGRATING-TO-1.1.md

@@ -0,0 +1,27 @@
+# Migrating to Yoke 1.1
+
+Yoke 1.1 makes Claude, Codex, and Gemini share the same setup, planning, runner-selection, and decision behavior.
+
+Run the setup wizard once in an existing project:
+
+```bash
+npx @hecer/yoke@1.1.0 setup .
+```
+
+It preserves existing Yoke configuration and asks for target agents, code graph, loop state, default runner, and decision mode. A non-interactive agent can apply explicit choices with `--yes`.
+
+The new config fields are optional and backward-compatible:
+
+```yaml
+runner:
+  agent: codex
+  permissions: safe
+loop:
+  enabled: true
+  timeoutMinutes: 30
+  decisionPolicy: critical  # auto | critical
+```
+
+`loop.onAmbiguity: resolve|abort` and `--on-ambiguity=` still work. Prefer `decisionPolicy` for new projects: `auto` resolves routine choices without asking; `critical` pauses only for high-impact decisions and continues after `yoke loop answer`. Resume restores the original isolation, review, runner, permissions, timeout, and policy flags instead of silently weakening the run. If the restart cannot begin, `yoke loop resume` retries from the request-bound state stored under Git's private state directory.
+
+Restart an already-open Codex task after retrofit if it does not discover the newly generated `.agents/skills/yoke-workflow/SKILL.md`.

package/docs/PUBLISHING.md

@@ -1,41 +1,77 @@
-# Publishing channels — status & playbook
-
-Where Yoke is published, and how each channel gets updated. (Researched 2026-07-10.)
-
-## Live
-
-| Channel | How | Update path |
-|---|---|---|
-| **npm** — [`@hecer/yoke`](https://www.npmjs.com/package/@hecer/yoke) | `npm publish` (2FA) | every release |
-| **GitHub** — [HECer/yoke](https://github.com/HECer/yoke) | push + tag | every release |
-| **Claude Code plugin (self-marketplace)** | `.claude-plugin/plugin.json` + `marketplace.json` in this repo; users: `/plugin marketplace add HECer/yoke` → `/plugin install yoke@yoke` | bump `version` in `plugin.json` |
-| **Gemini CLI extension** | `gemini-extension.json` + `GEMINI-EXTENSION.md` at repo root; users: `gemini extensions install https://github.com/HECer/yoke` | bump `version` in the manifest |
-
-## Submitted / pending
-
-| Channel | How | Status |
-|---|---|---|
-| **Gemini extensions gallery** (geminicli.com/extensions) | automatic daily crawl: needs `gemini-extension.json` at repo root + `gemini-cli-extension` repo topic — both done | wait for crawler |
-| **Anthropic community plugin directory** (`claude-community`, surfaced in `/plugin > Discover`) | form at **platform.claude.com/plugins/submit** (Console account, Developer role; submit the public repo URL; `claude plugin validate` runs in their pipeline — passes locally). After approval: pinned to a commit SHA, CI auto-bumps on push, catalog syncs nightly | **needs a human login** — see below |
-
-### Anthropic directory submission (manual step)
-
-1. Log in at https://platform.claude.com (free Console account is enough; role Developer+).
-2. Open https://platform.claude.com/plugins/submit
-3. Submit the public repo: `https://github.com/HECer/yoke`
-4. Suggested description: *"Cross-agent coding harness: one curated skill canon (TDD,
-   brainstorming → spec → plan, systematic debugging, cross-model review, design
-   verification) plus mechanical safety gates and an autonomous loop via the yoke CLI."*
-5. Category: development. Plugin name (immutable): `yoke`.
-
-## Worth doing later (community lists, PR/issue-based)
-
-- **awesome-claude-code** (hesreallyhim) — issue-form only, explicitly human-submitted, no PRs.
-- **ComposioHQ/awesome-claude-plugins** — PR per template (high merge latency).
-- **davila7/claude-code-templates** (aitmpl.com) — PR per CONTRIBUTING.md.
-- **Codex plugin directory** (platform.openai.com/plugins) — requires verified developer
-  identity + test cases; medium-high effort. Codex CLI users can already consume the repo
-  marketplace directly.
-- Auto-crawled directories (crossaitools.com etc.) pick the repo up on their own once the
-  marketplace manifest exists.
-- Launch channels (Product Hunt, Show HN, r/ClaudeAI, r/ClaudeCode) — deliberate, human-led.
+# Publishing channels — status & playbook
+
+Where Yoke is published, and how each channel gets updated. (Reviewed 2026-07-30.)
+
+## Live
+
+| Channel | How | Update path |
+|---|---|---|
+| **npm** — [`@hecer/yoke`](https://www.npmjs.com/package/@hecer/yoke) | `npm publish` (2FA) | every release |
+| **GitHub** — [HECer/yoke](https://github.com/HECer/yoke) | push + tag + GitHub Release | every release |
+| **Claude Code plugin (self-marketplace)** | `.claude-plugin/plugin.json` + `marketplace.json` in this repo; users: `/plugin marketplace add HECer/yoke` → `/plugin install yoke@yoke` | bump `version` in `plugin.json` |
+| **Gemini CLI extension** | `gemini-extension.json` + `GEMINI-EXTENSION.md` at repo root; users: `gemini extensions install https://github.com/HECer/yoke` | bump `version` in the manifest |
+| **Codex project skills** | `npx @hecer/yoke setup .` writes the canon to `.agents/skills/` plus native Codex config/hooks; `.codex-plugin/plugin.json` is bundled for plugin-capable hosts | every npm release |
+
+## GitHub release (required, not just a tag)
+
+A pushed tag appears under **Tags**, but GitHub only shows an entry under **Releases** after a
+release object is created. Use this idempotent check after the version commit reaches `main`:
+
+```bash
+set -euo pipefail
+VERSION=1.1.0
+TARGET=$(git rev-parse HEAD)
+git fetch --tags origin
+
+REMOTE=$(git ls-remote origin "refs/tags/v$VERSION^{}" | awk 'NR == 1 { print $1 }')
+if [ -z "$REMOTE" ]; then
+  REMOTE=$(git ls-remote origin "refs/tags/v$VERSION" | awk 'NR == 1 { print $1 }')
+fi
+if [ -n "$REMOTE" ] && [ "$REMOTE" != "$TARGET" ]; then
+  echo "origin/v$VERSION already points at a different commit" >&2
+  exit 1
+fi
+
+if git rev-parse -q --verify "refs/tags/v$VERSION" >/dev/null; then
+  test "$(git rev-list -n 1 "v$VERSION")" = "$TARGET" || {
+    echo "v$VERSION already points at a different commit" >&2
+    exit 1
+  }
+else
+  git tag "v$VERSION"
+fi
+git push origin "refs/tags/v$VERSION"
+gh release view "v$VERSION" >/dev/null 2>&1 || \
+  gh release create "v$VERSION" --title "Yoke $VERSION" --generate-notes
+```
+
+Verify both surfaces before publishing npm: `gh release view "v$VERSION"` and
+`npm view @hecer/yoke version`.
+
+## Submitted / pending
+
+| Channel | How | Status |
+|---|---|---|
+| **Gemini extensions gallery** (geminicli.com/extensions) | automatic daily crawl: needs `gemini-extension.json` at repo root + `gemini-cli-extension` repo topic — both done | wait for crawler |
+| **Anthropic community plugin directory** (`claude-community`, surfaced in `/plugin > Discover`) | form at **platform.claude.com/plugins/submit** (Console account, Developer role; submit the public repo URL; `claude plugin validate` runs in their pipeline — passes locally). After approval: pinned to a commit SHA, CI auto-bumps on push, catalog syncs nightly | **needs a human login** — see below |
+
+### Anthropic directory submission (manual step)
+
+1. Log in at https://platform.claude.com (free Console account is enough; role Developer+).
+2. Open https://platform.claude.com/plugins/submit
+3. Submit the public repo: `https://github.com/HECer/yoke`
+4. Suggested description: *"Cross-agent coding harness: one curated skill canon (TDD,
+   brainstorming → spec → plan, systematic debugging, cross-model review, design
+   verification) plus mechanical safety gates and an autonomous loop via the yoke CLI."*
+5. Category: development. Plugin name (immutable): `yoke`.
+
+## Worth doing later (community lists, PR/issue-based)
+
+- **awesome-claude-code** (hesreallyhim) — issue-form only, explicitly human-submitted, no PRs.
+- **ComposioHQ/awesome-claude-plugins** — PR per template (high merge latency).
+- **davila7/claude-code-templates** (aitmpl.com) — PR per CONTRIBUTING.md.
+- **Codex plugin directory** — public directory submission remains a separate channel. Codex
+  users do not need it: the npm setup path installs native project skills deterministically.
+- Auto-crawled directories (crossaitools.com etc.) pick the repo up on their own once the
+  marketplace manifest exists.
+- Launch channels (Product Hunt, Show HN, r/ClaudeAI, r/ClaudeCode) — deliberate, human-led.

package/gemini-extension.json

@@ -0,0 +1,6 @@
+{
+  "name": "yoke",
+  "version": "1.1.0",
+  "description": "Cross-agent coding harness: curated skill canon, mechanical safety gates, autonomous loop with proof artifacts. CLI: npm i -g @hecer/yoke",
+  "contextFileName": "GEMINI-EXTENSION.md"
+}

package/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@hecer/yoke",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "One harness, three agents, zero trust in \"done\" — cross-agent coding harness for Claude Code, Codex CLI, and Gemini CLI: one skill canon, mechanical safety gates, an autonomous loop with screenshot/video proofs.",
   "type": "module",
   "bin": {
-    "yoke": "./dist/cli.js"
+    "yoke": "dist/cli.js"
   },
   "files": [
     "dist",
     "canon",
+    ".claude-plugin",
     ".codex-plugin",
+    "gemini-extension.json",
     "agents",
     "hooks",
     "bench/README.md",