@esneiderbravo/speclaw 0.3.13 → 0.4.0

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 {
@@ -569,6 +613,7 @@ function configurationChecks(projectPath, initialised) {
             "cfg.hooks",
             "cfg.laws",
             "cfg.budget",
+            "cfg.tool-surface",
             "cfg.index.freshness",
             "cfg.specs.orphans",
         ];
@@ -650,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,
-    });
 }

package/dist/modules/foundation/setup-tool.js

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import { loadPacks } from "../tools/packs.js";
+import { AGENTS, configureAgent } from "../../shared/agents.js";
+import { emptyReport } from "../../shared/install.js";
+import { refreshAgents } from "../../shared/agents.js";
+import { installPack } from "../tools/packs.js";
+/** Human help text for init 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",
+};
+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(),
+};
+export const setupActions = ["init", "configure-agent", "add-pack", "list-packs"];
+export const speclawSetupSchema = {
+    projectPath: z.string(),
+    action: z.enum(setupActions),
+    agent: z.enum(AGENTS.map((a) => a.id)).optional(),
+    pack: z.string().optional(),
+    vars: z.record(z.string()).optional(),
+};
+/**
+ * Dispatch `speclaw_setup` by action. Scaffold is CLI-only — not exposed here.
+ *
+ * @param args - Setup action and parameters.
+ */
+export function handleSpeclawSetup(args) {
+    switch (args.action) {
+        case "init":
+            return {
+                instructions: [
+                    "1. Analyze the repository at projectPath and fill profile fields from the real codebase.",
+                    "2. Call speclaw_setup with action configure-agent / add-pack as needed.",
+                    "3. Run lawbook_change action init and compass_index when scaffold completes via CLI if needed.",
+                ],
+                profileFields: profileFieldHelp,
+                packs: loadPacks(),
+                note: "Full scaffold runs via CLI: speclaw init — not MCP.",
+            };
+        case "configure-agent": {
+            if (!args.agent)
+                throw new Error(`speclaw_setup: action 'configure-agent' requires 'agent'`);
+            const report = emptyReport();
+            configureAgent(args.projectPath, args.agent, report);
+            return report;
+        }
+        case "list-packs":
+            return loadPacks();
+        case "add-pack": {
+            if (!args.pack)
+                throw new Error(`speclaw_setup: action 'add-pack' requires 'pack'`);
+            const report = emptyReport();
+            installPack(args.projectPath, args.pack, args.vars ?? {}, report);
+            refreshAgents(args.projectPath, report);
+            return report;
+        }
+        default:
+            throw new Error(`speclaw_setup: unknown action '${String(args.action)}'`);
+    }
+}
+/** Zod profile shape for CLI scaffold (not in MCP schema). */
+export { profileShape as setupProfileShape };

package/dist/modules/lawbook/assets/commands/archive.md

@@ -6,5 +6,5 @@ Archive the completed change: $ARGUMENTS
 
 Follow the `archive` skill: confirm every task (or level-0 checklist) is done
 and gates are green, reconcile if the level has delta specs, run
-`lawbook_validate`, then `lawbook_archive` with today's date (YYYY-MM-DD). Sync
+`lawbook_change` (action: validate), then `lawbook_change` (action: archive) with today's date (YYYY-MM-DD). Sync
 runs only when the ceremony level requires specs. Never move the folder by hand.

package/dist/modules/lawbook/assets/commands/draft.md

@@ -8,4 +8,4 @@ Follow the `draft` skill: ensure `lawbook/` exists (`lawbook_init`), investigate
 with Compass, propose a ceremony level (`lawbook_level` mode `propose`) and
 **confirm** it with the human (`set`), then scaffold only the artifacts that
 level requires. For true one-liners use `speclaw quick` / the `quick` skill
-instead. Finish by running `lawbook_validate` and fixing every issue.
+instead. Finish by running `lawbook_change` (action: validate) and fixing every issue.

package/dist/modules/lawbook/assets/commands/explore.md

@@ -4,7 +4,7 @@ description: Enter explore mode — a thinking partner before or during a change
 
 Explore: $ARGUMENTS
 
-Follow the `explore` skill: use `compass_recall`/`compass_explore` to understand
+Follow the `explore` skill: use `compass_find` (mode: concept)/`compass_explore` to understand
 the code, ask sharp questions, check the relevant `docs/standards/`, weigh
 approaches with trade-offs, and give a recommendation. Write nothing to
 `lawbook/`; when the direction is clear, offer to `draft` the change.

package/dist/modules/lawbook/assets/commands/sync.md

@@ -5,6 +5,6 @@ description: Promote a change's delta specs into the canonical specs, without ar
 Sync the change's specs into canonical: $ARGUMENTS
 
 Follow the `sync` skill: reconcile the delta specs against what was actually
-built (branch diff + code graph), validate the change (`lawbook_validate`), then
-run `lawbook_sync` to promote each delta spec into `lawbook/specs/`. Report what
+built (branch diff + code graph), validate the change (`lawbook_change` (action: validate)), then
+run `lawbook_change` (action: sync) to promote each delta spec into `lawbook/specs/`. Report what
 you reconciled and what was promoted; leave the change active.

package/dist/modules/lawbook/assets/skills/archive/SKILL.md

@@ -9,7 +9,7 @@ Close out a completed change: its delta specs become canonical and the change
 folder moves to `lawbook/changes/archive/`. This is part of the PR that
 implements the change, not a post-merge chore.
 
-`lawbook_archive` is **gated** — the engine refuses to archive (and reports the
+`lawbook_change` (action: archive) is **gated** — the engine refuses to archive (and reports the
 reason) while any task is unchecked, while `reports/` holds no discipline report,
 or while the delta specs are not yet synced into the canonical specs. So archive
 is the last step of a completed change: reconcile, sync, then archive.

package/dist/modules/lawbook/assets/skills/archive/steps/03-validate-and-sync.md

@@ -1,8 +1,8 @@
 # Validate and sync
 
-Run `lawbook_validate`. If the confirmed ceremony level requires delta specs
-(levels 1–3), run `lawbook_sync` to promote them into `lawbook/specs/` —
-`lawbook_archive` refuses unless the canonical specs already match. At **level
+Run `lawbook_change` (action: validate). If the confirmed ceremony level requires delta specs
+(levels 1–3), run `lawbook_change` (action: sync) to promote them into `lawbook/specs/` —
+`lawbook_change` (action: archive) refuses unless the canonical specs already match. At **level
 0**, skip sync (there are no deltas).
 
 Next: read `steps/04-archive.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/archive/steps/04-archive.md

@@ -1,6 +1,6 @@
 # Archive
 
-Run the `lawbook_archive` tool with the change name and today's date
+Run the `lawbook_change` (action: archive) tool with the change name and today's date
 (`YYYY-MM-DD`). It re-checks the gate deterministically and, if it passes,
 moves `lawbook/changes/<name>/` to `lawbook/changes/archive/<date>-<name>/`.
 If it refuses, resolve the reported blockers (unchecked tasks, missing

package/dist/modules/lawbook/assets/skills/draft/steps/02-understand.md

@@ -4,7 +4,7 @@
   code — it is incremental (unchanged files are skipped by hash), so this is
   cheap and guarantees your decisions rest on the current graph, not a stale one.
 - Clarify what the user wants (feature / fix / refactor) and confirm scope.
-- Use `compass_explore` and `compass_recall` (speclaw's code index) BEFORE
+- Use `compass_explore` and `compass_find` (mode: concept) (speclaw's code index) BEFORE
   grep/read to locate the real code the change touches and its blast radius.
 - **Propose a ceremony level** with `lawbook_level` (mode `propose`) using the
   paths/symbols you found; **confirm with the human** (mode `set`) before

package/dist/modules/lawbook/assets/skills/draft/steps/05-validate.md

@@ -1,6 +1,6 @@
 # Validate
 
-Run the `lawbook_validate` tool for the change and fix every issue it reports
+Run the `lawbook_change` (action: validate) tool for the change and fix every issue it reports
 (missing artifacts, non-normative specs, missing scenarios) before handing off
 to implementation. Read its advisory **warnings** too: a near-duplicate
 capability name usually means you should reuse the existing capability's exact

package/dist/modules/lawbook/assets/skills/explore/steps/01-investigate.md

@@ -3,7 +3,7 @@
 - **Refresh the index first.** Run `compass_index` before investigating — it is
   incremental (unchanged files skipped by hash), so it is cheap and keeps your
   reasoning on the current graph rather than a stale one.
-- **Understand the code first.** Use `compass_recall` to find relevant code by
+- **Understand the code first.** Use `compass_find` (mode: concept) to find relevant code by
   meaning and `compass_explore` to read a symbol's source plus its callers and
   callees — before grep/read.
 - **Ask sharp questions** to surface hidden assumptions, constraints, and edge

package/dist/modules/lawbook/assets/skills/quick/steps/02-implement.md

@@ -1,7 +1,7 @@
 # Implement and evidence
 
 Make the fix, tick every `- [ ]` in `record.md`, and write at least one
-discipline report under `reports/`. Archive with `lawbook_archive` (no sync at
+discipline report under `reports/`. Archive with `lawbook_change` (action: archive) (no sync at
 level 0). Promote via `lawbook_level` if scope grew.
 
 No further steps — workflow complete.

package/dist/modules/lawbook/assets/skills/sync/SKILL.md

@@ -9,7 +9,7 @@ Update the project's canonical specifications (`lawbook/specs/`) with a change's
 delta specs, without archiving the change. Use this when the specs should
 become the source of truth but the change isn't finished (e.g. multi-PR work).
 
-`lawbook_sync` is a deterministic copy — it is blind to the code. So before
+`lawbook_change` (action: sync) is a deterministic copy — it is blind to the code. So before
 promoting, YOU reconcile the delta specs against what was actually built, so the
 specs that become canonical describe reality, not just the original draft.
 

package/dist/modules/lawbook/assets/skills/sync/steps/03-validate.md

@@ -1,6 +1,6 @@
 # Validate
 
-Run `lawbook_validate` for the change; do not sync a change whose specs are
+Run `lawbook_change` (action: validate) for the change; do not sync a change whose specs are
 invalid.
 
 Next: read `steps/04-promote.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/sync/steps/04-promote.md

@@ -1,6 +1,6 @@
 # Promote
 
-Run the `lawbook_sync` tool for the change. It copies each
+Run the `lawbook_change` (action: sync) tool for the change. It copies each
 `lawbook/changes/<name>/specs/<capability>/spec.md` over the canonical
 `lawbook/specs/<capability>/spec.md` and reports what it promoted, flagging
 each as **created** (new capability) or **updated** (overwrote an existing

package/dist/modules/lawbook/change-tool.js

@@ -0,0 +1,90 @@
+import { z } from "zod";
+import { specInit, specValidate, specSync, specArchive, specList } from "./engine.js";
+import { handleLevel } from "./quick.js";
+import { buildCoverageReport, loadCoverageConfig, renderCoverageAgent } from "./coverage.js";
+import { buildDriftReport, renderDriftAgent } from "./drift.js";
+export const lawbookChangeActions = [
+    "init",
+    "list",
+    "validate",
+    "sync",
+    "archive",
+    "level",
+    "coverage",
+    "drift",
+];
+export const lawbookChangeSchema = {
+    projectPath: z.string(),
+    action: z.enum(lawbookChangeActions),
+    change: z.string().optional(),
+    date: z
+        .string()
+        .regex(/^\d{4}-\d{2}-\d{2}$/)
+        .optional(),
+    mode: z.enum(["propose", "set", "promote", "explain"]).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(),
+    onlyDefects: z.boolean().optional(),
+    json: z.boolean().optional(),
+    capability: z.string().optional(),
+    includeReverse: z.boolean().optional(),
+    maxItems: z.number().int().min(1).max(50).optional(),
+};
+function requireField(args, field) {
+    const v = args[field];
+    if (typeof v === "string" && v.length > 0)
+        return v;
+    throw new Error(`lawbook_change: action '${args.action}' requires '${String(field)}'`);
+}
+/**
+ * Dispatch `lawbook_change` by action.
+ *
+ * @param args - Unified lawbook lifecycle arguments.
+ */
+export function handleLawbookChange(args) {
+    switch (args.action) {
+        case "init":
+            return specInit(args.projectPath);
+        case "list":
+            return specList(args.projectPath);
+        case "validate":
+            return specValidate(args.projectPath, requireField(args, "change"));
+        case "sync":
+            return specSync(args.projectPath, requireField(args, "change"));
+        case "archive":
+            return specArchive(args.projectPath, requireField(args, "change"), requireField(args, "date"));
+        case "level":
+            if (!args.mode)
+                throw new Error(`lawbook_change: action 'level' requires 'mode'`);
+            return handleLevel({
+                projectPath: args.projectPath,
+                mode: args.mode,
+                change: args.change,
+                paths: args.paths,
+                symbols: args.symbols,
+                level: args.level,
+                reason: args.reason,
+            });
+        case "coverage": {
+            const cfg = loadCoverageConfig(args.projectPath);
+            const report = buildCoverageReport(args.projectPath, { change: args.change, cfg });
+            if (args.json)
+                return report;
+            return renderCoverageAgent(report, args.onlyDefects !== false);
+        }
+        case "drift": {
+            const report = buildDriftReport(args.projectPath, {
+                capability: args.capability,
+                reverse: args.includeReverse === true,
+                failOn: "semantic",
+            });
+            if (args.json)
+                return report;
+            return renderDriftAgent(report, args.maxItems ?? 10);
+        }
+        default:
+            throw new Error(`lawbook_change: unknown action '${String(args.action)}'`);
+    }
+}