@esneiderbravo/speclaw 0.3.12 → 0.4.0

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)));
+        },
+    });
 }

package/dist/modules/foundation/context-budget.js

@@ -1,22 +1,12 @@
-import { z } from "zod";
 import { registerCompass } from "../compass/register.js";
 import { registerSpec } from "../lawbook/register.js";
 import { registerTools } from "../tools/register.js";
 import { registerFoundationCore } from "./register-core.js";
 import { measureBudget } from "../../shared/budget.js";
-import { isMinimalMode, packageRoot, shouldExpose } from "../../shared/exposure.js";
-/** Mirrors the `doctor` tool surface without importing `doctor.ts` (avoids a cycle). */
-const DOCTOR_TOOL_FOR_BUDGET = {
-    name: "doctor",
-    description: "Verify the speclaw install; returns a versioned DoctorReport (schemaVersion 1).",
-    inputSchema: { projectPath: z.string() },
-};
+import { isMinimalMode, packageRoot } from "../../shared/exposure.js";
 /**
  * Collect tool definitions as the MCP server would register them for a profile.
  *
- * Uses `registerFoundationCore` plus a static `doctor` stub so budget/doctor
- * measurement never imports the live `doctor` implementation (module cycle).
- *
  * @param minimal - Exposure profile.
  */
 export function collectRegisteredTools(minimal) {
@@ -33,9 +23,6 @@ export function collectRegisteredTools(minimal) {
     const opts = { minimal };
     const stub = server;
     registerFoundationCore(stub, opts);
-    if (shouldExpose("doctor", minimal)) {
-        tools.push(DOCTOR_TOOL_FOR_BUDGET);
-    }
     registerSpec(stub, opts);
     registerCompass(stub, opts);
     registerTools(stub, opts);

package/dist/modules/foundation/doctor.js

@@ -11,6 +11,8 @@ import { doctorDriftCheck } from "../lawbook/drift.js";
 import { loadCeremonyConfig } from "../lawbook/levels.js";
 import { globError, hasBackend, hasBatchBackend, readLawManifest } from "./laws.js";
 import { redactValue } from "../../shared/redact.js";
+import { readDeprecatedCallCounts, scanRetiredToolReferences } from "../../shared/deprecation.js";
+import { CANONICAL_TOOLS, ALIAS_TARGETS, isCanonicalTool } from "../../shared/tool-catalog.js";
 const STATUS_RANK = {
     skip: 0,
     ok: 1,
@@ -397,6 +399,48 @@ async function budgetCheck(projectPath) {
         };
     }
 }
+async function toolSurfaceCheck(projectPath) {
+    try {
+        const { measureInstallBudget, collectRegisteredTools } = await import("./context-budget.js");
+        const full = measureInstallBudget(projectPath, false);
+        const mini = measureInstallBudget(projectPath, true);
+        const canonicalCount = collectRegisteredTools(false).filter((t) => isCanonicalTool(t.name)).length;
+        const deprecated = readDeprecatedCallCounts(projectPath);
+        const aliasDetail = deprecated.size > 0
+            ? [...deprecated.entries()]
+                .map(([alias, n]) => `${alias}→${ALIAS_TARGETS[alias] ?? "?"} (${n}×)`)
+                .join("; ")
+            : "no deprecated alias calls logged";
+        const staleRefs = scanRetiredToolReferences(projectPath);
+        const staleDetail = staleRefs.length > 0
+            ? `retired names in: ${[...new Set(staleRefs.map((r) => `${r.file} (${r.alias}→${r.replacement})`))].join("; ")}`
+            : undefined;
+        return {
+            id: "cfg.tool-surface",
+            title: "MCP tool surface",
+            status: staleRefs.length > 0 ? "warn" : "ok",
+            value: canonicalCount,
+            detail: [
+                `${canonicalCount}/${CANONICAL_TOOLS.length} canonical tools`,
+                `~${full.tools} tool-definition tokens (full), ~${mini.tools} (minimal)`,
+                aliasDetail,
+                staleDetail,
+            ]
+                .filter(Boolean)
+                .join(" · "),
+            remedy: staleRefs.length > 0 ? "speclaw update" : undefined,
+        };
+    }
+    catch (err) {
+        return {
+            id: "cfg.tool-surface",
+            title: "MCP tool surface",
+            status: "skip",
+            detail: `could not measure: ${err.message}`,
+            remedy: "speclaw budget",
+        };
+    }
+}
 function freshnessCheck(projectPath) {
     if (!indexExists(projectPath)) {
         return {
@@ -527,6 +571,37 @@ function ceremonyChecks(projectPath) {
             ? "no archived changes"
             : `archived levels: 0=${counts["0"]}, 1=${counts["1"]}, 2=${counts["2"]}, 3=${counts["3"]} (missing change.json=${counts.missing})`,
     });
+    const typeCounts = { feature: 0, bug: 0, unknown: 0 };
+    if (fs.existsSync(archiveRoot)) {
+        for (const name of fs.readdirSync(archiveRoot)) {
+            const dir = path.join(archiveRoot, name);
+            if (!fs.statSync(dir).isDirectory())
+                continue;
+            try {
+                const p = path.join(dir, "change.json");
+                if (!fs.existsSync(p)) {
+                    typeCounts.unknown += 1;
+                    typeCounts.feature += 1;
+                    continue;
+                }
+                const raw = JSON.parse(fs.readFileSync(p, "utf8"));
+                if (raw.changeType === "bug")
+                    typeCounts.bug += 1;
+                else
+                    typeCounts.feature += 1;
+            }
+            catch {
+                typeCounts.unknown += 1;
+            }
+        }
+    }
+    out.push({
+        id: "cfg.ceremony.changeTypes",
+        title: "change type distribution",
+        status: "ok",
+        value: JSON.stringify(typeCounts),
+        detail: `archived types: feature=${typeCounts.feature}, bug=${typeCounts.bug}`,
+    });
     return out;
 }
 function configurationChecks(projectPath, initialised) {
@@ -538,6 +613,7 @@ function configurationChecks(projectPath, initialised) {
             "cfg.hooks",
             "cfg.laws",
             "cfg.budget",
+            "cfg.tool-surface",
             "cfg.index.freshness",
             "cfg.specs.orphans",
         ];
@@ -619,6 +695,7 @@ export async function doctor(projectPath, opts = {}) {
     const configuration = configurationChecks(projectPath, initialised);
     if (initialised) {
         configuration.push(await budgetCheck(projectPath));
+        configuration.push(await toolSurfaceCheck(projectPath));
         configuration.push(freshnessCheck(projectPath));
         configuration.push(specsOrphansCheck(projectPath));
         configuration.push(...ceremonyChecks(projectPath));

package/dist/modules/foundation/register-core.js

@@ -1,54 +1,10 @@
 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 { scaffold } from "./scaffold.js";
+import { aliasesEnabled } from "../../shared/tool-catalog.js";
+import { logDeprecatedCall, prefixDeprecated } from "../../shared/deprecation.js";
 import { checkAction } from "./check.js";
-import { verifyLaws } from "./verify.js";
-import { loadPacks } from "../tools/packs.js";
-import { AGENTS, configureAgent } from "../../shared/agents.js";
-import { emptyReport } from "../../shared/install.js";
-/** Human help text for init_project's questionnaire (not embedded in MCP schemas). */
-const profileFieldHelp = {
-    project_name: "Short project name, e.g. the repo name",
-    project_description: "One-line description of what the project does",
-    organization: "Company/team name",
-    stack_summary: "e.g. 'Next.js 15 + TypeScript frontend, FastAPI + PostgreSQL backend'",
-    architecture: "e.g. 'hexagonal architecture with bounded contexts'",
-    test_commands: "Real commands, e.g. 'pytest backend/tests && npm run test'",
-    lint_commands: "Real commands, e.g. 'ruff check . && npm run lint && tsc --noEmit'",
-    branch_pattern: "e.g. 'feature/<ticket-id>-<slug>'",
-    commit_style: "e.g. 'conventional commits, imperative, English'",
-    custom_laws: "Extra markdown for LAWS.md — project-specific binding rules",
-    compass_hints: "Markdown bullets with real entrypoints for docs/compass.md",
-    base_standards_extra: "Extra cross-cutting rules for base-standards.md",
-    modules_table: "Markdown table of modules/bounded contexts",
-    layering_rules: "Layers and allowed dependencies for architecture.md",
-    backend_layers: "Backend layer table for backend-standards.md",
-    frontend_layers: "Frontend layer table for frontend-standards.md",
-    versioning_rules: "Versioning/release convention for conventions.md",
-    documentation_extra: "Repo-specific docstring notes for documentation.md",
-};
-/** Lean Zod shape for scaffold — no .describe() text (that cost rides in every request). */
-const profileShape = {
-    project_name: z.string(),
-    project_description: z.string().optional(),
-    organization: z.string().optional(),
-    stack_summary: z.string().optional(),
-    architecture: z.string().optional(),
-    test_commands: z.string().optional(),
-    lint_commands: z.string().optional(),
-    branch_pattern: z.string().optional(),
-    commit_style: z.string().optional(),
-    custom_laws: z.string().optional(),
-    compass_hints: z.string().optional(),
-    base_standards_extra: z.string().optional(),
-    modules_table: z.string().optional(),
-    layering_rules: z.string().optional(),
-    backend_layers: z.string().optional(),
-    frontend_layers: z.string().optional(),
-    versioning_rules: z.string().optional(),
-    documentation_extra: z.string().optional(),
-};
+import { handleSpeclawSetup, speclawSetupSchema } from "./setup-tool.js";
 function makeAdd(server, minimal) {
     return (name, description, inputSchema, handler) => {
         if (!shouldExpose(name, minimal))
@@ -57,52 +13,65 @@ function makeAdd(server, minimal) {
     };
 }
 /**
- * Foundation tools except `doctor`. Lives in a separate file so budget/doctor
- * measurement can import it without forming a file-level SCC through
- * `register.ts` → `doctor.ts` → `context-budget.ts`.
+ * Foundation MCP tools (setup + hook check). `doctor` and `law_verify` are CLI-only.
+ * `scaffold` is CLI-only after tool-surface consolidation.
  */
 export function registerFoundationCore(server, opts = {}) {
-    const add = makeAdd(server, Boolean(opts.minimal));
-    add("init_project", "Start here to initialize speclaw: returns the analysis questionnaire and packs.", { projectPath: z.string() }, async () => {
-        const packs = loadPacks();
-        return text({
-            instructions: [
-                "1. Analyze the repository at projectPath and fill in every profile field below with REAL values from the codebase (read package.json / pyproject.toml / CI configs / README — do not invent).",
-                "2. The foundation is a set of GRANULAR standards under docs/standards/ (base, architecture, backend, frontend, testing, conventions, lawbook), bound by LAWS.md and referenced from CLAUDE.md/AGENTS.md. Fill their structured fields from the real repo: modules_table and layering_rules (architecture), backend_layers, frontend_layers, versioning_rules, and any base_standards_extra. Omit a field only when that standard genuinely doesn't apply to this stack.",
-                "3. Suggest packs: add stack packs whose 'detect' hints match dependencies you found; offer the rest. Ask the user which packs to install (the lawbook workflow is always installed).",
-                "4. Infer the working language and the branch/commit/tracker conventions from the repo itself — the language already used in docstrings, commit messages, branch names, and PR/ticket bodies. Do NOT ask the user or assume English; match what the repo does, and set branch_pattern/commit_style accordingly. speclaw does not prescribe a ticket tool — leave tracker linkage to the team's own convention.",
-                "5. Draft any custom_laws (extra binding rules for LAWS.md) from conventions you observed that the standard set doesn't cover.",
-                "6. Call the 'scaffold' tool with { projectPath, profile, packs }.",
-                "7. Follow the nextSteps returned by scaffold: complete the HTML-comment sections still left in docs/standards/*, then run the lawbook_init and compass_index tools (both built into speclaw — no external installs).",
-            ],
-            profileFields: profileFieldHelp,
-            packs,
-        });
-    });
-    add("scaffold", "Write foundation, lawbook workflow, packs, IDE symlinks, and .mcp.json. Never overwrites.", {
-        projectPath: z.string(),
-        profile: z.object(profileShape),
-        packs: z.array(z.string()),
-        agents: z.array(z.string()).optional(),
-    }, async ({ projectPath, profile, packs, agents }) => text(scaffold(projectPath, profile, packs, agents ?? [])));
-    add("configure_agent", "Add one agent's IDE symlinks and MCP config to an already-scaffolded project.", {
-        projectPath: z.string(),
-        agent: z.enum(AGENTS.map((a) => a.id)),
-    }, async ({ projectPath, agent }) => {
-        const report = emptyReport();
-        configureAgent(projectPath, agent, report);
-        return text(report);
-    });
+    const minimal = Boolean(opts.minimal);
+    const add = makeAdd(server, minimal);
+    add("speclaw_setup", "Project setup: init questionnaire, configure agent, list or add packs.", speclawSetupSchema, async (args) => text(handleSpeclawSetup(args)));
     add("speclaw_check", "Invoked by speclaw's hooks to enforce laws — do not call directly.", {
         projectPath: z.string(),
         event: z.enum(["PreToolUse", "PostToolUse", "Stop", "InstructionsLoaded"]),
         toolName: z.string().optional(),
         payload: z.record(z.unknown()),
     }, async ({ projectPath, event, toolName, payload }) => text(checkAction({ projectPath, event: event, toolName, payload })));
-    add("law_verify", "Verify deterministic deps/graph laws and return violations by file.", {
-        projectPath: z.string(),
-        paths: z.array(z.string()).optional(),
-        engines: z.array(z.enum(["deps", "graph"])).optional(),
-        lawIds: z.array(z.string()).optional(),
-    }, async ({ projectPath, paths, engines, lawIds }) => text(verifyLaws({ projectPath, paths, engines: engines, lawIds })));
+    if (minimal || !aliasesEnabled())
+        return;
+    defineAliasTool(server, {
+        name: "init_project",
+        description: "Deprecated alias for speclaw_setup action init.",
+        inputSchema: { projectPath: z.string() },
+        handler: async ({ projectPath }) => {
+            logDeprecatedCall(projectPath, "init_project");
+            const body = JSON.stringify(handleSpeclawSetup({ projectPath, action: "init" }), null, 2);
+            return text(prefixDeprecated("init_project", body));
+        },
+    });
+    defineAliasTool(server, {
+        name: "configure_agent",
+        description: "Deprecated alias for speclaw_setup configure-agent.",
+        inputSchema: {
+            projectPath: z.string(),
+            agent: z.string(),
+        },
+        handler: async ({ projectPath, agent }) => {
+            logDeprecatedCall(projectPath, "configure_agent");
+            const body = JSON.stringify(handleSpeclawSetup({ projectPath, action: "configure-agent", agent }), null, 2);
+            return text(prefixDeprecated("configure_agent", body));
+        },
+    });
+    defineAliasTool(server, {
+        name: "list_packs",
+        description: "Deprecated alias for speclaw_setup list-packs.",
+        inputSchema: {},
+        handler: async () => {
+            const body = JSON.stringify(handleSpeclawSetup({ projectPath: ".", action: "list-packs" }), null, 2);
+            return text(prefixDeprecated("list_packs", body));
+        },
+    });
+    defineAliasTool(server, {
+        name: "add_pack",
+        description: "Deprecated alias for speclaw_setup add-pack.",
+        inputSchema: {
+            projectPath: z.string(),
+            pack: z.string(),
+            vars: z.record(z.string()).optional(),
+        },
+        handler: async ({ projectPath, pack, vars }) => {
+            logDeprecatedCall(projectPath, "add_pack");
+            const body = JSON.stringify(handleSpeclawSetup({ projectPath, action: "add-pack", pack, vars }), null, 2);
+            return text(prefixDeprecated("add_pack", body));
+        },
+    });
 }

package/dist/modules/foundation/register.js

@@ -1,26 +1,6 @@
-import { z } from "zod";
-import { defineTool, text } from "../../shared/mcp.js";
-import { shouldExpose } from "../../shared/exposure.js";
 import { registerFoundationCore } from "./register-core.js";
 export { registerFoundationCore } from "./register-core.js";
-const DOCTOR_DESCRIPTION = "Verify the speclaw install; returns a versioned DoctorReport (schemaVersion 1).";
-/** Register foundation MCP tools (core + doctor). */
+/** Register foundation MCP tools. Doctor is CLI-only (`speclaw doctor`). */
 export function registerFoundation(server, opts = {}) {
     registerFoundationCore(server, opts);
-    const minimal = Boolean(opts.minimal);
-    if (!shouldExpose("doctor", minimal))
-        return;
-    const inputSchema = { projectPath: z.string() };
-    const handler = async ({ projectPath }) => {
-        // Lazy load: register.ts must stay out of the context-budget → doctor SCC.
-        const { doctor } = await import("./doctor.js");
-        const report = await doctor(projectPath, { redact: true });
-        return text(report);
-    };
-    defineTool(server, {
-        name: "doctor",
-        description: DOCTOR_DESCRIPTION,
-        inputSchema,
-        handler,
-    });
 }