@esneiderbravo/speclaw 0.3.3 → 0.3.5

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/assets/laws/laws-manifest.json

@@ -44,6 +44,55 @@
       "verification": { "kind": "path" },
       "enforcement": "feedback",
       "source": { "file": "LAWS.md" }
+    },
+    {
+      "id": "law~shared-stays-inner~1",
+      "title": "shared stays the innermost layer",
+      "rationale": "shared/ must not import modules/ or cli/, or the layering law is inverted.",
+      "severity": "error",
+      "scope": ["src/shared/**"],
+      "prose": "src/shared must not import from src/modules or src/cli.",
+      "verification": {
+        "kind": "deps",
+        "rule": {
+          "from": "^src/shared/",
+          "to": "^src/(modules|cli)/",
+          "type": "forbidden",
+          "edgeKinds": ["import"]
+        }
+      },
+      "enforcement": "gate",
+      "source": { "file": "docs/standards/architecture.md" }
+    },
+    {
+      "id": "law~compass-does-not-import-foundation~1",
+      "title": "Compass does not import foundation",
+      "rationale": "foundation already imports compass; the reverse would be a module cycle.",
+      "severity": "error",
+      "scope": ["src/modules/compass/**"],
+      "prose": "src/modules/compass must not import from src/modules/foundation.",
+      "verification": {
+        "kind": "deps",
+        "rule": {
+          "from": "^src/modules/compass/",
+          "to": "^src/modules/foundation/",
+          "type": "forbidden",
+          "edgeKinds": ["import"]
+        }
+      },
+      "enforcement": "gate",
+      "source": { "file": "docs/standards/architecture.md" }
+    },
+    {
+      "id": "law~no-module-cycles~1",
+      "title": "No circular module dependencies",
+      "rationale": "Modules may reuse another module's exported helper, but there are no circular dependencies.",
+      "severity": "error",
+      "scope": ["src/modules/**"],
+      "prose": "There are no circular dependencies between modules.",
+      "verification": { "kind": "graph", "rule": { "circular": true } },
+      "enforcement": "gate",
+      "source": { "file": "docs/standards/architecture.md" }
     }
   ]
 }

package/dist/modules/foundation/assets/workflows/speclaw.yml

@@ -0,0 +1,26 @@
+# Consumer template. init/update write this only when the path is missing.
+# Never the untrusted PR trigger. The verify job has no secrets.
+name: ⚖️ speclaw
+on: pull_request
+
+permissions: {}
+
+jobs:
+  verify:
+    name: ⚖️ Verify laws
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+    steps:
+      - name: 📥 Checkout
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - name: ⚖️ Verify
+        uses: esneiderbravo/speclaw@v1
+      - name: 🛡️ Upload SARIF
+        uses: github/codeql-action/upload-sarif@v4
+        if: always()
+        with:
+          sarif_file: speclaw.sarif

package/dist/modules/foundation/ci.js

@@ -0,0 +1,41 @@
+const RANK = { error: 3, warn: 2, info: 1 };
+/**
+ * Parse `--fail-on`. An omitted flag is `error`; any other string is invalid
+ * (the CLI maps that to exit 2).
+ *
+ * @param raw - The flag value from `parseFlags`.
+ */
+export function parseFailOn(raw) {
+    if (raw === undefined || raw === true)
+        return "error";
+    if (raw === "error" || raw === "warn" || raw === "info")
+        return raw;
+    return null;
+}
+/**
+ * Stable identity of a finding, reused as the SARIF `partialFingerprints`
+ * value. There is no known-violations baseline in this slice, so the
+ * fingerprint is local: law + file + line.
+ *
+ * @param f - A batch finding.
+ */
+export function fingerprint(f) {
+    return `${f.lawId}:${f.file}:${f.line ?? 0}`;
+}
+/**
+ * Map a {@link VerifyReport} onto the public `speclaw verify` exit codes
+ * `0` / `1` / `4`. Usage (`2`) and environment (`3`) errors are decided by
+ * the CLI before this runs.
+ *
+ * @param report - The batch report.
+ * @param opts.failOn - Minimum severity that fails the process.
+ * @param opts.strictEngines - When true, any skip becomes exit `4`.
+ */
+export function verifyExitCode(report, opts) {
+    const threshold = RANK[opts.failOn];
+    if (report.findings.some((f) => RANK[f.severity] >= threshold))
+        return 1;
+    if (opts.strictEngines && report.skipped.length > 0)
+        return 4;
+    return 0;
+}

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/deps.js

@@ -1,4 +1,4 @@
-import { underPaths } from "./verify.js";
+import { underPaths } from "./verify-model.js";
 /** Substitute `$1`, `$2`, … in a pattern with capture groups from a match. */
 function applyGroups(pattern, match) {
     return pattern.replace(/\$(\d+)/g, (_whole, d) => match[Number(d)] ?? "");

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. */

package/dist/modules/foundation/graph.js

@@ -1,4 +1,4 @@
-import { underPaths } from "./verify.js";
+import { underPaths } from "./verify-model.js";
 /** Build the cross-file dependency graph, restricted to `paths` when given. */
 function buildGraph(db, paths) {
     const rows = db

package/dist/modules/foundation/laws.js

@@ -151,6 +151,34 @@ export function seedManifest() {
     const raw = JSON.parse(fs.readFileSync(path.join(ASSETS, "laws", "laws-manifest.json"), "utf8"));
     return manifestSchema.parse(raw);
 }
+/**
+ * The manifest the batch verifier should use: the project's file when present,
+ * otherwise the shipped seed (so a clean CI clone does not silently pass).
+ *
+ * @param projectPath - Project root to read from.
+ */
+export function loadManifestForVerify(projectPath) {
+    return readLawManifest(projectPath) ?? seedManifest();
+}
+/**
+ * Append shipped seed laws whose `id` is not already in `existing`. Existing
+ * entries are never overwritten — a curated law keeps its prose, scope, and
+ * enforcement across `update`.
+ *
+ * @param existing - The project's current manifest.
+ * @returns The merged manifest and the ids that were added.
+ */
+export function mergeSeedLaws(existing) {
+    const seed = seedManifest();
+    const have = new Set(existing.laws.map((l) => l.id));
+    const extra = seed.laws.filter((l) => !have.has(l.id));
+    if (extra.length === 0)
+        return { manifest: existing, added: [] };
+    return {
+        manifest: { ...existing, laws: [...existing.laws, ...extra] },
+        added: extra.map((l) => l.id),
+    };
+}
 // ─── Glob matching (the `path` backend) ──────────────────────────────────────
 /**
  * Validate a scope glob without compiling it for use, so generation can fail

package/dist/modules/foundation/register.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { text } from "../../shared/mcp.js";
+import { defineTool, text } from "../../shared/mcp.js";
+import { shouldExpose } from "../../shared/exposure.js";
 import { scaffold } from "./scaffold.js";
 import { doctor } from "./doctor.js";
 import { checkAction } from "./check.js";
@@ -7,77 +8,57 @@ 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().describe("Short project name, e.g. the repo name"),
-    project_description: z
-        .string()
-        .optional()
-        .describe("One-line description of what the project does"),
-    organization: z.string().optional().describe("Company/team name"),
-    stack_summary: z
-        .string()
-        .optional()
-        .describe("e.g. 'Next.js 15 + TypeScript frontend, FastAPI + PostgreSQL backend'"),
-    architecture: z
-        .string()
-        .optional()
-        .describe("e.g. 'hexagonal architecture with bounded contexts'"),
-    test_commands: z
-        .string()
-        .optional()
-        .describe("Real commands, e.g. 'pytest backend/tests && npm run test'"),
-    lint_commands: z
-        .string()
-        .optional()
-        .describe("Real commands, e.g. 'ruff check . && npm run lint && tsc --noEmit'"),
-    branch_pattern: z.string().optional().describe("e.g. 'feature/<ticket-id>-<slug>'"),
-    commit_style: z.string().optional().describe("e.g. 'conventional commits, imperative, English'"),
-    custom_laws: z
-        .string()
-        .optional()
-        .describe("Extra markdown appended to LAWS.md — project-specific binding rules the analysis surfaced"),
-    compass_hints: z
-        .string()
-        .optional()
-        .describe("Markdown bullets with the repo's real entrypoints and common traces, inserted into docs/compass.md"),
-    base_standards_extra: z
-        .string()
-        .optional()
-        .describe("Markdown with any project-specific cross-cutting rules, appended to docs/standards/base-standards.md"),
-    modules_table: z
-        .string()
-        .optional()
-        .describe("Markdown table of the repo's real modules/bounded contexts + one-line responsibility, for docs/standards/architecture.md"),
-    layering_rules: z
-        .string()
-        .optional()
-        .describe("Markdown describing the layers and their allowed dependencies, for docs/standards/architecture.md"),
-    backend_layers: z
-        .string()
-        .optional()
-        .describe("Markdown layer table (Layer | File | Responsibility) from the real backend, for docs/standards/backend-standards.md"),
-    frontend_layers: z
-        .string()
-        .optional()
-        .describe("Markdown layer table from the real frontend, for docs/standards/frontend-standards.md"),
-    versioning_rules: z
-        .string()
-        .optional()
-        .describe("The repo's versioning/release convention, for docs/standards/conventions.md"),
-    documentation_extra: z
-        .string()
-        .optional()
-        .describe("Repo-specific docstring notes (keep only the languages used, the enforced linter), appended to docs/standards/documentation.md"),
+    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(),
 };
-// ─── The foundation module: analyze the repo, then write the constitution ───
-/** Register the foundation MCP tools (init_project, scaffold, configure_agent, doctor). */
-export function registerFoundation(server) {
-    server.registerTool("init_project", {
-        description: "START HERE to initialize speclaw in a project. Returns the analysis questionnaire the agent must answer by reading the target repo, plus the available skill packs. Do NOT guess answers — investigate the codebase (package.json, pyproject.toml, CI config, existing docs) and confirm the pack selection with the user before calling scaffold.",
-        inputSchema: {
-            projectPath: z.string().describe("Absolute path to the project to initialize"),
-        },
-    }, async () => {
+/** Register foundation MCP tools. */
+export function registerFoundation(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("init_project", "Start here to initialize speclaw: returns the analysis questionnaire and packs.", { projectPath: z.string() }, async () => {
         const packs = loadPacks();
         return text({
             instructions: [
@@ -89,67 +70,37 @@ export function registerFoundation(server) {
                 "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: Object.fromEntries(Object.entries(profileShape).map(([key, schema]) => [key, schema.description ?? ""])),
+            profileFields: profileFieldHelp,
             packs,
         });
     });
-    server.registerTool("scaffold", {
-        description: "Write the speclaw setup into a project: the foundation (LAWS.md constitution + granular docs/standards/* + CLAUDE.md + AGENTS.md + docs/compass.md), the lawbook workflow (always), the selected tool packs, multi-IDE symlinks (.claude/.cursor/.codex/.agents), .mcp.json wiring for speclaw, and .gitignore for .speclaw/. Never overwrites existing files. Call init_project first.",
-        inputSchema: {
-            projectPath: z.string().describe("Absolute path to the project"),
-            profile: z.object(profileShape).describe("Project profile gathered by analyzing the repo"),
-            packs: z.array(z.string()).describe("Optional tool pack names (quality, workflow, agents)"),
-            agents: z
-                .array(z.string())
-                .optional()
-                .describe(`Agent ids to configure (symlinks + MCP): ${AGENTS.map((a) => a.id).join(", ")}. Usually the CLI handles this; omit to write content only.`),
-        },
+    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 ?? [])));
-    server.registerTool("configure_agent", {
-        description: "Configure one agent's integration in an already-scaffolded project: create its IDE symlinks into ai-specs and register the speclaw MCP server in its config. Re-runnable; add agents one at a time.",
-        inputSchema: {
-            projectPath: z.string().describe("Absolute path to the project"),
-            agent: z
-                .enum(AGENTS.map((a) => a.id))
-                .describe("Agent id to configure"),
-        },
+    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);
     });
-    server.registerTool("speclaw_check", {
-        // ≤12 words: this is invoked by speclaw's hooks, never called directly.
-        description: "Invoked by speclaw's hooks to enforce laws — do not call directly.",
-        inputSchema: {
-            projectPath: z.string().describe("Absolute path to the project"),
-            event: z
-                .enum(["PreToolUse", "PostToolUse", "Stop", "InstructionsLoaded"])
-                .describe("The hook event that fired"),
-            toolName: z.string().optional().describe("The tool the agent is invoking, when relevant"),
-            payload: z.record(z.unknown()).describe("The raw hook event payload from the agent"),
-        },
+    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 })));
-    server.registerTool("law_verify", {
-        // ≤30 words: the batch counterpart to speclaw_check, for the Stop hook and CI.
-        description: "Verify the project's deterministic laws (dependency and graph rules) and return violations by file. Run before claiming an architecture task done.",
-        inputSchema: {
-            projectPath: z.string().describe("Absolute path to the project"),
-            paths: z
-                .array(z.string())
-                .optional()
-                .describe("Restrict to source files under these project-relative paths"),
-            engines: z
-                .array(z.enum(["deps", "graph"]))
-                .optional()
-                .describe("Which batch engines to run; omit for all"),
-            lawIds: z.array(z.string()).optional().describe("Restrict to these law ids"),
-        },
+    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 })));
-    server.registerTool("doctor", {
-        description: "Verify a speclaw installation: ai-specs presence, the foundation (LAWS.md + standards + agent contracts), IDE symlinks health, the lawbook/ workflow, the Compass index, and .mcp.json wiring. Returns a checklist with remediation hints.",
-        inputSchema: { projectPath: z.string().describe("Absolute path to the project") },
-    }, async ({ projectPath }) => {
+    add("doctor", "Verify the speclaw install: foundation, symlinks, lawbook, Compass, and MCP wiring.", { projectPath: z.string() }, async ({ projectPath }) => {
         const checks = doctor(projectPath);
         const failed = checks.filter((c) => !c.ok);
         return text({

package/dist/modules/foundation/report-md.js

@@ -0,0 +1,33 @@
+/**
+ * Markdown projection of a {@link VerifyReport} for `$GITHUB_STEP_SUMMARY`
+ * (and stdout `--format markdown`). Honest by construction: it lists findings
+ * and skips, and never claims a requirement is covered (trace is not in this
+ * slice).
+ *
+ * @param report - The batch report.
+ */
+export function toMarkdown(report) {
+    const lines = [
+        "## speclaw · law verification",
+        "",
+        `**${report.summary.passed}** passed · **${report.summary.failed}** failed · **${report.summary.skipped}** skipped · **${report.summary.unknown}** unknown`,
+        "",
+    ];
+    if (report.findings.length > 0) {
+        lines.push("### Findings", "", "| Law | Severity | Location |", "| :-- | :-- | :-- |");
+        for (const f of report.findings) {
+            const at = f.line ? `${f.file}:${f.line}` : f.file;
+            lines.push(`| \`${f.lawId}\` | ${f.severity} | \`${at}\` |`);
+        }
+        lines.push("");
+    }
+    if (report.skipped.length > 0) {
+        lines.push("<details><summary>Not evaluated</summary>", "");
+        for (const s of report.skipped) {
+            lines.push(`- \`${s.lawId}\` — ${s.reason}${s.detail ? `: ${s.detail}` : ""}`);
+        }
+        lines.push("", "</details>", "");
+    }
+    lines.push("_Deterministic · no model · no network. Reproduce with `speclaw verify`._", "");
+    return lines.join("\n");
+}