@esneiderbravo/speclaw 0.3.1 → 0.3.3

package/dist/modules/foundation/register.js

@@ -2,6 +2,8 @@ import { z } from "zod";
 import { text } from "../../shared/mcp.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";
@@ -116,6 +118,34 @@ export function registerFoundation(server) {
         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"),
+        },
+    }, 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"),
+        },
+    }, 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") },

package/dist/modules/foundation/scaffold.js

@@ -8,6 +8,8 @@ import { installWorkflow } from "../lawbook/register.js";
 import { installPack, loadPacks } from "../tools/packs.js";
 import { readManifest, writeManifest } from "../../shared/manifest.js";
 import { pkgVersion } from "../../shared/version.js";
+import { readLawManifest, seedManifest, writeLawManifest } from "./laws.js";
+import { installHooks } from "./hooks.js";
 const ASSETS = assetsDir(import.meta.url);
 // Every {{var}} the foundation templates may reference. Ones the agent didn't
 // provide default to empty so a bare `scaffold` never leaves a raw {{tag}}.
@@ -22,6 +24,21 @@ const FOUNDATION_DEFAULTS = {
     versioning_rules: "",
     documentation_extra: "",
 };
+/**
+ * Ensure the project has a law manifest, seeding it from the package's starter
+ * laws when absent. The manifest is a derived artifact under the gitignored
+ * `.speclaw/`; seeding only when missing keeps a curated manifest (the MVP's
+ * authoring surface until executable-laws) from being overwritten on update.
+ */
+function ensureLawManifest(projectPath, report) {
+    const existing = readLawManifest(projectPath);
+    if (existing)
+        return existing;
+    const seed = seedManifest();
+    writeLawManifest(projectPath, seed);
+    report.written.push(path.join(projectPath, ".speclaw", "laws-manifest.json"));
+    return seed;
+}
 /**
  * Render the foundation: walk the module's assets/, mirror its structure into
  * the project, stripping the `.template` marker (foo.template.md -> foo.md).
@@ -110,6 +127,15 @@ export function scaffold(projectPath, profile, packNames, agents = [], opts = {}
     ensureGitignore(projectPath, "ai-specs/", "speclaw workflow content (regenerated by init/update; never commit)", report);
     for (const id of agents)
         configureAgent(projectPath, id, report); // only the chosen agents
+    // Compile the declared laws into agent hooks for every hook-capable agent just
+    // configured. The seam is the manifest: check-dispatcher enforces `path` laws;
+    // executable-laws will extend the same manifest with more backends.
+    const lawManifest = ensureLawManifest(projectPath, report);
+    report.hooks = installHooks(projectPath, agents, lawManifest, report, {
+        baselines: managedOpts.baselines,
+        backup: managedOpts.backup,
+        record,
+    });
     // Record what was installed so `speclaw update` can re-apply these packs and
     // gate feature migrations by version, plus the managed-file baselines that let
     // a later update tell user edits from stale files.

package/dist/modules/foundation/verify.js

@@ -0,0 +1,107 @@
+import { performance } from "node:perf_hooks";
+import { openDb, indexExists } from "../compass/db.js";
+import { hasBatchBackend, readLawManifest } from "./laws.js";
+import { runDepsLaw } from "./deps.js";
+import { runGraphLaw } from "./graph.js";
+/** True when `file` (POSIX, project-relative) is at or under one of `paths`. */
+export function underPaths(file, paths) {
+    if (!paths || paths.length === 0)
+        return true;
+    return paths.some((p) => {
+        const norm = p.replace(/\/+$/, "");
+        return file === norm || file.startsWith(norm + "/");
+    });
+}
+/**
+ * Verify the project's deterministic `deps`/`graph` laws against the Compass
+ * index and return a four-state report.
+ *
+ * When the project has no index, every selected batch law is reported as
+ * `skipped` with reason `no-index` (never silently passed). Each evaluated law
+ * lands in exactly one of `passed` / `failed` / `unknown`: it fails when the
+ * engine produced a finding, is `unknown` when it produced none but rests on
+ * unresolved edges (which could hide a violation), and passes otherwise.
+ *
+ * @param args - The project, and optional `paths` / `engines` / `lawIds` filters.
+ * @returns The {@link VerifyReport}.
+ */
+export function verifyLaws(args) {
+    const start = performance.now();
+    const findings = [];
+    const skipped = [];
+    const unknown = [];
+    let passed = 0;
+    let failed = 0;
+    const done = () => ({
+        schemaVersion: 1,
+        summary: {
+            evaluated: passed + failed + unknown.length,
+            passed,
+            failed,
+            skipped: skipped.length,
+            unknown: unknown.length,
+        },
+        findings,
+        skipped,
+        unknown,
+        elapsedMs: performance.now() - start,
+    });
+    const manifest = readLawManifest(args.projectPath);
+    if (!manifest)
+        return done();
+    const engines = args.engines;
+    const selected = manifest.laws.filter((law) => {
+        if (!hasBatchBackend(law))
+            return false;
+        if (args.lawIds && !args.lawIds.includes(law.id))
+            return false;
+        if (engines && !engines.includes(law.verification.kind))
+            return false;
+        return true;
+    });
+    if (selected.length === 0)
+        return done();
+    if (!indexExists(args.projectPath)) {
+        for (const law of selected) {
+            skipped.push({
+                lawId: law.id,
+                reason: "no-index",
+                detail: "no .speclaw/index.db — build it with the compass_index tool",
+            });
+        }
+        return done();
+    }
+    const db = openDb(args.projectPath);
+    try {
+        for (const law of selected) {
+            let result;
+            try {
+                result =
+                    law.verification.kind === "deps"
+                        ? runDepsLaw(db, law, args.paths)
+                        : runGraphLaw(db, law, args.paths);
+            }
+            catch (err) {
+                skipped.push({ lawId: law.id, reason: "engine-error", detail: err.message });
+                continue;
+            }
+            findings.push(...result.findings);
+            if (result.findings.length > 0) {
+                failed++;
+            }
+            else if (result.unresolved > 0) {
+                unknown.push({
+                    lawId: law.id,
+                    detail: `evaluated with ${result.unresolved} unresolved reference(s) — result unknown`,
+                });
+            }
+            else {
+                passed++;
+            }
+        }
+    }
+    finally {
+        db.close();
+    }
+    return done();
+}

package/dist/shared/agents.js

@@ -9,6 +9,7 @@ export const AGENTS = [
         ideDir: ".claude",
         linkTargets: ["skills", "commands", "agents"],
         mcpFile: ".mcp.json",
+        hooks: { file: ".claude/settings.json", key: "hooks" },
     },
     {
         id: "cursor",

package/package.json

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