@hecer/yoke 0.2.0

package/dist/retrofit/planners/codex.js

@@ -0,0 +1,36 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { mcpServers, rtkInstruction } from '../tools.js';
+function tomlMcp(codeGraph) {
+    const servers = mcpServers(codeGraph);
+    // Codex reads MCP servers from ~/.codex/config.toml. This project-level file is a
+    // ready-to-merge snippet; users append these blocks to their global config.
+    return Object.entries(servers)
+        .map(([name, cfg]) => {
+        const args = cfg.args.map(a => `"${a}"`).join(', ');
+        return `[mcp_servers.${name}]\ncommand = "${cfg.command}"\nargs = [${args}]\n`;
+    })
+        .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)',
+        },
+    ];
+}

package/dist/retrofit/planners/gemini.js

@@ -0,0 +1,54 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadManifest } from '../../canon/manifest.js';
+import { parseFrontmatter } from '../../canon/frontmatter.js';
+import { mcpServers, rtkInstruction } from '../tools.js';
+function tomlString(s) {
+    return '"""\n' + s.replace(/\\/g, '\\\\').replace(/"""/g, '\\"\\"\\"') + '\n"""';
+}
+export function planGemini(canonDir, _targetDir, codeGraph = 'graphify') {
+    const manifest = loadManifest(join(canonDir, 'manifest.yaml'));
+    const actions = [];
+    // GEMINI.md: baseline + rtk instruction (Gemini has no rewrite hook).
+    const baseline = readFileSync(join(canonDir, 'AGENTS.md'), 'utf8');
+    actions.push({
+        kind: 'write',
+        target: 'GEMINI.md',
+        content: `${baseline}\n${rtkInstruction()}\n`,
+        reason: 'baseline + rtk instruction (no hook on Gemini)',
+    });
+    // One TOML slash command per skill.
+    for (const skill of manifest.skills) {
+        const body = readFileSync(join(canonDir, skill.path, 'SKILL.md'), 'utf8');
+        const fm = parseFrontmatter(body) ?? {};
+        // Collapse any newlines so the single-line TOML `description = "..."` stays valid
+        // even for ported skills whose frontmatter description spans multiple lines.
+        const description = String(fm.description ?? skill.id).replace(/\s*\r?\n\s*/g, ' ').trim();
+        const skillBody = body.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '').trim();
+        const prompt = `You are using the "${skill.id}" skill.\n\n${skillBody}\n\nFollow it for the current task.`;
+        actions.push({
+            kind: 'write',
+            target: `.gemini/commands/${skill.id}.toml`,
+            content: `description = "${description.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"\nprompt = ${tomlString(prompt)}\n`,
+            reason: `gemini command: ${skill.id}`,
+        });
+    }
+    // settings.json: MCP servers + read AGENTS.md as context.
+    actions.push({
+        kind: 'write',
+        target: '.gemini/settings.json',
+        content: JSON.stringify({
+            mcpServers: mcpServers(codeGraph),
+            context: { fileName: ['AGENTS.md', 'GEMINI.md'] },
+        }, null, 2) + '\n',
+        reason: 'MCP servers + AGENTS.md context',
+    });
+    // Also ship AGENTS.md so the context.fileName entry resolves.
+    actions.push({
+        kind: 'write',
+        target: 'AGENTS.md',
+        content: baseline,
+        reason: 'baseline instructions (shared)',
+    });
+    return actions;
+}

package/dist/retrofit/report.js

@@ -0,0 +1,14 @@
+export function formatReport(applied, meta) {
+    const count = (s) => applied.filter(a => a.status === s).length;
+    const lines = [];
+    lines.push('Yoke retrofit (Claude Code):');
+    for (const a of applied) {
+        const note = a.backedUp ? ` (backup: ${a.backedUp})` : '';
+        lines.push(`  ${a.status.padEnd(11)} ${a.target}${note}`);
+    }
+    lines.push('');
+    lines.push(`Detected agents: ${meta.detectedAgents.length ? meta.detectedAgents.join(', ') : 'none'}`);
+    lines.push(`Summary: ${count('created')} created, ${count('overwritten')} overwritten, ${count('merged')} merged, ${count('unchanged')} unchanged`);
+    lines.push(`Loop: ${meta.loopEnabled ? 'enabled' : 'disabled'}`);
+    return lines.join('\n');
+}

package/dist/retrofit/tools.js

@@ -0,0 +1,23 @@
+// Best-effort launch commands per code-graph tool. Users may need to adjust these
+// to match their local install (graphify: `uv tool install graphify`; serena: `uv`,
+// e.g. `uvx --from git+https://github.com/oraios/serena serena-mcp-server`).
+const CODE_GRAPH_SERVERS = {
+    graphify: { command: 'graphify', args: ['serve'] },
+    serena: { command: 'serena', args: ['start-mcp-server'] },
+};
+export function mcpServers(codeGraph = 'graphify') {
+    return {
+        [codeGraph]: CODE_GRAPH_SERVERS[codeGraph],
+        playwright: { command: 'npx', args: ['@playwright/mcp@latest'] },
+    };
+}
+// rtk has no transparent-rewrite hook on Codex/Gemini; those agents get this
+// instruction instead. On Claude (Windows) it is also the WSL-less fallback.
+export function rtkInstruction() {
+    return [
+        '## Token efficiency (rtk)',
+        '',
+        'Prefix shell/dev commands with `rtk` to compress their output before it enters context.',
+        'Example: `rtk git status`, `rtk npm test`. See https://github.com/rtk-ai/rtk.',
+    ].join('\n');
+}

package/dist/retrofit/wsl.js

@@ -0,0 +1,15 @@
+import { execFileSync } from 'node:child_process';
+// True only on Windows where a WSL distribution responds. Used to decide whether
+// rtk can use its transparent PreToolUse hook (needs WSL) or must fall back to
+// instruction mode. Never throws.
+export function hasWsl() {
+    if (process.platform !== 'win32')
+        return false;
+    try {
+        execFileSync('wsl', ['--status'], { stdio: 'pipe', timeout: 5000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/review/command.js

@@ -0,0 +1,43 @@
+import { agentInvocation, buildStandaloneReviewPrompt, buildWatchdogInvocation, runAgent, isAgentAvailable, } from '../loop/runner.js';
+import { resolveIdleMs } from '../loop/run-command.js';
+// Resolve to the first available agent, preferring a *second* model so the review
+// is genuinely cross-model. claude last => a Claude-only box degrades to self-review.
+const RESOLUTION_ORDER = ['codex', 'gemini', 'claude'];
+export function runReview(targetDir, opts = {}) {
+    const available = opts.isAvailable ?? isAgentAvailable;
+    let reviewer = opts.reviewer;
+    if (reviewer) {
+        if (!available(reviewer)) {
+            console.error(`Reviewer agent CLI "${reviewer}" was not found on PATH. Install it, or pick another with --reviewer=<claude|codex|gemini>.`);
+            return 2;
+        }
+    }
+    else {
+        reviewer = RESOLUTION_ORDER.find(a => available(a));
+        if (!reviewer) {
+            console.error('No agent CLI (claude|codex|gemini) found on PATH. Install one to run a review.');
+            return 2;
+        }
+        if (reviewer === 'claude') {
+            console.log('Note: only Claude is available — this is a self-review, not cross-model.');
+        }
+    }
+    const scope = opts.base
+        ? `the diff ${opts.base}..HEAD`
+        : 'the uncommitted working-tree changes (working tree + staged)';
+    const prompt = buildStandaloneReviewPrompt(scope, opts.focus);
+    const idleMs = resolveIdleMs(opts.timeoutMinutes, undefined);
+    // Pass the *agent* invocation to the runner so callers (and tests) see the
+    // reviewer command. The default runner adds the watchdog wrapper before exec;
+    // an injected run() gets the raw invocation.
+    const inv = agentInvocation(reviewer, prompt, targetDir);
+    console.log(`Reviewing ${scope} with ${reviewer}...`);
+    const run = opts.run ?? ((i) => runAgent(buildWatchdogInvocation(i, idleMs)));
+    const result = run(inv);
+    if (result.success) {
+        console.log(`✓ ${reviewer} approved`);
+        return 0;
+    }
+    console.log(`✗ ${reviewer} found issues (${result.summary})`);
+    return 1;
+}

package/dist/scan/design.js

@@ -0,0 +1,79 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, extname } from 'node:path';
+const AI_PURPLE_HEX = /#(6c5ce7|7c3aed|8b5cf6|a855f7|9333ea)\b/i;
+const AI_PURPLE_TW = /\b(from|via|to)-(purple|violet|fuchsia)-(4|5|6|7)00\b/i;
+const NEON_TW = /\b(shadow|drop-shadow)-\[0_0_/i;
+const NEON_CSS = /box-shadow:[^;]*\b0\s+0\s+\d{2,}px/i;
+const EMOJI = /\p{Extended_Pictographic}/u;
+const JSX_ICON_CTX = /<button|<a\s|aria-hidden|(icon|emoji)/i;
+export const TELLS = [
+    { name: 'ai-purple', weight: 2, hint: 'AI-purple is the #1 vibecoded tell — pick a real brand color',
+        test: (l) => AI_PURPLE_HEX.test(l) || AI_PURPLE_TW.test(l) },
+    { name: 'gradient-clip-text', weight: 2, hint: 'Gradient hero text reads as AI-slop — use a solid color + weight',
+        test: (l) => (/bg-clip-text/.test(l) && /text-transparent/.test(l)) || /-webkit-background-clip:\s*text/i.test(l) },
+    { name: 'neon-glow', weight: 2, hint: 'Neon glow is a tell — use subtle, neutral elevation',
+        test: (l) => NEON_TW.test(l) || NEON_CSS.test(l) },
+    // A purple gradient legitimately trips BOTH ai-purple and gradient-overload — that double-count
+    // is intentional (two distinct tells), and the weights are kept small so it never dominates.
+    { name: 'gradient-overload', weight: 1, hint: 'Gradients everywhere flatten hierarchy — use them sparingly',
+        test: (l) => /bg-gradient-to-/.test(l) || /linear-gradient\(/i.test(l) },
+    { name: 'emoji-icon', weight: 1, hint: 'Emoji-as-icons is a tell — use a real icon set',
+        test: (l) => EMOJI.test(l) && JSX_ICON_CTX.test(l) },
+];
+// One match per (line, tell) at most, so a line with three purple classes counts once.
+export function scanText(text, tells = TELLS) {
+    const matches = [];
+    const lines = text.split(/\r?\n/);
+    lines.forEach((line, i) => {
+        for (const tell of tells) {
+            if (tell.test(line))
+                matches.push({ line: i + 1, tell, text: line.trim().slice(0, 200) });
+        }
+    });
+    return matches;
+}
+const EXT = new Set(['.css', '.scss', '.tsx', '.jsx', '.ts', '.js', '.html', '.vue', '.svelte', '.astro']);
+const SKIP = new Set(['node_modules', 'dist', '.next', 'build', '.yoke', 'coverage', '.git', 'out', '__fixtures__', '__mocks__']);
+// Test/spec/story files routinely embed slop patterns as FIXTURES (a purple gradient in a
+// snapshot, a neon shadow in a render test). Scanning them would make the gate flag test data
+// as if it were shipped UI, so they're excluded — the scanner gates real source, not fixtures.
+const FIXTURE = /\.(test|spec|stories|story)\.[cm]?[jt]sx?$/i;
+function walk(dir, acc) {
+    for (const entry of readdirSync(dir)) {
+        const full = join(dir, entry);
+        let s;
+        try {
+            s = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (s.isDirectory()) {
+            if (!SKIP.has(entry))
+                walk(full, acc);
+        }
+        else if (EXT.has(extname(entry).toLowerCase()) && !FIXTURE.test(entry)) {
+            acc.push(full);
+        }
+    }
+}
+export function scanDir(dir, tells = TELLS) {
+    const files = [];
+    walk(dir, files);
+    const findings = [];
+    let score = 0;
+    for (const file of files) {
+        let text;
+        try {
+            text = readFileSync(file, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const m of scanText(text, tells)) {
+            findings.push({ file, line: m.line, tell: m.tell.name, hint: m.tell.hint, text: m.text });
+            score += m.tell.weight;
+        }
+    }
+    return { findings, score };
+}

package/dist/smoke/command.js

@@ -0,0 +1,141 @@
+import { mkdirSync, rmSync, renameSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { createRequire } from 'node:module';
+import { loadConfig } from '../retrofit/config.js';
+const CONFIG_GUIDANCE = [
+    'No smoke flows configured. Add a smoke section to .yoke/config.yaml, e.g.:',
+    '',
+    'smoke:',
+    '  baseUrl: http://localhost:3000',
+    '  flows:',
+    '    - name: home',
+    '      path: /',
+    '      landmark: "main h1"',
+].join('\n');
+export async function launchPlaywright(targetDir) {
+    try {
+        // createRequire needs an absolute anchor — a relative targetDir (the CLI
+        // default '.') would throw and masquerade as "playwright not found".
+        // Playwright is CJS, so load it with native require() rather than a
+        // file:// dynamic import — the URL round-trip breaks under Windows 8.3
+        // short paths (e.g. RUNNER~1 on CI) and test-runner import interception.
+        const req = createRequire(join(resolve(targetDir), 'package.json'));
+        const pw = req('playwright');
+        const chromium = pw.chromium ?? pw.default?.chromium;
+        if (!chromium)
+            return null;
+        return await chromium.launch({ headless: true });
+    }
+    catch {
+        return null;
+    }
+}
+// Flow names come from user config and become filenames — keep them safe.
+function safeName(name) {
+    return name.replace(/[^\w.-]+/g, '-');
+}
+// The label names a directory that gets rmSync'd recursively — it must never
+// carry path semantics ('..', separators). Dots are stripped entirely so a
+// bare '..' cannot survive; an emptied label falls back to 'latest'.
+export function safeLabel(label) {
+    const cleaned = label.replace(/[^\w-]+/g, '-').replace(/^-+|-+$/g, '');
+    return cleaned || 'latest';
+}
+export async function runFlowSmoke(targetDir, opts = {}) {
+    const config = loadConfig(targetDir);
+    const smoke = config?.smoke;
+    if (!smoke) {
+        console.error(CONFIG_GUIDANCE);
+        return 2;
+    }
+    const baseUrl = opts.url ?? smoke.baseUrl;
+    const label = safeLabel(opts.label ?? process.env.YOKE_STORY ?? 'latest');
+    const proofRel = join('.yoke', 'proof', label);
+    const proofDir = join(targetDir, proofRel);
+    const launch = opts.launch ?? launchPlaywright;
+    const browser = await launch(targetDir);
+    if (!browser) {
+        console.error(`Playwright not found in ${targetDir}. Install it: npm i -D playwright && npx playwright install chromium`);
+        return 2;
+    }
+    // Wipe only once the run is actually going to happen — an exit-2 run must
+    // not destroy the previous run's evidence.
+    rmSync(proofDir, { recursive: true, force: true }); // fresh evidence per run
+    mkdirSync(proofDir, { recursive: true });
+    const videoTmp = join(proofDir, '.video-tmp');
+    let green = 0;
+    try {
+        for (const flow of smoke.flows) {
+            const context = await browser.newContext({ recordVideo: { dir: videoTmp } });
+            const page = await context.newPage();
+            const errors = [];
+            page.on('console', (msg) => {
+                const m = msg;
+                if (m.type?.() === 'error')
+                    errors.push(String(m.text?.() ?? msg));
+            });
+            page.on('pageerror', (err) => {
+                errors.push(String(err?.message ?? err));
+            });
+            let reason;
+            try {
+                const resp = await page.goto(baseUrl + flow.path, { waitUntil: 'load', timeout: 30_000 });
+                if (resp && !resp.ok())
+                    reason = `HTTP ${resp.status()}`;
+                if (!reason && flow.landmark) {
+                    try {
+                        await page.waitForSelector(flow.landmark, { timeout: 10_000 });
+                    }
+                    catch {
+                        reason = `landmark "${flow.landmark}" not found`;
+                    }
+                }
+                if (!reason && errors.length > 0) {
+                    reason = `${errors.length} console error(s): ${errors[0].slice(0, 200)}`;
+                }
+            }
+            catch (e) {
+                reason = e.message.split('\n')[0];
+            }
+            // The screenshot IS the evidence — taken on success AND failure; a crashed
+            // page must not mask the original failure.
+            const shotName = `${safeName(flow.name)}.png`;
+            let shotOk = false;
+            try {
+                await page.screenshot({ path: join(proofDir, shotName), fullPage: true });
+                shotOk = true;
+            }
+            catch { /* keep the original reason */ }
+            const video = page.video();
+            await context.close();
+            let videoKept = false;
+            if (video) {
+                try {
+                    const vpath = await video.path();
+                    if (reason) {
+                        renameSync(vpath, join(proofDir, `${safeName(flow.name)}.webm`));
+                        videoKept = true;
+                    }
+                    else {
+                        rmSync(vpath, { force: true });
+                    }
+                }
+                catch { /* video is best-effort evidence */ }
+            }
+            if (reason) {
+                const saved = [shotOk ? 'screenshot' : null, videoKept ? 'video' : null].filter(Boolean).join(' + ');
+                console.log(`✘ ${flow.name} — ${reason}${saved ? ` (${saved} saved under ${proofRel})` : ''}`);
+            }
+            else {
+                green++;
+                console.log(`✔ ${flow.name} (screenshot: ${join(proofRel, shotName)})`);
+            }
+        }
+    }
+    finally {
+        await browser.close();
+        rmSync(videoTmp, { recursive: true, force: true });
+    }
+    console.log(`Flow-smoke: ${green}/${smoke.flows.length} flows green — proof: ${proofRel}`);
+    return green === smoke.flows.length ? 0 : 1;
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@hecer/yoke",
+  "version": "0.2.0",
+  "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"
+  },
+  "files": [
+    "dist",
+    "canon",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HECer/yoke.git"
+  },
+  "homepage": "https://github.com/HECer/yoke#readme",
+  "bugs": {
+    "url": "https://github.com/HECer/yoke/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "codex",
+    "gemini-cli",
+    "agents",
+    "agentic-coding",
+    "harness",
+    "autonomous",
+    "ralph-loop",
+    "code-review",
+    "skills",
+    "agents-md",
+    "tdd"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "yoke": "tsx src/cli.ts",
+    "prepublishOnly": "npm run build && vitest run"
+  },
+  "dependencies": {
+    "yaml": "^2.5.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.0",
+    "smol-toml": "^1.7.0",
+    "tsx": "^4.19.1",
+    "typescript": "^5.6.2",
+    "vitest": "^2.1.1"
+  }
+}