@esneiderbravo/speclaw 2.0.10 → 2.0.12

package/README.md

@@ -250,7 +250,11 @@ hooks into that agent's settings **by identity** — it never touches hooks you
 added yourself. The same merge adds one `SessionStart` command hook that
 silently refreshes an existing Compass index when a session starts
 (`speclaw session-start`; it skips when no index exists, never downloads or
-contacts the registry, and always exits 0). The compiled law manifest lives in `.speclaw/laws-manifest.json`
+contacts the registry, and always exits 0), and one separate `PostToolUse`
+command hook for `Write|Edit|MultiEdit|NotebookEdit` that hands each edited
+file to `speclaw reindex-file`, which re-indexes it in a detached background
+process (silent, always exit 0; PageRank and the compact map catch up on the
+next full run). The compiled law manifest lives in `.speclaw/laws-manifest.json`
 (gitignored) and is **adapted to the target tree** on `init`/`update` — speclaw's
 own architecture laws are seeded only when those paths exist, and the cycle law
 follows `apps/*/src`, `packages/*/src`, or `src/` rather than copying
@@ -306,6 +310,10 @@ speclaw laws accept AGENTS.md   # interactive TTY only — never via MCP
 speclaw laws lock --force       # list drifted files, confirm, re-baseline — interactive TTY only
 ```
 
+`speclaw laws scan` (text or `--json`) exits 1 when `speclaw.lock` cannot be
+read or a finding has severity `error`. On an unreadable lock it names the lock
+error (`lockError` in the JSON) and still reports every injection finding.
+
 A lock refresh (`init`, `update`, `laws compile`, `laws lock`) never launders an
 edit: a strict file (`CLAUDE.md`, `AGENTS.md`, compiled rules) that drifted from
 the lock outside speclaw **keeps its locked digest**, and the command warns

package/dist/cli/commands/cortex.js

@@ -1,6 +1,6 @@
 import { handleHarness, readHarness } from "../../modules/cortex/harness.js";
 import { briefForStage } from "../../modules/cortex/brief.js";
-import { list } from "../lib/args.js";
+import { repeated } from "../lib/args.js";
 import { ui } from "../lib/ui.js";
 const OPS = ["status", "start", "advance", "rework", "brief"];
 /**
@@ -36,7 +36,8 @@ export async function runCortex(flags) {
             change: changeName,
             harnessOp: op,
             verdict: verdict ?? null,
-            openQuestions: list(flags.question),
+            // Covers: req~harness-state~1
+            openQuestions: repeated(flags.question),
             pauseForQuestions: Boolean(flags["pause-questions"]),
             note: typeof flags.note === "string" ? flags.note : undefined,
         });

package/dist/cli/commands/lawbook.js

@@ -5,7 +5,7 @@ import { scaffoldFeature } from "../../modules/lawbook/scaffold-change.js";
 import { investigate, formatInvestigateResult } from "../../modules/lawbook/investigate.js";
 import { handleHarness } from "../../modules/cortex/harness.js";
 import { printHarnessWarnings } from "./cortex.js";
-import { list } from "../lib/args.js";
+import { list, repeated } from "../lib/args.js";
 import { ui } from "../lib/ui.js";
 function today() {
     // The MCP path passes the date in; the CLL runs on a real machine, so read it here.
@@ -181,7 +181,8 @@ export async function runSpec(flags) {
                     change: changeName,
                     harnessOp: op,
                     verdict: verdict ?? null,
-                    openQuestions: list(flags.question),
+                    // Covers: req~harness-state~1
+                    openQuestions: repeated(flags.question),
                     pauseForQuestions: Boolean(flags["pause-questions"]),
                     note: typeof flags.note === "string" ? flags.note : undefined,
                 });

package/dist/cli/commands/laws.js

@@ -73,13 +73,21 @@ export async function runLaws(flags) {
         return;
     }
     if (sub === "scan") {
+        // Text and --json share one exit rule: 1 on an unreadable lock or any
+        // error-severity finding, else 0.
+        // Covers: req~injection-scan~1, req~laws-integrity-cli~1
         const report = verifyIntegrity({ projectPath: process.cwd(), checks: "scan" });
+        const failed = report.lockError !== undefined || report.findings.some((f) => f.severity === "error");
         if (flags.json) {
             console.log(JSON.stringify(report, null, 2));
+            if (failed)
+                process.exit(1);
             return;
         }
         ui.heading("speclaw laws scan");
-        if (report.findings.length === 0) {
+        if (report.lockError !== undefined)
+            ui.err(report.lockError);
+        if (report.findings.length === 0 && report.lockError === undefined) {
             ui.ok("No injection findings.");
             return;
         }
@@ -91,7 +99,7 @@ export async function runLaws(flags) {
             else
                 ui.warn(msg);
         }
-        if (report.findings.some((f) => f.severity === "error"))
+        if (failed)
             process.exit(1);
         return;
     }

package/dist/cli/commands/reindex-file.js

@@ -0,0 +1,146 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { helpFor } from "../lib/help.js";
+import { realPathOf } from "../../shared/paths.js";
+/** Hook payloads are small JSON objects; anything larger is not one. */
+const MAX_PAYLOAD_BYTES = 1024 * 1024;
+/**
+ * Split raw arguments into file paths: every token after `--`, and every
+ * token before it that does not look like a flag.
+ *
+ * @param args - The arguments after `reindex-file`.
+ * @returns The path arguments, in order.
+ */
+export function reindexPathArgs(args) {
+    const out = [];
+    let rest = false;
+    for (const a of args) {
+        if (rest)
+            out.push(a);
+        else if (a === "--")
+            rest = true;
+        else if (!a.startsWith("-"))
+            out.push(a);
+    }
+    return out;
+}
+/**
+ * The absolute file a `PostToolUse` hook payload edited: the first non-empty of
+ * `tool_input.file_path` and `tool_input.notebook_path`, a relative value
+ * resolved against the payload's absolute `cwd`, else against `fallbackCwd`.
+ *
+ * @param payload - The parsed hook JSON.
+ * @param fallbackCwd - Base for a relative path when the payload has no absolute `cwd`.
+ * @returns The absolute path, or `null` when the payload names no file.
+ */
+export function hookTarget(payload, fallbackCwd) {
+    if (!payload || typeof payload !== "object")
+        return null;
+    const p = payload;
+    const input = p.tool_input;
+    if (!input || typeof input !== "object")
+        return null;
+    const pick = (v) => typeof v === "string" && v.trim() !== "" ? v.trim() : null;
+    const target = pick(input.file_path) ?? pick(input.notebook_path);
+    if (target === null)
+        return null;
+    const base = typeof p.cwd === "string" && path.isAbsolute(p.cwd) ? p.cwd : fallbackCwd;
+    return path.resolve(base, target);
+}
+/** Whether `abs` lies strictly inside `root` (symlinked prefixes such as macOS `/var` resolved). */
+function insideRoot(root, abs) {
+    const rel = path.relative(realPathOf(root), realPathOf(abs));
+    return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
+}
+/** Read stdin to its end; `null` when it exceeds the payload cap (still drained). */
+async function readPayload(stdin) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of stdin) {
+        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+        size += buf.length;
+        if (size <= MAX_PAYLOAD_BYTES)
+            chunks.push(buf);
+    }
+    return size > MAX_PAYLOAD_BYTES ? null : Buffer.concat(chunks).toString("utf8");
+}
+/**
+ * `speclaw reindex-file [--] <path>...` and its hook mode.
+ *
+ * - **Path mode** (paths given): re-index exactly those files in the foreground
+ *   with Compass `indexFiles` — the detached child, tests, the bench, and manual
+ *   use run this.
+ * - **Hook mode** (no path): read the Claude Code `PostToolUse` JSON from stdin,
+ *   take `tool_input.file_path` / `notebook_path`, and hand it to a detached
+ *   `speclaw reindex-file -- <abs>` child, then return without waiting, so the
+ *   edit is not slowed. This branch never opens the database or loads Compass
+ *   (or tree-sitter). With stdin on a terminal it prints usage instead of
+ *   blocking.
+ *
+ * The project root is the working directory (where the hook guard found
+ * `.speclaw/index.db`); a payload `cwd` only resolves a relative file path, so
+ * a payload cannot redirect writes into another project's index. With no index
+ * it does nothing and creates nothing. It prints nothing, is never logged as a
+ * Compass call, and swallows every failure (including `SQLITE_BUSY`): the
+ * caller always sees exit 0.
+ *
+ * @param args - Raw arguments after `reindex-file` (`--` honored).
+ * @param cwd - Project root (defaults to the process working directory).
+ * @param opts - `entry`: the CLI script the detached child runs (defaults to
+ *   this process's `argv[1]`); `stdin`: the payload stream (defaults to
+ *   `process.stdin`). Both are test seams.
+ */
+// Covers: req~reindex-on-edit~1
+export async function runReindexFile(args, cwd = process.cwd(), opts = {}) {
+    // Node lines that still flag `node:sqlite` as experimental would print an
+    // ExperimentalWarning to stderr; this command must print nothing.
+    process.removeAllListeners("warning");
+    try {
+        const paths = reindexPathArgs(args);
+        const hasIndex = () => fs.existsSync(path.join(cwd, ".speclaw", "index.db"));
+        if (paths.length > 0) {
+            if (!hasIndex())
+                return;
+            const { indexFiles } = await import("../../modules/compass/indexer.js");
+            await indexFiles(cwd, paths);
+            return;
+        }
+        const stdin = opts.stdin ?? process.stdin;
+        if (stdin.isTTY) {
+            process.stdout.write(helpFor("reindex-file") ?? "");
+            return;
+        }
+        const raw = await readPayload(stdin);
+        if (raw === null)
+            return;
+        let payload;
+        try {
+            payload = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        const target = hookTarget(payload, cwd);
+        if (target === null || !hasIndex() || !insideRoot(cwd, target))
+            return;
+        const entry = opts.entry ?? process.argv[1];
+        if (!entry)
+            return;
+        // detached: its own process group, so neither the hook timeout nor the
+        // agent's cleanup of the hook's group kills it. `--` keeps a path that
+        // starts with "-" from reading as a flag.
+        const child = spawn(process.execPath, [entry, "reindex-file", "--", target], {
+            cwd,
+            detached: true,
+            stdio: "ignore",
+            windowsHide: true,
+        });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        // A concurrent writer (SQLITE_BUSY after busy_timeout) or any other failure
+        // must never fail or print into the agent's edit.
+    }
+}

package/dist/cli/commands/update.js

@@ -254,6 +254,21 @@ const MIGRATIONS = [
             "project's docs or scripts run `command` blindly, make them handle `null`.\n" +
             "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
     },
+    {
+        version: "2.0.11",
+        describe: "Compass re-indexes each file an agent edits (PostToolUse → speclaw reindex-file)",
+        agentPrompt: "- For hook-capable agents (Claude Code), `init`/`update` now add one more `PostToolUse` " +
+            "command hook (matcher `Write|Edit|MultiEdit|NotebookEdit`, timeout 10) that hands the " +
+            "edited file to `speclaw reindex-file` in a detached background process: silent, always " +
+            "exit 0, skipped when `.speclaw/index.db` is absent, never downloads. This update reports " +
+            "the agent settings file under `refreshedDiverged` once; that is expected.\n" +
+            "- Where the project documents how the Compass index stays fresh (session start, " +
+            "`compass_index`, `speclaw watch`), add: each Write/Edit is re-indexed right after the " +
+            "edit; PageRank and the compact map in `docs/compass.md` catch up on the next full run; " +
+            "files created or renamed by shell commands and edits by agents without hooks are picked " +
+            "up at the next session start or `compass_index`.\n" +
+            "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
+    },
 ];
 /**
  * Bring the current project up to date without a full re-init. When the npm

package/dist/cli/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { parseFlags } from "./lib/args.js";
+import { parseFlags, REPEATABLE_FLAGS } from "./lib/args.js";
 import { ui, header } from "./lib/ui.js";
 import { maybeNotifyUpdate } from "./lib/update-check.js";
 import { GLOBAL_HELP as HELP, helpFor, knownCommands, wantsHelp } from "./lib/help.js";
@@ -36,7 +36,8 @@ const HEADER_COMMANDS = new Set([
  * forced-color signal counts as interactive so the header is exercisable in a
  * child process. `budget --json`, `doctor --json`, and `coverage` when emitting
  * TAP/JSON (or when stdout is not a TTY) are machine-consumed and suppress the
- * header. `session-start` is not header-eligible: it must print nothing.
+ * header. `session-start` and `reindex-file` are not header-eligible: they must print
+ * nothing.
  */
 function maybeHeader(cmd, flags) {
     if (!process.stdout.isTTY && process.env.FORCE_COLOR !== "1")
@@ -106,6 +107,9 @@ async function dispatch(cmd, flags) {
             return (await import("./commands/index-build.js")).runWatch(flags);
         case "session-start":
             return (await import("./commands/session-start.js")).runSessionStart();
+        case "reindex-file":
+            // Raw argv: the shared flag parser would read `-- <path>` as a flag value.
+            return (await import("./commands/reindex-file.js")).runReindexFile(process.argv.slice(3));
         case "explore":
         case "search":
         case "recall":
@@ -162,11 +166,11 @@ async function main() {
         process.exitCode = 0;
         return;
     }
-    const flags = parseFlags(rest);
+    const flags = parseFlags(rest, REPEATABLE_FLAGS);
     maybeHeader(cmd, flags);
     await dispatch(cmd, flags);
-    // The SessionStart hook's refresh must stay silent: no update notice either.
-    if (cmd === "session-start")
+    // The SessionStart and edit hooks must stay silent: no update notice either.
+    if (cmd === "session-start" || cmd === "reindex-file")
         return;
     await maybeNotifyUpdate(cmd);
 }

package/dist/cli/lib/args.js

@@ -1,23 +1,37 @@
 /**
- * Minimal flag parser: `--key value`, `--key=value`, `--bool`, `-x`.
+ * Minimal flag parser: `--key value`, `--key=value`, `--bool`, `-x`. A repeated
+ * key keeps its last value unless it is listed in `repeatable`.
  *
  * @param argv - Raw argument tokens (already stripped of the command name).
+ * @param repeatable - Keys whose every value is kept: such a key always yields a
+ *   `string[]` in argv order, and its values are never split at commas.
  * @returns Flags with named options set and non-flag tokens collected in `_`.
  */
-export function parseFlags(argv) {
+export function parseFlags(argv, repeatable = []) {
     const flags = { _: [] };
+    const set = (key, value) => {
+        const prev = flags[key];
+        if (repeatable.includes(key) && (typeof value === "string" || Array.isArray(prev))) {
+            // A bare repeatable flag after real values adds nothing and drops nothing.
+            if (typeof value === "string")
+                flags[key] = Array.isArray(prev) ? [...prev, value] : [value];
+        }
+        else {
+            flags[key] = value;
+        }
+    };
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if (arg.startsWith("--")) {
             const [key, inlineVal] = arg.slice(2).split("=", 2);
             if (inlineVal !== undefined) {
-                flags[key] = inlineVal;
+                set(key, inlineVal);
             }
             else if (i + 1 < argv.length && !argv[i + 1].startsWith("-")) {
-                flags[key] = argv[++i];
+                set(key, argv[++i]);
             }
             else {
-                flags[key] = true;
+                set(key, true);
             }
         }
         else if (arg.startsWith("-")) {
@@ -29,6 +43,22 @@ export function parseFlags(argv) {
     }
     return flags;
 }
+/** Flags that may be passed more than once; each occurrence is one value. */
+export const REPEATABLE_FLAGS = ["question"];
+/**
+ * The values of a repeatable flag parsed with {@link REPEATABLE_FLAGS}, as-is:
+ * in argv order and never split at commas.
+ *
+ * @param value - The parsed flag value.
+ * @returns The string values; empty when the flag is absent or a bare boolean.
+ */
+export function repeated(value) {
+    if (Array.isArray(value))
+        return value;
+    if (typeof value === "string")
+        return [value];
+    return [];
+}
 /**
  * Normalize a flag value into a list, splitting comma-separated strings.
  *

package/dist/cli/lib/help.js

@@ -24,6 +24,7 @@ Setup
 Compass (code intelligence — the same surface agents use via MCP)
   index                    (Re)build the local code graph (--force / --prune / --json)
   session-start            Silent, fail-safe refresh of an existing index (SessionStart hook)
+  reindex-file [paths...]  Silent re-index of edited files (PostToolUse hook; stdin JSON)
   watch                    Keep the index fresh on file changes
   explore <node>           A node's source + callers/callees
   search <query>           Hybrid find (BM25+vector+name); --focus --max-tokens --explain
@@ -171,6 +172,24 @@ Keep the Compass index fresh: re-index changed files until interrupted (Ctrl-C).
 
 Silent, fail-safe refresh of an existing Compass index. The SessionStart hook
 runs it; it prints nothing and never fails the session.
+`,
+    },
+    {
+        name: "reindex-file",
+        usage: `Usage: speclaw reindex-file [--] <path>...
+       speclaw reindex-file < hook.json
+
+Re-index single files in an existing Compass index, silently and fail-safe.
+
+With paths, re-indexes exactly those files now (a deleted file is removed;
+paths outside the project, in skipped directories, of no indexed language, or
+over the size cap are ignored). With no path, reads a PostToolUse hook payload
+from stdin and re-indexes tool_input.file_path (or notebook_path) in a detached
+background process, returning at once. The PostToolUse hook for
+Write|Edit|MultiEdit|NotebookEdit runs it.
+
+PageRank and docs/compass.md are left to the next full run (session start,
+speclaw index, compass_index, watch). Prints nothing and always exits 0.
 `,
     },
     {
@@ -312,7 +331,7 @@ Options
   --change <name>      The change (or pass it as the second argument)
   --verdict <v>        PASS or FAIL (advance from reviewing/testing)
   --note <text>        A history note
-  --question <text>    An open question (repeatable)
+  --question <text>    One open question, commas included; repeat for more
   --pause-questions    Pause the loop for open questions
   --json               Print the result as JSON
 `,

package/dist/modules/compass/db.js

@@ -568,6 +568,67 @@ export function needsReindex(db) {
 export function clearNeedsReindex(db) {
     db.prepare("DELETE FROM meta WHERE key = 'needs_reindex'").run();
 }
+/** `meta` key set by a per-file reindex until the next full post-processing pass. */
+const POST_PENDING_KEY = "post_pending";
+/**
+ * Whether a per-file reindex left global post-processing (PageRank, the compact
+ * map, cache upkeep) for the next full run. While set, a full run may not take
+ * its no-op fast path.
+ */
+export function postPending(db) {
+    const row = db.prepare("SELECT value FROM meta WHERE key = ?").get(POST_PENDING_KEY);
+    return row?.value === "1";
+}
+/** Record that a per-file reindex wrote rows and deferred the global pass. */
+export function setPostPending(db) {
+    db.prepare("INSERT INTO meta(key, value) VALUES (?, '1') ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(POST_PENDING_KEY);
+}
+/** Clear the per-file marker once a full run has done the global pass. */
+export function clearPostPending(db) {
+    db.prepare("DELETE FROM meta WHERE key = ?").run(POST_PENDING_KEY);
+}
+/**
+ * Whether an open index is current for a per-file write: this release's schema
+ * version and edge shape, not stale, and no full reindex pending. Callers that
+ * probe before taking the write lock re-check under it.
+ */
+export function isCurrentIndex(db) {
+    return (readSchemaVersion(db) === SCHEMA_VERSION && hasEdgeSpec(db) && !isStale(db) && !needsReindex(db));
+}
+/**
+ * Open an existing index for a per-file write only when it is current.
+ *
+ * Unlike {@link openDb}, this never creates the `.speclaw` directory or the
+ * database, and never migrates, wipes, or re-stamps a schema: a missing index,
+ * an old or stale schema, or a pending full reindex returns `null` after a
+ * read-only probe, so the caller writes nothing and leaves the repair to the
+ * next full run.
+ *
+ * @param projectPath - Absolute path to the project root.
+ * @returns A read-write connection (WAL, foreign keys, 5 s busy timeout), or `null`.
+ */
+export function openCurrentDb(projectPath) {
+    const file = indexPath(projectPath);
+    if (!fs.existsSync(file))
+        return null;
+    let current;
+    const probe = new DatabaseSync(file, { readOnly: true });
+    try {
+        probe.exec("PRAGMA busy_timeout = 5000;");
+        current = isCurrentIndex(probe);
+    }
+    catch {
+        current = false;
+    }
+    finally {
+        probe.close();
+    }
+    if (!current)
+        return null;
+    const db = new DatabaseSync(file);
+    db.exec("PRAGMA foreign_keys = ON; PRAGMA busy_timeout = 5000;");
+    return db;
+}
 /** Absolute path to the index database file for a project. */
 export function indexPath(projectPath) {
     return path.join(projectPath, ".speclaw", "index.db");