@davesheffer/hunch 0.26.1 → 0.28.0

package/dist/cli/index.js

@@ -38,13 +38,14 @@ 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";
 import { blockingInScope, vetoInScope, proposedEditLines } from "../core/hookpolicy.js";
 import { loadGoldenSet, evaluateGraphLift } from "../eval/harness.js";
 import { computeDrift } from "../core/drift.js";
+import { compareCandidates } from "../core/compare.js";
 import { draftTripwires, knownRepoDeps } from "../synthesis/tripwires.js";
 import { constraintId } from "../core/ids.js";
 import { readManifest, writeManifest, SCHEMA_VERSION } from "../core/migrate.js";
@@ -165,9 +166,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 +267,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
@@ -527,6 +536,36 @@ program
     console.log(dim("  advisory, deterministic draft — refine the steps/gotchas; surfaced via `hunch query` and MCP."));
     store.close();
 });
+// ---- compare (rank N candidate solutions by architectural fit) ------------
+program
+    .command("compare")
+    .description("Rank candidate branches/commits by how well each fits the architecture — deterministic merge-verdict over the graph (the 'evaluate 5 solutions' check).")
+    .argument("<candidates...>", "refs to compare (branches or commits), e.g. feat-a feat-b feat-c")
+    .option("--base <ref>", "base to diff each candidate against (3-dot, since merge-base)", "main")
+    .action((candidates, opts) => {
+    const { store, root } = storeFor();
+    if (!isGitRepo(root)) {
+        store.close();
+        return fail("compare needs a git repo");
+    }
+    if (!revExists(opts.base, root)) {
+        store.close();
+        return fail(`base ref "${opts.base}" not found (pass --base <ref>)`);
+    }
+    store.reindex();
+    const ranked = compareCandidates(store, root, opts.base, candidates);
+    const icon = (v) => (v === "pass" ? "✅" : v === "warn" ? "⚠️ " : "⛔");
+    console.log(`Candidates vs ${opts.base} — best architectural fit first:\n`);
+    ranked.forEach((c, i) => {
+        if (c.error) {
+            console.log(`  ${i + 1}. ${c.ref} — ${c.error}`);
+            return;
+        }
+        const best = i === 0 ? dim("  ← best fit") : "";
+        console.log(`  ${i + 1}. ${icon(c.verdict)} ${c.ref}  [${c.verdict}]  ${c.blocking} blocking · ${c.direct} direct · ${c.near} near · ${c.vetoes} veto · ${c.redundant} redundant  (${c.files} files)${best}`);
+    });
+    store.close();
+});
 // ---- embed (opt-in semantic search) ---------------------------------------
 program
     .command("embed")

package/dist/core/compare.js

@@ -0,0 +1,35 @@
+import { verdict } from "./checkreport.js";
+import { revExists, rangeFiles, rangeDiff } from "../extractors/git.js";
+/** A lower fit score is better. Verdict dominates (pass < warn < block), then the
+ *  blocking count, then total advisory hits. Errored candidates sort last. */
+function fitKey(c) {
+    const tier = c.error ? 9 : c.verdict === "pass" ? 0 : c.verdict === "warn" ? 1 : 2;
+    return [tier, c.blocking, c.direct + c.near + c.vetoes + c.redundant];
+}
+export function compareCandidates(store, root, base, candidates) {
+    const results = candidates.map((ref) => {
+        const zero = { ref, verdict: "block", blocking: 0, direct: 0, near: 0, vetoes: 0, redundant: 0, files: 0 };
+        if (!revExists(ref, root))
+            return { ...zero, error: `ref "${ref}" not found` };
+        const files = rangeFiles(base, root, ref);
+        if (!files.length)
+            return { ...zero, verdict: "pass", error: `no changes vs ${base}` };
+        const r = store.buildCheckReport(files, rangeDiff(base, root, ref), { strict: true });
+        return {
+            ref,
+            verdict: verdict(r),
+            blocking: r.strictBlockers + r.regBlocking + r.vetoBlocking,
+            direct: r.direct.length,
+            near: r.near.length,
+            vetoes: r.vetoes.length,
+            redundant: r.redundant.length,
+            files: files.length,
+        };
+    });
+    return results.sort((a, b) => {
+        const [at, ab, ah] = fitKey(a);
+        const [bt, bb, bh] = fitKey(b);
+        return at - bt || ab - bb || ah - bh;
+    });
+}
+//# sourceMappingURL=compare.js.map

package/dist/integrations/claudemd.js

@@ -33,6 +33,7 @@ export function renderHunchSection(store) {
     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_compare(candidates)` — rank N candidate branches/commits by architectural fit (fewest invariant hits).");
     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/dist/mcp/server.js

@@ -16,6 +16,7 @@ import { decisionId } from "../core/ids.js";
 import { buildCorrectionConstraint } from "../core/correction.js";
 import { revParse, asOfDate, revExists, lastChangeDate, rangeFiles, rangeDiff, commitFiles, commitDiff, stagedFiles, stagedDiff, commitAndPushHunch } from "../extractors/git.js";
 import { formatContext } from "../core/format.js";
+import { compareCandidates } from "../core/compare.js";
 import { renderMarkdown, verdict } from "../core/checkreport.js";
 import { HUNCH_VERSION } from "../core/version.js";
 const ok = (text) => ({ content: [{ type: "text", text }] });
@@ -407,6 +408,33 @@ export function buildServer(root) {
             return err(`Failed to compute merge verdict: ${e.message}`);
         }
     });
+    // -- hunch_compare --------------------------------------------------------
+    server.registerTool("hunch_compare", {
+        title: "Rank candidate solutions by architectural fit",
+        description: "Given several candidate branches/commits (e.g. N solutions to one task), replay each against engineering memory and RANK them best-fit first — the candidate that trips the fewest in-force invariants, reverses no decisions, and adds the least sprawl wins. Deterministic (the same merge-verdict per candidate, no LLM). Use to choose among multiple solutions before committing to one.",
+        inputSchema: {
+            candidates: z.array(z.string()).describe("Refs to compare — branches or commits, e.g. ['feat-a','feat-b','feat-c']."),
+            base: z.string().optional().describe("Base to diff each candidate against (3-dot; default: main)."),
+        },
+    }, async ({ candidates, base }) => {
+        try {
+            const b = base ?? "main";
+            if (!candidates.length)
+                return err("Pass at least one candidate ref.");
+            if (!revExists(b, root))
+                return err(`base ref "${b}" does not resolve (in CI, fetch it first).`);
+            const ranked = compareCandidates(store, root, b, candidates);
+            const icon = (v) => (v === "pass" ? "✅" : v === "warn" ? "⚠" : "⛔");
+            const lines = ranked.map((c, i) => c.error
+                ? `${i + 1}. ${c.ref} — ${c.error}`
+                : `${i + 1}. ${icon(c.verdict)} ${c.ref} [${c.verdict}] — ${c.blocking} blocking · ${c.direct} direct · ${c.near} near · ${c.vetoes} veto · ${c.redundant} redundant (${c.files} files)`);
+            const best = ranked.find((c) => !c.error);
+            return ok(`Candidates vs ${b}, best architectural fit first:\n\n${lines.join("\n")}${best ? `\n\nBest fit: ${best.ref}` : ""}`);
+        }
+        catch (e) {
+            return err(`Failed to compare candidates: ${e.message}`);
+        }
+    });
     return server;
 }
 function provLine(record) {

package/package.json

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