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

@davesheffer/hunch 0.23.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 (8) 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";
@@ -43,6 +44,7 @@ import { formatContext } from "../core/format.js";
 import { readConfig, writeConfig, FIRMNESS_LEVELS, isFirmness } from "../core/config.js";
 import { blockingInScope, vetoInScope, proposedEditLines } from "../core/hookpolicy.js";
 import { loadGoldenSet, evaluateGraphLift } from "../eval/harness.js";
+import { computeDrift } from "../core/drift.js";
 import { draftTripwires, knownRepoDeps } from "../synthesis/tripwires.js";
 import { constraintId } from "../core/ids.js";
 import { readManifest, writeManifest, SCHEMA_VERSION } from "../core/migrate.js";
@@ -453,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")
@@ -1273,6 +1325,20 @@ program
     }
     // Windows: detect/heal the Claude Code ~/.claude.json drive-letter case-split
     // that silently hides the hunch_* MCP tools. No-op (silent) off Windows.
+    // Memory drift: deterministic, advisory smoke detector for memory that has
+    // fallen out of sync with the code/docs (dead file refs, dangling supersedes,
+    // docs still marked "proposed"). Never blocks; never auto-fixes.
+    const drift = computeDrift(store, root);
+    if (drift.findings.length) {
+        console.log(`drift:      ⚠ ${drift.findings.length} finding(s) — memory may be out of sync with the code:`);
+        for (const f of drift.findings.slice(0, 20))
+            console.log(`              · [${f.kind}] ${f.id} — ${f.detail}`);
+        if (drift.findings.length > 20)
+            console.log(dim(`              … and ${drift.findings.length - 20} more`));
+    }
+    else {
+        console.log(`drift:      ✓ no stale refs, dangling supersedes, or stale "proposed" docs`);
+    }
     reportClaudeConfigHeal();
     store.close();
 });

package/dist/core/drift.js ADDED Viewed

@@ -0,0 +1,98 @@
+/**
+ * Memory drift checks (roadmap #7, dec_2a53072620). Deterministic, model-free
+ * comparisons of the curated graph against the actual code/docs — a smoke detector
+ * for stale memory, NOT a robot that rewrites it. Advisory only: `hunch doctor`
+ * prints findings; nothing blocks and nothing is auto-fixed. Each check maps to drift
+ * observed in practice:
+ *   - dead-ref:   an in-force decision points at a file that no longer exists.
+ *   - supersede:  A claims to supersede B, but B was never properly closed.
+ *   - doc-stale:  a doc marked "proposed / not yet implemented" references shipped code.
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join, extname } from "node:path";
+const STALE_MARKER = /\b(proposed|not yet implemented|no code yet)\b/i;
+const SRC_REF = /\bsrc\/[A-Za-z0-9_\-/]+\.ts\b/g;
+export function computeDrift(store, root) {
+    const findings = [];
+    const decisions = store.recs("decisions");
+    const byId = new Map(decisions.map((d) => [d.id, d]));
+    for (const d of decisions) {
+        // 1. DEAD-REFERENCE — only for in-force decisions; a superseded one referencing
+        //    a since-deleted file is legitimate history, not drift.
+        const inForce = d.status !== "superseded" && !d.superseded_by;
+        if (inForce) {
+            for (const f of d.related_files ?? []) {
+                if (!f || f.includes("*"))
+                    continue; // skip globs / empties
+                if (!existsSync(join(root, f))) {
+                    findings.push({ kind: "dead-ref", id: d.id, detail: `references missing file "${f}"` });
+                }
+            }
+        }
+        // 2. SUPERSEDE-INTEGRITY — a contradiction class: A.supersedes = B, but B is
+        //    either gone or still in force (the private-supersede bug shape).
+        if (d.supersedes) {
+            const target = byId.get(d.supersedes);
+            if (!target) {
+                findings.push({ kind: "supersede", id: d.id, detail: `supersedes "${d.supersedes}", which does not exist` });
+            }
+            else if (target.status !== "superseded" || target.superseded_by !== d.id) {
+                findings.push({
+                    kind: "supersede",
+                    id: d.id,
+                    detail: `supersedes "${d.supersedes}", but it is still in force (status=${target.status}, superseded_by=${target.superseded_by ?? "null"})`,
+                });
+            }
+        }
+    }
+    // 3. DOC-STALE — a doc that still advertises "proposed / not implemented" while
+    //    referencing code that exists. Heuristic + advisory; scoped to the repo's own
+    //    markdown (node_modules and sub-projects skipped).
+    for (const doc of markdownDocs(root)) {
+        const text = safeRead(doc.path);
+        if (!STALE_MARKER.test(text.slice(0, 1500)))
+            continue;
+        const existing = (text.match(SRC_REF) ?? []).find((r) => existsSync(join(root, r)));
+        if (existing) {
+            findings.push({ kind: "doc-stale", id: doc.rel, detail: `marked proposed/not-implemented but references shipped code (${existing})` });
+        }
+    }
+    return { findings };
+}
+function safeRead(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return "";
+    }
+}
+const SKIP_DIRS = new Set(["node_modules", ".git", ".hunch", ".hunch-private", "dist", "vscode-extension", "site"]);
+/** Bounded walk for repo markdown (root + docs/, depth-limited; heavy/irrelevant trees skipped). */
+function markdownDocs(root) {
+    const out = [];
+    const walk = (dir, rel, depth) => {
+        if (depth > 4)
+            return;
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (e.isDirectory()) {
+                if (e.name.startsWith(".") || SKIP_DIRS.has(e.name))
+                    continue;
+                walk(join(dir, e.name), rel ? `${rel}/${e.name}` : e.name, depth + 1);
+            }
+            else if (extname(e.name) === ".md") {
+                out.push({ path: join(dir, e.name), rel: rel ? `${rel}/${e.name}` : e.name });
+            }
+        }
+    };
+    walk(root, "", 0);
+    return out;
+}
+//# sourceMappingURL=drift.js.map

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.23.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.",