@esneiderbravo/speclaw 0.3.5 → 0.3.8

package/dist/modules/foundation/graph.js

@@ -1,14 +1,17 @@
 import { underPaths } from "./verify-model.js";
 /** Build the cross-file dependency graph, restricted to `paths` when given. */
-function buildGraph(db, paths) {
+function buildGraph(db, paths, edgeKinds) {
+    const kindFilter = edgeKinds && edgeKinds.length > 0
+        ? ` AND e.kind IN (${edgeKinds.map(() => "?").join(", ")})`
+        : "";
     const rows = db
         .prepare(`SELECT DISTINCT sf.path AS src, df.path AS dst
        FROM edges e
        JOIN files sf ON sf.id = e.src_file_id
        JOIN nodes dn ON dn.id = e.dst_node_id
        JOIN files df ON df.id = dn.file_id
-       WHERE e.dst_node_id IS NOT NULL AND sf.path <> df.path`)
-        .all();
+       WHERE e.dst_node_id IS NOT NULL AND sf.path <> df.path${kindFilter}`)
+        .all(...(edgeKinds && edgeKinds.length > 0 ? edgeKinds : []));
     const adj = new Map();
     for (const { src, dst } of rows) {
         if (!underPaths(src, paths) || !underPaths(dst, paths))
@@ -203,7 +206,7 @@ function reachableFindings(law, rule, adj) {
  */
 export function runGraphLaw(db, law, paths) {
     const rule = law.verification.rule;
-    const adj = buildGraph(db, paths);
+    const adj = buildGraph(db, paths, rule.edgeKinds);
     const findings = [];
     const wantReachable = rule.reachable === true && rule.from != null && rule.to != null;
     const wantCircular = rule.circular === true || (!rule.circular && !wantReachable);

package/dist/modules/foundation/hooks.js

@@ -3,12 +3,24 @@ import path from "node:path";
 import { agentById } from "../../shared/agents.js";
 import { sha256 } from "../../shared/install.js";
 import { globError, hasBackend } from "./laws.js";
+/** Claude Code `${path}` templates — see https://code.claude.com/docs/en/hooks */
+const SPECLAW_HOOK_INPUT = {
+    projectPath: "${cwd}",
+    event: "${hook_event_name}",
+    toolName: "${tool_name}",
+    payload: {
+        hook_event_name: "${hook_event_name}",
+        tool_name: "${tool_name}",
+        tool_input: { file_path: "${tool_input.file_path}" },
+    },
+};
 /** The speclaw hook object — its `{type, server}` pair is the merge identity. */
 const SPECLAW_HOOK = {
     type: "mcp_tool",
     server: "speclaw",
     tool: "speclaw_check",
     timeout: 5,
+    input: SPECLAW_HOOK_INPUT,
 };
 /** Tool-name matcher for the file-mutating tools the `path` backend can evaluate. */
 const MUTATION_MATCHER = "Write|Edit|MultiEdit|NotebookEdit";

package/dist/modules/foundation/laws.js

@@ -22,6 +22,7 @@ const graphRuleSchema = z.object({
     reachable: z.boolean().optional(),
     from: z.string().optional(),
     to: z.string().optional(),
+    edgeKinds: z.array(z.string()).optional(),
 });
 const verificationSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("path") }),

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

@@ -0,0 +1,108 @@
+import { z } from "zod";
+import { defineTool, text } from "../../shared/mcp.js";
+import { shouldExpose } from "../../shared/exposure.js";
+import { scaffold } from "./scaffold.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(),
+};
+function makeAdd(server, minimal) {
+    return (name, description, inputSchema, handler) => {
+        if (!shouldExpose(name, minimal))
+            return;
+        defineTool(server, { name, description, inputSchema, handler });
+    };
+}
+/**
+ * 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`.
+ */
+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);
+    });
+    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 })));
+}

package/dist/modules/foundation/register.js

@@ -1,114 +1,26 @@
 import { z } from "zod";
 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";
-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(),
-};
-/** Register foundation MCP tools. */
+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). */
 export function registerFoundation(server, opts = {}) {
+    registerFoundationCore(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: [
-                "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);
+    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);
-    });
-    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 })));
-    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({
-            healthy: failed.length === 0,
-            checks,
-            summary: failed.length === 0
-                ? "Everything is within the law."
-                : `${failed.length} check(s) failed — see details.`,
-        });
+    };
+    defineTool(server, {
+        name: "doctor",
+        description: DOCTOR_DESCRIPTION,
+        inputSchema,
+        handler,
     });
 }