@esneiderbravo/speclaw 0.3.3 → 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`), 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). |
+| **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/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

@@ -36,6 +36,7 @@ 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
@@ -116,6 +117,8 @@ async function dispatch(cmd, flags) {
             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

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

package/dist/modules/foundation/graph.js

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

package/dist/modules/foundation/laws.js

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

package/dist/modules/foundation/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

@@ -1,26 +1,27 @@
 import { performance } from "node:perf_hooks";
 import { openDb, indexExists } from "../compass/db.js";
-import { hasBatchBackend, readLawManifest } from "./laws.js";
+import { hasBatchBackend, loadManifestForVerify } 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 + "/");
-    });
-}
+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). 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.
+ * `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}.
@@ -46,9 +47,7 @@ export function verifyLaws(args) {
         unknown,
         elapsedMs: performance.now() - start,
     });
-    const manifest = readLawManifest(args.projectPath);
-    if (!manifest)
-        return done();
+    const manifest = loadManifestForVerify(args.projectPath);
     const engines = args.engines;
     const selected = manifest.laws.filter((law) => {
         if (!hasBatchBackend(law))

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.3",
+  "version": "0.3.4",
   "publishConfig": {
     "access": "public"
   },