@davesheffer/hunch 0.26.0 → 0.27.0

package/dist/cli/index.js

@@ -38,7 +38,7 @@ import { ensureGitignore, ignoreHunchMemory, HUNCH_MEMORY_DIRS } from "../integr
 import { writeCiWorkflow } from "../integrations/ciAction.js";
 import { updateClaudeMd } from "../integrations/claudemd.js";
 import { writeMcpJson, writeSlashCommands, installClaudeHooks } from "../integrations/scaffold.js";
-import { scaffoldProviders, regenerateGrounding } from "../integrations/providers.js";
+import { scaffoldProviders, regenerateGrounding, refreshExistingGrounding } from "../integrations/providers.js";
 import { healClaudeConfigCaseSplit } from "../integrations/claudeConfig.js";
 import { formatContext } from "../core/format.js";
 import { readConfig, writeConfig, FIRMNESS_LEVELS, isFirmness } from "../core/config.js";
@@ -165,9 +165,13 @@ program
     ensureGitignore(root); // keep the derived SQLite index out of git (idempotent)
     const res = indexRepo(store, root);
     const { counts } = store.reindex();
-    updateClaudeMd(root, store);
+    // Self-heal grounding: pick up generator fixes (param names) + fresh counts in every
+    // assistant doc the project already has — no manual re-init. Refresh-only (no scaffold).
+    const healed = refreshExistingGrounding(root, store);
     console.log(`Indexed ${res.files} files:`);
     console.log(`  ${counts.symbols} symbols, ${counts.edges} edges, ${counts.components} components`);
+    if (healed.length)
+        console.log(`  grounding refreshed: ${healed.join(", ")}`);
     if (res.skipped)
         console.log(`  ⚠ ${res.skipped} file(s) could not be parsed (skipped)`);
     store.close();
@@ -262,10 +266,14 @@ program
     const r = await syncCommit(store, root, sha ?? headSha(root), { force: opts.force, private: opts.private, deep: opts.deep, verify: opts.verify, samples: parseSamples(opts.samples) });
     if (r.status === "written") {
         store.reindex();
-        // Don't rewrite CLAUDE.md from the hook — it would dirty the working tree
-        // on every commit. `hunch index`/`init` refresh it intentionally instead.
-        if (!opts.fromHook)
-            updateClaudeMd(root, store);
+        // Don't rewrite grounding from the hook — it would dirty the working tree on
+        // every commit. Off the hook (manual `hunch sync`), self-heal ALL existing
+        // grounding docs (param-name fixes + fresh counts), not just CLAUDE.md.
+        if (!opts.fromHook) {
+            const healed = refreshExistingGrounding(root, store);
+            if (healed.length && !opts.quiet)
+                console.log(`  ↳ grounding refreshed: ${healed.join(", ")}`);
+        }
         // Opt-in: persist the captured decision in the repo it landed in (private store
         // under --private, else this repo). Best-effort — a non-repo dir / offline push
         // just no-ops. Stage ONLY the hunch dir (never sweep unrelated working-tree

package/dist/integrations/claudemd.js

@@ -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/integrations/providers.js

@@ -241,6 +241,33 @@ export function regenerateGrounding(root, store) {
         writeWindsurfRule(root, store),
     ];
 }
+/** Self-heal: refresh the Hunch section in each grounding doc that ALREADY exists,
+ *  and report which ones actually changed. Unlike regenerateGrounding it NEVER creates
+ *  a file (so it can't scaffold grounding into a project that opted out of an
+ *  assistant). Run by `hunch index` and non-hook `hunch sync` so a project silently
+ *  picks up generator fixes (e.g. corrected MCP tool param names) and fresh record
+ *  counts on the next refresh — no manual `hunch init`. Not run from the commit hook,
+ *  which deliberately avoids dirtying the working tree on every commit. */
+export function refreshExistingGrounding(root, store) {
+    const targets = [
+        ["CLAUDE.md", () => updateClaudeMd(root, store)],
+        ["AGENTS.md", () => writeAgentsMd(root, store)],
+        [join(".github", "copilot-instructions.md"), () => writeCopilotInstructions(root, store)],
+        [join(".cursor", "rules", "hunch.mdc"), () => writeCursorRule(root, store)],
+        [join(".windsurf", "rules", "hunch.md"), () => writeWindsurfRule(root, store)],
+    ];
+    const changed = [];
+    for (const [rel, write] of targets) {
+        const file = join(root, rel);
+        if (!existsSync(file))
+            continue; // refresh-only: never scaffold a doc the project doesn't have
+        const before = readFileSync(file, "utf8");
+        write();
+        if (readFileSync(file, "utf8") !== before)
+            changed.push(rel);
+    }
+    return changed;
+}
 /** Scaffold MCP config + grounding for all supported assistants. Returns a
  *  per-assistant summary for `hunch init` to print. Each assistant is isolated:
  *  a writer that refuses to clobber a malformed file degrades to a warning rather

package/package.json

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