@esneiderbravo/speclaw 2.0.10 → 2.0.12

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/doctor.js

@@ -563,7 +563,7 @@ function specsOrphansCheck(projectPath) {
  * accepting any pending drift — so that is offered only as a last resort.
  */
 export const UNREADABLE_LOCK_REMEDY = "resolve the merge conflict in speclaw.lock or restore it from git " +
-    "(git checkout -- speclaw.lock); upgrade speclaw if the lockfileVersion is newer. " +
+    "(git checkout HEAD -- speclaw.lock); upgrade speclaw if the lockfileVersion is newer. " +
     "Last resort: delete it and run speclaw laws lock — this re-baselines every " +
     "pinned file and accepts any pending drift";
 function integrityChecks(projectPath) {

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/modules/foundation/integrity.js

@@ -23,23 +23,31 @@ export function verifyIntegrity(opts) {
         lock = readLockfile(projectPath);
     }
     catch (err) {
+        // An unreadable lock only blocks the digest/symlink comparison; the scan
+        // never needs the lock, so its findings must still be reported.
+        // Covers: req~injection-scan~1
+        const lockError = err.message;
+        const scanned = doScan ? scanAll(projectPath) : [];
         return {
             ok: false,
             lockPresent: fs.existsSync(lockfilePath(projectPath)),
             rootMatches: false,
-            guidance: err.message,
+            guidance: lockError,
             files: [],
             symlinks: [],
-            findings: [],
+            findings: scanned,
             verifyFindings: [
                 {
                     lawId: "integrity~lockfile~1",
                     severity: "error",
                     engine: "integrity",
                     file: "speclaw.lock",
-                    message: err.message,
+                    message: lockError,
                 },
+                ...scanned.filter((f) => f.severity === "error").map(scanToFinding),
+                ...scanned.filter((f) => f.severity === "warn").map(scanToFinding),
             ],
+            lockError,
         };
     }
     if (!lock && doIntegrity) {

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.12",
   "publishConfig": {
     "access": "public"
   },