@esneiderbravo/speclaw 0.3.13 → 1.0.0

package/dist/modules/foundation/dialects/claude-cursor.js

@@ -0,0 +1,45 @@
+import { frontmatter, lawSlug, } from "./types.js";
+function body(law) {
+    return [`# ${law.title}`, "", `<!-- speclaw:law-id ${law.id} -->`, "", law.prose, ""].join("\n");
+}
+/** Claude Code `.claude/rules` via managed `ai-specs/rules/<slug>.md` + `paths:`. */
+export const claudeRulesDialect = {
+    id: "claude-rules",
+    compile(laws, ctx) {
+        if (!ctx.agents.includes("claude"))
+            return [];
+        const active = laws.filter((l) => (l.status ?? "active") !== "draft");
+        return active.map((law) => {
+            const fm = law.scope.length === 0 ? frontmatter({}) : frontmatter({ paths: law.scope });
+            return {
+                path: `ai-specs/rules/${lawSlug(law.id)}.md`,
+                contents: fm + body(law),
+                lawIds: [law.id],
+                mode: "write",
+            };
+        });
+    },
+};
+/** Cursor rules as `.mdc` under `ai-specs/rules` (symlinked via `.cursor/rules`). */
+export const cursorMdcDialect = {
+    id: "cursor-mdc",
+    compile(laws, ctx) {
+        if (!ctx.agents.includes("cursor"))
+            return [];
+        const active = laws.filter((l) => (l.status ?? "active") !== "draft");
+        return active.map((law) => {
+            const empty = law.scope.length === 0;
+            const fm = frontmatter({
+                description: law.title,
+                alwaysApply: empty,
+                ...(empty ? {} : { globs: law.scope }),
+            });
+            return {
+                path: `ai-specs/rules/${lawSlug(law.id)}.mdc`,
+                contents: fm + body(law),
+                lawIds: [law.id],
+                mode: "write",
+            };
+        });
+    },
+};

package/dist/modules/foundation/dialects/coderabbit.js

@@ -0,0 +1,27 @@
+/**
+ * CodeRabbit: emit a merge artifact describing path_instructions entries.
+ * The orchestrator merges into existing YAML without a full YAML parser —
+ * marker-based line surgery on `path_instructions:` list items.
+ */
+export const coderabbitDialect = {
+    id: "coderabbit",
+    compile(laws, ctx) {
+        if (!ctx.agents.includes("coderabbit"))
+            return [];
+        const active = laws.filter((l) => (l.status ?? "active") !== "draft" && l.scope.length > 0);
+        if (active.length === 0)
+            return [];
+        const entries = active.map((law) => ({
+            path: law.scope[0] ?? "**",
+            instructions: `[speclaw:${law.id}] ${law.prose}`,
+        }));
+        return [
+            {
+                path: ".coderabbit.yaml",
+                contents: JSON.stringify({ path_instructions: entries }, null, 2) + "\n",
+                lawIds: active.map((l) => l.id),
+                mode: "merge-yaml-path-instructions",
+            },
+        ];
+    },
+};

package/dist/modules/foundation/dialects/copilot.js

@@ -0,0 +1,35 @@
+import { frontmatter, lawSlug, } from "./types.js";
+/**
+ * Copilot path-scoped instructions. Scoped laws only — never also dump the
+ * same body into AGENTS (dual-read nondeterminism).
+ */
+export const copilotDialect = {
+    id: "copilot-instructions",
+    compile(laws, ctx) {
+        // Emit when explicitly wanted: agent id "copilot" or always if .github exists —
+        // orchestrator passes agents; treat missing copilot as skip unless "agents" generic.
+        const want = ctx.agents.includes("copilot") ||
+            ctx.agents.includes("github-copilot") ||
+            ctx.agents.includes("agents");
+        if (!want)
+            return [];
+        const scoped = laws.filter((l) => (l.status ?? "active") !== "draft" && l.scope.length > 0);
+        return scoped.map((law) => {
+            const fm = frontmatter({ applyTo: law.scope.join(",") });
+            const body = [
+                `# ${law.title}`,
+                "",
+                `<!-- speclaw:law-id ${law.id} -->`,
+                "",
+                law.prose,
+                "",
+            ].join("\n");
+            return {
+                path: `.github/instructions/${lawSlug(law.id)}.instructions.md`,
+                contents: fm + body,
+                lawIds: [law.id],
+                mode: "write",
+            };
+        });
+    },
+};

package/dist/modules/foundation/dialects/index.js

@@ -0,0 +1,5 @@
+export { frontmatter, delimit, patchDelimited, lawSlug, commonPrefix } from "./types.js";
+export { agentsmdDialect } from "./agentsmd.js";
+export { claudeRulesDialect, cursorMdcDialect } from "./claude-cursor.js";
+export { copilotDialect } from "./copilot.js";
+export { coderabbitDialect } from "./coderabbit.js";

package/dist/modules/foundation/dialects/types.js

@@ -0,0 +1,58 @@
+/** YAML-ish frontmatter for markdown rule files. */
+export function frontmatter(fields) {
+    const lines = ["---"];
+    for (const [k, v] of Object.entries(fields)) {
+        if (Array.isArray(v)) {
+            lines.push(`${k}:`);
+            for (const item of v)
+                lines.push(`  - ${JSON.stringify(item)}`);
+        }
+        else if (typeof v === "boolean") {
+            lines.push(`${k}: ${v}`);
+        }
+        else {
+            lines.push(`${k}: ${JSON.stringify(v)}`);
+        }
+    }
+    lines.push("---", "");
+    return lines.join("\n");
+}
+/** HTML comment markers for delimited patches in personalized files. */
+export function delimit(marker, body) {
+    return `<!-- speclaw:${marker}:start -->\n${body.trim()}\n<!-- speclaw:${marker}:end -->\n`;
+}
+/**
+ * Replace or append a delimited speclaw block inside `existing` text.
+ * Preserves all content outside the markers.
+ */
+export function patchDelimited(existing, marker, body) {
+    const block = delimit(marker, body);
+    const re = new RegExp(`<!--\\s*speclaw:${marker}:start\\s-->[\\s\\S]*?<!--\\s*speclaw:${marker}:end\\s-->\\n?`, "m");
+    if (re.test(existing))
+        return existing.replace(re, block);
+    const sep = existing.endsWith("\n") || existing.length === 0 ? "" : "\n";
+    return `${existing}${sep}\n${block}`;
+}
+/** Stable filename slug from a law id (`law~foo~1` → `law-foo-1`). */
+export function lawSlug(id) {
+    return id.replace(/~/g, "-").replace(/[^a-zA-Z0-9._-]+/g, "-");
+}
+/** Longest common directory prefix of scope globs (best-effort). */
+export function commonPrefix(scopes) {
+    const dirs = scopes
+        .map((s) => s
+        .replace(/\\/g, "/")
+        .replace(/\*\*.*$/, "")
+        .replace(/\/$/, ""))
+        .filter((s) => s.length > 0 && !s.includes("*"));
+    if (dirs.length === 0)
+        return "";
+    const parts = dirs[0].split("/");
+    let i = 0;
+    for (; i < parts.length; i++) {
+        const p = parts[i];
+        if (!dirs.every((d) => d.split("/")[i] === p))
+            break;
+    }
+    return parts.slice(0, i).join("/");
+}

package/dist/modules/foundation/doctor.js

@@ -5,12 +5,18 @@ import { isMinimalMode, packageRoot } from "../../shared/exposure.js";
 import { isGitRepo } from "../../shared/git.js";
 import { readManifest } from "../../shared/manifest.js";
 import { pkgName, pkgVersion } from "../../shared/version.js";
-import { indexExists, openDb } from "../compass/db.js";
+import { indexExists, openDb, probeFts5Support } from "../compass/db.js";
+import { getEmbedder } from "../compass/embedder.js";
 import { specList } from "../lawbook/engine.js";
 import { doctorDriftCheck } from "../lawbook/drift.js";
 import { loadCeremonyConfig } from "../lawbook/levels.js";
+import { doctorOwnersChecks } from "../team/owners.js";
 import { globError, hasBackend, hasBatchBackend, readLawManifest } from "./laws.js";
+import { estimateAlwaysOnTokens } from "./compile-laws.js";
 import { redactValue } from "../../shared/redact.js";
+import { readDeprecatedCallCounts, scanRetiredToolReferences } from "../../shared/deprecation.js";
+import { CANONICAL_TOOLS, ALIAS_TARGETS, isCanonicalTool } from "../../shared/tool-catalog.js";
+import { discoverIntegrityPaths, lockfilePath, readLockfile, rootDigest } from "./lock.js";
 const STATUS_RANK = {
     skip: 0,
     ok: 1,
@@ -46,18 +52,29 @@ function detectInstallKind() {
 function enginesRequirement() {
     try {
         const pkg = JSON.parse(fs.readFileSync(path.join(packageRoot(), "package.json"), "utf8"));
-        return pkg.engines?.node ?? ">=22";
+        return pkg.engines?.node ?? ">=22.16";
     }
     catch {
-        return ">=22";
+        return ">=22.16";
     }
 }
 function nodeSatisfies(required, version) {
-    const m = /^>=\s*(\d+)/.exec(required.trim());
+    const m = /^>=\s*(\d+)(?:\.(\d+))?/.exec(required.trim());
     if (!m)
         return true;
-    const major = parseInt(version.replace(/^v/, "").split(".")[0], 10);
-    return major >= parseInt(m[1], 10);
+    const parts = version
+        .replace(/^v/, "")
+        .split(".")
+        .map((x) => parseInt(x, 10));
+    const major = parts[0] ?? 0;
+    const minor = parts[1] ?? 0;
+    const needMajor = parseInt(m[1], 10);
+    const needMinor = m[2] !== undefined ? parseInt(m[2], 10) : 0;
+    if (major > needMajor)
+        return true;
+    if (major < needMajor)
+        return false;
+    return minor >= needMinor;
 }
 function libcLabel() {
     if (process.platform !== "linux")
@@ -177,6 +194,25 @@ function buildEnvironment(projectPath) {
         detail: git ? "repository" : "not a git repository",
         remedy: git ? undefined : "git init",
     });
+    const ftsOk = probeFts5Support();
+    addCheck(checks, {
+        id: "env.fts5",
+        title: "fts5",
+        status: ftsOk ? "ok" : "warn",
+        value: ftsOk,
+        detail: ftsOk
+            ? "node:sqlite FTS5 available"
+            : "FTS5 unavailable — hybrid search degrades to vector+name (need Node >=22.16)",
+        remedy: ftsOk ? undefined : "Upgrade to Node.js >=22.16",
+    });
+    const embedderId = getEmbedder().id;
+    addCheck(checks, {
+        id: "env.embedder",
+        title: "embedder",
+        status: "ok",
+        value: embedderId,
+        detail: `active embedder: ${embedderId}`,
+    });
     addCheck(checks, {
         id: "env.ast-engine",
         title: "ast engine",
@@ -367,12 +403,23 @@ function lawsCheck(projectPath) {
     }
     const withPath = manifest.laws.filter(hasBackend).length;
     const withBatch = manifest.laws.filter(hasBatchBackend).length;
+    const budget = estimateAlwaysOnTokens(manifest.laws);
+    if (budget.total > 2000) {
+        const top = budget.top.map((t) => `${t.id}(~${t.tokens})`).join(", ");
+        return {
+            id: "cfg.laws",
+            title: "laws",
+            status: "warn",
+            detail: `always-on laws ~${budget.total} tokens (budget 2000); top: ${top || "n/a"}`,
+            remedy: "Add scope globs to the largest always-on laws, then speclaw laws compile",
+        };
+    }
     return {
         id: "cfg.laws",
         title: "laws",
         status: "ok",
         value: manifest.laws.length,
-        detail: `${manifest.laws.length} declared · ${withPath} path · ${withBatch} deps/graph · 0 invalid`,
+        detail: `${manifest.laws.length} declared · ${withPath} path · ${withBatch} deps/graph · always-on ~${budget.total} tokens`,
     };
 }
 async function budgetCheck(projectPath) {
@@ -397,6 +444,48 @@ async function budgetCheck(projectPath) {
         };
     }
 }
+async function toolSurfaceCheck(projectPath) {
+    try {
+        const { measureInstallBudget, collectRegisteredTools } = await import("./context-budget.js");
+        const full = measureInstallBudget(projectPath, false);
+        const mini = measureInstallBudget(projectPath, true);
+        const canonicalCount = collectRegisteredTools(false).filter((t) => isCanonicalTool(t.name)).length;
+        const deprecated = readDeprecatedCallCounts(projectPath);
+        const aliasDetail = deprecated.size > 0
+            ? [...deprecated.entries()]
+                .map(([alias, n]) => `${alias}→${ALIAS_TARGETS[alias] ?? "?"} (${n}×)`)
+                .join("; ")
+            : "no deprecated alias calls logged";
+        const staleRefs = scanRetiredToolReferences(projectPath);
+        const staleDetail = staleRefs.length > 0
+            ? `retired names in: ${[...new Set(staleRefs.map((r) => `${r.file} (${r.alias}→${r.replacement})`))].join("; ")}`
+            : undefined;
+        return {
+            id: "cfg.tool-surface",
+            title: "MCP tool surface",
+            status: staleRefs.length > 0 ? "warn" : "ok",
+            value: canonicalCount,
+            detail: [
+                `${canonicalCount}/${CANONICAL_TOOLS.length} canonical tools`,
+                `~${full.tools} tool-definition tokens (full), ~${mini.tools} (minimal)`,
+                aliasDetail,
+                staleDetail,
+            ]
+                .filter(Boolean)
+                .join(" · "),
+            remedy: staleRefs.length > 0 ? "speclaw update" : undefined,
+        };
+    }
+    catch (err) {
+        return {
+            id: "cfg.tool-surface",
+            title: "MCP tool surface",
+            status: "skip",
+            detail: `could not measure: ${err.message}`,
+            remedy: "speclaw budget",
+        };
+    }
+}
 function freshnessCheck(projectPath) {
     if (!indexExists(projectPath)) {
         return {
@@ -468,6 +557,154 @@ function specsOrphansCheck(projectPath) {
         remedy: `speclaw lawbook archive ${active[0]}`,
     };
 }
+function integrityChecks(projectPath) {
+    // Covers: req~doctor-integrity~1
+    const out = [];
+    const abs = lockfilePath(projectPath);
+    if (!fs.existsSync(abs)) {
+        out.push({
+            id: "cfg.integrity.lock",
+            title: "rule lockfile",
+            status: "warn",
+            detail: "no speclaw.lock — rule digests are not pinned",
+            remedy: "speclaw laws lock",
+        });
+    }
+    else {
+        try {
+            const lock = readLockfile(projectPath);
+            const matches = rootDigest(lock.files) === lock.root;
+            out.push({
+                id: "cfg.integrity.lock",
+                title: "rule lockfile",
+                status: matches ? "ok" : "warn",
+                value: matches,
+                detail: matches
+                    ? `speclaw.lock root matches (${Object.keys(lock.files).length} files)`
+                    : "speclaw.lock root does not match recomputed digests",
+                remedy: matches ? undefined : "speclaw laws lock",
+            });
+        }
+        catch (err) {
+            out.push({
+                id: "cfg.integrity.lock",
+                title: "rule lockfile",
+                status: "error",
+                detail: err.message,
+                remedy: "speclaw laws lock",
+            });
+        }
+    }
+    const imports = findExternalImports(projectPath, 4);
+    out.push({
+        id: "cfg.integrity.imports",
+        title: "external rule imports",
+        status: imports.length ? "warn" : "ok",
+        value: imports.length ? imports.slice(0, 8).join("; ") : null,
+        detail: imports.length
+            ? `${imports.length} external @import hop(s) (≤4): ${imports.slice(0, 5).join("; ")}`
+            : "no external @import / @~/ paths detected in rule files",
+        remedy: imports.length
+            ? "review imports that resolve outside the working directory"
+            : undefined,
+    });
+    const { files } = discoverIntegrityPaths(projectPath);
+    const outside = files.filter((f) => {
+        const n = f.split("\\").join("/");
+        return (n === ".clinerules" ||
+            n === ".windsurfrules" ||
+            n === "BUGBOT.md" ||
+            n === ".cursorrules" ||
+            n.startsWith("ai-specs/skills/") ||
+            n.startsWith(".claude/skills/"));
+    });
+    out.push({
+        id: "cfg.integrity.outside-pipeline",
+        title: "outside-pipeline rules",
+        status: "ok",
+        value: outside.length,
+        detail: outside.length > 0
+            ? `${outside.length} scan-only / outside-pipeline path(s): ${outside.slice(0, 6).join(", ")}`
+            : "no outside-pipeline rule files discovered",
+    });
+    return out;
+}
+/**
+ * Follow `@~/…`, absolute `@/…`, and `@import "…"` targets outside the project,
+ * transitively up to `maxHops`.
+ */
+/* node:coverage disable */
+function findExternalImports(projectPath, maxHops) {
+    const roots = [
+        "CLAUDE.md",
+        "AGENTS.md",
+        "LAWS.md",
+        ".cursorrules",
+        ".clinerules",
+        ".windsurfrules",
+    ];
+    const seen = new Set();
+    const out = [];
+    const queue = [];
+    for (const r of roots) {
+        const abs = path.join(projectPath, r);
+        if (fs.existsSync(abs))
+            queue.push({ file: abs, hop: 0 });
+    }
+    while (queue.length) {
+        const { file, hop } = queue.shift();
+        if (hop > maxHops || seen.has(file))
+            continue;
+        seen.add(file);
+        let text;
+        try {
+            text = fs.readFileSync(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const line of text.split(/\r?\n/)) {
+            const m = /@([~/][^\s)\]>"']+)/.exec(line) ??
+                /@import\s+["']([^"']+)["']/.exec(line) ??
+                /@([A-Za-z]:[^\s)\]>"']+)/.exec(line);
+            if (!m)
+                continue;
+            const target = m[1];
+            const resolved = resolveImportTarget(file, target);
+            if (!resolved)
+                continue;
+            const projectRoot = path.resolve(projectPath);
+            const outside = target.startsWith("~/") ||
+                path.isAbsolute(target) ||
+                !resolved.startsWith(projectRoot + path.sep);
+            if (outside) {
+                const label = `${path.relative(projectPath, file) || path.basename(file)} → ${target}`;
+                out.push(label);
+                if (hop < maxHops && fs.existsSync(resolved) && fs.statSync(resolved).isFile()) {
+                    queue.push({ file: resolved, hop: hop + 1 });
+                }
+            }
+        }
+    }
+    return out;
+}
+function resolveImportTarget(fromFile, target) {
+    if (target.startsWith("~/")) {
+        const home = process.env.HOME || process.env.USERPROFILE || "";
+        if (!home)
+            return null;
+        return path.resolve(home, target.slice(2));
+    }
+    if (target.startsWith("/") || /^[A-Za-z]:/.test(target))
+        return path.resolve(target);
+    if (target.startsWith("./") || target.startsWith("../")) {
+        return path.resolve(path.dirname(fromFile), target);
+    }
+    if (!target.includes("://"))
+        return path.resolve(path.dirname(fromFile), target);
+    return null;
+}
+/* node:coverage enable */
 /** Ceremony config validity + archived level histogram. */
 function ceremonyChecks(projectPath) {
     const out = [];
@@ -569,16 +806,20 @@ function configurationChecks(projectPath, initialised) {
             "cfg.hooks",
             "cfg.laws",
             "cfg.budget",
+            "cfg.tool-surface",
             "cfg.index.freshness",
             "cfg.specs.orphans",
         ];
-        return ids.map((id) => ({
-            id,
-            title: id.replace(/^cfg\./, ""),
-            status: "skip",
-            detail: "project not initialised",
-            remedy: "speclaw init",
-        }));
+        return [
+            ...ids.map((id) => ({
+                id,
+                title: id.replace(/^cfg\./, ""),
+                status: "skip",
+                detail: "project not initialised",
+                remedy: "speclaw init",
+            })),
+            ...integrityChecks(projectPath),
+        ];
     }
     const checks = [];
     const manifest = readManifest(projectPath);
@@ -605,6 +846,7 @@ function configurationChecks(projectPath, initialised) {
         remedy: "speclaw update",
     });
     checks.push(lawsCheck(projectPath));
+    checks.push(...integrityChecks(projectPath));
     // budget + mcp + freshness + specs filled async by caller
     return checks;
 }
@@ -650,6 +892,7 @@ export async function doctor(projectPath, opts = {}) {
     const configuration = configurationChecks(projectPath, initialised);
     if (initialised) {
         configuration.push(await budgetCheck(projectPath));
+        configuration.push(await toolSurfaceCheck(projectPath));
         configuration.push(freshnessCheck(projectPath));
         configuration.push(specsOrphansCheck(projectPath));
         configuration.push(...ceremonyChecks(projectPath));
@@ -663,6 +906,15 @@ export async function doctor(projectPath, opts = {}) {
                 remedy: d.remedy,
             });
         }
+        for (const o of doctorOwnersChecks(projectPath)) {
+            addCheck(configuration, {
+                id: o.id,
+                title: o.title,
+                status: o.status,
+                detail: o.detail,
+                remedy: o.remedy,
+            });
+        }
         const configured = detectConfiguredAgents(projectPath);
         const mcpAgents = AGENTS.filter((a) => a.mcpFile && configured.includes(a.id));
         if (mcpAgents.length === 0) {

package/dist/modules/foundation/import-rules.js

@@ -0,0 +1,67 @@
+import fs from "node:fs";
+import path from "node:path";
+import { readLawManifest, writeLawManifest } from "./laws.js";
+/**
+ * Import rulesync-style markdown rules under `.rulesync/` or `rulesync/` into
+ * draft semantic laws and append them to the manifest.
+ */
+export function importRulesFrom(projectPath, from) {
+    if (from !== "rulesync") {
+        throw new Error(`unsupported import source "${from}" — try rulesync`);
+    }
+    const candidates = [".rulesync", "rulesync", ".rulesync/rules", "rulesync/rules"];
+    let root = null;
+    for (const c of candidates) {
+        const abs = path.join(projectPath, c);
+        if (fs.existsSync(abs) && fs.statSync(abs).isDirectory()) {
+            root = abs;
+            break;
+        }
+    }
+    if (!root) {
+        throw new Error("no rulesync rules directory found (.rulesync/ or rulesync/)");
+    }
+    const report = { imported: [], skipped: [] };
+    const existing = readLawManifest(projectPath) ?? { version: 1, laws: [] };
+    const have = new Set(existing.laws.map((l) => l.id));
+    const walk = (dir) => {
+        for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+            const abs = path.join(dir, ent.name);
+            if (ent.isDirectory()) {
+                walk(abs);
+                continue;
+            }
+            if (!/\.(md|mdc)$/i.test(ent.name))
+                continue;
+            const rel = path.relative(projectPath, abs).split(path.sep).join("/");
+            const prose = fs.readFileSync(abs, "utf8").trim() || "(empty rule)";
+            const slug = ent.name
+                .replace(/\.(md|mdc)$/i, "")
+                .toLowerCase()
+                .replace(/[^a-z0-9]+/g, "-")
+                .replace(/^-|-$/g, "");
+            const id = `law~import-rulesync-${slug}~1`;
+            if (have.has(id)) {
+                report.skipped.push(id);
+                continue;
+            }
+            const law = {
+                id,
+                title: `Imported: ${ent.name}`,
+                severity: "warn",
+                scope: [],
+                prose,
+                verification: { kind: "semantic" },
+                enforcement: "feedback",
+                source: { file: rel, line: 1 },
+                status: "draft",
+            };
+            existing.laws.push(law);
+            have.add(id);
+            report.imported.push(id);
+        }
+    };
+    walk(root);
+    writeLawManifest(projectPath, existing);
+    return report;
+}