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

@davesheffer/hunch 0.24.0 → 0.25.0

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 (7) hide show

package/README.md CHANGED Viewed

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

@@ -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";
@@ -454,6 +455,56 @@ program
     }
     store.close();
 });
+// ---- 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) => {
+    const { store, root } = storeFor();
+    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 CHANGED Viewed

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

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

@@ -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/store/hunchStore.js CHANGED Viewed

@@ -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();

package/package.json CHANGED Viewed

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