@esneiderbravo/speclaw 2.0.5 → 2.0.7

package/README.md

@@ -4,12 +4,12 @@
 
 <br/>
 
-<a href="https://www.npmjs.com/package/@esneiderbravo/speclaw"><img src="https://img.shields.io/npm/v/@esneiderbravo/speclaw?color=0E8E8E&labelColor=0B0F10&style=flat-square&label=npm" alt="npm"></a>
-&nbsp;<a href="https://github.com/esneiderbravo/speclaw/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/esneiderbravo/speclaw/ci.yml?branch=main&label=CI&labelColor=0B0F10&style=flat-square&color=0E8E8E" alt="CI"></a>
-&nbsp;<a href="https://www.npmjs.com/package/@esneiderbravo/speclaw?activeTab=versions"><img src="https://img.shields.io/badge/provenance-SLSA-0E8E8E?labelColor=0B0F10&style=flat-square" alt="npm provenance"></a>
-&nbsp;<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-0E8E8E?labelColor=0B0F10&style=flat-square" alt="MIT"></a>
-&nbsp;<img src="https://img.shields.io/badge/node-%E2%89%A522.16-0E8E8E?labelColor=0B0F10&style=flat-square" alt="Node >= 22.16">
-&nbsp;<img src="https://img.shields.io/badge/v2.0-0E8E8E?labelColor=0B0F10&style=flat-square" alt="v2.0">
+<a href="https://www.npmjs.com/package/@esneiderbravo/speclaw"><img src="https://img.shields.io/npm/v/@esneiderbravo/speclaw?color=00707f&labelColor=131313&style=flat-square&label=npm" alt="npm"></a>
+&nbsp;<a href="https://github.com/esneiderbravo/speclaw/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/esneiderbravo/speclaw/ci.yml?branch=main&label=CI&labelColor=131313&style=flat-square&color=00707f" alt="CI"></a>
+&nbsp;<a href="https://www.npmjs.com/package/@esneiderbravo/speclaw?activeTab=versions"><img src="https://img.shields.io/badge/provenance-SLSA-00707f?labelColor=131313&style=flat-square" alt="npm provenance"></a>
+&nbsp;<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-00707f?labelColor=131313&style=flat-square" alt="MIT"></a>
+&nbsp;<img src="https://img.shields.io/badge/node-%E2%89%A522.16-00707f?labelColor=131313&style=flat-square" alt="Node >= 22.16">
+&nbsp;<img src="https://img.shields.io/badge/v2.0-00707f?labelColor=131313&style=flat-square" alt="v2.0">
 
 <br/><br/>
 
@@ -24,12 +24,12 @@ those laws hold in the editor, in CI, and in the PR.
 One command. No cloud, no LLM, no API keys — <b>everything runs on your machine.</b>
 </p>
 
-<img src="https://img.shields.io/badge/100%25_local-0E8E8E?labelColor=0B0F10&style=flat-square" alt="100% local">
-&nbsp;<img src="https://img.shields.io/badge/no_LLM_·_no_cloud-0E8E8E?labelColor=0B0F10&style=flat-square" alt="no LLM">
-&nbsp;<img src="https://img.shields.io/badge/CLI_+_MCP-0E8E8E?labelColor=0B0F10&style=flat-square" alt="CLI + MCP">
-&nbsp;<img src="https://img.shields.io/badge/9_canonical_tools-0E8E8E?labelColor=0B0F10&style=flat-square" alt="9 tools">
-&nbsp;<img src="https://img.shields.io/badge/Cortex-One_brain._Many_agents.-0E8E8E?labelColor=0B0F10&style=flat-square" alt="Cortex">
-&nbsp;<img src="https://img.shields.io/badge/any_agent-0E8E8E?labelColor=0B0F10&style=flat-square" alt="any agent">
+<img src="https://img.shields.io/badge/100%25_local-00707f?labelColor=131313&style=flat-square" alt="100% local">
+&nbsp;<img src="https://img.shields.io/badge/no_LLM_·_no_cloud-00707f?labelColor=131313&style=flat-square" alt="no LLM">
+&nbsp;<img src="https://img.shields.io/badge/CLI_+_MCP-00707f?labelColor=131313&style=flat-square" alt="CLI + MCP">
+&nbsp;<img src="https://img.shields.io/badge/9_canonical_tools-00707f?labelColor=131313&style=flat-square" alt="9 tools">
+&nbsp;<img src="https://img.shields.io/badge/Cortex-One_brain._Many_agents.-00707f?labelColor=131313&style=flat-square" alt="Cortex">
+&nbsp;<img src="https://img.shields.io/badge/any_agent-00707f?labelColor=131313&style=flat-square" alt="any agent">
 
 </div>
 
@@ -107,7 +107,7 @@ gh attestation verify <tarball> --owner esneiderbravo
   <img src="https://raw.githubusercontent.com/esneiderbravo/speclaw/main/brand/terminal-init.png" width="800" alt="speclaw init — terminal output">
 </p>
 
-<p align="center"><i>Teal steps, green checks, a live progress bar — themed with the speclaw palette.</i></p>
+<p align="center"><i>Cyan steps, green checks, a live progress bar — themed with the speclaw palette.</i></p>
 
 <br/>
 
@@ -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/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/cli/lib/ui.js

@@ -1,17 +1,21 @@
-// Brand-themed terminal UI. Colors come from the speclaw palette (cyan #2EE6E6
-// = the "law", cream text, muted gray, green/amber for status) rendered as
-// 24-bit truecolor ANSI — no dependency needed. Colors auto-disable when the
-// output is not a TTY or NO_COLOR is set.
+// Brand-themed terminal UI. Colors come from the speclaw site's ink theme
+// (`app/tokens.css` in speclaw-site): signal cyan #00E3FD = the "law" accent,
+// ink #F4F4F3 primary text, ink-faint #999EA3 secondary text, deny #FF5C47 for
+// errors, and green/amber re-tuned for success/warning. Every color holds at
+// least 4.5:1 (WCAG 2.x) against the ink paper #131313. They render as 24-bit
+// truecolor ANSI — no dependency needed — and auto-disable when the output is
+// not a TTY or NO_COLOR is set.
 import { pkgVersion } from "../../shared/version.js";
-const PALETTE = {
-    cyan: [46, 230, 230], // #2EE6E6 — the accent / "law"
-    cyanDim: [23, 193, 193], // #17C1C1
-    cream: [244, 241, 234], // #F4F1EA — primary text
-    muted: [110, 123, 128], // #6E7B80 — secondary text
-    green: [63, 185, 80], // #3FB950 — success
-    amber: [227, 179, 65], // #E3B341 — warning
-    red: [235, 90, 90],
-};
+// Covers: req~brand-terminal-palette~1
+export const PALETTE = Object.freeze({
+    cyan: [0, 227, 253], // #00E3FD — signal: the accent / "law"
+    cyanDim: [0, 227, 253], // #00E3FD — signal (the site has no mid cyan for text)
+    cream: [244, 244, 243], // #F4F4F3 — ink: primary text
+    muted: [153, 158, 163], // #999EA3 — ink-faint: secondary text
+    green: [62, 207, 122], // #3ECF7A — success (re-tuned)
+    amber: [245, 183, 61], // #F5B73D — warning (re-tuned)
+    red: [255, 92, 71], // #FF5C47 — deny: errors
+});
 const colorOn = (Boolean(process.stdout.isTTY) || process.env.FORCE_COLOR === "1") && !process.env.NO_COLOR;
 // Whether the terminal reliably renders the unicode box/block glyphs the brand
 // output uses. Non-Windows terminals are assumed capable; a Windows console is

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/compass/visualize.js

@@ -88,11 +88,14 @@ export function visualize(projectPath, opts = {}) {
 /**
  * Render the graph as a self-contained, offline HTML page: the data is embedded
  * as JSON and drawn by an inline canvas force-directed renderer (no CDN, no
- * dependencies).
+ * dependencies). Colors are the site's ink tokens (`app/tokens.css` in
+ * speclaw-site): paper #131313, sheet #1f2022, rule #303236, ink #f4f4f3,
+ * ink-faint #999ea3, signal #00e3fd. No retired-palette color may return here.
  *
  * @param data - The nodes/links/totals to embed.
  * @returns A complete HTML document as a string.
  */
+// Covers: req~brand-viewer-palette~1
 export function renderHtml(data) {
     const payload = JSON.stringify(data);
     return `<!doctype html>
@@ -100,20 +103,20 @@ export function renderHtml(data) {
 <meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
 <title>speclaw · Compass graph</title>
 <style>
-  :root { --cy:#17C1C1; --cr:#F4F1EA; --mu:#6E7B80; --bg:#0B0F10; }
+  :root { --cy:#00e3fd; --cr:#f4f4f3; --mu:#999ea3; --bg:#131313; --sh:#1f2022; --ru:#303236; }
   * { box-sizing:border-box; }
   html,body { margin:0; height:100%; background:var(--bg); color:var(--cr);
-    font-family:'SF Mono','JetBrains Mono',Menlo,Consolas,monospace; overflow:hidden; }
+    font-family:'Chivo Mono','SFMono-Regular',Menlo,monospace; overflow:hidden; }
   canvas { display:block; cursor:grab; }
   canvas:active { cursor:grabbing; }
   .panel { position:fixed; top:16px; left:16px; padding:12px 14px; border-radius:10px;
-    background:rgba(12,17,19,.82); border:1px solid #232A2D; font-size:12px; line-height:1.5; }
+    background:rgba(31,32,34,.82); border:1px solid var(--ru); font-size:12px; line-height:1.5; }
   .panel b { color:var(--cr); } .panel .sub { color:var(--mu); }
   .legend { position:fixed; bottom:16px; left:16px; font-size:11px; color:var(--mu);
-    background:rgba(12,17,19,.82); border:1px solid #232A2D; border-radius:10px; padding:10px 12px; }
+    background:rgba(31,32,34,.82); border:1px solid var(--ru); border-radius:10px; padding:10px 12px; }
   .legend span { display:inline-flex; align-items:center; margin-right:12px; }
   .legend i { width:9px; height:9px; border-radius:50%; display:inline-block; margin-right:5px; }
-  .tip { position:fixed; padding:6px 9px; border-radius:7px; background:#0E1517; border:1px solid #17C1C1;
+  .tip { position:fixed; padding:6px 9px; border-radius:7px; background:var(--sh); border:1px solid var(--cy);
     color:var(--cr); font-size:12px; pointer-events:none; opacity:0; transition:opacity .1s; white-space:nowrap; }
   .brand { color:var(--cy); font-weight:700; }
 </style></head><body>
@@ -127,9 +130,9 @@ export function renderHtml(data) {
 <div class="tip" id="tip"></div>
 <script>
 const DATA = ${payload};
-const KIND_COLORS = { function:'#17C1C1', method:'#3FB950', class:'#E3B341',
-  interface:'#8B989E', type:'#8B989E', enum:'#8B989E' };
-const colorOf = k => KIND_COLORS[k] || '#6E7B80';
+const KIND_COLORS = { function:'#00e3fd', method:'#3ecf7a', class:'#f5b73d',
+  interface:'#babdc1', type:'#babdc1', enum:'#babdc1' };
+const colorOf = k => KIND_COLORS[k] || '#7c8083';
 
 const cv = document.getElementById('c'), ctx = cv.getContext('2d');
 const tip = document.getElementById('tip');
@@ -179,7 +182,7 @@ function draw(){
   ctx.lineWidth = 1;
   for(const l of L){ const a=toScreen(N[l.s]), b=toScreen(N[l.t]);
     const on = hover>=0 && (l.s===hover||l.t===hover);
-    ctx.strokeStyle = on ? 'rgba(23,193,193,.7)' : 'rgba(110,123,128,.16)';
+    ctx.strokeStyle = on ? 'rgba(0,227,253,.7)' : 'rgba(124,128,131,.16)';
     ctx.beginPath(); ctx.moveTo(a.x,a.y); ctx.lineTo(b.x,b.y); ctx.stroke();
   }
   for(let i=0;i<N.length;i++){ const n=N[i], p=toScreen(n);
@@ -187,7 +190,7 @@ function draw(){
     ctx.globalAlpha = dim ? 0.28 : 1;
     ctx.beginPath(); ctx.arc(p.x,p.y,n.r*Math.sqrt(scale),0,7); ctx.fillStyle=colorOf(n.kind); ctx.fill();
     if((n.r>7 || i===hover || (hoverSet&&hoverSet.has(i))) && scale>0.5){
-      ctx.globalAlpha = dim?0.4:0.9; ctx.fillStyle='#F4F1EA'; ctx.font='11px monospace';
+      ctx.globalAlpha = dim?0.4:0.9; ctx.fillStyle='#f4f4f3'; ctx.font="11px 'Chivo Mono','SFMono-Regular',Menlo,monospace";
       ctx.fillText(n.name, p.x+n.r+3, p.y+3);
     }
   }
@@ -208,7 +211,7 @@ addEventListener('mousemove', e=>{
   lastX=e.clientX; lastY=e.clientY;
   const i=pick(e.clientX,e.clientY); hover=i;
   if(i>=0){ const n=N[i]; tip.style.opacity=1; tip.style.left=(e.clientX+12)+'px'; tip.style.top=(e.clientY+12)+'px';
-    tip.innerHTML='<b>'+n.name+'</b> <span style="color:#6E7B80">'+n.kind+' · '+n.file+':'+n.line+'</span>'; }
+    tip.innerHTML='<b>'+n.name+'</b> <span style="color:#999ea3">'+n.kind+' · '+n.file+':'+n.line+'</span>'; }
   else tip.style.opacity=0;
 });
 addEventListener('mouseup', ()=>{ dragging=null; panning=false; });

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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@esneiderbravo/speclaw",
-  "version": "2.0.5",
+  "version": "2.0.7",
   "publishConfig": {
     "access": "public"
   },
@@ -59,6 +59,8 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "@fontsource/chivo": "^5.3.0",
+    "@fontsource/chivo-mono": "^5.3.0",
     "@resvg/resvg-js": "^2.6.2",
     "@types/node": "^22.0.0",
     "eslint": "^10.8.0",
@@ -67,6 +69,7 @@
     "globals": "^17.9.0",
     "prettier": "^3.9.6",
     "typescript": "^5.6.0",
-    "typescript-eslint": "^8.65.0"
+    "typescript-eslint": "^8.65.0",
+    "wawoff2": "^2.0.1"
   }
 }