@esneiderbravo/speclaw 2.0.6 → 2.0.8

package/README.md

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

@@ -41,6 +41,10 @@ export async function runCortex(flags) {
             note: typeof flags.note === "string" ? flags.note : undefined,
         });
         printHarnessWarnings(result);
+        // The human line goes to stderr so stdout stays one JSON document.
+        if (op === "status" && !flags.json && "summary" in result && result.summary) {
+            process.stderr.write(`  ${result.summary.line}\n`);
+        }
         console.log(JSON.stringify(result, null, 2));
     }
     catch (err) {

package/dist/cli/commands/index-build.js

@@ -2,9 +2,27 @@ import { buildIndex } from "../../modules/compass/indexer.js";
 import { startWatch } from "../../modules/compass/watcher.js";
 import { recordCompassCall } from "../../shared/compass-calls.js";
 import { ui, renderProgress, clearProgress } from "../lib/ui.js";
+/** Usage text for `speclaw index --help`. */
+export const INDEX_HELP = `Usage: speclaw index [options]
+
+(Re)build the local Compass code graph for the current directory. Runs are
+incremental: unchanged files are skipped, and an unchanged project skips the
+global post-processing.
+
+Options
+  --force              Re-extract every file
+  --prune              Also evict embedding-cache rows unused for --retention days
+  --retention <days>   Retention window for --prune (default 30)
+  --max-cache-mb <mb>  Embedding-cache size cap (default 256)
+  --json               Print the index statistics as JSON
+`;
 /** (Re)build the Compass code graph for the cwd, showing progress and final stats. */
 export async function runIndex(flags) {
     const cwd = process.cwd();
+    if (flags.help || flags.h) {
+        process.stdout.write(INDEX_HELP);
+        return;
+    }
     recordCompassCall(cwd, "compass_index");
     const json = Boolean(flags.json);
     if (!json)

package/dist/cli/commands/session-start.js

@@ -0,0 +1,29 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * `speclaw session-start`: refresh an existing Compass index incrementally,
+ * print nothing, and never fail. It is a top-level command rather than an
+ * `index` flag so an older speclaw that resolves first rejects it as unknown
+ * before indexing anything. With no `.speclaw/index.db` it returns at once,
+ * before `node:sqlite` is even loaded — the first build stays an explicit
+ * `speclaw index` / `compass_index`. It is not logged as a Compass call: the
+ * hook would otherwise append an entry per session and rotate real evidence out.
+ *
+ * @param cwd - Project root (defaults to the process working directory).
+ */
+// Covers: req~session-start-index~1
+export async function runSessionStart(cwd = process.cwd()) {
+    try {
+        if (!fs.existsSync(path.join(cwd, ".speclaw", "index.db")))
+            return;
+        // Node lines that still flag `node:sqlite` as experimental would print an
+        // ExperimentalWarning to stderr; this command must print nothing.
+        process.removeAllListeners("warning");
+        const { buildIndex } = await import("../../modules/compass/indexer.js");
+        await buildIndex(cwd, {});
+    }
+    catch {
+        // A concurrent writer (SQLITE_BUSY after busy_timeout) or any other failure
+        // must never fail or print into a starting session.
+    }
+}

package/dist/cli/index.js

@@ -19,6 +19,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)
   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
@@ -99,7 +100,7 @@ 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.
+ * header. `session-start` is not header-eligible: it must print nothing.
  */
 function maybeHeader(cmd, flags) {
     if (!process.stdout.isTTY && process.env.FORCE_COLOR !== "1")
@@ -156,6 +157,8 @@ async function dispatch(cmd, flags) {
             return (await import("./commands/index-build.js")).runIndex(flags);
         case "watch":
             return (await import("./commands/index-build.js")).runWatch(flags);
+        case "session-start":
+            return (await import("./commands/session-start.js")).runSessionStart();
         case "explore":
         case "search":
         case "recall":
@@ -204,6 +207,9 @@ 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")
+        return;
     await maybeNotifyUpdate(cmd);
 }
 main().catch((err) => {

package/dist/modules/compass/db.js

@@ -19,6 +19,8 @@ CREATE TABLE IF NOT EXISTS files (
 );
 CREATE INDEX IF NOT EXISTS idx_files_is_test ON files(is_test);
 -- nodes: the definitions in the codebase (functions, classes, methods, types).
+-- start_byte/end_byte are UTF-16 code-unit offsets into the decoded source
+-- (tree-sitter's startIndex/endIndex), not UTF-8 byte offsets, despite the names.
 CREATE TABLE IF NOT EXISTS nodes (
   id INTEGER PRIMARY KEY,
   file_id INTEGER NOT NULL REFERENCES files(id) ON DELETE CASCADE,

package/dist/modules/compass/hash.js

@@ -36,9 +36,9 @@ function digest(parts) {
 /**
  * Hash of the exact source bytes for a symbol range (detects cosmetic edits).
  *
- * @param source - Full file source as UTF-8 string.
- * @param startByte - Inclusive start offset.
- * @param endByte - Exclusive end offset.
+ * @param source - Full file source, decoded from UTF-8.
+ * @param startByte - Inclusive start offset: a UTF-16 code-unit index into `source`, despite the name.
+ * @param endByte - Exclusive end offset: a UTF-16 code-unit index into `source`, despite the name.
  */
 export function rawHash(source, startByte, endByte) {
     return createHash("sha256").update(source.slice(startByte, endByte)).digest("hex").slice(0, 32);

package/dist/modules/compass/indexer.js

@@ -186,6 +186,13 @@ function* walkFiles(root) {
  * and an embedding cache keyed by embedder-input hash so renames/moves do not
  * recompute vectors. The whole run executes in a single transaction.
  *
+ * A run without force, prune, or an explicit `maxCacheMB` that re-extracts and
+ * removes nothing and finds the root hash unchanged is a no-op: it skips the
+ * dir-hash rewrite, edge/import resolution, PageRank, and the embedding-cache
+ * touch and eviction, writes only `meta.indexed_at`, and rewrites
+ * `docs/compass.md` only when its map block is empty. It still returns full
+ * statistics (`totals`, `nextStep`).
+ *
  * @param projectPath - Absolute path to the project root.
  * @param onProgressOrOpts - Progress callback (legacy) or {@link BuildIndexOptions}.
  */
@@ -251,6 +258,8 @@ export async function buildIndex(projectPath, onProgressOrOpts) {
        signature = excluded.signature,
        doc = excluded.doc`);
     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;
@@ -369,37 +378,49 @@ export async function buildIndex(projectPath, onProgressOrOpts) {
         const dirMap = buildDirHashMap(fileHashes);
         const rootHash = dirMap.get("") ?? "";
         stats.rootUnchanged = Boolean(prevRoot && prevRoot.hash === rootHash && !force && stats.files === 0);
-        const now = Date.now();
-        db.prepare("DELETE FROM dir_hashes").run();
-        const insDir = db.prepare("INSERT INTO dir_hashes(path, hash, n_files, updated_at) VALUES (?, ?, ?, ?)");
-        for (const [dir, hash] of dirMap) {
-            const nFiles = [...fileHashes.keys()].filter((f) => dir === "" ? true : f === dir || f.startsWith(dir + "/")).length;
-            insDir.run(dir, hash, nFiles, now);
-        }
-        db.exec(`
-      UPDATE edges SET dst_node_id = (
-        SELECT n.id FROM nodes n
-        WHERE n.name = edges.dst_name
-        ORDER BY CASE WHEN n.file_id = edges.src_file_id THEN 0 ELSE 1 END, n.id
-        LIMIT 1
-      )
-      WHERE kind = 'call' AND dst_node_id IS NULL
-    `);
-        resolveImportEdges(db, projectPath);
-        recomputeGlobalPagerank(db);
-        // Touch last_seen for all live content hashes under active model
-        db.prepare(`UPDATE embedding_cache SET last_seen_at = ?
-       WHERE model = ?
-         AND content_hash IN (SELECT content_hash FROM nodes WHERE content_hash IS NOT NULL)`).run(now, embedder.id);
-        if (prune) {
-            const cutoff = now - retentionDays * 24 * 60 * 60 * 1000;
-            db.prepare(`DELETE FROM embedding_cache
-         WHERE last_seen_at < ?
-           AND content_hash NOT IN (SELECT content_hash FROM nodes WHERE content_hash IS NOT NULL)`).run(cutoff);
+        // Covers: req~index-noop-fast-path~1
+        // No-op fast path: nothing re-extracted or removed and the same root means
+        // dir hashes, edges, PageRank, and the cache are already what a full pass
+        // 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;
+        if (!noop) {
+            const now = Date.now();
+            db.prepare("DELETE FROM dir_hashes").run();
+            const insDir = db.prepare("INSERT INTO dir_hashes(path, hash, n_files, updated_at) VALUES (?, ?, ?, ?)");
+            for (const [dir, hash] of dirMap) {
+                const nFiles = [...fileHashes.keys()].filter((f) => dir === "" ? true : f === dir || f.startsWith(dir + "/")).length;
+                insDir.run(dir, hash, nFiles, now);
+            }
+            db.exec(`
+        UPDATE edges SET dst_node_id = (
+          SELECT n.id FROM nodes n
+          WHERE n.name = edges.dst_name
+          ORDER BY CASE WHEN n.file_id = edges.src_file_id THEN 0 ELSE 1 END, n.id
+          LIMIT 1
+        )
+        WHERE kind = 'call' AND dst_node_id IS NULL
+      `);
+            resolveImportEdges(db, projectPath);
+            recomputeGlobalPagerank(db);
+            // Touch last_seen for all live content hashes under active model
+            db.prepare(`UPDATE embedding_cache SET last_seen_at = ?
+         WHERE model = ?
+           AND content_hash IN (SELECT content_hash FROM nodes WHERE content_hash IS NOT NULL)`).run(now, embedder.id);
+            if (prune) {
+                const cutoff = now - retentionDays * 24 * 60 * 60 * 1000;
+                db.prepare(`DELETE FROM embedding_cache
+           WHERE last_seen_at < ?
+             AND content_hash NOT IN (SELECT content_hash FROM nodes WHERE content_hash IS NOT NULL)`).run(cutoff);
+            }
+            evictCacheBySize(db, maxCacheMB);
         }
-        evictCacheBySize(db, maxCacheMB);
+        // Written on every run, no-op included, so doctor's freshness check sees a
+        // verified-current index as fresh.
         db.prepare("INSERT INTO meta(key, value) VALUES ('indexed_at', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run(new Date().toISOString());
-        clearNeedsReindex(db);
+        if (!noop)
+            clearNeedsReindex(db);
         stats.totals = countTotals(db);
         stats.nextStep = indexNextStep(stats.totals);
         db.exec("COMMIT");
@@ -412,8 +433,11 @@ export async function buildIndex(projectPath, onProgressOrOpts) {
         db.close();
     }
     try {
-        const { writeCompactMap } = await import("./map.js");
-        writeCompactMap(projectPath);
+        const { writeCompactMap, compactMapPending } = await import("./map.js");
+        // A no-op run leaves the tracked docs/compass.md alone (no working-tree
+        // churn) unless its map block is still empty.
+        if (!noop || compactMapPending(projectPath))
+            writeCompactMap(projectPath);
     }
     catch {
         // Map generation must never fail an index run.

package/dist/modules/compass/map.js

@@ -82,6 +82,30 @@ export function generateCompactMap(projectPath) {
         db.close();
     }
 }
+/**
+ * True when `docs/compass.md` holds both map markers with nothing but
+ * whitespace between them — a freshly scaffolded or reset map block that a
+ * no-op index run must still fill. False when the file or a marker is missing
+ * (there is nothing a map write could fill) or the block already has a map.
+ *
+ * @param projectPath - Project root.
+ * @returns Whether the compact map block is present but empty.
+ */
+export function compactMapPending(projectPath) {
+    const compassPath = path.join(projectPath, "docs", "compass.md");
+    let text;
+    try {
+        text = fs.readFileSync(compassPath, "utf8");
+    }
+    catch {
+        return false;
+    }
+    const start = text.indexOf(MAP_START);
+    const end = text.indexOf(MAP_END);
+    if (start < 0 || end < 0 || end < start)
+        return false;
+    return text.slice(start + MAP_START.length, end).trim() === "";
+}
 /**
  * Replace content between map markers in `docs/compass.md`. Preserves content
  * outside markers. Does nothing (with reason) when markers are missing or the

package/dist/modules/compass/query.js

@@ -43,10 +43,25 @@ export function search(projectPath, query, limit = 25) {
         db.close();
     }
 }
-function readSource(projectPath, file, startByte, endByte) {
+/**
+ * Read a symbol's source text from disk.
+ *
+ * @remarks The offsets are UTF-16 code-unit indices into the decoded file text
+ * (tree-sitter parses the `utf8`-decoded string), not byte offsets — so the file
+ * is decoded before slicing. A byte slice drifts on any preceding non-ASCII text.
+ *
+ * @param projectPath - Absolute project root.
+ * @param file - Repo-relative file path.
+ * @param startIndex - Inclusive start offset (`nodes.start_byte`).
+ * @param endIndex - Exclusive end offset (`nodes.end_byte`).
+ * @returns The symbol's source, or `""` when the file cannot be read.
+ *
+ * // Covers: req~explore-exact-source~1
+ */
+function readSource(projectPath, file, startIndex, endIndex) {
     try {
-        const buf = fs.readFileSync(path.join(projectPath, file));
-        return buf.subarray(startByte, endByte).toString("utf8");
+        const text = fs.readFileSync(path.join(projectPath, file), "utf8");
+        return text.slice(startIndex, endIndex);
     }
     catch {
         return "";

package/dist/modules/cortex/harness.js

@@ -11,6 +11,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { GATED_STAGES, compassGateError, compassGateWarning, evaluateCompassGate, readCompassGateMode, } from "./compass-gate.js";
+import { buildStatusSummary } from "./status.js";
 // Harness types live in the leaf `types.ts` so `compass-gate.ts` can use them
 // without importing this file back (no file-level import cycle).
 export { HARNESS_STAGES, } from "./types.js";
@@ -112,7 +113,8 @@ function allowedAdvance(from, level, verdict) {
     }
 }
 /**
- * Dispatch a harness op for a change.
+ * Dispatch a harness op for a change. `status` also returns the status
+ * summary (`req~cortex-status-summary~1`); other ops return the state.
  *
  * // Covers: req~harness-state~1
  */
@@ -120,7 +122,8 @@ export function handleHarness(args) {
     const { projectPath, change, harnessOp } = args;
     requireChangeDir(projectPath, change);
     if (harnessOp === "status") {
-        return { state: readHarness(projectPath, change) };
+        const state = readHarness(projectPath, change);
+        return { summary: state ? buildStatusSummary(projectPath, state) : null, state };
     }
     if (harnessOp === "start") {
         const existing = readHarness(projectPath, change);

package/dist/modules/cortex/register.js

@@ -8,6 +8,7 @@ import { defineTool, text } from "../../shared/mcp.js";
 import { shouldExpose } from "../../shared/exposure.js";
 import { handleHarness, harnessOps, readHarness, } from "./harness.js";
 import { briefForStage } from "./brief.js";
+import { fitStatusResult } from "./status.js";
 export const cortexActions = [...harnessOps, "brief"];
 /**
  * Register the canonical `cortex` MCP tool.
@@ -22,7 +23,7 @@ export function registerCortex(server, opts = {}) {
             return;
         defineTool(server, { name, description, inputSchema, handler });
     };
-    add("cortex", "Cortex multi-agent loop: status, start, advance, rework, brief for a change.", {
+    add("cortex", "Cortex multi-agent loop: status with summary, start, advance, rework, brief for a change.", {
         projectPath: z.string(),
         change: z.string(),
         action: z.enum(cortexActions),
@@ -36,7 +37,7 @@ export function registerCortex(server, opts = {}) {
             const brief = briefForStage(state?.stage ?? null);
             return text(JSON.stringify({ state, ...brief }, null, 2));
         }
-        return text(handleHarness({
+        const result = handleHarness({
             projectPath,
             change,
             harnessOp: action,
@@ -44,6 +45,8 @@ export function registerCortex(server, opts = {}) {
             verdict: verdict ?? null,
             openQuestions,
             pauseForQuestions,
-        }));
+        });
+        // `text()` cuts from the end; fit `status` so `summary` and valid JSON survive.
+        return text(action === "status" && "summary" in result ? fitStatusResult(result) : result);
     });
 }

package/dist/modules/cortex/status.js

@@ -0,0 +1,197 @@
+/**
+ * Per-change status summary for Cortex `status`: stage, active role, time in
+ * stage, task progress, rework, pending verdicts, and the configured interval
+ * at which the coordinator posts status updates.
+ *
+ * Cortex must not import from the lawbook module, so task checkboxes and the
+ * `cortex.statusIntervalMinutes` key are read with local text scans, like
+ * `readCompassGateMode`.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { briefForStage } from "./brief.js";
+import { stageStartedAt } from "./compass-gate.js";
+import { OUTPUT_BUDGET, estimateTokens } from "../../shared/output-budget.js";
+/** Interval used when the key is missing or invalid. */
+export const DEFAULT_STATUS_INTERVAL_MINUTES = 5;
+/**
+ * Largest interval reported. A session timer is a cron expression, and
+ * an every-N-minutes step only exists for N ≤ 59; 60 is the hourly ping.
+ */
+export const MAX_STATUS_INTERVAL_MINUTES = 60;
+const CHECKBOX = /^\s*[-*]\s+\[( |x|X)\]/;
+/**
+ * Count Markdown task-list items (`- [ ]`, `- [x]`, `* [X]`). Brackets outside
+ * a list item are ignored. This is a line scan, not a Markdown parser: items
+ * inside fenced code blocks are counted, and `+` bullets and numbered
+ * (`1. [ ]`) items are not.
+ *
+ * @param text - Markdown source.
+ * @returns Checked and total item counts.
+ */
+export function countTaskCheckboxes(text) {
+    let done = 0;
+    let total = 0;
+    for (const lineText of text.split(/\r?\n/)) {
+        const m = CHECKBOX.exec(lineText);
+        if (!m)
+            continue;
+        total++;
+        if (m[1] !== " ")
+            done++;
+    }
+    return { done, total };
+}
+/**
+ * Read `statusIntervalMinutes` from the top-level `cortex:` block of
+ * `lawbook/config.yaml`. Quotes and a trailing comment are allowed. A missing
+ * file, block, or key, or any value that is not a whole number ≥ 0, yields 5.
+ * Values above 60 are clamped to 60. Never throws.
+ *
+ * This is a line scan, not a YAML parser: the key is accepted at any
+ * indentation under `cortex:` (nested maps included), and flow style
+ * (`cortex: {statusIntervalMinutes: 3}`) is not read, so it yields 5.
+ *
+ * @param projectPath - Project root.
+ *
+ * // Covers: req~cortex-status-interval~1
+ */
+export function readStatusIntervalMinutes(projectPath) {
+    let raw;
+    try {
+        raw = fs.readFileSync(path.join(projectPath, "lawbook", "config.yaml"), "utf8");
+    }
+    catch {
+        return DEFAULT_STATUS_INTERVAL_MINUTES;
+    }
+    const lines = raw.split(/\r?\n/);
+    const start = lines.findIndex((l) => /^cortex:[ \t]*(?:#.*)?$/.test(l));
+    if (start < 0)
+        return DEFAULT_STATUS_INTERVAL_MINUTES;
+    for (let i = start + 1; i < lines.length; i++) {
+        const l = lines[i];
+        // The block ends at the next column-0 key; blank and comment lines are skipped.
+        if (/^\S/.test(l) && !l.startsWith("#"))
+            break;
+        const m = /^\s+statusIntervalMinutes:\s*(\S+)/.exec(l);
+        if (!m)
+            continue;
+        const value = m[1].replace(/#.*$/, "").replace(/^(["'])(.*)\1$/, "$2");
+        if (!/^\d+$/.test(value))
+            return DEFAULT_STATUS_INTERVAL_MINUTES;
+        return Math.min(Number(value), MAX_STATUS_INTERVAL_MINUTES);
+    }
+    return DEFAULT_STATUS_INTERVAL_MINUTES;
+}
+function readTaskCounts(projectPath, change) {
+    const dir = path.join(projectPath, "lawbook", "changes", change);
+    for (const file of ["tasks.md", "record.md"]) {
+        let text;
+        try {
+            text = fs.readFileSync(path.join(dir, file), "utf8");
+        }
+        catch {
+            continue;
+        }
+        return countTaskCheckboxes(text);
+    }
+    return null;
+}
+function elapsedSince(startedAt, now) {
+    if (!startedAt)
+        return null;
+    const t = Date.parse(startedAt);
+    if (Number.isNaN(t))
+        return null;
+    return Math.max(0, Math.floor((now.getTime() - t) / 60000));
+}
+/**
+ * Build the status summary of a running change from its harness state, its
+ * task list, and the configured status interval.
+ *
+ * @param projectPath - Project root.
+ * @param state - Harness state of the change.
+ * @param now - Clock for `elapsedMinutes`; injectable for tests.
+ * @returns The structured summary and its one-line English rendering.
+ *
+ * // Covers: req~cortex-status-summary~1
+ */
+export function buildStatusSummary(projectPath, state, now = new Date()) {
+    const role = briefForStage(state.stage).role;
+    const startedAt = stageStartedAt(state);
+    const elapsedMinutes = elapsedSince(startedAt, now);
+    const tasks = readTaskCounts(projectPath, state.change);
+    const pendingVerdicts = [];
+    if (state.level >= 1 && state.verdicts.review !== "PASS")
+        pendingVerdicts.push("review");
+    if (state.verdicts.test !== "PASS")
+        pendingVerdicts.push("test");
+    const openQuestions = state.openQuestions.length;
+    const parts = [
+        state.change,
+        role ? `${state.stage} (${role})` : state.stage,
+        elapsedMinutes === null ? "elapsed n/a" : `${elapsedMinutes}m in stage`,
+        tasks ? `tasks ${tasks.done}/${tasks.total}` : "tasks n/a",
+        `rework ${state.iteration}/${state.maxRework}`,
+        `pending: ${pendingVerdicts.length ? pendingVerdicts.join(", ") : "none"}`,
+    ];
+    if (state.stage === "questions") {
+        parts.push(`waiting on human: ${openQuestions} question(s)`);
+    }
+    return {
+        change: state.change,
+        stage: state.stage,
+        role,
+        stageStartedAt: startedAt,
+        elapsedMinutes,
+        tasks,
+        iteration: state.iteration,
+        maxRework: state.maxRework,
+        pendingVerdicts,
+        openQuestions,
+        statusIntervalMinutes: readStatusIntervalMinutes(projectPath),
+        line: parts.join(" · "),
+    };
+}
+/**
+ * Fit a `status` result into the brief MCP output budget without ever cutting
+ * `summary`. `text()` truncates a payload from the end, which would yield
+ * invalid JSON and lose whatever comes last; this keeps the payload under the
+ * budget instead, by dropping the oldest `state.history` entries (newest
+ * kept) and recording how many were dropped in `historyOmitted`. If an empty
+ * history still does not fit, `state` becomes `null` with `stateOmitted`.
+ * Only the MCP rendering is trimmed: `harness.json` and the CLI keep the full
+ * history.
+ *
+ * @param result - The `handleHarness` `status` result.
+ * @param maxTokens - Token ceiling; defaults to the brief output budget.
+ * @returns A result whose pretty-printed JSON fits `maxTokens`.
+ *
+ * // Covers: req~cortex-status-summary~1
+ */
+export function fitStatusResult(result, maxTokens = OUTPUT_BUDGET.brief) {
+    const fits = (value) => estimateTokens(JSON.stringify(value, null, 2)) <= maxTokens;
+    const { summary, state } = result;
+    const full = { summary, state };
+    if (!state || fits(full))
+        return full;
+    const history = state.history;
+    const keepLast = (k) => ({
+        summary,
+        historyOmitted: history.length - k,
+        state: { ...state, history: k > 0 ? history.slice(-k) : [] },
+    });
+    // Fitting is monotone in the number of kept entries: binary-search the most.
+    let lo = 0;
+    let hi = history.length - 1;
+    if (!fits(keepLast(0)))
+        return { summary, stateOmitted: true, state: null };
+    while (lo < hi) {
+        const mid = Math.ceil((lo + hi) / 2);
+        if (fits(keepLast(mid)))
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return keepLast(lo);
+}

package/dist/modules/foundation/assets/AGENTS.template.md

@@ -20,7 +20,8 @@ Claude-specific notes: [`CLAUDE.md`](CLAUDE.md). The law: [`LAWS.md`](LAWS.md).
    `compass_explore` **before** any grep/sed/cat/Read,
    including files you already know by name. Fall back to manual file tools only
    after Compass returns nothing useful, the graph is missing (`compass_index`
-   first), or the target isn't indexed code (stylesheets, config, logs). Cheat
+   first; Claude Code sessions refresh an existing index at start), or the
+   target isn't indexed code (stylesheets, config, logs). Cheat
    sheet: [`docs/compass.md`](docs/compass.md).
 3. **Follow Cortex** (*One brain. Many agents.*) for every non-trivial change;
    archive within the same PR. The primary agent is the **coordinator**

package/dist/modules/foundation/assets/CLAUDE.template.md

@@ -35,7 +35,8 @@ where it lives, how a value flows — call Compass **first**: `compass_find` to
 locate, `compass_explore` to read a symbol with its callers and callees (include
 `blast_radius` for what could break, `to` for a call path), and
 `compass_diff_context` for the context of a diff.
-Run `compass_index` first if the graph is missing.
+Run `compass_index` first if the graph is missing. Under Claude Code a
+`SessionStart` hook refreshes an existing index when each session starts.
 
 This includes files you already know the name of: to learn what `Foo` imports,
 uses, or depends on, run `compass_explore Foo` — do **not** `cat`/`sed`/`grep`/

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

@@ -37,6 +37,12 @@ a request, not whole files.
 `compass_index` also takes `action: start|stop|status` to keep the index fresh
 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`.
+
 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
 to Grep/Read: a Compass call returned nothing useful for your query, or the

package/dist/modules/foundation/hooks.js

@@ -3,6 +3,39 @@ import path from "node:path";
 import { agentById } from "../../shared/agents.js";
 import { sha256 } from "../../shared/install.js";
 import { globError, hasBackend } from "./laws.js";
+/**
+ * Substring every speclaw session-start command contains, in each of its
+ * resolution branches. It is the merge identity of the `SessionStart` hook.
+ */
+export const SESSION_START_MARKER = "speclaw session-start";
+/**
+ * The marker of the unreleased `index --session-start` hook shape that
+ * pre-release 2.0.7 builds wrote. Still recognized so a merge replaces such an
+ * entry instead of keeping it next to the current one.
+ */
+const LEGACY_SESSION_START_MARKER = "speclaw index --session-start";
+/**
+ * The POSIX `sh` command the `SessionStart` hook runs. The `index.db` guard runs
+ * in the shell, so a project without an index pays no Node start-up. It invokes
+ * the top-level `session-start` command, which a speclaw older than 2.0.7
+ * rejects as unknown (exit 1) before indexing, logging, or notifying, so a stale
+ * binary first in the resolution order does nothing. speclaw resolves as local
+ * `node_modules/.bin`, then `PATH`, then `npx --no-install` with
+ * `npm_config_offline=true` and `npm_config_update_notifier=false`, so npx
+ * neither installs nor contacts the registry (offline alone still lets npm's
+ * own update notifier query it).
+ * 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";
+/** `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). */
+const SESSION_START_TIMEOUT = 30;
 /** Claude Code `${path}` templates — see https://code.claude.com/docs/en/hooks */
 const SPECLAW_HOOK_INPUT = {
     projectPath: "${cwd}",
@@ -36,17 +69,32 @@ const MUTATION_MATCHER = "Write|Edit|MultiEdit|NotebookEdit";
  * and the event cannot gate the tool; a `PreToolUse` "allow" would auto-approve.
  */
 export const NUDGE_MATCHER = "Read|Grep|Glob";
-/** True when a hook object is one speclaw owns (safe to replace on merge). */
-function isSpeclawHook(h) {
+/**
+ * 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
+ * marker is never speclaw's.
+ *
+ * @param h - A hook object read from an agent's settings (any shape).
+ * @returns Whether speclaw owns the hook.
+ */
+export function isSpeclawHook(h) {
     const o = h;
-    return o?.type === "mcp_tool" && o?.server === "speclaw";
+    if (o?.type === "mcp_tool" && o?.server === "speclaw")
+        return true;
+    return (o?.type === "command" &&
+        typeof o?.command === "string" &&
+        (o.command.includes(SESSION_START_MARKER) || o.command.includes(LEGACY_SESSION_START_MARKER)));
 }
 /**
  * Compile a law manifest into the hook groups speclaw contributes, one per event
  * the laws demand: `PreToolUse` when any `bloqueo` law exists, `PostToolUse` for
  * `feedback`, `Stop` for `gate`, and `InstructionsLoaded` whenever any law exists
- * (the context-coverage audit). One `PostToolUse` group matching `Read|Grep|Glob`
- * is always emitted for the Compass-first nudge, even with no laws. A law whose scope contains a malformed glob is
+ * (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
  * excluded and reported, so a bad pattern fails loudly at generation rather than
  * silently matching nothing at runtime.
  *
@@ -77,13 +125,20 @@ export function compileHooks(manifest) {
         byEvent.Stop = [{ hooks: [{ ...SPECLAW_HOOK }] }];
     if (valid.length > 0)
         byEvent.InstructionsLoaded = [{ hooks: [{ ...SPECLAW_HOOK }] }];
+    // Covers: req~session-start-hook~1
+    byEvent.SessionStart = [
+        {
+            matcher: SESSION_START_MATCHER,
+            hooks: [{ type: "command", command: SESSION_START_COMMAND, timeout: SESSION_START_TIMEOUT }],
+        },
+    ];
     return { byEvent, invalid };
 }
 /**
  * Merge speclaw's compiled hook groups into an existing `hooks` object by
  * identity: for every event, drop the groups speclaw owns (a group whose hooks
  * are all speclaw's) and re-add the freshly compiled ones, never touching a
- * group with a foreign `server` or `type`. Idempotent, marker-free, and it
+ * hook that is not speclaw's (see {@link isSpeclawHook}). Idempotent, and it
  * cannot delete another tool's hooks.
  *
  * @param existing - The current `hooks` object from the agent's settings (any shape).

package/dist/modules/lawbook/assets/agents/explorer.md

@@ -11,8 +11,9 @@ You are the **explorer** role in speclaw's **Cortex** (One brain. Many agents.).
 
 Investigate the idea or bug with Compass **before** any grep/read: locate with
 `compass_find`, read with `compass_explore`, and run `compass_index` only when
-find returns nothing or reports a missing or stale index. Read/Grep code only
-after naming which Rule 1 fallback holds. Produce a short brief for the
+find returns nothing or reports a missing or stale index (under Claude Code an
+existing index is already refreshed when the session starts). Read/Grep code
+only after naming which Rule 1 fallback holds. Produce a short brief for the
 planner: relevant symbols, blast radius, risks, open questions, and
 `Compass calls made: N`. Do **not** draft change artifacts or edit source.
 

package/dist/modules/lawbook/assets/commands/cortex.md

@@ -9,3 +9,5 @@ explorer → planner → implementer → reviewer → tester → archiver. Drive
 with the `cortex` MCP tool (`status`/`start`/`advance`/`rework`/`brief`) or
 `speclaw cortex …`. Surface planner questions to the human. Do not implement
 product code yourself.
+The run posts status updates every `cortex.statusIntervalMinutes` minutes
+(`lawbook/config.yaml`, default 5, `0` disables, at most 60).

package/dist/modules/lawbook/assets/skills/build/steps/03-implement.md

@@ -2,7 +2,8 @@
 
 - Use `compass_explore` before editing to see a symbol's callers/callees and
   blast radius; re-run `compass_index` after significant edits to keep the
-  graph fresh.
+  graph fresh (the `SessionStart` hook refreshes it only when a session
+  starts).
 - Make the smallest correct change; match the surrounding code.
 - The code must satisfy the delta spec exactly. If reality diverges from the
   spec, update the spec in the change (not silently) — the two must agree.

package/dist/modules/lawbook/assets/skills/cortex/steps/01-load-or-start.md

@@ -22,4 +22,31 @@ Stage → role:
 | archiving | archiver (`sync` + `archive`) |
 | done | stop — report success |
 
+## Status updates
+
+- Read `summary.statusIntervalMinutes` from the `status` result (after
+  `start`, run `status` once). `0` disables unsolicited updates; never parse
+  `lawbook/config.yaml` yourself.
+- Create the timer only when the summary is non-null and the stage is not
+  `done`, the interval is greater than 0, and the host has a session timer
+  (Claude Code `CronCreate`, session-only, at least 1 minute). Then create
+  **one** recurring timer every `statusIntervalMinutes` minutes:
+  - schedule: for 1–59 minutes use `*/N * * * *`; for 60 (the engine caps the
+    interval at 60) use an hourly expression such as `7 * * * *`;
+  - prompt: the timer firing is a fresh prompt, so it must carry its context.
+    Name the change and the rules: run `cortex` action `status` for that
+    change and post the update in the session's language; skip the ping while
+    the stage is `questions`; when the stage is `done` or the run was stopped,
+    delete this timer (`CronDelete`) and post nothing.
+- Remember the id that `CronCreate` returns; it is the run's status timer.
+  Before creating one, check that no status timer exists for this change
+  (your remembered id, or `CronList`), so there is exactly one per run.
+  `CronDelete` always targets that id.
+- Create the timer only inside a Cortex run, never a second one per run, and
+  none when the interval is 0.
+- Prefer background role dispatch: the timer fires only while the session is
+  idle, not during a blocking dispatch.
+- On a host without a session timer, the after-op and before-dispatch updates
+  of the dispatch loop stand in for it.
+
 Next: read `steps/02-dispatch-loop.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/cortex/steps/02-dispatch-loop.md

@@ -34,5 +34,20 @@ For the current Cortex stage (`cortex` action `brief` or `status`):
 4. Max rework is 3; if the engine rejects further rework, **ask the human**.
 5. Coordinator never edits `src/`, never archives, never pushes, never runs
    `laws accept`.
+6. **Status updates.** Unless `summary.statusIntervalMinutes` is 0, post a
+   compact update after every Cortex op and just before every blocking role
+   dispatch, built from the `status` summary fields:
+   - the change, the stage and active role, the elapsed time in the stage;
+   - tasks done/total, rework iteration/max, and the pending verdicts;
+   - in `questions`, that the human owes answers.
+
+   Write it in the session's language (the language of the human's most
+   recent messages); keep stage, role, and tool names, file paths, and change
+   names in English. `summary.line` is English-only; use it as is only in an
+   English session. Skip timer pings while the stage is `questions` (the
+   question round already speaks to the human). When the human asks to stop
+   the updates, delete the timer (`CronDelete` with the id `CronCreate`
+   returned) and post no further unsolicited update for this run. An explicit
+   request for status is always answered.
 
 Next: read `steps/03-complete.md` and do only what it says.

package/dist/modules/lawbook/assets/skills/cortex/steps/03-complete.md

@@ -1,6 +1,8 @@
 # Complete
 
-When Cortex stage is `done` (or the human stops the run), summarize:
+When Cortex stage is `done` (or the human stops the run), first delete the
+status timer if one exists (`CronDelete` with the id `CronCreate` returned,
+or the id `CronList` shows for this change), then summarize:
 
 - Change name and final stage
 - Review/test verdicts and iteration count

package/dist/modules/lawbook/assets/skills/draft/steps/02-understand.md

@@ -6,9 +6,11 @@
   `compass_find` or `compass_explore` only for a gap the brief names. Re-read
   a file under `docs/standards/` only when the brief does not cite it.
 - When the handoff has no complete explorer brief, refresh the index with
-  `compass_index`, then use `compass_explore` and `compass_find` (mode:
-  concept) before grep/read to locate the code and its blast radius. Read the
-  governing standards in `docs/standards/`.
+  `compass_index` (an existing index was already refreshed at session start
+  under Claude Code; refresh again after edits or when it is missing), then use
+  `compass_explore` and `compass_find` (mode: concept) before grep/read to
+  locate the code and its blast radius. Read the governing standards in
+  `docs/standards/`.
 - Clarify what the user wants (feature / fix / refactor) and confirm scope.
 - When `change.json` already has a `confirmedLevel` (the coordinator recorded
   it in the single question round), use that level and skip the separate level

package/dist/modules/lawbook/assets/skills/explore/steps/01-investigate.md

@@ -6,7 +6,9 @@
   callees. Use `compass_diff_context` when the question is about a diff.
 - **Index only when needed.** Run `compass_index` only when `compass_find`
   returns nothing or reports a missing or stale index, then retry the find. It
-  is incremental (unchanged files skipped by hash).
+  is incremental (unchanged files skipped by hash). Under Claude Code the
+  `SessionStart` hook already refreshes an existing index when the session
+  starts, so it is usually current.
 - **Read/Grep code only with a named reason.** Before any Read/Grep/Glob of
   indexed source code, name which Rule 1 fallback holds: (1) a Compass call ran
   and returned nothing useful for the query, (2) the graph is missing and

package/dist/modules/lawbook/assets/skills/investigate/steps/01-investigate.md

@@ -1,6 +1,8 @@
 # Investigate the bug
 
-- Refresh the index (`compass_index`).
+- Refresh the index (`compass_index`). Under Claude Code the `SessionStart`
+  hook already refreshed an existing index when the session started; refresh
+  again when files changed since then or the index is missing.
 - Call **`lawbook_investigate`** with `stackTrace` and/or `symptom`.
 - **`compass_explore`** the top suspect — read the code yourself.
 

package/dist/modules/lawbook/change-tool.js

@@ -6,6 +6,7 @@ import { scaffoldFeature } from "./scaffold-change.js";
 import { buildCoverageReport, loadCoverageConfig, renderCoverageAgent } from "./coverage.js";
 import { buildDriftReport, renderDriftAgent } from "./drift.js";
 import { handleHarness, harnessOps } from "../cortex/harness.js";
+import { fitStatusResult } from "../cortex/status.js";
 export const lawbookChangeActions = [
     "init",
     "list",
@@ -111,7 +112,7 @@ export function handleLawbookChange(args) {
             if (!args.harnessOp) {
                 throw new Error(`lawbook_change: action 'harness' requires 'harnessOp'`);
             }
-            return handleHarness({
+            const result = handleHarness({
                 projectPath: args.projectPath,
                 change: requireField(args, "change"),
                 harnessOp: args.harnessOp,
@@ -120,6 +121,8 @@ export function handleLawbookChange(args) {
                 pauseForQuestions: args.pauseForQuestions,
                 note: args.note ?? args.reason,
             });
+            // MCP-only path: fit `status` to the output budget like the `cortex` tool.
+            return args.harnessOp === "status" && "summary" in result ? fitStatusResult(result) : result;
         }
         default:
             throw new Error(`lawbook_change: unknown action '${String(args.action)}'`);

package/package.json

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