@esneiderbravo/speclaw 2.0.20 → 2.0.22

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

@@ -8,6 +8,7 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { pkgName, pkgVersion } from "../../shared/version.js";
+import { COMPASS_MAP_END, COMPASS_MAP_START, stripCompassMapBlock, } from "../../shared/compass-map.js";
 export const LOCKFILE_NAME = "speclaw.lock";
 export const LOCKFILE_VERSION = 1;
 /** Delimited provenance block excluded from digests (self-reference). */
@@ -270,23 +271,9 @@ function walkFiles(dir, projectPath, out, pred) {
         }
     }
 }
-/** Markers for the regenerable map block inside `docs/compass.md` (see compass/map.ts). */
-export const COMPASS_MAP_START = "<!-- speclaw:map:start -->";
-export const COMPASS_MAP_END = "<!-- speclaw:map:end -->";
-/**
- * Strip the regenerable map body between markers so integrity digests stay stable
- * across `speclaw index` (which rewrites the map in CI before verify).
- *
- * @param text - Full docs/compass.md contents.
- * @returns The same text with an empty map body, or `text` if markers are missing.
- */
-export function stripCompassMapBlock(text) {
-    const start = text.indexOf(COMPASS_MAP_START);
-    const end = text.indexOf(COMPASS_MAP_END);
-    if (start < 0 || end < 0 || end < start)
-        return text;
-    return text.slice(0, start + COMPASS_MAP_START.length) + "\n" + text.slice(end);
-}
+// The map block helpers moved to shared/ so the lawbook can ignore the
+// regenerated map too; re-exported here for existing importers.
+export { COMPASS_MAP_END, COMPASS_MAP_START, stripCompassMapBlock };
 /**
  * Path-specific bytes that feed {@link digestText}: speclaw-owned coderabbit
  * region, regenerable Compass map body stripped, otherwise the file as-is.

package/dist/modules/lawbook/ship.js

@@ -1,8 +1,10 @@
 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 { COMPASS_DOC, stripCompassMapBlock } from "../../shared/compass-map.js";
 import { handleHarness, readHarness } from "../cortex/harness.js";
 import { deltaSpecFiles, specArchive, specArchivePreconditions } from "./engine.js";
 import { artifactNeeds, confirmedLevel, gatherSignals, loadCeremonyConfig, promoteCeremonyLevel, proposeLevel, readCeremonyRecord, readChangeType, } from "./levels.js";
@@ -88,8 +90,28 @@ function branchFiles(projectPath) {
         ]),
     ]
         .filter((f) => !f.startsWith("lawbook/changes/"))
+        .filter((f) => f !== COMPASS_DOC || !onlyMapChanged(projectPath, base))
         .sort();
 }
+/**
+ * Whether `docs/compass.md` differs from `base` only inside its generated map
+ * block: every full index rewrites that block, so on a fresh branch it would
+ * otherwise read as the agent's work and ship an empty change.
+ */
+function onlyMapChanged(projectPath, base) {
+    if (!base)
+        return false;
+    try {
+        const now = fs.readFileSync(path.join(projectPath, COMPASS_DOC), "utf8");
+        const then = git(projectPath, ["show", `${base}:${COMPASS_DOC}`]);
+        // Line endings are the platform's (core.autocrlf), not the agent's work.
+        const lf = (t) => stripCompassMapBlock(t.replace(/\r\n/g, "\n"));
+        return then !== "" && lf(now) === lf(then);
+    }
+    catch {
+        return false;
+    }
+}
 /** New files not yet added, outside ship's own output (`lawbook/changes/`, `.speclaw/`). */
 function untrackedFiles(projectPath) {
     return git(projectPath, [
@@ -211,10 +233,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 +627,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 +667,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 +685,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`).
@@ -656,12 +769,18 @@ function workFingerprint(projectPath) {
         ":(exclude).speclaw",
     ]).split("\n");
     const hash = createHash("sha256");
-    for (const f of [...new Set([...tracked, ...untrackedFiles(projectPath)])].sort()) {
+    const files = [...new Set([...tracked, ...untrackedFiles(projectPath)])]
+        // A map-only docs/compass.md is no work: neither its bytes nor its name count.
+        .filter((f) => f !== COMPASS_DOC || !onlyMapChanged(projectPath, base))
+        .sort();
+    for (const f of files) {
         if (!f)
             continue;
         hash.update(`${f}\n`);
         try {
-            hash.update(fs.readFileSync(path.join(projectPath, f)));
+            const bytes = fs.readFileSync(path.join(projectPath, f));
+            // A re-index rewrites the map block; only the rest of the file is work.
+            hash.update(f === COMPASS_DOC ? stripCompassMapBlock(bytes.toString("utf8")) : bytes);
         }
         catch {
             // Deleted, vanished or unreadable: its name stands in.

package/dist/shared/compass-map.js

@@ -0,0 +1,20 @@
+/** Markers for the regenerable map block inside `docs/compass.md` (see compass/map.ts). */
+export const COMPASS_MAP_START = "<!-- speclaw:map:start -->";
+export const COMPASS_MAP_END = "<!-- speclaw:map:end -->";
+/** The project-relative path of the Compass guide that carries the generated map. */
+export const COMPASS_DOC = "docs/compass.md";
+/**
+ * Strip the regenerable map body between markers. `speclaw index` rewrites it on
+ * every full run, so integrity digests and "did the agent change this file?"
+ * checks must both ignore it.
+ *
+ * @param text - Full docs/compass.md contents.
+ * @returns The same text with an empty map body, or `text` if markers are missing.
+ */
+export function stripCompassMapBlock(text) {
+    const start = text.indexOf(COMPASS_MAP_START);
+    const end = text.indexOf(COMPASS_MAP_END);
+    if (start < 0 || end < 0 || end < start)
+        return text;
+    return text.slice(0, start + COMPASS_MAP_START.length) + "\n" + text.slice(end);
+}

package/package.json

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