@esneiderbravo/speclaw 0.3.2 → 0.3.4

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 verify` (CI orchestrator: exit codes, SARIF, markdown) and `speclaw laws verify` / `law_verify`. Each law is reported 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. |
@@ -210,6 +210,35 @@ context. Agents without hooks (Cursor, Codex) enforce the same laws in CI via
 
 <br/>
 
+## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; Verify in CI
+
+`speclaw verify` evaluates your `deps` and `graph` laws against the local Compass
+index. It is deterministic: **no model, no API key, no network.**
+
+```bash
+speclaw verify --ci --sarif speclaw.sarif --json speclaw.json
+```
+
+| Exit | Meaning |
+| :-- | :-- |
+| **0** | No findings at or above `--fail-on` (default `error`) |
+| **1** | At least one finding at or above `--fail-on` |
+| **2** | Usage error (unknown `--fail-on` / `--format`) |
+| **3** | Environment (shallow clone under `--ci`, or an unwritable `--sarif`/`--json` path) |
+| **4** | At least one law was skipped, and `--strict-engines` was set |
+
+On GitHub:
+
+```yaml
+- uses: esneiderbravo/speclaw@v1
+```
+
+`init` / `update` write `.github/workflows/speclaw.yml` only when that path is
+missing — they never overwrite your CI. Make the check required in branch
+protection yourself; speclaw does not.
+
+<br/>
+
 ## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; Staying up to date
 
 speclaw checks for new releases in the background (at most once a day) and nudges

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/commands/update.js

@@ -60,6 +60,13 @@ const MIGRATIONS = [
             "in docs/standards/testing-standards.md (the 'Manual & end-to-end verification' section).\n" +
             "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
     },
+    {
+        version: "0.3.4",
+        describe: "CI verify workflow (if missing) and seed-law merge",
+        agentPrompt: "- If you want pull requests gated on speclaw, add the `speclaw` GitHub check as a " +
+            "required status check in branch protection. speclaw never enables that itself.\n" +
+            "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
+    },
 ];
 /**
  * Update speclaw and bring the current project up to date without a full re-init:

package/dist/cli/commands/verify.js

@@ -0,0 +1,118 @@
+import fs from "node:fs";
+import { list } from "../lib/args.js";
+import { ui, c } from "../lib/ui.js";
+import { isShallowRepo } from "../../shared/git-history.js";
+import { pkgVersion } from "../../shared/version.js";
+import { parseFailOn, verifyExitCode } from "../../modules/foundation/ci.js";
+import { toMarkdown } from "../../modules/foundation/report-md.js";
+import { toSarif } from "../../modules/foundation/sarif.js";
+import { loadManifestForVerify } from "../../modules/foundation/laws.js";
+import { verifyLaws } from "../../modules/foundation/verify.js";
+const FORMATS = new Set(["text", "json", "sarif", "markdown"]);
+/**
+ * `speclaw verify` — the CI orchestrator over {@link verifyLaws}. Formats and
+ * exit codes live here; graph evaluation stays in `verify.ts`. `speclaw check`
+ * (hooks) and `speclaw laws verify` (the thin batch twin) are unchanged.
+ *
+ * @param flags - Parsed CLI flags.
+ */
+export async function runVerify(flags) {
+    const cwd = process.cwd();
+    const ci = Boolean(flags.ci);
+    if (ci)
+        process.env.NO_COLOR = "1";
+    const failOn = parseFailOn(flags["fail-on"]);
+    if (failOn === null) {
+        ui.err(`--fail-on must be error, warn, or info.`);
+        process.exit(2);
+    }
+    const format = flags.format === undefined || flags.format === true ? "text" : String(flags.format);
+    if (!FORMATS.has(format)) {
+        ui.err(`--format must be text, json, sarif, or markdown.`);
+        process.exit(2);
+    }
+    const strict = Boolean(flags["strict-engines"]);
+    const engines = list(flags.engine).filter((e) => e === "deps" || e === "graph");
+    const paths = list(flags.path);
+    if (ci && isShallowRepo(cwd)) {
+        ui.err("Shallow clone — speclaw cannot see the merge base. Check out with fetch-depth: 0.");
+        process.exit(3);
+    }
+    const manifest = loadManifestForVerify(cwd);
+    const report = verifyLaws({
+        projectPath: cwd,
+        paths: paths.length ? paths : undefined,
+        engines: engines.length ? engines : undefined,
+        lawIds: list(flags.law).length ? list(flags.law) : undefined,
+    });
+    const sarifPath = typeof flags.sarif === "string" ? flags.sarif : undefined;
+    const jsonPath = typeof flags.json === "string" ? flags.json : undefined;
+    if (sarifPath) {
+        if (!writeOut(sarifPath, JSON.stringify(toSarif(report, sarifCtx(manifest.laws)), null, 2))) {
+            process.exit(3);
+        }
+    }
+    if (jsonPath) {
+        if (!writeOut(jsonPath, JSON.stringify(report, null, 2)))
+            process.exit(3);
+    }
+    const summaryFile = process.env.GITHUB_STEP_SUMMARY;
+    if (summaryFile) {
+        try {
+            fs.appendFileSync(summaryFile, toMarkdown(report));
+        }
+        catch (err) {
+            ui.warn(`Could not write $GITHUB_STEP_SUMMARY: ${err.message}`);
+        }
+    }
+    printReport(report, format, flags.json === true && !jsonPath);
+    process.exit(verifyExitCode(report, { failOn, strictEngines: strict }));
+}
+function sarifCtx(laws) {
+    return { speclawVersion: pkgVersion(), laws };
+}
+function writeOut(file, body) {
+    try {
+        fs.writeFileSync(file, body.endsWith("\n") ? body : body + "\n");
+        return true;
+    }
+    catch (err) {
+        ui.err(`Cannot write ${file}: ${err.message}`);
+        return false;
+    }
+}
+function printReport(report, format, jsonStdout) {
+    if (jsonStdout || format === "json") {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    if (format === "sarif") {
+        // Rules need the loaded laws; re-read via the same fallback the run used.
+        const laws = loadManifestForVerify(process.cwd()).laws;
+        console.log(JSON.stringify(toSarif(report, sarifCtx(laws)), null, 2));
+        return;
+    }
+    if (format === "markdown") {
+        process.stdout.write(toMarkdown(report));
+        return;
+    }
+    const { summary } = report;
+    ui.heading("speclaw verify");
+    ui.info(`${summary.passed} passed · ${c.red(String(summary.failed))} failed · ` +
+        `${summary.skipped} skipped · ${summary.unknown} unknown ` +
+        `(${report.elapsedMs.toFixed(1)} ms)`);
+    if (summary.evaluated === 0 && summary.skipped === 0) {
+        ui.warn("0 batch laws evaluated — verify is not checking anything.");
+    }
+    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,8 @@ 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
+  verify                   Verify laws for CI: exit codes, --sarif, --json, --strict-engines
   mcp                      Start the MCP server (used by your agent's config)
   help                     Show this help
   --version                Print the installed speclaw version
@@ -113,6 +115,10 @@ 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);
+        case "verify":
+            return (await import("./commands/verify.js")).runVerify(flags);
         default:
             ui.err(`Unknown command: ${cmd}`);
             console.log(HELP);

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

@@ -0,0 +1,117 @@
+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)] ?? "");
+}
+/** 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-model.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");
@@ -78,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

@@ -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/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");
+}

package/dist/modules/foundation/sarif.js

@@ -0,0 +1,96 @@
+import { fingerprint } from "./ci.js";
+/** GitHub Code Scanning rejects a run with more than this many results. */
+export const SARIF_RESULT_CAP = 5000;
+function toSarifLevel(s) {
+    if (s === "error")
+        return "error";
+    if (s === "warn")
+        return "warning";
+    return "note";
+}
+/**
+ * A project-relative POSIX URI. Absolute paths (Unix `/…` or Windows `C:\…`)
+ * make GitHub drop the annotation; never emit them.
+ *
+ * @param file - A finding's `file` field (already project-relative POSIX).
+ */
+export function toRepoRelativeUri(file) {
+    return file
+        .replace(/\\/g, "/")
+        .replace(/^[A-Za-z]:/, "")
+        .replace(/^\/+/, "");
+}
+const SEVERITY_ORDER = { error: 0, warn: 1, info: 2 };
+/**
+ * Project a {@link VerifyReport} to SARIF 2.1.0. One `rule` per loaded law
+ * (so GitHub groups alerts by law id); results truncated to
+ * {@link SARIF_RESULT_CAP} by severity; skipped laws become
+ * `toolExecutionNotifications`.
+ *
+ * @param report - The batch report.
+ * @param ctx - Package version and the laws that were loaded.
+ * @returns A JSON-serialisable SARIF log.
+ */
+export function toSarif(report, ctx) {
+    const sorted = [...report.findings].sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity]);
+    const dropped = Math.max(0, sorted.length - SARIF_RESULT_CAP);
+    const kept = dropped > 0 ? sorted.slice(0, SARIF_RESULT_CAP) : sorted;
+    const notifications = report.skipped.map((s) => ({
+        level: "warning",
+        message: {
+            text: `Law ${s.lawId} not evaluated: ${s.reason}${s.detail ? ` (${s.detail})` : ""}`,
+        },
+    }));
+    if (dropped > 0) {
+        notifications.push({
+            level: "warning",
+            message: { text: `Truncated ${dropped} findings (SARIF cap ${SARIF_RESULT_CAP})` },
+        });
+    }
+    return {
+        $schema: "https://json.schemastore.org/sarif-2.1.0.json",
+        version: "2.1.0",
+        runs: [
+            {
+                tool: {
+                    driver: {
+                        name: "speclaw",
+                        informationUri: "https://github.com/esneiderbravo/speclaw",
+                        semanticVersion: ctx.speclawVersion,
+                        rules: ctx.laws.map((law) => ({
+                            id: law.id,
+                            name: law.id.replace(/~/g, "_"),
+                            shortDescription: { text: law.title },
+                            fullDescription: { text: law.prose },
+                            help: {
+                                text: law.rationale ?? law.prose,
+                                markdown: `**${law.title}**\n\n${law.prose}`,
+                            },
+                            properties: { tags: ["speclaw", law.verification.kind] },
+                        })),
+                    },
+                },
+                results: kept.map((f) => ({
+                    ruleId: f.lawId,
+                    level: toSarifLevel(f.severity),
+                    message: { text: f.detail ? `${f.message} ${f.detail}` : f.message },
+                    locations: [
+                        {
+                            physicalLocation: {
+                                artifactLocation: { uri: toRepoRelativeUri(f.file) },
+                                region: { startLine: f.line ?? 1 },
+                            },
+                        },
+                    ],
+                    partialFingerprints: { "speclaw/v1": fingerprint(f) },
+                })),
+                invocations: [
+                    {
+                        executionSuccessful: report.summary.failed === 0,
+                        toolExecutionNotifications: notifications,
+                    },
+                ],
+            },
+        ],
+    };
+}

package/dist/modules/foundation/scaffold.js

@@ -8,7 +8,7 @@ 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 { mergeSeedLaws, 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
@@ -25,19 +25,38 @@ const FOUNDATION_DEFAULTS = {
     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.
+ * Ensure the project has a law manifest. Missing → seed. Present → append any
+ * shipped seed law whose `id` is absent (never overwrite a curated entry).
  */
 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;
+    if (!existing) {
+        const seed = seedManifest();
+        writeLawManifest(projectPath, seed);
+        report.written.push(path.join(projectPath, ".speclaw", "laws-manifest.json"));
+        return seed;
+    }
+    const { manifest, added } = mergeSeedLaws(existing);
+    if (added.length > 0) {
+        writeLawManifest(projectPath, manifest);
+        report.written.push(path.join(projectPath, ".speclaw", "laws-manifest.json"));
+    }
+    return manifest;
+}
+/**
+ * Write `.github/workflows/speclaw.yml` from the shipped template when the
+ * path does not exist. Never overwrite — the user's CI is theirs.
+ */
+function ensureVerifyWorkflow(projectPath, report) {
+    const dest = path.join(projectPath, ".github", "workflows", "speclaw.yml");
+    if (fs.existsSync(dest)) {
+        report.skipped.push(dest);
+        return;
+    }
+    const src = path.join(ASSETS, "workflows", "speclaw.yml");
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    fs.copyFileSync(src, dest);
+    report.written.push(dest);
 }
 /**
  * Render the foundation: walk the module's assets/, mirror its structure into
@@ -131,6 +150,7 @@ export function scaffold(projectPath, profile, packNames, agents = [], opts = {}
     // 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);
+    ensureVerifyWorkflow(projectPath, report);
     report.hooks = installHooks(projectPath, agents, lawManifest, report, {
         baselines: managedOpts.baselines,
         backup: managedOpts.backup,

package/dist/modules/foundation/verify-model.js

@@ -0,0 +1,14 @@
+/**
+ * True when `file` (POSIX, project-relative) is at or under one of `paths`.
+ *
+ * @param file - A project-relative POSIX path.
+ * @param paths - Optional path prefixes; omitted or empty matches everything.
+ */
+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 + "/");
+    });
+}

package/dist/modules/foundation/verify.js

@@ -0,0 +1,106 @@
+import { performance } from "node:perf_hooks";
+import { openDb, indexExists } from "../compass/db.js";
+import { hasBatchBackend, loadManifestForVerify } from "./laws.js";
+import { runDepsLaw } from "./deps.js";
+import { runGraphLaw } from "./graph.js";
+export { underPaths } from "./verify-model.js";
+// The batch verifier behind the `law_verify` tool and the `speclaw laws verify`
+// CLI. It evaluates every law whose backend reads the Compass graph (`deps`,
+// `graph`) without a language model, and reports a result honest enough to
+// trust: it distinguishes passed / failed / skipped / unknown and never counts a
+// skip or an unknown as a pass. It is the single home of graph evaluation; the
+// action-time evaluator (`check.ts`) shares this module's model and scope matcher
+// but never runs these engines, so no index query lands on the keystroke budget.
+/**
+ * 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). When the gitignored
+ * manifest file is missing, the shipped seed is used so a clean clone does not
+ * report an empty pass. 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 = loadManifestForVerify(args.projectPath);
+    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/git.js

@@ -37,3 +37,52 @@ export function listTrackedPaths(projectPath, candidates) {
         return res.status === 0 && res.stdout.trim().length > 0;
     });
 }
+/**
+ * The merge-base SHA of `ref` and `HEAD`, or `null` when the repo is missing,
+ * shallow, or `ref` is unknown. Callers that need a PR diff must treat `null`
+ * as "cannot see the base" — never as "nothing changed".
+ *
+ * @param projectPath - Directory inside the work tree.
+ * @param ref - The other end of the range (e.g. `origin/main`, a SHA).
+ */
+export function mergeBase(projectPath, ref) {
+    if (!isGitRepo(projectPath))
+        return null;
+    const res = spawnSync("git", ["-C", projectPath, "merge-base", ref, "HEAD"], {
+        encoding: "utf8",
+    });
+    if (res.status !== 0)
+        return null;
+    const sha = res.stdout.trim();
+    return sha || null;
+}
+/**
+ * Project-relative paths changed between `base` and `HEAD` (added, copied,
+ * modified, renamed). Uses `merge-base` so merge commits in the range are not
+ * counted as the PR's own work. Returns `[]` when the merge base cannot be
+ * resolved — callers in CI must fail that case rather than treat it as clean.
+ *
+ * @param projectPath - Directory inside the work tree.
+ * @param base - The other end of the range (branch name or SHA).
+ */
+export function changedFiles(projectPath, base) {
+    const mb = mergeBase(projectPath, base);
+    if (!mb)
+        return [];
+    const res = spawnSync("git", [
+        "-C",
+        projectPath,
+        "-c",
+        "core.quotePath=false",
+        "diff",
+        "--name-only",
+        "--diff-filter=ACMR",
+        `${mb}...HEAD`,
+    ], { encoding: "utf8" });
+    if (res.status !== 0 || typeof res.stdout !== "string")
+        return [];
+    return res.stdout
+        .split("\n")
+        .map((l) => l.trim())
+        .filter(Boolean);
+}

package/package.json

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