@esneiderbravo/speclaw 2.0.10 → 2.0.11

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

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

@@ -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/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");

package/dist/modules/compass/indexer.js

@@ -1,13 +1,14 @@
 import fs from "node:fs";
 import path from "node:path";
 import { createHash } from "node:crypto";
-import { openDb, clearNeedsReindex, needsReindex, FILE_NODE_KIND } from "./db.js";
+import { openDb, openCurrentDb, isCurrentIndex, clearNeedsReindex, needsReindex, postPending, setPostPending, clearPostPending, FILE_NODE_KIND, } from "./db.js";
 import { langForPath } from "./languages.js";
 import { extract, importSpecifier } from "./extract.js";
 import { getEmbedder, toBlob } from "./embedder.js";
 import { contentHashFor, defaultEmbedText } from "./embed-input.js";
-import { buildDirHashMap } from "./merkle.js";
-import { loadAffectedConfig, isTestPath, inferModule } from "./affected-config.js";
+import { buildDirHashMap, dirHash, HASH_EMPTY } from "./merkle.js";
+import { loadAffectedConfig, isTestPath, inferModule, } from "./affected-config.js";
+import { realPathOf } from "../../shared/paths.js";
 import { personalizedPageRank, edgeWeightMul } from "./pagerank.js";
 const SKIP_DIRS = new Set([
     ".git",
@@ -30,6 +31,132 @@ const SKIP_DIRS = new Set([
     ".cache",
 ]);
 const MAX_FILE_BYTES = 1_500_000;
+/**
+ * Whether a directory or file name inside the project is walked by a full index.
+ * The single source of the skip rule shared by the walk and per-file reindex.
+ */
+function isSkippedDir(name) {
+    return SKIP_DIRS.has(name);
+}
+/**
+ * `p` with symlinks resolved and, where the platform reports it (macOS,
+ * Windows), each existing segment spelled as stored on disk. A missing tail
+ * keeps its given spelling. Falls back to {@link realPathOf} when the native
+ * resolver fails.
+ *
+ * @param p - An absolute path.
+ */
+function canonicalPathOf(p) {
+    const tail = [];
+    let cur = path.resolve(p);
+    for (;;) {
+        try {
+            return path.join(fs.realpathSync.native(cur), ...tail.reverse());
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== "ENOENT" && code !== "ENOTDIR")
+                return realPathOf(p);
+            const parent = path.dirname(cur);
+            if (parent === cur)
+                return realPathOf(p);
+            tail.push(path.basename(cur));
+            cur = parent;
+        }
+    }
+}
+/**
+ * Classify one path against the full walk's file-set rules, so a per-file
+ * reindex and a full index agree on which files are indexed (and the directory
+ * Merkle tree stays the hash of the same file set).
+ *
+ * A path is eligible when it lies inside `projectPath` (symlinks in its existing
+ * prefix resolved, and its spelling taken from the filesystem where the platform
+ * reports it, so a case variant on a case-insensitive volume yields the stored
+ * spelling), no directory segment is a skipped directory, its extension
+ * maps to an indexed language, it is a regular file, and it does not exceed the
+ * walk's size cap. A path that does not exist yields `missing` with its
+ * repo-relative form, so the caller can drop a deleted file's rows.
+ *
+ * @param projectPath - Absolute project root.
+ * @param absPath - Absolute path to classify.
+ */
+export function classifyIndexPath(projectPath, absPath) {
+    const relNative = path.relative(canonicalPathOf(projectPath), canonicalPathOf(absPath));
+    if (!relNative || relNative.startsWith("..") || path.isAbsolute(relNative)) {
+        return { eligible: false, rel: null, reason: "outside" };
+    }
+    const rel = relNative.split(path.sep).join("/");
+    const parts = rel.split("/");
+    if (parts.slice(0, -1).some(isSkippedDir))
+        return { eligible: false, rel, reason: "ignored" };
+    const lang = langForPath(rel);
+    if (!lang)
+        return { eligible: false, rel, reason: "language" };
+    let stat;
+    try {
+        stat = fs.statSync(path.join(projectPath, rel));
+    }
+    catch {
+        return { eligible: false, rel, reason: "missing" };
+    }
+    if (!stat.isFile())
+        return { eligible: false, rel, reason: "ignored" };
+    if (stat.size > MAX_FILE_BYTES)
+        return { eligible: false, rel, reason: "size" };
+    return { eligible: true, rel, lang, size: stat.size, mtimeMs: Math.trunc(stat.mtimeMs) };
+}
+/**
+ * Whether a full walk of `projectPath` would yield exactly `rel`: every segment
+ * is listed by its parent directory with exactly that spelling (a case-sensitive
+ * compare, so a case-only rename on a case-insensitive volume does not match),
+ * every directory segment is a real, non-skipped directory and the leaf a
+ * regular file (no segment is a symlink, as the walk never follows one), and
+ * {@link classifyIndexPath} finds it eligible under the same `rel`.
+ *
+ * A full run keeps a stored row its walk did not see only when this holds;
+ * any other row would duplicate the file's symbols under a second path.
+ *
+ * @param projectPath - Absolute project root (as walked).
+ * @param rel - Repo-relative path with `/` separators.
+ * @param listings - Optional cache of directory listings, keyed by absolute
+ *   directory, shared across calls in one run.
+ */
+export function walkWouldYield(projectPath, rel, listings = new Map()) {
+    const parts = rel.split("/");
+    if (parts.some((p) => p === "" || p === "." || p === ".."))
+        return false;
+    let dir = projectPath;
+    for (let i = 0; i < parts.length; i++) {
+        const name = parts[i];
+        let names = listings.get(dir);
+        if (names === undefined) {
+            try {
+                names = new Set(fs.readdirSync(dir));
+            }
+            catch {
+                names = null;
+            }
+            listings.set(dir, names);
+        }
+        if (!names?.has(name))
+            return false;
+        const full = path.join(dir, name);
+        let stat;
+        try {
+            stat = fs.lstatSync(full);
+        }
+        catch {
+            return false;
+        }
+        const leaf = i === parts.length - 1;
+        if (leaf ? !stat.isFile() : !stat.isDirectory() || isSkippedDir(name))
+            return false;
+        dir = full;
+    }
+    const c = classifyIndexPath(projectPath, path.join(projectPath, rel));
+    return c.eligible && c.rel === rel;
+}
 function hashOf(content) {
     return createHash("sha256").update(content).digest("hex");
 }
@@ -431,7 +558,7 @@ function* walkFiles(root) {
         for (const entry of entries) {
             const full = path.join(dir, entry.name);
             if (entry.isDirectory()) {
-                if (!SKIP_DIRS.has(entry.name))
+                if (!isSkippedDir(entry.name))
                     stack.push(full);
             }
             else if (entry.isFile()) {
@@ -441,6 +568,152 @@ function* walkFiles(root) {
         }
     }
 }
+function prepareFileWriter(db, embedder, cfg, touch = true) {
+    return {
+        db,
+        touch,
+        collectOwners: !touch,
+        embedder,
+        cfg,
+        insFile: db.prepare("INSERT INTO files(path, hash, lang, is_test, module, mtime_ms, size) VALUES (?, ?, ?, ?, ?, ?, ?)"),
+        updFile: db.prepare("UPDATE files SET hash = ?, lang = ?, is_test = ?, module = ?, mtime_ms = ?, size = ? WHERE id = ?"),
+        detach: db.prepare("UPDATE edges SET dst_node_id = NULL WHERE dst_node_id IN (SELECT id FROM nodes WHERE file_id = ?)"),
+        detachedOwners: db.prepare(`SELECT DISTINCT src_file_id AS id FROM edges
+       WHERE src_file_id <> ? AND dst_node_id IN (SELECT id FROM nodes WHERE file_id = ?)`),
+        delNodes: db.prepare("DELETE FROM nodes WHERE file_id = ?"),
+        delEdges: db.prepare("DELETE FROM edges WHERE src_file_id = ?"),
+        delCoverage: db.prepare("DELETE FROM coverage_links WHERE file_path = ?"),
+        delFile: db.prepare("DELETE FROM files WHERE id = ?"),
+        insNode: db.prepare(`INSERT INTO nodes(file_id, name, kind, start_line, end_line, start_byte, end_byte, parent_id, signature, body_hash, norm_hash, content_hash)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`),
+        insMetrics: db.prepare(`INSERT INTO node_metrics(node_id, loc, max_nesting, branches) VALUES (?, ?, ?, ?)`),
+        insEdge: db.prepare(`INSERT INTO edges(src_node_id, src_file_id, dst_name, kind, line, is_member, spec) VALUES (?, ?, ?, ?, ?, ?, ?)`),
+        insCoverage: db.prepare(`INSERT OR REPLACE INTO coverage_links(
+         artifact_type, name, revision, kind, file_path, line, node_id, source_type, origin
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`),
+        insCache: db.prepare(`INSERT INTO embedding_cache(content_hash, model, dim, vec, created_at, last_seen_at)
+       VALUES (?, ?, ?, ?, ?, ?)
+       ON CONFLICT(content_hash, model) DO UPDATE SET last_seen_at = excluded.last_seen_at`),
+        hasCache: db.prepare(`SELECT 1 AS ok FROM embedding_cache WHERE content_hash = ? AND model = ?`),
+        touchCache: db.prepare(`UPDATE embedding_cache SET last_seen_at = ? WHERE content_hash = ? AND model = ?`),
+        insNodeText: db.prepare(`INSERT INTO node_text(node_id, name, subtokens, signature, doc) VALUES (?, ?, ?, ?, ?)
+       ON CONFLICT(node_id) DO UPDATE SET
+         name = excluded.name,
+         subtokens = excluded.subtokens,
+         signature = excluded.signature,
+         doc = excluded.doc`),
+    };
+}
+/**
+ * Reset every edge whose destination is one of a file's nodes, before those
+ * nodes are deleted. Without this, a rowid freed by the delete and reused by a
+ * node inserted later in the same run would silently re-point another file's
+ * edge at an unrelated symbol; a post-hoc "id not in nodes" check cannot see
+ * that. The run's resolution pass then re-binds the edges by their rules.
+ *
+ * @returns The ids of the other files whose edges were reset (empty on a full run, which does not need them).
+ */
+function detachFileNodes(w, fileId) {
+    // Covers: req~edge-ids-survive-reindex~1
+    const owners = w.collectOwners
+        ? w.detachedOwners.all(fileId, fileId).map((r) => r.id)
+        : [];
+    w.detach.run(fileId);
+    return owners;
+}
+/**
+ * Drop a removed file: detach edges into it, delete its coverage links (the
+ * file-level ones have no node to cascade from), then delete its row (nodes and
+ * edges cascade).
+ */
+function removeFileRows(w, fileId, rel) {
+    const owners = detachFileNodes(w, fileId);
+    w.delCoverage.run(rel);
+    w.delFile.run(fileId);
+    return owners;
+}
+/**
+ * (Re-)extract one file and write its whole fragment: upsert its `files` row,
+ * replace its nodes, file-owner node, edges, `node_text`/FTS rows, metrics, and
+ * coverage links, and embed cache misses through `embedding_cache`. Edges are
+ * written unresolved; the caller runs {@link resolveEdges}.
+ *
+ * @returns The file id and the ids of other files whose edges were detached.
+ */
+async function writeFileFragment(w, f) {
+    const { rel, lang, content, stats } = f;
+    let fileId;
+    let detachedOwners = [];
+    const isTest = isTestPath(rel, w.cfg.testGlobs) ? 1 : 0;
+    const mod = inferModule(rel);
+    if (f.priorId !== null) {
+        w.updFile.run(f.hash, lang.id, isTest, mod, f.mtimeMs, f.size, f.priorId);
+        // Covers: req~edge-ids-survive-reindex~1
+        detachedOwners = detachFileNodes(w, f.priorId);
+        w.delNodes.run(f.priorId);
+        w.delEdges.run(f.priorId);
+        w.delCoverage.run(rel);
+        fileId = f.priorId;
+    }
+    else {
+        fileId = Number(w.insFile.run(rel, f.hash, lang.id, isTest, mod, f.mtimeMs, f.size).lastInsertRowid);
+    }
+    const { symbols, refs, coverage, reexports } = await extract(content, lang);
+    const nodeIds = [];
+    const now = Date.now();
+    for (const s of symbols) {
+        const parentId = s.parentIndex !== null ? nodeIds[s.parentIndex] : null;
+        const embedText = defaultEmbedText(s.kind, s.name, s.signature);
+        const ch = contentHashFor({
+            lang: lang.id,
+            kind: s.kind,
+            name: s.name,
+            signature: s.signature,
+            embedText,
+        });
+        const id = Number(w.insNode.run(fileId, s.name, s.kind, s.startLine, s.endLine, s.startByte, s.endByte, parentId, s.signature, s.bodyHash, s.normHash, ch).lastInsertRowid);
+        nodeIds.push(id);
+        w.insMetrics.run(id, s.loc, s.maxNesting, s.branches);
+        w.insNodeText.run(id, s.name, s.subtokens, s.signature ?? "", s.docstring);
+        const hit = w.hasCache.get(ch, w.embedder.id);
+        if (hit) {
+            if (w.touch)
+                w.touchCache.run(now, ch, w.embedder.id);
+            stats.fromCache++;
+        }
+        else {
+            const vec = await w.embedder.embed(embedText);
+            w.insCache.run(ch, w.embedder.id, w.embedder.dim, toBlob(vec), now, now);
+            stats.computed++;
+        }
+        stats.embeddings++;
+    }
+    // Covers: req~impact-id-first~1
+    // Imports and calls outside any definition belong to the file: give the
+    // file one hidden owner node so no edge is ever stored ownerless. A file
+    // with no symbols or with re-exports (a barrel: `export * from "./x"`)
+    // gets one too, so an import of it resolves to the file instead of
+    // looking like a package. It gets no text, embedding, or metrics.
+    const isOrphan = (r) => r.kind === "import" || r.ownerIndex === null;
+    let fileOwner = null;
+    if (refs.some(isOrphan) || symbols.length === 0 || reexports.length > 0) {
+        const lastLine = content.length === 0 ? 1 : content.replace(/\n$/, "").split("\n").length;
+        fileOwner = Number(w.insNode.run(fileId, rel, FILE_NODE_KIND, 1, lastLine, 0, content.length, null, null, null, null, null).lastInsertRowid);
+    }
+    for (const r of refs) {
+        const srcId = isOrphan(r) ? fileOwner : nodeIds[r.ownerIndex];
+        w.insEdge.run(srcId, fileId, r.name, r.kind, r.line, r.member, r.spec);
+        stats.edges++;
+    }
+    const sourceType = inferSourceType(rel);
+    for (const c of coverage) {
+        const nodeId = c.ownerIndex !== null ? nodeIds[c.ownerIndex] : null;
+        w.insCoverage.run(c.artifactType, c.name, c.revision, c.kind, rel, c.line, nodeId, sourceType, "comment");
+    }
+    stats.files++;
+    stats.nodes += symbols.length;
+    return { fileId, detachedOwners };
+}
 /**
  * Build or incrementally refresh the index for a project.
  *
@@ -467,7 +740,7 @@ export async function buildIndex(projectPath, onProgressOrOpts) {
     const maxCacheMB = opts.maxCacheMB ?? DEFAULT_MAX_CACHE_MB;
     const retentionDays = opts.retentionDays ?? DEFAULT_RETENTION_DAYS;
     const db = openDb(projectPath);
-    const force = Boolean(opts.force) || needsReindex(db);
+    opts.hooks?.onOpen?.(db);
     const embedder = getEmbedder();
     const stats = {
         files: 0,
@@ -485,61 +758,45 @@ export async function buildIndex(projectPath, onProgressOrOpts) {
         nextStep: "",
     };
     const cfg = loadAffectedConfig(projectPath);
-    const existing = new Map();
-    for (const row of db.prepare("SELECT id, path, hash, mtime_ms, size FROM files").all()) {
-        existing.set(row.path, {
-            id: row.id,
-            hash: row.hash,
-            mtime_ms: row.mtime_ms,
-            size: row.size,
-        });
-    }
-    const prevRoot = db.prepare("SELECT hash FROM dir_hashes WHERE path = ''").get();
     const seen = new Set();
     const fileHashes = new Map();
-    const insFile = db.prepare("INSERT INTO files(path, hash, lang, is_test, module, mtime_ms, size) VALUES (?, ?, ?, ?, ?, ?, ?)");
-    const updFile = db.prepare("UPDATE files SET hash = ?, lang = ?, is_test = ?, module = ?, mtime_ms = ?, size = ? WHERE id = ?");
-    const delNodes = db.prepare("DELETE FROM nodes WHERE file_id = ?");
-    const delEdges = db.prepare("DELETE FROM edges WHERE src_file_id = ?");
-    const delCoverage = db.prepare("DELETE FROM coverage_links WHERE file_path = ?");
-    const insNode = db.prepare(`INSERT INTO nodes(file_id, name, kind, start_line, end_line, start_byte, end_byte, parent_id, signature, body_hash, norm_hash, content_hash)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
-    const insMetrics = db.prepare(`INSERT INTO node_metrics(node_id, loc, max_nesting, branches) VALUES (?, ?, ?, ?)`);
-    const insEdge = db.prepare(`INSERT INTO edges(src_node_id, src_file_id, dst_name, kind, line, is_member, spec) VALUES (?, ?, ?, ?, ?, ?, ?)`);
-    const insCoverage = db.prepare(`INSERT OR REPLACE INTO coverage_links(
-       artifact_type, name, revision, kind, file_path, line, node_id, source_type, origin
-     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`);
-    const insCache = db.prepare(`INSERT INTO embedding_cache(content_hash, model, dim, vec, created_at, last_seen_at)
-     VALUES (?, ?, ?, ?, ?, ?)
-     ON CONFLICT(content_hash, model) DO UPDATE SET last_seen_at = excluded.last_seen_at`);
-    const hasCache = db.prepare(`SELECT 1 AS ok FROM embedding_cache WHERE content_hash = ? AND model = ?`);
-    const insNodeText = db.prepare(`INSERT INTO node_text(node_id, name, subtokens, signature, doc) VALUES (?, ?, ?, ?, ?)
-     ON CONFLICT(node_id) DO UPDATE SET
-       name = excluded.name,
-       subtokens = excluded.subtokens,
-       signature = excluded.signature,
-       doc = excluded.doc`);
+    const w = prepareFileWriter(db, embedder, cfg);
     const allFiles = [...walkFiles(projectPath)];
     // Set inside the transaction; read after it to decide whether the map is written.
     let noop;
-    db.exec("BEGIN");
     try {
-        let done = 0;
-        for (const filePath of allFiles) {
-            const rel = path.relative(projectPath, filePath).split(path.sep).join("/");
-            done++;
-            if (onProgress)
-                onProgress({ file: rel, done, total: allFiles.length });
+        await opts.hooks?.afterWalk?.();
+        // Take the write lock before reading the stored file set: a per-file
+        // reindex committing a new file's row between that read and this run's
+        // insert would otherwise fail the whole run on the unique path. Per-file
+        // runs wait for (or give up on) this lock instead. Inside the try so a
+        // SQLITE_BUSY here still closes the connection.
+        db.exec("BEGIN IMMEDIATE");
+        const force = Boolean(opts.force) || needsReindex(db);
+        const existing = new Map();
+        for (const row of db
+            .prepare("SELECT id, path, hash, mtime_ms, size FROM files")
+            .all()) {
+            existing.set(row.path, {
+                id: row.id,
+                hash: row.hash,
+                mtime_ms: row.mtime_ms,
+                size: row.size,
+            });
+        }
+        const prevRoot = db.prepare("SELECT hash FROM dir_hashes WHERE path = ''").get();
+        // Stat, hash, and (when changed) re-extract one walked file.
+        const visit = async (filePath, rel) => {
             seen.add(rel);
             const lang = langForPath(filePath);
             let stat;
             try {
                 stat = fs.statSync(filePath);
                 if (stat.size > MAX_FILE_BYTES)
-                    continue;
+                    return;
             }
             catch {
-                continue;
+                return;
             }
             const prior = existing.get(rel);
             const mtimeMs = Math.trunc(stat.mtimeMs);
@@ -553,98 +810,60 @@ export async function buildIndex(projectPath, onProgressOrOpts) {
                 fileHashes.set(rel, prior.hash);
                 stats.skippedByStat++;
                 stats.unchanged++;
-                continue;
+                return;
             }
             let content;
             try {
                 content = fs.readFileSync(filePath, "utf8");
             }
             catch {
-                continue;
+                return;
             }
             const hash = hashOf(content);
             fileHashes.set(rel, hash);
             if (!force && prior && prior.hash === hash) {
-                updFile.run(hash, lang.id, isTestPath(rel, cfg.testGlobs) ? 1 : 0, inferModule(rel), mtimeMs, size, prior.id);
+                w.updFile.run(hash, lang.id, isTestPath(rel, cfg.testGlobs) ? 1 : 0, inferModule(rel), mtimeMs, size, prior.id);
                 stats.unchanged++;
-                continue;
-            }
-            let fileId;
-            const isTest = isTestPath(rel, cfg.testGlobs) ? 1 : 0;
-            const mod = inferModule(rel);
-            if (prior) {
-                updFile.run(hash, lang.id, isTest, mod, mtimeMs, size, prior.id);
-                delNodes.run(prior.id);
-                delEdges.run(prior.id);
-                delCoverage.run(rel);
-                fileId = prior.id;
-            }
-            else {
-                fileId = Number(insFile.run(rel, hash, lang.id, isTest, mod, mtimeMs, size).lastInsertRowid);
+                return;
             }
-            const { symbols, refs, coverage, reexports } = await extract(content, lang);
-            const nodeIds = [];
-            const now = Date.now();
-            const touchCache = db.prepare(`UPDATE embedding_cache SET last_seen_at = ? WHERE content_hash = ? AND model = ?`);
-            for (const s of symbols) {
-                const parentId = s.parentIndex !== null ? nodeIds[s.parentIndex] : null;
-                const embedText = defaultEmbedText(s.kind, s.name, s.signature);
-                const ch = contentHashFor({
-                    lang: lang.id,
-                    kind: s.kind,
-                    name: s.name,
-                    signature: s.signature,
-                    embedText,
-                });
-                const id = Number(insNode.run(fileId, s.name, s.kind, s.startLine, s.endLine, s.startByte, s.endByte, parentId, s.signature, s.bodyHash, s.normHash, ch).lastInsertRowid);
-                nodeIds.push(id);
-                insMetrics.run(id, s.loc, s.maxNesting, s.branches);
-                insNodeText.run(id, s.name, s.subtokens, s.signature ?? "", s.docstring);
-                const hit = hasCache.get(ch, embedder.id);
-                if (hit) {
-                    touchCache.run(now, ch, embedder.id);
-                    stats.fromCache++;
-                }
-                else {
-                    const vec = await embedder.embed(embedText);
-                    insCache.run(ch, embedder.id, embedder.dim, toBlob(vec), now, now);
-                    stats.computed++;
-                }
-                stats.embeddings++;
-            }
-            // Covers: req~impact-id-first~1
-            // Imports and calls outside any definition belong to the file: give the
-            // file one hidden owner node so no edge is ever stored ownerless. A file
-            // with no symbols or with re-exports (a barrel: `export * from "./x"`)
-            // gets one too, so an import of it resolves to the file instead of
-            // looking like a package. It gets no text, embedding, or metrics.
-            const isOrphan = (r) => r.kind === "import" || r.ownerIndex === null;
-            let fileOwner = null;
-            if (refs.some(isOrphan) || symbols.length === 0 || reexports.length > 0) {
-                const lastLine = content.length === 0 ? 1 : content.replace(/\n$/, "").split("\n").length;
-                fileOwner = Number(insNode.run(fileId, rel, FILE_NODE_KIND, 1, lastLine, 0, content.length, null, null, null, null, null).lastInsertRowid);
-            }
-            for (const r of refs) {
-                const srcId = isOrphan(r) ? fileOwner : nodeIds[r.ownerIndex];
-                insEdge.run(srcId, fileId, r.name, r.kind, r.line, r.member, r.spec);
-                stats.edges++;
-            }
-            const sourceType = inferSourceType(rel);
-            for (const c of coverage) {
-                const nodeId = c.ownerIndex !== null ? nodeIds[c.ownerIndex] : null;
-                insCoverage.run(c.artifactType, c.name, c.revision, c.kind, rel, c.line, nodeId, sourceType, "comment");
-            }
-            stats.files++;
-            stats.nodes += symbols.length;
+            await writeFileFragment(w, {
+                rel,
+                lang,
+                content,
+                hash,
+                mtimeMs,
+                size,
+                priorId: prior?.id ?? null,
+                stats,
+            });
+        };
+        let done = 0;
+        for (const filePath of allFiles) {
+            const rel = path.relative(projectPath, filePath).split(path.sep).join("/");
+            done++;
+            if (onProgress)
+                onProgress({ file: rel, done, total: allFiles.length });
+            await visit(filePath, rel);
         }
+        const listings = new Map();
         for (const [rel, row] of existing) {
             if (!seen.has(rel)) {
-                db.prepare("DELETE FROM files WHERE id = ?").run(row.id);
-                stats.removed++;
+                // The walk ran before the lock: a per-file reindex may have committed
+                // a row for a file created after the walk passed its directory. Keep
+                // and index a row only when the walk would now yield that exact path;
+                // drop the rest (deleted, ineligible, renamed by case only, or reached
+                // only through a symlink) so no file is held under two paths.
+                const abs = path.join(projectPath, rel);
+                if (!walkWouldYield(projectPath, rel, listings)) {
+                    // Covers: req~edge-ids-survive-reindex~1
+                    removeFileRows(w, row.id, rel);
+                    stats.removed++;
+                    continue;
+                }
+                await visit(abs, rel);
             }
-            else if (!fileHashes.has(rel)) {
+            if (!fileHashes.has(rel))
                 fileHashes.set(rel, row.hash);
-            }
         }
         const dirMap = buildDirHashMap(fileHashes);
         const rootHash = dirMap.get("") ?? "";
@@ -655,7 +874,14 @@ export async function buildIndex(projectPath, onProgressOrOpts) {
         // would write — skip them so a run on every session start stays cheap.
         // `rootUnchanged` already implies no force (explicit or needs_reindex); an
         // explicit prune or cache cap is a maintenance request and runs in full.
-        noop = stats.rootUnchanged && !prune && opts.maxCacheMB === undefined && stats.removed === 0;
+        // A per-file reindex already moved the stored hashes to match the tree but
+        // deferred PageRank and the map to here: its marker disables the fast path.
+        noop =
+            stats.rootUnchanged &&
+                !prune &&
+                opts.maxCacheMB === undefined &&
+                stats.removed === 0 &&
+                !postPending(db);
         if (!noop) {
             const now = Date.now();
             db.prepare("DELETE FROM dir_hashes").run();
@@ -666,6 +892,7 @@ export async function buildIndex(projectPath, onProgressOrOpts) {
             }
             resolveEdges(db);
             recomputeGlobalPagerank(db);
+            clearPostPending(db);
             // Touch last_seen for all live content hashes under active model
             db.prepare(`UPDATE embedding_cache SET last_seen_at = ?
          WHERE model = ?
@@ -688,7 +915,10 @@ export async function buildIndex(projectPath, onProgressOrOpts) {
         db.exec("COMMIT");
     }
     catch (err) {
-        db.exec("ROLLBACK");
+        // SQLite may already have rolled back (or BEGIN never succeeded): an
+        // unguarded ROLLBACK would throw and mask the original error.
+        if (db.isTransaction)
+            db.exec("ROLLBACK");
         throw err;
     }
     finally {
@@ -706,6 +936,202 @@ export async function buildIndex(projectPath, onProgressOrOpts) {
     }
     return stats;
 }
+/**
+ * Re-index exactly the given files in an existing, current index — the
+ * per-edit path behind `speclaw reindex-file`.
+ *
+ * Inside one `BEGIN IMMEDIATE` transaction (so each file is read after the
+ * write lock is held, and the last run to begin saw the last edit), each path
+ * is classified with the full walk's rules ({@link classifyIndexPath}): a
+ * changed file is re-extracted with the same fragment writer as
+ * {@link buildIndex}, a deleted file's rows are dropped, an unchanged file only
+ * refreshes its stat columns, and anything else is skipped. Edges are then
+ * resolved by {@link resolveEdges} scoped to the re-indexed files plus the files
+ * whose edges were detached from them (that scope also re-tries NULL edges that
+ * name a symbol the re-indexed files now define), and the directory hashes of
+ * the touched files' ancestors are recomputed.
+ *
+ * Global post-processing is deferred: no PageRank recomputation (the old rows of
+ * replaced nodes drop by cascade; new symbols have none until the next full
+ * run), no embedding-cache touch or eviction, no `docs/compass.md` write, no
+ * `meta.indexed_at` change, and no Compass call log entry. When it writes any
+ * row it sets `meta.post_pending`, which makes the next full run skip its no-op
+ * fast path and do that work.
+ *
+ * Caveat inherited from scoped resolution: an edge already bound to a node
+ * elsewhere is never re-ranked, so when an edit adds a better candidate for an
+ * ambiguous name the old binding stays until the next full run that re-extracts
+ * the calling file.
+ *
+ * Never creates, migrates, or wipes the database: a missing index or one that
+ * needs a full reindex returns `stale: true` with nothing written.
+ *
+ * @param projectPath - Absolute project root.
+ * @param paths - File paths, absolute or relative to `projectPath`.
+ * @throws When the database stays locked past the busy timeout (`SQLITE_BUSY`) or a write fails; the transaction is rolled back.
+ */
+export async function indexFiles(projectPath, paths) {
+    // Covers: req~reindex-on-edit~1
+    const result = {
+        reindexed: [],
+        removed: [],
+        unchanged: [],
+        skipped: [],
+        stale: false,
+    };
+    const db = openCurrentDb(projectPath);
+    if (!db) {
+        result.stale = true;
+        return result;
+    }
+    try {
+        const embedder = getEmbedder();
+        const w = prepareFileWriter(db, embedder, loadAffectedConfig(projectPath), false);
+        const getFile = db.prepare("SELECT id, hash FROM files WHERE path = ?");
+        const stats = {
+            files: 0,
+            nodes: 0,
+            edges: 0,
+            embeddings: 0,
+            computed: 0,
+            fromCache: 0,
+        };
+        const scope = new Set();
+        const changed = [];
+        const targets = [...new Set(paths.map((p) => path.resolve(projectPath, p)))];
+        db.exec("BEGIN IMMEDIATE");
+        try {
+            // The probe ran before the lock: a full run (or another version) may
+            // have migrated, wiped, or flagged the index since. Re-check under the
+            // lock and leave it to the next full run if so.
+            if (!isCurrentIndex(db)) {
+                db.exec("ROLLBACK");
+                result.stale = true;
+                return result;
+            }
+            for (const abs of targets) {
+                let c = classifyIndexPath(projectPath, abs);
+                // Register only the path a full walk would yield (exact spelling, no
+                // symlink segment); a full run would otherwise drop the row again.
+                if (c.eligible && !walkWouldYield(projectPath, c.rel)) {
+                    c = { eligible: false, rel: c.rel, reason: "ignored" };
+                }
+                if (!c.eligible) {
+                    const row = c.reason === "missing" && c.rel !== null
+                        ? getFile.get(c.rel)
+                        : undefined;
+                    if (row && c.rel !== null) {
+                        // Covers: req~edge-ids-survive-reindex~1
+                        for (const id of removeFileRows(w, row.id, c.rel))
+                            scope.add(id);
+                        result.removed.push(c.rel);
+                        changed.push(c.rel);
+                    }
+                    else {
+                        result.skipped.push({ path: c.rel ?? abs, reason: c.reason });
+                    }
+                    continue;
+                }
+                let content;
+                try {
+                    content = fs.readFileSync(path.join(projectPath, c.rel), "utf8");
+                }
+                catch {
+                    result.skipped.push({ path: c.rel, reason: "missing" });
+                    continue;
+                }
+                const hash = hashOf(content);
+                const prior = getFile.get(c.rel);
+                if (prior && prior.hash === hash) {
+                    w.updFile.run(hash, c.lang.id, isTestPath(c.rel, w.cfg.testGlobs) ? 1 : 0, inferModule(c.rel), c.mtimeMs, c.size, prior.id);
+                    result.unchanged.push(c.rel);
+                    continue;
+                }
+                const written = await writeFileFragment(w, {
+                    rel: c.rel,
+                    lang: c.lang,
+                    content,
+                    hash,
+                    mtimeMs: c.mtimeMs,
+                    size: c.size,
+                    priorId: prior?.id ?? null,
+                    stats,
+                });
+                scope.add(written.fileId);
+                for (const id of written.detachedOwners)
+                    scope.add(id);
+                result.reindexed.push(c.rel);
+                changed.push(c.rel);
+            }
+            if (changed.length > 0) {
+                resolveEdges(db, [...scope]);
+                updateAncestorDirHashes(db, changed);
+                setPostPending(db);
+            }
+            db.exec("COMMIT");
+        }
+        catch (err) {
+            if (db.isTransaction)
+                db.exec("ROLLBACK");
+            throw err;
+        }
+    }
+    finally {
+        db.close();
+    }
+    return result;
+}
+/**
+ * Recompute the `dir_hashes` rows of every ancestor directory of the given
+ * files (deepest first, root last) from the stored `files.hash` values and the
+ * child directory rows, with the same hash rule and `n_files` count as the full
+ * walk ({@link buildDirHashMap}). A directory left with no indexed file loses
+ * its row; the root row always exists.
+ */
+function updateAncestorDirHashes(db, rels) {
+    const dirs = new Set([""]);
+    for (const rel of rels) {
+        const parts = rel.split("/");
+        for (let i = 1; i < parts.length; i++)
+            dirs.add(parts.slice(0, i).join("/"));
+    }
+    const depth = (d) => (d === "" ? 0 : d.split("/").length);
+    const ordered = [...dirs].sort((a, b) => depth(b) - depth(a));
+    const all = db.prepare("SELECT path, hash FROM files");
+    // '/' + 1 is '0': [dir/, dir0) is every path under dir/ in byte order.
+    const under = db.prepare("SELECT path, hash FROM files WHERE path >= ? AND path < ?");
+    const dirRow = db.prepare("SELECT hash FROM dir_hashes WHERE path = ?");
+    const upsert = db.prepare(`INSERT INTO dir_hashes(path, hash, n_files, updated_at) VALUES (?, ?, ?, ?)
+     ON CONFLICT(path) DO UPDATE SET hash = excluded.hash, n_files = excluded.n_files,
+       updated_at = excluded.updated_at`);
+    const del = db.prepare("DELETE FROM dir_hashes WHERE path = ?");
+    const now = Date.now();
+    for (const dir of ordered) {
+        const prefix = dir === "" ? "" : `${dir}/`;
+        const rows = (dir === "" ? all.all() : under.all(prefix, `${dir}0`));
+        if (rows.length === 0 && dir !== "") {
+            del.run(dir);
+            continue;
+        }
+        const children = new Map();
+        for (const r of rows) {
+            const rest = r.path.slice(prefix.length);
+            const slash = rest.indexOf("/");
+            if (slash < 0) {
+                children.set(rest, r.hash);
+            }
+            else {
+                const name = rest.slice(0, slash);
+                if (!children.has(name)) {
+                    const sub = dirRow.get(prefix + name);
+                    children.set(name, sub?.hash ?? HASH_EMPTY);
+                }
+            }
+        }
+        const hash = dirHash([...children].map(([name, h]) => ({ name, hash: h })));
+        upsert.run(dir, hash, rows.length, now);
+    }
+}
 function countTotals(db) {
     const count = (table) => Number(db.prepare(`SELECT COUNT(*) AS n FROM ${table}`).get().n);
     const nodes = Number(db.prepare(`SELECT COUNT(*) AS n FROM nodes WHERE kind <> '${FILE_NODE_KIND}'`).get().n);

package/dist/modules/foundation/assets/docs/compass.template.md

@@ -56,8 +56,12 @@ automatically (a debounced incremental re-index on file change).
 Under Claude Code, a `SessionStart` hook refreshes an existing index when each
 session starts (`speclaw session-start`: silent, never fails, skips
 when `.speclaw/index.db` is absent, and leaves this file alone when nothing
-changed). The first build is always an explicit `compass_index` /
-`speclaw index`.
+changed). A `PostToolUse` hook re-indexes each file the agent writes or edits
+right after the edit (`speclaw reindex-file`: detached, silent, never fails);
+PageRank and this file's map 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, `compass_index`, or `speclaw watch`. The first build is
+always an explicit `compass_index` / `speclaw index`.
 
 If the graph is missing (no `.speclaw/index.db`), run `compass_index` first —
 a missing graph is not license to skip Compass. The only legitimate fallbacks

package/dist/modules/foundation/hooks.js

@@ -27,11 +27,38 @@ const LEGACY_SESSION_START_MARKER = "speclaw index --session-start";
  * Output is discarded because `SessionStart` stdout enters the agent's context,
  * and `|| true` keeps the exit code 0 in every case.
  */
-export const SESSION_START_COMMAND = 'cd "${CLAUDE_PROJECT_DIR:-.}" 2>/dev/null && [ -f .speclaw/index.db ] && { ' +
-    "if [ -x node_modules/.bin/speclaw ]; then node_modules/.bin/speclaw session-start; " +
-    "elif command -v speclaw >/dev/null 2>&1; then speclaw session-start; " +
-    "else npm_config_update_notifier=false npm_config_offline=true npx --no-install @esneiderbravo/speclaw session-start; fi; " +
-    "} >/dev/null 2>&1 || true";
+export const SESSION_START_COMMAND = speclawCommand("session-start");
+/**
+ * Substring every edit-reindex command contains, in each of its resolution
+ * branches. It is the merge identity of the `PostToolUse` reindex hook.
+ */
+export const REINDEX_FILE_MARKER = "speclaw reindex-file";
+/**
+ * The POSIX `sh` command the edit `PostToolUse` hook runs: the session-start
+ * command with `reindex-file` as the subcommand, so it keeps the same index
+ * guard, resolution order, offline npx, discarded output, and exit 0. The hook
+ * payload on stdin passes through `sh` to speclaw unchanged. A speclaw older
+ * than the command rejects it as unknown (exit 1) before touching the index.
+ */
+export const REINDEX_FILE_COMMAND = speclawCommand("reindex-file");
+/** Seconds the edit hook may run; the command returns once it has spawned the work. */
+const REINDEX_TIMEOUT_SECONDS = 10;
+/**
+ * Build a guarded, fail-safe speclaw hook command for one top-level subcommand
+ * (see {@link SESSION_START_COMMAND} for the shape). The only difference
+ * between the hook commands is the subcommand.
+ *
+ * @param sub - The top-level speclaw command the hook runs.
+ * @returns The POSIX `sh` command string.
+ */
+export function speclawCommand(sub) {
+    // Covers: req~edit-reindex-hook~1
+    return ('cd "${CLAUDE_PROJECT_DIR:-.}" 2>/dev/null && [ -f .speclaw/index.db ] && { ' +
+        `if [ -x node_modules/.bin/speclaw ]; then node_modules/.bin/speclaw ${sub}; ` +
+        `elif command -v speclaw >/dev/null 2>&1; then speclaw ${sub}; ` +
+        `else npm_config_update_notifier=false npm_config_offline=true npx --no-install @esneiderbravo/speclaw ${sub}; fi; ` +
+        "} >/dev/null 2>&1 || true");
+}
 /** `SessionStart` matcher covering every session source Claude Code reports. */
 const SESSION_START_MATCHER = "startup|resume|clear|compact";
 /** Seconds the blocking session-start hook may run (index wait plus a real refresh). */
@@ -72,8 +99,8 @@ export const NUDGE_MATCHER = "Read|Grep|Glob";
 /**
  * True when a hook object is one speclaw owns (safe to replace on merge): an
  * `mcp_tool` hook on the `speclaw` server, or a `command` hook whose command
- * contains {@link SESSION_START_MARKER} (or the pre-release
- * `index --session-start` marker). A user `command` hook without the
+ * contains {@link SESSION_START_MARKER}, {@link REINDEX_FILE_MARKER}, or the
+ * pre-release `index --session-start` marker. A user `command` hook without a
  * marker is never speclaw's.
  *
  * @param h - A hook object read from an agent's settings (any shape).
@@ -85,7 +112,9 @@ export function isSpeclawHook(h) {
         return true;
     return (o?.type === "command" &&
         typeof o?.command === "string" &&
-        (o.command.includes(SESSION_START_MARKER) || o.command.includes(LEGACY_SESSION_START_MARKER)));
+        (o.command.includes(SESSION_START_MARKER) ||
+            o.command.includes(REINDEX_FILE_MARKER) ||
+            o.command.includes(LEGACY_SESSION_START_MARKER)));
 }
 /**
  * Compile a law manifest into the hook groups speclaw contributes, one per event
@@ -93,8 +122,10 @@ export function isSpeclawHook(h) {
  * `feedback`, `Stop` for `gate`, and `InstructionsLoaded` whenever any law exists
  * (the context-coverage audit). Two groups are always emitted, even with no
  * laws: one `PostToolUse` group matching `Read|Grep|Glob` for the Compass-first
- * nudge, and one `SessionStart` group whose `command` hook refreshes the index
- * silently when a session starts. A law whose scope contains a malformed glob is
+ * nudge, a separate `PostToolUse` group matching the mutating tools whose
+ * `command` hook re-indexes the edited file in the background, and one
+ * `SessionStart` group whose `command` hook refreshes the index silently when a
+ * session starts. A law whose scope contains a malformed glob is
  * excluded and reported, so a bad pattern fails loudly at generation rather than
  * silently matching nothing at runtime.
  *
@@ -121,6 +152,13 @@ export function compileHooks(manifest) {
     byEvent.PostToolUse = [{ matcher: NUDGE_MATCHER, hooks: [{ ...SPECLAW_HOOK }] }];
     if (hasFeedback)
         byEvent.PostToolUse.unshift({ matcher: MUTATION_MATCHER, hooks: [{ ...SPECLAW_HOOK }] });
+    // Covers: req~edit-reindex-hook~1
+    // Its own group, never folded into the feedback `mcp_tool` group, and only
+    // the keys the agent's hook schema defines (no `async`).
+    byEvent.PostToolUse.push({
+        matcher: MUTATION_MATCHER,
+        hooks: [{ type: "command", command: REINDEX_FILE_COMMAND, timeout: REINDEX_TIMEOUT_SECONDS }],
+    });
     if (hasGate)
         byEvent.Stop = [{ hooks: [{ ...SPECLAW_HOOK }] }];
     if (valid.length > 0)

package/dist/shared/paths.js

@@ -1,4 +1,5 @@
 import { fileURLToPath } from "node:url";
+import fs from "node:fs";
 import path from "node:path";
 /**
  * The `assets/` directory that sits next to a compiled module file. Each module
@@ -8,3 +9,26 @@ import path from "node:path";
 export function assetsDir(importMetaUrl) {
     return path.join(path.dirname(fileURLToPath(importMetaUrl)), "assets");
 }
+/**
+ * `p` with symlinks resolved in its longest existing prefix (a deleted file or
+ * directory keeps its missing tail), so `/var/…` and `/private/var/…` spellings
+ * of one path compare equal even after the file is gone.
+ *
+ * @param p - An absolute path.
+ */
+export function realPathOf(p) {
+    const tail = [];
+    let cur = path.resolve(p);
+    for (;;) {
+        try {
+            return path.join(fs.realpathSync(cur), ...tail.reverse());
+        }
+        catch {
+            const parent = path.dirname(cur);
+            if (parent === cur)
+                return path.resolve(p);
+            tail.push(path.basename(cur));
+            cur = parent;
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esneiderbravo/speclaw",
-  "version": "2.0.10",
+  "version": "2.0.11",
   "publishConfig": {
     "access": "public"
   },