@esneiderbravo/speclaw 0.3.4 → 0.3.5

package/README.md

@@ -91,6 +91,30 @@ Compass is inspired by [CodeGraph](https://github.com/colbymchenry/codegraph) an
 
 <br/>
 
+## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; Context cost
+
+speclaw publishes and **gates** its own always-on context cost. Measured with a
+deterministic offline estimator (`speclaw/estimate-v1`, about ±8% vs Anthropic's
+tokenizer on this corpus — not a BPE dependency):
+
+| | Tokens |
+| :-- | --: |
+| **speclaw budget (always-on)** | **~11.7k** (budget ceiling **13.0k**) |
+| Spec Kit commands alone | ~18.6k ([spec-kit#1401](https://github.com/github/spec-kit/issues/1401)) |
+
+```bash
+speclaw budget          # human table
+speclaw budget --json   # machine-readable; used by the suite gate
+speclaw init --minimal  # omit setup/lifecycle MCP tools from registration
+```
+
+Raising a number in committed `token-budget.json` is a reviewable PR. Optional
+calibration (never CI): `npm run budget:calibrate` with `ANTHROPIC_API_KEY`.
+MCP servers cannot mark tools `defer_loading` — savings come from shorter
+definitions, omitted registration (`--minimal`), and JIT skill steps.
+
+<br/>
+
 ## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; The spec-driven workflow (Lawbook)
 
 Lawbook is speclaw's answer to the biggest risk with AI agents: **code that

package/dist/cli/commands/budget.js

@@ -0,0 +1,36 @@
+import { ui } from "../lib/ui.js";
+import { formatBudgetTable } from "../../shared/budget.js";
+import { loadDeclaredBudget } from "../../shared/exposure.js";
+import { measureInstallBudget } from "../../modules/foundation/context-budget.js";
+/** Print the context-budget table or JSON. */
+export async function runBudget(flags) {
+    const cwd = process.cwd();
+    const minimal = flags.minimal === true ? true : flags.minimal === false ? false : undefined;
+    const measurement = measureInstallBudget(cwd, minimal);
+    const declared = loadDeclaredBudget();
+    if (flags.json) {
+        console.log(JSON.stringify({
+            schemaVersion: 1,
+            profile: measurement.profile,
+            tools: measurement.tools,
+            skillsAndCommands: measurement.skillsAndCommands,
+            alwaysOnInstructions: measurement.alwaysOnInstructions,
+            pathScoped: measurement.pathScoped,
+            total: measurement.total,
+            toolCount: measurement.toolCount,
+            declared: {
+                tools: declared.surfaces.tools,
+                skillsAndCommands: declared.surfaces.skillsAndCommands,
+                alwaysOnInstructions: declared.surfaces.alwaysOnInstructions,
+                total: measurement.profile === "minimal" ? declared.minimal.total : declared.total,
+            },
+            details: measurement.details,
+        }, null, 2));
+        return;
+    }
+    ui.heading("speclaw budget");
+    console.log(formatBudgetTable(measurement, declared));
+    ui.plain();
+    ui.info(`profile: ${measurement.profile} · tools registered: ${measurement.toolCount}`);
+    ui.info("Spec Kit (commands only), for comparison: ~18,600 — github/spec-kit#1401");
+}

package/dist/cli/commands/doctor.js

@@ -1,8 +1,10 @@
 import { doctor } from "../../modules/foundation/doctor.js";
+import { measureInstallBudget } from "../../modules/foundation/context-budget.js";
 import { ui } from "../lib/ui.js";
 /** Verify the installation, printing each check and exiting non-zero on failure. */
 export async function runDoctor(_flags) {
-    const checks = doctor(process.cwd());
+    const cwd = process.cwd();
+    const checks = doctor(cwd);
     ui.heading("speclaw doctor");
     for (const c of checks) {
         if (c.ok)
@@ -10,6 +12,14 @@ export async function runDoctor(_flags) {
         else
             ui.err(`${c.name} — ${c.detail}`);
     }
+    try {
+        const m = measureInstallBudget(cwd);
+        ui.ok(`context budget — profile ${m.profile} · ${m.toolCount} tools · ~${m.total} always-on tokens ` +
+            `(A ${m.tools} · B ${m.skillsAndCommands} · C ${m.alwaysOnInstructions}; D path-scoped ${m.pathScoped} not in total)`);
+    }
+    catch (err) {
+        ui.warn(`context budget — could not measure: ${err.message}`);
+    }
     const failed = checks.filter((c) => !c.ok).length;
     ui.plain();
     if (failed === 0)

package/dist/cli/commands/init.js

@@ -87,7 +87,9 @@ export async function runInit(flags) {
     if (reinit) {
         ui.info("speclaw is already set up here — your existing files are kept; only missing pieces are added.");
     }
-    const report = scaffold(cwd, profile, packs, agents);
+    const report = scaffold(cwd, profile, packs, agents, {
+        minimal: Boolean(flags.minimal),
+    });
     ui.ok(`Foundation ${c.muted("— LAWS.md + 8 standards + CLAUDE.md/AGENTS.md")}`);
     ui.ok(`Lawbook workflow ${c.muted("— draft · build · sync · archive · explore")}`);
     for (const p of packs)

package/dist/cli/commands/update.js

@@ -67,6 +67,18 @@ const MIGRATIONS = [
             "required status check in branch protection. speclaw never enables that itself.\n" +
             "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
     },
+    {
+        version: "0.3.5",
+        describe: "Context budget: compact map markers and budget-aware agent contracts",
+        agentPrompt: "- In docs/compass.md, ensure the markers `<!-- speclaw:map:start -->` and " +
+            "`<!-- speclaw:map:end -->` exist (usually just above 'Project-specific starting points') " +
+            "so `compass_index` can regenerate the compact project map between them. Do not hand-edit " +
+            "the content between the markers.\n" +
+            "- Optionally note in CLAUDE.md / AGENTS.md that `speclaw budget` reports always-on context " +
+            "cost and that `speclaw init --minimal` / `SPECLAW_MINIMAL=1` omit setup MCP tools " +
+            "(no server-side defer_loading).\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:
@@ -108,7 +120,12 @@ export async function runUpdate(flags) {
             // Re-exec the NEWLY installed binary so migrations run with the new assets
             // and any new feature steps — not this (now-stale) process. Carry --backup
             // through so the refresh honors it after the upgrade.
-            const reArgs = ["update", "--migrate-only", ...(backup ? ["--backup"] : [])];
+            const reArgs = [
+                "update",
+                "--migrate-only",
+                ...(backup ? ["--backup"] : []),
+                ...(flags.minimal ? ["--minimal"] : []),
+            ];
             const re = spawnSync("speclaw", reArgs, {
                 stdio: "inherit",
                 shell: winShell,
@@ -125,7 +142,7 @@ export async function runUpdate(flags) {
                 return;
         }
     }
-    applyProjectMigrations(cwd, backup);
+    applyProjectMigrations(cwd, backup, flags.minimal ? true : undefined);
 }
 /**
  * Additively apply the current version's content and feature steps to a project.
@@ -135,8 +152,10 @@ export async function runUpdate(flags) {
  * @param backup - When true, a locally edited managed file is copied to
  *   `<file>.bak` before it is refreshed; the default overwrites it in place
  *   (recoverable from git) and only reports the overwrite.
+ * @param minimal - When true, persist minimal exposure; when undefined, keep
+ *   the manifest's existing value.
  */
-function applyProjectMigrations(cwd, backup) {
+function applyProjectMigrations(cwd, backup, minimal) {
     const initialized = fs.existsSync(path.join(cwd, "ai-specs")) || fs.existsSync(path.join(cwd, "LAWS.md"));
     if (!initialized) {
         ui.step("Project");
@@ -154,6 +173,7 @@ function applyProjectMigrations(cwd, backup) {
     const report = scaffold(cwd, { project_name: detectProjectName(cwd) }, packs, agents, {
         refreshManaged: true,
         backup,
+        ...(minimal !== undefined ? { minimal } : {}),
     });
     const changed = report.written.filter((w) => !w.includes(".gitignore"));
     if (changed.length) {

package/dist/cli/index.js

@@ -11,7 +11,9 @@ Install globally so the command is always available:
 
 Setup
   init                     Interactive setup: pick agents, scaffold, index, get the prompt
+                           (--minimal omits setup/lifecycle MCP tools)
   update                   Upgrade speclaw and apply only what's new (no re-init)
+                           (--minimal persists minimal exposure; omit to keep prior)
   agent list               Show which agents are configured
   agent add <id>           Configure another agent later (symlinks + MCP)
 
@@ -34,6 +36,7 @@ Lawbook (spec-driven workflow)
 
 Other
   doctor                   Verify the installation
+  budget                   Measure always-on context cost (tools, skills, instructions)
   check                    Evaluate an action against the laws (hooks call this; --dry-run to preview)
   laws verify              Verify the deterministic dependency/graph laws against the index
   verify                   Verify laws for CI: exit codes, --sarif, --json, --strict-engines
@@ -55,6 +58,7 @@ const HEADER_COMMANDS = new Set([
     "update",
     "agent",
     "doctor",
+    "budget",
     "index",
     "watch",
     "lawbook",
@@ -64,13 +68,15 @@ const HEADER_COMMANDS = new Set([
  * header-eligible command AND stdout is an interactive terminal (so pipes,
  * redirection, and CI stay clean — mirroring the color gate in `ui.ts`). A
  * forced-color signal counts as interactive so the header is exercisable in a
- * child process.
+ * child process. `budget --json` is machine-consumed and suppresses the header.
  */
-function maybeHeader(cmd) {
+function maybeHeader(cmd, flags) {
     if (!process.stdout.isTTY && process.env.FORCE_COLOR !== "1")
         return;
     if (!HEADER_COMMANDS.has(cmd))
         return;
+    if (cmd === "budget" && flags.json)
+        return;
     header();
 }
 /** Run the handler for a single command. Returns when the command completes. */
@@ -113,6 +119,8 @@ async function dispatch(cmd, flags) {
             return (await import("./commands/lawbook.js")).runSpec(flags);
         case "doctor":
             return (await import("./commands/doctor.js")).runDoctor(flags);
+        case "budget":
+            return (await import("./commands/budget.js")).runBudget(flags);
         case "check":
             return (await import("./commands/check.js")).runCheck(flags);
         case "laws":
@@ -129,7 +137,7 @@ async function dispatch(cmd, flags) {
 async function main() {
     const [cmd, ...rest] = process.argv.slice(2);
     const flags = parseFlags(rest);
-    maybeHeader(cmd);
+    maybeHeader(cmd, flags);
     await dispatch(cmd, flags);
     await maybeNotifyUpdate(cmd);
 }

package/dist/modules/compass/indexer.js

@@ -9,6 +9,7 @@ const SKIP_DIRS = new Set([
     ".git",
     "node_modules",
     "dist",
+    "dist-test",
     "build",
     ".next",
     "out",
@@ -173,5 +174,13 @@ export async function buildIndex(projectPath, onProgress) {
     finally {
         db.close();
     }
+    // Compact map in committed docs/compass.md (between markers) — zero tool-call cost.
+    try {
+        const { writeCompactMap } = await import("./map.js");
+        writeCompactMap(projectPath);
+    }
+    catch {
+        // Map generation must never fail an index run.
+    }
     return stats;
 }

package/dist/modules/compass/map.js

@@ -0,0 +1,114 @@
+import fs from "node:fs";
+import path from "node:path";
+import { openDb } from "./db.js";
+import { estimateTokens } from "../../shared/tokens.js";
+import { loadDeclaredBudget } from "../../shared/exposure.js";
+export const MAP_START = "<!-- speclaw:map:start -->";
+export const MAP_END = "<!-- speclaw:map:end -->";
+/**
+ * Build a compact project map (hubs + top-level layout) from the Compass DB.
+ * Truncates to the declared map token budget.
+ *
+ * @param projectPath - Project root with `.speclaw/index.db`.
+ * @returns Map body text (no markers), or null if the index is missing/empty.
+ */
+export function generateCompactMap(projectPath) {
+    const dbPath = path.join(projectPath, ".speclaw", "index.db");
+    if (!fs.existsSync(dbPath))
+        return null;
+    const db = openDb(projectPath);
+    try {
+        const fileCount = db.prepare("SELECT COUNT(*) AS c FROM files").get().c;
+        const nodeCount = db.prepare("SELECT COUNT(*) AS c FROM nodes").get().c;
+        if (fileCount === 0)
+            return null;
+        const hubs = db
+            .prepare(`SELECT n.name AS name, COUNT(*) AS fan_in
+         FROM edges e
+         JOIN nodes n ON n.id = e.dst_node_id
+         WHERE e.kind = 'call' AND e.dst_node_id IS NOT NULL
+         GROUP BY n.id
+         ORDER BY fan_in DESC
+         LIMIT 12`)
+            .all();
+        const topDirs = db
+            .prepare(`SELECT CASE
+           WHEN instr(path, '/') > 0 THEN substr(path, 1, instr(path, '/') - 1)
+           ELSE path
+         END AS top, COUNT(*) AS c
+         FROM files
+         GROUP BY top
+         ORDER BY c DESC
+         LIMIT 8`)
+            .all();
+        const hubLine = hubs.length === 0
+            ? "hubs: (none yet)"
+            : `hubs: ${hubs.map((h) => `${h.name} ${h.fan_in}`).join(" · ")}`;
+        const dirLine = topDirs.map((d) => `${d.top}/ (${d.c})`).join("  ");
+        let body = [
+            `speclaw · ${fileCount} files · ${nodeCount} nodes`,
+            dirLine,
+            hubLine,
+            "entry: src/server.ts (mcp) · src/cli/index.ts (bin)",
+        ].join("\n");
+        const cap = loadDeclaredBudget().map;
+        let omitted = false;
+        while (estimateTokens(body) > cap && hubs.length > 3) {
+            hubs.pop();
+            omitted = true;
+            const shorter = hubs.length === 0
+                ? "hubs: (truncated)"
+                : `hubs: ${hubs.map((h) => `${h.name} ${h.fan_in}`).join(" · ")}`;
+            body = [
+                `speclaw · ${fileCount} files · ${nodeCount} nodes`,
+                dirLine,
+                shorter,
+                "entry: src/server.ts (mcp) · src/cli/index.ts (bin)",
+                omitted ? "(entries omitted to fit map budget)" : "",
+            ]
+                .filter(Boolean)
+                .join("\n");
+        }
+        if (estimateTokens(body) > cap) {
+            body = [
+                `speclaw · ${fileCount} files · ${nodeCount} nodes`,
+                "entry: src/server.ts (mcp) · src/cli/index.ts (bin)",
+                "(entries omitted to fit map budget)",
+            ].join("\n");
+        }
+        return body;
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * Replace content between map markers in `docs/compass.md`. Preserves content
+ * outside markers. Does nothing (with reason) when markers are missing or the
+ * map cannot be generated.
+ *
+ * @param projectPath - Project root.
+ */
+export function writeCompactMap(projectPath) {
+    const compassPath = path.join(projectPath, "docs", "compass.md");
+    if (!fs.existsSync(compassPath)) {
+        return { written: false, reason: "docs/compass.md missing" };
+    }
+    const original = fs.readFileSync(compassPath, "utf8");
+    const start = original.indexOf(MAP_START);
+    const end = original.indexOf(MAP_END);
+    if (start < 0 || end < 0 || end < start) {
+        return { written: false, reason: "map markers missing — not regenerating" };
+    }
+    const map = generateCompactMap(projectPath);
+    if (!map) {
+        // Leave markers but clear body so we don't leave a stale map.
+        const next = original.slice(0, start + MAP_START.length) + "\n" + original.slice(end);
+        if (next !== original)
+            fs.writeFileSync(compassPath, next);
+        return { written: false, reason: "no index or empty graph — map omitted" };
+    }
+    const next = original.slice(0, start + MAP_START.length) + "\n" + map + "\n" + original.slice(end);
+    fs.writeFileSync(compassPath, next);
+    return { written: true };
+}

package/dist/modules/compass/register.js

@@ -1,78 +1,44 @@
 import { z } from "zod";
-import { text } from "../../shared/mcp.js";
+import { defineTool, text } from "../../shared/mcp.js";
+import { shouldExpose } from "../../shared/exposure.js";
 import { buildIndex } from "./indexer.js";
 import { explore, search, recall, impact, trace } from "./query.js";
 import { startWatch, stopWatch, watchStatus } from "./watcher.js";
 import { visualize } from "./visualize.js";
 // ─── Compass: speclaw's own code-intelligence engine (no external deps) ───
-// A local graph of the codebase (nodes = definitions, edges = calls/imports)
-// plus a local vector store for semantic recall. Lives in .speclaw/ (gitignored).
 /**
- * Register all Compass MCP tools (index, explore, search, recall, impact,
- * trace, watch) on the given server.
+ * Register Compass MCP tools on the given server.
  *
- * @param server - The MCP server to register the Compass tools on.
+ * @param server - The MCP server to register on.
+ * @param opts - Exposure options (`minimal` omits setup/specialized tools).
  */
-export function registerCompass(server) {
-    server.registerTool("compass_index", {
-        description: "Build or incrementally refresh the Compass — speclaw's local code graph (.speclaw/index.db). Parses TS/JS/Python with tree-sitter into nodes (definitions) and edges (calls/imports), and computes a local vector embedding per node for semantic recall. Files unchanged since the last run are skipped by content hash. Run once after init and whenever you want a fresh graph.",
-        inputSchema: { projectPath: z.string().describe("Absolute path to the project") },
-    }, async ({ projectPath }) => text(await buildIndex(projectPath)));
-    server.registerTool("compass_explore", {
-        description: "Explore a node in the Compass: returns its verbatim source, location, callees, and resolved callers (blast radius). Use this BEFORE grep/read when locating or understanding code. Requires compass_index to have run.",
-        inputSchema: {
-            projectPath: z.string().describe("Absolute path to the project"),
-            node: z.string().describe("Exact node name to explore (function/class/method/type)"),
-        },
-    }, async ({ projectPath, node }) => text(explore(projectPath, node)));
-    server.registerTool("compass_search", {
-        description: "Structural search of the Compass: find nodes by name or keyword (substring match). Returns name, kind, and file:line per hit. Cheaper and more structural than grep. Requires compass_index to have run.",
-        inputSchema: {
-            projectPath: z.string().describe("Absolute path to the project"),
-            query: z.string().describe("Name or keyword to search for"),
-            limit: z.number().optional().describe("Max results (default 25)"),
-        },
-    }, async ({ projectPath, query, limit }) => text(search(projectPath, query, limit ?? 25)));
-    server.registerTool("compass_recall", {
-        description: "Semantic search of the Compass: describe what you're looking for in natural language ('where auth tokens are validated') and get the nodes ranked by meaning, using the local vector store — even when the identifier names don't contain your words. Requires compass_index to have run.",
-        inputSchema: {
-            projectPath: z.string().describe("Absolute path to the project"),
-            query: z.string().describe("Natural-language description of the code you want"),
-            limit: z.number().optional().describe("Max results (default 15)"),
-        },
-    }, async ({ projectPath, query, limit }) => text(await recall(projectPath, query, limit ?? 15)));
-    server.registerTool("compass_impact", {
-        description: "Blast radius: every node that transitively calls the target, up to a depth. Answers 'what could break if I change this?' before editing. Includes dynamic-dispatch callers (matched by name). Requires compass_index.",
-        inputSchema: {
-            projectPath: z.string().describe("Absolute path to the project"),
-            node: z.string().describe("Node name whose dependents you want"),
-            maxDepth: z.number().optional().describe("Max hops to traverse (default 4)"),
-        },
-    }, async ({ projectPath, node, maxDepth }) => text(impact(projectPath, node, maxDepth ?? 4)));
-    server.registerTool("compass_trace", {
-        description: "Trace a call path from one node to another: returns the chain of calls linking them (or null if none within depth). Useful to understand how an entrypoint reaches a sink. Requires compass_index.",
-        inputSchema: {
-            projectPath: z.string().describe("Absolute path to the project"),
-            from: z.string().describe("Starting node name"),
-            to: z.string().describe("Target node name"),
-            maxDepth: z.number().optional().describe("Max hops to search (default 8)"),
-        },
+export function registerCompass(server, opts = {}) {
+    const minimal = Boolean(opts.minimal);
+    const add = (name, description, inputSchema, handler) => {
+        if (!shouldExpose(name, minimal))
+            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", "List transitive callers of a symbol (blast radius) before editing.", { projectPath: z.string(), node: z.string(), maxDepth: z.number().optional() }, async ({ projectPath, node, maxDepth }) => text(impact(projectPath, node, maxDepth ?? 4)));
+    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)));
-    server.registerTool("compass_visualize", {
-        description: "Generate an interactive, offline HTML visualization of the code graph into .speclaw/graph.html (gitignored). Nodes are definitions, edges are calls; drag/zoom/hover to explore. Pass a node to focus on its neighborhood, else the most-connected nodes are shown. Requires compass_index.",
-        inputSchema: {
-            projectPath: z.string().describe("Absolute path to the project"),
-            node: z.string().optional().describe("Focus on this node's neighborhood (optional)"),
-            depth: z.number().optional().describe("BFS depth around the focus node (default 2)"),
-            limit: z.number().optional().describe("Max nodes for the whole-graph view (default 300)"),
-        },
+    add("compass_visualize", "Write an offline HTML graph to .speclaw/graph.html for interactive exploration.", {
+        projectPath: z.string(),
+        node: z.string().optional(),
+        depth: z.number().optional(),
+        limit: z.number().optional(),
     }, async ({ projectPath, node, depth, limit }) => text(visualize(projectPath, { focus: node, depth, limit })));
-    server.registerTool("compass_watch", {
-        description: "Keep the Compass index fresh automatically: start/stop a file watcher that incrementally re-indexes on change (debounced). action=start|stop|status. Optional — the index is also refreshed on demand by compass_index.",
-        inputSchema: {
-            projectPath: z.string().describe("Absolute path to the project"),
-            action: z.enum(["start", "stop", "status"]).describe("start, stop, or status"),
-        },
+    add("compass_watch", "Start, stop, or status a debounced file watcher that re-indexes on change.", {
+        projectPath: z.string(),
+        action: z.enum(["start", "stop", "status"]),
     }, async ({ projectPath, action }) => {
         const result = action === "start"
             ? startWatch(projectPath)

package/dist/modules/foundation/assets/docs/compass.template.md

@@ -42,6 +42,9 @@ a missing graph is not license to skip Compass. The only legitimate fallbacks
 to Grep/Read: a Compass call returned nothing useful for your query, or the
 target isn't indexed code (stylesheets, JSON/config, markdown, logs).
 
+<!-- speclaw:map:start -->
+<!-- speclaw:map:end -->
+
 ## Project-specific starting points
 
 <!-- Filled in during speclaw init: the project's real entrypoints, core

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

@@ -0,0 +1,45 @@
+import { registerCompass } from "../compass/register.js";
+import { registerSpec } from "../lawbook/register.js";
+import { registerTools } from "../tools/register.js";
+import { registerFoundation } from "./register.js";
+import { measureBudget } from "../../shared/budget.js";
+import { isMinimalMode, packageRoot } from "../../shared/exposure.js";
+/**
+ * Collect tool definitions as the MCP server would register them for a profile.
+ *
+ * @param minimal - Exposure profile.
+ */
+export function collectRegisteredTools(minimal) {
+    const tools = [];
+    const server = {
+        registerTool(name, config) {
+            tools.push({
+                name,
+                description: config.description ?? "",
+                inputSchema: config.inputSchema,
+            });
+        },
+    };
+    const opts = { minimal };
+    const stub = server;
+    registerFoundation(stub, opts);
+    registerSpec(stub, opts);
+    registerCompass(stub, opts);
+    registerTools(stub, opts);
+    return tools;
+}
+/**
+ * Measure context budget for an install (registered tools + project files).
+ *
+ * @param projectPath - Project root.
+ * @param minimal - Optional forced profile.
+ */
+export function measureInstallBudget(projectPath, minimal) {
+    const profile = minimal ?? isMinimalMode(projectPath);
+    return measureBudget({
+        projectPath,
+        packagePath: packageRoot(),
+        tools: collectRegisteredTools(profile),
+        minimal: profile,
+    });
+}

package/dist/modules/foundation/doctor.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { AGENTS, agentById, detectConfiguredAgents } from "../../shared/agents.js";
+import { isMinimalMode } from "../../shared/exposure.js";
 import { globError, hasBackend, hasBatchBackend, readLawManifest } from "./laws.js";
 /**
  * Run the speclaw installation health checks against a project: ai-specs and
@@ -101,6 +102,14 @@ export function doctor(projectPath) {
         detail: has(".mcp.json") ? "present" : "missing — scaffold writes it",
     });
     lawEnforcementChecks(projectPath, checks);
+    const minimal = isMinimalMode(projectPath);
+    checks.push({
+        name: "exposure profile",
+        ok: true,
+        detail: minimal
+            ? "minimal — setup/lifecycle MCP tools are omitted from registration"
+            : "full — all MCP tools registered (no server-side defer_loading)",
+    });
     return checks;
 }
 /** The law ids recorded as loaded into agent context, from the append-only log. */