@esneiderbravo/speclaw 2.0.11 → 2.0.13

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 **11**. Refreshed silently at every Claude Code session start once built. 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 **12** (type-reference callers). 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. |
@@ -310,6 +310,10 @@ speclaw laws accept AGENTS.md   # interactive TTY only — never via MCP
 speclaw laws lock --force       # list drifted files, confirm, re-baseline — interactive TTY only
 ```
 
+`speclaw laws scan` (text or `--json`) exits 1 when `speclaw.lock` cannot be
+read or a finding has severity `error`. On an unreadable lock it names the lock
+error (`lockError` in the JSON) and still reports every injection finding.
+
 A lock refresh (`init`, `update`, `laws compile`, `laws lock`) never launders an
 edit: a strict file (`CLAUDE.md`, `AGENTS.md`, compiled rules) that drifted from
 the lock outside speclaw **keeps its locked digest**, and the command warns

package/dist/cli/commands/cortex.js

@@ -1,6 +1,6 @@
 import { handleHarness, readHarness } from "../../modules/cortex/harness.js";
 import { briefForStage } from "../../modules/cortex/brief.js";
-import { list } from "../lib/args.js";
+import { repeated } from "../lib/args.js";
 import { ui } from "../lib/ui.js";
 const OPS = ["status", "start", "advance", "rework", "brief"];
 /**
@@ -36,7 +36,8 @@ export async function runCortex(flags) {
             change: changeName,
             harnessOp: op,
             verdict: verdict ?? null,
-            openQuestions: list(flags.question),
+            // Covers: req~harness-state~1
+            openQuestions: repeated(flags.question),
             pauseForQuestions: Boolean(flags["pause-questions"]),
             note: typeof flags.note === "string" ? flags.note : undefined,
         });

package/dist/cli/commands/lawbook.js

@@ -5,7 +5,7 @@ import { scaffoldFeature } from "../../modules/lawbook/scaffold-change.js";
 import { investigate, formatInvestigateResult } from "../../modules/lawbook/investigate.js";
 import { handleHarness } from "../../modules/cortex/harness.js";
 import { printHarnessWarnings } from "./cortex.js";
-import { list } from "../lib/args.js";
+import { list, repeated } from "../lib/args.js";
 import { ui } from "../lib/ui.js";
 function today() {
     // The MCP path passes the date in; the CLL runs on a real machine, so read it here.
@@ -126,7 +126,10 @@ export async function runSpec(flags) {
                         console.log(JSON.stringify(result, null, 2));
                         return;
                     }
-                    ui.ok(`bug change "${name}" scaffolded at ${result.dir}`);
+                    ui.ok(`bug change "${name}" scaffolded at ${result.dir} ` +
+                        (level === undefined
+                            ? "(level unconfirmed — run `speclaw lawbook level set`)"
+                            : `(level ${level})`));
                     return;
                 }
                 const name = req(change, "lawbook draft <name> [--level N] [--capability C] [--json] | --bug <name>");
@@ -181,7 +184,8 @@ export async function runSpec(flags) {
                     change: changeName,
                     harnessOp: op,
                     verdict: verdict ?? null,
-                    openQuestions: list(flags.question),
+                    // Covers: req~harness-state~1
+                    openQuestions: repeated(flags.question),
                     pauseForQuestions: Boolean(flags["pause-questions"]),
                     note: typeof flags.note === "string" ? flags.note : undefined,
                 });

package/dist/cli/commands/laws.js

@@ -73,13 +73,21 @@ export async function runLaws(flags) {
         return;
     }
     if (sub === "scan") {
+        // Text and --json share one exit rule: 1 on an unreadable lock or any
+        // error-severity finding, else 0.
+        // Covers: req~injection-scan~1, req~laws-integrity-cli~1
         const report = verifyIntegrity({ projectPath: process.cwd(), checks: "scan" });
+        const failed = report.lockError !== undefined || report.findings.some((f) => f.severity === "error");
         if (flags.json) {
             console.log(JSON.stringify(report, null, 2));
+            if (failed)
+                process.exit(1);
             return;
         }
         ui.heading("speclaw laws scan");
-        if (report.findings.length === 0) {
+        if (report.lockError !== undefined)
+            ui.err(report.lockError);
+        if (report.findings.length === 0 && report.lockError === undefined) {
             ui.ok("No injection findings.");
             return;
         }
@@ -91,7 +99,7 @@ export async function runLaws(flags) {
             else
                 ui.warn(msg);
         }
-        if (report.findings.some((f) => f.severity === "error"))
+        if (failed)
             process.exit(1);
         return;
     }

package/dist/cli/commands/query.js

@@ -36,7 +36,7 @@ export async function runQuery(cmd, flags) {
     try {
         switch (cmd) {
             case "explore": {
-                const r = explore(cwd, need(args[0], "explore <node>"));
+                const r = explore(cwd, need(args[0], "explore <node>"), { includeRefs: true });
                 if (!r.found) {
                     ui.warn(r.message ?? "not found");
                     r.otherMatches?.forEach((m) => ui.info(`${m.name} (${m.kind}) ${m.file}:${m.line}`));
@@ -51,7 +51,7 @@ export async function runQuery(cmd, flags) {
                     ui.info(`+ ${r.unresolvedCallees.count} unresolved call(s): ${r.unresolvedCallees.sample.join(", ")}`);
                 }
                 ui.heading("Callers");
-                r.callers?.forEach((c) => ui.info(`${c.kind === "file" ? "(file) " : ""}${c.name} (${c.file}:${c.line})`));
+                r.callers?.forEach((c) => ui.info(`${c.kind === "file" ? "(file) " : ""}${c.name} (${c.file}:${c.line})${c.via ? ` via ${c.via}` : ""}`));
                 return;
             }
             case "search":

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

@@ -0,0 +1,46 @@
+import { shipOnStop } from "../../modules/lawbook/ship.js";
+/**
+ * `speclaw ship-on-stop`: the Claude Code `Stop` hook. Ships the branch's
+ * change when the work changed since the last ship; prints nothing on stdout.
+ * A failing gate goes to stderr with exit 2 so the agent sees it and fixes it
+ * — once: when the hook already blocked this stop (`stop_hook_active`), it
+ * exits 0 so the agent can never loop. Any other failure exits 0.
+ *
+ * @param cwd - Project root (defaults to the process working directory).
+ */
+// Covers: req~ship-on-stop-hook~1
+export async function runShipOnStop(cwd = process.cwd()) {
+    const active = await stopHookActive();
+    try {
+        const out = shipOnStop(cwd);
+        if (out.skipped === null && !out.result.gatesPassed && !active) {
+            const failed = out.result.gates[out.result.gates.length - 1];
+            process.stderr.write(`speclaw: gate failed — ${failed.command} (exit ${failed.exitCode}). Fix it before finishing.\n${failed.tail}\n`);
+            process.exit(2);
+        }
+    }
+    catch {
+        // A hook must never break the session.
+    }
+}
+/** Whether this stop was already blocked by the hook once (`stop_hook_active`). */
+async function stopHookActive() {
+    try {
+        const raw = process.stdin.isTTY ? "" : await readStdin();
+        return raw
+            ? Boolean(JSON.parse(raw).stop_hook_active)
+            : false;
+    }
+    catch {
+        return false;
+    }
+}
+function readStdin() {
+    return new Promise((resolve) => {
+        let data = "";
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (c) => (data += c));
+        process.stdin.on("end", () => resolve(data));
+        setTimeout(() => resolve(data), 1000).unref();
+    });
+}

package/dist/cli/commands/ship.js

@@ -0,0 +1,44 @@
+import { list } from "../lib/args.js";
+import { ui } from "../lib/ui.js";
+import { shipChange } from "../../modules/lawbook/ship.js";
+/**
+ * Fast path for finished work (`speclaw ship <name>`): gates once, a report
+ * from their real output, and the archive at level 0.
+ *
+ * @param flags - `_[0]` is the change name; `--summary`, `--gate`, `--discipline`, `--no-archive`, `--json`.
+ */
+export async function runShip(flags) {
+    const name = flags._[0];
+    if (!name || typeof name !== "string") {
+        ui.err("Usage: speclaw ship <name> [--summary <text>] [--gate <cmd>] [--discipline <name>]");
+        process.exit(1);
+    }
+    const gates = list(flags.gate);
+    const result = shipChange(process.cwd(), name, {
+        summary: typeof flags.summary === "string" ? flags.summary : undefined,
+        gates: gates.length ? gates : undefined,
+        discipline: typeof flags.discipline === "string" ? flags.discipline : undefined,
+        noArchive: Boolean(flags["no-archive"]),
+    });
+    if (flags.json) {
+        console.log(JSON.stringify(result, null, 2));
+    }
+    else {
+        for (const g of result.gates) {
+            const t = `${(g.durationMs / 1000).toFixed(1)} s`;
+            if (g.exitCode === 0)
+                ui.ok(`${g.command} (${t})`);
+            else
+                ui.err(`${g.command} failed, exit ${g.exitCode} (${t})`);
+        }
+        ui.ok(`report ${ui.code(result.report)}`);
+        if (result.archivedTo)
+            ui.ok(`archived to ${result.archivedTo}`);
+        for (const n of result.next)
+            ui.warn(n);
+        const s = (ms) => `${(ms / 1000).toFixed(2)} s`;
+        ui.info(`speclaw overhead ${s(result.timings.overhead)} · gates ${s(result.timings.gates)} · total ${s(result.timings.total)}`);
+    }
+    if (!result.gatesPassed)
+        process.exit(1);
+}

package/dist/cli/commands/update.js

@@ -269,6 +269,31 @@ const MIGRATIONS = [
             "up at the next session start or `compass_index`.\n" +
             "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
     },
+    {
+        version: "2.0.13",
+        describe: "Compass schema 12 — type-reference callers, compact compass_find, unconfirmed bug drafts",
+        agentPrompt: "- Compass is now **schema 12**: the first `speclaw index` after upgrading migrates " +
+            "11→12 and re-extracts every file once (embeddings are reused). Where the project " +
+            'mentions "Schema **11**" or "Compass (schema 11)", change it to schema 12 ' +
+            "(11→12 forces a reindex; embeddings reused).\n" +
+            "- speclaw 2.0.12 or older (including an MCP entry pinned at `@2.0.12` or a stale " +
+            "global CLI) treats a schema-12 index as incompatible and rebuilds it from scratch. " +
+            "Pin every speclaw the project uses (global CLI, `npx`, CI, and the MCP entry) to " +
+            "2.0.13: run `speclaw update` so the pinned MCP entry moves to 2.0.13.\n" +
+            "- `compass_find` now returns one compact JSON document capped as a whole at " +
+            "`maxTokens` (default 1500): hits carry only `name`, `kind`, `file`, `line`; exact mode " +
+            "adds `found`, `terms`, and `nearest` when no symbol has the name; `focusIgnored` lists " +
+            "focus paths that are not indexed; `truncated: true` appears only when it trimmed. " +
+            "`speclaw search --json` keeps its shape. If the project's docs describe the find " +
+            "response fields, update them.\n" +
+            "- `compass_explore` and `speclaw explore` list type references (`ref` edges: " +
+            "annotations, `extends`/`implements`) among callers; every caller carries " +
+            '`via: "call" | "ref"`. Blast radius, affected tests, and ranking are unchanged.\n' +
+            "- Cortex: `pauseForQuestions` is accepted only from stage `planning` (an error " +
+            "elsewhere); `advance`/`rework` re-read the confirmed level; `speclaw lawbook draft " +
+            "--bug` without `--level` leaves the level unconfirmed (validate uses 3).\n" +
+            "- Preserve all project-specific wording; only apply these speclaw-authored changes.",
+    },
 ];
 /**
  * Bring the current project up to date without a full re-init. When the npm

package/dist/cli/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { parseFlags } from "./lib/args.js";
+import { parseFlags, REPEATABLE_FLAGS } from "./lib/args.js";
 import { ui, header } from "./lib/ui.js";
 import { maybeNotifyUpdate } from "./lib/update-check.js";
 import { GLOBAL_HELP as HELP, helpFor, knownCommands, wantsHelp } from "./lib/help.js";
@@ -28,6 +28,7 @@ const HEADER_COMMANDS = new Set([
     "lawbook",
     "cortex",
     "quick",
+    "ship",
 ]);
 /**
  * Print the branded header once, ahead of a command's output, when it is a
@@ -124,6 +125,10 @@ async function dispatch(cmd, flags) {
             return (await import("./commands/visualize.js")).runVisualize(flags);
         case "quick":
             return (await import("./commands/quick.js")).runQuick(flags);
+        case "ship":
+            return (await import("./commands/ship.js")).runShip(flags);
+        case "ship-on-stop":
+            return (await import("./commands/ship-on-stop.js")).runShipOnStop();
         case "cortex":
             return (await import("./commands/cortex.js")).runCortex(flags);
         case "lawbook":
@@ -166,11 +171,11 @@ async function main() {
         process.exitCode = 0;
         return;
     }
-    const flags = parseFlags(rest);
+    const flags = parseFlags(rest, REPEATABLE_FLAGS);
     maybeHeader(cmd, flags);
     await dispatch(cmd, flags);
     // The SessionStart and edit hooks must stay silent: no update notice either.
-    if (cmd === "session-start" || cmd === "reindex-file")
+    if (cmd === "session-start" || cmd === "reindex-file" || cmd === "ship-on-stop")
         return;
     await maybeNotifyUpdate(cmd);
 }

package/dist/cli/lib/args.js

@@ -1,23 +1,37 @@
 /**
- * Minimal flag parser: `--key value`, `--key=value`, `--bool`, `-x`.
+ * Minimal flag parser: `--key value`, `--key=value`, `--bool`, `-x`. A repeated
+ * key keeps its last value unless it is listed in `repeatable`.
  *
  * @param argv - Raw argument tokens (already stripped of the command name).
+ * @param repeatable - Keys whose every value is kept: such a key always yields a
+ *   `string[]` in argv order, and its values are never split at commas.
  * @returns Flags with named options set and non-flag tokens collected in `_`.
  */
-export function parseFlags(argv) {
+export function parseFlags(argv, repeatable = []) {
     const flags = { _: [] };
+    const set = (key, value) => {
+        const prev = flags[key];
+        if (repeatable.includes(key) && (typeof value === "string" || Array.isArray(prev))) {
+            // A bare repeatable flag after real values adds nothing and drops nothing.
+            if (typeof value === "string")
+                flags[key] = Array.isArray(prev) ? [...prev, value] : [value];
+        }
+        else {
+            flags[key] = value;
+        }
+    };
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
         if (arg.startsWith("--")) {
             const [key, inlineVal] = arg.slice(2).split("=", 2);
             if (inlineVal !== undefined) {
-                flags[key] = inlineVal;
+                set(key, inlineVal);
             }
             else if (i + 1 < argv.length && !argv[i + 1].startsWith("-")) {
-                flags[key] = argv[++i];
+                set(key, argv[++i]);
             }
             else {
-                flags[key] = true;
+                set(key, true);
             }
         }
         else if (arg.startsWith("-")) {
@@ -29,6 +43,22 @@ export function parseFlags(argv) {
     }
     return flags;
 }
+/** Flags that may be passed more than once; each occurrence is one value. */
+export const REPEATABLE_FLAGS = ["question"];
+/**
+ * The values of a repeatable flag parsed with {@link REPEATABLE_FLAGS}, as-is:
+ * in argv order and never split at commas.
+ *
+ * @param value - The parsed flag value.
+ * @returns The string values; empty when the flag is absent or a bare boolean.
+ */
+export function repeated(value) {
+    if (Array.isArray(value))
+        return value;
+    if (typeof value === "string")
+        return [value];
+    return [];
+}
 /**
  * Normalize a flag value into a list, splitting comma-separated strings.
  *

package/dist/cli/lib/help.js

@@ -24,6 +24,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)
+  ship-on-stop             Ship the branch's change when work changed (Stop hook)
   reindex-file [paths...]  Silent re-index of edited files (PostToolUse hook; stdin JSON)
   watch                    Keep the index fresh on file changes
   explore <node>           A node's source + callers/callees
@@ -41,6 +42,7 @@ Cortex (One brain. Many agents. — multi-agent loop)
   cortex <op>              status|start|advance|rework|brief — drive harness.json (--change)
 
 Lawbook (spec-driven workflow)
+  ship <name>              Fast path: gates once → report → archive (level 0)
   quick <name>             Scaffold a level-0 change (record.md + reports)
   lawbook init             Create the lawbook/ workspace
   lawbook list             Active/archived changes and capabilities
@@ -164,6 +166,15 @@ Options
         usage: `Usage: speclaw watch
 
 Keep the Compass index fresh: re-index changed files until interrupted (Ctrl-C).
+`,
+    },
+    {
+        name: "ship-on-stop",
+        usage: `Usage: speclaw ship-on-stop
+
+The Claude Code Stop hook. On a feature branch whose work changed since the
+last ship, runs \`speclaw ship\` for the change named after the branch. Prints
+nothing on stdout; a failing gate goes to stderr with exit 2 once.
 `,
     },
     {
@@ -196,7 +207,9 @@ speclaw index, compass_index, watch). Prints nothing and always exits 0.
         name: "explore",
         usage: `Usage: speclaw explore <node> [options]
 
-A symbol's source plus its callers and callees.
+A symbol's source plus its callers and callees. Each caller carries
+via: call (it calls the symbol) or ref (it names the type in an annotation
+or an extends/implements clause).
 
 Options
   --json               Print the result as JSON
@@ -307,6 +320,23 @@ Options
   --depth <n>          Neighborhood depth around <node>
   --limit <n>          Maximum nodes
   --no-open            Do not open the browser
+`,
+    },
+    {
+        name: "ship",
+        usage: `Usage: speclaw ship <name> [options]
+
+Fast path for finished work: scaffold a level-0 record if the change is new,
+run the project's gates once, write reports/<discipline>.md from their real
+output, and archive at level 0. Level 1+ stops after the evidence: review
+happens on the PR. Ship never records a review verdict.
+
+Options
+  --summary <text>     What changed (default: the changed-file list)
+  --gate <cmd>         Gate command (repeatable; default ship.gates or package.json)
+  --discipline <name>  Report name (default ship.discipline or "change")
+  --no-archive         Stop after the report
+  --json               Print the result as JSON
 `,
     },
     {
@@ -331,8 +361,9 @@ Options
   --change <name>      The change (or pass it as the second argument)
   --verdict <v>        PASS or FAIL (advance from reviewing/testing)
   --note <text>        A history note
-  --question <text>    An open question (repeatable)
-  --pause-questions    Pause the loop for open questions
+  --question <text>    One open question, commas included; repeat for more
+  --pause-questions    From planning only: pause for the --question list
+                       (any other stage is rejected, exit 1)
   --json               Print the result as JSON
 `,
     },
@@ -344,7 +375,8 @@ Options
   list                         Active/archived changes and capabilities
   level <mode> [change]        propose|set|promote|explain ceremony level (--level, --reason)
   draft <name>                 Scaffold a feature change (--level N, --capability C)
-  draft --bug <name>           Scaffold a bug change (bugfix.md + reports)
+  draft --bug <name>           Scaffold a bug change (bugfix.md + reports;
+                               level unconfirmed unless --level N)
   investigate                  Rank bug suspects (--symptom, --stack-trace, --symbol, --path)
   validate <change>            Validate a change's artifacts
   sync <change>                Promote delta specs to canonical

package/dist/modules/compass/db.js

@@ -234,7 +234,7 @@ export function probeFts5Support() {
     }
 }
 /** Schema version stamped into the `meta` table on first creation. */
-export const SCHEMA_VERSION = "11";
+export const SCHEMA_VERSION = "12";
 /**
  * `nodes.kind` of the synthetic per-file owner node. It owns the references that
  * sit outside any definition (top-level imports, calls in callbacks) and is
@@ -253,7 +253,7 @@ function readSchemaVersion(db) {
 }
 /**
  * Decide whether an existing database is from an incompatible schema and must be
- * rebuilt. Schema 8→9, 9→10, and 10→11 are handled by migrators instead of a wipe.
+ * rebuilt. Schema 8→9, 9→10, 10→11, and 11→12 are handled by migrators instead of a wipe.
  */
 function isStale(db) {
     const hasEdges = db
@@ -262,10 +262,8 @@ function isStale(db) {
     if (!hasEdges)
         return false;
     const ver = readSchemaVersion(db);
-    if (ver === "8" || ver === "9" || ver === "10")
+    if (ver === "8" || ver === "9" || ver === "10" || ver === "11")
         return false; // migrate in openDb
-    if (ver === "11" && !hasEdgeSpec(db))
-        return false; // pre-release 11: migrate in openDb
     if (ver !== SCHEMA_VERSION)
         return true;
     const edgeCols = db.prepare("PRAGMA table_info(edges)").all().map((c) => c.name);
@@ -469,12 +467,49 @@ export function migrate10to11(db) {
         throw new Error(`schema 10→11 migration failed — delete .speclaw/index.db to rebuild: ${err.message}`, { cause: err });
     }
 }
+/** Reason recorded with the needs-reindex marker by the 11→12 migration. */
+export const SCHEMA_12_REINDEX_REASON = "schema 12 adds type-reference (ref) edges for explore callers; reindex required";
+/**
+ * Migrate schema 11 → 12: set the needs-reindex marker (its reason names
+ * schema 12, after any reason an earlier step of the same chain recorded) and
+ * stamp `"12"`, in one `BEGIN IMMEDIATE` transaction. No column changes
+ * (`edges.kind` is text); the next index run re-extracts every file so `ref`
+ * edges exist, while `embedding_cache` is untouched so unchanged symbols reuse
+ * their vectors.
+ *
+ * @param db - Open connection already at schema 11 (with `edges.spec`).
+ * @throws If any step fails; the transaction is rolled back and the stamp stays `"11"`.
+ */
+export function migrate11to12(db) {
+    // Covers: req~schema-ref-edges~1
+    db.exec("BEGIN IMMEDIATE");
+    try {
+        const pending = db.prepare("SELECT value FROM meta WHERE key = 'needs_reindex'").get();
+        const prior = db.prepare("SELECT value FROM meta WHERE key = 'reindex_reason'").get();
+        const reason = pending?.value === "1" && prior?.value && prior.value !== SCHEMA_12_REINDEX_REASON
+            ? `${prior.value}; ${SCHEMA_12_REINDEX_REASON}`
+            : SCHEMA_12_REINDEX_REASON;
+        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(reason);
+        db.prepare("INSERT INTO meta(key, value) VALUES ('schema_version', ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value").run("12");
+        db.exec("COMMIT");
+    }
+    catch (err) {
+        try {
+            db.exec("ROLLBACK");
+        }
+        catch {
+            /* already rolled back */
+        }
+        throw new Error(`schema 11→12 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. Schema 8→9, 9→10, and 10→11 migrate in place
- * and chain forward (embeddings preserved). Other incompatible schemas are wiped
+ * keys, and applies the schema. Schema 8→9, 9→10, 10→11, and 11→12 migrate in
+ * place and chain forward (embeddings preserved). Other incompatible schemas are wiped
  * and rebuilt.
  *
  * @param projectPath - Absolute path to the project root.
@@ -494,13 +529,16 @@ export function openDb(projectPath) {
             return null;
         }
     })();
-    if (ver === "8" || ver === "9" || ver === "10" || (ver === "11" && !hasEdgeSpec(db))) {
+    if (ver === "8" || ver === "9" || ver === "10" || ver === "11") {
         try {
             if (ver === "8")
                 migrate8to9(db, projectPath);
             if (ver === "8" || ver === "9")
                 migrate9to10(db);
-            migrate10to11(db);
+            // A pre-release schema-11 index (no `edges.spec`) takes the 10→11 step too.
+            if (ver !== "11" || !hasEdgeSpec(db))
+                migrate10to11(db);
+            migrate11to12(db);
         }
         catch (err) {
             db.close();

package/dist/modules/compass/explore-rich.js

@@ -1,9 +1,9 @@
 import { explore, impact, trace } from "./query.js";
 import { affectedTests } from "./affected.js";
-import { FILE_NODE_KIND } from "./db.js";
+import { FILE_NODE_KIND, indexExists, openDb } from "./db.js";
 import { hotspots } from "./hotspots.js";
 import { summarizeImpact } from "./impact-summary.js";
-import { budgetExploreShape, applyTextBudget, } from "../../shared/output-budget.js";
+import { budgetExploreShape, applyTextBudget, OUTPUT_BUDGET, } from "../../shared/output-budget.js";
 const DEFAULT_INCLUDES = [
     "source",
     "callers",
@@ -28,7 +28,7 @@ export async function exploreRich(query) {
     const degraded = [];
     if (query.to) {
         const pathResult = trace(query.projectPath, query.node, query.to, query.maxDepth ?? 8);
-        const base = explore(query.projectPath, query.node);
+        const base = explore(query.projectPath, query.node, { includeRefs: true });
         const out = {
             ...base,
             path: pathResult.path,
@@ -49,7 +49,7 @@ export async function exploreRich(query) {
         budgetExploreShape(out, mode, truncated);
         return out;
     }
-    const base = explore(query.projectPath, query.node);
+    const base = explore(query.projectPath, query.node, { includeRefs: true });
     const out = { ...base, truncated, degraded };
     if (!includes.includes("source") && out.symbol)
         out.symbol = withoutSource(out.symbol);
@@ -123,16 +123,57 @@ export async function exploreRich(query) {
         delete out.degraded;
     return out;
 }
-/** Merge lexical and semantic search behind one surface. */
+/**
+ * Merge lexical and semantic search behind one surface (the MCP find path).
+ * The focus is resolved against the index first so dropped paths can be
+ * reported; exact mode keeps only symbols named exactly a query term and
+ * reports `found`, `terms`, and, when nothing matches, `nearest`.
+ *
+ * @param projectPath - Indexed project root.
+ * @param query - Identifier(s) or prose.
+ * @param mode - `exact` (name lookup) or `concept` (fuzzy, dense-heavy).
+ * @param limit - Seed limit (default 50).
+ * @param opts - Focus paths and the response token cap (default: brief ceiling).
+ */
+// Covers: req~find-exact-not-found~1, req~task-relative-ranking~1
 export async function findSymbols(projectPath, query, mode, limit, opts) {
-    const { hybridSearch } = await import("./hybrid.js");
+    const { hybridSearch, resolveSearchFocus, exactTerms, nearestSymbols } = await import("./hybrid.js");
+    if (!indexExists(projectPath)) {
+        throw new Error("No index found. Build it first with the index_build tool (creates .speclaw/index.db).");
+    }
+    const db = openDb(projectPath);
+    let resolvedFocus;
+    try {
+        resolvedFocus = resolveSearchFocus(db, projectPath, opts?.focus);
+    }
+    finally {
+        db.close();
+    }
+    const cap = opts?.maxTokens ?? OUTPUT_BUDGET.brief;
+    const terms = mode === "exact" ? exactTerms(query) : undefined;
+    const report = { ranked: 0, knnIds: [] };
     const result = await hybridSearch(projectPath, query, {
         mode,
-        focus: opts?.focus,
-        maxTokens: opts?.maxTokens,
+        maxTokens: cap,
         seedLimit: limit ?? 50,
+        resolvedFocus,
+        exactNames: terms,
+        report,
     });
-    return result;
+    const out = {
+        ...result,
+        mode,
+        focusIgnored: resolvedFocus.ignored,
+        cap,
+        capped: report.ranked > result.hits.length,
+    };
+    if (terms) {
+        out.terms = terms;
+        out.found = result.hits.length > 0;
+        if (!out.found)
+            out.nearest = nearestSymbols(projectPath, terms, report.knnIds);
+    }
+    return out;
 }
 /** Serialize explore-rich with output budget applied. */
 export function formatExploreRich(result, mode = "brief") {