@esneiderbravo/speclaw 2.0.9 → 2.0.11

package/README.md

@@ -116,7 +116,7 @@ gh attestation verify <tarball> --owner esneiderbravo
 | Module | What it does |
 | :-- | :-- |
 | **Foundation** | The project's constitution: `LAWS.md` binding granular standards under `docs/standards/`, plus `CLAUDE.md` / `AGENTS.md`. **Enforced** via agent hooks (`speclaw check`), deterministic graph laws (`speclaw verify` / `laws verify`), multidialect compile (`laws compile`), and committed **`speclaw.lock`** digests + injection scan (`laws lock` / `accept` / `scan`). |
-| **Compass** | Local code graph (tree-sitter → `node:sqlite`): hybrid find (FTS5 + vectors + RRF + PageRank), impact, affected-tests, hotspots, coupling, visualize. Schema **10**. Refreshed silently at every Claude Code session start once built. No LLM — lives in `.speclaw/` (gitignored). |
+| **Compass** | Local code graph (tree-sitter → `node:sqlite`): hybrid find (FTS5 + vectors + RRF + PageRank), impact, affected-tests, hotspots, coupling, visualize. Schema **11**. Refreshed silently at every Claude Code session start once built. No LLM — lives in `.speclaw/` (gitignored). |
 | **Lawbook** | Spec-driven workflow with **adaptive ceremony** (levels 0–3), EARS linting, requirement **coverage**, sealed **drift** anchors, bugfix + `lawbook_investigate`. Artifacts under `lawbook/`. |
 | **Cortex** | **One brain. Many agents.** The multi-agent loop: durable `harness.json`, MCP tool `cortex` (`status`/`start`/`advance`/`rework`/`brief`), CLI `speclaw cortex`, skill `/lawbook/cortex`. Dispatches explorer → planner → implementer → reviewer → tester → archiver. |
 | **Team** | Declare `team.owners` in `lawbook/config.yaml`; `speclaw owners --write` compiles a managed trailing block in `.github/CODEOWNERS` (GitHub: last match wins). Doctor checks the posture. CLI-only — no MCP tool. |
@@ -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

package/dist/cli/commands/query.js

@@ -47,8 +47,11 @@ export async function runQuery(cmd, flags) {
                 console.log(s.source);
                 ui.heading("Callees");
                 r.callees?.forEach((c) => ui.info(`${c.name}${c.file ? ` (${c.file}:${c.line})` : ""}`));
+                if (r.unresolvedCallees && r.unresolvedCallees.count > 0) {
+                    ui.info(`+ ${r.unresolvedCallees.count} unresolved call(s): ${r.unresolvedCallees.sample.join(", ")}`);
+                }
                 ui.heading("Callers");
-                r.callers?.forEach((c) => ui.info(`${c.name} (${c.file}:${c.line})`));
+                r.callers?.forEach((c) => ui.info(`${c.kind === "file" ? "(file) " : ""}${c.name} (${c.file}:${c.line})`));
                 return;
             }
             case "search":
@@ -147,7 +150,14 @@ export async function runQuery(cmd, flags) {
                 ui.info(result.reason);
                 result.tests.forEach((t) => ui.info(t.file));
                 ui.heading("Command");
-                console.log(result.command);
+                // Covers: req~affected-test-selection~1
+                if (result.command === null) {
+                    console.log(`no command: ${result.commandReason}`);
+                }
+                else {
+                    console.log(result.command);
+                    ui.info(result.commandReason);
+                }
                 result.warnings.forEach((w) => ui.warn(w));
                 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

@@ -237,6 +237,38 @@ const MIGRATIONS = [
             "`speclaw.lock`.\n" +
             "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
     },
+    {
+        version: "2.0.10",
+        describe: "Compass schema 11 — truthful callers, callees, and affected-test commands",
+        agentPrompt: "- Compass is now **schema 11**: the first `speclaw index` after upgrading migrates " +
+            "10→11 and re-extracts every file once (embeddings are reused). Where the project " +
+            'mentions "Schema **10**" or "Compass (schema 10)", change it to schema 11 ' +
+            "(10→11 forces a reindex; embeddings reused).\n" +
+            "- speclaw 2.0.9 or older (including an MCP entry pinned at `@2.0.9` or a stale " +
+            "global CLI) treats a schema-11 index as incompatible and rebuilds it from scratch, " +
+            "dropping the embedding cache. Where the project documents the index or the MCP entry, " +
+            "add: run `speclaw update` so the pinned MCP entry moves to 2.0.10; an older speclaw " +
+            "opening this index rebuilds it from scratch.\n" +
+            "- Affected-test `command` may now be `null` (with `commandReason`) when no test is " +
+            "reachable, and `commands[]` lists one `{ cwd, command, files }` per package. If the " +
+            "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

@@ -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":
@@ -165,8 +169,8 @@ async function main() {
     const flags = parseFlags(rest);
     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/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.
 `,
     },
     {

package/dist/modules/compass/affected-config.js

@@ -10,10 +10,15 @@ const DEFAULT_TARGETS = {
         exclude: ["**/*.{test,spec}.{ts,tsx,js,jsx,mts,cts}", "test/**", "tests/**"],
     },
     test: {
+        // The `**/` forms cover workspace packages (`apps/web/src/**`), whose
+        // changes would otherwise be filtered out before any test is selected.
         include: [
             "src/**",
             "test/**",
             "tests/**",
+            "**/src/**",
+            "**/test/**",
+            "**/tests/**",
             "**/*.{test,spec}.{ts,tsx,js,jsx}",
             "**/conftest.py",
         ],