@hecer/yoke 0.2.0

package/dist/loop/watchdog.js

@@ -0,0 +1,86 @@
+import { spawn } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
+export function runWatchdog(opts) {
+    const spawnFn = opts.spawnFn ?? spawn;
+    const out = opts.out ?? ((d) => process.stdout.write(d));
+    const err = opts.err ?? ((d) => process.stderr.write(d));
+    const child = spawnFn(opts.command, opts.args, { shell: process.platform === 'win32' });
+    if (opts.stdin && child.stdin) {
+        try {
+            opts.stdin.pipe(child.stdin);
+        }
+        catch { /* no stdin */ }
+    }
+    const graceMs = opts.graceMs ?? 5000;
+    return new Promise((resolve) => {
+        let timer;
+        let graceTimer;
+        let killedForIdle = false;
+        // Clear BOTH the idle timer and the post-SIGTERM grace timer so no dangling
+        // timers survive on any terminal path (close/error) or on each re-arm.
+        const clear = () => {
+            if (timer) {
+                clearTimeout(timer);
+                timer = undefined;
+            }
+            if (graceTimer) {
+                clearTimeout(graceTimer);
+                graceTimer = undefined;
+            }
+        };
+        const arm = () => {
+            if (opts.idleMs <= 0)
+                return;
+            // Once we've committed to killing, output no longer rescinds the escalation:
+            // a child that catches SIGTERM and keeps emitting heartbeats must not be able
+            // to reset the idle clock / cancel the pending SIGKILL. Forwarding still happens
+            // because the data handlers call out(d)/err(d) BEFORE arm().
+            if (killedForIdle)
+                return;
+            clear();
+            timer = setTimeout(() => {
+                timer = undefined;
+                killedForIdle = true;
+                try {
+                    child.kill('SIGTERM');
+                }
+                catch { /* already gone */ }
+                // Escalation: a child that catches/ignores SIGTERM would never emit
+                // 'close' and the promise would hang forever — defeating the watchdog.
+                // SIGKILL is uncatchable, so the child must close and we resolve.
+                // win32 limitation: with shell:true, SIGKILL on the shell may orphan
+                // grandchild processes (a resource-cleanup edge, not a hang) — not fixed here.
+                graceTimer = setTimeout(() => {
+                    graceTimer = undefined;
+                    try {
+                        child.kill('SIGKILL');
+                    }
+                    catch { /* already gone */ }
+                }, graceMs);
+            }, opts.idleMs);
+        };
+        child.stdout.on('data', (d) => { out(d); arm(); });
+        child.stderr.on('data', (d) => { err(d); arm(); });
+        child.on('error', () => { clear(); resolve(127); });
+        child.on('close', (code) => { clear(); resolve(killedForIdle ? 124 : (code ?? 0)); });
+        arm();
+    });
+}
+export function parseWatchdogArgs(argv) {
+    const sep = argv.indexOf('--');
+    const flags = sep === -1 ? argv : argv.slice(0, sep);
+    const rest = sep === -1 ? [] : argv.slice(sep + 1);
+    const idleArg = flags.find((a) => a.startsWith('--idle-ms='));
+    const idleMs = idleArg ? Number(idleArg.slice('--idle-ms='.length)) : 0;
+    const [command, ...args] = rest;
+    return { idleMs: Number.isFinite(idleMs) ? idleMs : 0, command: command ?? '', args };
+}
+const isMain = process.argv[1] ? pathToFileURL(process.argv[1]).href === import.meta.url : false;
+if (isMain) {
+    const { idleMs, command, args } = parseWatchdogArgs(process.argv.slice(2));
+    if (!command) {
+        process.stderr.write('watchdog: no command given\n');
+        process.exit(2);
+    }
+    runWatchdog({ command, args, idleMs, stdin: process.stdin }).then((code) => process.exit(code));
+}

package/dist/new/command.js

@@ -0,0 +1,53 @@
+import { existsSync, mkdirSync, readdirSync, statSync, writeFileSync, appendFileSync } from 'node:fs';
+import { join, basename, resolve } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { runRetrofit } from '../retrofit/command.js';
+import { runContextInit } from '../context/command.js';
+import { runPrdDraft, PRD_TEMPLATE } from '../prd/command.js';
+export function runNew(dir, opts = {}) {
+    const git = opts.git ?? ((args, cwd) => { execFileSync('git', args, { cwd, stdio: 'pipe' }); });
+    const target = resolve(dir);
+    if (existsSync(target) && (!statSync(target).isDirectory() || readdirSync(target).length > 0)) {
+        console.error(`${dir} already exists and is not empty — yoke new is greenfield-only (use yoke retrofit for existing projects).`);
+        return 1;
+    }
+    mkdirSync(target, { recursive: true });
+    git(['init'], target);
+    const name = basename(target);
+    writeFileSync(join(target, 'README.md'), `# ${name}\n${opts.idea ? `\n${opts.idea}\n` : ''}`);
+    writeFileSync(join(target, '.gitignore'), 'node_modules/\ndist/\n.env\n');
+    runRetrofit(target, { loop: opts.loop ?? false, agents: opts.agents });
+    runContextInit(target);
+    if (opts.idea) {
+        appendFileSync(join(target, '.yoke', 'context', 'PROJECT.md'), `\n## Idea\n\n${opts.idea}\n`);
+    }
+    writeFileSync(join(target, '.yoke', 'prd.yaml'), PRD_TEMPLATE);
+    git(['add', '-A'], target);
+    git(['-c', 'commit.gpgsign=false', 'commit', '-m', `chore: bootstrap ${name} with yoke`], target);
+    let code = 0;
+    if (opts.idea) {
+        const draft = runPrdDraft(target, {
+            idea: opts.idea,
+            runner: opts.runner,
+            timeoutMinutes: opts.timeoutMinutes,
+            isAvailable: opts.isAvailable,
+            run: opts.run,
+        });
+        if (draft === 0) {
+            git(['add', '-A'], target);
+            git(['-c', 'commit.gpgsign=false', 'commit', '-m', 'docs: draft PRD from idea'], target);
+        }
+        else {
+            console.error(`PRD draft did not succeed. The project is ready anyway; retry with: yoke prd draft ${dir} --idea="..."`);
+            code = draft;
+        }
+    }
+    console.log([
+        `✓ ${name} bootstrapped.`,
+        'Next steps:',
+        '  1. Review .yoke/prd.yaml (or draft it: yoke prd draft --idea="...")',
+        '  2. Set verify.command in .yoke/config.yaml (e.g. "npm test")',
+        `  3. yoke loop on ${dir} && yoke loop run ${dir} --isolate`,
+    ].join('\n'));
+    return code;
+}

package/dist/prd/command.js

@@ -0,0 +1,129 @@
+import { existsSync } 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';
+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
+#   acceptance:
+#     - "the verify command exits 0"
+#     - "a placeholder test exists and passes"
+#   passes: false
+[]
+`;
+export function buildPrdDraftPrompt(idea) {
+    return [
+        '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');
+}
+export function prdFile(targetDir) {
+    return join(targetDir, '.yoke', 'prd.yaml');
+}
+export function runPrdDraft(targetDir, opts) {
+    const idea = opts.idea?.trim();
+    if (!idea) {
+        console.error('yoke prd draft requires --idea="..."');
+        return 1;
+    }
+    const path = prdFile(targetDir);
+    if (existsSync(path) && !opts.force) {
+        try {
+            const existing = loadPrd(path);
+            if (existing.length > 0) {
+                console.error(`PRD already has ${existing.length} stories — use --force to overwrite.`);
+                return 1;
+            }
+        }
+        catch {
+            // an unparseable PRD is likely a hand-edit typo, not consent to overwrite
+            console.error('Existing .yoke/prd.yaml is unparseable — fix it, or pass --force to overwrite it.');
+            return 1;
+        }
+    }
+    const available = opts.isAvailable ?? isAgentAvailable;
+    const config = loadConfig(targetDir);
+    const agent = opts.runner ?? config?.agents[0] ?? 'claude';
+    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);
+    console.log(`Drafting PRD with ${agent}...`);
+    const run = opts.run ?? ((i) => runAgent(buildWatchdogInvocation(i, idleMs)));
+    const result = run(inv);
+    if (!result.success) {
+        console.error(`PRD draft failed: ${result.summary}`);
+        return 1;
+    }
+    let count;
+    try {
+        count = loadPrd(path).length;
+    }
+    catch (e) {
+        console.error(`PRD draft produced an invalid PRD: ${e.message}`);
+        return 1;
+    }
+    if (count === 0) {
+        console.error('PRD draft failed: agent produced an empty PRD.');
+        return 1;
+    }
+    console.log(`Drafted ${count} stories → ${path}`);
+    return 0;
+}
+export function runPrdCheck(targetDir) {
+    const path = prdFile(targetDir);
+    if (!existsSync(path)) {
+        console.error(`No PRD at ${path} — create one with yoke prd draft or yoke new.`);
+        return 1;
+    }
+    let stories;
+    try {
+        stories = loadPrd(path);
+    }
+    catch (e) {
+        console.error(`Invalid PRD: ${e.message}`);
+        return 1;
+    }
+    const errors = [];
+    if (stories.length === 0)
+        errors.push('PRD has no stories');
+    const seen = new Set();
+    for (const s of stories) {
+        if (seen.has(s.id))
+            errors.push(`duplicate story id: ${s.id}`);
+        seen.add(s.id);
+        // 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 (errors.length > 0) {
+        for (const e of errors)
+            console.error(`ERROR ${e}`);
+        return 1;
+    }
+    const p = progress(stories);
+    console.log(`✓ PRD valid — ${p.total} stories, ${p.passed} pass`);
+    return 0;
+}

package/dist/retrofit/apply.js

@@ -0,0 +1,54 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { mergeJson } from './merge-json.js';
+export function applyActions(actions, targetDir, opts) {
+    const results = [];
+    for (const action of actions) {
+        const dest = join(targetDir, action.target);
+        let status;
+        let backedUp;
+        if (existsSync(dest)) {
+            if (action.ifAbsent) {
+                results.push({ target: action.target, status: 'unchanged', reason: `${action.reason} (exists, left untouched)` });
+                continue;
+            }
+            const current = readFileSync(dest, 'utf8');
+            if (action.merge) {
+                let parsedCurrent;
+                try {
+                    parsedCurrent = JSON.parse(current);
+                }
+                catch {
+                    throw new Error(`yoke: cannot merge ${action.target} — existing file is not valid JSON. Fix or delete it and re-run.`);
+                }
+                const merged = JSON.stringify(mergeJson(parsedCurrent, JSON.parse(action.content)), null, 2) + '\n';
+                if (merged === current) {
+                    results.push({ target: action.target, status: 'unchanged', reason: action.reason });
+                    continue;
+                }
+                backedUp = join(opts.backupDir, action.target);
+                mkdirSync(dirname(backedUp), { recursive: true });
+                copyFileSync(dest, backedUp);
+                mkdirSync(dirname(dest), { recursive: true });
+                writeFileSync(dest, merged);
+                results.push({ target: action.target, status: 'merged', backedUp, reason: action.reason });
+                continue;
+            }
+            if (current === action.content) {
+                results.push({ target: action.target, status: 'unchanged', reason: action.reason });
+                continue;
+            }
+            backedUp = join(opts.backupDir, action.target);
+            mkdirSync(dirname(backedUp), { recursive: true });
+            copyFileSync(dest, backedUp);
+            status = 'overwritten';
+        }
+        else {
+            status = 'created';
+        }
+        mkdirSync(dirname(dest), { recursive: true });
+        writeFileSync(dest, action.content);
+        results.push({ target: action.target, status, backedUp, reason: action.reason });
+    }
+    return results;
+}

package/dist/retrofit/canon-dir.js

@@ -0,0 +1,22 @@
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// Walk up from this module to the package root (the dir containing package.json),
+// then return its `canon/` directory. Works under both tsx (src/) and built dist/.
+export function resolveCanonDir() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 10; i++) {
+        if (existsSync(join(dir, 'package.json'))) {
+            const canon = join(dir, 'canon');
+            if (existsSync(join(canon, 'manifest.yaml'))) {
+                return canon;
+            }
+            throw new Error(`yoke installation incomplete — canon/ missing at ${canon}`);
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new Error('could not locate package root to resolve canon/');
+}

package/dist/retrofit/command.js

@@ -0,0 +1,37 @@
+import { join } from 'node:path';
+import { resolveCanonDir } from './canon-dir.js';
+import { planRetrofit } from './plan.js';
+import { applyActions } from './apply.js';
+import { formatReport } from './report.js';
+import { detectProject } from './detect.js';
+import { ensureGitignore } from './gitignore.js';
+import { loadConfig, saveConfig, defaultConfig } from './config.js';
+import { loadManifest } from '../canon/manifest.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']);
+    const existing = loadConfig(targetDir);
+    const codeGraph = opts.codeGraph ?? existing?.codeGraph ?? 'graphify';
+    const actions = planRetrofit(canonDir, targetDir, agents, codeGraph);
+    const backupDir = join(targetDir, '.yoke', 'backup', String(Date.now()));
+    const applied = applyActions(actions, targetDir, { backupDir });
+    // Ensure runtime artifacts (loop status/log, worktrees, backups) are gitignored
+    // so the loop's clean-tree pre-dispatch gate is not broken by untracked files.
+    ensureGitignore(targetDir);
+    const priorAgents = existing?.agents ?? [];
+    const mergedAgents = [...new Set([...priorAgents, ...agents])];
+    const config = {
+        ...(existing ?? defaultConfig(canonVersion)),
+        canonVersion,
+        agents: mergedAgents,
+        loop: { enabled: opts.loop },
+        codeGraph,
+    };
+    saveConfig(targetDir, config);
+    console.log(formatReport(applied, { loopEnabled: config.loop.enabled, detectedAgents: detection.agents }));
+    return 0;
+}

package/dist/retrofit/config.js

@@ -0,0 +1,53 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { parse, stringify } from 'yaml';
+import { z } from 'zod';
+const AgentSchema = z.enum(['claude', 'codex', 'gemini']);
+const CodeGraphSchema = z.enum(['graphify', 'serena']);
+const SmokeFlowSchema = z.object({ name: z.string().min(1), path: z.string().min(1), landmark: z.string().optional() });
+const SmokeSchema = z.object({ baseUrl: z.string().min(1), flows: z.array(SmokeFlowSchema).min(1) });
+export const YokeConfigSchema = z.object({
+    canonVersion: z.string().min(1),
+    agents: z.array(AgentSchema),
+    loop: z.object({ enabled: z.boolean(), timeoutMinutes: z.number().optional() }),
+    verify: z.object({ command: z.string().min(1), retries: z.number().int().nonnegative().optional() }).optional(),
+    codeGraph: CodeGraphSchema.optional(),
+    smoke: SmokeSchema.optional(),
+});
+export function defaultConfig(canonVersion) {
+    return { canonVersion, agents: [], loop: { enabled: false } };
+}
+export function configPath(targetDir) {
+    return join(targetDir, '.yoke', 'config.yaml');
+}
+export function loadConfig(targetDir) {
+    const file = configPath(targetDir);
+    if (!existsSync(file))
+        return null;
+    return YokeConfigSchema.parse(parse(readFileSync(file, 'utf8')));
+}
+export function saveConfig(targetDir, config) {
+    const file = configPath(targetDir);
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, stringify(config));
+}
+// Decide which command verifies a story is done: explicit config wins; otherwise
+// detect an npm test script; otherwise null (caller must refuse to run blindly).
+export function resolveVerifyCommand(targetDir, config) {
+    if (config.verify?.command)
+        return config.verify.command;
+    const pkgPath = join(targetDir, 'package.json');
+    if (existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+            const testScript = pkg?.scripts?.test;
+            if (typeof testScript === 'string' && testScript.trim() !== '' && !testScript.includes('no test specified')) {
+                return 'npm test';
+            }
+        }
+        catch {
+            // ignore malformed package.json
+        }
+    }
+    return null;
+}

package/dist/retrofit/context-actions.js

@@ -0,0 +1,21 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+const CONTEXT_FILES = ['PROJECT.md', 'DECISIONS.md', 'KNOWLEDGE.md'];
+export function baseContextActions(canonDir) {
+    return CONTEXT_FILES.map(name => {
+        let content;
+        try {
+            content = readFileSync(join(canonDir, 'context', name), 'utf8');
+        }
+        catch {
+            throw new Error(`yoke: missing context template ${name} in ${canonDir}/context — run \`yoke validate canon\` to diagnose the canon.`);
+        }
+        return {
+            kind: 'write',
+            target: `.yoke/context/${name}`,
+            content,
+            reason: `context scaffold: ${name}`,
+            ifAbsent: true,
+        };
+    });
+}

package/dist/retrofit/detect.js

@@ -0,0 +1,17 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+export function detectProject(targetDir) {
+    const has = (...parts) => existsSync(join(targetDir, ...parts));
+    const agents = [];
+    if (has('.claude') || has('CLAUDE.md'))
+        agents.push('claude');
+    if (has('.codex') || has('AGENTS.md'))
+        agents.push('codex');
+    if (has('.gemini') || has('GEMINI.md'))
+        agents.push('gemini');
+    return {
+        agents,
+        hasAgentsMd: has('AGENTS.md'),
+        hasYokeConfig: has('.yoke', 'config.yaml'),
+    };
+}

package/dist/retrofit/gitignore.js

@@ -0,0 +1,26 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const YOKE_IGNORE_LINES = [
+    '.yoke/worktrees/',
+    '.yoke/backup/',
+    '.yoke/loop-status.json',
+    '.yoke/loop.log',
+    '.yoke/loop.lock',
+    '.yoke/proof/',
+];
+const HEADER = '# Yoke runtime artifacts (managed by yoke retrofit)';
+// Idempotently ensure each Yoke runtime path is gitignored. Appends only the
+// lines not already present (matched verbatim, line-wise). Preserves existing
+// content. Returns true if the file changed.
+export function ensureGitignore(targetDir) {
+    const file = join(targetDir, '.gitignore');
+    const current = existsSync(file) ? readFileSync(file, 'utf8') : '';
+    const present = new Set(current.split(/\r?\n/).map((l) => l.trim()));
+    const missing = YOKE_IGNORE_LINES.filter((l) => !present.has(l));
+    if (missing.length === 0)
+        return false;
+    const prefix = current === '' ? '' : current.endsWith('\n') ? '' : '\n';
+    const block = `${prefix}${current === '' ? '' : '\n'}${HEADER}\n${missing.join('\n')}\n`;
+    writeFileSync(file, current + block);
+    return true;
+}

package/dist/retrofit/gstack.js

@@ -0,0 +1,19 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+// Best-effort, non-fatal detection of a gstack install (garrytan/gstack).
+// gstack lives at ~/.claude/skills/gstack (global) or .claude/skills/gstack (repo-local).
+export function detectGstack(targetDir, home = homedir()) {
+    const candidates = [
+        join(targetDir, '.claude', 'skills', 'gstack'),
+        join(home, '.claude', 'skills', 'gstack'),
+    ];
+    return candidates.some(p => {
+        try {
+            return existsSync(p);
+        }
+        catch {
+            return false;
+        }
+    });
+}

package/dist/retrofit/merge-json.js

@@ -0,0 +1,38 @@
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+// Order-independent serialization: object keys are sorted recursively so two
+// structurally-equal values compare equal regardless of key order. Used to
+// de-dupe array items (e.g. a hand-edited hook block with reordered keys must
+// not duplicate our entry).
+function stableStringify(v) {
+    if (Array.isArray(v))
+        return '[' + v.map(stableStringify).join(',') + ']';
+    if (isPlainObject(v)) {
+        return '{' + Object.keys(v).sort().map(k => JSON.stringify(k) + ':' + stableStringify(v[k])).join(',') + '}';
+    }
+    return JSON.stringify(v);
+}
+// Deep-merge two parsed JSON values. Objects merge by key (recursing on shared
+// keys). Arrays concatenate with structural de-duplication. For any other type
+// mismatch or primitive collision, the incoming value wins.
+export function mergeJson(base, incoming) {
+    if (isPlainObject(base) && isPlainObject(incoming)) {
+        // null prototype: incoming __proto__ becomes a plain own key, never pollutes.
+        const out = Object.assign(Object.create(null), base);
+        for (const [key, value] of Object.entries(incoming)) {
+            out[key] = key in base ? mergeJson(base[key], value) : value;
+        }
+        return out;
+    }
+    if (Array.isArray(base) && Array.isArray(incoming)) {
+        const out = [...base];
+        for (const item of incoming) {
+            if (!out.some(existing => stableStringify(existing) === stableStringify(item))) {
+                out.push(item);
+            }
+        }
+        return out;
+    }
+    return incoming;
+}

package/dist/retrofit/plan.js

@@ -0,0 +1,29 @@
+import { planClaude } from './planners/claude.js';
+import { planCodex } from './planners/codex.js';
+import { planGemini } from './planners/gemini.js';
+import { baseContextActions } from './context-actions.js';
+export function planClaudeRetrofit(canonDir, targetDir) {
+    return planClaude(canonDir, targetDir);
+}
+export const PLANNERS = {
+    claude: (c, t, cg) => planClaude(c, t, undefined, cg),
+    codex: planCodex,
+    gemini: planGemini,
+};
+export function planRetrofit(canonDir, targetDir, agents, codeGraph = 'graphify') {
+    const seen = new Set();
+    const merged = [];
+    for (const action of baseContextActions(canonDir)) {
+        seen.add(action.target);
+        merged.push(action);
+    }
+    for (const agent of agents) {
+        for (const action of PLANNERS[agent](canonDir, targetDir, codeGraph)) {
+            if (seen.has(action.target))
+                continue;
+            seen.add(action.target);
+            merged.push(action);
+        }
+    }
+    return merged;
+}

package/dist/retrofit/planners/claude.js

@@ -0,0 +1,67 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadManifest } from '../../canon/manifest.js';
+import { mcpServers, rtkInstruction } from '../tools.js';
+import { hasWsl } from '../wsl.js';
+import { detectGstack } from '../gstack.js';
+const GSTACK_COMPOSE = `## Composed tools (gstack detected)
+
+This project also has [gstack](https://github.com/garrytan/gstack) installed. For capabilities Yoke does not ship, prefer gstack's skills:
+
+- Live-browser QA → \`/qa\`
+- Security audit → \`/cso\`
+- Ship / deploy → \`/ship\`, \`/land-and-deploy\`
+`;
+const claudeMd = (rtkNote, composeNote) => `# Project Instructions
+
+This project uses the Yoke harness. Baseline instructions:
+
+@AGENTS.md
+${rtkNote ? `\n${rtkNote}\n` : ''}${composeNote ? `\n${composeNote}\n` : ''}`;
+export function planClaude(canonDir, targetDir, wslAvailable = hasWsl(), codeGraph = 'graphify', gstackDetected = detectGstack(targetDir)) {
+    const manifest = loadManifest(join(canonDir, 'manifest.yaml'));
+    const actions = [];
+    for (const skill of manifest.skills) {
+        actions.push({
+            kind: 'write',
+            target: `.claude/skills/${skill.id}/SKILL.md`,
+            content: readFileSync(join(canonDir, skill.path, 'SKILL.md'), 'utf8'),
+            reason: `skill: ${skill.id}`,
+        });
+    }
+    actions.push({
+        kind: 'write',
+        target: 'AGENTS.md',
+        content: readFileSync(join(canonDir, 'AGENTS.md'), 'utf8'),
+        reason: 'baseline instructions',
+    });
+    // rtk: PreToolUse hook needs WSL on Windows; otherwise fall back to instruction mode.
+    const rtkHookable = wslAvailable;
+    actions.push({
+        kind: 'write',
+        target: 'CLAUDE.md',
+        content: claudeMd(rtkHookable ? '' : rtkInstruction(), gstackDetected ? GSTACK_COMPOSE : ''),
+        reason: 'Claude entry importing AGENTS.md',
+    });
+    actions.push({
+        kind: 'write',
+        target: '.mcp.json',
+        content: JSON.stringify({ mcpServers: mcpServers(codeGraph) }, null, 2) + '\n',
+        reason: 'MCP servers (code-graph + playwright)',
+    });
+    if (rtkHookable) {
+        actions.push({
+            kind: 'write',
+            target: '.claude/settings.json',
+            merge: true,
+            content: JSON.stringify({
+                _yoke: 'Generated by yoke retrofit. A pre-existing .claude/settings.json (if any) was backed up under .yoke/backup/.',
+                hooks: {
+                    PreToolUse: [{ matcher: 'Bash', hooks: [{ type: 'command', command: 'rtk hook claude' }] }],
+                },
+            }, null, 2) + '\n',
+            reason: 'rtk PreToolUse hook (WSL detected)',
+        });
+    }
+    return actions;
+}