@esneiderbravo/speclaw 0.3.2 → 0.3.3

package/README.md

@@ -82,7 +82,7 @@ too (also `pnpm dlx` / `yarn dlx`) — but installing globally means you can run
 
 | Module | What it does |
 | :-- | :-- |
-| **Foundation** | The project's constitution: `LAWS.md` binding a set of granular standards under `docs/standards/` (base, architecture, backend, frontend, testing, documentation, conventions, lawbook), plus strict `CLAUDE.md` / `AGENTS.md` agent contracts — filled from your real codebase. It also **enforces** them: blocking laws compile into agent hooks that deny a forbidden edit at the keystroke (`speclaw check` / `speclaw_check`). |
+| **Foundation** | The project's constitution: `LAWS.md` binding a set of granular standards under `docs/standards/` (base, architecture, backend, frontend, testing, documentation, conventions, lawbook), plus strict `CLAUDE.md` / `AGENTS.md` agent contracts — filled from your real codebase. It also **enforces** them: blocking laws compile into agent hooks that deny a forbidden edit at the keystroke (`speclaw check` / `speclaw_check`), and architectural laws are verified deterministically against the Compass graph — dependency rules (`deps`) and cycles (`graph`) — via `speclaw laws verify` / `law_verify`, which reports each law as passed, failed, skipped, or unknown (an unresolved reference is *unknown*, never a silent pass). |
 | **Compass** | speclaw's own local code graph. Parses your code (tree-sitter) into nodes + edges plus a local vector store, so an agent finds and understands code with a fraction of the tokens a grep/read loop would cost. No LLM, 100% local, lives in `.speclaw/` (gitignored). |
 | **Lawbook** | speclaw's own spec-driven workflow: `draft → build → sync → archive` (and `explore`), backed by `lawbook_*` engine tools. No external CLI. |
 | **Tools** | Opt-in packs of skills and subagents (currently the dev-agents) that agents use for specific tasks. |

package/dist/cli/commands/laws.js

@@ -0,0 +1,48 @@
+import { list } from "../lib/args.js";
+import { ui, c } from "../lib/ui.js";
+import { verifyLaws } from "../../modules/foundation/verify.js";
+/**
+ * `speclaw laws <subcommand>` — the CLI twin of the batch law tools. Today it
+ * exposes `verify`, the twin of the `law_verify` MCP tool: it runs the project's
+ * deterministic `deps`/`graph` laws against the Compass index and prints the
+ * four-state result. Both transports delegate to the same {@link verifyLaws}
+ * core, so the CLI and the tool never diverge.
+ *
+ * - `laws verify [--engine deps,graph] [--path a,b] [--law id1,id2] [--json]`
+ *
+ * @param flags - Parsed CLI flags; `flags._[0]` is the subcommand.
+ */
+export async function runLaws(flags) {
+    const sub = flags._[0];
+    if (sub !== "verify") {
+        ui.err(`Unknown laws subcommand: ${sub ?? "(none)"} — try ${ui.code("speclaw laws verify")}.`);
+        process.exit(1);
+    }
+    const engines = list(flags.engine).filter((e) => e === "deps" || e === "graph");
+    const report = verifyLaws({
+        projectPath: process.cwd(),
+        paths: list(flags.path).length ? list(flags.path) : undefined,
+        engines: engines.length ? engines : undefined,
+        lawIds: list(flags.law).length ? list(flags.law) : undefined,
+    });
+    if (flags.json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    const { summary } = report;
+    ui.heading("speclaw laws verify");
+    ui.info(`${summary.passed} passed · ${c.red(String(summary.failed))} failed · ` +
+        `${summary.skipped} skipped · ${summary.unknown} unknown ` +
+        `(${report.elapsedMs.toFixed(1)} ms)`);
+    for (const f of report.findings) {
+        const at = f.line ? `${f.file}:${f.line}` : f.file;
+        ui.warn(`${c.cream(f.lawId)} — ${at}${f.detail ? ` ${f.detail}` : ""}`);
+    }
+    for (const u of report.unknown)
+        ui.plain(`  ? ${c.cream(u.lawId)} — ${u.detail}`);
+    for (const s of report.skipped) {
+        ui.plain(`  – ${c.cream(s.lawId)} — skipped: ${s.reason}${s.detail ? ` (${s.detail})` : ""}`);
+    }
+    if (report.findings.length === 0 && summary.evaluated > 0)
+        ui.ok("No violations.");
+}

package/dist/cli/index.js

@@ -35,6 +35,7 @@ Lawbook (spec-driven workflow)
 Other
   doctor                   Verify the installation
   check                    Evaluate an action against the laws (hooks call this; --dry-run to preview)
+  laws verify              Verify the deterministic dependency/graph laws against the index
   mcp                      Start the MCP server (used by your agent's config)
   help                     Show this help
   --version                Print the installed speclaw version
@@ -113,6 +114,8 @@ async function dispatch(cmd, flags) {
             return (await import("./commands/doctor.js")).runDoctor(flags);
         case "check":
             return (await import("./commands/check.js")).runCheck(flags);
+        case "laws":
+            return (await import("./commands/laws.js")).runLaws(flags);
         default:
             ui.err(`Unknown command: ${cmd}`);
             console.log(HELP);

package/dist/modules/foundation/deps.js

@@ -0,0 +1,117 @@
+import { underPaths } from "./verify.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)] ?? "");
+}
+/** The `IN (?, ?)` clause and params for an optional edge-kind filter. */
+function edgeKindClause(edgeKinds) {
+    if (!edgeKinds || edgeKinds.length === 0)
+        return { sql: "", params: [] };
+    return { sql: ` AND e.kind IN (${edgeKinds.map(() => "?").join(", ")})`, params: edgeKinds };
+}
+/** Load resolved file→file edges (earliest line per pair) from the index. */
+function resolvedEdges(db, edgeKinds) {
+    const kind = edgeKindClause(edgeKinds);
+    return db
+        .prepare(`SELECT sf.path AS src, df.path AS dst, MIN(e.line) AS line
+       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${kind.sql}
+       GROUP BY sf.path, df.path`)
+        .all(...kind.params);
+}
+/** Count unresolved edges (`dst_node_id IS NULL`) per source file. */
+function unresolvedBySource(db, edgeKinds) {
+    const kind = edgeKindClause(edgeKinds);
+    return db
+        .prepare(`SELECT sf.path AS src, COUNT(*) AS n
+       FROM edges e
+       JOIN files sf ON sf.id = e.src_file_id
+       WHERE e.dst_node_id IS NULL${kind.sql}
+       GROUP BY sf.path`)
+        .all(...kind.params);
+}
+/**
+ * Evaluate one `deps` law against the index.
+ *
+ * A `forbidden` rule emits a finding for every resolved edge whose source
+ * matches `from` and whose destination matches `to` (excluding `toNot`); a
+ * `required` rule emits a finding for every `from` file with no resolved edge to
+ * any `to` destination. `from` may carry a capture group referenced as `$1` in
+ * `to`/`toNot`, so one rule expresses "no feature imports another feature".
+ *
+ * @param db - An open connection to the project's index.
+ * @param law - The `deps` law to evaluate.
+ * @param paths - Optional project-relative paths restricting the source files.
+ * @returns The findings and the count of unresolved in-scope edges.
+ */
+export function runDepsLaw(db, law, paths) {
+    const rule = law.verification.rule;
+    const fromRe = new RegExp(rule.from);
+    const type = rule.type ?? "forbidden";
+    const findings = [];
+    const inScope = (src) => underPaths(src, paths) ? src.match(fromRe) : null;
+    const matchesTo = (dst, m) => {
+        const toRe = new RegExp(applyGroups(rule.to, m));
+        if (!toRe.test(dst))
+            return false;
+        if (rule.toNot && new RegExp(applyGroups(rule.toNot, m)).test(dst))
+            return false;
+        return true;
+    };
+    const edges = resolvedEdges(db, rule.edgeKinds);
+    if (type === "forbidden") {
+        for (const e of edges) {
+            const m = inScope(e.src);
+            if (!m)
+                continue;
+            if (matchesTo(e.dst, m)) {
+                findings.push({
+                    lawId: law.id,
+                    severity: law.severity,
+                    engine: "deps",
+                    file: e.src,
+                    line: e.line,
+                    message: law.prose,
+                    detail: `→ ${e.dst}`,
+                });
+            }
+        }
+    }
+    else {
+        // required: every `from` file must have at least one edge to a `to` file.
+        const bySrc = new Map();
+        for (const e of edges) {
+            const list = bySrc.get(e.src);
+            if (list)
+                list.push(e);
+            else
+                bySrc.set(e.src, [e]);
+        }
+        const files = db.prepare("SELECT path FROM files").all().map((r) => r.path);
+        for (const src of files) {
+            const m = inScope(src);
+            if (!m)
+                continue;
+            const satisfied = (bySrc.get(src) ?? []).some((e) => matchesTo(e.dst, m));
+            if (!satisfied) {
+                findings.push({
+                    lawId: law.id,
+                    severity: law.severity,
+                    engine: "deps",
+                    file: src,
+                    message: law.prose,
+                    detail: `required dependency to ${rule.to} is missing`,
+                });
+            }
+        }
+    }
+    let unresolved = 0;
+    for (const row of unresolvedBySource(db, rule.edgeKinds)) {
+        if (inScope(row.src))
+            unresolved += row.n;
+    }
+    return { findings, unresolved };
+}

package/dist/modules/foundation/doctor.js

@@ -1,7 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { AGENTS, agentById, detectConfiguredAgents } from "../../shared/agents.js";
-import { globError, hasBackend, readLawManifest } from "./laws.js";
+import { globError, hasBackend, hasBatchBackend, readLawManifest } from "./laws.js";
 /**
  * Run the speclaw installation health checks against a project: ai-specs and
  * LAWS.md presence, agent contracts, the docs/standards set, per-agent IDE
@@ -136,20 +136,35 @@ function lawEnforcementChecks(projectPath, checks) {
         });
         return;
     }
-    const withBackend = manifest.laws.filter(hasBackend);
-    const noBackend = manifest.laws.filter((l) => !hasBackend(l));
+    const withPath = manifest.laws.filter(hasBackend);
+    const withBatch = manifest.laws.filter(hasBatchBackend);
+    const noBackend = manifest.laws.filter((l) => !hasBackend(l) && !hasBatchBackend(l));
     checks.push({
         name: "law manifest",
         ok: true,
-        detail: `${manifest.laws.length} law(s): ${withBackend.length} enforced (path)` +
+        detail: `${manifest.laws.length} law(s): ${withPath.length} enforced (path), ` +
+            `${withBatch.length} verified (deps/graph)` +
             (noBackend.length
                 ? `, ${noBackend.length} declared without a backend yet (${noBackend
                     .map((l) => l.id)
                     .join(", ")})`
                 : ""),
     });
-    // Glob validation — a malformed scope must fail loudly here, never silently
-    // match zero files at runtime.
+    // Graph-engine availability — the deps/graph backends need the Compass index.
+    if (withBatch.length > 0) {
+        const indexed = fs.existsSync(path.join(projectPath, ".speclaw", "index.db"));
+        checks.push({
+            name: "graph law engines",
+            ok: indexed,
+            detail: indexed
+                ? `index present — ${withBatch.length} deps/graph law(s) evaluable via \`speclaw laws verify\``
+                : `${withBatch.length} deps/graph law(s) will be skipped (no-index) — run the \`compass_index\` tool`,
+        });
+    }
+    // Glob validation — a malformed scope glob must fail loudly here, never
+    // silently match zero files at runtime. (A malformed deps/graph regex is
+    // rejected earlier, when the manifest is validated, so a manifest that reaches
+    // here has none.)
     const badGlobs = [];
     for (const law of manifest.laws) {
         for (const pattern of law.scope) {

package/dist/modules/foundation/graph.js

@@ -0,0 +1,215 @@
+import { underPaths } from "./verify.js";
+/** Build the cross-file dependency graph, restricted to `paths` when given. */
+function buildGraph(db, paths) {
+    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();
+    const adj = new Map();
+    for (const { src, dst } of rows) {
+        if (!underPaths(src, paths) || !underPaths(dst, paths))
+            continue;
+        const list = adj.get(src);
+        if (list)
+            list.push(dst);
+        else
+            adj.set(src, [dst]);
+        if (!adj.has(dst))
+            adj.set(dst, []);
+    }
+    return adj;
+}
+/**
+ * Iterative Tarjan strongly-connected-components. Written with an explicit work
+ * stack so a deep import chain cannot overflow the call stack.
+ *
+ * @param adj - The directed graph.
+ * @returns The list of SCCs, each a list of node ids.
+ */
+export function tarjanSCC(adj) {
+    const index = new Map();
+    const low = new Map();
+    const onStack = new Set();
+    const stack = [];
+    const sccs = [];
+    let counter = 0;
+    for (const root of adj.keys()) {
+        if (index.has(root))
+            continue;
+        const work = [{ node: root, i: 0 }];
+        while (work.length > 0) {
+            const frame = work[work.length - 1];
+            const { node } = frame;
+            if (frame.i === 0) {
+                index.set(node, counter);
+                low.set(node, counter);
+                counter++;
+                stack.push(node);
+                onStack.add(node);
+            }
+            const neighbors = adj.get(node) ?? [];
+            if (frame.i < neighbors.length) {
+                const next = neighbors[frame.i];
+                frame.i++;
+                if (!index.has(next)) {
+                    work.push({ node: next, i: 0 });
+                }
+                else if (onStack.has(next)) {
+                    low.set(node, Math.min(low.get(node), index.get(next)));
+                }
+                continue;
+            }
+            // All neighbors visited: settle this node, propagating low-links up.
+            if (low.get(node) === index.get(node)) {
+                const scc = [];
+                for (;;) {
+                    const w = stack.pop();
+                    onStack.delete(w);
+                    scc.push(w);
+                    if (w === node)
+                        break;
+                }
+                sccs.push(scc);
+            }
+            work.pop();
+            const parent = work[work.length - 1];
+            if (parent)
+                low.set(parent.node, Math.min(low.get(parent.node), low.get(node)));
+        }
+    }
+    return sccs;
+}
+/**
+ * The shortest cycle passing through `start`, via BFS over the induced subgraph.
+ *
+ * @param start - The node to find a return path to.
+ * @param within - The set of nodes the search is restricted to (one SCC).
+ * @param adj - The full graph.
+ * @returns The cycle as an ordered node list `[start, …]`, or null if none.
+ */
+function shortestCycleThrough(start, within, adj) {
+    const parent = new Map();
+    const visited = new Set([start]);
+    let queue = [start];
+    while (queue.length > 0) {
+        const next = [];
+        for (const node of queue) {
+            for (const neighbor of adj.get(node) ?? []) {
+                if (!within.has(neighbor))
+                    continue;
+                if (neighbor === start) {
+                    // Reconstruct start → … → node, which closes back to start.
+                    const path = [node];
+                    let cur = node;
+                    while (cur !== start) {
+                        cur = parent.get(cur);
+                        path.push(cur);
+                    }
+                    path.reverse();
+                    return path;
+                }
+                if (!visited.has(neighbor)) {
+                    visited.add(neighbor);
+                    parent.set(neighbor, node);
+                    next.push(neighbor);
+                }
+            }
+        }
+        queue = next;
+    }
+    return null;
+}
+/** Findings for the `circular` rule: one minimal cycle per multi-node SCC. */
+function circularFindings(law, adj) {
+    const findings = [];
+    for (const scc of tarjanSCC(adj)) {
+        if (scc.length < 2)
+            continue;
+        const within = new Set(scc);
+        let best = null;
+        for (const node of scc) {
+            const cycle = shortestCycleThrough(node, within, adj);
+            if (cycle && (best === null || cycle.length < best.length))
+                best = cycle;
+        }
+        if (!best)
+            continue;
+        findings.push({
+            lawId: law.id,
+            severity: law.severity,
+            engine: "graph",
+            file: best[0],
+            message: law.prose,
+            detail: `cycle: ${[...best, best[0]].join(" → ")} (SCC size ${scc.length})`,
+        });
+    }
+    return findings;
+}
+/** Findings for the `reachable` rule: a `from` file transitively reaches a `to` file. */
+function reachableFindings(law, rule, adj) {
+    const fromRe = new RegExp(rule.from);
+    const toRe = new RegExp(rule.to);
+    const findings = [];
+    for (const src of adj.keys()) {
+        if (!fromRe.test(src))
+            continue;
+        const seen = new Set([src]);
+        let queue = [src];
+        let hit = null;
+        while (queue.length > 0 && !hit) {
+            const next = [];
+            for (const node of queue) {
+                for (const neighbor of adj.get(node) ?? []) {
+                    if (seen.has(neighbor))
+                        continue;
+                    if (toRe.test(neighbor)) {
+                        hit = neighbor;
+                        break;
+                    }
+                    seen.add(neighbor);
+                    next.push(neighbor);
+                }
+                if (hit)
+                    break;
+            }
+            queue = next;
+        }
+        if (hit) {
+            findings.push({
+                lawId: law.id,
+                severity: law.severity,
+                engine: "graph",
+                file: src,
+                message: law.prose,
+                detail: `transitively reaches ${hit}`,
+            });
+        }
+    }
+    return findings;
+}
+/**
+ * Evaluate one `graph` law: forbidden dependency cycles and/or forbidden
+ * transitive reachability, over the file-level import graph.
+ *
+ * @param db - An open connection to the project's index.
+ * @param law - The `graph` law to evaluate.
+ * @param paths - Optional project-relative paths restricting the graph.
+ * @returns The findings; `unresolved` is always 0 (cycles are read off the
+ *   resolved graph, so a graph law never reports an unknown here).
+ */
+export function runGraphLaw(db, law, paths) {
+    const rule = law.verification.rule;
+    const adj = buildGraph(db, paths);
+    const findings = [];
+    const wantReachable = rule.reachable === true && rule.from != null && rule.to != null;
+    const wantCircular = rule.circular === true || (!rule.circular && !wantReachable);
+    if (wantCircular)
+        findings.push(...circularFindings(law, adj));
+    if (wantReachable)
+        findings.push(...reachableFindings(law, rule, adj));
+    return { findings, unresolved: 0 };
+}

package/dist/modules/foundation/laws.js

@@ -8,6 +8,31 @@ import { assetsDir } from "../../shared/paths.js";
 // backend; executable-laws extends the same model with `ast`/`deps`/`process`
 // backends by filling in more `verification.kind` cases — it never rewrites it.
 const ASSETS = assetsDir(import.meta.url);
+const depsRuleSchema = z.object({
+    name: z.string().optional(),
+    from: z.string(),
+    to: z.string(),
+    toNot: z.string().optional(),
+    type: z.enum(["forbidden", "required"]).optional(),
+    edgeKinds: z.array(z.string()).optional(),
+});
+const graphRuleSchema = z.object({
+    name: z.string().optional(),
+    circular: z.boolean().optional(),
+    reachable: z.boolean().optional(),
+    from: z.string().optional(),
+    to: z.string().optional(),
+});
+const verificationSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("path") }),
+    z.object({ kind: z.literal("deps"), rule: depsRuleSchema }),
+    z.object({ kind: z.literal("graph"), rule: graphRuleSchema }),
+    z.object({ kind: z.literal("ast") }),
+    z.object({ kind: z.literal("process") }),
+    z.object({ kind: z.literal("traceability") }),
+    z.object({ kind: z.literal("semantic") }),
+    z.object({ kind: z.literal("none") }),
+]);
 const lawSchema = z.object({
     id: z.string().min(1),
     title: z.string().min(1),
@@ -15,22 +40,70 @@ const lawSchema = z.object({
     severity: z.enum(["error", "warn", "info"]),
     scope: z.array(z.string()),
     prose: z.string().min(1),
-    verification: z.object({
-        kind: z.enum(["path", "ast", "graph", "deps", "process", "traceability", "semantic", "none"]),
-    }),
+    verification: verificationSchema,
     enforcement: z.enum(["bloqueo", "feedback", "gate"]),
     source: z.object({ file: z.string(), line: z.number().optional() }),
 });
-const manifestSchema = z.object({
+// Reject a malformed `from`/`to` regex when the manifest is validated — naming
+// the law id, not a bare array index — rather than letting it explode at verify
+// time. Mirrors the generation-time treatment of malformed globs.
+const manifestSchema = z
+    .object({
     version: z.number(),
     laws: z.array(lawSchema),
+})
+    .superRefine((manifest, ctx) => {
+    manifest.laws.forEach((law, i) => {
+        const v = law.verification;
+        const patterns = [];
+        if (v.kind === "deps") {
+            patterns.push(["from", v.rule.from], ["to", v.rule.to], ["toNot", v.rule.toNot]);
+        }
+        else if (v.kind === "graph") {
+            patterns.push(["from", v.rule.from], ["to", v.rule.to]);
+        }
+        for (const [field, pattern] of patterns) {
+            if (pattern == null)
+                continue;
+            const err = regexError(pattern);
+            if (err) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ["laws", i, "verification", "rule", field],
+                    message: `${law.id}: verification.rule.${field} is not a valid regular expression (${err})`,
+                });
+            }
+        }
+    });
 });
-/** The verification backends this change actually evaluates at runtime. */
+/** Backends evaluated on the action-time hot path (`speclaw_check`) — glob only. */
 export const IMPLEMENTED_BACKENDS = ["path"];
-/** True when a law's verification backend is evaluated at runtime (only `path` today). */
+/** Backends evaluated by the batch verifier (`law_verify`) — they read the index. */
+export const BATCH_BACKENDS = ["deps", "graph"];
+/** True when a law is evaluated on the action-time hot path (only `path` today). */
 export function hasBackend(law) {
     return IMPLEMENTED_BACKENDS.includes(law.verification.kind);
 }
+/** True when a law is evaluated by the batch verifier (`deps`/`graph`). */
+export function hasBatchBackend(law) {
+    return BATCH_BACKENDS.includes(law.verification.kind);
+}
+/**
+ * Validate a regular expression without using it, so manifest generation and
+ * `doctor` can fail loudly on a malformed `from`/`to` pattern.
+ *
+ * @param pattern - A regular-expression source string.
+ * @returns An error message if the pattern does not compile, else null.
+ */
+export function regexError(pattern) {
+    try {
+        new RegExp(pattern);
+        return null;
+    }
+    catch (err) {
+        return err.message;
+    }
+}
 /** Absolute path to a project's compiled law manifest (under the gitignored `.speclaw/`). */
 export function manifestPath(projectPath) {
     return path.join(projectPath, ".speclaw", "laws-manifest.json");

package/dist/modules/foundation/register.js

@@ -3,6 +3,7 @@ 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";
@@ -129,6 +130,22 @@ export function registerFoundation(server) {
             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/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/package.json

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