@esneiderbravo/speclaw 0.3.13 → 0.4.0

package/README.md

@@ -123,7 +123,7 @@ tokenizer on this corpus — not a BPE dependency):
 
 | | Tokens |
 | :-- | --: |
-| **speclaw budget (always-on)** | **~11.7k** (budget ceiling **13.0k**) |
+| **speclaw budget (always-on)** | **~12.9k** (8 MCP tools · ceiling **13.0k**) |
 | Spec Kit commands alone | ~18.6k ([spec-kit#1401](https://github.com/github/spec-kit/issues/1401)) |
 
 ```bash
@@ -184,7 +184,7 @@ Plus a **`reports/`** folder — scaffolded at draft, filled at build with one r
 **Three ways to drive it — same engine, no external CLI:**
 
 - **In your agent** — the `/lawbook:explore`, `/lawbook:draft`, `/lawbook:build`, `/lawbook:sync`, `/lawbook:archive` commands (installed as skills).
-- **MCP tools** — `lawbook_init`, `lawbook_validate`, `lawbook_sync`, `lawbook_archive`, `lawbook_list`.
+- **MCP tools** — eight canonical tools: `compass_explore`, `compass_find`, `compass_diff_context`, `compass_index`, `lawbook_change`, `lawbook_investigate`, `speclaw_setup`, `speclaw_check`.
 - **CLI** — `speclaw lawbook init | list | validate | sync | archive`.
 
 The workspace is committed under `lawbook/`: `specs/` (canonical), `changes/`

package/dist/cli/commands/query.js

@@ -1,6 +1,7 @@
 import { explore, search, recall, impact, trace } from "../../modules/compass/query.js";
 import { affectedTests } from "../../modules/compass/affected.js";
 import { hotspots, coupling } from "../../modules/compass/hotspots.js";
+import { diffContext, formatDiffContext } from "../../modules/compass/diff-context.js";
 import { list } from "../lib/args.js";
 import { ui } from "../lib/ui.js";
 /**
@@ -161,6 +162,25 @@ export async function runQuery(cmd, flags) {
                 result.warnings.forEach((w) => ui.warn(w));
                 return;
             }
+            case "diff-context": {
+                const files = list(flags.file);
+                const rev = typeof flags.rev === "string" ? flags.rev : undefined;
+                if (files.length === 0 && !rev && !flags.worktree) {
+                    need(undefined, "diff-context [--file <path>...] [--rev <ref>] [--worktree]");
+                }
+                const result = diffContext({
+                    projectPath: cwd,
+                    rev: flags.worktree ? "WORKTREE" : rev,
+                    paths: files.length ? files : undefined,
+                    mode: flags.full ? "full" : "brief",
+                });
+                if (asJson) {
+                    console.log(JSON.stringify(result, null, 2));
+                    return;
+                }
+                console.log(formatDiffContext(result));
+                return;
+            }
             case "trace": {
                 const r = trace(cwd, need(args[0], "trace <from> <to>"), need(args[1], "trace <from> <to>"));
                 ui.heading(`Trace ${r.from} → ${r.to}`);

package/dist/cli/commands/update.js

@@ -136,11 +136,13 @@ const MIGRATIONS = [
             "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
     },
     {
-        version: "0.3.13",
-        describe: "Bugfix specs — draft --bug, bugfix.md, lawbook_investigate",
-        agentPrompt: "- Mention bug changes: `speclaw lawbook draft --bug`, `bugfix.md` (repro + regression + prevention), " +
-            "and `lawbook_investigate` / the investigate skill for graph-backed RCA. Feature ceremony unchanged; " +
-            "`changeType: bug` in `change.json`. Security-withheld mode is not in this release.\n" +
+        version: "0.4.0",
+        describe: "Tool surface — eight canonical MCP tools, aliases deprecated",
+        agentPrompt: "- MCP exposes eight canonical tools: `compass_explore`, `compass_find`, `compass_diff_context`, " +
+            "`compass_index`, `lawbook_change`, `lawbook_investigate`, `speclaw_setup`, `speclaw_check`. " +
+            "Retired names (e.g. `compass_search`, `lawbook_validate`, `init_project`) are aliases with " +
+            "`[deprecated]` responses — prefer the canonical names. `scaffold`, `doctor`, `compass_visualize`, " +
+            "and `law_verify` are CLI-only. Minimal profile omits setup/check/investigate/index.\n" +
             "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
     },
 ];

package/dist/cli/index.js

@@ -25,6 +25,7 @@ Compass (code intelligence — the same surface agents use via MCP)
   recall "<query>"         Find code by meaning (semantic)
   impact <node>            Blast radius (grouped by module; --flat / --json)
   affected-tests           Tests affected by a change (--file / --from-diff / --json)
+  diff-context             Change context for a diff (--file / --rev / --worktree / --json)
   hotspots                 Rank files by recent churn × AST complexity (--json / --sort)
   coupling <file>          Temporal co-change partners for a file (--json)
   trace <from> <to>        A call path between two nodes
@@ -144,6 +145,7 @@ async function dispatch(cmd, flags) {
         case "impact":
         case "trace":
         case "affected-tests":
+        case "diff-context":
         case "hotspots":
         case "coupling":
             return (await import("./commands/query.js")).runQuery(cmd, flags);

package/dist/modules/compass/diff-context.js

@@ -0,0 +1,134 @@
+import { isGitRepo, changedFiles, worktreeChangedFiles } from "../../shared/git.js";
+import { openDb, indexExists } from "./db.js";
+import { impact } from "./query.js";
+import { affectedTests } from "./affected.js";
+import { hotspots } from "./hotspots.js";
+import { summarizeImpact } from "./impact-summary.js";
+import { applyTextBudget, } from "../../shared/output-budget.js";
+function listWorktreeChanges(projectPath) {
+    const wt = worktreeChangedFiles(projectPath);
+    if (wt.length > 0)
+        return wt;
+    for (const base of ["main", "master"]) {
+        const files = changedFiles(projectPath, base);
+        if (files.length > 0)
+            return files;
+    }
+    return [];
+}
+function symbolsForFiles(projectPath, files, overestimate) {
+    if (!indexExists(projectPath))
+        return [];
+    const db = openDb(projectPath);
+    try {
+        const out = [];
+        for (const file of files) {
+            const nodes = db
+                .prepare(`SELECT n.name, n.kind, n.start_line AS line, f.path AS file
+           FROM nodes n JOIN files f ON f.id = n.file_id
+           WHERE f.path = ?`)
+                .all(file);
+            if (overestimate || nodes.length === 0) {
+                for (const n of nodes)
+                    out.push(n);
+            }
+            else {
+                for (const n of nodes)
+                    out.push(n);
+            }
+        }
+        return out;
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Graph context for a set of changed files (git rev, working tree, or explicit paths).
+ *
+ * @param query - Diff scope and output mode.
+ */
+export function diffContext(query) {
+    const mode = query.mode ?? "brief";
+    const truncated = [];
+    let files = [...(query.paths ?? [])];
+    let message;
+    if (files.length === 0) {
+        if (!isGitRepo(query.projectPath)) {
+            throw new Error("not a git repository — pass `paths` explicitly to compass_diff_context");
+        }
+        files =
+            query.rev && query.rev !== "WORKTREE"
+                ? changedFiles(query.projectPath, query.rev)
+                : listWorktreeChanges(query.projectPath);
+    }
+    if (files.length === 0) {
+        return {
+            changedFiles: [],
+            changedSymbols: [],
+            message: "no changed files in scope",
+            truncated,
+        };
+    }
+    if (files.length > 50) {
+        message = `diff touches ${files.length} files — returning aggregated blast radius only; pass paths to narrow`;
+        files = files.slice(0, 50);
+    }
+    const overestimate = Boolean(query.paths?.length && !query.rev);
+    if (overestimate) {
+        message = "symbol set is an overestimate (paths without hunks — all nodes in those files)";
+    }
+    const changedSymbols = symbolsForFiles(query.projectPath, files, overestimate);
+    const result = { changedFiles: files, changedSymbols, truncated, message };
+    try {
+        const imp = impact(query.projectPath, {
+            files,
+            maxDepth: query.maxDepth ?? 4,
+            format: "grouped",
+        });
+        result.blastRadius = summarizeImpact(imp);
+    }
+    catch {
+        /* no index */
+    }
+    try {
+        const at = affectedTests(query.projectPath, {
+            files,
+            fromDiff: query.rev === "WORKTREE" || !query.rev ? "WORKTREE" : query.rev,
+            maxDepth: query.maxDepth ?? 6,
+        });
+        result.affectedTests = {
+            tests: at.tests,
+            command: at.command,
+            mode: at.mode,
+            reason: at.reason,
+        };
+    }
+    catch {
+        /* degrade */
+    }
+    try {
+        const hs = hotspots(query.projectPath, { sortBy: "combined", limit: 200 });
+        const touched = hs.hotspots.filter((h) => files.includes(h.file));
+        result.hotspotsTouched = touched.slice(0, 10).map((h) => ({
+            file: h.file,
+            combinedScore: h.combinedScore,
+        }));
+    }
+    catch {
+        /* degrade */
+    }
+    const json = applyTextBudget(JSON.stringify(result, null, 2), mode);
+    if (json.truncated) {
+        truncated.push({
+            field: "response",
+            omitted: json.omittedChars,
+            hint: 'use mode:"full" or pass explicit paths',
+        });
+    }
+    return result;
+}
+/** Format diff context with output budget. */
+export function formatDiffContext(result, mode = "brief") {
+    return applyTextBudget(JSON.stringify(result, null, 2), mode).text;
+}

package/dist/modules/compass/explore-rich.js

@@ -0,0 +1,129 @@
+import { explore, impact, trace, search, recall } from "./query.js";
+import { affectedTests } from "./affected.js";
+import { hotspots } from "./hotspots.js";
+import { summarizeImpact } from "./impact-summary.js";
+import { budgetExploreShape, applyTextBudget, } from "../../shared/output-budget.js";
+const DEFAULT_INCLUDES = [
+    "source",
+    "callers",
+    "callees",
+    "blast_radius",
+    "tests",
+];
+function withoutSource(symbol) {
+    const { source: _omit, ...rest } = symbol;
+    return { ...rest, source: "" };
+}
+/**
+ * Enriched symbol context: explore plus optional blast radius, tests, hotspot,
+ * and call path when `to` is set.
+ *
+ * @param query - Project path, symbol, includes, and output mode.
+ */
+export async function exploreRich(query) {
+    const includes = query.include ?? DEFAULT_INCLUDES;
+    const mode = query.mode ?? "brief";
+    const truncated = [];
+    const degraded = [];
+    if (query.to) {
+        const pathResult = trace(query.projectPath, query.node, query.to, query.maxDepth ?? 8);
+        const base = explore(query.projectPath, query.node);
+        const out = {
+            ...base,
+            path: pathResult.path,
+            truncated,
+            degraded,
+            message: pathResult.path
+                ? `Call path ${query.node} → ${query.to} (${pathResult.hops} hop(s))`
+                : `No call path found within depth limit`,
+        };
+        if (!includes.includes("source") && out.symbol)
+            out.symbol = withoutSource(out.symbol);
+        if (!includes.includes("callers"))
+            out.callers = [];
+        if (!includes.includes("callees"))
+            out.callees = [];
+        budgetExploreShape(out, mode, truncated);
+        return out;
+    }
+    const base = explore(query.projectPath, query.node);
+    const out = { ...base, truncated, degraded };
+    if (!includes.includes("source") && out.symbol)
+        out.symbol = withoutSource(out.symbol);
+    if (!includes.includes("callers"))
+        out.callers = [];
+    if (!includes.includes("callees"))
+        out.callees = [];
+    if (base.found && base.symbol) {
+        const sym = base.symbol.name;
+        const file = base.symbol.file;
+        if (includes.includes("blast_radius")) {
+            try {
+                const imp = impact(query.projectPath, {
+                    symbol: sym,
+                    maxDepth: query.maxDepth ?? 4,
+                    format: "grouped",
+                });
+                out.blastRadius = summarizeImpact(imp);
+            }
+            catch {
+                degraded.push("no-index");
+            }
+        }
+        if (includes.includes("tests")) {
+            try {
+                const at = affectedTests(query.projectPath, {
+                    symbols: [sym],
+                    maxDepth: query.maxDepth ?? 6,
+                });
+                out.affectedTests = {
+                    count: at.tests.length,
+                    files: at.tests.map((t) => t.file),
+                    command: at.command,
+                };
+            }
+            catch {
+                degraded.push("no-tests-data");
+            }
+        }
+        if (includes.includes("hotspot")) {
+            try {
+                const hs = hotspots(query.projectPath, { sortBy: "combined", limit: 200 });
+                const idx = hs.hotspots.findIndex((h) => h.file === file);
+                if (idx >= 0) {
+                    const h = hs.hotspots[idx];
+                    out.hotspot = {
+                        file: h.file,
+                        combinedScore: h.combinedScore,
+                        churn: h.activity.commits,
+                        complexity: h.health?.worstLoc ?? 0,
+                        rank: idx + 1,
+                    };
+                }
+                else {
+                    degraded.push("no-hotspots");
+                }
+            }
+            catch {
+                degraded.push("no-hotspots");
+            }
+        }
+    }
+    budgetExploreShape(out, mode, truncated);
+    if (truncated.length === 0)
+        delete out.truncated;
+    if (degraded.length === 0)
+        delete out.degraded;
+    return out;
+}
+/** Merge lexical and semantic search behind one surface. */
+export async function findSymbols(projectPath, query, mode, limit) {
+    if (mode === "exact")
+        return search(projectPath, query, limit ?? 25);
+    return recall(projectPath, query, limit ?? 15);
+}
+/** Serialize explore-rich with output budget applied. */
+export function formatExploreRich(result, mode = "brief") {
+    const json = JSON.stringify(result, null, 2);
+    return applyTextBudget(json, mode).text;
+}

package/dist/modules/compass/impact-summary.js

@@ -0,0 +1,33 @@
+/**
+ * Convert a grouped {@link ImpactResult} into a compact blast-radius summary.
+ *
+ * @param impact - Grouped impact output from Compass.
+ */
+export function summarizeImpact(impact) {
+    const topNodes = [];
+    for (const mod of impact.modules) {
+        for (const n of mod.top) {
+            topNodes.push({ name: n.name, file: n.file, depth: n.depth });
+            if (topNodes.length >= 15)
+                break;
+        }
+        if (topNodes.length >= 15)
+            break;
+    }
+    const reachesPublicApi = impact.modules.some((m) => m.module.includes("public") || m.module === "api" || m.module.endsWith("/api"));
+    return {
+        totalNodes: impact.totals.nodes,
+        totalFiles: impact.totals.files,
+        totalModules: impact.totals.modules,
+        byModule: impact.modules.map((m) => ({
+            module: m.module,
+            nodes: m.nodes,
+            files: m.files,
+            minDepth: m.minDepth,
+        })),
+        reachesPublicApi,
+        maxDepthReached: impact.limits.maxDepthReached,
+        truncated: impact.limits.truncated,
+        topNodes,
+    };
+}

package/dist/modules/compass/register.js

@@ -1,19 +1,17 @@
 import { z } from "zod";
-import { defineTool, text } from "../../shared/mcp.js";
+import { defineTool, defineAliasTool, text } from "../../shared/mcp.js";
 import { shouldExpose } from "../../shared/exposure.js";
+import { aliasesEnabled } from "../../shared/tool-catalog.js";
+import { logDeprecatedCall, prefixDeprecated } from "../../shared/deprecation.js";
 import { buildIndex } from "./indexer.js";
-import { explore, search, recall, impact, trace } from "./query.js";
+import { impact } from "./query.js";
 import { affectedTests } from "./affected.js";
 import { hotspots, coupling } from "./hotspots.js";
 import { startWatch, stopWatch, watchStatus } from "./watcher.js";
-import { visualize } from "./visualize.js";
-// ─── Compass: speclaw's own code-intelligence engine (no external deps) ───
-/**
- * Register Compass MCP tools on the given server.
- *
- * @param server - The MCP server to register on.
- * @param opts - Exposure options (`minimal` omits setup/specialized tools).
- */
+import { exploreRich, findSymbols, formatExploreRich, } from "./explore-rich.js";
+import { diffContext, formatDiffContext } from "./diff-context.js";
+const includeEnum = z.array(z.enum(["source", "callers", "callees", "blast_radius", "tests", "hotspot"]));
+/** Register Compass MCP tools on the given server. */
 export function registerCompass(server, opts = {}) {
     const minimal = Boolean(opts.minimal);
     const add = (name, description, inputSchema, handler) => {
@@ -21,78 +19,170 @@ export function registerCompass(server, opts = {}) {
             return;
         defineTool(server, { name, description, inputSchema, handler });
     };
-    add("compass_index", "Build or refresh the local code graph index. Run once per project, then on demand.", { projectPath: z.string() }, async ({ projectPath }) => text(await buildIndex(projectPath)));
-    add("compass_explore", "Read a symbol's source plus callers and callees. Prefer this before grep or Read.", { projectPath: z.string(), node: z.string() }, async ({ projectPath, node }) => text(explore(projectPath, node)));
-    add("compass_search", "Find symbols by name or keyword (substring). Cheaper structural search than grep.", { projectPath: z.string(), query: z.string(), limit: z.number().optional() }, async ({ projectPath, query, limit }) => text(search(projectPath, query, limit ?? 25)));
-    add("compass_recall", "Find symbols by meaning via local embeddings. Use when names are unknown.", { projectPath: z.string(), query: z.string(), limit: z.number().optional() }, async ({ projectPath, query, limit }) => text(await recall(projectPath, query, limit ?? 15)));
-    add("compass_impact", "Blast radius for a symbol or files, grouped by module (not a flat dump).", {
+    add("compass_explore", "Symbol context in one call: source, callers, callees, blast radius, tests, hotspot. Prefer before grep.", {
         projectPath: z.string(),
-        /** @deprecated Prefer `symbol`. Kept for existing callers. */
-        node: z.string().optional(),
-        symbol: z.string().optional(),
-        files: z.array(z.string()).optional(),
-        nodeId: z.number().int().optional(),
-        maxDepth: z.number().int().min(1).max(12).optional(),
-        edgeKinds: z.array(z.enum(["call", "import"])).optional(),
-        target: z.enum(["build", "test", "lint", "any"]).optional(),
-        format: z.enum(["grouped", "flat"]).optional(),
-        topModules: z.number().int().min(1).max(50).optional(),
-        topPerModule: z.number().int().min(1).max(50).optional(),
-    }, async (args) => text(impact(args.projectPath, {
-        symbol: args.symbol ?? args.node,
-        files: args.files,
-        nodeId: args.nodeId,
-        maxDepth: args.maxDepth ?? 4,
-        edgeKinds: args.edgeKinds,
-        target: args.target,
-        format: args.format ?? "grouped",
-        topModules: args.topModules,
-        topPerModule: args.topPerModule,
-    })));
-    add("compass_affected_tests", "Select test files affected by a change; returns a ready-to-run command.", {
-        projectPath: z.string(),
-        files: z.array(z.string()).optional(),
-        symbols: z.array(z.string()).optional(),
-        fromDiff: z.string().optional(),
-        maxDepth: z.number().int().min(1).max(12).optional(),
-    }, async ({ projectPath, files, symbols, fromDiff, maxDepth }) => text(affectedTests(projectPath, { files, symbols, fromDiff, maxDepth })));
-    add("compass_hotspots", "Rank files by recent churn and AST complexity; two axes, no magic score.", {
-        projectPath: z.string(),
-        days: z.number().int().min(1).max(3650).optional(),
-        since: z.string().optional(),
-        sortBy: z.enum(["churn", "complexity", "combined"]).optional(),
-        limit: z.number().int().min(1).max(200).optional(),
-    }, async ({ projectPath, days, since, sortBy, limit }) => text(hotspots(projectPath, { days, since, sortBy, limit })));
-    add("compass_coupling", "Files that co-change with a target; strength, graph edge, and test-pair facts.", {
-        projectPath: z.string(),
-        file: z.string(),
-        days: z.number().int().min(1).max(3650).optional(),
-        since: z.string().optional(),
-        minShared: z.number().int().min(1).optional(),
-        maxFilesPerCommit: z.number().int().min(2).optional(),
-        limit: z.number().int().min(1).max(200).optional(),
-    }, async ({ projectPath, file, days, since, minShared, maxFilesPerCommit, limit }) => text(coupling(projectPath, file, { days, since, minShared, maxFilesPerCommit, limit })));
-    add("compass_trace", "Find a call path between two symbols within a depth limit.", {
-        projectPath: z.string(),
-        from: z.string(),
-        to: z.string(),
-        maxDepth: z.number().optional(),
-    }, async ({ projectPath, from, to, maxDepth }) => text(trace(projectPath, from, to, maxDepth ?? 8)));
-    add("compass_visualize", "Write an offline HTML graph to .speclaw/graph.html for interactive exploration.", {
+        node: z.string(),
+        to: z.string().optional(),
+        include: includeEnum.optional(),
+        mode: z.enum(["brief", "full"]).optional(),
+        maxDepth: z.number().int().min(1).max(8).optional(),
+    }, async ({ projectPath, node, to, include, mode, maxDepth }) => {
+        const result = await exploreRich({
+            projectPath,
+            node,
+            to,
+            include: include,
+            mode: (mode ?? "brief"),
+            maxDepth,
+        });
+        return text(formatExploreRich(result, (mode ?? "brief")));
+    });
+    add("compass_find", "Find symbols by exact name or by concept. Use exact for identifiers, concept for meaning.", {
         projectPath: z.string(),
-        node: z.string().optional(),
-        depth: z.number().optional(),
+        query: z.string(),
+        mode: z.enum(["exact", "concept"]),
         limit: z.number().optional(),
-    }, async ({ projectPath, node, depth, limit }) => text(visualize(projectPath, { focus: node, depth, limit })));
-    add("compass_watch", "Start, stop, or status a debounced file watcher that re-indexes on change.", {
+    }, async ({ projectPath, query, mode, limit }) => text(await findSymbols(projectPath, query, mode, limit)));
+    add("compass_diff_context", "Graph context of changes in one call: symbols, blast radius, tests, hotspots. Default: working tree.", {
+        projectPath: z.string(),
+        rev: z.string().optional(),
+        paths: z.array(z.string()).optional(),
+        mode: z.enum(["brief", "full"]).optional(),
+        maxDepth: z.number().int().min(1).max(8).optional(),
+    }, async ({ projectPath, rev, paths, mode, maxDepth }) => {
+        const result = diffContext({
+            projectPath,
+            rev,
+            paths,
+            mode: (mode ?? "brief"),
+            maxDepth,
+        });
+        return text(formatDiffContext(result, (mode ?? "brief")));
+    });
+    add("compass_index", "Build or refresh the code graph index; optional watch action for live re-index.", {
         projectPath: z.string(),
-        action: z.enum(["start", "stop", "status"]),
+        action: z.enum(["index", "start", "stop", "status"]).optional(),
     }, async ({ projectPath, action }) => {
-        const result = action === "start"
+        const act = action ?? "index";
+        if (act === "index")
+            return text(await buildIndex(projectPath));
+        const result = act === "start"
             ? startWatch(projectPath)
-            : action === "stop"
+            : act === "stop"
                 ? stopWatch(projectPath)
                 : watchStatus(projectPath);
         return text(result);
     });
+    if (minimal || !aliasesEnabled())
+        return;
+    defineAliasTool(server, {
+        name: "compass_search",
+        description: "Deprecated alias for compass_find mode exact.",
+        inputSchema: { projectPath: z.string(), query: z.string(), limit: z.number().optional() },
+        handler: async ({ projectPath, query, limit }) => {
+            logDeprecatedCall(projectPath, "compass_search");
+            const body = JSON.stringify(await findSymbols(projectPath, query, "exact", limit), null, 2);
+            return text(prefixDeprecated("compass_search", body));
+        },
+    });
+    defineAliasTool(server, {
+        name: "compass_recall",
+        description: "Deprecated alias for compass_find mode concept.",
+        inputSchema: { projectPath: z.string(), query: z.string(), limit: z.number().optional() },
+        handler: async ({ projectPath, query, limit }) => {
+            logDeprecatedCall(projectPath, "compass_recall");
+            const body = JSON.stringify(await findSymbols(projectPath, query, "concept", limit), null, 2);
+            return text(prefixDeprecated("compass_recall", body));
+        },
+    });
+    defineAliasTool(server, {
+        name: "compass_impact",
+        description: "Deprecated alias for compass_explore blast_radius include.",
+        inputSchema: {
+            projectPath: z.string(),
+            node: z.string().optional(),
+            symbol: z.string().optional(),
+            files: z.array(z.string()).optional(),
+            maxDepth: z.number().optional(),
+        },
+        handler: async (args) => {
+            logDeprecatedCall(args.projectPath, "compass_impact");
+            const sym = args.symbol ?? args.node;
+            const body = sym
+                ? JSON.stringify(await exploreRich({
+                    projectPath: args.projectPath,
+                    node: sym,
+                    include: ["blast_radius"],
+                }), null, 2)
+                : JSON.stringify(impact(args.projectPath, { files: args.files, maxDepth: args.maxDepth ?? 4 }), null, 2);
+            return text(prefixDeprecated("compass_impact", body));
+        },
+    });
+    defineAliasTool(server, {
+        name: "compass_trace",
+        description: "Deprecated alias for compass_explore with to parameter.",
+        inputSchema: {
+            projectPath: z.string(),
+            from: z.string(),
+            to: z.string(),
+            maxDepth: z.number().optional(),
+        },
+        handler: async ({ projectPath, from, to, maxDepth }) => {
+            logDeprecatedCall(projectPath, "compass_trace");
+            const body = JSON.stringify(await exploreRich({ projectPath, node: from, to, maxDepth }), null, 2);
+            return text(prefixDeprecated("compass_trace", body));
+        },
+    });
+    defineAliasTool(server, {
+        name: "compass_affected_tests",
+        description: "Deprecated alias — use compass_diff_context or explore.",
+        inputSchema: {
+            projectPath: z.string(),
+            files: z.array(z.string()).optional(),
+            symbols: z.array(z.string()).optional(),
+            fromDiff: z.string().optional(),
+        },
+        handler: async (args) => {
+            logDeprecatedCall(args.projectPath, "compass_affected_tests");
+            const body = JSON.stringify(affectedTests(args.projectPath, args), null, 2);
+            return text(prefixDeprecated("compass_affected_tests", body));
+        },
+    });
+    defineAliasTool(server, {
+        name: "compass_hotspots",
+        description: "Deprecated alias — use compass_explore hotspot include.",
+        inputSchema: { projectPath: z.string(), limit: z.number().optional() },
+        handler: async ({ projectPath, limit }) => {
+            logDeprecatedCall(projectPath, "compass_hotspots");
+            const body = JSON.stringify(hotspots(projectPath, { limit }), null, 2);
+            return text(prefixDeprecated("compass_hotspots", body));
+        },
+    });
+    defineAliasTool(server, {
+        name: "compass_coupling",
+        description: "Deprecated alias — use compass_diff_context.",
+        inputSchema: { projectPath: z.string(), file: z.string() },
+        handler: async ({ projectPath, file }) => {
+            logDeprecatedCall(projectPath, "compass_coupling");
+            const body = JSON.stringify(coupling(projectPath, file, {}), null, 2);
+            return text(prefixDeprecated("compass_coupling", body));
+        },
+    });
+    defineAliasTool(server, {
+        name: "compass_watch",
+        description: "Deprecated alias for compass_index watch actions.",
+        inputSchema: {
+            projectPath: z.string(),
+            action: z.enum(["start", "stop", "status"]),
+        },
+        handler: async ({ projectPath, action }) => {
+            logDeprecatedCall(projectPath, "compass_watch");
+            const result = action === "start"
+                ? startWatch(projectPath)
+                : action === "stop"
+                    ? stopWatch(projectPath)
+                    : watchStatus(projectPath);
+            return text(prefixDeprecated("compass_watch", JSON.stringify(result, null, 2)));
+        },
+    });
 }