@esneiderbravo/speclaw 0.3.12 → 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/lawbook.js

@@ -1,5 +1,7 @@
 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 { investigate, formatInvestigateResult } from "../../modules/lawbook/investigate.js";
 import { list } from "../lib/args.js";
 import { ui } from "../lib/ui.js";
 function today() {
@@ -89,6 +91,45 @@ export async function runSpec(flags) {
                 r.promoted.forEach((p) => ui.info(`${r.created.includes(p) ? "created" : "updated"}: ${p}`));
                 return;
             }
+            case "investigate": {
+                const stackTrace = typeof flags["stack-trace"] === "string"
+                    ? flags["stack-trace"]
+                    : typeof flags.stackTrace === "string"
+                        ? flags.stackTrace
+                        : undefined;
+                const symptom = typeof flags.symptom === "string" ? flags.symptom : undefined;
+                const result = await investigate({
+                    projectPath: cwd,
+                    stackTrace,
+                    symptom,
+                    hintPaths: list(flags.path),
+                    maxSuspects: flags.max !== undefined && flags.max !== true ? Number(flags.max) : undefined,
+                });
+                if (flags.json) {
+                    console.log(formatInvestigateResult(result));
+                    return;
+                }
+                console.log(formatInvestigateResult(result));
+                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 });
+                if (flags.json) {
+                    console.log(JSON.stringify(result, null, 2));
+                    return;
+                }
+                ui.ok(`bug change "${name}" scaffolded at ${result.dir}`);
+                return;
+            }
             case "archive": {
                 const r = specArchive(cwd, req(change, "lawbook archive <change>"), today());
                 ui.ok(`archived to ${r.archivedTo} (${r.promoted.length} spec(s) promoted)`);
@@ -103,7 +144,7 @@ export async function runSpec(flags) {
                 return;
             }
             default:
-                ui.err("Usage: speclaw lawbook <init|list|validate|sync|archive|level> [change]");
+                ui.err("Usage: speclaw lawbook <init|list|validate|sync|archive|level|draft|investigate> [change]");
                 process.exit(1);
         }
     }

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

@@ -135,6 +135,16 @@ const MIGRATIONS = [
             "docs/standards/lawbook.md wording if the project still says every change needs all four artifacts.\n" +
             "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
     },
+    {
+        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.",
+    },
 ];
 /**
  * Update speclaw and bring the current project up to date without a full re-init:

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
@@ -35,6 +36,8 @@ 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 --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
   lawbook sync <c>         Promote delta specs to canonical
   lawbook archive <c>      Finalize and archive a change
@@ -102,6 +105,10 @@ function maybeHeader(cmd, flags) {
         return;
     if (cmd === "lawbook" && flags.json && flags._[0] === "level")
         return;
+    if (cmd === "lawbook" && flags.json && flags._[0] === "investigate")
+        return;
+    if (cmd === "lawbook" && flags.json && flags._[0] === "draft")
+        return;
     header();
 }
 /** Run the handler for a single command. Returns when the command completes. */
@@ -138,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,
+    };
+}