@esneiderbravo/speclaw 2.0.2 → 2.0.4

package/dist/cli/commands/check.js

@@ -14,7 +14,9 @@ async function readStdin() {
  *
  * - `--hook-payload -` reads a hook event JSON from stdin, evaluates it, prints
  *   the `hookSpecificOutput` contract, and exits 2 on `deny` (the documented
- *   command-hook block signal).
+ *   command-hook block signal). `PostToolUse` never carries a
+ *   `permissionDecision`: it prints `additionalContext` when the result has a
+ *   reason (nothing otherwise) and always exits 0.
  * - `--dry-run [--path P] [--event E]` previews the verdict for a synthetic
  *   action against path `P`, without blocking anything (always exits 0).
  * - with no flags, prints a summary of the project's declared laws.
@@ -37,6 +39,14 @@ export async function runCheck(flags) {
         const event = (payload.hook_event_name ?? payload.event ?? "PreToolUse");
         const toolName = (payload.tool_name ?? payload.toolName);
         const result = checkAction({ projectPath: cwd, event, toolName, payload });
+        if (event === "PostToolUse") {
+            // PostToolUse (feedback laws, the Compass-first nudge) carries context
+            // only and never a permission decision. Other events keep their output.
+            if (result.hookSpecificOutput) {
+                console.log(JSON.stringify({ hookSpecificOutput: result.hookSpecificOutput }));
+            }
+            return;
+        }
         const decision = result.verdict === "deny" ? "deny" : "allow";
         console.log(JSON.stringify({
             hookSpecificOutput: {

package/dist/cli/commands/cortex.js

@@ -40,6 +40,7 @@ export async function runCortex(flags) {
             pauseForQuestions: Boolean(flags["pause-questions"]),
             note: typeof flags.note === "string" ? flags.note : undefined,
         });
+        printHarnessWarnings(result);
         console.log(JSON.stringify(result, null, 2));
     }
     catch (err) {
@@ -47,3 +48,19 @@ export async function runCortex(flags) {
         process.exit(1);
     }
 }
+/**
+ * Print the Compass-first gate outcome of a harness result to stderr — the
+ * `compassEvidence` count, then any warning — keeping stdout pure JSON.
+ *
+ * @param result - Any `handleHarness` result.
+ */
+export function printHarnessWarnings(result) {
+    const { compassEvidence: ev, warnings } = result;
+    if (ev) {
+        process.stderr.write(`  compass-first: ${ev.calls} Compass evidence call(s) in stage "${ev.stage}" (compassGate: ${ev.mode})\n`);
+    }
+    if (!Array.isArray(warnings))
+        return;
+    for (const w of warnings)
+        process.stderr.write(`  ! ${String(w)}\n`);
+}

package/dist/cli/commands/index-build.js

@@ -1,18 +1,26 @@
 import { buildIndex } from "../../modules/compass/indexer.js";
 import { startWatch } from "../../modules/compass/watcher.js";
+import { recordCompassCall } from "../../shared/compass-calls.js";
 import { ui, renderProgress, clearProgress } from "../lib/ui.js";
 /** (Re)build the Compass code graph for the cwd, showing progress and final stats. */
 export async function runIndex(flags) {
     const cwd = process.cwd();
-    ui.step("Indexing with Compass");
+    recordCompassCall(cwd, "compass_index");
+    const json = Boolean(flags.json);
+    if (!json)
+        ui.step("Indexing with Compass");
     const start = Date.now();
     const stats = await buildIndex(cwd, {
         force: Boolean(flags.force),
         prune: Boolean(flags.prune),
         maxCacheMB: flags["max-cache-mb"] ? Number(flags["max-cache-mb"]) : undefined,
         retentionDays: flags.retention ? Number(flags.retention) : undefined,
-        onProgress: (e) => renderProgress(e.done, e.total, e.file),
+        onProgress: json ? undefined : (e) => renderProgress(e.done, e.total, e.file),
     });
+    if (json) {
+        process.stdout.write(JSON.stringify(stats, null, 2) + "\n");
+        return;
+    }
     clearProgress();
     const secs = ((Date.now() - start) / 1000).toFixed(1);
     const root = stats.rootUnchanged ? " · root unchanged" : "";
@@ -20,6 +28,9 @@ export async function runIndex(flags) {
         `${stats.computed} computed · ${stats.fromCache} fromCache · ` +
         `${stats.unchanged} unchanged · ${stats.skippedByStat} skippedByStat` +
         `${root}  (${secs}s)`);
+    const t = stats.totals;
+    ui.info(`Totals: ${t.files} files · ${t.nodes} nodes · ${t.edges} edges`);
+    ui.info(stats.nextStep);
 }
 /** Build the initial index, then watch for file changes to keep it fresh. */
 export async function runWatch(_flags) {

package/dist/cli/commands/lawbook.js

@@ -1,8 +1,10 @@
 import { specInit, specValidate, specSync, specArchive, specList, } from "../../modules/lawbook/engine.js";
 import { handleLevel } from "../../modules/lawbook/quick.js";
 import { scaffoldBugfix } from "../../modules/lawbook/bugfix.js";
+import { scaffoldFeature } from "../../modules/lawbook/scaffold-change.js";
 import { investigate, formatInvestigateResult } from "../../modules/lawbook/investigate.js";
 import { handleHarness } from "../../modules/cortex/harness.js";
+import { printHarnessWarnings } from "./cortex.js";
 import { list } from "../lib/args.js";
 import { ui } from "../lib/ui.js";
 function today() {
@@ -115,21 +117,32 @@ export async function runSpec(flags) {
                 return;
             }
             case "draft": {
-                if (!flags.bug) {
-                    ui.err("Usage: speclaw lawbook draft --bug <name> [--level N] [--json]");
-                    process.exit(1);
-                }
-                const name = typeof flags.bug === "string" ? flags.bug : req(change, "lawbook draft --bug <name>");
                 const levelFlag = flags.level;
-                const level = levelFlag === undefined || levelFlag === true
-                    ? undefined
-                    : Number(levelFlag);
-                const result = scaffoldBugfix(cwd, name, { level });
+                const level = levelFlag === undefined || levelFlag === true ? undefined : parseLevel(levelFlag);
+                if (flags.bug) {
+                    const name = typeof flags.bug === "string" ? flags.bug : req(change, "lawbook draft --bug <name>");
+                    const result = scaffoldBugfix(cwd, name, { level });
+                    if (flags.json) {
+                        console.log(JSON.stringify(result, null, 2));
+                        return;
+                    }
+                    ui.ok(`bug change "${name}" scaffolded at ${result.dir}`);
+                    return;
+                }
+                const name = req(change, "lawbook draft <name> [--level N] [--capability C] [--json] | --bug <name>");
+                const result = scaffoldFeature(cwd, name, {
+                    level,
+                    reason: typeof flags.reason === "string" ? flags.reason : undefined,
+                    capability: typeof flags.capability === "string" ? flags.capability : undefined,
+                });
                 if (flags.json) {
                     console.log(JSON.stringify(result, null, 2));
                     return;
                 }
-                ui.ok(`bug change "${name}" scaffolded at ${result.dir}`);
+                ui.ok(`feature change "${name}" scaffolded at ${result.dir} ` +
+                    (result.level === null
+                        ? "(level unconfirmed — run `speclaw lawbook level set`)"
+                        : `(level ${result.level})`));
                 return;
             }
             case "archive": {
@@ -170,6 +183,7 @@ export async function runSpec(flags) {
                     pauseForQuestions: Boolean(flags["pause-questions"]),
                     note: typeof flags.note === "string" ? flags.note : undefined,
                 });
+                printHarnessWarnings(result);
                 if (flags.json) {
                     console.log(JSON.stringify(result, null, 2));
                     return;
@@ -187,6 +201,13 @@ export async function runSpec(flags) {
         process.exit(1);
     }
 }
+/** Parse a `--level` flag value into a ceremony level; throws on anything but 0–3. */
+function parseLevel(raw) {
+    const n = Number(Array.isArray(raw) ? raw[raw.length - 1] : raw);
+    if (n === 0 || n === 1 || n === 2 || n === 3)
+        return n;
+    throw new Error(`--level must be 0, 1, 2, or 3 (got "${String(raw)}")`);
+}
 /** Return the value or print a usage error and exit if it is missing. */
 function req(value, usage) {
     if (!value) {

package/dist/cli/commands/query.js

@@ -5,6 +5,16 @@ 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";
+import { recordCompassCall } from "../../shared/compass-calls.js";
+/** CLI query verbs that are Compass call-log twins of an MCP tool. */
+const LOGGED_VERBS = {
+    explore: "compass_explore",
+    search: "compass_search",
+    recall: "compass_recall",
+    impact: "compass_impact",
+    trace: "compass_trace",
+    "diff-context": "compass_diff_context",
+};
 /**
  * Run a Compass query from the shell — the same surface agents call via MCP.
  *
@@ -20,6 +30,9 @@ export async function runQuery(cmd, flags) {
     const focus = list(flags.focus);
     const maxTokens = flags["max-tokens"] ? Number(flags["max-tokens"]) : undefined;
     const explain = Boolean(flags.explain);
+    const logged = LOGGED_VERBS[cmd];
+    if (logged)
+        recordCompassCall(cwd, logged);
     try {
         switch (cmd) {
             case "explore": {

package/dist/cli/index.js

@@ -18,7 +18,7 @@ Setup
   agent add <id>           Configure another agent later (symlinks + MCP)
 
 Compass (code intelligence — the same surface agents use via MCP)
-  index                    (Re)build the local code graph (--force / --prune)
+  index                    (Re)build the local code graph (--force / --prune / --json)
   watch                    Keep the index fresh on file changes
   explore <node>           A node's source + callers/callees
   search <query>           Hybrid find (BM25+vector+name); --focus --max-tokens --explain
@@ -39,6 +39,7 @@ Lawbook (spec-driven workflow)
   lawbook init             Create the lawbook/ workspace
   lawbook list             Active/archived changes and capabilities
   lawbook level <mode>     Propose/set/promote/explain ceremony level (--json)
+  lawbook draft <name>     Scaffold a feature change (--level N, --capability C, --json)
   lawbook draft --bug <c>  Scaffold a bug change (bugfix.md + reports)
   lawbook investigate      Rank bug suspects from graph (--symptom / --stack-trace, --json)
   lawbook validate <c>     Validate a change's artifacts
@@ -115,6 +116,8 @@ function maybeHeader(cmd, flags) {
         return;
     if (cmd === "quick" && flags.json)
         return;
+    if (cmd === "index" && flags.json)
+        return;
     if (cmd === "lawbook" && flags.json && flags._[0] === "level")
         return;
     if (cmd === "lawbook" && flags.json && flags._[0] === "investigate")

package/dist/modules/compass/indexer.js

@@ -212,6 +212,8 @@ export async function buildIndex(projectPath, onProgressOrOpts) {
         removed: 0,
         rootUnchanged: false,
         embedder: embedder.id,
+        totals: { files: 0, nodes: 0, edges: 0 },
+        nextStep: "",
     };
     const cfg = loadAffectedConfig(projectPath);
     const existing = new Map();
@@ -398,6 +400,8 @@ export async function buildIndex(projectPath, onProgressOrOpts) {
         evictCacheBySize(db, maxCacheMB);
         db.prepare("INSERT INTO meta(key, value) VALUES ('indexed_at', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(new Date().toISOString());
         clearNeedsReindex(db);
+        stats.totals = countTotals(db);
+        stats.nextStep = indexNextStep(stats.totals);
         db.exec("COMMIT");
     }
     catch (err) {
@@ -416,6 +420,16 @@ export async function buildIndex(projectPath, onProgressOrOpts) {
     }
     return stats;
 }
+function countTotals(db) {
+    const count = (table) => Number(db.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get().n);
+    return { files: count("files"), nodes: count("nodes"), edges: count("edges") };
+}
+/** Next-step hint printed after an index run; names the query tools, not grep. */
+export function indexNextStep(totals) {
+    const fmt = (n) => n.toLocaleString("en-US");
+    return (`Index ready: ${fmt(totals.files)} files, ${fmt(totals.nodes)} symbols. ` +
+        `Next: compass_find "<concept>" or compass_explore <symbol> — do not grep.`);
+}
 function evictCacheBySize(db, maxCacheMB) {
     const limitBytes = maxCacheMB * 1024 * 1024;
     const row = db

package/dist/modules/compass/query.js

@@ -9,11 +9,16 @@ function requireIndex(projectPath) {
     }
 }
 /**
- * Structural search: find nodes whose name contains `query` (substring match),
- * ranking exact matches and shorter names first.
+ * Structural search: find nodes whose name contains `query`, or whose indexed
+ * file path contains `query`. Exact name matches and shorter names rank first.
+ *
+ * LIKE metacharacters `%` and `_` in `query` are escaped so they match
+ * literally. Name matching stays a substring of the caller's original text;
+ * the path comparison uses a repo-relative normalization (trim, slashes, a
+ * leading `./`, absolute paths under the project root).
  *
  * @param projectPath - Absolute path to the indexed project.
- * @param query - Name or keyword to match as a substring.
+ * @param query - Name substring or file path to match.
  * @param limit - Maximum number of hits to return.
  * @returns Matching nodes ordered by relevance.
  * @throws If no index exists for the project.
@@ -22,13 +27,16 @@ export function search(projectPath, query, limit = 25) {
     requireIndex(projectPath);
     const db = openDb(projectPath);
     try {
+        const normalized = normalizePathQuery(projectPath, query);
+        const pathPattern = normalized ? `%${escapeLike(normalized)}%` : "";
         const rows = db
             .prepare(`SELECT s.name, s.kind, f.path AS file, s.start_line AS line, s.signature
          FROM nodes s JOIN files f ON f.id = s.file_id
-         WHERE s.name LIKE ?
-         ORDER BY (s.name = ?) DESC, length(s.name) ASC
+         WHERE s.name LIKE ? ESCAPE '\\'
+            OR (? != '' AND f.path LIKE ? ESCAPE '\\')
+         ORDER BY (s.name = ?) DESC, length(s.name) ASC, f.path ASC, s.start_line ASC
          LIMIT ?`)
-            .all(`%${query}%`, query, limit);
+            .all(`%${escapeLike(query)}%`, normalized, pathPattern, query, limit);
         return rows;
     }
     finally {
@@ -44,18 +52,205 @@ function readSource(projectPath, file, startByte, endByte) {
         return "";
     }
 }
+/**
+ * Escape SQL `LIKE` metacharacters so `%` and `_` match literally under
+ * `ESCAPE '\'`.
+ */
+function escapeLike(value) {
+    return value.replace(/[\\%_]/g, (ch) => `\\${ch}`);
+}
+/**
+ * Normalize a path-shaped query to a repo-relative slash path.
+ *
+ * Trims, turns backslashes into slashes, and strips one leading `./`. An
+ * absolute path that lies under `projectPath` becomes repo-relative; a path
+ * outside the project is left absolute so it will not match `files.path`.
+ *
+ * @param projectPath - Absolute path to the indexed project.
+ * @param query - Caller-supplied name or path.
+ * @returns The normalized path, or `""` when the query is only the project root.
+ */
+function normalizePathQuery(projectPath, query) {
+    let q = query.trim().split("\\").join("/");
+    if (q.startsWith("./"))
+        q = q.slice(2);
+    if (path.isAbsolute(q)) {
+        const rel = path.relative(path.resolve(projectPath), q).split("\\").join("/");
+        if (rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel)))
+            return rel;
+    }
+    return q;
+}
+/** Indexed paths that equal `query` or end with `/${query}`. Exact row first. */
+function matchingFiles(db, query) {
+    const exact = db.prepare("SELECT path FROM files WHERE path = ?").get(query);
+    const suffix = db
+        .prepare("SELECT path FROM files WHERE path LIKE ? ESCAPE '\\' ORDER BY path")
+        .all(`%/${escapeLike(query)}`);
+    return { exact: exact?.path ?? null, suffix: suffix.map((row) => row.path) };
+}
+/**
+ * Resolve `query` to indexed files after a symbol-name miss.
+ *
+ * Exact `files.path` wins. Otherwise a query that contains `/` must match
+ * exactly one suffix (`path` ends with `/${query}`). A query with no slash
+ * uses the same suffix rule as a basename; more than one file is ambiguous.
+ */
+function resolveIndexedFile(db, projectPath, query) {
+    const normalized = normalizePathQuery(projectPath, query);
+    if (!normalized)
+        return { status: "none" };
+    const { exact, suffix } = matchingFiles(db, normalized);
+    if (exact)
+        return { status: "one", file: exact };
+    if (normalized.includes("/")) {
+        if (suffix.length === 1)
+            return { status: "one", file: suffix[0] };
+        return { status: "none" };
+    }
+    if (suffix.length === 1)
+        return { status: "one", file: suffix[0] };
+    if (suffix.length > 1)
+        return { status: "ambiguous", basename: normalized, files: suffix };
+    return { status: "none" };
+}
+/** Definitions in one indexed file, ordered by source position. */
+function fileSymbols(db, file) {
+    return db
+        .prepare(`SELECT s.id, s.name, s.kind, s.start_line, s.end_line, s.start_byte, s.end_byte,
+              s.signature, f.path AS file
+       FROM nodes s JOIN files f ON f.id = s.file_id
+       WHERE f.path = ?
+       ORDER BY s.start_line ASC, s.id ASC`)
+        .all(file);
+}
+/** Symbols defined in `files`, stable across files. Empty when none exist. */
+function symbolsInFiles(db, files) {
+    if (files.length === 0)
+        return [];
+    const placeholders = files.map(() => "?").join(", ");
+    return db
+        .prepare(`SELECT s.name, s.kind, f.path AS file, s.start_line AS line, s.signature
+       FROM nodes s JOIN files f ON f.id = s.file_id
+       WHERE f.path IN (${placeholders})
+       ORDER BY f.path ASC, s.start_line ASC, s.name ASC`)
+        .all(...files);
+}
+/**
+ * Choose the symbol a file-path explore returns.
+ *
+ * Prefer a symbol whose name equals the file stem, function before class,
+ * then any other kind. Otherwise the first function by `start_line`, then
+ * the first symbol. `symbols` must be non-empty and ordered by `start_line`.
+ */
+function pickPrimary(symbols) {
+    const stem = path.parse(symbols[0].file).name;
+    const named = symbols.filter((s) => s.name === stem);
+    if (named.length > 0) {
+        return (named.find((s) => s.kind === "function") ?? named.find((s) => s.kind === "class") ?? named[0]);
+    }
+    return symbols.find((s) => s.kind === "function") ?? symbols[0];
+}
+/**
+ * Source, callers, and callees for one definition. `others` are the
+ * `otherMatches` (same-name siblings, or the rest of a file).
+ */
+function assembleExplore(db, projectPath, best, others) {
+    const callees = db
+        .prepare(`SELECT e.dst_name AS name, e.line, f.path AS file
+       FROM edges e LEFT JOIN nodes s ON s.id = e.dst_node_id
+       LEFT JOIN files f ON f.id = s.file_id
+       WHERE e.src_node_id = ? AND e.kind = 'call'
+       ORDER BY e.line`)
+        .all(best.id);
+    // Callers: match both the resolved edge AND any call by this name, so
+    // dynamic dispatch (a method/function called by name across sites) is not
+    // missed. Over-approximates conservatively — the point of a blast radius.
+    const callers = db
+        .prepare(`SELECT DISTINCT owner.name AS name, owner.kind AS kind, f.path AS file, e.line
+       FROM edges e
+       JOIN nodes owner ON owner.id = e.src_node_id
+       JOIN files f ON f.id = owner.file_id
+       WHERE (e.dst_node_id = ? OR e.dst_name = ?) AND e.kind = 'call'
+       ORDER BY f.path, e.line`)
+        .all(best.id, best.name);
+    return {
+        found: true,
+        symbol: {
+            name: best.name,
+            kind: best.kind,
+            file: best.file,
+            startLine: best.start_line,
+            endLine: best.end_line,
+            signature: best.signature,
+            source: readSource(projectPath, best.file, best.start_byte, best.end_byte),
+        },
+        callees: callees.map((c) => ({ name: c.name, file: c.file ?? undefined, line: c.line })),
+        callers,
+        otherMatches: others.length > 0
+            ? others.map((m) => ({
+                name: m.name,
+                kind: m.kind,
+                file: m.file,
+                line: m.start_line,
+                signature: m.signature,
+            }))
+            : undefined,
+    };
+}
+/**
+ * Name miss: resolve a file path to one symbol, or list symbols when the
+ * basename is ambiguous or the file defines nothing. A non-unique suffix
+ * falls through to {@link search}, which also matches `files.path`.
+ */
+function exploreWhenNameMisses(db, projectPath, query) {
+    // Covers: req~explore-file-path~1
+    const resolved = resolveIndexedFile(db, projectPath, query);
+    if (resolved.status === "one") {
+        const symbols = fileSymbols(db, resolved.file);
+        if (symbols.length === 0) {
+            const near = search(projectPath, query, 10);
+            return {
+                found: false,
+                message: `Indexed file "${resolved.file}" has no symbols.`,
+                otherMatches: near,
+            };
+        }
+        const primary = pickPrimary(symbols);
+        const result = assembleExplore(db, projectPath, primary, symbols.filter((s) => s.id !== primary.id));
+        return {
+            ...result,
+            message: `Path "${resolved.file}" resolved to ${primary.name}.`,
+        };
+    }
+    if (resolved.status === "ambiguous") {
+        return {
+            found: false,
+            message: `Basename "${resolved.basename}" is ambiguous.`,
+            otherMatches: symbolsInFiles(db, resolved.files),
+        };
+    }
+    const near = search(projectPath, query, 10);
+    return {
+        found: false,
+        message: `No exact symbol named "${query}". ${near.length} similar symbol(s) below.`,
+        otherMatches: near,
+    };
+}
 /**
  * Explore an exact node by name: return its verbatim source, callees, and
  * callers (its blast radius).
  *
  * When several nodes share the name, functions and classes are preferred as the
- * primary result and the rest are surfaced under `otherMatches`. When no exact
- * match exists, falls back to a fuzzy {@link search} so the caller still gets
- * useful candidates.
+ * primary result and the rest are surfaced under `otherMatches`. When the name
+ * misses, a normalized file path (exact, unique suffix, or unique basename)
+ * resolves to one symbol in that file — stem name first (function, then
+ * class), otherwise the first function, otherwise the first symbol. Anything
+ * still unresolved falls back to a fuzzy {@link search}.
  *
  * @param projectPath - Absolute path to the indexed project.
- * @param query - Exact node name to explore.
- * @returns The explore result; `found` is `false` when no exact match exists.
+ * @param query - Exact node name, or a file path when no symbol has that name.
+ * @returns The explore result; `found` is `false` when no single symbol is selected.
  * @throws If no index exists for the project.
  */
 export function explore(projectPath, query) {
@@ -70,57 +265,9 @@ export function explore(projectPath, query) {
          ORDER BY s.kind = 'function' DESC, s.kind = 'class' DESC
          LIMIT 10`)
             .all(query);
-        if (matches.length === 0) {
-            // fall back to fuzzy search so the caller gets something useful
-            const near = search(projectPath, query, 10);
-            return {
-                found: false,
-                message: `No exact symbol named "${query}". ${near.length} similar symbol(s) below.`,
-                otherMatches: near,
-            };
-        }
-        const best = matches[0];
-        const callees = db
-            .prepare(`SELECT e.dst_name AS name, e.line, f.path AS file
-         FROM edges e LEFT JOIN nodes s ON s.id = e.dst_node_id
-         LEFT JOIN files f ON f.id = s.file_id
-         WHERE e.src_node_id = ? AND e.kind = 'call'
-         ORDER BY e.line`)
-            .all(best.id);
-        // Callers: match both the resolved edge AND any call by this name, so
-        // dynamic dispatch (a method/function called by name across sites) is not
-        // missed. Over-approximates conservatively — the point of a blast radius.
-        const callers = db
-            .prepare(`SELECT DISTINCT owner.name AS name, owner.kind AS kind, f.path AS file, e.line
-         FROM edges e
-         JOIN nodes owner ON owner.id = e.src_node_id
-         JOIN files f ON f.id = owner.file_id
-         WHERE (e.dst_node_id = ? OR e.dst_name = ?) AND e.kind = 'call'
-         ORDER BY f.path, e.line`)
-            .all(best.id, best.name);
-        return {
-            found: true,
-            symbol: {
-                name: best.name,
-                kind: best.kind,
-                file: best.file,
-                startLine: best.start_line,
-                endLine: best.end_line,
-                signature: best.signature,
-                source: readSource(projectPath, best.file, best.start_byte, best.end_byte),
-            },
-            callees: callees.map((c) => ({ name: c.name, file: c.file ?? undefined, line: c.line })),
-            callers,
-            otherMatches: matches.length > 1
-                ? matches.slice(1).map((m) => ({
-                    name: m.name,
-                    kind: m.kind,
-                    file: m.file,
-                    line: m.start_line,
-                    signature: m.signature,
-                }))
-                : undefined,
-        };
+        if (matches.length === 0)
+            return exploreWhenNameMisses(db, projectPath, query);
+        return assembleExplore(db, projectPath, matches[0], matches.slice(1));
     }
     finally {
         db.close();

package/dist/modules/compass/register.js

@@ -3,6 +3,7 @@ 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 { recordCompassCall } from "../../shared/compass-calls.js";
 import { buildIndex } from "./indexer.js";
 import { impact } from "./query.js";
 import { affectedTests } from "./affected.js";
@@ -17,7 +18,14 @@ export function registerCompass(server, opts = {}) {
     const add = (name, description, inputSchema, handler) => {
         if (!shouldExpose(name, minimal))
             return;
-        defineTool(server, { name, description, inputSchema, handler });
+        // Every canonical call lands in the call log the Cortex gate and the
+        // Compass-first nudge read; the write is best-effort and never throws.
+        const call = handler;
+        const logged = ((args, extra) => {
+            recordCompassCall(args.projectPath, name);
+            return call(args, extra);
+        });
+        defineTool(server, { name, description, inputSchema, handler: logged });
     };
     add("compass_explore", "Symbol context in one call: source, callers, callees, blast radius, tests, hotspot. Prefer before grep.", {
         projectPath: z.string(),
@@ -85,6 +93,7 @@ export function registerCompass(server, opts = {}) {
         inputSchema: { projectPath: z.string(), query: z.string(), limit: z.number().optional() },
         handler: async ({ projectPath, query, limit }) => {
             logDeprecatedCall(projectPath, "compass_search");
+            recordCompassCall(projectPath, "compass_search");
             const body = JSON.stringify(await findSymbols(projectPath, query, "exact", limit), null, 2);
             return text(prefixDeprecated("compass_search", body));
         },
@@ -95,6 +104,7 @@ export function registerCompass(server, opts = {}) {
         inputSchema: { projectPath: z.string(), query: z.string(), limit: z.number().optional() },
         handler: async ({ projectPath, query, limit }) => {
             logDeprecatedCall(projectPath, "compass_recall");
+            recordCompassCall(projectPath, "compass_recall");
             const body = JSON.stringify(await findSymbols(projectPath, query, "concept", limit), null, 2);
             return text(prefixDeprecated("compass_recall", body));
         },
@@ -111,6 +121,7 @@ export function registerCompass(server, opts = {}) {
         },
         handler: async (args) => {
             logDeprecatedCall(args.projectPath, "compass_impact");
+            recordCompassCall(args.projectPath, "compass_impact");
             const sym = args.symbol ?? args.node;
             const body = sym
                 ? JSON.stringify(await exploreRich({
@@ -133,6 +144,7 @@ export function registerCompass(server, opts = {}) {
         },
         handler: async ({ projectPath, from, to, maxDepth }) => {
             logDeprecatedCall(projectPath, "compass_trace");
+            recordCompassCall(projectPath, "compass_trace");
             const body = JSON.stringify(await exploreRich({ projectPath, node: from, to, maxDepth }), null, 2);
             return text(prefixDeprecated("compass_trace", body));
         },
@@ -148,6 +160,7 @@ export function registerCompass(server, opts = {}) {
         },
         handler: async (args) => {
             logDeprecatedCall(args.projectPath, "compass_affected_tests");
+            recordCompassCall(args.projectPath, "compass_affected_tests");
             const body = JSON.stringify(affectedTests(args.projectPath, args), null, 2);
             return text(prefixDeprecated("compass_affected_tests", body));
         },
@@ -158,6 +171,7 @@ export function registerCompass(server, opts = {}) {
         inputSchema: { projectPath: z.string(), limit: z.number().optional() },
         handler: async ({ projectPath, limit }) => {
             logDeprecatedCall(projectPath, "compass_hotspots");
+            recordCompassCall(projectPath, "compass_hotspots");
             const body = JSON.stringify(hotspots(projectPath, { limit }), null, 2);
             return text(prefixDeprecated("compass_hotspots", body));
         },
@@ -168,6 +182,7 @@ export function registerCompass(server, opts = {}) {
         inputSchema: { projectPath: z.string(), file: z.string() },
         handler: async ({ projectPath, file }) => {
             logDeprecatedCall(projectPath, "compass_coupling");
+            recordCompassCall(projectPath, "compass_coupling");
             const body = JSON.stringify(coupling(projectPath, file, {}), null, 2);
             return text(prefixDeprecated("compass_coupling", body));
         },
@@ -181,6 +196,7 @@ export function registerCompass(server, opts = {}) {
         },
         handler: async ({ projectPath, action }) => {
             logDeprecatedCall(projectPath, "compass_watch");
+            recordCompassCall(projectPath, "compass_watch");
             const result = action === "start"
                 ? startWatch(projectPath)
                 : action === "stop"