@esneiderbravo/speclaw 0.3.13 → 0.4.0

package/dist/modules/lawbook/register.js

@@ -1,19 +1,16 @@
 import path from "node:path";
 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 { assetsDir } from "../../shared/paths.js";
 import { copyRendered } from "../../shared/install.js";
-import { specInit, specValidate, specSync, specArchive, specList } from "./engine.js";
-import { handleLevel } from "./quick.js";
 import { investigate, formatInvestigateResult } from "./investigate.js";
-import { buildCoverageReport, loadCoverageConfig, renderCoverageAgent } from "./coverage.js";
-import { buildDriftReport, renderDriftAgent } from "./drift.js";
+import { handleLawbookChange, lawbookChangeSchema } from "./change-tool.js";
 const ASSETS = assetsDir(import.meta.url);
 /**
- * Install the spec module's workflow interface into a project's ai-specs/:
- * the draft/build/sync/archive/explore skills, the /spec commands, and the
- * mandatory-task-steps rule. Always installed — it's the core workflow.
+ * Install the spec module's workflow interface into a project's ai-specs/.
  */
 export function installWorkflow(projectPath, vars, report, opts) {
     const aiSpecs = path.join(projectPath, "ai-specs");
@@ -21,7 +18,7 @@ export function installWorkflow(projectPath, vars, report, opts) {
     copyRendered(path.join(ASSETS, "commands"), path.join(aiSpecs, "commands", "lawbook"), vars, report, opts);
     copyRendered(path.join(ASSETS, "rules"), path.join(aiSpecs, "rules"), vars, report, opts);
 }
-/** Register the spec workflow MCP tools (init, list, validate, sync, archive). */
+/** Register the spec workflow MCP tools. */
 export function registerSpec(server, opts = {}) {
     const minimal = Boolean(opts.minimal);
     const add = (name, description, inputSchema, handler) => {
@@ -29,57 +26,102 @@ export function registerSpec(server, opts = {}) {
             return;
         defineTool(server, { name, description, inputSchema, handler });
     };
-    add("lawbook_init", "Create the lawbook/ workspace (specs, changes, archive, config). Idempotent.", { projectPath: z.string() }, async ({ projectPath }) => text(specInit(projectPath)));
-    add("lawbook_list", "List active changes, archives, and canonical capabilities under lawbook/.", { projectPath: z.string() }, async ({ projectPath }) => text(specList(projectPath)));
-    add("lawbook_level", "Propose, set, promote, or explain a change's ceremony level (0–3).", {
-        projectPath: z.string(),
-        mode: z.enum(["propose", "set", "promote", "explain"]),
-        change: z.string().optional(),
-        paths: z.array(z.string()).optional(),
-        symbols: z.array(z.string()).optional(),
-        level: z.union([z.literal(0), z.literal(1), z.literal(2), z.literal(3)]).optional(),
-        reason: z.string().optional(),
-    }, async (args) => text(handleLevel(args)));
-    add("lawbook_investigate", "Rank bug origins from the graph. Pass stackTrace or symptom. Returns suspects with reasons — evidence, not a verdict.", {
+    add("lawbook_change", "Lawbook lifecycle: init, list, validate, sync, archive, level, coverage, drift.", lawbookChangeSchema, async (args) => text(handleLawbookChange(args)));
+    add("lawbook_investigate", "Rank bug origins from the graph. Pass stackTrace or symptom — evidence, not verdict.", {
         projectPath: z.string(),
         stackTrace: z.string().optional(),
         symptom: z.string().optional(),
         hintPaths: z.array(z.string()).optional(),
         maxSuspects: z.number().int().min(1).max(25).optional(),
     }, async (args) => text(formatInvestigateResult(await investigate(args))));
-    add("lawbook_validate", "Validate a change's proposal, tasks, and delta specs before build or sync.", { projectPath: z.string(), change: z.string() }, async ({ projectPath, change }) => text(specValidate(projectPath, change)));
-    add("lawbook_sync", "Promote a change's delta specs into canonical lawbook/specs/ without archiving.", { projectPath: z.string(), change: z.string() }, async ({ projectPath, change }) => text(specSync(projectPath, change)));
-    add("lawbook_archive", "Sync a change into canonical specs, then move it under changes/archive/.", {
-        projectPath: z.string(),
-        change: z.string(),
-        date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
-    }, async ({ projectPath, change, date }) => text(specArchive(projectPath, change, date)));
-    add("lawbook_coverage", "Report which requirements lack impl/test coverage before declaring work done.", {
-        projectPath: z.string(),
-        change: z.string().optional(),
-        onlyDefects: z.boolean().optional(),
-        json: z.boolean().optional(),
-    }, async ({ projectPath, change, onlyDefects, json }) => {
-        const cfg = loadCoverageConfig(projectPath);
-        const report = buildCoverageReport(projectPath, { change, cfg });
-        if (json)
-            return text(JSON.stringify(report));
-        return text(renderCoverageAgent(report, onlyDefects !== false));
+    if (minimal || !aliasesEnabled())
+        return;
+    const aliasHandler = (alias, action) => async (args) => {
+        logDeprecatedCall(args.projectPath, alias);
+        const merged = { ...args, action };
+        const result = handleLawbookChange(merged);
+        const body = typeof result === "string" ? result : JSON.stringify(result, null, 2);
+        return text(prefixDeprecated(alias, body));
+    };
+    defineAliasTool(server, {
+        name: "lawbook_init",
+        description: "Deprecated alias for lawbook_change action init.",
+        inputSchema: { projectPath: z.string() },
+        handler: aliasHandler("lawbook_init", "init"),
     });
-    add("lawbook_drift", "Report deterministic drift between sealed spec anchors and the code graph. Call before claiming a task is done.", {
-        projectPath: z.string(),
-        capability: z.string().optional(),
-        includeReverse: z.boolean().optional(),
-        maxItems: z.number().int().min(1).max(50).optional(),
-        json: z.boolean().optional(),
-    }, async ({ projectPath, capability, includeReverse, maxItems, json }) => {
-        const report = buildDriftReport(projectPath, {
-            capability,
-            reverse: includeReverse === true,
-            failOn: "semantic",
-        });
-        if (json)
-            return text(JSON.stringify(report));
-        return text(renderDriftAgent(report, maxItems ?? 10));
+    defineAliasTool(server, {
+        name: "lawbook_list",
+        description: "Deprecated alias for lawbook_change action list.",
+        inputSchema: { projectPath: z.string() },
+        handler: aliasHandler("lawbook_list", "list"),
+    });
+    defineAliasTool(server, {
+        name: "lawbook_validate",
+        description: "Deprecated alias for lawbook_change action validate.",
+        inputSchema: { projectPath: z.string(), change: z.string() },
+        handler: aliasHandler("lawbook_validate", "validate"),
+    });
+    defineAliasTool(server, {
+        name: "lawbook_sync",
+        description: "Deprecated alias for lawbook_change action sync.",
+        inputSchema: { projectPath: z.string(), change: z.string() },
+        handler: aliasHandler("lawbook_sync", "sync"),
+    });
+    defineAliasTool(server, {
+        name: "lawbook_archive",
+        description: "Deprecated alias for lawbook_change action archive.",
+        inputSchema: {
+            projectPath: z.string(),
+            change: z.string(),
+            date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
+        },
+        handler: aliasHandler("lawbook_archive", "archive"),
+    });
+    defineAliasTool(server, {
+        name: "lawbook_level",
+        description: "Deprecated alias for lawbook_change action level.",
+        inputSchema: {
+            projectPath: z.string(),
+            mode: z.string().optional(),
+            change: z.string().optional(),
+            level: z.number().optional(),
+            reason: z.string().optional(),
+        },
+        handler: async (args) => {
+            logDeprecatedCall(args.projectPath, "lawbook_level");
+            const body = JSON.stringify(handleLawbookChange({ ...args, action: "level" }), null, 2);
+            return text(prefixDeprecated("lawbook_level", body));
+        },
+    });
+    defineAliasTool(server, {
+        name: "lawbook_coverage",
+        description: "Deprecated alias for lawbook_change action coverage.",
+        inputSchema: {
+            projectPath: z.string(),
+            change: z.string().optional(),
+            onlyDefects: z.boolean().optional(),
+            json: z.boolean().optional(),
+        },
+        handler: async (args) => {
+            logDeprecatedCall(args.projectPath, "lawbook_coverage");
+            const body = JSON.stringify(handleLawbookChange({ ...args, action: "coverage" }), null, 2);
+            return text(prefixDeprecated("lawbook_coverage", body));
+        },
+    });
+    defineAliasTool(server, {
+        name: "lawbook_drift",
+        description: "Deprecated alias for lawbook_change action drift.",
+        inputSchema: {
+            projectPath: z.string(),
+            capability: z.string().optional(),
+            includeReverse: z.boolean().optional(),
+            maxItems: z.number().int().optional(),
+            json: z.boolean().optional(),
+        },
+        handler: async (args) => {
+            logDeprecatedCall(args.projectPath, "lawbook_drift");
+            const body = JSON.stringify(handleLawbookChange({ ...args, action: "drift" }), null, 2);
+            return text(prefixDeprecated("lawbook_drift", body));
+        },
     });
 }

package/dist/modules/tools/register.js

@@ -1,27 +1,5 @@
-import { z } from "zod";
-import { defineTool, text } from "../../shared/mcp.js";
-import { shouldExpose } from "../../shared/exposure.js";
-import { emptyReport } from "../../shared/install.js";
-import { refreshAgents } from "../../shared/agents.js";
-import { loadPacks, installPack } from "./packs.js";
-export { loadPacks, installPack };
-/** Register the tools-module MCP tools (list_packs, add_pack). */
-export function registerTools(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("list_packs", "List available speclaw skill packs and what each contains.", {}, async () => text(loadPacks()));
-    add("add_pack", "Install one pack into an initialized project and refresh IDE symlinks.", {
-        projectPath: z.string(),
-        pack: z.string(),
-        vars: z.record(z.string()).optional(),
-    }, async ({ projectPath, pack, vars }) => {
-        const report = emptyReport();
-        installPack(projectPath, pack, vars ?? {}, report);
-        refreshAgents(projectPath, report);
-        return text(report);
-    });
+export { loadPacks, installPack } from "./packs.js";
+/** Packs are registered via `speclaw_setup` — no standalone MCP tools. */
+export function registerTools(_server, _opts = {}) {
+    /* consolidated into speclaw_setup */
 }

package/dist/shared/deprecation.js

@@ -0,0 +1,99 @@
+import fs from "node:fs";
+import path from "node:path";
+import { ALIAS_TARGETS } from "./tool-catalog.js";
+const LOG_NAME = "deprecated-calls.jsonl";
+/** Append-only log of deprecated alias invocations under `.speclaw/`. */
+export function logDeprecatedCall(projectPath, alias) {
+    const target = ALIAS_TARGETS[alias];
+    if (!target)
+        return;
+    const dir = path.join(projectPath, ".speclaw");
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        const line = JSON.stringify({
+            at: new Date().toISOString(),
+            alias,
+            replacement: target,
+        });
+        fs.appendFileSync(path.join(dir, LOG_NAME), line + "\n", "utf8");
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** Read recent deprecated alias counts for doctor. */
+export function readDeprecatedCallCounts(projectPath) {
+    const counts = new Map();
+    const file = path.join(projectPath, ".speclaw", LOG_NAME);
+    try {
+        for (const line of fs.readFileSync(file, "utf8").split("\n")) {
+            if (!line.trim())
+                continue;
+            const row = JSON.parse(line);
+            if (row.alias)
+                counts.set(row.alias, (counts.get(row.alias) ?? 0) + 1);
+        }
+    }
+    catch {
+        /* no log */
+    }
+    return counts;
+}
+const SCAN_PATHS = ["CLAUDE.md", "AGENTS.md", "LAWS.md", "docs/compass.md"];
+const SCAN_DIRS = [".cursor/rules", ".claude/rules", "ai-specs/rules"];
+function listMarkdownFiles(dir) {
+    const out = [];
+    try {
+        for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, ent.name);
+            if (ent.isDirectory())
+                out.push(...listMarkdownFiles(full));
+            else if (ent.name.endsWith(".md"))
+                out.push(full);
+        }
+    }
+    catch {
+        /* missing dir */
+    }
+    return out;
+}
+/** Find personalized files that still cite retired MCP tool names. */
+export function scanRetiredToolReferences(projectPath) {
+    const files = new Set();
+    for (const rel of SCAN_PATHS) {
+        const full = path.join(projectPath, rel);
+        if (fs.existsSync(full))
+            files.add(full);
+    }
+    for (const rel of SCAN_DIRS) {
+        for (const full of listMarkdownFiles(path.join(projectPath, rel)))
+            files.add(full);
+    }
+    const hits = [];
+    for (const file of files) {
+        let text;
+        try {
+            text = fs.readFileSync(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const [alias, replacement] of Object.entries(ALIAS_TARGETS)) {
+            if (text.includes(alias)) {
+                hits.push({ file: path.relative(projectPath, file), alias, replacement });
+            }
+        }
+    }
+    return hits;
+}
+const REMOVAL_VERSION = "0.6.0";
+/**
+ * Prefix a tool response when invoked through a deprecated alias.
+ *
+ * @param alias - Retired tool name.
+ * @param body - Serialized response body.
+ */
+export function prefixDeprecated(alias, body) {
+    const target = ALIAS_TARGETS[alias] ?? "see canonical tools";
+    return `[deprecated] ${alias} → ${target}. Retiring in ${REMOVAL_VERSION}.\n\n${body}`;
+}

package/dist/shared/exposure.js

@@ -4,29 +4,14 @@ import { fileURLToPath } from "node:url";
 import { readManifest } from "./manifest.js";
 /**
  * Tools omitted when the exposure profile is `minimal`. Kept tools are the
- * discovery + law loop: compass_explore/search/recall, lawbook_validate/sync,
- * lawbook_coverage, lawbook_drift, law_verify, speclaw_check.
+ * discovery + law loop: compass_explore/find/diff_context, lawbook_change.
+ * Deprecated aliases are never registered in minimal mode.
  */
 export const MINIMAL_OMIT = new Set([
     "compass_index",
-    "compass_watch",
-    "compass_impact",
-    "compass_affected_tests",
-    "compass_hotspots",
-    "compass_coupling",
-    "compass_trace",
-    "compass_visualize",
-    "lawbook_init",
-    "lawbook_archive",
-    "lawbook_list",
-    "lawbook_level",
     "lawbook_investigate",
-    "init_project",
-    "scaffold",
-    "configure_agent",
-    "doctor",
-    "add_pack",
-    "list_packs",
+    "speclaw_setup",
+    "speclaw_check",
 ]);
 /**
  * Whether minimal exposure is active for this process / project.

package/dist/shared/git.js

@@ -86,3 +86,28 @@ export function changedFiles(projectPath, base) {
         .map((l) => l.trim())
         .filter(Boolean);
 }
+/**
+ * Project-relative paths with uncommitted changes vs `HEAD` (staged and unstaged).
+ *
+ * @param projectPath - Directory inside the work tree.
+ */
+export function worktreeChangedFiles(projectPath) {
+    if (!isGitRepo(projectPath))
+        return [];
+    const res = spawnSync("git", [
+        "-C",
+        projectPath,
+        "-c",
+        "core.quotePath=false",
+        "diff",
+        "--name-only",
+        "--diff-filter=ACMR",
+        "HEAD",
+    ], { encoding: "utf8" });
+    if (res.status !== 0 || typeof res.stdout !== "string")
+        return [];
+    return res.stdout
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean);
+}

package/dist/shared/mcp.js

@@ -1,18 +1,22 @@
 import { loadDeclaredBudget } from "./exposure.js";
 import { toolDefinitionTokens } from "./schema-tokens.js";
 import { countWords } from "./tokens.js";
+import { applyTextBudget } from "./output-budget.js";
 /**
- * Wrap a value as an MCP text tool-result.
+ * Wrap a value as an MCP text tool-result, optionally applying an output budget.
  *
  * @param value - Payload to return; strings are emitted verbatim, other values are pretty-printed as JSON.
+ * @param mode - Output mode (`brief` default) for token budgeting.
  * @returns An MCP result object with a single text content block.
  */
-export function text(value) {
+export function text(value, mode = "brief") {
+    const raw = typeof value === "string" ? value : JSON.stringify(value, null, 2);
+    const budgeted = applyTextBudget(raw, mode);
     return {
         content: [
             {
                 type: "text",
-                text: typeof value === "string" ? value : JSON.stringify(value, null, 2),
+                text: budgeted.text,
             },
         ],
     };
@@ -47,3 +51,25 @@ export function defineTool(server, spec) {
         ...(spec.annotations ? { annotations: spec.annotations } : {}),
     }, spec.handler);
 }
+const ALIAS_MAX_WORDS = 12;
+const ALIAS_MAX_TOKENS = 200;
+/**
+ * Register a deprecated alias with a terse description (not counted in the
+ * canonical eight-tool limit).
+ */
+export function defineAliasTool(server, spec) {
+    const words = countWords(spec.description);
+    if (words > ALIAS_MAX_WORDS) {
+        throw new Error(`alias ${spec.name}: description is ${words} words (cap ${ALIAS_MAX_WORDS})`);
+    }
+    const cost = toolDefinitionTokens({
+        name: spec.name,
+        description: spec.description,
+        inputSchema: spec.inputSchema,
+    });
+    if (cost > ALIAS_MAX_TOKENS) {
+        throw new Error(`alias ${spec.name}: ${cost} tokens exceeds alias cap ${ALIAS_MAX_TOKENS}`);
+    }
+    const inputSchema = (spec.inputSchema ?? {});
+    server.registerTool(spec.name, { description: spec.description, inputSchema }, spec.handler);
+}

package/dist/shared/output-budget.js

@@ -0,0 +1,68 @@
+/** Declared output token ceilings (estimator v1: ~4 chars per token). */
+export const OUTPUT_BUDGET = {
+    brief: 1500,
+    full: 4500,
+};
+const TRUNCATION_SUFFIX = `\n… [truncated — use mode:"full" or narrow includes]`;
+/** Stable offline token estimate for budgeting (not a real tokenizer). */
+export function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+/**
+ * Trim `text` to fit `mode` budget; returns the possibly shortened text and
+ * whether truncation occurred.
+ */
+export function applyTextBudget(text, mode = "brief") {
+    const budget = OUTPUT_BUDGET[mode];
+    const tokens = estimateTokens(text);
+    if (tokens <= budget)
+        return { text, truncated: false, omittedChars: 0 };
+    const suffixTokens = estimateTokens(TRUNCATION_SUFFIX);
+    const bodyBudget = Math.max(1, budget - suffixTokens);
+    const maxChars = bodyBudget * 4;
+    const trimmed = text.slice(0, maxChars);
+    return {
+        text: trimmed + TRUNCATION_SUFFIX,
+        truncated: true,
+        omittedChars: text.length - maxChars,
+    };
+}
+/**
+ * Truncate known list fields on an explore-style object before serialization.
+ *
+ * @param value - Plain object to mutate in place (arrays shortened, counts kept).
+ * @param mode - Output mode controlling list limits.
+ * @param truncated - Collector for explicit truncation records.
+ */
+export function budgetExploreShape(value, mode, truncated) {
+    const maxCallers = mode === "full" ? 40 : 12;
+    const maxSourceLines = mode === "full" ? 120 : 40;
+    const symbol = value.symbol;
+    if (symbol && typeof symbol.source === "string") {
+        const lines = symbol.source.split("\n");
+        if (lines.length > maxSourceLines) {
+            const omitted = lines.length - maxSourceLines;
+            symbol.source = lines.slice(0, maxSourceLines).join("\n") + "\n…";
+            truncated.push({
+                field: "symbol.source",
+                omitted,
+                hint: 'use mode:"full" or omit source from include',
+            });
+        }
+    }
+    for (const field of ["callers", "callees"]) {
+        const list = value[field];
+        if (!Array.isArray(list))
+            continue;
+        if (list.length > maxCallers) {
+            const omitted = list.length - maxCallers;
+            value[`${field}Total`] = list.length;
+            value[field] = list.slice(0, maxCallers);
+            truncated.push({
+                field,
+                omitted,
+                hint: 'use mode:"full" or narrow with include',
+            });
+        }
+    }
+}

package/dist/shared/tool-catalog.js

@@ -0,0 +1,49 @@
+/** Canonical MCP tools counted toward the surface limit (aliases excluded). */
+export const CANONICAL_TOOLS = [
+    "compass_explore",
+    "compass_find",
+    "compass_diff_context",
+    "compass_index",
+    "lawbook_change",
+    "lawbook_investigate",
+    "speclaw_setup",
+    "speclaw_check",
+];
+export const MAX_CANONICAL_TOOLS = 8;
+/** Retired MCP names → canonical replacement hint for deprecation notices. */
+export const ALIAS_TARGETS = {
+    compass_search: "compass_find (mode: exact)",
+    compass_recall: "compass_find (mode: concept)",
+    compass_impact: 'compass_explore (include: ["blast_radius"])',
+    compass_trace: "compass_explore (to: <symbol>)",
+    compass_affected_tests: "compass_explore or compass_diff_context",
+    compass_hotspots: "compass_explore or compass_diff_context",
+    compass_coupling: "compass_diff_context",
+    compass_watch: "compass_index (action: start|stop|status)",
+    lawbook_init: 'lawbook_change (action: "init")',
+    lawbook_list: 'lawbook_change (action: "list")',
+    lawbook_validate: 'lawbook_change (action: "validate")',
+    lawbook_sync: 'lawbook_change (action: "sync")',
+    lawbook_archive: 'lawbook_change (action: "archive")',
+    lawbook_level: 'lawbook_change (action: "level")',
+    lawbook_coverage: 'lawbook_change (action: "coverage")',
+    lawbook_drift: 'lawbook_change (action: "drift")',
+    init_project: 'speclaw_setup (action: "init")',
+    configure_agent: 'speclaw_setup (action: "configure-agent")',
+    add_pack: 'speclaw_setup (action: "add-pack")',
+    list_packs: 'speclaw_setup (action: "list-packs")',
+};
+export const ALIAS_NAMES = Object.keys(ALIAS_TARGETS);
+const ALIAS_SET = new Set(ALIAS_NAMES);
+/** True when `name` is one of the eight canonical tools. */
+export function isCanonicalTool(name) {
+    return CANONICAL_TOOLS.includes(name);
+}
+/** True when `name` is a deprecated alias (not counted in the canonical limit). */
+export function isAliasTool(name) {
+    return ALIAS_SET.has(name);
+}
+/** Whether deprecated aliases should register for this process. */
+export function aliasesEnabled() {
+    return process.env.SPECLAW_NO_ALIASES !== "1";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esneiderbravo/speclaw",
-  "version": "0.3.13",
+  "version": "0.4.0",
   "publishConfig": {
     "access": "public"
   },