@hecer/yoke 1.14.0 → 1.15.0

package/dist/code-intelligence/mcp-server.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { CodeIntelligenceCoordinator } from './coordinator.js';
+import { TOOL_DEFINITIONS } from './contracts.js';
+import { loadConfig } from '../retrofit/config.js';
+const INPUT_SCHEMAS = {
+    code_context: { type: 'object', required: ['workspace_id', 'query'], properties: { workspace_id: { type: 'string' }, query: { type: 'string' }, snapshot_id: { type: 'string' }, mode: { type: 'string', enum: ['orient', 'locate', 'explain'] }, paths: { type: 'array', items: { type: 'string' } }, include_docs: { type: 'boolean' }, token_budget: { type: 'integer' }, timeout_ms: { type: 'integer' } } },
+    code_symbol: { type: 'object', required: ['workspace_id', 'snapshot_id'], properties: { workspace_id: { type: 'string' }, snapshot_id: { type: 'string' }, symbol_id: { type: 'string' }, query: { type: 'string' }, path: { type: 'string' }, include: { type: 'array' } } },
+    code_trace: { type: 'object', required: ['workspace_id', 'snapshot_id', 'symbol_id', 'direction', 'relations'], properties: { workspace_id: { type: 'string' }, snapshot_id: { type: 'string' }, symbol_id: { type: 'string' }, direction: { type: 'string', enum: ['in', 'out'] }, relations: { type: 'array' }, max_depth: { type: 'integer' }, max_nodes: { type: 'integer' } } },
+    code_impact: { type: 'object', required: ['workspace_id', 'snapshot_id'], properties: { workspace_id: { type: 'string' }, snapshot_id: { type: 'string' }, targets: { type: 'array' }, plan_id: { type: 'string' }, include_docs: { type: 'boolean' }, require_semantic: { type: 'boolean' } } },
+    code_edit_preview: { type: 'object', required: ['workspace_id', 'snapshot_id', 'operations', 'validation_profile'], properties: { workspace_id: { type: 'string' }, snapshot_id: { type: 'string' }, operations: { type: 'array' }, validation_profile: { type: 'string', enum: ['default', 'extended'] } } },
+    code_edit_apply: { type: 'object', required: ['workspace_id', 'plan_id', 'expected_snapshot_id', 'idempotency_key'], properties: { workspace_id: { type: 'string' }, plan_id: { type: 'string' }, expected_snapshot_id: { type: 'string' }, idempotency_key: { type: 'string' } } },
+};
+function arg(name, args) { return args.find(value => value.startsWith(`--${name}=`))?.slice(name.length + 3); }
+function summary(response) { return `status=${response.status} snapshot=${response.snapshot_id} warnings=${response.warnings.length} (full result in structuredContent)`; }
+export async function runCodeIntelligenceServer(argv = process.argv.slice(2)) {
+    const workspace = arg('workspace', argv) ?? process.cwd();
+    const configured = loadConfig(workspace)?.codeIntelligence;
+    const mode = arg('mode', argv) ?? configured?.mode ?? 'active';
+    const coordinator = new CodeIntelligenceCoordinator(workspace, {
+        mode,
+        policy: { excludePatterns: configured?.policy?.excludePatterns, maxFileBytes: configured?.policy?.maxFileBytes },
+        limits: { maxBytes: configured?.limits?.maxBytes, maxBackends: configured?.limits?.maxBackends },
+        graft: configured?.graft, graphify: configured?.graphify, serena: configured?.serena,
+    });
+    let framing = 'line';
+    let buffer = Buffer.alloc(0);
+    const send = (message) => {
+        const payload = JSON.stringify(message);
+        if (framing === 'line')
+            process.stdout.write(`${payload}\n`);
+        else
+            process.stdout.write(`Content-Length: ${Buffer.byteLength(payload, 'utf8')}\r\n\r\n${payload}`);
+    };
+    const handle = async (message) => {
+        if (message.method === 'notifications/initialized' || message.method?.startsWith('notifications/'))
+            return;
+        if (message.method === 'initialize') {
+            send({ jsonrpc: '2.0', id: message.id, result: { protocolVersion: '2025-11-25', capabilities: { tools: {} }, serverInfo: { name: 'yoke-code-intelligence', version: '0.1.0' } } });
+            return;
+        }
+        if (message.method === 'tools/list') {
+            send({ jsonrpc: '2.0', id: message.id, result: { tools: TOOL_DEFINITIONS.map(tool => ({ ...tool, inputSchema: INPUT_SCHEMAS[tool.name] })) } });
+            return;
+        }
+        if (message.method === 'tools/call') {
+            const name = message.params?.name;
+            const response = await coordinator.dispatch(name, message.params?.arguments ?? {});
+            send({ jsonrpc: '2.0', id: message.id, result: { content: [{ type: 'text', text: summary(response) }], structuredContent: response, isError: response.status === 'error' || response.status === 'blocked' } });
+            return;
+        }
+        if (message.id !== undefined)
+            send({ jsonrpc: '2.0', id: message.id, error: { code: -32601, message: `method not found: ${message.method}` } });
+    };
+    process.stdin.on('data', chunk => {
+        buffer = Buffer.concat([buffer, Buffer.from(chunk)]);
+        while (buffer.length) {
+            let raw;
+            if (/^Content-Length:/i.test(buffer.toString('ascii', 0, Math.min(buffer.length, 32)))) {
+                framing = 'content-length';
+                const end = buffer.indexOf('\r\n\r\n');
+                if (end < 0)
+                    return;
+                const header = buffer.subarray(0, end).toString('ascii');
+                const match = /Content-Length:\s*(\d+)/i.exec(header);
+                if (!match) {
+                    buffer = buffer.subarray(end + 4);
+                    continue;
+                }
+                const length = Number(match[1]);
+                if (buffer.length < end + 4 + length)
+                    return;
+                raw = buffer.subarray(end + 4, end + 4 + length).toString('utf8');
+                buffer = buffer.subarray(end + 4 + length);
+            }
+            else {
+                const end = buffer.indexOf(10);
+                if (end < 0)
+                    return;
+                raw = buffer.subarray(0, end).toString('utf8').trim();
+                buffer = buffer.subarray(end + 1);
+            }
+            if (!raw)
+                continue;
+            try {
+                void handle(JSON.parse(raw));
+            }
+            catch { /* malformed protocol input is ignored */ }
+        }
+    });
+    await new Promise(resolve => { const stop = () => { process.off('SIGTERM', stop); process.off('SIGINT', stop); void coordinator.close().finally(resolve); }; process.once('SIGTERM', stop); process.once('SIGINT', stop); process.stdin.once('end', stop); });
+}
+if (process.argv[1]?.endsWith('code-intelligence-server.js'))
+    void runCodeIntelligenceServer();

package/dist/code-intelligence/snapshots.js

@@ -0,0 +1,117 @@
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync, readdirSync, writeFileSync } from 'node:fs';
+import { join, relative, resolve, sep } from 'node:path';
+import { z } from 'zod';
+export const SnapshotFileSchema = z.object({ path: z.string().min(1), hash: z.string().length(64), size: z.number().int().nonnegative() });
+export const SnapshotSchema = z.object({
+    snapshot_id: z.string().length(64), workspace_id: z.string().min(1), root: z.string().min(1), head: z.string().nullable(),
+    files: z.array(SnapshotFileSchema), policy_hash: z.string().length(64), created_at: z.string(),
+});
+function sha256(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function inside(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !rel.startsWith(sep));
+}
+function globToRegExp(pattern) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*\*/g, '.*').replace(/\*/g, '[^/]*').replace(/\?/g, '.');
+    return new RegExp(`^${escaped}$`);
+}
+function excluded(path, policy) {
+    const standard = [/^\.git(?:\/|$)/, /^\.yoke\/code-intelligence(?:\/|$)/, /(^|\/)\.env(?:\.|$)/, /\.(?:pem|key|p12|pfx)$/i];
+    if (standard.some(re => re.test(path)))
+        return true;
+    return (policy.excludePatterns ?? []).some(pattern => globToRegExp(pattern).test(path));
+}
+function safeFile(root, rel, policy) {
+    const normalized = rel.replaceAll('\\', '/');
+    if (!normalized || normalized.startsWith('/') || normalized.split('/').some(part => part === '..') || excluded(normalized, policy))
+        return null;
+    const absolute = resolve(root, normalized);
+    if (!inside(root, absolute) || !existsSync(absolute))
+        return null;
+    const stat = lstatSync(absolute);
+    if (!stat.isFile() || stat.isSymbolicLink() || (policy.maxFileBytes && stat.size > policy.maxFileBytes))
+        return null;
+    return { path: normalized, bytes: readFileSync(absolute) };
+}
+function fallbackFiles(root, dir = root, output = []) {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (entry.name === '.git' || entry.name === '.yoke' || entry.name === 'node_modules')
+            continue;
+        const absolute = join(dir, entry.name);
+        if (entry.isDirectory() && !entry.isSymbolicLink())
+            fallbackFiles(root, absolute, output);
+        else if (entry.isFile())
+            output.push(relative(root, absolute).replaceAll('\\', '/'));
+    }
+    return output;
+}
+function trackedAndUntracked(root) {
+    try {
+        const result = execFileSync('git', ['-C', root, 'ls-files', '-co', '--exclude-standard', '-z'], { encoding: 'buffer', stdio: ['ignore', 'pipe', 'ignore'] });
+        return result.toString('utf8').split('\0').filter(Boolean);
+    }
+    catch {
+        return fallbackFiles(root);
+    }
+}
+function head(root) {
+    try {
+        return execFileSync('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+export function workspaceId(workspaceRoot) {
+    return `workspace-${sha256(realpathSync(resolve(workspaceRoot))).slice(0, 24)}`;
+}
+export function assertSafePath(workspaceRoot, candidate, policy = {}) {
+    const root = realpathSync(resolve(workspaceRoot));
+    const absolute = resolve(root, candidate);
+    const rel = relative(root, absolute).replaceAll('\\', '/');
+    if (!inside(root, absolute) || rel === '' || excluded(rel, policy))
+        throw new Error(`path is outside the permitted workspace: ${candidate}`);
+    try {
+        if (lstatSync(absolute).isSymbolicLink())
+            throw new Error(`symbolic links are not allowed: ${candidate}`);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    return rel;
+}
+export function createSnapshot(workspaceRoot, policy = {}, workspace = workspaceId(workspaceRoot)) {
+    const root = realpathSync(resolve(workspaceRoot));
+    const files = trackedAndUntracked(root).map(path => safeFile(root, path, policy)).filter((value) => value !== null)
+        .sort((a, b) => a.path.localeCompare(b.path)).map(file => ({ path: file.path, hash: sha256(file.bytes), size: file.bytes.byteLength }));
+    const policyHash = sha256(JSON.stringify({ excludePatterns: policy.excludePatterns ?? [], maxFileBytes: policy.maxFileBytes ?? null }));
+    const identity = JSON.stringify({ workspace, root, head: head(root), files, policyHash });
+    const snapshot = SnapshotSchema.parse({ snapshot_id: sha256(identity), workspace_id: workspace, root, head: head(root), files, policy_hash: policyHash, created_at: new Date().toISOString() });
+    const dir = join(root, '.yoke', 'code-intelligence', 'snapshots');
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, `${snapshot.snapshot_id}.json`), JSON.stringify(snapshot, null, 2) + '\n', { mode: 0o600 });
+    return snapshot;
+}
+export function loadSnapshot(workspaceRoot, snapshotId) {
+    const root = realpathSync(resolve(workspaceRoot));
+    const file = join(root, '.yoke', 'code-intelligence', 'snapshots', `${snapshotId}.json`);
+    if (!existsSync(file))
+        throw new Error(`unknown snapshot: ${snapshotId}`);
+    const snapshot = SnapshotSchema.parse(JSON.parse(readFileSync(file, 'utf8')));
+    if (snapshot.root !== root)
+        throw new Error('snapshot belongs to another workspace');
+    return snapshot;
+}
+export function currentSnapshotMatches(workspaceRoot, snapshot, policy = {}) {
+    const current = createSnapshot(workspaceRoot, policy, snapshot.workspace_id);
+    return current.snapshot_id === snapshot.snapshot_id;
+}
+export function assertSnapshotCurrent(workspaceRoot, snapshot, policy = {}) {
+    if (!currentSnapshotMatches(workspaceRoot, snapshot, policy))
+        throw new Error('snapshot is stale; create a new snapshot before continuing');
+}

package/dist/code-intelligence/transactions.js

@@ -0,0 +1,60 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { copyFileSync, existsSync, mkdirSync, openSync, closeSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { assertSnapshotCurrent } from './snapshots.js';
+import { readPlanApproval } from './edit-plans.js';
+function transactionDir(root) { return join(root, '.yoke', 'code-intelligence', 'transactions'); }
+function hash(value) { return createHash('sha256').update(JSON.stringify(value)).digest('hex'); }
+export function applyEditPlan(root, plan, snapshot, idempotencyKey) {
+    if (plan.expires_at <= new Date().toISOString())
+        throw new Error('edit plan has expired');
+    if (!readPlanApproval(root, plan))
+        throw new Error('edit plan requires Yoke control approval');
+    assertSnapshotCurrent(root, snapshot);
+    if (!existsSync(plan.diff_uri) || hash(readFileSync(plan.diff_uri, 'utf8')) !== plan.diff_hash)
+        throw new Error('edit plan diff has changed');
+    const sandboxHash = hash(plan.changed_paths.map(path => [path, existsSync(join(plan.sandbox_root, path)) ? readFileSync(join(plan.sandbox_root, path)).toString('base64') : null]));
+    if (sandboxHash !== plan.sandbox_hash)
+        throw new Error('edit plan sandbox has changed');
+    const dir = transactionDir(root);
+    mkdirSync(dir, { recursive: true });
+    const idem = join(dir, `${idempotencyKey}.json`);
+    if (existsSync(idem)) {
+        const prior = JSON.parse(readFileSync(idem, 'utf8'));
+        if (prior.plan_id !== plan.plan_id)
+            throw new Error('idempotency key is bound to another plan');
+        return prior;
+    }
+    const lock = join(dir, '.write.lock');
+    let handle;
+    try {
+        handle = openSync(lock, 'wx');
+    }
+    catch {
+        throw new Error('another code-intelligence transaction is active');
+    }
+    try {
+        const transactionId = `tx-${randomUUID()}`;
+        const worktree = join(root, '.yoke', 'code-intelligence', 'worktrees', transactionId);
+        mkdirSync(worktree, { recursive: true });
+        for (const path of plan.changed_paths) {
+            const source = join(plan.sandbox_root, path);
+            const target = join(worktree, path);
+            if (!existsSync(source))
+                continue;
+            mkdirSync(dirname(target), { recursive: true });
+            copyFileSync(source, target);
+        }
+        const result = { transaction_id: transactionId, plan_id: plan.plan_id, changed_paths: plan.changed_paths, worktree, new_snapshot_id: snapshot.snapshot_id, validation: plan.validation, committed: false, merged: false };
+        writeFileSync(idem, JSON.stringify(result, null, 2) + '\n', { mode: 0o600 });
+        return result;
+    }
+    finally {
+        if (handle !== undefined)
+            closeSync(handle);
+        try {
+            unlinkSync(lock);
+        }
+        catch { /* best effort */ }
+    }
+}

package/dist/retrofit/command.js

@@ -17,7 +17,8 @@ export function runRetrofit(targetDir, opts) {
         : (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);
+    const codeIntelligence = opts.codeIntelligence ?? existing?.codeIntelligence?.mode ?? 'off';
+    const actions = planRetrofit(canonDir, targetDir, agents, codeGraph, codeIntelligence);
     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
@@ -31,6 +32,7 @@ export function runRetrofit(targetDir, opts) {
         agents: mergedAgents,
         loop: { ...existing?.loop, enabled: opts.loop },
         codeGraph,
+        codeIntelligence: { ...(existing?.codeIntelligence ?? {}), mode: codeIntelligence },
         ...(existing?.design
             ? { design: existing.design }
             : detection.ui.detected ? { design: { mode: 'auto', max: 4 } } : {}),

package/dist/retrofit/config.js

@@ -6,7 +6,16 @@ import { AgentSchema, PermissionProfileSchema } from '../agents/contracts.js';
 import { ProjectQualityDefaultsSchema } from '../quality/types.js';
 import { DEFAULT_OUTPUT_POLICY } from '../output/types.js';
 import { ToolActionSchema } from '../execution/actions.js';
+import { CodeIntelligenceModeSchema } from '../code-intelligence/contracts.js';
+export { CodeIntelligenceModeSchema };
 const CodeGraphSchema = z.enum(['graphify', 'serena']);
+const CodeIntelligenceProcessSchema = z.object({ command: z.string().min(1), args: z.array(z.string()).max(32).optional() });
+const CodeIntelligenceSchema = z.object({
+    mode: CodeIntelligenceModeSchema.default('off'), workspaceId: z.string().min(1).optional(),
+    graft: CodeIntelligenceProcessSchema.optional(), graphify: CodeIntelligenceProcessSchema.optional(), serena: CodeIntelligenceProcessSchema.optional(),
+    policy: z.object({ allowNetwork: z.boolean().default(false), excludePatterns: z.array(z.string().min(1)).max(100).default([]), maxFileBytes: z.number().int().positive().max(20_000_000).optional() }).optional(),
+    limits: z.object({ tokenBudget: z.number().int().min(128).max(16000).default(2400), timeoutMs: z.number().int().min(100).max(600000).default(10000), maxBytes: z.number().int().positive().max(10_000_000).default(2_000_000), maxBackends: z.number().int().min(1).max(3).default(3) }).optional(),
+});
 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) });
 const OutputPolicySchema = z.object({
@@ -118,6 +127,7 @@ export const YokeConfigSchema = z.object({
         max: z.number().int().positive().default(4),
     }).optional(),
     codeGraph: CodeGraphSchema.optional(),
+    codeIntelligence: CodeIntelligenceSchema.optional(),
     smoke: SmokeSchema.optional(),
     quality: ProjectQualityDefaultsSchema.optional(),
     output: OutputPolicySchema.optional(),

package/dist/retrofit/gitignore.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 export const YOKE_IGNORE_LINES = [
     '.yoke/worktrees/',
     '.yoke/backup/',
+    '.yoke/code-intelligence/',
     '.yoke/loop-status.json',
     '.yoke/loop.log',
     '.yoke/loop.lock',

package/dist/retrofit/plan.js

@@ -10,7 +10,7 @@ export function planClaudeRetrofit(canonDir, targetDir) {
     return planClaude(canonDir, targetDir);
 }
 export const PLANNERS = {
-    claude: (c, t, cg) => planClaude(c, t, undefined, cg),
+    claude: (c, t, cg, ci) => planClaude(c, t, undefined, cg, undefined, ci),
     codex: planCodex,
     gemini: planGemini,
     qwen: planQwen,
@@ -18,7 +18,7 @@ export const PLANNERS = {
     kilo: planKilo,
     pi: planPi,
 };
-export function planRetrofit(canonDir, targetDir, agents, codeGraph = 'graphify') {
+export function planRetrofit(canonDir, targetDir, agents, codeGraph = 'graphify', codeIntelligence = 'off') {
     const seen = new Set();
     const merged = [];
     for (const action of baseContextActions(canonDir)) {
@@ -26,7 +26,7 @@ export function planRetrofit(canonDir, targetDir, agents, codeGraph = 'graphify'
         merged.push(action);
     }
     for (const agent of agents) {
-        for (const action of PLANNERS[agent](canonDir, targetDir, codeGraph)) {
+        for (const action of PLANNERS[agent](canonDir, targetDir, codeGraph, codeIntelligence)) {
             if (seen.has(action.target))
                 continue;
             seen.add(action.target);

package/dist/retrofit/planners/claude.js

@@ -22,7 +22,7 @@ This project uses the Yoke harness. Baseline instructions:
 ${rtkNote ? `\n${rtkNote}\n` : ''}${composeNote ? `\n${composeNote}\n` : ''}
 ${PRESERVE_SCAFFOLD}
 `;
-export function planClaude(canonDir, targetDir, wslAvailable = hasWsl(), codeGraph = 'graphify', gstackDetected = detectGstack(targetDir)) {
+export function planClaude(canonDir, targetDir, wslAvailable = hasWsl(), codeGraph = 'graphify', gstackDetected = detectGstack(targetDir), codeIntelligence = 'off') {
     const manifest = loadManifest(join(canonDir, 'manifest.yaml'));
     const actions = [];
     for (const skill of manifest.skills) {
@@ -45,8 +45,8 @@ export function planClaude(canonDir, targetDir, wslAvailable = hasWsl(), codeGra
     actions.push({
         kind: 'write',
         target: '.mcp.json',
-        content: JSON.stringify({ mcpServers: mcpServers(codeGraph) }, null, 2) + '\n',
-        reason: 'MCP servers (code-graph + playwright)',
+        content: JSON.stringify({ mcpServers: mcpServers(codeGraph, codeIntelligence, targetDir) }, null, 2) + '\n',
+        reason: codeIntelligence === 'off' ? 'MCP servers (code-graph + playwright)' : 'Yoke code-intelligence facade + playwright',
     });
     if (rtkHookable) {
         actions.push({

package/dist/retrofit/planners/codex.js

@@ -3,8 +3,8 @@ import { join } from 'node:path';
 import { loadManifest } from '../../canon/manifest.js';
 import { mcpServers, rtkInstruction } from '../tools.js';
 import { skillPackageActions } from '../skill-actions.js';
-function tomlMcp(codeGraph) {
-    const servers = mcpServers(codeGraph);
+function tomlMcp(codeGraph, codeIntelligence, targetDir) {
+    const servers = mcpServers(codeGraph, codeIntelligence, targetDir);
     // 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)
@@ -14,7 +14,7 @@ function tomlMcp(codeGraph) {
     })
         .join('\n');
 }
-export function planCodex(canonDir, _targetDir, codeGraph = 'graphify') {
+export function planCodex(canonDir, targetDir, codeGraph = 'graphify', codeIntelligence = 'off') {
     const manifest = loadManifest(join(canonDir, 'manifest.yaml'));
     const baseline = readFileSync(join(canonDir, 'AGENTS.md'), 'utf8');
     const actions = manifest.skills.flatMap(skill => skillPackageActions(canonDir, skill, 'codex'));
@@ -32,8 +32,8 @@ export function planCodex(canonDir, _targetDir, codeGraph = 'graphify') {
     }, {
         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)',
+        content: `# Yoke project configuration. Codex loads this in trusted repositories.\n\n[features]\nhooks = true\n\n${tomlMcp(codeGraph, codeIntelligence, targetDir)}`,
+        reason: codeIntelligence === 'off' ? 'MCP servers (code-graph + playwright)' : 'Yoke code-intelligence facade + playwright',
     }, {
         kind: 'write',
         target: '.codex/hooks.json',

package/dist/retrofit/planners/gemini.js

@@ -8,7 +8,7 @@ import { skillPackageActions } from '../skill-actions.js';
 function tomlString(s) {
     return '"""\n' + s.replace(/\\/g, '\\\\').replace(/"""/g, '\\"\\"\\"') + '\n"""';
 }
-export function planGemini(canonDir, _targetDir, codeGraph = 'graphify') {
+export function planGemini(canonDir, targetDir, codeGraph = 'graphify', codeIntelligence = 'off') {
     const manifest = loadManifest(join(canonDir, 'manifest.yaml'));
     const actions = [];
     // GEMINI.md: baseline + instruction for commands outside the rewrite hook.
@@ -56,7 +56,7 @@ export function planGemini(canonDir, _targetDir, codeGraph = 'graphify') {
         target: '.gemini/settings.json',
         merge: true,
         content: JSON.stringify({
-            mcpServers: mcpServers(codeGraph),
+            mcpServers: mcpServers(codeGraph, codeIntelligence, targetDir),
             context: { fileName: ['AGENTS.md', 'GEMINI.md'] },
             hooks: { BeforeTool: [{ matcher: '^run_shell_command$', hooks: [{ name: 'yoke-rtk', type: 'command', command: 'node .gemini/hooks/gemini-rtk-hook.mjs' }] }] },
         }, null, 2) + '\n',

package/dist/retrofit/planners/kilo.js

@@ -15,7 +15,7 @@ permission:
 
 Review the observed diff and test evidence. Do not modify files. Return only actionable findings grounded in evidence.
 `;
-export function planKilo(canonDir, _targetDir, codeGraph = 'graphify') {
+export function planKilo(canonDir, targetDir, codeGraph = 'graphify', codeIntelligence = 'off') {
     const manifest = loadManifest(join(canonDir, 'manifest.yaml'));
     const baseline = readFileSync(join(canonDir, 'AGENTS.md'), 'utf8');
     const actions = manifest.skills.flatMap(skill => skillPackageActions(canonDir, skill, 'kilo'));
@@ -31,7 +31,7 @@ export function planKilo(canonDir, _targetDir, codeGraph = 'graphify') {
         content: JSON.stringify({
             $schema: 'https://app.kilo.ai/config.json',
             instructions: ['AGENTS.md', '.yoke/context/*.md'],
-            mcp: openCodeMcpServers(codeGraph),
+            mcp: openCodeMcpServers(codeGraph, codeIntelligence, targetDir),
         }, null, 2) + '\n',
         reason: 'Kilo instructions + MCP servers',
     }, {

package/dist/retrofit/planners/opencode.js

@@ -15,7 +15,7 @@ tools:
 
 Review the observed diff and test evidence. Do not modify files. Return only actionable findings grounded in evidence.
 `;
-export function planOpenCode(canonDir, _targetDir, codeGraph = 'graphify') {
+export function planOpenCode(canonDir, targetDir, codeGraph = 'graphify', codeIntelligence = 'off') {
     const manifest = loadManifest(join(canonDir, 'manifest.yaml'));
     const baseline = readFileSync(join(canonDir, 'AGENTS.md'), 'utf8');
     const actions = manifest.skills.flatMap(skill => skillPackageActions(canonDir, skill, 'opencode'));
@@ -31,7 +31,7 @@ export function planOpenCode(canonDir, _targetDir, codeGraph = 'graphify') {
         content: JSON.stringify({
             $schema: 'https://opencode.ai/config.json',
             instructions: ['AGENTS.md', '.yoke/context/*.md'],
-            mcp: openCodeMcpServers(codeGraph),
+            mcp: openCodeMcpServers(codeGraph, codeIntelligence, targetDir),
         }, null, 2) + '\n',
         reason: 'OpenCode instructions + MCP servers',
     }, {

package/dist/retrofit/planners/pi.js

@@ -4,7 +4,7 @@ import { loadManifest } from '../../canon/manifest.js';
 import { rtkInstruction } from '../tools.js';
 import { PRESERVE_SCAFFOLD } from '../preserve.js';
 import { skillPackageActions } from '../skill-actions.js';
-export function planPi(canonDir, _targetDir, _codeGraph = 'graphify') {
+export function planPi(canonDir, _targetDir, _codeGraph = 'graphify', _codeIntelligence = 'off') {
     const manifest = loadManifest(join(canonDir, 'manifest.yaml'));
     const baseline = readFileSync(join(canonDir, 'AGENTS.md'), 'utf8');
     const actions = manifest.skills.flatMap(skill => skillPackageActions(canonDir, skill, 'pi'));

package/dist/retrofit/planners/qwen.js

@@ -8,7 +8,7 @@ import { skillPackageActions } from '../skill-actions.js';
 function tomlString(s) {
     return '"""\n' + s.replace(/\\/g, '\\\\').replace(/"""/g, '\\"\\"\\"') + '\n"""';
 }
-export function planQwen(canonDir, _targetDir, codeGraph = 'graphify') {
+export function planQwen(canonDir, targetDir, codeGraph = 'graphify', codeIntelligence = 'off') {
     const manifest = loadManifest(join(canonDir, 'manifest.yaml'));
     const actions = [];
     // QWEN.md: baseline + instruction for commands outside the rewrite hook.
@@ -56,7 +56,7 @@ export function planQwen(canonDir, _targetDir, codeGraph = 'graphify') {
         target: '.qwen/settings.json',
         merge: true,
         content: JSON.stringify({
-            mcpServers: mcpServers(codeGraph),
+            mcpServers: mcpServers(codeGraph, codeIntelligence, targetDir),
             context: { fileName: ['AGENTS.md', 'QWEN.md'] },
             hooks: { PreToolUse: [{ matcher: '^run_shell_command$', hooks: [{ name: 'yoke-rtk', type: 'command', command: 'node .qwen/hooks/qwen-rtk-hook.mjs' }] }] },
         }, null, 2) + '\n',

package/dist/retrofit/tools.js

@@ -8,15 +8,17 @@ const CODE_GRAPH_SERVERS = {
         args: ['start-mcp-server', '--open-web-dashboard', 'false'],
     },
 };
-export function mcpServers(codeGraph = 'graphify') {
-    return {
-        [codeGraph]: CODE_GRAPH_SERVERS[codeGraph],
-        playwright: { command: 'npx', args: ['@playwright/mcp@latest'] },
-    };
+export function mcpServers(codeGraph = 'graphify', codeIntelligence = 'off', targetDir = '.') {
+    if (codeIntelligence !== 'off')
+        return {
+            'code-intelligence': { command: 'yoke', args: ['code-intelligence-server', `--workspace=${targetDir}`, `--mode=${codeIntelligence}`] },
+            playwright: { command: 'npx', args: ['@playwright/mcp@latest'] },
+        };
+    return { [codeGraph]: CODE_GRAPH_SERVERS[codeGraph], playwright: { command: 'npx', args: ['@playwright/mcp@latest'] } };
 }
 /** OpenCode-family CLIs use an object with a local command array, not Claude's mcpServers shape. */
-export function openCodeMcpServers(codeGraph = 'graphify') {
-    return Object.fromEntries(Object.entries(mcpServers(codeGraph)).map(([name, server]) => [name, {
+export function openCodeMcpServers(codeGraph = 'graphify', codeIntelligence = 'off', targetDir = '.') {
+    return Object.fromEntries(Object.entries(mcpServers(codeGraph, codeIntelligence, targetDir)).map(([name, server]) => [name, {
             type: 'local',
             command: [server.command, ...server.args],
             enabled: true,

package/dist/setup/command.js

@@ -75,6 +75,7 @@ export async function runSetup(targetDir, opts = {}) {
                 ? detected.agents
                 : modelProviders.length ? ['qwen'] : [host ?? 'claude'];
     const defaultGraph = opts.codeGraph ?? existing?.codeGraph ?? 'graphify';
+    const defaultCodeIntelligence = opts.codeIntelligence ?? existing?.codeIntelligence?.mode ?? 'off';
     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');
@@ -90,6 +91,7 @@ export async function runSetup(targetDir, opts = {}) {
     try {
         let agents = defaultAgents;
         let codeGraph = defaultGraph;
+        let codeIntelligence = defaultCodeIntelligence;
         let loop = defaultLoop;
         let runner = defaultRunner;
         let decisionPolicy = defaultPolicy;
@@ -112,7 +114,7 @@ export async function runSetup(targetDir, opts = {}) {
             agents = [...agents, 'qwen'];
         if (!agents.includes(runner))
             agents = [...agents, runner];
-        const code = runRetrofit(targetDir, { loop, agents, codeGraph, host });
+        const code = runRetrofit(targetDir, { loop, agents, codeGraph, codeIntelligence, host });
         if (code !== 0)
             return code;
         applyActions(presetActions, targetDir, { backupDir: join(targetDir, '.yoke', 'backups', `model-presets-${Date.now()}`) });

package/docs/CODE-INTELLIGENCE.md

@@ -0,0 +1,36 @@
+# Yoke Code Intelligence
+
+Yoke integrates Graphify, Graft and Serena as a federation. Their repositories are not merged into Yoke and their individual MCP tools are not published to agents. Yoke publishes one snapshot-bound facade with six tools:
+
+`code_context`, `code_symbol`, `code_trace`, `code_impact`, `code_edit_preview`, and `code_edit_apply`.
+
+## Enable it
+
+```sh
+yoke setup . --yes --code-intelligence=active
+# or, for an existing project:
+yoke retrofit . --code-intelligence=active
+```
+
+The default is `off`, which preserves the previous `codeGraph` behavior. `shadow` enables a read-only canary and keeps all edits blocked. `active` enables read operations and snapshot-bound edit previews. The generated host configuration exposes only Yoke's facade, so an agent cannot accidentally combine duplicate backend tools.
+
+## Backend roles and tested pins
+
+| Backend | Role | Launch command | Pin checked during integration |
+|---|---|---|---|
+| [Graft](https://github.com/trailhq/Graft) | structural code search, repo map, call graph | `graft mcp` | `05760b07abc0e427f5af8ad378889ee402c5afc6` / 0.17.0 |
+| [Graphify](https://github.com/Graphify-Labs/graphify) | architecture/document knowledge graph | `python -m graphify.serve` | `67f99bd0059dd1bac9e44382907ef9f10098b39f` / 0.9.56 |
+| [Serena](https://github.com/oraios/serena) | LSP symbols, references, implementations and semantic edits | `serena start-mcp-server --project-from-cwd --context codex` | `701e7c843f46c6a649203a488cece1bf19f1df90` / 1.7.1-dev |
+
+Install and pin these tools in the project or developer environment before enabling the facade. Yoke never installs `latest` during a task. Missing tools produce an explicit `partial` response with backend warnings and provenance; they are never interpreted as “no references”.
+
+## Safety contract
+
+- Every request is tied to a workspace and a content-addressed snapshot of committed and uncommitted, non-sensitive files.
+- Paths are workspace-relative; traversal, symlinks, `.env`/key material and policy-excluded paths are rejected.
+- Read calls are bounded by timeout and output budgets. Results carry backend, version, source path, content hash, resolution and freshness.
+- Edits run in a disposable Yoke sandbox. Preview writes a durable plan and diff but requires an approval record created by the Yoke control layer.
+- Apply rechecks the snapshot, plan expiry, plan hash, an exclusive transaction lock and idempotency. It produces a managed worktree and does not commit or merge; the existing Yoke loop and gates remain authoritative for integration.
+- Network access is not needed by the facade. Backend installation and any backend-specific network behavior remain an explicit environment concern.
+
+For a host that has no native MCP support (currently Pi), use the normal Yoke loop and bounded CLI/skill adapter. Yoke does not invent a second MCP transport for that host.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hecer/yoke",
-  "version": "1.14.0",
+  "version": "1.15.0",
   "description": "One harness, seven agents, zero trust in \"done\" — cross-agent coding harness for Claude Code, Codex CLI, Gemini CLI, Qwen Code, OpenCode, Kilo and Pi: one skill canon, mechanical safety gates, an autonomous loop with screenshot/video proofs.",
   "type": "module",
   "bin": {