@esneiderbravo/speclaw 0.4.0 → 1.0.1

package/dist/cli/commands/update.js

@@ -145,6 +145,45 @@ const MIGRATIONS = [
             "and `law_verify` are CLI-only. Minimal profile omits setup/check/investigate/index.\n" +
             "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
     },
+    {
+        version: "0.4.1",
+        describe: "Rule integrity — speclaw.lock digests + injection scan",
+        agentPrompt: "- Mention committed `speclaw.lock` at the repo root (never under `.speclaw/`), " +
+            "`speclaw laws lock` / `accept` / `scan`, and that digest acceptance is interactive TTY only " +
+            "(never via MCP). `speclaw verify` folds integrity findings with deps/graph. " +
+            "Strict paths include AGENTS.md / CLAUDE.md / compiled rules; standards docs are advisory.\n" +
+            "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
+    },
+    {
+        version: "0.4.2",
+        describe: "Spec ownership — team.owners → CODEOWNERS",
+        agentPrompt: '- Optional `team.owners` in `lawbook/config.yaml` maps capability names (and `"*"`) to ' +
+            "`@user` / `@org/team` / email owners. Run `speclaw owners --write` to compile a managed " +
+            "block at the **end** of `.github/CODEOWNERS` (GitHub: last match wins). `speclaw doctor` " +
+            "errors if content appears after the end marker. No new MCP tool — CLI only. " +
+            "deriveFromTraceability is not enabled in this release.\n" +
+            "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
+    },
+    {
+        version: "1.0.0",
+        describe: "speclaw 1.0 — official release (enforcement + graph + lawbook + owners)",
+        agentPrompt: "- speclaw **1.0** is the official release: Foundation (hooks + `speclaw.lock` integrity), " +
+            "Compass (schema 10, eight canonical MCP tools), Lawbook (ceremony 0–3, coverage, drift, " +
+            "bugfix), and Team (`team.owners` → `speclaw owners --write`). Install remains " +
+            "`npx @esneiderbravo/speclaw@latest init`. CI consumers use `esneiderbravo/speclaw@v1`.\n" +
+            "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
+    },
+    {
+        version: "1.0.1",
+        describe: "Seed laws match the target repository layout",
+        agentPrompt: "- After this update, speclaw rewrites `.speclaw/laws-manifest.json` from the " +
+            "target tree: dogfood laws (compass/foundation, ATTRIBUTION.md, local-first, " +
+            "protect-templates, shared-stays-inner) are dropped when those paths do not exist; " +
+            "the cycle law is scoped to detected source roots (`apps/*/src`, `packages/*/src`, " +
+            "`src/`, `lib/`) excluding test files, and considers import edges only. Run " +
+            "`speclaw laws compile` if agent rule files look stale, then `speclaw index`.\n" +
+            "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
+    },
 ];
 /**
  * Update speclaw and bring the current project up to date without a full re-init:

package/dist/cli/commands/verify.js

@@ -8,6 +8,7 @@ import { toMarkdown } from "../../modules/foundation/report-md.js";
 import { toSarif } from "../../modules/foundation/sarif.js";
 import { loadManifestForVerify } from "../../modules/foundation/laws.js";
 import { verifyLaws } from "../../modules/foundation/verify.js";
+import { foldIntegrityIntoReport, verifyIntegrity } from "../../modules/foundation/integrity.js";
 import { driftFindingsForVerify } from "../../modules/lawbook/drift.js";
 const FORMATS = new Set(["text", "json", "sarif", "markdown"]);
 /**
@@ -46,6 +47,13 @@ export async function runVerify(flags) {
         engines: engines.length ? engines : undefined,
         lawIds: list(flags.law).length ? list(flags.law) : undefined,
     });
+    // Rule-file integrity (speclaw.lock digests + injection scan). Soft when no lock.
+    // Covers: req~integrity-verify~1
+    const integrity = verifyIntegrity({ projectPath: cwd });
+    foldIntegrityIntoReport(report, integrity);
+    if (integrity.guidance && format === "text" && flags.json !== true) {
+        ui.info(integrity.guidance);
+    }
     // Structural spec↔code drift (when anchors exist) contributes semantic/deleted
     // findings into the same report stream used by SARIF / exit codes.
     for (const f of driftFindingsForVerify(cwd)) {

package/dist/cli/index.js

@@ -18,11 +18,11 @@ Setup
   agent add <id>           Configure another agent later (symlinks + MCP)
 
 Compass (code intelligence — the same surface agents use via MCP)
-  index                    (Re)build the local code graph, with progress
+  index                    (Re)build the local code graph (--force / --prune)
   watch                    Keep the index fresh on file changes
   explore <node>           A node's source + callers/callees
-  search <query>           Find nodes by name/keyword
-  recall "<query>"         Find code by meaning (semantic)
+  search <query>           Hybrid find (BM25+vector+name); --focus --max-tokens --explain
+  recall "<query>"         Hybrid find with concept weights; same flags as search
   impact <node>            Blast radius (grouped by module; --flat / --json)
   affected-tests           Tests affected by a change (--file / --from-diff / --json)
   diff-context             Change context for a diff (--file / --rev / --worktree / --json)
@@ -47,10 +47,16 @@ Other
   budget                   Measure always-on context cost (tools, skills, instructions)
   coverage                 Requirement → impl → test coverage (--json, --tap, --adopt, --write)
   drift                    Spec↔code drift (--json, --reseal, --reverse, --fail-on)
+  owners                   Compile team.owners → .github/CODEOWNERS (--write / --check / --diff)
   telemetry status         Confirm speclaw ships no telemetry
   check                    Evaluate an action against the laws (hooks call this; --dry-run to preview)
   laws verify              Verify the deterministic dependency/graph laws against the index
-  verify                   Verify laws for CI: exit codes, --sarif, --json, --strict-engines
+  laws compile             Compile laws into agent rule dialects (AGENTS / Claude / Cursor / …)
+  laws import              Import third-party rules as draft laws (--from rulesync)
+  laws lock                Create/refresh committed speclaw.lock digests for rule files
+  laws accept <path>       Interactively accept a changed rule-file digest (TTY only)
+  laws scan                Scan rule/skill files for prompt-injection patterns
+  verify                   Verify laws + integrity for CI: exit codes, --sarif, --json, --strict-engines
   mcp                      Start the MCP server (used by your agent's config)
   help                     Show this help
   --version                Print the installed speclaw version
@@ -74,6 +80,7 @@ const HEADER_COMMANDS = new Set([
     "coverage",
     "drift",
     "telemetry",
+    "owners",
     "index",
     "watch",
     "lawbook",
@@ -165,6 +172,8 @@ async function dispatch(cmd, flags) {
             return (await import("./commands/drift.js")).runDrift(flags);
         case "telemetry":
             return (await import("./commands/telemetry.js")).runTelemetry(flags);
+        case "owners":
+            return (await import("./commands/owners.js")).runOwners(flags);
         case "check":
             return (await import("./commands/check.js")).runCheck(flags);
         case "laws":

package/dist/modules/compass/budget.js

@@ -0,0 +1,128 @@
+/**
+ * Fit ranked retrieval hits into a token budget via binary search, and render
+ * a compact TreeContext with elision markers.
+ */
+/**
+ * Rough token estimate: ~4 chars/token, sampling every 100th line on large text.
+ *
+ * @param s - Text to estimate.
+ */
+export function estimateTokens(s) {
+    if (s.length < 4000)
+        return Math.ceil(s.length / 4);
+    const lines = s.split("\n");
+    if (lines.length < 200)
+        return Math.ceil(s.length / 4);
+    let sampled = 0;
+    let count = 0;
+    for (let i = 0; i < lines.length; i += 100) {
+        sampled += lines[i].length + 1;
+        count++;
+    }
+    const avg = sampled / Math.max(count, 1);
+    return Math.ceil((avg * lines.length) / 4);
+}
+/**
+ * Render hits as a TreeContext block with `⋮` elision between non-adjacent lines.
+ *
+ * @param hits - Ordered hits to include.
+ */
+export function renderTreeContext(hits) {
+    if (hits.length === 0)
+        return "";
+    const byFile = new Map();
+    for (const h of hits) {
+        const list = byFile.get(h.file) ?? [];
+        list.push(h);
+        byFile.set(h.file, list);
+    }
+    const parts = [];
+    for (const [file, list] of byFile) {
+        parts.push(`# ${file}`);
+        list.sort((a, b) => a.line - b.line);
+        let lastLine = -Infinity;
+        for (const h of list) {
+            if (h.line - lastLine > 3 && lastLine !== -Infinity)
+                parts.push("⋮");
+            const sig = h.signature ?? `${h.kind} ${h.name}`;
+            parts.push(`${h.line}| ${sig}`);
+            if (h.excerpt) {
+                const lines = h.excerpt.split("\n");
+                if (lines.length > 6) {
+                    parts.push(...lines.slice(0, 3).map((l) => `  ${l}`));
+                    parts.push("  ⋮");
+                    parts.push(...lines.slice(-2).map((l) => `  ${l}`));
+                }
+                else {
+                    parts.push(...lines.map((l) => `  ${l}`));
+                }
+            }
+            lastLine = h.line;
+        }
+    }
+    return parts.join("\n");
+}
+/**
+ * Binary-search how many leading hits fit `maxTokens` within 15% tolerance.
+ * Never returns empty when hits is non-empty — truncates the first hit instead.
+ *
+ * @param ranked - Hits in final rank order.
+ * @param maxTokens - Token budget.
+ */
+export function fitToBudget(ranked, maxTokens) {
+    const budget = Math.max(1, maxTokens);
+    if (ranked.length === 0) {
+        return { rendered: "", tokens: 0, budget, hitCount: 0 };
+    }
+    let lower = 1;
+    let upper = ranked.length;
+    let best = renderTreeContext(ranked.slice(0, 1));
+    let bestCount = 1;
+    while (lower <= upper) {
+        const mid = (lower + upper) >> 1;
+        const tree = renderTreeContext(ranked.slice(0, mid));
+        const n = estimateTokens(tree);
+        if (Math.abs(n - budget) / budget < 0.15) {
+            return { rendered: tree, tokens: n, budget, hitCount: mid };
+        }
+        if (n <= budget) {
+            best = tree;
+            bestCount = mid;
+            lower = mid + 1;
+        }
+        else {
+            upper = mid - 1;
+        }
+    }
+    // Single oversized hit: truncate excerpt.
+    if (bestCount === 1 && estimateTokens(best) > budget) {
+        const h = { ...ranked[0], excerpt: truncateExcerpt(ranked[0].excerpt, budget) };
+        const rendered = renderTreeContext([h]);
+        return { rendered, tokens: estimateTokens(rendered), budget, hitCount: 1 };
+    }
+    return {
+        rendered: best,
+        tokens: estimateTokens(best),
+        budget,
+        hitCount: bestCount,
+    };
+}
+function truncateExcerpt(excerpt, budget) {
+    if (!excerpt)
+        return "";
+    const maxChars = Math.max(32, budget * 3);
+    if (excerpt.length <= maxChars)
+        return excerpt;
+    return `${excerpt.slice(0, maxChars)}\n⋮`;
+}
+/**
+ * Default token budget inspired by aider: clamp between 1024 and 4096, ×8 when
+ * there is no focus set.
+ *
+ * @param hasFocus - Whether a non-empty focus file set is in use.
+ * @param maxInput - Optional model input window hint.
+ */
+export function defaultBudget(hasFocus, maxInput = 32_000) {
+    const base = Math.max(1024, Math.min(Math.floor(maxInput / 8), 4096));
+    return hasFocus ? base : base * 8;
+}

package/dist/modules/compass/db.js

@@ -1,6 +1,7 @@
 import { DatabaseSync } from "node:sqlite";
 import fs from "node:fs";
 import path from "node:path";
+import { contentHashFor, defaultEmbedText } from "./embed-input.js";
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS meta (
   key TEXT PRIMARY KEY,
@@ -12,7 +13,9 @@ CREATE TABLE IF NOT EXISTS files (
   hash TEXT NOT NULL,
   lang TEXT NOT NULL,
   is_test INTEGER NOT NULL DEFAULT 0,
-  module TEXT NOT NULL DEFAULT ''
+  module TEXT NOT NULL DEFAULT '',
+  mtime_ms INTEGER,
+  size INTEGER
 );
 CREATE INDEX IF NOT EXISTS idx_files_is_test ON files(is_test);
 -- nodes: the definitions in the codebase (functions, classes, methods, types).
@@ -28,11 +31,13 @@ CREATE TABLE IF NOT EXISTS nodes (
   parent_id INTEGER,
   signature TEXT,
   body_hash TEXT,
-  norm_hash TEXT
+  norm_hash TEXT,
+  content_hash TEXT
 );
 CREATE INDEX IF NOT EXISTS idx_nodes_name ON nodes(name);
 CREATE INDEX IF NOT EXISTS idx_nodes_file ON nodes(file_id);
 CREATE INDEX IF NOT EXISTS idx_nodes_norm_hash ON nodes(norm_hash);
+CREATE INDEX IF NOT EXISTS idx_nodes_content_hash ON nodes(content_hash);
 -- node_metrics: AST health frames (LOC / nesting / branches) per definition.
 CREATE TABLE IF NOT EXISTS node_metrics (
   node_id INTEGER PRIMARY KEY REFERENCES nodes(id) ON DELETE CASCADE,
@@ -53,12 +58,23 @@ CREATE TABLE IF NOT EXISTS edges (
 CREATE INDEX IF NOT EXISTS idx_edges_dst ON edges(dst_name);
 CREATE INDEX IF NOT EXISTS idx_edges_src ON edges(src_node_id);
 CREATE INDEX IF NOT EXISTS idx_edges_dstid ON edges(dst_node_id);
--- node_embeddings: the local vector store (one embedding per node).
-CREATE TABLE IF NOT EXISTS node_embeddings (
-  node_id INTEGER PRIMARY KEY REFERENCES nodes(id) ON DELETE CASCADE,
-  dim INTEGER NOT NULL,
+-- embedding_cache: vectors keyed by embedder-input content hash (survives reindex).
+CREATE TABLE IF NOT EXISTS embedding_cache (
+  content_hash TEXT NOT NULL,
   model TEXT NOT NULL,
-  vec BLOB NOT NULL
+  dim INTEGER NOT NULL,
+  vec BLOB NOT NULL,
+  created_at INTEGER NOT NULL,
+  last_seen_at INTEGER NOT NULL,
+  PRIMARY KEY (content_hash, model)
+);
+CREATE INDEX IF NOT EXISTS idx_embedding_cache_seen ON embedding_cache(last_seen_at);
+-- dir_hashes: Merkle tree of indexed directories ("" = project root).
+CREATE TABLE IF NOT EXISTS dir_hashes (
+  path TEXT PRIMARY KEY,
+  hash TEXT NOT NULL,
+  n_files INTEGER NOT NULL,
+  updated_at INTEGER NOT NULL
 );
 -- git_history_cache: memoized results of the expensive git-history scans
 -- (churn, co-change), keyed by query and invalidated when HEAD moves.
@@ -109,9 +125,104 @@ CREATE TABLE IF NOT EXISTS spec_anchors (
 CREATE INDEX IF NOT EXISTS idx_anchors_capability ON spec_anchors(capability);
 CREATE INDEX IF NOT EXISTS idx_anchors_symbol ON spec_anchors(symbol_name);
 CREATE INDEX IF NOT EXISTS idx_anchors_node ON spec_anchors(node_id);
+-- node_text: searchable name/subtokens/signature/doc (FTS content source).
+CREATE TABLE IF NOT EXISTS node_text (
+  node_id INTEGER PRIMARY KEY REFERENCES nodes(id) ON DELETE CASCADE,
+  name TEXT NOT NULL,
+  subtokens TEXT NOT NULL DEFAULT '',
+  signature TEXT NOT NULL DEFAULT '',
+  doc TEXT NOT NULL DEFAULT ''
+);
+-- pagerank: global (non-personalized) scores recomputed at index time.
+CREATE TABLE IF NOT EXISTS pagerank (
+  node_id INTEGER PRIMARY KEY REFERENCES nodes(id) ON DELETE CASCADE,
+  score REAL NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_pagerank_score ON pagerank(score DESC);
 `;
+const FTS_DDL = `
+CREATE VIRTUAL TABLE IF NOT EXISTS nodes_fts USING fts5(
+  name, subtokens, signature, doc,
+  content='node_text', content_rowid='node_id',
+  tokenize="unicode61 remove_diacritics 0 tokenchars '_$'",
+  prefix='2 3'
+);
+CREATE TRIGGER IF NOT EXISTS node_text_ai AFTER INSERT ON node_text BEGIN
+  INSERT INTO nodes_fts(rowid, name, subtokens, signature, doc)
+  VALUES (new.node_id, new.name, new.subtokens, new.signature, new.doc);
+END;
+CREATE TRIGGER IF NOT EXISTS node_text_ad AFTER DELETE ON node_text BEGIN
+  INSERT INTO nodes_fts(nodes_fts, rowid, name, subtokens, signature, doc)
+  VALUES ('delete', old.node_id, old.name, old.subtokens, old.signature, old.doc);
+END;
+CREATE TRIGGER IF NOT EXISTS node_text_au AFTER UPDATE ON node_text BEGIN
+  INSERT INTO nodes_fts(nodes_fts, rowid, name, subtokens, signature, doc)
+  VALUES ('delete', old.node_id, old.name, old.subtokens, old.signature, old.doc);
+  INSERT INTO nodes_fts(rowid, name, subtokens, signature, doc)
+  VALUES (new.node_id, new.name, new.subtokens, new.signature, new.doc);
+END;
+`;
+/** Ensure node_embeddings is a VIEW over embedding_cache (idempotent). */
+function ensureEmbeddingsView(db) {
+    const row = db
+        .prepare("SELECT type FROM sqlite_master WHERE name = 'node_embeddings' LIMIT 1")
+        .get();
+    if (row?.type === "view")
+        return;
+    if (row?.type === "table") {
+        db.exec("DROP TABLE node_embeddings");
+    }
+    db.exec(`
+    CREATE VIEW node_embeddings AS
+      SELECT n.id AS node_id, ec.dim AS dim, ec.model AS model, ec.vec AS vec
+      FROM nodes n
+      JOIN embedding_cache ec ON ec.content_hash = n.content_hash
+  `);
+}
+/**
+ * Try to create the FTS5 virtual table + sync triggers. Soft-degrades when the
+ * Node SQLite build lacks FTS5 (pre-22.16).
+ *
+ * @returns Whether FTS5 is usable after this call.
+ */
+export function ensureFts(db) {
+    const existing = db.prepare("SELECT 1 FROM sqlite_master WHERE name = 'nodes_fts' LIMIT 1").get();
+    if (existing) {
+        db.prepare("INSERT INTO meta(key, value) VALUES ('fts5', '1') ON CONFLICT(key) DO UPDATE SET value = excluded.value").run();
+        return true;
+    }
+    try {
+        db.exec(FTS_DDL);
+        db.prepare("INSERT INTO meta(key, value) VALUES ('fts5', '1') ON CONFLICT(key) DO UPDATE SET value = excluded.value").run();
+        return true;
+    }
+    catch {
+        db.prepare("INSERT INTO meta(key, value) VALUES ('fts5', '0') ON CONFLICT(key) DO UPDATE SET value = excluded.value").run();
+        return false;
+    }
+}
+/** Whether the open database has a usable FTS5 index. */
+export function ftsAvailable(db) {
+    const row = db.prepare("SELECT value FROM meta WHERE key = 'fts5'").get();
+    if (row?.value === "0")
+        return false;
+    const tbl = db.prepare("SELECT 1 FROM sqlite_master WHERE name = 'nodes_fts' LIMIT 1").get();
+    return Boolean(tbl);
+}
+/** Probe whether this Node build can create an FTS5 virtual table. */
+export function probeFts5Support() {
+    try {
+        const mem = new DatabaseSync(":memory:");
+        mem.exec("CREATE VIRTUAL TABLE t USING fts5(x)");
+        mem.close();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /** Schema version stamped into the `meta` table on first creation. */
-export const SCHEMA_VERSION = "8";
+export const SCHEMA_VERSION = "10";
 /** The stamped schema version, or null if the db predates versioning / has no meta table. */
 function readSchemaVersion(db) {
     try {
@@ -124,10 +235,7 @@ function readSchemaVersion(db) {
 }
 /**
  * Decide whether an existing database is from an incompatible schema and must be
- * rebuilt. A fresh database (no tables) needs no reset — the schema will create
- * them. An existing one is stale if its stamped version differs from the current
- * one, or if the `edges` table is missing a column the current code writes to
- * (guards against past schema changes that weren't version-bumped).
+ * rebuilt. Schema 8→9 and 9→10 are handled by migrators instead of a wipe.
  */
 function isStale(db) {
     const hasEdges = db
@@ -135,7 +243,10 @@ function isStale(db) {
         .get();
     if (!hasEdges)
         return false;
-    if (readSchemaVersion(db) !== SCHEMA_VERSION)
+    const ver = readSchemaVersion(db);
+    if (ver === "8" || ver === "9")
+        return false; // migrate in openDb
+    if (ver !== SCHEMA_VERSION)
         return true;
     const edgeCols = db.prepare("PRAGMA table_info(edges)").all().map((c) => c.name);
     if (!edgeCols.includes("src_node_id") || !edgeCols.includes("dst_node_id"))
@@ -151,10 +262,18 @@ function isStale(db) {
 /** Drop every table (children first) so the current schema can be recreated cleanly. */
 function resetSchema(db) {
     db.exec(`
+    DROP VIEW IF EXISTS node_embeddings;
+    DROP TRIGGER IF EXISTS node_text_ai;
+    DROP TRIGGER IF EXISTS node_text_ad;
+    DROP TRIGGER IF EXISTS node_text_au;
+    DROP TABLE IF EXISTS nodes_fts;
+    DROP TABLE IF EXISTS pagerank;
+    DROP TABLE IF EXISTS node_text;
     DROP TABLE IF EXISTS spec_anchors;
     DROP TABLE IF EXISTS coverage_links;
     DROP TABLE IF EXISTS git_history_cache;
-    DROP TABLE IF EXISTS node_embeddings;
+    DROP TABLE IF EXISTS embedding_cache;
+    DROP TABLE IF EXISTS dir_hashes;
     DROP TABLE IF EXISTS edges;
     DROP TABLE IF EXISTS node_metrics;
     DROP TABLE IF EXISTS nodes;
@@ -162,14 +281,131 @@ function resetSchema(db) {
     DROP TABLE IF EXISTS meta;
   `);
 }
+/**
+ * Migrate schema 8 → 9: embedding_cache, dir_hashes, mtime/size, content_hash,
+ * preserve vectors into the cache, replace node_embeddings table with a view.
+ *
+ * @param db - Open connection already at schema 8.
+ * @param projectPath - Project root for backfilling content hashes from disk.
+ */
+export function migrate8to9(db, projectPath) {
+    db.exec("BEGIN IMMEDIATE");
+    try {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS embedding_cache (
+        content_hash TEXT NOT NULL,
+        model TEXT NOT NULL,
+        dim INTEGER NOT NULL,
+        vec BLOB NOT NULL,
+        created_at INTEGER NOT NULL,
+        last_seen_at INTEGER NOT NULL,
+        PRIMARY KEY (content_hash, model)
+      );
+      CREATE INDEX IF NOT EXISTS idx_embedding_cache_seen ON embedding_cache(last_seen_at);
+      CREATE TABLE IF NOT EXISTS dir_hashes (
+        path TEXT PRIMARY KEY,
+        hash TEXT NOT NULL,
+        n_files INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      );
+    `);
+        const fileCols = db.prepare("PRAGMA table_info(files)").all().map((c) => c.name);
+        if (!fileCols.includes("mtime_ms"))
+            db.exec("ALTER TABLE files ADD COLUMN mtime_ms INTEGER");
+        if (!fileCols.includes("size"))
+            db.exec("ALTER TABLE files ADD COLUMN size INTEGER");
+        const nodeCols = db.prepare("PRAGMA table_info(nodes)").all().map((c) => c.name);
+        if (!nodeCols.includes("content_hash")) {
+            db.exec("ALTER TABLE nodes ADD COLUMN content_hash TEXT");
+            db.exec("CREATE INDEX IF NOT EXISTS idx_nodes_content_hash ON nodes(content_hash)");
+        }
+        const upd = db.prepare("UPDATE nodes SET content_hash = ? WHERE id = ?");
+        const rows = db
+            .prepare(`SELECT n.id, n.kind, n.name, n.signature, f.lang
+         FROM nodes n JOIN files f ON f.id = n.file_id`)
+            .all();
+        for (const r of rows) {
+            const embedText = defaultEmbedText(r.kind, r.name, r.signature);
+            upd.run(contentHashFor({
+                lang: r.lang,
+                kind: r.kind,
+                name: r.name,
+                signature: r.signature,
+                embedText,
+            }), r.id);
+        }
+        void projectPath;
+        const now = Date.now();
+        const embType = db
+            .prepare("SELECT type FROM sqlite_master WHERE name = 'node_embeddings' LIMIT 1")
+            .get();
+        if (embType?.type === "table") {
+            db.prepare(`INSERT OR IGNORE INTO embedding_cache(content_hash, model, dim, vec, created_at, last_seen_at)
+         SELECT n.content_hash, ne.model, ne.dim, ne.vec, ?, ?
+         FROM node_embeddings ne
+         JOIN nodes n ON n.id = ne.node_id
+         WHERE n.content_hash IS NOT NULL`).run(now, now);
+            db.exec("DROP TABLE node_embeddings");
+        }
+        ensureEmbeddingsView(db);
+        db.prepare("INSERT INTO meta(key, value) VALUES ('schema_version', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run("9");
+        db.exec("COMMIT");
+    }
+    catch (err) {
+        try {
+            db.exec("ROLLBACK");
+        }
+        catch {
+            /* already rolled back */
+        }
+        throw new Error(`schema 8→9 migration failed — delete .speclaw/index.db to rebuild: ${err.message}`, { cause: err });
+    }
+}
+/**
+ * Migrate schema 9 → 10: `node_text`, optional FTS5, `pagerank`. Embedding cache
+ * is left intact; a reindex is required to populate text rows.
+ *
+ * @param db - Open connection already at schema 9.
+ */
+export function migrate9to10(db) {
+    db.exec("BEGIN IMMEDIATE");
+    try {
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS node_text (
+        node_id INTEGER PRIMARY KEY REFERENCES nodes(id) ON DELETE CASCADE,
+        name TEXT NOT NULL,
+        subtokens TEXT NOT NULL DEFAULT '',
+        signature TEXT NOT NULL DEFAULT '',
+        doc TEXT NOT NULL DEFAULT ''
+      );
+      CREATE TABLE IF NOT EXISTS pagerank (
+        node_id INTEGER PRIMARY KEY REFERENCES nodes(id) ON DELETE CASCADE,
+        score REAL NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_pagerank_score ON pagerank(score DESC);
+    `);
+        ensureFts(db);
+        db.prepare("INSERT INTO meta(key, value) VALUES ('schema_version', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run("10");
+        db.prepare("INSERT INTO meta(key, value) VALUES ('needs_reindex', '1') ON CONFLICT(key) DO UPDATE SET value = excluded.value").run();
+        db.prepare("INSERT INTO meta(key, value) VALUES ('reindex_reason', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run("schema 10 adds full-text index (names, subtokens, signatures, docs); reindex required");
+        db.exec("COMMIT");
+    }
+    catch (err) {
+        try {
+            db.exec("ROLLBACK");
+        }
+        catch {
+            /* already rolled back */
+        }
+        throw new Error(`schema 9→10 migration failed — delete .speclaw/index.db to rebuild: ${err.message}`, { cause: err });
+    }
+}
 /**
  * Open (creating if needed) the index database at `<projectPath>/.speclaw/index.db`.
  *
  * Ensures the `.speclaw` directory exists, enables WAL journaling and foreign
- * keys, and applies the schema. If an existing database is from an incompatible
- * schema (e.g. after a speclaw upgrade), it is dropped and rebuilt — `.speclaw`
- * is fully regenerable, so the next index just repopulates it. The schema
- * version is stamped on a fresh (or freshly reset) database.
+ * keys, and applies the schema. Schema 8→9 and 9→10 migrate in place
+ * (embeddings preserved). Other incompatible schemas are wiped and rebuilt.
  *
  * @param projectPath - Absolute path to the project root.
  * @returns An open connection to the index database.
@@ -178,19 +414,43 @@ export function openDb(projectPath) {
     const dir = path.join(projectPath, ".speclaw");
     fs.mkdirSync(dir, { recursive: true });
     const db = new DatabaseSync(path.join(dir, "index.db"));
-    db.exec("PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON;");
-    const wiped = isStale(db);
-    if (wiped)
-        resetSchema(db);
-    db.exec(SCHEMA);
-    const row = db.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get();
-    if (!row) {
-        db.prepare("INSERT INTO meta(key, value) VALUES ('schema_version', ?)").run(SCHEMA_VERSION);
-    }
-    if (wiped) {
-        db.prepare("INSERT INTO meta(key, value) VALUES ('needs_reindex', '1') ON CONFLICT(key) DO UPDATE SET value = excluded.value").run();
+    db.exec("PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON; PRAGMA busy_timeout = 5000;");
+    const ver = (() => {
+        try {
+            return readSchemaVersion(db);
+        }
+        catch {
+            return null;
+        }
+    })();
+    if (ver === "8") {
+        migrate8to9(db, projectPath);
+        migrate9to10(db);
+        db.exec(SCHEMA);
+        ensureEmbeddingsView(db);
+        ensureFts(db);
+    }
+    else if (ver === "9") {
+        migrate9to10(db);
+        db.exec(SCHEMA);
+        ensureEmbeddingsView(db);
+        ensureFts(db);
+    }
+    else {
+        const wiped = isStale(db);
+        if (wiped)
+            resetSchema(db);
+        db.exec(SCHEMA);
+        ensureEmbeddingsView(db);
+        ensureFts(db);
+        const row = db.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get();
+        if (!row) {
+            db.prepare("INSERT INTO meta(key, value) VALUES ('schema_version', ?)").run(SCHEMA_VERSION);
+        }
+        if (wiped) {
+            db.prepare("INSERT INTO meta(key, value) VALUES ('needs_reindex', '1') ON CONFLICT(key) DO UPDATE SET value = excluded.value").run();
+        }
     }
-    // Projection from committed JSON — safe even when nodes are empty (node_id null).
     rehydrateAnchors(db, projectPath);
     return db;
 }

package/dist/modules/compass/embed-input.js

@@ -0,0 +1,28 @@
+import { createHash } from "node:crypto";
+/**
+ * Bump when the text (or metadata) fed to the embedder changes shape.
+ * Combined into LexicalEmbedder.id so stale cache rows never match.
+ */
+export const EMBED_INPUT_VERSION = "in2";
+/**
+ * Content-addressable key for `embedding_cache`: hash of the embedder recipe,
+ * not the file path and not solely `body_hash` (drift uses a different recipe).
+ *
+ * @param input - Language, kind, name, optional signature, and embedder text.
+ */
+export function contentHashFor(input) {
+    return createHash("sha256")
+        .update([
+        EMBED_INPUT_VERSION,
+        input.lang,
+        input.kind,
+        input.name,
+        input.signature ?? "",
+        input.embedText,
+    ].join("\0"))
+        .digest("hex");
+}
+/** Default embedder text for a symbol (matches historical indexer behaviour). */
+export function defaultEmbedText(kind, name, signature) {
+    return `${kind} ${name} ${signature ?? ""}`;
+}