npm - @davesheffer/hunch - Versions diffs - 0.25.0 → 0.26.1 - Mend

@davesheffer/hunch 0.25.0 → 0.26.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (6) hide show

package/dist/cli/index.js +28 -6
package/dist/eval/harness.js +6 -1
package/dist/integrations/claudemd.js +3 -2
package/dist/mcp/server.js +19 -0
package/dist/store/hunchStore.js +48 -2
package/package.json +1 -1

package/dist/cli/index.js CHANGED Viewed

@@ -419,6 +419,7 @@ program
     .requiredOption("--file <path>", "golden set JSON: [{ query, expected: [refs], note? }]")
     .option("--k <n>", "top-k cutoff", "10")
     .option("--semantic", "also blend the semantic stream (requires `hunch embed`; default is deterministic FTS + graph)")
+    .option("--kind <kind>", "restrict scoring to one record kind (e.g. runbooks) — scoped retrieval")
     .action(async (opts) => {
     const { store } = storeFor();
     store.reindex(); // reflect any out-of-band JSON edits before scoring
@@ -438,7 +439,7 @@ program
     // Default is deterministic (FTS + graph, no model). --semantic only adds the
     // semantic leg when embeddings actually exist; otherwise it's still FTS + graph.
     const embedder = opts.semantic ? await selectEmbedder() : undefined;
-    const lift = await evaluateGraphLift(store, cases, { k, embedder });
+    const lift = await evaluateGraphLift(store, cases, { k, embedder, kind: opts.kind });
     const pct = (x) => `${(x * 100).toFixed(1)}%`;
     const dpt = (x) => `${x >= 0 ? "+" : ""}${(x * 100).toFixed(1)}pt`;
     const dnum = (x) => `${x >= 0 ? "+" : ""}${x.toFixed(3)}`;
@@ -458,12 +459,33 @@ program
 // ---- runbook (distill reusable "how" from a commit range; roadmap #5) ------
 program
     .command("runbook")
-    .description("Distill a reusable runbook (the 'how' of a recurring task) from a commit range. Advisory; refine before relying on it.")
-    .argument("<range>", "commit range: <base>..<head>, or <base> (→ <base>..HEAD)")
-    .requiredOption("--task <task>", "the recurring task this runbook answers")
-    .option("--private", "write into the private overlay (HUNCH_PRIVATE_DIR), not the committed repo")
-    .action((range, opts) => {
+    .description("Capture a runbook (the 'how' of a recurring task) from a commit range, or --find one. Advisory.")
+    .argument("[range]", "commit range for capture: <base>..<head>, or <base> (→ <base>..HEAD)")
+    .option("--task <task>", "the recurring task this runbook answers (capture mode)")
+    .option("--find <query>", "look up the runbooks that best match a task/intent (scoped retrieval)")
+    .option("--semantic", "use semantic retrieval for --find (requires `hunch embed`)")
+    .option("--private", "capture into the private overlay (HUNCH_PRIVATE_DIR), not the committed repo")
+    .action(async (range, opts) => {
     const { store, root } = storeFor();
+    // Lookup mode: scoped runbook retrieval (search within runbooks, not the whole graph).
+    if (opts.find) {
+        const emb = opts.semantic ? await selectEmbedder() : undefined;
+        const hits = await store.searchRunbooks(opts.find, 5, { embedder: emb });
+        if (!hits.length)
+            console.log(`No runbook matches "${opts.find}".`);
+        else {
+            console.log(`Runbooks for "${opts.find}":\n`);
+            for (const h of hits)
+                console.log(`• ${h.ref} — ${h.title}\n    ${h.snippet}`);
+        }
+        store.close();
+        return;
+    }
+    // Capture mode.
+    if (!range || !opts.task) {
+        store.close();
+        return fail("capture needs a <range> and --task (or use --find <query> to look up)");
+    }
     if (opts.private && !store.hasPrivate) {
         store.close();
         return fail("--private needs HUNCH_PRIVATE_DIR set to a private store");

package/dist/eval/harness.js CHANGED Viewed

@@ -3,7 +3,12 @@ export async function evaluateRetrieval(store, cases, opts = {}) {
     const k = opts.k ?? 10;
     const perCase = [];
     for (const c of cases) {
-        const hits = await store.hybridSearch(c.query, k, { embedder: opts.embedder, graphWeight: opts.graphWeight });
+        // A kind-scoped eval uses true scoped retrieval (candidate pool restricted to the
+        // kind from the start), not a whole-corpus fetch + filter — the latter's top-50 cap
+        // buries terse records before any filter.
+        const hits = opts.kind
+            ? await store.searchScoped(c.query, opts.kind, k, { embedder: opts.embedder })
+            : await store.hybridSearch(c.query, k, { embedder: opts.embedder, graphWeight: opts.graphWeight });
         const top = hits.slice(0, k).map((h) => h.ref);
         const expected = new Set(c.expected);
         let found = 0;

package/dist/integrations/claudemd.js CHANGED Viewed

@@ -30,8 +30,9 @@ export function renderHunchSection(store) {
     lines.push("- `hunch_why(target)` — why a file/symbol is shaped this way (decisions, bugs, constraints).");
     lines.push("- `hunch_check_constraints(scope)` — invariants you must not break. **Always run before editing.**");
     lines.push("- `hunch_get_dependents(symbol)` — blast radius before a change.");
-    lines.push("- `hunch_bug_lineage(symptom)` — has this bug happened before? what was the root cause?");
-    lines.push("- `hunch_query(question)` — free-text search across all of Hunch.");
+    lines.push("- `hunch_bug_lineage(symptom_or_symbol)` — has this bug happened before? what was the root cause?");
+    lines.push("- `hunch_query(query)` — free-text search across all of Hunch.");
+    lines.push("- `hunch_runbook(task)` — the proven steps for a recurring task (e.g. \"add an MCP tool\", \"cut a release\").");
     lines.push("- `hunch_record_decision(...)` — write back a decision after a non-trivial choice.");
     if (constraints.length) {
         lines.push("");

package/dist/mcp/server.js CHANGED Viewed

@@ -77,6 +77,25 @@ export function buildServer(root) {
         });
         return ok(`Top matches for "${query}":\n\n${lines.join("\n")}`);
     });
+    // -- hunch_runbook --------------------------------------------------------
+    server.registerTool("hunch_runbook", {
+        title: "Find a runbook for a task",
+        description: "Look up the proven 'how-to' (ordered steps + files) for a recurring task — runbook-SCOPED retrieval (searches within runbooks, not the whole graph). Use at the START of a task to reuse a known procedure instead of re-deriving it. Advisory.",
+        inputSchema: { task: z.string().describe("The task/intent, e.g. 'add an MCP tool' or 'cut a release'.") },
+    }, async ({ task }) => {
+        const hits = await store.searchRunbooks(task, 5, { embedder: await embedderReady });
+        if (!hits.length)
+            return ok(`No runbook for "${task}" yet. Capture one with: hunch runbook <base>..<head> --task "${task}"`);
+        const lines = hits.map((h) => {
+            const r = store.resolve(h.ref)?.record;
+            if (!r)
+                return `• ${h.ref} — ${h.title}`;
+            const steps = r.steps.length ? `\n    steps: ${r.steps.map((s, i) => `${i + 1}. ${s}`).join("  ")}` : "";
+            const files = r.files.length ? `\n    files: ${r.files.slice(0, 8).join(", ")}` : "";
+            return `• ${r.id} — ${r.task}${steps}${files}${provLine(r)}`;
+        });
+        return ok(`Runbooks for "${task}" (advisory — a proven 'how', refine to fit):\n\n${lines.join("\n\n")}`);
+    });
     // -- hunch_why ------------------------------------------------------------
     server.registerTool("hunch_why", {
         title: "Explain why a file/symbol is the way it is",

package/dist/store/hunchStore.js CHANGED Viewed

@@ -333,14 +333,60 @@ export class HunchStore {
             return fts.slice(0, limit);
         return this.rrfFuse(fts, sem, graph, limit, gw);
     }
+    /** Runbook-scoped retrieval (roadmap #5): the same FTS+graph(+semantic) fusion,
+     *  restricted to the `runbooks` kind — so a "what's the procedure for X" query
+     *  competes only with other runbooks, not the whole graph. Measurement showed
+     *  whole-corpus retrieval buries terse runbooks (33% recall); scoping + semantic
+     *  lifted recall@5 to 83% (dec_1239efae54 follow-up). Pass an embedder for the
+     *  semantic leg; omit for keyword+graph. */
+    async searchRunbooks(query, limit = 5, opts = {}) {
+        return this.searchScoped(query, "runbooks", limit, opts);
+    }
+    /** Kind-SCOPED retrieval: FTS + (optional) semantic fused, but the candidate pool is
+     *  restricted to one record kind from the START — not over-fetched from a whole-corpus
+     *  ranking (whose top-50 cap can bury a terse record before any filter). This is what
+     *  lifted runbook recall@5 from 33% → 83% in the measurement (dec_1239efae54 follow-up). */
+    async searchScoped(query, kind, limit = 5, opts = {}) {
+        const fts = this.scopedFts(query, kind, Math.max(limit, 20));
+        const embedder = opts.embedder !== undefined ? opts.embedder : await selectEmbedder();
+        let sem = [];
+        if (embedder && this.semanticReady(embedder)) {
+            try {
+                const [qvec] = await embedder.embed([query]);
+                if (qvec)
+                    sem = this.cosineRank(qvec, embedder.id, Math.max(limit, 20), kind);
+            }
+            catch {
+                sem = [];
+            }
+        }
+        if (!sem.length)
+            return fts.slice(0, limit);
+        return this.rrfFuse(fts, sem, [], limit);
+    }
+    /** FTS bm25 over a single kind (the `kind` column is UNINDEXED, so a plain `=`
+     *  constraint composes with MATCH). Empty when the query has no FTS-able terms. */
+    scopedFts(query, kind, limit) {
+        const match = toFtsQuery(query);
+        if (!match)
+            return [];
+        try {
+            const rows = this.db.prepare(`SELECT ref, kind, title, snippet(search, 3, '[', ']', '…', 12) AS snip, bm25(search) AS score
+         FROM search WHERE search MATCH ? AND kind = ? ORDER BY score LIMIT ?`).all(match, kind, limit);
+            return rows.map((r) => ({ ref: r.ref, kind: r.kind, title: r.title, snippet: r.snip, score: r.score }));
+        }
+        catch {
+            return [];
+        }
+    }
     /** Brute-force exact cosine top-n over stored vectors for one model. Vectors are
      *  pre-normalized, so cosine == dot product. Scoped to `dim = qvec.length` so a
      *  row stored at a different dimension (model id reused at a new dim) can never
      *  drive an out-of-bounds BLOB read; any with an unexpected byte length are
      *  skipped defensively rather than crashing the query. */
-    cosineRank(qvec, model, n) {
+    cosineRank(qvec, model, n, kind) {
         const dim = qvec.length;
-        const rows = this.db.prepare(`SELECT ref, kind, vec FROM embeddings WHERE model = ? AND dim = ?`).all(model, dim);
+        const rows = this.db.prepare(`SELECT ref, kind, vec FROM embeddings WHERE model = ? AND dim = ?${kind ? " AND kind = ?" : ""}`).all(...(kind ? [model, dim, kind] : [model, dim]));
         const scored = [];
         for (const r of rows) {
             if (r.vec.byteLength !== dim * 4)

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "0.25.0",
+  "version": "0.26.1",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
   "description": "Hunch — an Engineering Memory OS: a persistent, git-native reasoning graph over a codebase, exposed to Claude Code via MCP.",