@esneiderbravo/speclaw 0.3.0 → 0.3.2

package/README.md

@@ -55,7 +55,8 @@ The `speclaw` command is now available everywhere — run `speclaw index`,
 
 1. **Ask which agents you use** (Claude Code, Cursor, Codex, …) — and configure
    only those. Add more later; nothing is forced on you.
-2. Write the **foundation** (constitution + standards) and the **lawbook workflow**.
+2. Write the **foundation** (constitution + standards) and the **lawbook workflow**,
+   and compile your blocking laws into **agent hooks** for the agents that support them.
 3. **Index your code** with a live progress bar and a summary of what it found.
 4. Register the speclaw **MCP server** in each chosen agent's config.
 5. Print a prompt to paste into your agent so it fills the constitution with your
@@ -81,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. |
+| **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`). |
 | **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. |
@@ -175,6 +176,12 @@ ai-specs` command to stop tracking it (they never touch your git index
 themselves). The agent directories (`.claude/`, `.cursor/`, …) are **left to
 you** — commit your own skills and commands there if you want to.
 
+**Enforcement artifacts.** For agents that support hooks, speclaw merges its law
+hooks into that agent's settings (e.g. `.claude/settings.json`) **by identity** —
+it never touches hooks you added yourself. The compiled law manifest lives in
+`.speclaw/laws-manifest.json` (gitignored, regenerated on `init`/`update`), and a
+context-coverage log in `.speclaw/context-log.jsonl` feeds `speclaw doctor`.
+
 <br/>
 
 ## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; Philosophy — why "laws"?
@@ -186,6 +193,21 @@ you** — commit your own skills and commands there if you want to.
 > knowledge explicit, executable, and binding, and gives agents a local map
 > (Compass) and a disciplined workflow (Lawbook) to act on it — without burning tokens.
 
+This is why "enforced" is literal, not a metaphor. Anthropic's own guidance puts
+it plainly:
+
+> _"An instruction like 'never edit .env' in CLAUDE.md or a skill is **a request,
+> not a guarantee**. A `PreToolUse` hook that blocks the edit is enforcement. If a
+> rule must hold every time, make it a hook rather than a prompt instruction."_
+> — [Claude Code — Hooks](https://code.claude.com/docs/en/hooks)
+
+So `speclaw init` compiles your blocking laws into agent hooks: a law marked
+`bloqueo` is denied at the keystroke (`PreToolUse`), citing the law's id, text,
+and source. `speclaw check --dry-run --path <file>` previews what would block, and
+`speclaw doctor` reports how many of your laws actually reached the agent's
+context. Agents without hooks (Cursor, Codex) enforce the same laws in CI via
+`speclaw verify`.
+
 <br/>
 
 ## <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/diamond.png" height="20" alt="◆" align="absmiddle">&nbsp; Staying up to date

package/dist/cli/commands/check.js

@@ -0,0 +1,100 @@
+import { ui, c } from "../lib/ui.js";
+import { checkAction } from "../../modules/foundation/check.js";
+import { hasBackend, readLawManifest } from "../../modules/foundation/laws.js";
+/** Read all of stdin as UTF-8 text (used for `--hook-payload -`). */
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString("utf8");
+}
+/**
+ * `speclaw check` — the CLI twin of the `speclaw_check` MCP tool, and the
+ * command-hook fallback for agents driven purely by the CLI.
+ *
+ * - `--hook-payload -` reads a hook event JSON from stdin, evaluates it, prints
+ *   the `hookSpecificOutput` contract, and exits 2 on `deny` (the documented
+ *   command-hook block signal).
+ * - `--dry-run [--path P] [--event E]` previews the verdict for a synthetic
+ *   action against path `P`, without blocking anything (always exits 0).
+ * - with no flags, prints a summary of the project's declared laws.
+ *
+ * @param flags - Parsed CLI flags.
+ */
+export async function runCheck(flags) {
+    const cwd = process.cwd();
+    if (flags["hook-payload"]) {
+        const raw = await readStdin();
+        let payload;
+        try {
+            payload = JSON.parse(raw);
+        }
+        catch {
+            // Fail open: an unreadable payload must never block the agent.
+            console.log(JSON.stringify({ hookSpecificOutput: { permissionDecision: "allow" } }));
+            return;
+        }
+        const event = (payload.hook_event_name ?? payload.event ?? "PreToolUse");
+        const toolName = (payload.tool_name ?? payload.toolName);
+        const result = checkAction({ projectPath: cwd, event, toolName, payload });
+        const decision = result.verdict === "deny" ? "deny" : "allow";
+        console.log(JSON.stringify({
+            hookSpecificOutput: {
+                hookEventName: event,
+                permissionDecision: decision,
+                permissionDecisionReason: result.reason ?? "",
+            },
+        }));
+        if (result.verdict === "deny")
+            process.exit(2);
+        return;
+    }
+    if (flags["dry-run"]) {
+        const target = typeof flags.path === "string" ? flags.path : "";
+        const event = (typeof flags.event === "string" ? flags.event : "PreToolUse");
+        if (!target) {
+            ui.err(`Pass ${ui.code("--path <file>")} to preview what a law would do to that path.`);
+            process.exit(1);
+        }
+        const result = checkAction({
+            projectPath: cwd,
+            event,
+            payload: { tool_input: { file_path: target } },
+        });
+        ui.heading(`speclaw check --dry-run (${event})`);
+        ui.info(`target: ${c.cream(target)}`);
+        if (result.diagnostic)
+            ui.warn(result.diagnostic);
+        if (result.evaluated.length === 0) {
+            ui.ok("No law applies to this path.");
+        }
+        else {
+            for (const e of result.evaluated) {
+                // The message already opens with the law id (see check.ts `cite`).
+                const line = e.message ?? e.lawId;
+                if (e.passed)
+                    ui.info(line);
+                else
+                    ui.warn(line);
+            }
+        }
+        ui.plain();
+        const verb = result.verdict === "deny" ? c.red("would BLOCK") : c.green("would allow");
+        ui.plain(`  verdict: ${verb} · evaluated in ${result.elapsedMs.toFixed(1)} ms`);
+        return;
+    }
+    // Default: summarize the declared laws.
+    const manifest = readLawManifest(cwd);
+    ui.heading("speclaw check");
+    if (!manifest) {
+        ui.warn("No law manifest — run `speclaw init` to seed .speclaw/laws-manifest.json.");
+        return;
+    }
+    ui.info(`${manifest.laws.length} law(s) declared:`);
+    for (const law of manifest.laws) {
+        const backend = hasBackend(law)
+            ? law.verification.kind
+            : `${law.verification.kind} (no backend yet)`;
+        ui.plain(`  · ${c.cream(law.id)} — ${law.enforcement} · ${backend} · [${law.scope.join(", ")}]`);
+    }
+}

package/dist/cli/index.js

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

package/dist/modules/compass/db.js

@@ -47,9 +47,17 @@ CREATE TABLE IF NOT EXISTS node_embeddings (
   model TEXT NOT NULL,
   vec BLOB NOT NULL
 );
+-- git_history_cache: memoized results of the expensive git-history scans
+-- (churn, co-change), keyed by query and invalidated when HEAD moves.
+CREATE TABLE IF NOT EXISTS git_history_cache (
+  query_key TEXT PRIMARY KEY,
+  head_sha TEXT NOT NULL,
+  payload TEXT NOT NULL,
+  computed_at INTEGER NOT NULL
+);
 `;
 /** Schema version stamped into the `meta` table on first creation. */
-export const SCHEMA_VERSION = "3";
+export const SCHEMA_VERSION = "4";
 /** The stamped schema version, or null if the db predates versioning / has no meta table. */
 function readSchemaVersion(db) {
     try {
@@ -81,6 +89,7 @@ function isStale(db) {
 /** Drop every table (children first) so the current schema can be recreated cleanly. */
 function resetSchema(db) {
     db.exec(`
+    DROP TABLE IF EXISTS git_history_cache;
     DROP TABLE IF EXISTS node_embeddings;
     DROP TABLE IF EXISTS edges;
     DROP TABLE IF EXISTS nodes;

package/dist/modules/compass/git-history-cache.js

@@ -0,0 +1,65 @@
+import { churn, coChanges, headSha, } from "../../shared/git-history.js";
+import { openDb } from "./db.js";
+/**
+ * Look up a cached payload valid at the current HEAD, or compute it and store it.
+ *
+ * When `head` is `null` (no commits / not a repo) the cache is bypassed entirely
+ * and `compute()` runs directly, so an empty repo never poisons the cache.
+ *
+ * @param projectPath - Project root, whose `.speclaw/index.db` holds the cache.
+ * @param head - The current HEAD SHA, or `null` when there is none.
+ * @param queryKey - Stable key identifying this query (function + options).
+ * @param compute - Produces the fresh result on a miss.
+ * @param serialize - Turns the result into a JSON-safe payload string.
+ * @param deserialize - Rebuilds the result from a stored payload string.
+ * @returns The cached-or-freshly-computed result.
+ */
+function readThrough(projectPath, head, queryKey, compute, serialize, deserialize) {
+    if (head === null)
+        return compute();
+    const db = openDb(projectPath);
+    try {
+        const row = db
+            .prepare("SELECT head_sha, payload FROM git_history_cache WHERE query_key = ?")
+            .get(queryKey);
+        if (row && row.head_sha === head) {
+            return deserialize(row.payload);
+        }
+        const value = compute();
+        db.prepare(`INSERT INTO git_history_cache(query_key, head_sha, payload, computed_at)
+       VALUES (?, ?, ?, 0)
+       ON CONFLICT(query_key) DO UPDATE SET
+         head_sha = excluded.head_sha,
+         payload = excluded.payload,
+         computed_at = excluded.computed_at`).run(queryKey, head, serialize(value));
+        return value;
+    }
+    finally {
+        db.close();
+    }
+}
+/**
+ * {@link churn}, memoized in the Compass index until `HEAD` moves.
+ *
+ * @param projectPath - Project root to query.
+ * @param opts - Same options as {@link churn}.
+ * @returns Per-path change counts and the shallow marker, cached per HEAD.
+ */
+export function cachedChurn(projectPath, opts = {}) {
+    const key = `churn:${JSON.stringify({ since: opts.since ?? null, pathspec: opts.pathspec ?? null })}`;
+    return readThrough(projectPath, headSha(projectPath), key, () => churn(projectPath, opts), (value) => JSON.stringify({ shallow: value.shallow, byPath: [...value.byPath] }), (payload) => {
+        const parsed = JSON.parse(payload);
+        return { shallow: parsed.shallow, byPath: new Map(parsed.byPath) };
+    });
+}
+/**
+ * {@link coChanges}, memoized in the Compass index until `HEAD` moves.
+ *
+ * @param projectPath - Project root to query.
+ * @param opts - Same options as {@link coChanges}.
+ * @returns The co-change pairs and the shallow marker, cached per HEAD.
+ */
+export function cachedCoChanges(projectPath, opts = {}) {
+    const key = `coChanges:${JSON.stringify({ since: opts.since ?? null, minSupport: opts.minSupport ?? null })}`;
+    return readThrough(projectPath, headSha(projectPath), key, () => coChanges(projectPath, opts), (value) => JSON.stringify(value), (payload) => JSON.parse(payload));
+}

package/dist/modules/foundation/assets/laws/laws-manifest.json

@@ -0,0 +1,49 @@
+{
+  "version": 1,
+  "laws": [
+    {
+      "id": "law~no-secrets-in-repo~1",
+      "title": "No secrets in the repository",
+      "rationale": "A committed secret is a leaked secret; enforcement at the keystroke is the only reliable guard.",
+      "severity": "error",
+      "scope": ["**/.env", "**/.env.*", "**/*.env"],
+      "prose": "Never write a .env file into the repository. Secrets live in the environment, not in version control.",
+      "verification": { "kind": "path" },
+      "enforcement": "bloqueo",
+      "source": { "file": "docs/standards/base-standards.md" }
+    },
+    {
+      "id": "law~local-first~1",
+      "title": "Local-first is non-negotiable",
+      "rationale": "speclaw runs entirely on the user's machine; every new dependency must be justified in the PR.",
+      "severity": "warn",
+      "scope": ["package.json"],
+      "prose": "Justify any new dependency in the PR: it must not break 'runs offline with no API keys'.",
+      "verification": { "kind": "path" },
+      "enforcement": "feedback",
+      "source": { "file": "LAWS.md" }
+    },
+    {
+      "id": "law~protect-templates~1",
+      "title": "Protect the templates",
+      "rationale": "Assets under src/modules/*/assets/** are product output; the build must copy them and the {{placeholder}} contracts must stay intact.",
+      "severity": "warn",
+      "scope": ["src/modules/*/assets/**"],
+      "prose": "Assets under src/modules/*/assets/** are product output — keep the {{placeholder}} and speclaw-init contracts intact, and let the build copy them (never hand-copy into dist/).",
+      "verification": { "kind": "path" },
+      "enforcement": "feedback",
+      "source": { "file": "LAWS.md" }
+    },
+    {
+      "id": "law~honest-attribution~1",
+      "title": "Keep attribution honest",
+      "rationale": "Compass reimplements CodeGraph and Lawbook reimplements OpenSpec (both MIT); ATTRIBUTION.md must stay accurate.",
+      "severity": "info",
+      "scope": ["ATTRIBUTION.md"],
+      "prose": "Keep ATTRIBUTION.md accurate as the Compass and Lawbook modules evolve.",
+      "verification": { "kind": "path" },
+      "enforcement": "feedback",
+      "source": { "file": "LAWS.md" }
+    }
+  ]
+}

package/dist/modules/foundation/check.js

@@ -0,0 +1,144 @@
+import fs from "node:fs";
+import path from "node:path";
+import { performance } from "node:perf_hooks";
+import { compileScope, hasBackend, manifestPath, matchCompiled, readLawManifest, } from "./laws.js";
+const cache = new Map();
+/**
+ * Load the project's compiled law index, using the in-process cache when the
+ * manifest is unchanged (keeps `PreToolUse` off the disk and off the regex
+ * compiler on the hot path). Returns null when the manifest is missing or
+ * unparseable, so the caller fails open.
+ */
+function loadLaws(projectPath) {
+    let mtimeMs;
+    try {
+        mtimeMs = fs.statSync(manifestPath(projectPath)).mtimeMs;
+    }
+    catch {
+        cache.delete(projectPath);
+        return null;
+    }
+    const hit = cache.get(projectPath);
+    if (hit && hit.mtimeMs === mtimeMs)
+        return hit.laws;
+    const manifest = readLawManifest(projectPath);
+    if (!manifest)
+        return null;
+    const laws = manifest.laws.map((law) => ({ law, scope: compileScope(law.scope) }));
+    cache.set(projectPath, { mtimeMs, laws });
+    return laws;
+}
+/** Clear the manifest cache (used by tests and by a manifest rewrite in-process). */
+export function clearLawCache() {
+    cache.clear();
+}
+/** POSIX-normalize a path and make it project-relative when it is absolute. */
+function toRelPosix(projectPath, p) {
+    let rel = p;
+    if (path.isAbsolute(p))
+        rel = path.relative(projectPath, p);
+    return rel.split(path.sep).join("/").replace(/^\.\//, "");
+}
+/** Extract the file the action targets from a tool payload, across common shapes. */
+function targetPath(projectPath, payload) {
+    const input = (payload.tool_input ?? payload.toolInput ?? payload);
+    const candidate = input.file_path ?? input.filePath ?? input.path ?? input.notebook_path ?? input.notebookPath;
+    return typeof candidate === "string" ? toRelPosix(projectPath, candidate) : null;
+}
+/** Extract the instructions file that was loaded, across common payload shapes. */
+function loadedFile(projectPath, payload) {
+    const candidate = payload.file ?? payload.filePath ?? payload.path ?? payload.file_path;
+    return typeof candidate === "string" ? toRelPosix(projectPath, candidate) : null;
+}
+/** Format the citation for a matched law: id, source, and its literal prose. */
+function cite(law) {
+    const at = law.source.line ? `${law.source.file}:${law.source.line}` : law.source.file;
+    return `${law.id} (${at}): «${law.prose}»`;
+}
+/** Append the ids of the laws a just-loaded instructions file declares to the context log. */
+function recordContextCoverage(projectPath, laws, file) {
+    const ids = laws.filter((l) => (file ? l.source.file === file : true)).map((l) => l.id);
+    if (ids.length === 0)
+        return ids;
+    try {
+        const logDir = path.join(projectPath, ".speclaw");
+        fs.mkdirSync(logDir, { recursive: true });
+        const line = JSON.stringify({ at: new Date().toISOString(), file, lawIds: ids }) + "\n";
+        fs.appendFileSync(path.join(logDir, "context-log.jsonl"), line);
+    }
+    catch {
+        // Best-effort audit — never let a logging failure affect the verdict.
+    }
+    return ids;
+}
+/**
+ * Evaluate an agent action against every law whose scope matches its target and
+ * return an ACS-aligned verdict. Only the `path` backend is evaluated; laws with
+ * another (unimplemented) backend are skipped. The evaluator fails open: a
+ * missing or unparseable manifest, or any exception, yields `allow` with a
+ * diagnostic — an enforcement layer that blocks when its own checker crashes is
+ * worse than none.
+ *
+ * @param args - The project, hook event, optional tool name, and raw payload.
+ * @returns The verdict, the laws evaluated, an optional reason, and `elapsedMs`.
+ */
+export function checkAction(args) {
+    const start = performance.now();
+    const done = (r) => ({
+        ...r,
+        elapsedMs: performance.now() - start,
+    });
+    try {
+        const laws = loadLaws(args.projectPath);
+        if (!laws) {
+            return done({
+                verdict: "allow",
+                evaluated: [],
+                diagnostic: "law manifest missing or unparseable — failing open",
+            });
+        }
+        if (args.event === "InstructionsLoaded") {
+            const ids = recordContextCoverage(args.projectPath, laws.map((il) => il.law), loadedFile(args.projectPath, args.payload));
+            return done({
+                verdict: "allow",
+                evaluated: ids.map((id) => ({ lawId: id, severity: "info", passed: true })),
+            });
+        }
+        const target = targetPath(args.projectPath, args.payload);
+        if (target === null)
+            return done({ verdict: "allow", evaluated: [] });
+        const matched = laws
+            .filter((il) => hasBackend(il.law) && matchCompiled(il.scope, target))
+            .map((il) => il.law);
+        const evaluated = matched.map((l) => ({
+            lawId: l.id,
+            severity: l.severity,
+            passed: l.enforcement !== "bloqueo" || args.event !== "PreToolUse",
+            message: cite(l),
+            file: target,
+        }));
+        // Only a `bloqueo` law, and only on PreToolUse, stops the keystroke. Every
+        // other match still enters context as a message the agent reads.
+        const blocking = args.event === "PreToolUse" ? matched.filter((l) => l.enforcement === "bloqueo") : [];
+        if (blocking.length > 0) {
+            return done({
+                verdict: "deny",
+                evaluated,
+                reason: `Blocked by ${blocking.map(cite).join("; ")}`,
+            });
+        }
+        const messages = evaluated.map((e) => e.message).filter(Boolean);
+        return done({
+            verdict: "allow",
+            evaluated,
+            reason: messages.length ? messages.join("; ") : undefined,
+        });
+    }
+    catch (err) {
+        return done({
+            verdict: "allow",
+            evaluated: [],
+            diagnostic: `check failed open: ${err.message}`,
+        });
+    }
+}

package/dist/modules/foundation/doctor.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
-import { AGENTS, detectConfiguredAgents } from "../../shared/agents.js";
+import { AGENTS, agentById, detectConfiguredAgents } from "../../shared/agents.js";
+import { globError, hasBackend, 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
@@ -99,5 +100,95 @@ export function doctor(projectPath) {
         ok: has(".mcp.json"),
         detail: has(".mcp.json") ? "present" : "missing — scaffold writes it",
     });
+    lawEnforcementChecks(projectPath, checks);
     return checks;
 }
+/** The law ids recorded as loaded into agent context, from the append-only log. */
+function loadedLawIds(projectPath) {
+    const loaded = new Set();
+    try {
+        const log = fs.readFileSync(path.join(projectPath, ".speclaw", "context-log.jsonl"), "utf8");
+        for (const line of log.split(/\r?\n/)) {
+            if (!line.trim())
+                continue;
+            const ids = JSON.parse(line).lawIds ?? [];
+            for (const id of ids)
+                loaded.add(id);
+        }
+    }
+    catch {
+        // No log yet — hooks have not recorded any context loads.
+    }
+    return loaded;
+}
+/**
+ * Append the law-enforcement health checks: manifest presence and backend
+ * coverage, glob validity (caught here rather than at runtime), context-coverage
+ * with the post-compact caveat, and the agents where blocking laws don't apply.
+ */
+function lawEnforcementChecks(projectPath, checks) {
+    const manifest = readLawManifest(projectPath);
+    if (!manifest) {
+        checks.push({
+            name: "law manifest",
+            ok: false,
+            detail: "missing — run `speclaw init`/`update` to seed .speclaw/laws-manifest.json",
+        });
+        return;
+    }
+    const withBackend = manifest.laws.filter(hasBackend);
+    const noBackend = manifest.laws.filter((l) => !hasBackend(l));
+    checks.push({
+        name: "law manifest",
+        ok: true,
+        detail: `${manifest.laws.length} law(s): ${withBackend.length} enforced (path)` +
+            (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.
+    const badGlobs = [];
+    for (const law of manifest.laws) {
+        for (const pattern of law.scope) {
+            const err = globError(pattern);
+            if (err)
+                badGlobs.push(`${law.id}: ${pattern} (${err})`);
+        }
+    }
+    checks.push({
+        name: "law scope globs",
+        ok: badGlobs.length === 0,
+        detail: badGlobs.length === 0 ? "all valid" : `malformed: ${badGlobs.join("; ")}`,
+    });
+    // Context coverage — which laws actually entered the agent's context.
+    const loaded = loadedLawIds(projectPath);
+    const declared = manifest.laws.map((l) => l.id);
+    const missing = declared.filter((id) => !loaded.has(id));
+    checks.push({
+        name: "law context coverage",
+        ok: true,
+        detail: `${declared.length - missing.length} of ${declared.length} laws loaded into context` +
+            (missing.length ? ` — not yet loaded: ${missing.join(", ")}` : "") +
+            ". Note: after a compact, root CLAUDE.md is re-injected but `paths:`-scoped rules are not," +
+            " until a matching file is next touched — so a path-scoped law can be out of context" +
+            " exactly when it matters, which is why it is also a hook.",
+    });
+    // Agent asymmetry — where blocking laws cannot be enforced at the keystroke.
+    const configured = detectConfiguredAgents(projectPath);
+    const unhooked = configured
+        .map((id) => agentById(id))
+        .filter((a) => a && !a.hooks)
+        .map((a) => a.label);
+    if (unhooked.length) {
+        const blocking = manifest.laws.filter((l) => l.enforcement === "bloqueo").length;
+        checks.push({
+            name: "hook coverage across agents",
+            ok: true,
+            detail: `no hook support for ${unhooked.join(", ")} — your ${blocking} blocking law(s) apply ` +
+                "there only via `speclaw verify`.",
+        });
+    }
+}

package/dist/modules/foundation/hooks.js

@@ -0,0 +1,165 @@
+import fs from "node:fs";
+import path from "node:path";
+import { agentById } from "../../shared/agents.js";
+import { sha256 } from "../../shared/install.js";
+import { globError, hasBackend } from "./laws.js";
+/** The speclaw hook object — its `{type, server}` pair is the merge identity. */
+const SPECLAW_HOOK = {
+    type: "mcp_tool",
+    server: "speclaw",
+    tool: "speclaw_check",
+    timeout: 5,
+};
+/** Tool-name matcher for the file-mutating tools the `path` backend can evaluate. */
+const MUTATION_MATCHER = "Write|Edit|MultiEdit|NotebookEdit";
+/** True when a hook object is one speclaw owns (safe to replace on merge). */
+function isSpeclawHook(h) {
+    const o = h;
+    return o?.type === "mcp_tool" && o?.server === "speclaw";
+}
+/**
+ * Compile a law manifest into the hook groups speclaw contributes, one per event
+ * the laws demand: `PreToolUse` when any `bloqueo` law exists, `PostToolUse` for
+ * `feedback`, `Stop` for `gate`, and `InstructionsLoaded` whenever any law exists
+ * (the context-coverage audit). A law whose scope contains a malformed glob is
+ * excluded and reported, so a bad pattern fails loudly at generation rather than
+ * silently matching nothing at runtime.
+ *
+ * @param manifest - The project's law manifest.
+ * @returns The per-event hook groups and the list of laws rejected for bad globs.
+ */
+export function compileHooks(manifest) {
+    const invalid = [];
+    const valid = [];
+    for (const law of manifest.laws) {
+        const bad = law.scope.map((p) => ({ p, e: globError(p) })).find((x) => x.e);
+        if (bad)
+            invalid.push({ lawId: law.id, pattern: bad.p, error: bad.e });
+        else
+            valid.push(law);
+    }
+    const byEvent = {};
+    const hasBloqueo = valid.some((l) => l.enforcement === "bloqueo" && hasBackend(l));
+    const hasFeedback = valid.some((l) => l.enforcement === "feedback" && hasBackend(l));
+    const hasGate = valid.some((l) => l.enforcement === "gate");
+    if (hasBloqueo)
+        byEvent.PreToolUse = [{ matcher: MUTATION_MATCHER, hooks: [{ ...SPECLAW_HOOK }] }];
+    if (hasFeedback)
+        byEvent.PostToolUse = [{ matcher: MUTATION_MATCHER, hooks: [{ ...SPECLAW_HOOK }] }];
+    if (hasGate)
+        byEvent.Stop = [{ hooks: [{ ...SPECLAW_HOOK }] }];
+    if (valid.length > 0)
+        byEvent.InstructionsLoaded = [{ hooks: [{ ...SPECLAW_HOOK }] }];
+    return { byEvent, invalid };
+}
+/**
+ * Merge speclaw's compiled hook groups into an existing `hooks` object by
+ * identity: for every event, drop the groups speclaw owns (a group whose hooks
+ * are all speclaw's) and re-add the freshly compiled ones, never touching a
+ * group with a foreign `server` or `type`. Idempotent, marker-free, and it
+ * cannot delete another tool's hooks.
+ *
+ * @param existing - The current `hooks` object from the agent's settings (any shape).
+ * @param compiled - speclaw's per-event hook groups from {@link compileHooks}.
+ * @returns A new `hooks` object with speclaw's entries reconciled in.
+ */
+export function mergeHooks(existing, compiled) {
+    const out = {};
+    const events = new Set([...Object.keys(existing ?? {}), ...Object.keys(compiled)]);
+    for (const event of events) {
+        const prior = Array.isArray(existing?.[event]) ? existing[event] : [];
+        // Keep foreign groups: drop speclaw hooks from each group, then any group left empty.
+        const kept = prior
+            .map((g) => ({ ...g, hooks: (g.hooks ?? []).filter((h) => !isSpeclawHook(h)) }))
+            .filter((g) => g.hooks.length > 0);
+        const mine = compiled[event] ?? [];
+        const merged = [...kept, ...mine];
+        if (merged.length > 0)
+            out[event] = merged;
+    }
+    return out;
+}
+/**
+ * Install (or refresh) speclaw's hooks into one agent's settings file, merging by
+ * identity and honoring the managed-file baseline: a settings file that diverged
+ * from what speclaw last wrote is backed up to `<file>.bak` first when `backup`
+ * is set, and always reported. The baseline sha of the written file is recorded.
+ *
+ * @param projectPath - Project root.
+ * @param agent - The agent whose `hooks` capability names the settings file and key.
+ * @param compiled - speclaw's compiled hook groups.
+ * @param report - Install report mutated in place.
+ * @param opts - Managed-file behavior: recorded baselines, backup, and a record sink.
+ */
+function installForAgent(projectPath, agent, compiled, report, opts) {
+    if (!agent.hooks)
+        return;
+    const settingsPath = path.join(projectPath, agent.hooks.file);
+    const rel = path.relative(projectPath, settingsPath);
+    let settings = {};
+    let current = null;
+    if (fs.existsSync(settingsPath)) {
+        current = fs.readFileSync(settingsPath, "utf8");
+        try {
+            settings = JSON.parse(current);
+        }
+        catch {
+            // A settings file we cannot parse is the user's — never clobber it silently.
+            report.skipped.push(`${settingsPath} (unparseable — left untouched)`);
+            return;
+        }
+    }
+    settings[agent.hooks.key] = mergeHooks(settings[agent.hooks.key], compiled);
+    const content = JSON.stringify(settings, null, 2) + "\n";
+    const newSha = sha256(content);
+    if (current !== null) {
+        if (sha256(current) === newSha) {
+            if (opts.record)
+                opts.record[rel] = newSha;
+            return; // already current — no drift
+        }
+        const baseline = opts.baselines?.[rel];
+        if (!baseline || sha256(current) !== baseline) {
+            if (opts.backup) {
+                fs.copyFileSync(settingsPath, settingsPath + ".bak");
+                report.backedUp.push(settingsPath);
+            }
+            report.refreshedDiverged.push(settingsPath);
+        }
+    }
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+    fs.writeFileSync(settingsPath, content);
+    report.written.push(`${settingsPath} (speclaw hooks)`);
+    if (opts.record)
+        opts.record[rel] = newSha;
+}
+/**
+ * Compile the manifest and install speclaw's hooks into every hook-capable agent
+ * among those selected, skipping agents without a `hooks` capability (Cursor,
+ * Codex, Windsurf) by construction. A malformed glob excludes only that law and
+ * is surfaced in the result.
+ *
+ * @param projectPath - Project root.
+ * @param agentIds - Ids of the agents configured for this project.
+ * @param manifest - The project's law manifest.
+ * @param report - Install report mutated in place.
+ * @param opts - Managed-file behavior: recorded baselines, backup, and a record sink.
+ * @returns Which agents were hooked, which were skipped, and any rejected laws.
+ */
+export function installHooks(projectPath, agentIds, manifest, report, opts) {
+    const { byEvent, invalid } = compileHooks(manifest);
+    const hooked = [];
+    const unhooked = [];
+    for (const id of agentIds) {
+        const agent = agentById(id);
+        if (!agent)
+            continue;
+        if (!agent.hooks) {
+            unhooked.push(id);
+            continue;
+        }
+        installForAgent(projectPath, agent, byEvent, report, opts);
+        hooked.push(id);
+    }
+    return { hooked, unhooked, invalid };
+}

package/dist/modules/foundation/laws.js

@@ -0,0 +1,211 @@
+import fs from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { assetsDir } from "../../shared/paths.js";
+// The machine-readable law model and its manifest. This is the contract seam
+// (`.speclaw/laws-manifest.json`) between where laws come from and how they are
+// enforced: check-dispatcher owns the schema and the single `path` verification
+// 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 lawSchema = z.object({
+    id: z.string().min(1),
+    title: z.string().min(1),
+    rationale: z.string().optional(),
+    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"]),
+    }),
+    enforcement: z.enum(["bloqueo", "feedback", "gate"]),
+    source: z.object({ file: z.string(), line: z.number().optional() }),
+});
+const manifestSchema = z.object({
+    version: z.number(),
+    laws: z.array(lawSchema),
+});
+/** The verification backends this change actually evaluates at runtime. */
+export const IMPLEMENTED_BACKENDS = ["path"];
+/** True when a law's verification backend is evaluated at runtime (only `path` today). */
+export function hasBackend(law) {
+    return IMPLEMENTED_BACKENDS.includes(law.verification.kind);
+}
+/** 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");
+}
+/**
+ * Read and validate a project's law manifest.
+ *
+ * @param projectPath - Project root to read from.
+ * @returns The parsed manifest, or null if it is missing or unparseable (the
+ *   caller fails open — a broken manifest never blocks the agent).
+ */
+export function readLawManifest(projectPath) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(manifestPath(projectPath), "utf8"));
+        return manifestSchema.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write a project's law manifest, validating every law first.
+ *
+ * @param projectPath - Project root to write into.
+ * @param manifest - The manifest to persist; each law is schema-validated.
+ * @throws If any law fails validation.
+ */
+export function writeLawManifest(projectPath, manifest) {
+    const validated = manifestSchema.parse(manifest);
+    const p = manifestPath(projectPath);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(validated, null, 2) + "\n");
+}
+/**
+ * The starter law manifest shipped with speclaw, seeded from a speclaw-style
+ * project's own `path`-verifiable Project-specific laws. It is the source the
+ * MVP compiles into `.speclaw/laws-manifest.json`; once executable-laws lands,
+ * laws are authored in `docs/standards/*` and compiled here instead. Laws whose
+ * scope does not match a given repo are simply inert there.
+ *
+ * @returns The validated seed manifest read from the module's assets.
+ * @throws If the seed asset is missing or fails validation.
+ */
+export function seedManifest() {
+    const raw = JSON.parse(fs.readFileSync(path.join(ASSETS, "laws", "laws-manifest.json"), "utf8"));
+    return manifestSchema.parse(raw);
+}
+// ─── Glob matching (the `path` backend) ──────────────────────────────────────
+/**
+ * Validate a scope glob without compiling it for use, so generation can fail
+ * loudly on a malformed pattern (e.g. an unclosed `[`) rather than silently
+ * matching zero files at runtime.
+ *
+ * @param pattern - A single scope glob (a leading `!` negation is allowed).
+ * @returns An error message if the glob is malformed, else null.
+ */
+export function globError(pattern) {
+    try {
+        compileGlob(pattern);
+        return null;
+    }
+    catch (err) {
+        return err.message;
+    }
+}
+/** Regex-special characters that are literals in a glob and must be escaped. */
+const REGEX_SPECIALS = new Set([".", "+", "^", "$", "(", ")", "|", "\\"]);
+/**
+ * Compile a glob into an anchored regular expression matching a POSIX-style
+ * relative path. Supports `**` (any run of segments), `*`/`?` (within a
+ * segment), `{a,b}` alternation, and `[...]`/`[!...]` character classes.
+ *
+ * @param pattern - A single scope glob; a leading `!` is stripped by the caller.
+ * @returns A `RegExp` anchored to the whole path.
+ * @throws If the glob contains an unclosed `[` or `{`.
+ */
+export function compileGlob(pattern) {
+    let re = "";
+    let braceDepth = 0;
+    for (let i = 0; i < pattern.length; i++) {
+        const ch = pattern[i];
+        if (ch === "*") {
+            if (pattern[i + 1] === "*") {
+                // `**` (optionally followed by `/`) spans any number of segments.
+                i++;
+                if (pattern[i + 1] === "/")
+                    i++;
+                re += "(?:[^/]*(?:/|$))*";
+            }
+            else {
+                re += "[^/]*";
+            }
+        }
+        else if (ch === "?") {
+            re += "[^/]";
+        }
+        else if (ch === "{") {
+            braceDepth++;
+            re += "(?:";
+        }
+        else if (ch === "}") {
+            if (braceDepth === 0)
+                throw new Error(`unmatched '}' in glob: ${pattern}`);
+            braceDepth--;
+            re += ")";
+        }
+        else if (ch === "," && braceDepth > 0) {
+            re += "|";
+        }
+        else if (ch === "[") {
+            const close = pattern.indexOf("]", i + 1);
+            if (close === -1)
+                throw new Error(`unclosed '[' in glob: ${pattern}`);
+            let cls = pattern.slice(i + 1, close);
+            if (cls.startsWith("!"))
+                cls = "^" + cls.slice(1);
+            re += `[${cls}]`;
+            i = close;
+        }
+        else if (REGEX_SPECIALS.has(ch)) {
+            re += "\\" + ch;
+        }
+        else {
+            re += ch;
+        }
+    }
+    if (braceDepth !== 0)
+        throw new Error(`unclosed '{' in glob: ${pattern}`);
+    return new RegExp(`^${re}$`);
+}
+/**
+ * Compile a law's scope globs into regexes once, so runtime matching does no
+ * regex compilation on the critical path. Malformed globs are dropped (they are
+ * caught and reported at generation time).
+ *
+ * @param scope - The law's scope globs.
+ * @returns The compiled positive and negative matchers.
+ */
+export function compileScope(scope) {
+    const positives = [];
+    const negatives = [];
+    for (const g of scope) {
+        const negated = g.startsWith("!");
+        try {
+            (negated ? negatives : positives).push(compileGlob(negated ? g.slice(1) : g));
+        }
+        catch {
+            // Skip malformed globs — generation already flagged them.
+        }
+    }
+    return { matchAll: scope.length === 0, positives, negatives };
+}
+/**
+ * Test a target path against a pre-compiled scope. Positive globs are OR-ed; a
+ * `!`-prefixed glob excludes; an empty scope matches everything.
+ *
+ * @param compiled - The scope compiled by {@link compileScope}.
+ * @param target - A POSIX-style project-relative path (forward slashes).
+ * @returns True when the target is in scope.
+ */
+export function matchCompiled(compiled, target) {
+    const included = compiled.matchAll ||
+        compiled.positives.length === 0 ||
+        compiled.positives.some((r) => r.test(target));
+    return included && !compiled.negatives.some((r) => r.test(target));
+}
+/**
+ * Test whether a target path matches a law's scope, compiling on the spot.
+ * Convenience for non-hot paths (doctor, dry-run); the evaluator uses
+ * {@link compileScope} + {@link matchCompiled} to stay off the compiler.
+ *
+ * @param scope - The law's scope globs.
+ * @param target - A POSIX-style project-relative path (forward slashes).
+ * @returns True when the target is in scope. Malformed globs never match.
+ */
+export function matchesScope(scope, target) {
+    return matchCompiled(compileScope(scope), target);
+}

package/dist/modules/foundation/register.js

@@ -2,6 +2,7 @@ import { z } from "zod";
 import { text } from "../../shared/mcp.js";
 import { scaffold } from "./scaffold.js";
 import { doctor } from "./doctor.js";
+import { checkAction } from "./check.js";
 import { loadPacks } from "../tools/packs.js";
 import { AGENTS, configureAgent } from "../../shared/agents.js";
 import { emptyReport } from "../../shared/install.js";
@@ -116,6 +117,18 @@ export function registerFoundation(server) {
         configureAgent(projectPath, agent, report);
         return text(report);
     });
+    server.registerTool("speclaw_check", {
+        // ≤12 words: this is invoked by speclaw's hooks, never called directly.
+        description: "Invoked by speclaw's hooks to enforce laws — do not call directly.",
+        inputSchema: {
+            projectPath: z.string().describe("Absolute path to the project"),
+            event: z
+                .enum(["PreToolUse", "PostToolUse", "Stop", "InstructionsLoaded"])
+                .describe("The hook event that fired"),
+            toolName: z.string().optional().describe("The tool the agent is invoking, when relevant"),
+            payload: z.record(z.unknown()).describe("The raw hook event payload from the agent"),
+        },
+    }, async ({ projectPath, event, toolName, payload }) => text(checkAction({ projectPath, event: event, toolName, payload })));
     server.registerTool("doctor", {
         description: "Verify a speclaw installation: ai-specs presence, the foundation (LAWS.md + standards + agent contracts), IDE symlinks health, the lawbook/ workflow, the Compass index, and .mcp.json wiring. Returns a checklist with remediation hints.",
         inputSchema: { projectPath: z.string().describe("Absolute path to the project") },

package/dist/modules/foundation/scaffold.js

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

package/dist/shared/agents.js

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

package/dist/shared/git-history.js

@@ -0,0 +1,204 @@
+import { spawnSync } from "node:child_process";
+/** ASCII NUL — the record/field separator git emits with `-z` and we request via `%x00`. */
+const NUL = "\0";
+/**
+ * Run git in `projectPath` and return stdout, or `null` on any failure.
+ *
+ * Best-effort like {@link isGitRepo}: git missing, not a repo, or a non-zero
+ * exit all yield `null` so callers can fail soft rather than throw.
+ */
+function git(projectPath, args) {
+    // `core.quotePath=false` keeps non-ASCII paths as raw UTF-8 instead of git's
+    // default octal-escaped, double-quoted form — so our path parsing stays exact.
+    const res = spawnSync("git", ["-C", projectPath, "-c", "core.quotePath=false", ...args], {
+        encoding: "utf8",
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    if (res.status !== 0 || typeof res.stdout !== "string")
+        return null;
+    return res.stdout;
+}
+/** Parse a `--numstat` count field: `-` (binary) becomes `0`, anything non-numeric too. */
+function numstat(field) {
+    if (field === "-")
+        return 0;
+    const n = Number.parseInt(field, 10);
+    return Number.isFinite(n) ? n : 0;
+}
+/**
+ * The current `HEAD` commit SHA, or `null` when the repo has no commits yet
+ * (or is not a repo / git is unavailable).
+ *
+ * @param projectPath - Directory inside the work tree to query.
+ * @returns The 40-char SHA, or `null`.
+ */
+export function headSha(projectPath) {
+    const out = git(projectPath, ["rev-parse", "HEAD"]);
+    const sha = out?.trim();
+    return sha ? sha : null;
+}
+/**
+ * Whether `projectPath` is inside a shallow clone (e.g. CI's `--depth=1`), where
+ * history is truncated and change/coupling counts would be misleadingly low.
+ *
+ * @param projectPath - Directory inside the work tree to query.
+ * @returns `true` only when git reports the repository is shallow.
+ */
+export function isShallowRepo(projectPath) {
+    const out = git(projectPath, ["rev-parse", "--is-shallow-repository"]);
+    return out?.trim() === "true";
+}
+/**
+ * The commits that touched `relPath`, most-recent first, with the line churn
+ * each introduced there.
+ *
+ * Fail-soft: a path with no history, a repo with no commits, or an unavailable
+ * git binary all yield an empty list. Records are parsed over NUL separators, so
+ * paths containing spaces or unicode are handled correctly.
+ *
+ * `since`/`until` bound the history as a **revision range** (`since..until`,
+ * `until` defaulting to `HEAD`) — the exact, deterministic form drift needs
+ * (`<archived-sha>..HEAD`), not an approximate date window. `since` is exclusive.
+ *
+ * @param projectPath - Project root to query.
+ * @param relPath - Project-relative path whose history to read.
+ * @param opts - Optional revision bounds: `since` (exclusive lower bound) and
+ *   `until` (upper bound, default `HEAD`) — any revision git accepts, e.g. a SHA.
+ * @returns The touching commits, newest first; empty when there is no history.
+ */
+export function logForPath(projectPath, relPath, opts = {}) {
+    const range = [];
+    if (opts.since)
+        range.push(`${opts.since}..${opts.until ?? "HEAD"}`);
+    else if (opts.until)
+        range.push(opts.until);
+    // Per commit: <sha>\0<ts>\0 then one numstat line per file it touched.
+    const out = git(projectPath, [
+        "log",
+        "--format=%x00%H%x00%ct%x00",
+        "--numstat",
+        ...range,
+        "--",
+        relPath,
+    ]);
+    if (out === null)
+        return [];
+    const touches = [];
+    // The stream is a sequence of "\0<sha>\0<ts>\0<numstat lines>" per commit.
+    const records = out.split(NUL);
+    // records[0] is empty (leading NUL); then repeating [sha, ts, tail...] where
+    // `tail` holds the numstat lines for that commit up to the next leading NUL.
+    for (let i = 1; i + 1 < records.length; i += 3) {
+        const sha = records[i]?.trim();
+        const ts = Number.parseInt(records[i + 1] ?? "", 10);
+        const tail = records[i + 2] ?? "";
+        if (!sha || !Number.isFinite(ts))
+            continue;
+        let added = 0;
+        let deleted = 0;
+        for (const line of tail.split("\n")) {
+            const cols = line.split("\t");
+            if (cols.length < 3)
+                continue;
+            added += numstat(cols[0]);
+            deleted += numstat(cols[1]);
+        }
+        touches.push({ sha, ts, added, deleted });
+    }
+    return touches;
+}
+/**
+ * How many commits touched each file in the window, summed from `--numstat`.
+ *
+ * Fail-soft: yields an empty map on any git failure. Does not follow renames —
+ * a renamed file is counted under its path as it appears in each commit (a safe
+ * superset, not a precise lineage). The result carries the {@link isShallowRepo}
+ * marker so consumers can degrade to "insufficient data" on a shallow clone.
+ *
+ * @param projectPath - Project root to query.
+ * @param opts - Optional `since` window (any date/revision git accepts) and a
+ *   `pathspec` list to restrict which paths are considered.
+ * @returns Per-path change counts and the shallow marker.
+ */
+export function churn(projectPath, opts = {}) {
+    const shallow = isShallowRepo(projectPath);
+    const args = ["log", "--numstat", "--format=%x00"];
+    if (opts.since)
+        args.push(`--since=${opts.since}`);
+    if (opts.pathspec && opts.pathspec.length > 0)
+        args.push("--", ...opts.pathspec);
+    const out = git(projectPath, args);
+    const byPath = new Map();
+    if (out === null)
+        return { shallow, byPath };
+    for (const line of out.split("\n")) {
+        // Numstat rows are "<added>\t<deleted>\t<path>"; the %x00 format lines and
+        // blank lines have no tabs and are skipped.
+        const cols = line.split("\t");
+        if (cols.length < 3)
+            continue;
+        const path = cols[2].replace(/^\0+/, "").trim();
+        if (!path)
+            continue;
+        byPath.set(path, (byPath.get(path) ?? 0) + 1);
+    }
+    return { shallow, byPath };
+}
+/**
+ * For every pair of files that changed together, how many commits touched both.
+ *
+ * Groups each commit's changed files and emits a count per unordered pair. Pairs
+ * with fewer than `minSupport` shared commits are omitted. Fail-soft (empty on
+ * git failure) and does not follow renames. Carries the shallow marker.
+ *
+ * @param projectPath - Project root to query.
+ * @param opts - Optional `since` window and `minSupport` threshold (default `1`).
+ * @returns The qualifying co-change pairs and the shallow marker.
+ */
+export function coChanges(projectPath, opts = {}) {
+    const shallow = isShallowRepo(projectPath);
+    const minSupport = opts.minSupport ?? 1;
+    const args = ["log", "--name-only", "--format=%x00"];
+    if (opts.since)
+        args.push(`--since=${opts.since}`);
+    const out = git(projectPath, args);
+    if (out === null)
+        return { shallow, pairs: [] };
+    const counts = new Map();
+    // Each commit's file list is the run of lines between two %x00 markers.
+    for (const commitBlock of out.split(NUL)) {
+        const files = commitBlock
+            .split("\n")
+            .map((l) => l.trim())
+            .filter((l) => l.length > 0);
+        const unique = [...new Set(files)].sort();
+        for (let i = 0; i < unique.length; i++) {
+            for (let j = i + 1; j < unique.length; j++) {
+                const key = `${unique[i]}\t${unique[j]}`;
+                counts.set(key, (counts.get(key) ?? 0) + 1);
+            }
+        }
+    }
+    const pairs = [];
+    for (const [key, count] of counts) {
+        if (count < minSupport)
+            continue;
+        const [a, b] = key.split("\t");
+        pairs.push({ a: a, b: b, count });
+    }
+    pairs.sort((x, y) => y.count - x.count || x.a.localeCompare(y.a) || x.b.localeCompare(y.b));
+    return { shallow, pairs };
+}
+/**
+ * The SHA of the most recent commit that touched `relPath`, or `null` when the
+ * path has no history (or on any git failure).
+ *
+ * @param projectPath - Project root to query.
+ * @param relPath - Project-relative path.
+ * @returns The last-touching commit SHA, or `null`.
+ */
+export function lastTouch(projectPath, relPath) {
+    const out = git(projectPath, ["log", "-1", "--format=%H", "--", relPath]);
+    const sha = out?.trim();
+    return sha ? sha : null;
+}

package/package.json

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