@hecer/yoke 1.13.0 → 1.15.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 1.15.0 — 2026-09-09
+
+### Added
+- Add opt-in federated Code Intelligence that composes Graft, Graphify and Serena behind one Yoke-controlled MCP facade with six stable tools for context, symbols, traces, impact and edit workflows.
+- Add pinned backend adapters, explicit coverage/provenance/freshness evidence, content-addressed workspace snapshots and bounded local policy checks.
+- Add isolated edit previews and guarded apply transactions with approval, snapshot freshness, exclusive locking and idempotency checks; Yoke's existing review, verify and commit gates remain authoritative.
+
+### Changed
+- Add `off`, `shadow` and `active` Code Intelligence modes to setup and retrofit. `off` preserves the legacy `codeGraph` path unchanged; `shadow` is read-only; `active` enables preview and approved edits.
+- Keep backend runtimes external and configurable instead of vendoring or silently installing them. Pin the validated integration targets to Graft `0.17.0`, Graphify `0.9.56` and Serena `1.7.1-dev`.
+- Add the [Code Intelligence guide](docs/CODE-INTELLIGENCE.md), including setup, backend requirements, safety boundaries, limitations and the Pi integration note.
+
+### Migration and validation limits
+- No migration is required. Existing projects remain on the legacy path until `yoke setup` or `yoke retrofit` is run with `--code-intelligence=shadow` or `--code-intelligence=active`.
+- Validated with the Code Intelligence contract/coordinator/snapshot/MCP tests, TypeScript lint/build, documentation metadata, package dry run and the facade MCP handshake. The full suite retains one pre-existing provider-process timing failure; it is reproduced independently and is not caused by this release.
+- This release does not claim that every language or backend is available in every environment. Backend failures are surfaced as partial coverage or an explicit unavailable capability, never silently treated as complete evidence.
+
+## 1.14.0 — 2026-09-09
+
+### Added
+- Add a local-first workspace control room that ranks registered projects by attention, activity, recorded tokens, reported cost, acceptance, or name, with composable search, status filters, UTC scopes, and restorable view links.
+- Add workspace and project analytics with time buckets, token/call/duration/outcome summaries, provider/model/agent/role/phase/run rankings, usage comparisons, and visible measurement coverage.
+- Add project live operations for task and phase state, worker metadata, bounded event timelines, safe-boundary pause/resume, append-only operator notes, and queued change requests.
+- Add a responsive dashboard shell with dark/light themes, keyboard and reduced-motion support, explicit loading/empty/error/stale states, and readable narrow-screen navigation.
+
+### Changed
+- Base dashboard views on durable local history and versioned events while keeping unknown, partial, corrupt, unavailable, and stale telemetry explicit instead of treating it as zero.
+- Keep dashboard controls on the existing loop/goal runner and lock boundaries; browser requests remain typed, same-origin, loopback-only, and unable to execute arbitrary shell commands.
+
+### Fixed
+- Scope dashboard loop verification to the intended local project and retain focused coverage for dashboard authorization, path safety, partial history, concurrency, navigation, and control behavior.
+- Improve light-theme contrast for the active navigation state and keep long project names inside desktop and mobile navigation areas.
+
+### Migration and validation limits
+- No migration is required. Start the local view with `yoke dashboard --no-register`, then register projects with `yoke projects add <path>` as needed. Existing dashboard settings remain local and authoritative.
+- Validated with the dashboard tests, TypeScript lint/build, canonical manifest validation, release metadata checks, package dry run, and real local browser screenshots at desktop and mobile sizes.
+- Dashboard data is limited to explicitly registered local projects and retained local telemetry. It does not provide remote multi-user access, reconstruct missing history, prove requested models were used, or execute arbitrary browser-supplied commands. Pause/resume operates only at existing safe loop/goal boundaries.
+- This release targets npm package 1.14.0; npm publication is triggered by the matching published GitHub release and verified separately.
+
 ## 1.13.0 — 2026-09-08
 
 ### Added

package/README.md

@@ -1,9 +1,9 @@
 <div align="center">
 
-<h1><img src="https://raw.githubusercontent.com/HECer/yoke/v1.13.0/docs/assets/yoke-logo.png" alt="Yoke" width="100" height="63"></h1>
+<h1><img src="https://raw.githubusercontent.com/HECer/yoke/v1.15.0/docs/assets/yoke-logo.png" alt="Yoke" width="100" height="63"></h1>
 
-<!-- yoke:version:start -->1.13.0<!-- yoke:version:end -->
-<!-- yoke:tests:start -->1231<!-- yoke:tests:end -->
+<!-- yoke:version:start -->1.15.0<!-- yoke:version:end -->
+<!-- yoke:tests:start -->1268<!-- yoke:tests:end -->
 <!-- yoke:skills:start -->34<!-- yoke:skills:end -->
 <!-- yoke:agents:start -->Claude | Codex | Gemini | Qwen | OpenCode | Kilo | Pi<!-- yoke:agents:end -->
 
@@ -17,7 +17,7 @@
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](#-license)
 ![Node](https://img.shields.io/badge/node-%E2%89%A520-339933?logo=node.js&logoColor=white)
 ![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)
-![Tests](https://img.shields.io/badge/tests-1231%20defined-blue.svg)
+![Tests](https://img.shields.io/badge/tests-1268%20defined-blue.svg)
 ![Agents](https://img.shields.io/badge/agents-Claude%20%7C%20Codex%20%7C%20Gemini%20%7C%20Qwen%20%7C%20OpenCode%20%7C%20Kilo%20%7C%20Pi-8A2BE2)
 ![Built with TDD](https://img.shields.io/badge/built%20with-TDD%20%2B%20review-ff69b4.svg)
 
@@ -27,7 +27,7 @@
 
 > **TL;DR** — `yoke setup .` asks six questions and installs the native harness for your agent. `yoke new my-app --idea="..."` bootstraps a project and drafts its story backlog. `yoke loop run my-app --isolate --review` then implements it behind hard gates: **clean tree → acceptance criteria → your real tests green → an independent model approves → commit**. Add `--parallel=N` for dependency-aware workers, or declare a reference and add `--quality` for a bounded critic/repair gauntlet. If any blocking gate is red, nothing is committed. Proof lives in `.yoke/proof/<story>/`.
 
-**New in 1.13.0:** first-class [OpenCode, Kilo and Pi integrations](docs/HARNESSES.md), including native headless invocation, provider/model/variant routing, retrofit artifacts, role configuration and provider telemetry. [Qwen Code hardening and explicit DeepSeek/Kimi API model profiles](docs/QWEN-MODEL-SUPPORT.md) remain available. Since 1.10.0, Yoke also includes [dashboard search, filters and period comparisons](docs/DASHBOARD-EVOLUTION.md), [batch task assessments with separate planning models](docs/CAPABILITY-ROUTING.md), and [Windows sandbox preflight and process supervision](docs/WINDOWS-RUNNER-VALIDATION.md). Existing routing settings remain authoritative. See the [changelog](CHANGELOG.md) and the [harness integration guide](docs/HARNESSES.md) for limitations and setup.
+**New in 1.15.0:** federated [Code Intelligence](docs/CODE-INTELLIGENCE.md) composes Graft, Graphify and Serena behind one Yoke-controlled MCP surface, with structural and semantic evidence, content-addressed snapshots, partial-coverage reporting and isolated edit previews. It is opt-in: use `off` for the unchanged legacy path, `shadow` for read-only canaries, or `active` for previews and approved edits. The [1.14.0 dashboard overhaul](docs/DASHBOARD-OVERHAUL.md) and first-class [OpenCode, Kilo and Pi integrations](docs/HARNESSES.md) remain available. See the [changelog](CHANGELOG.md) and [Code Intelligence guide](docs/CODE-INTELLIGENCE.md) for setup and limitations.
 
 OpenCode, Kilo and Pi are real CLI integrations, not bundled runtimes or credentials. OpenCode/Kilo use their JSON headless modes and local MCP configuration; Pi uses JSONL and explicit tool allowlists, but has no native MCP, sub-agent or plan layer. Read the [integration guide](docs/HARNESSES.md) before selecting a permission profile.
 
@@ -40,11 +40,11 @@ yoke projects add /path/to/backend
 yoke dashboard --no-register
 ```
 
-Open the printed `http://127.0.0.1:...` URL. Each registered project has its own goals, tasks and evidence. The dashboard shows available worker state, per-task duration estimates, planned start offsets, input/output tokens, costs and unknown measurements. You can request a goal pause at a safe boundary.
+Open the printed `http://127.0.0.1:...` URL. Each registered project has its own goals, tasks and evidence. The dashboard is a local control room with an overview/ranking screen, project live view, bounded **History explorer**, and Workspace analytics by UTC time bucket. It shows worker state, agent/provider/model/variant/role/phase metadata when recorded, per-task duration estimates, planned start offsets, input/output tokens, reported costs, outcomes, and explicit unknown or partial measurements. Dark and light themes, keyboard navigation, responsive layouts, and reduced-motion handling are included.
 
-The dashboard includes attention-first project search and filters, restorable view links, and usage comparisons against the preceding period. See [dashboard behavior and measurement limits](docs/DASHBOARD-EVOLUTION.md).
+The dashboard includes attention-first project search and filters, project ranking by attention, last activity, token usage, reported cost, acceptance, or name, restorable view links, and usage comparisons against the preceding period. From a project’s live view you can request a safe-boundary pause or resume, add an operator note, and use **Queue a change** for the next planning boundary. See [dashboard behavior and measurement limits](docs/DASHBOARD-EVOLUTION.md) and the [dashboard overhaul contract](docs/DASHBOARD-OVERHAUL.md).
 
-Projects are registered explicitly; this version does not automatically discover every process or aggregate other computers. Start/resume and budget changes use the CLI. Missing history appears as unknown; time ranges are empirical estimates, not exact deadlines.
+Projects are registered explicitly; this version does not automatically discover every process or aggregate other computers. Dashboard controls call the existing goal/loop pause and resume boundaries and never execute arbitrary shell commands. Change requests are append-only pending inbox entries, not immediate code changes. The server stays loopback-only and POST actions require same-origin session authorization; the local Yoke process remains the authority for execution. Missing history appears as unknown; time ranges are empirical estimates, not exact deadlines. Read the [overhaul contract](docs/DASHBOARD-OVERHAUL.md) for data limits and non-goals.
 
 ### Verified goals and efficient execution
 
@@ -208,10 +208,11 @@ Yoke's CLI is deterministic and chainable by design: an agent (or a shell `&&`)
 | `yoke projects add\|list\|remove` | Register a project, list registrations or remove a reference by ID | `0` · `2` invalid/unavailable |
 | `yoke check [dir] [--json] [--requirement=] [--protect [--refresh]]` | Execute acceptance checks or explicitly pin their infrastructure | `0` passed/pinned · `1` failed · `2` unverified/unavailable |
 | `yoke goal set\|run\|resume\|pause\|status\|handoff\|budget [dir]` | Durable objectives, provider handoff, protected checks and checkpoint budgets | run/resume: `0` complete · `1` unfinished · `2` unavailable |
-| `yoke setup [dir] [--yes] [--host=] [--agent=] [--runner=] [--code-graph=] [--decision-policy=] [--loop\|--no-loop] [--routing\|--no-routing] [--model-provider=deepseek,kimi]` | Shared setup for all seven harnesses; optional DeepSeek/Kimi API profiles run through Qwen | `0` · `1` invalid setup |
+| `yoke setup [dir] [--yes] [--host=] [--agent=] [--runner=] [--code-graph=] [--code-intelligence=off\|shadow\|active] [--decision-policy=] [--loop\|--no-loop] [--routing\|--no-routing] [--model-provider=deepseek,kimi]` | Shared setup for all seven harnesses; optional federated code intelligence and DeepSeek/Kimi API profiles | `0` · `1` invalid setup |
+| `yoke code-intelligence-server [--workspace=] [--mode=off\|shadow\|active]` | Serve the single Yoke-controlled MCP facade for federated code intelligence | `0` · `1` invalid/unavailable |
 | `yoke validate [canonDir]` | Validate the canon (schema, frontmatter, templates) | `0` valid · `1` errors |
 | `yoke new <dir> [--idea=] [--agent=] [--runner=] [--loop]` | Greenfield bootstrap: git init → scaffold → retrofit → context → PRD (drafted from `--idea`) → committed | `0` · `1` usage / non-empty dir / draft failed (scaffold survives) · `2` draft agent unavailable |
-| `yoke retrofit [dir] [--agent=claude,codex,gemini,qwen,opencode,kilo,pi\|all] [--code-graph=graphify\|serena] [--loop]` | Install/update the harness for the selected agents, non-destructively | `0` |
+| `yoke retrofit [dir] [--agent=claude,codex,gemini,qwen,opencode,kilo,pi\|all] [--code-graph=graphify\|serena] [--code-intelligence=off\|shadow\|active] [--loop]` | Install/update the harness for the selected agents, non-destructively | `0` |
 | `yoke prd draft [dir] --idea= [--runner=] [--force]` | Idea → 5–12 stories with testable acceptance criteria | `0` · `1` invalid/guarded · `2` agent unavailable |
 | `yoke prd check [dir]` | PRD lint gate (schema, dependencies, cycles, duplicate ids, acceptance) | `0` valid · `1` violations |
 | `yoke change add\|status [dir] [--idea=]` | Queue a change at any time; the loop turns it into append-only stories at the next safe boundary | `0` · `1` invalid inbox/request |
@@ -852,7 +853,7 @@ Yoke's guardrails are **mechanical, not advisory** — the loop blocks on a dirt
 
 ## 🧠 Choose your code-graph
 
-`yoke retrofit --code-graph=graphify|serena` (default `graphify`, remembered per project). The `yoke-retrofit` skill asks and recommends based on the project.
+`yoke retrofit --code-graph=graphify|serena` (default `graphify`, remembered per project) selects the legacy single graph. For complete code intelligence, enable the federated facade with `yoke retrofit --code-intelligence=active` (or `shadow` for a read-only canary). See the [Code Intelligence guide](docs/CODE-INTELLIGENCE.md).
 
 | | **graphify** | **Serena** |
 |---|---|---|
@@ -862,6 +863,8 @@ Yoke's guardrails are **mechanical, not advisory** — the loop blocks on a dirt
 | Best for | rapid exploration / migration / onboarding | systematic refactoring in typed codebases |
 | Caveat | heuristic edges; static index can go stale | one language server per language |
 
+The federated mode composes both structural and semantic evidence and adds Graphify's architecture/document graph. It exposes one Yoke-controlled MCP surface, content-addressed snapshots, partial-coverage reporting and isolated edit previews; the legacy `codeGraph` setting remains valid and unchanged when code intelligence is `off`.
+
 ## 🪙 Token efficiency
 
 Yoke attacks tokens on two complementary surfaces:
@@ -903,6 +906,7 @@ canon/            # the source of truth — harness-agnostic
   AGENTS.md  skills/  policy/  loop/  tools/  manifest.yaml
 src/
   canon/          # manifest schema + validator (yoke validate)
+  code-intelligence/ # federated MCP facade, adapters, snapshots and guarded edits
   change/         # append-only change inbox · planning · independent coverage review
   retrofit/       # detect · plan · apply · planners (all seven harnesses) · tools
   loop/           # prd · gates · runner · verify · git/worktree · loop · run-command · lock · cleanup
@@ -925,7 +929,7 @@ release provenance.
 ## 🧪 Development
 
 ```bash
-npm test          # vitest (1231 tests)
+npm test          # vitest (1268 tests)
 npm run build     # tsc, no emit errors
 npm run yoke -- validate canon
 ```

package/canon/manifest.yaml

@@ -1,5 +1,5 @@
 name: yoke-canon
-version: 1.13.0
+version: 1.14.0
 agents: [claude, codex, gemini, qwen, opencode, kilo, pi]
 skills:
   - { id: tdd, path: skills/tdd, kind: methodology, invocation: auto }

package/dist/cli.js

@@ -22,6 +22,7 @@ import { runUpgrade } from './update/upgrade.js';
 import { AGENT_LIST, isSupportedAgent, SUPPORTED_AGENTS } from './agents/catalog.js';
 import { printAudit, runAudit } from './audit/command.js';
 import { runSetup } from './setup/command.js';
+import { runCodeIntelligenceServer } from './code-intelligence/mcp-server.js';
 import { pendingChanges, queueChange } from './change/inbox.js';
 import { answerPendingDecision, answeredDecisionResumeIsValid, clearDecisionResume, decisionProcessingExists, decisionResumeMatchesCurrent, finalizeCommittedDecisionResume, formatPendingDecision, readDecisionResume, readPendingDecision, writeDecisionResume, } from './loop/decision.js';
 export { runRetrofit } from './retrofit/command.js';
@@ -104,6 +105,8 @@ export function parseQualityFlags(args) {
 export function main(argv) {
     const [cmd, ...rest] = argv;
     switch (cmd) {
+        case 'code-intelligence-server':
+            return runCodeIntelligenceServer(rest).then(() => 0).catch(error => { console.error(`Code intelligence server: ${error.message}`); return 2; });
         case 'setup': {
             const targetDir = rest.find(a => !a.startsWith('-')) ?? '.';
             const valid = [...SUPPORTED_AGENTS];
@@ -130,6 +133,11 @@ export function main(argv) {
                 console.error(`Invalid --code-graph value: ${graphArg}`);
                 return 1;
             }
+            const intelligenceArg = rest.find(a => a.startsWith('--code-intelligence='))?.slice('--code-intelligence='.length);
+            if (intelligenceArg && !['off', 'shadow', 'active'].includes(intelligenceArg)) {
+                console.error(`Invalid --code-intelligence value: ${intelligenceArg}`);
+                return 1;
+            }
             const policyArg = rest.find(a => a.startsWith('--decision-policy='))?.slice('--decision-policy='.length);
             if (policyArg && policyArg !== 'auto' && policyArg !== 'critical') {
                 console.error(`Invalid --decision-policy value: ${policyArg}`);
@@ -152,6 +160,7 @@ export function main(argv) {
                 modelProviders: modelProviders,
                 host: hostArg, agents, runner: runnerArg,
                 codeGraph: graphArg,
+                codeIntelligence: intelligenceArg,
                 loop, routing, decisionPolicy: policyArg,
                 routingStrategy: routingStrategy,
                 routingPreset: rest.includes('--routing-preset'),
@@ -291,7 +300,12 @@ export function main(argv) {
                 console.error(`Invalid --code-graph value: ${cgArg} (expected graphify|serena)`);
                 return 1;
             }
-            return runRetrofit(targetDir, { loop, agents, codeGraph });
+            const ciArg = rest.find(a => a.startsWith('--code-intelligence='))?.slice('--code-intelligence='.length);
+            if (ciArg && !['off', 'shadow', 'active'].includes(ciArg)) {
+                console.error(`Invalid --code-intelligence value: ${ciArg} (expected off|shadow|active)`);
+                return 1;
+            }
+            return runRetrofit(targetDir, { loop, agents, codeGraph, codeIntelligence: ciArg });
         }
         case 'change': {
             const sub = rest[0];
@@ -657,7 +671,7 @@ export function main(argv) {
             return runUpgrade();
         default:
             console.log('Project workflows: yoke check [dir] [--json|--protect] | goal set|run|resume|pause|status|handoff|budget [dir] | projects add|list|remove | dashboard [dir] [--port=N]');
-            console.log(`usage: yoke <setup [dir] | new <dir> [--idea="..."] | validate [canonDir] | retrofit [targetDir] [--agent=${AGENT_LIST}|all] [--code-graph=graphify|serena] [--loop] | change <add|status> [dir] | prd <draft|check|assess> [dir] | loop <on|off|status|decision|answer|resume|run|cleanup> | context <init|status> | review [dir] [--reviewer=<${AGENT_LIST}>] [--base=<ref>] [--focus="..."] | design-scan [dir] [--max=N] [--report] | flow-smoke [dir] [--url=<baseUrl>] [--label=<name>] | upgrade>`);
+            console.log(`usage: yoke <setup [dir] | new <dir> [--idea="..."] | validate [canonDir] | retrofit [targetDir] [--agent=${AGENT_LIST}|all] [--code-graph=graphify|serena] [--code-intelligence=off|shadow|active] [--loop] | change <add|status> [dir] | code-intelligence-server --workspace=<dir> --mode=<mode> | prd <draft|check|assess> [dir] | loop <on|off|status|decision|answer|resume|run|cleanup> | context <init|status> | review [dir] | design-scan [dir] | flow-smoke [dir] | upgrade>`);
             return cmd ? 1 : 0;
     }
 }

package/dist/code-intelligence/adapters/graft.js

@@ -0,0 +1,11 @@
+import { McpBackendAdapter } from './mcp.js';
+export const GRAFT_VERSION = '0.17.0';
+export function createGraftAdapter(cwd, override) {
+    return new McpBackendAdapter({
+        name: 'graft', version: GRAFT_VERSION, cwd, command: override?.command ?? 'graft', args: override?.args ?? ['mcp'], framing: 'line', semantic: false, documents: false,
+        aliases: { context: 'graft_find_code', trace: 'graft_trace_calls', file: 'graft_file_api', freshness: 'graft_check_freshness', repo_map: 'graft_repo_map' },
+    });
+}
+export function graftCall(kind, args) {
+    return { tool: kind, arguments: args };
+}

package/dist/code-intelligence/adapters/graphify.js

@@ -0,0 +1,8 @@
+import { McpBackendAdapter } from './mcp.js';
+export const GRAPHIFY_VERSION = '0.9.56';
+export function createGraphifyAdapter(cwd, override) {
+    return new McpBackendAdapter({
+        name: 'graphify', version: GRAPHIFY_VERSION, cwd, command: override?.command ?? 'python', args: override?.args ?? ['-m', 'graphify.serve'], framing: 'content-length', semantic: false, documents: true,
+        aliases: { context: 'query_graph', symbol: 'get_node', neighbors: 'get_neighbors', trace: 'shortest_path', impact: 'get_pr_impact' },
+    });
+}

package/dist/code-intelligence/adapters/index.js

@@ -0,0 +1,5 @@
+export * from './types.js';
+export * from './mcp.js';
+export * from './graft.js';
+export * from './graphify.js';
+export * from './serena.js';

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

@@ -0,0 +1,37 @@
+import { McpStdioClient } from '../mcp-client.js';
+function valueFromResult(value) {
+    if (!value || typeof value !== 'object')
+        return value;
+    if (value.structuredContent !== undefined)
+        return value.structuredContent;
+    const text = Array.isArray(value.content) ? value.content.find((item) => item?.type === 'text')?.text : undefined;
+    if (typeof text !== 'string')
+        return value;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { text };
+    }
+}
+export class McpBackendAdapter {
+    name;
+    version;
+    semantic;
+    documents;
+    client;
+    aliases;
+    constructor(options) {
+        this.name = options.name;
+        this.version = options.version;
+        this.semantic = options.semantic;
+        this.documents = options.documents;
+        this.aliases = options.aliases;
+        this.client = new McpStdioClient(options.command, options.args, options.cwd, options.framing);
+    }
+    async call(request, timeoutMs) {
+        const tool = this.aliases[request.tool] ?? request.tool;
+        return valueFromResult(await this.client.call(tool, request.arguments, timeoutMs));
+    }
+    close() { return this.client.close(); }
+}

package/dist/code-intelligence/adapters/serena.js

@@ -0,0 +1,11 @@
+import { McpBackendAdapter } from './mcp.js';
+export const SERENA_VERSION = '1.7.1-dev';
+export function createSerenaAdapter(cwd, override) {
+    return new McpBackendAdapter({
+        name: 'serena-lsp', version: SERENA_VERSION, cwd, command: override?.command ?? 'serena', args: override?.args ?? ['start-mcp-server', '--project-from-cwd', '--context', 'codex'], framing: 'content-length', semantic: true, documents: false,
+        aliases: {
+            symbol: 'find_symbol', references: 'find_referencing_symbols', implementations: 'find_implementations', overview: 'get_symbols_overview', diagnostics: 'get_diagnostics_for_file',
+            rename: 'rename_symbol', replace_symbol_body: 'replace_symbol_body', insert_before_symbol: 'insert_before_symbol', insert_after_symbol: 'insert_after_symbol', safe_delete: 'safe_delete_symbol',
+        },
+    });
+}

package/dist/code-intelligence/adapters/types.js

@@ -0,0 +1 @@
+export {};

package/dist/code-intelligence/contracts.js

@@ -0,0 +1,137 @@
+import { z } from 'zod';
+export const CodeIntelligenceModeSchema = z.enum(['off', 'shadow', 'active']);
+export const BackendNameSchema = z.enum(['graft', 'graphify', 'serena-lsp', 'serena-jetbrains', 'yoke']);
+export const StatusSchema = z.enum(['success', 'partial', 'blocked', 'error']);
+export const ResolutionSchema = z.enum(['resolved', 'unresolved', 'ambiguous', 'not_applicable']);
+export const FreshnessSchema = z.enum(['current', 'stale', 'unknown']);
+export const ProvenanceSchema = z.object({
+    backend: BackendNameSchema,
+    version: z.string().min(1),
+    source_path: z.string().nullable(),
+    content_hash: z.string().nullable(),
+    byte_range: z.object({ start: z.number().int().nonnegative(), end: z.number().int().nonnegative() }).nullable(),
+    origin: z.enum(['parser', 'resolver', 'lsp', 'ide', 'llm', 'manual']),
+    resolution: ResolutionSchema,
+    freshness: FreshnessSchema,
+});
+export const CoverageSchema = z.object({
+    backends_requested: z.array(BackendNameSchema),
+    backends_used: z.array(BackendNameSchema),
+    backends_missing: z.array(BackendNameSchema),
+    structural: z.enum(['complete', 'partial', 'unavailable']),
+    semantic: z.enum(['complete', 'partial', 'unavailable']),
+    documents: z.enum(['complete', 'partial', 'unavailable']),
+});
+export const MetricsSchema = z.object({
+    latency_ms: z.number().nonnegative(),
+    result_tokens: z.number().int().nonnegative(),
+    token_count_kind: z.enum(['exact', 'estimated']),
+    returned_bytes: z.number().int().nonnegative(),
+});
+export const ErrorSchema = z.object({
+    code: z.enum([
+        'INVALID_ARGUMENT', 'WORKSPACE_DENIED', 'CAPABILITY_UNAVAILABLE', 'SNAPSHOT_STALE',
+        'AMBIGUOUS_SYMBOL', 'BACKEND_TIMEOUT', 'BACKEND_UNAVAILABLE', 'BUDGET_EXCEEDED',
+        'APPROVAL_REQUIRED', 'PLAN_EXPIRED', 'SCOPE_VIOLATION', 'VALIDATION_FAILED',
+        'WRITE_CONFLICT', 'IDEMPOTENCY_CONFLICT', 'INTERNAL_ERROR',
+    ]),
+    message: z.string().min(1),
+    backend: BackendNameSchema.optional(),
+});
+export const ItemSchema = z.object({
+    item_id: z.string().min(1),
+    kind: z.enum(['symbol', 'code', 'document', 'memory', 'summary']),
+    path: z.string().nullable(),
+    excerpt: z.string().max(12000),
+    evidence_ids: z.array(z.string().min(1)),
+    rank: z.number().nonnegative(),
+});
+export const SymbolSchema = z.object({
+    symbol_id: z.string().min(1),
+    name: z.string().min(1),
+    path: z.string().nullable(),
+    kind: z.string().min(1),
+    signature: z.string().nullable(),
+    evidence_ids: z.array(z.string().min(1)),
+});
+export const ReferenceSchema = z.object({
+    symbol_id: z.string().min(1),
+    path: z.string().nullable(),
+    line: z.number().int().positive().nullable(),
+    excerpt: z.string().max(4000),
+    evidence_ids: z.array(z.string().min(1)),
+});
+export const DiagnosticSchema = z.object({
+    path: z.string().nullable(),
+    line: z.number().int().positive().nullable(),
+    severity: z.enum(['error', 'warning', 'info', 'unknown']),
+    message: z.string().max(4000),
+    evidence_ids: z.array(z.string().min(1)),
+});
+export const EdgeSchema = z.object({
+    from: z.string().min(1),
+    to: z.string().min(1),
+    relation: z.enum(['calls', 'references', 'imports', 'implements', 'extends', 'docs', 'rationale_for', 'related_to']),
+    evidence_ids: z.array(z.string().min(1)),
+});
+export const ResponseBaseSchema = z.object({
+    schema_version: z.literal('0.1.0'),
+    request_id: z.string().min(1),
+    workspace_id: z.string().min(1),
+    snapshot_id: z.string().min(1),
+    status: StatusSchema,
+    coverage: CoverageSchema,
+    provenance: z.array(ProvenanceSchema),
+    warnings: z.array(z.string()),
+    metrics: MetricsSchema,
+    artifact_uri: z.string().nullable(),
+    error: ErrorSchema.nullable(),
+});
+const BudgetSchema = z.object({
+    token_budget: z.number().int().min(128).max(16000).default(2400),
+    timeout_ms: z.number().int().min(100).max(60000).default(5000),
+});
+export const ContextInputSchema = z.object({
+    workspace_id: z.string().min(1), query: z.string().min(1).max(20000), snapshot_id: z.string().min(1).optional(),
+    mode: z.enum(['orient', 'locate', 'explain']).default('orient'), paths: z.array(z.string().min(1)).max(32).default([]),
+    include_docs: z.boolean().default(false), ...BudgetSchema.shape,
+});
+export const SymbolInputSchema = z.object({
+    workspace_id: z.string().min(1), snapshot_id: z.string().min(1), symbol_id: z.string().min(1).optional(),
+    query: z.string().min(1).optional(), path: z.string().min(1).optional(),
+    include: z.array(z.enum(['definition', 'references', 'implementations', 'diagnostics'])).default(['definition']), ...BudgetSchema.shape,
+}).refine(v => Boolean(v.symbol_id) !== Boolean(v.query), 'exactly one of symbol_id or query is required');
+export const TraceInputSchema = z.object({
+    workspace_id: z.string().min(1), snapshot_id: z.string().min(1), symbol_id: z.string().min(1),
+    direction: z.enum(['in', 'out']), relations: z.array(z.enum(['calls', 'references', 'imports', 'implements', 'extends'])).min(1),
+    max_depth: z.number().int().min(1).max(6).default(2), max_nodes: z.number().int().min(1).max(2000).default(200),
+    require_resolved: z.boolean().default(false), timeout_ms: z.number().int().min(100).max(60000).default(5000),
+});
+const TargetSchema = z.union([z.object({ path: z.string().min(1) }), z.object({ symbol_id: z.string().min(1) })]);
+export const ImpactInputSchema = z.object({
+    workspace_id: z.string().min(1), snapshot_id: z.string().min(1), targets: z.array(TargetSchema).max(50).optional(),
+    plan_id: z.string().min(1).optional(), include_docs: z.boolean().default(true), require_semantic: z.boolean().default(true),
+    max_depth: z.number().int().min(1).max(6).default(3), timeout_ms: z.number().int().min(100).max(60000).default(10000),
+}).refine(v => Boolean(v.targets) !== Boolean(v.plan_id), 'exactly one of targets or plan_id is required');
+const OperationSchema = z.discriminatedUnion('kind', [
+    z.object({ kind: z.literal('rename'), symbol_id: z.string().min(1), new_name: z.string().regex(/^[A-Za-z_$][\w$]*$/) }),
+    z.object({ kind: z.literal('replace_symbol_body'), symbol_id: z.string().min(1), content: z.string().max(500000) }),
+    z.object({ kind: z.literal('insert_before_symbol'), symbol_id: z.string().min(1), content: z.string().max(500000) }),
+    z.object({ kind: z.literal('insert_after_symbol'), symbol_id: z.string().min(1), content: z.string().max(500000) }),
+    z.object({ kind: z.literal('safe_delete'), symbol_id: z.string().min(1) }),
+]);
+export const EditPreviewInputSchema = z.object({
+    workspace_id: z.string().min(1), snapshot_id: z.string().min(1), operations: z.array(OperationSchema).min(1).max(20),
+    validation_profile: z.enum(['default', 'extended']), timeout_ms: z.number().int().min(100).max(600000).default(120000),
+});
+export const EditApplyInputSchema = z.object({
+    workspace_id: z.string().min(1), plan_id: z.string().min(1), expected_snapshot_id: z.string().min(1),
+    idempotency_key: z.string().min(8).max(128),
+});
+export const TOOL_NAMES = ['code_context', 'code_symbol', 'code_trace', 'code_impact', 'code_edit_preview', 'code_edit_apply'];
+export const TOOL_DEFINITIONS = TOOL_NAMES.map(name => ({
+    name,
+    description: `Yoke-controlled ${name.replace('code_', '').replace('_', ' ')} with snapshot-bound evidence.`,
+    inputSchema: { type: 'object', additionalProperties: false },
+    annotations: { openWorldHint: false, destructiveHint: name === 'code_edit_apply', readOnlyHint: name !== 'code_edit_preview' && name !== 'code_edit_apply', idempotentHint: name !== 'code_edit_apply' },
+}));