@esneiderbravo/speclaw 0.3.1 → 0.3.3

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`), and architectural laws are verified deterministically against the Compass graph — dependency rules (`deps`) and cycles (`graph`) — via `speclaw laws verify` / `law_verify`, which reports each law as passed, failed, skipped, or unknown (an unresolved reference is *unknown*, never a silent pass). |
 | **Compass** | speclaw's own local code graph. Parses your code (tree-sitter) into nodes + edges plus a local vector store, so an agent finds and understands code with a fraction of the tokens a grep/read loop would cost. No LLM, 100% local, lives in `.speclaw/` (gitignored). |
 | **Lawbook** | speclaw's own spec-driven workflow: `draft → build → sync → archive` (and `explore`), backed by `lawbook_*` engine tools. No external CLI. |
 | **Tools** | Opt-in packs of skills and subagents (currently the dev-agents) that agents use for specific tasks. |
@@ -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/commands/laws.js

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

package/dist/cli/index.js

@@ -34,6 +34,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
   mcp                      Start the MCP server (used by your agent's config)
   help                     Show this help
   --version                Print the installed speclaw version
@@ -110,6 +112,10 @@ 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);
+        case "laws":
+            return (await import("./commands/laws.js")).runLaws(flags);
         default:
             ui.err(`Unknown command: ${cmd}`);
             console.log(HELP);

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

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

package/dist/modules/foundation/doctor.js

@@ -1,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, 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
@@ -99,5 +100,110 @@ 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 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): ${withPath.length} enforced (path), ` +
+            `${withBatch.length} verified (deps/graph)` +
+            (noBackend.length
+                ? `, ${noBackend.length} declared without a backend yet (${noBackend
+                    .map((l) => l.id)
+                    .join(", ")})`
+                : ""),
+    });
+    // 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) {
+            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`.",
+        });
+    }
+}