@esneiderbravo/speclaw 2.0.20 → 2.0.21

package/dist/cli/commands/ship-on-stop.js

@@ -1,4 +1,4 @@
-import { shipOnStop } from "../../modules/lawbook/ship.js";
+import { measureBranchDiff, shipOnStop } from "../../modules/lawbook/ship.js";
 /**
  * `speclaw ship-on-stop`: the Claude Code `Stop` hook. Ships the branch's
  * change when the work changed since the last ship; prints nothing on stdout.
@@ -28,6 +28,21 @@ export async function runShipOnStop(cwd = process.cwd()) {
         // A hook must never break the session.
     }
 }
+/**
+ * `speclaw measure-diff`: the edit hook's detached background job. Measures the
+ * branch diff's ceremony level into `.speclaw/level-cache.json` so the next
+ * hook call and the stop reuse it. Silent and fail-safe.
+ *
+ * @param cwd - Project root (defaults to the process working directory).
+ */
+export async function runMeasureDiff(cwd = process.cwd()) {
+    try {
+        measureBranchDiff(cwd);
+    }
+    catch {
+        // A background job must never surface anywhere.
+    }
+}
 /** Whether this stop was already blocked by the hook once (`stop_hook_active`). */
 async function stopHookActive() {
     try {

package/dist/cli/index.js

@@ -131,6 +131,8 @@ async function dispatch(cmd, flags) {
             return (await import("./commands/ship.js")).runShip(flags);
         case "ship-on-stop":
             return (await import("./commands/ship-on-stop.js")).runShipOnStop();
+        case "measure-diff":
+            return (await import("./commands/ship-on-stop.js")).runMeasureDiff();
         case "cortex":
             return (await import("./commands/cortex.js")).runCortex(flags);
         case "lawbook":
@@ -177,7 +179,7 @@ async function main() {
     await maybeHeader(cmd, flags);
     await dispatch(cmd, flags);
     // The SessionStart and edit hooks must stay silent: no update notice either.
-    if (cmd === "session-start" || cmd === "reindex-file" || cmd === "ship-on-stop")
+    if (["session-start", "reindex-file", "ship-on-stop", "measure-diff"].includes(cmd ?? ""))
         return;
     await maybeNotifyUpdate(cmd);
 }

package/dist/cli/lib/help.js

@@ -25,6 +25,7 @@ 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)
   ship-on-stop             Ship the branch's change when work changed (Stop hook)
+  measure-diff             Measure the branch diff's level into the cache (edit hook job)
   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
@@ -176,6 +177,16 @@ Keep the Compass index fresh: re-index changed files until interrupted (Ctrl-C).
 The Claude Code Stop hook. On a feature branch whose work changed since the
 last ship, runs \`speclaw ship\` for the change named after the branch. Prints
 nothing on stdout; a failing gate goes to stderr with exit 2 once.
+`,
+    },
+    {
+        name: "measure-diff",
+        usage: `Usage: speclaw measure-diff
+
+Measure the branch diff's ceremony level into .speclaw/level-cache.json. The
+edit hook starts it as a detached background job when the changed files change,
+so the hook never waits on a slow measurement; ship reuses the cached result.
+Silent and fail-safe.
 `,
     },
     {

package/dist/modules/foundation/compass-nudge.js

@@ -55,9 +55,11 @@ export function bashCodeRead(projectPath, command) {
             continue;
         }
         const where = existing.find((a) => isDirectory(projectPath, a) === true || indexedExt(path.extname(a) || "."));
+        // Shell quoting and escapes are not part of the searched text.
+        const pattern = args[0]?.replace(/^[\\'"]+|[\\'"]+$/g, "") || undefined;
         // No path argument: a search of the working directory, i.e. the repo.
         if (where || existing.length === 0)
-            return { tool: "Grep", raw: where ?? ".", pattern: args[0] };
+            return { tool: "Grep", raw: where ?? ".", pattern };
     }
     return null;
 }

package/dist/modules/lawbook/ship.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
 import { createHash } from "node:crypto";
 import { changedFiles, isGitRepo, mergeBase, worktreeChangedFiles } from "../../shared/git.js";
 import { handleHarness, readHarness } from "../cortex/harness.js";
@@ -211,10 +212,70 @@ function isVersionBump(projectPath, base, file) {
  * manifests is not a global change, so it does not raise the level.
  */
 function measureDiff(projectPath, files) {
+    const cached = cachedMeasure(projectPath, files);
+    if (cached)
+        return cached;
     const base = mergeBase(projectPath, "main") ?? mergeBase(projectPath, "master");
     const paths = files.filter((f) => !isVersionBump(projectPath, base, f));
     const { thresholds } = loadCeremonyConfig(projectPath);
-    return proposeLevel(gatherSignals(projectPath, { paths, symbols: [] }, thresholds), thresholds);
+    const proposal = proposeLevel(gatherSignals(projectPath, { paths, symbols: [] }, thresholds), thresholds);
+    try {
+        const file = path.join(projectPath, LEVEL_CACHE);
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify({ key: fileSetKey(files), proposal }) + "\n");
+    }
+    catch {
+        // The cache only saves time; the measurement stands without it.
+    }
+    return proposal;
+}
+/**
+ * The last measurement, kept per changed-file set: measuring a large diff
+ * (blast radius, affected tests) takes seconds, so the edit hook measures in
+ * the background and ship reuses the result at the stop.
+ */
+const LEVEL_CACHE = path.join(".speclaw", "level-cache.json");
+function fileSetKey(files) {
+    return createHash("sha256").update(files.join("\n")).digest("hex");
+}
+/** The cached proposal for exactly this file set, or null. */
+function cachedMeasure(projectPath, files) {
+    try {
+        const c = JSON.parse(fs.readFileSync(path.join(projectPath, LEVEL_CACHE), "utf8"));
+        return c.key === fileSetKey(files) && c.proposal ? c.proposal : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Measure the branch's current diff into the level cache (`speclaw
+ * measure-diff`, the edit hook's detached background job).
+ *
+ * @param projectPath - Project root.
+ */
+export function measureBranchDiff(projectPath) {
+    const files = branchFiles(projectPath);
+    if (files.length)
+        measureDiff(projectPath, files);
+}
+/** The CLI entry beside this module, run by the background measurement. */
+const CLI_ENTRY = fileURLToPath(new URL("../../cli/index.js", import.meta.url));
+/** Start `speclaw measure-diff` in its own process group; never waits, never throws. */
+function measureInBackground(projectPath) {
+    try {
+        const child = spawn(process.execPath, [CLI_ENTRY, "measure-diff"], {
+            cwd: projectPath,
+            detached: true,
+            stdio: "ignore",
+            windowsHide: true,
+        });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        // The stop measures anyway; a lost background job only delays the hint.
+    }
 }
 /**
  * Create the change at the level its diff measures: level 0 gets a record,
@@ -545,16 +606,31 @@ export function docHint(projectPath) {
         catch {
             // First hint on this checkout.
         }
-        if (prev.quick === quick)
+        const save = (next) => {
+            fs.mkdirSync(path.dirname(statePath), { recursive: true });
+            fs.writeFileSync(statePath, JSON.stringify(next) + "\n");
+        };
+        if (prev.quick === quick && !prev.pending)
             return null;
+        // A measurement still running for this same worktree: nothing new to say yet,
+        // and listing the branch's files would cost more git calls than the answer.
+        if (prev.quick === quick && prev.pending && !measuredSince(projectPath, prev.pending.at)) {
+            if (Date.now() - prev.pending.at < MEASURE_GRACE_MS)
+                return null;
+        }
         const files = branchFiles(projectPath);
         const key = `${branch}\n${files.join("\n")}`;
-        const remember = (extra) => {
-            fs.mkdirSync(path.dirname(statePath), { recursive: true });
-            fs.writeFileSync(statePath, JSON.stringify({ ...prev, quick, key, ...extra }) + "\n");
-        };
-        if (files.length === 0 || prev.key === key) {
-            remember({});
+        if (files.length === 0 || (prev.key === key && !prev.pending)) {
+            save({ ...prev, quick, key });
+            return null;
+        }
+        // Measuring a large diff takes seconds — longer than the hook may run —
+        // so it happens in the background and the hint follows on a later call.
+        if (!cachedMeasure(projectPath, files)) {
+            const fresh = prev.pending?.key === key && Date.now() - prev.pending.at < MEASURE_GRACE_MS;
+            if (!fresh)
+                measureInBackground(projectPath);
+            save({ ...prev, quick, pending: fresh ? prev.pending : { key, at: Date.now() } });
             return null;
         }
         const change = branchChange(projectPath, branch);
@@ -570,10 +646,15 @@ export function docHint(projectPath) {
                 scaffoldMeasured(projectPath, change, files, proposal);
         }
         const level = fs.existsSync(changeDir) ? confirmedLevel(projectPath, change) : 0;
-        remember({ change, level });
         const pending = level > 0 ? pendingArtifacts(projectPath, change) : [];
-        if (pending.length === 0 || (prev.change === change && prev.level === level))
+        const told = prev.told?.change === change && prev.told.level === level;
+        if (pending.length === 0 || told) {
+            save({ quick, key, ...(prev.told ? { told: prev.told } : {}) });
             return null;
+        }
+        // "Told" is recorded only with the hint actually returned, so a level is
+        // never marked as told by a call that said nothing.
+        save({ quick, key, told: { change, level } });
         const why = readCeremonyRecord(projectPath, change)?.rationale ?? "";
         return (`speclaw: this change measures level ${level}${why ? ` (${why})` : ""}. ` +
             `In this same turn, before you stop, write briefly and truthfully:\n- ${pending.join("\n- ")}\n` +
@@ -583,6 +664,17 @@ export function docHint(projectPath) {
         return null;
     }
 }
+/** Whether the level cache was written at or after `at` (epoch ms). */
+function measuredSince(projectPath, at) {
+    try {
+        return fs.statSync(path.join(projectPath, LEVEL_CACHE)).mtimeMs >= at;
+    }
+    catch {
+        return false;
+    }
+}
+/** How long a started background measurement is awaited before it is started again. */
+const MEASURE_GRACE_MS = 2 * 60 * 1000;
 /**
  * Change name for a branch: the part after the last `/`, kebab-cased
  * (`fix/compass-query-output` → `compass-query-output`).

package/package.json

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