@esneiderbravo/speclaw 0.4.0 → 1.0.0

package/dist/modules/foundation/laws-parse.js

@@ -0,0 +1,131 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Parse laws declared in markdown via HTML comment blocks:
+ *
+ * ```html
+ * <!-- speclaw:law
+ * id: law~example~1
+ * title: Example
+ * severity: warn
+ * scope: src/**\/*.ts
+ * enforcement: feedback
+ * verification: semantic
+ * -->
+ * Prose that follows until the next heading or comment.
+ * ```
+ */
+const BLOCK_RE = /<!--\s*speclaw:law\b([\s\S]*?)-->/gi;
+function parseMeta(raw) {
+    const out = {};
+    for (const line of raw.split(/\r?\n/)) {
+        const m = /^\s*([a-zA-Z_][\w-]*)\s*:\s*(.*?)\s*$/.exec(line);
+        if (m)
+            out[m[1].toLowerCase()] = m[2];
+    }
+    return out;
+}
+function verificationOf(kind) {
+    switch (kind) {
+        case "path":
+            return { kind: "path" };
+        case "ast":
+            return { kind: "ast" };
+        case "deps":
+            return { kind: "deps", rule: { from: "^", to: "^", type: "forbidden" } };
+        case "graph":
+            return { kind: "graph", rule: { circular: true } };
+        case "process":
+            return { kind: "process" };
+        case "traceability":
+            return { kind: "traceability" };
+        case "none":
+            return { kind: "none" };
+        case "semantic":
+        default:
+            return { kind: "semantic" };
+    }
+}
+function proseAfter(content, endIndex) {
+    const rest = content.slice(endIndex);
+    const next = rest.search(/\n#{1,3}\s|\n<!--\s*speclaw:law\b/i);
+    const chunk = (next === -1 ? rest : rest.slice(0, next)).trim();
+    return chunk.replace(/^#+\s*.*$/m, "").trim() || "(no prose)";
+}
+/**
+ * Parse one markdown file for `speclaw:law` blocks.
+ *
+ * @param fileRel - Project-relative path recorded on each law's `source`.
+ * @param content - File contents.
+ */
+export function parseLawsFromMarkdown(fileRel, content) {
+    const laws = [];
+    let m;
+    const re = new RegExp(BLOCK_RE.source, "gi");
+    while ((m = re.exec(content)) !== null) {
+        const meta = parseMeta(m[1] ?? "");
+        const id = meta.id?.trim();
+        if (!id)
+            continue;
+        const line = content.slice(0, m.index).split(/\r?\n/).length;
+        const scope = (meta.scope ?? "")
+            .split(",")
+            .map((s) => s.trim())
+            .filter(Boolean);
+        const severity = (meta.severity ?? "warn");
+        const enforcement = (meta.enforcement ?? "feedback");
+        const title = meta.title?.trim() || id;
+        const prose = proseAfter(content, m.index + m[0].length);
+        laws.push({
+            id,
+            title,
+            severity: ["error", "warn", "info"].includes(severity) ? severity : "warn",
+            scope,
+            prose,
+            verification: verificationOf(meta.verification),
+            enforcement: ["bloqueo", "feedback", "gate"].includes(enforcement) ? enforcement : "feedback",
+            source: { file: fileRel, line },
+            status: meta.status === "draft" ? "draft" : "active",
+        });
+    }
+    return laws;
+}
+/**
+ * Walk `docs/standards/**\/*.md` under the project and parse law blocks.
+ * Collects duplicate ids across files into {@link ParseLawsResult.duplicates}.
+ */
+export function parseLawsFromStandards(projectPath) {
+    const root = path.join(projectPath, "docs", "standards");
+    const laws = [];
+    const seen = new Map();
+    if (!fs.existsSync(root))
+        return { laws, duplicates: seen };
+    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 (!ent.name.endsWith(".md"))
+                continue;
+            const rel = path.relative(projectPath, abs).split(path.sep).join("/");
+            const content = fs.readFileSync(abs, "utf8");
+            for (const law of parseLawsFromMarkdown(rel, content)) {
+                const locs = seen.get(law.id) ?? [];
+                locs.push(`${law.source.file}:${law.source.line ?? "?"}`);
+                seen.set(law.id, locs);
+                laws.push(law);
+            }
+        }
+    };
+    walk(root);
+    const duplicates = new Map();
+    for (const [id, locs] of seen) {
+        if (locs.length > 1)
+            duplicates.set(id, locs);
+    }
+    // Keep first occurrence of each id in `laws` when reporting merge later;
+    // callers must fail if duplicates.size > 0.
+    return { laws, duplicates };
+}

package/dist/modules/foundation/laws.js

@@ -44,7 +44,12 @@ const lawSchema = z.object({
     verification: verificationSchema,
     enforcement: z.enum(["bloqueo", "feedback", "gate"]),
     source: z.object({ file: z.string(), line: z.number().optional() }),
+    status: z.enum(["active", "draft"]).optional(),
 });
+/** True when a law participates in enforcement (default active). */
+export function isActiveLaw(law) {
+    return (law.status ?? "active") !== "draft";
+}
 // Reject a malformed `from`/`to` regex when the manifest is validated — naming
 // the law id, not a bare array index — rather than letting it explode at verify
 // time. Mirrors the generation-time treatment of malformed globs.

package/dist/modules/foundation/lock.js

@@ -0,0 +1,283 @@
+/**
+ * speclaw.lock — committed digests for rule files (never under `.speclaw/`).
+ * A gitignored lock would be invisible in PR diffs and would not detect
+ * Rules File Backdoor edits. Like package-lock.json / go.sum.
+ */
+// Covers: req~speclaw-lock~1
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { pkgName, pkgVersion } from "../../shared/version.js";
+export const LOCKFILE_NAME = "speclaw.lock";
+export const LOCKFILE_VERSION = 1;
+/** Delimited provenance block excluded from digests (self-reference). */
+export const PROVENANCE_START = "<!-- speclaw:begin-provenance";
+export const PROVENANCE_END = "speclaw:end-provenance -->";
+/** Project-relative path of the committed lockfile. */
+export function lockfilePath(projectPath) {
+    return path.join(projectPath, LOCKFILE_NAME);
+}
+/**
+ * Canonical bytes for hashing: LF endings, strip provenance, trim EOL spaces,
+ * ensure a single trailing newline.
+ */
+export function canonicalize(raw) {
+    let text = raw.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+    text = stripProvenanceBlock(text);
+    text = text
+        .split("\n")
+        .map((line) => line.replace(/[ \t]+$/g, ""))
+        .join("\n");
+    if (!text.endsWith("\n"))
+        text += "\n";
+    else if (text.endsWith("\n\n")) {
+        // collapse to exactly one trailing newline
+        text = text.replace(/\n+$/g, "\n");
+    }
+    return text;
+}
+/** Remove speclaw provenance HTML comment blocks. */
+export function stripProvenanceBlock(text) {
+    const re = new RegExp(`${escapeRegExp(PROVENANCE_START)}[\\s\\S]*?${escapeRegExp(PROVENANCE_END)}\\n?`, "g");
+    return text.replace(re, "");
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** sha256 digest with `sha256:` prefix. */
+export function digestOf(canonical) {
+    const hex = crypto.createHash("sha256").update(canonical, "utf8").digest("hex");
+    return `sha256:${hex}`;
+}
+/** Digest raw file text after canonicalization. */
+export function digestText(raw) {
+    return digestOf(canonicalize(raw));
+}
+/** Root hash over sorted path → digest pairs. */
+export function rootDigest(files) {
+    const paths = Object.keys(files).sort();
+    let acc = "";
+    for (const p of paths) {
+        acc += `${p}\0${files[p].digest}\n`;
+    }
+    return digestOf(acc);
+}
+/** Read lockfile or null if missing. Throws on unknown version / parse error. */
+export function readLockfile(projectPath) {
+    const abs = lockfilePath(projectPath);
+    if (!fs.existsSync(abs))
+        return null;
+    const raw = JSON.parse(fs.readFileSync(abs, "utf8"));
+    if (typeof raw.lockfileVersion !== "number") {
+        throw new Error("speclaw.lock: missing lockfileVersion");
+    }
+    if (raw.lockfileVersion > LOCKFILE_VERSION) {
+        throw new Error(`speclaw.lock: unsupported lockfileVersion ${raw.lockfileVersion} (max ${LOCKFILE_VERSION})`);
+    }
+    return {
+        lockfileVersion: raw.lockfileVersion,
+        generator: String(raw.generator ?? ""),
+        algorithm: "sha256",
+        root: String(raw.root ?? ""),
+        files: raw.files && typeof raw.files === "object" ? raw.files : {},
+        symlinks: raw.symlinks && typeof raw.symlinks === "object" ? raw.symlinks : {},
+        accepted: Array.isArray(raw.accepted) ? raw.accepted : [],
+    };
+}
+/** Write lockfile with stable JSON formatting. */
+export function writeLockfile(projectPath, lock) {
+    const abs = lockfilePath(projectPath);
+    const body = JSON.stringify(lock, null, 2) + "\n";
+    fs.writeFileSync(abs, body);
+}
+/** Build a fresh lock object from file digests + symlinks. */
+export function buildLock(opts) {
+    const files = { ...opts.files };
+    return {
+        lockfileVersion: LOCKFILE_VERSION,
+        generator: `${pkgName()}@${pkgVersion()}`,
+        algorithm: "sha256",
+        root: rootDigest(files),
+        files,
+        symlinks: { ...(opts.symlinks ?? {}) },
+        accepted: [...(opts.accepted ?? [])],
+    };
+}
+/** Integrity severity policy for a project-relative path. */
+export function integrityPolicy(relPath) {
+    const n = relPath.split("\\").join("/");
+    // `.cursor/rules/` mirrors regenerable `ai-specs/` (gitignored) — lock/CI must
+    // not treat them as strict committed files; scan when present, never pin.
+    if (n === "AGENTS.md" ||
+        n === "CLAUDE.md" ||
+        n.startsWith(".github/instructions/") ||
+        n === ".coderabbit.yaml" ||
+        n === ".claude/rules/speclaw") {
+        return "strict";
+    }
+    if (n === "LAWS.md" || n === "docs/compass.md" || n.startsWith("docs/standards/")) {
+        return "advisory";
+    }
+    return "scan-only";
+}
+/** True when a path is an IDE mirror of regenerable (typically gitignored) content. */
+export function isRegenerableIdeMirror(relPath) {
+    const n = relPath.split("\\").join("/");
+    return (n.startsWith(".cursor/rules/") ||
+        n.startsWith(".cursor/skills/") ||
+        n.startsWith(".cursor/commands/") ||
+        n.startsWith(".claude/skills/") ||
+        n.startsWith(".claude/commands/") ||
+        n.startsWith("ai-specs/"));
+}
+/** Discover candidate paths under the project for locking / scanning. */
+export function discoverIntegrityPaths(projectPath) {
+    const files = [];
+    const symlinks = [];
+    const addFile = (rel) => {
+        const abs = path.join(projectPath, rel);
+        if (fs.existsSync(abs) && fs.statSync(abs).isFile())
+            files.push(rel.split("\\").join("/"));
+    };
+    for (const f of ["AGENTS.md", "CLAUDE.md", "LAWS.md", "docs/compass.md", ".coderabbit.yaml"]) {
+        addFile(f);
+    }
+    walkFiles(path.join(projectPath, "docs", "standards"), projectPath, files, (p) => p.endsWith(".md"));
+    walkFiles(path.join(projectPath, ".cursor", "rules"), projectPath, files, () => true);
+    walkFiles(path.join(projectPath, ".github", "instructions"), projectPath, files, () => true);
+    // Outside-pipeline / skills (scan-only)
+    for (const f of [".clinerules", ".windsurfrules", "BUGBOT.md", ".cursorrules"])
+        addFile(f);
+    walkFiles(path.join(projectPath, "ai-specs", "skills"), projectPath, files, (p) => p.endsWith("SKILL.md") || p.endsWith(".md"));
+    walkFiles(path.join(projectPath, "ai-specs", "agents"), projectPath, files, (p) => p.endsWith(".md"));
+    walkFiles(path.join(projectPath, ".claude", "skills"), projectPath, files, (p) => p.endsWith("SKILL.md") || p.endsWith(".md"));
+    const linkRel = ".claude/rules/speclaw";
+    const linkAbs = path.join(projectPath, linkRel);
+    try {
+        const st = fs.lstatSync(linkAbs);
+        if (st.isSymbolicLink()) {
+            symlinks.push({ path: linkRel, target: fs.readlinkSync(linkAbs) });
+        }
+    }
+    catch {
+        /* missing */
+    }
+    return { files: [...new Set(files)].sort(), symlinks };
+}
+function walkFiles(dir, projectPath, out, pred) {
+    if (!fs.existsSync(dir))
+        return;
+    const stack = [dir];
+    while (stack.length) {
+        const cur = stack.pop();
+        let entries;
+        try {
+            entries = fs.readdirSync(cur, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            const full = path.join(cur, e.name);
+            if (e.isDirectory())
+                stack.push(full);
+            else if (e.isFile()) {
+                const rel = path.relative(projectPath, full).split(path.sep).join("/");
+                if (pred(rel))
+                    out.push(rel);
+            }
+        }
+    }
+}
+/** Markers for the regenerable map block inside `docs/compass.md` (see compass/map.ts). */
+export const COMPASS_MAP_START = "<!-- speclaw:map:start -->";
+export const COMPASS_MAP_END = "<!-- speclaw:map:end -->";
+/**
+ * Strip the regenerable map body between markers so integrity digests stay stable
+ * across `speclaw index` (which rewrites the map in CI before verify).
+ *
+ * @param text - Full docs/compass.md contents.
+ * @returns The same text with an empty map body, or `text` if markers are missing.
+ */
+export function stripCompassMapBlock(text) {
+    const start = text.indexOf(COMPASS_MAP_START);
+    const end = text.indexOf(COMPASS_MAP_END);
+    if (start < 0 || end < 0 || end < start)
+        return text;
+    return text.slice(0, start + COMPASS_MAP_START.length) + "\n" + text.slice(end);
+}
+/**
+ * Path-specific bytes that feed {@link digestText}: speclaw-owned coderabbit
+ * region, regenerable Compass map body stripped, otherwise the file as-is.
+ *
+ * @param relPath - Project-relative path.
+ * @param raw - File contents.
+ * @returns Text to canonicalize and hash for this path.
+ */
+export function prepareIntegrityText(relPath, raw) {
+    const n = relPath.split("\\").join("/");
+    if (n === ".coderabbit.yaml")
+        return extractSpeclawYamlBlock(raw) ?? raw;
+    if (n === "docs/compass.md")
+        return stripCompassMapBlock(raw);
+    return raw;
+}
+/**
+ * Snapshot digests for discovered files with ownership policy.
+ * For `.coderabbit.yaml`, digests only the speclaw delimited block when present.
+ * For `docs/compass.md`, digests with the regenerable map body stripped.
+ */
+export function snapshotLockEntries(projectPath) {
+    const { files: paths, symlinks } = discoverIntegrityPaths(projectPath);
+    const files = {};
+    for (const rel of paths) {
+        const ownership = integrityPolicy(rel);
+        if (ownership === "scan-only")
+            continue; // locked only when previously accepted / explicit
+        const abs = path.join(projectPath, rel);
+        const raw = prepareIntegrityText(rel, fs.readFileSync(abs, "utf8"));
+        files[rel] = { digest: digestText(raw), ownership };
+    }
+    const symlinkMap = {};
+    for (const s of symlinks)
+        symlinkMap[s.path] = { target: s.target };
+    return { files, symlinks: symlinkMap };
+}
+/** Extract a speclaw-marked region from coderabbit yaml if present. */
+export function extractSpeclawYamlBlock(raw) {
+    const m = /# speclaw:begin[\s\S]*?# speclaw:end/.exec(raw);
+    if (m)
+        return m[0];
+    const m2 = /<!-- speclaw:laws:start -->[\s\S]*?<!-- speclaw:laws:end -->/.exec(raw) ??
+        /<!-- speclaw:begin-provenance[\s\S]*?speclaw:end-provenance -->/.exec(raw);
+    return m2 ? m2[0] : null;
+}
+/** Create or refresh speclaw.lock from the current tree. */
+export function refreshLockfile(projectPath) {
+    const prev = (() => {
+        try {
+            return readLockfile(projectPath);
+        }
+        catch {
+            return null;
+        }
+    })();
+    const { files, symlinks } = snapshotLockEntries(projectPath);
+    const lock = buildLock({
+        files,
+        symlinks,
+        accepted: prev?.accepted ?? [],
+    });
+    writeLockfile(projectPath, lock);
+    return lock;
+}
+/** Render a data-only provenance HTML comment (no imperatives). */
+export function provenanceBlock(opts) {
+    const laws = (opts.lawIds ?? []).map((l) => `  law: ${l}`).join("\n");
+    return (`${PROVENANCE_START}\n` +
+        (laws ? laws + "\n" : "") +
+        (opts.source ? `  source: ${opts.source}\n` : "") +
+        `  digest: ${opts.digest}\n` +
+        `  generator: ${pkgName()}@${pkgVersion()}\n` +
+        `speclaw:end-provenance -->\n`);
+}

package/dist/modules/foundation/ownership.js

@@ -1,6 +1,10 @@
 // Which scaffolded files speclaw owns vs the user owns. `speclaw update` uses
 // this split to decide what it may overwrite automatically (managed) and what it
 // must leave to the user's agent via a prompt (personalized).
+//
+// Integrity severity (`strict` / `advisory` / `scan-only` in lock.ts) is a
+// separate axis: CLAUDE.md / AGENTS.md stay PERSONALIZED for update, but are
+// `strict` for `verifyIntegrity` digest mismatches.
 /**
  * Project-relative trees that hold speclaw's workflow machinery. The user is not
  * meant to edit these, so `speclaw update` overwrites them with the current

package/dist/modules/foundation/scaffold.js

@@ -10,6 +10,9 @@ import { readManifest, writeManifest } from "../../shared/manifest.js";
 import { pkgVersion } from "../../shared/version.js";
 import { mergeSeedLaws, readLawManifest, seedManifest, writeLawManifest, } from "./laws.js";
 import { installHooks } from "./hooks.js";
+import { compileLaws } from "./compile-laws.js";
+import { refreshLockfile } from "./lock.js";
+import { refreshOwnersIfConfigured } from "../team/owners.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}}.
@@ -150,12 +153,34 @@ export function scaffold(projectPath, profile, packNames, agents = [], opts = {}
     // configured. The seam is the manifest: check-dispatcher enforces `path` laws;
     // executable-laws will extend the same manifest with more backends.
     const lawManifest = ensureLawManifest(projectPath, report);
+    try {
+        compileLaws({ projectPath, agents, writeManifest: false });
+    }
+    catch {
+        // Compilation must not fail scaffold; `speclaw laws compile` surfaces errors.
+    }
+    // Covers: req~lock-refresh-update~1
+    try {
+        refreshLockfile(projectPath);
+    }
+    catch {
+        // Lock refresh must not fail scaffold; `speclaw laws lock` surfaces errors.
+    }
     ensureVerifyWorkflow(projectPath, report);
     report.hooks = installHooks(projectPath, agents, lawManifest, report, {
         baselines: managedOpts.baselines,
         backup: managedOpts.backup,
         record,
     });
+    // Refresh CODEOWNERS managed block when the project declared team.owners —
+    // never invent owners when the key is absent.
+    try {
+        refreshOwnersIfConfigured(projectPath);
+    }
+    catch (err) {
+        // Surface as a soft note — invalid tokens should not abort scaffold/update.
+        report.skipped.push(`owners refresh skipped: ${err.message}`);
+    }
     // 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.