@davesheffer/hunch 0.24.0 → 0.26.0

package/README.md

@@ -66,6 +66,24 @@ came before. Local-first, no documentation toil, no SaaS.
 [provenance](https://hunch-pi.vercel.app/docs#provenance) ·
 [time-travel](https://hunch-pi.vercel.app/docs#time-travel)
 
+## Why Hunch is different
+
+"Memory for coding agents" is getting crowded, but most of it is a *server-side, ephemeral,
+single-vendor* RAG cache over your current code. Hunch is the opposite on every axis — and that
+combination is the moat:
+
+| | Typical agent memory | **Hunch** |
+|---|---|---|
+| **Storage** | server-side / a vendor's cloud | **git-tracked JSON in your repo** — diff it, review it in PRs, sync it over `git push` |
+| **Lifetime** | the session; often auto-expiring | the **lifetime of the codebase** — non-destructive supersede/veto keeps the *why-it-changed* trail |
+| **Clients** | one vendor's agent | **client-agnostic** — one `.hunch/` graph serves Claude Code, Cursor, Copilot & Windsurf via MCP |
+| **What's stored** | opaque extracted "facts" | **structured ADRs** — decisions with rejected-alternatives, bug lineage, and invariants |
+| **Enforcement** | advisory / just-in-time hints | **fail-closed deterministic guards** — no model in the block path; a commit fails on a human-vouched, set-intersection match |
+| **Trust** | take it on faith | **provenance on every record** (source + confidence + evidence) and a measurable retrieval signal (`hunch eval`) |
+
+The short version: **git tracks *what* changed; Hunch tracks *why*** — locally, durably, and under
+your control, with guards that actually hold the line instead of just suggesting.
+
 ## Getting started
 
 ```bash

package/dist/cli/index.js

@@ -28,7 +28,8 @@ import { indexRepo } from "../extractors/indexer.js";
 import { syncCommit, recordFailure, captureTestRun } from "../synthesis/synthesize.js";
 import { parseTestReport } from "../extractors/testreport.js";
 import { selectProvider } from "../synthesis/provider.js";
-import { isGitRepo, headSha, logSince, lastChangeDate, stagedFiles, commitFiles, asOfDate, stagedDiff, commitDiff, rangeFiles, rangeDiff, revExists, commitAndPushHunch, gitUntrackCached } from "../extractors/git.js";
+import { isGitRepo, headSha, logSince, lastChangeDate, stagedFiles, commitFiles, asOfDate, stagedDiff, commitDiff, rangeFiles, rangeDiff, rangeSubjects, revExists, commitAndPushHunch, gitUntrackCached } from "../extractors/git.js";
+import { runbookId } from "../core/ids.js";
 import { renderText, renderMarkdown, reportFailsStrict } from "../core/checkreport.js";
 import { partitionReview, READY_MIN_GROUNDED } from "../core/reviewqueue.js";
 import { installPostCommitHook, installPreCommitHook } from "../integrations/hooks.js";
@@ -418,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
@@ -437,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)}`;
@@ -454,6 +456,77 @@ program
     }
     store.close();
 });
+// ---- runbook (distill reusable "how" from a commit range; roadmap #5) ------
+program
+    .command("runbook")
+    .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");
+    }
+    const [base, head = "HEAD"] = range.split("..");
+    if (!base || !revExists(base, root)) {
+        store.close();
+        return fail(`base ref "${base ?? ""}" not found (range: ${range})`);
+    }
+    const steps = rangeSubjects(base, root, head);
+    const files = rangeFiles(base, root, head);
+    if (!steps.length && !files.length) {
+        store.close();
+        return fail(`no commits or changes in range ${range}`);
+    }
+    const now = new Date().toISOString();
+    const rec = {
+        id: runbookId(opts.task),
+        task: opts.task,
+        trigger: [opts.task],
+        steps, // already oldest-first (chronological procedure)
+        files,
+        gotchas: [],
+        outcome: "",
+        source_range: range,
+        valid_from: now,
+        valid_to: null,
+        // Deterministic draft (commit subjects + changed files); advisory, low-confidence.
+        // Refine steps/gotchas by hand. LLM enrichment is a later tier.
+        provenance: { source: "extracted", confidence: 0.5, evidence: [range] },
+        date: now,
+    };
+    if (opts.private)
+        store.putPrivate("runbooks", rec);
+    else
+        store.json.put("runbooks", rec);
+    store.reindex();
+    console.log(`✓ runbook ${rec.id} — "${rec.task}"  (${rec.steps.length} steps, ${rec.files.length} files)${opts.private ? " [private overlay]" : ""}`);
+    console.log(dim("  advisory, deterministic draft — refine the steps/gotchas; surfaced via `hunch query` and MCP."));
+    store.close();
+});
 // ---- embed (opt-in semantic search) ---------------------------------------
 program
     .command("embed")

package/dist/core/ids.js

@@ -32,6 +32,11 @@ export function decisionId(seed) {
 export function bugId(seed) {
     return "bug_" + shortHash(seed);
 }
+/** Runbook id seeded by its task; trim + lowercase so re-capturing the same task
+ *  is idempotent rather than minting a duplicate. */
+export function runbookId(seed) {
+    return "rb_" + shortHash(seed.trim().toLowerCase());
+}
 /** Constraint id seeded by its statement. Trim + lowercase so trivial
  *  whitespace/case variants of the same rule collapse to one id (idempotent
  *  re-capture), instead of minting a duplicate constraint. */

package/dist/core/types.js

@@ -163,8 +163,25 @@ export const ConstraintSchema = z.object({
     valid_to: z.string().nullable().default(null).describe("ISO instant it was retired (null = active)"),
     provenance: ProvenanceSchema,
 });
-/** The six entity collections, keyed by their on-disk directory name. */
-export const ENTITY_KINDS = ["components", "edges", "symbols", "decisions", "bugs", "constraints"];
+/** A reusable "how" for a recurring task — trajectory/runbook memory (roadmap #5).
+ *  ADVISORY retrieval context only; never enters any block path. Distilled from a
+ *  commit range, surfaced through the same FTS+graph retrieval as every record. */
+export const RunbookSchema = z.object({
+    id: z.string().describe("rb_*"),
+    task: z.string().describe("the recurring task this answers"),
+    trigger: z.array(z.string()).default([]).describe("phrases/intents that should surface it"),
+    steps: z.array(z.string()).default([]).describe("ordered procedure"),
+    files: z.array(z.string()).default([]).describe("canonical files the task touches (drift-checkable)"),
+    gotchas: z.array(z.string()).default([]),
+    outcome: z.string().default("").describe("what 'done' looks like"),
+    source_range: z.string().nullable().default(null).describe("the commit range it was distilled from"),
+    valid_from: z.string().optional(),
+    valid_to: z.string().nullable().default(null),
+    provenance: ProvenanceSchema,
+    date: z.string(),
+});
+/** The entity collections, keyed by their on-disk directory name. */
+export const ENTITY_KINDS = ["components", "edges", "symbols", "decisions", "bugs", "constraints", "runbooks"];
 export const SCHEMAS = {
     components: ComponentSchema,
     edges: EdgeSchema,
@@ -172,6 +189,7 @@ export const SCHEMAS = {
     decisions: DecisionSchema,
     bugs: BugSchema,
     constraints: ConstraintSchema,
+    runbooks: RunbookSchema,
 };
 /** Default provenance helper for deterministic (extracted) records. */
 export function extracted(confidence, evidence = []) {

package/dist/eval/harness.js

@@ -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/extractors/git.js

@@ -194,6 +194,12 @@ export function rangeFiles(base, cwd, head = "HEAD") {
     const out = gitSafe(["diff", "--name-only", "--diff-filter=ACMR", `${base}...${head}`], cwd);
     return out ? out.split("\n").filter(Boolean) : [];
 }
+/** Commit subjects on `head` since `base` (2-dot: commits added by the task),
+ *  oldest-first, for distilling a runbook's ordered steps (roadmap #5). */
+export function rangeSubjects(base, cwd, head = "HEAD", max = 50) {
+    const out = gitSafe(["log", "--reverse", `-n${max}`, "--format=%s", `${base}..${head}`], cwd);
+    return out ? out.split("\n").filter(Boolean) : [];
+}
 /** The PR's unified diff vs `base` (3-dot), for the Regression Guard's structural
  *  analysis. Same noise-exclusion + truncation budget as commit/staged diffs. */
 export function rangeDiff(base, cwd, head = "HEAD", maxBytes = 60_000) {

package/dist/mcp/server.js

@@ -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

@@ -179,6 +179,13 @@ export class HunchStore {
                 fts(c.id, "constraints", c.statement, `${c.rationale} ${c.scope.join(" ")}`);
             }
             counts.constraints = cons.length;
+            // Runbooks (roadmap #5): advisory "how" records — no dedicated SQL table, they
+            // ride the unified `search` FTS so they retrieve through the same FTS+graph path.
+            const runbooks = this.recs("runbooks");
+            for (const r of runbooks) {
+                fts(r.id, "runbooks", r.task, `${r.trigger.join(" ")} ${r.steps.join(" ")} ${r.gotchas.join(" ")} ${r.outcome} ${r.files.join(" ")}`);
+            }
+            counts.runbooks = runbooks.length;
             void j;
         });
         tx();
@@ -326,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

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "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.",