@davesheffer/hunch 0.15.4 → 0.16.1

package/README.md

@@ -135,6 +135,16 @@ forbidden dependency) — code that never existed, so a diff reviewer is blind t
 decision carries machine-checkable **tripwires**; re-introduce one and Hunch blocks it with
 the receipt of what you rejected and why. → [docs](https://hunch-pi.vercel.app/docs#veto)
 
+### Redundancy Guard — "this already exists"
+
+An agent works from a *local* context window, so it re-implements a helper that already
+lives three modules over, or re-adds a dependency the codebase already has — sprawl a
+diff-only reviewer can't see, but Hunch's symbol graph can. Add a function or class already
+defined elsewhere and `hunch check` / the CI guard / `hunch_merge_verdict` flag it with the
+existing location. Deterministic and **advisory** — it never blocks; tuned to stay quiet
+(stopword + length filters, scoped to the change's own project root, move-aware so a
+refactor isn't mistaken for a duplicate). → [docs](https://hunch-pi.vercel.app/docs#redundancy)
+
 Plus the **Regression Guard** (re-adding deliberately-retired code) and the
 **[CI Constraint Guard](https://hunch-pi.vercel.app/docs#ci)** (`hunch ci` — a PR gate that
 comments the affected `con_`/`dec_` ids and fails on a blocking one).

package/dist/cli/index.js

@@ -545,7 +545,7 @@ program
 // ---- check (constraint enforcement) ---------------------------------------
 program
     .command("check")
-    .description("Flag changes that touch a do-not-break invariant — the local guardrail AND the CI/PR Constraint Guard.")
+    .description("Flag changes that touch a do-not-break invariant — the local guardrail AND the CI/PR Constraint Guard. Also flags (advisory) symbols you add that already exist elsewhere — possible re-implementation/sprawl.")
     .option("--staged", "check git staged files (default)")
     .option("--commit <sha>", "check a specific commit's files")
     .option("--base <ref>", "check a PR/branch: files changed vs <ref> (e.g. origin/main) — for CI")
@@ -557,7 +557,7 @@ program
     if (sources.length > 1)
         return fail(`pick one of --staged / --commit / --base (got ${sources.join(", ")})`);
     const markdown = opts.format === "markdown";
-    const emptyReport = { fileCount: 0, strict: !!opts.strict, direct: [], near: [], regressions: [], vetoes: [], strictBlockers: 0, regBlocking: 0, vetoBlocking: 0 };
+    const emptyReport = { fileCount: 0, strict: !!opts.strict, direct: [], near: [], regressions: [], vetoes: [], redundant: [], strictBlockers: 0, regBlocking: 0, vetoBlocking: 0 };
     const { store, root } = storeFor();
     // Fail loudly on an unresolvable --base (e.g. CI forgot to fetch the base
     // branch) — otherwise the diff is empty and the guard passes vacuously.
@@ -575,8 +575,9 @@ program
         return;
     }
     // DIRECT (scope match) + NEAR (blast radius) + REGRESSION (re-added retired
-    // code) + the hardened strict gate + causal `why` citations — all assembled by
-    // the shared store.buildCheckReport (also used by the hunch_merge_verdict tool).
+    // code) + REDUNDANT (adds a symbol already defined elsewhere — advisory) + the
+    // hardened strict gate + causal `why` citations — all assembled by the shared
+    // store.buildCheckReport (also used by the hunch_merge_verdict tool).
     const diff = opts.commit ? commitDiff(opts.commit, root) : opts.base ? rangeDiff(opts.base, root) : stagedDiff(root);
     const report = store.buildCheckReport(files, diff, {
         strict: !!opts.strict,
@@ -633,7 +634,7 @@ const vetoCmd = program
     }
     // Render ONLY the veto class — zero the other sections so the shared renderer
     // shows just the rejected-alternative reversals (the rest is `hunch check`).
-    const vetoOnly = { ...full, direct: [], near: [], regressions: [], strictBlockers: 0, regBlocking: 0 };
+    const vetoOnly = { ...full, direct: [], near: [], regressions: [], redundant: [], strictBlockers: 0, regBlocking: 0 };
     console.log(markdown ? renderMarkdown(vetoOnly) : renderText(vetoOnly));
     if (reportFailsStrict(vetoOnly))
         process.exitCode = 1;

package/dist/core/checkreport.js

@@ -4,7 +4,7 @@
  *  then renders it as text (terminal, unchanged) or markdown (a PR comment posted
  *  by the GitHub Action). The exit-code decision lives with the caller. */
 export function reportIsClean(r) {
-    return r.direct.length === 0 && r.near.length === 0 && r.regressions.length === 0 && r.vetoes.length === 0;
+    return r.direct.length === 0 && r.near.length === 0 && r.regressions.length === 0 && r.vetoes.length === 0 && r.redundant.length === 0;
 }
 /** True when --strict should FAIL the commit/PR. */
 export function reportFailsStrict(r) {
@@ -76,6 +76,12 @@ export function renderText(r) {
             out.push(`  ${v.blocking ? "⛔" : "⚠"} ${v.decision} rejected this approach${v.blocking ? " (human-confirmed)" : " (advisory)"}\n      you rejected: ${clip(v.alternative)}\n      you chose:    ${clip(v.chosen)}\n      evidence: ${v.evidence.slice(0, 4).join(", ")}`);
         }
     }
+    if (r.redundant.length) {
+        out.push(`${r.direct.length || r.near.length || r.regressions.length || r.vetoes.length ? "\n" : ""}Possibly re-implements ${r.redundant.length} symbol(s) that already exist (advisory — review, never blocks):\n`);
+        for (const x of r.redundant) {
+            out.push(`  ⟲ adds ${x.kind} \`${x.name}\` — already defined in ${x.existingFile}`);
+        }
+    }
     if (reportFailsStrict(r)) {
         const reasons = [
             r.strictBlockers ? `${r.strictBlockers} high-confidence blocking invariant(s) directly in scope` : "",
@@ -142,6 +148,13 @@ export function renderMarkdown(r) {
         }
         out.push("");
     }
+    if (r.redundant.length) {
+        out.push(`### ⟲ Possibly re-implements existing code (advisory)`);
+        for (const x of r.redundant) {
+            out.push(`- \`${x.name}\` (${x.kind}) — already defined in \`${x.existingFile}\``);
+        }
+        out.push("");
+    }
     out.push("---");
     if (reportFailsStrict(r)) {
         const reasons = [

package/dist/mcp/server.js

@@ -323,7 +323,7 @@ export function buildServer(root) {
     // -- hunch_merge_verdict (Causal Merge Verdict — read-only, client-agnostic) --
     server.registerTool("hunch_merge_verdict", {
         title: "Causal merge verdict: is this change safe against the recorded WHY?",
-        description: "Before opening or merging a PR, replay a diff against engineering memory and return ONE verdict — BLOCK / WARN / PASS. For each invariant DIRECTLY in scope it cites WHY the guard exists (the decision that motivated it + the bug whose root cause spawned it); it also lists invariants reached via blast radius (near, advisory) and any deliberately-retired code the diff re-introduces. Deterministic, no LLM. Omit base AND commit to check STAGED changes; pass base (e.g. origin/main) for a PR range, or commit for a single commit. Call this before merging a widely-scoped change.",
+        description: "Before opening or merging a PR, replay a diff against engineering memory and return ONE verdict — BLOCK / WARN / PASS. For each invariant DIRECTLY in scope it cites WHY the guard exists (the decision that motivated it + the bug whose root cause spawned it); it also lists invariants reached via blast radius (near, advisory), any deliberately-retired code the diff re-introduces, and symbols the diff adds that are already defined elsewhere in the graph (possible re-implementation/sprawl, advisory). Deterministic, no LLM. Omit base AND commit to check STAGED changes; pass base (e.g. origin/main) for a PR range, or commit for a single commit. Call this before merging a widely-scoped change.",
         inputSchema: {
             base: z.string().optional().describe("Diff against this base ref (e.g. origin/main) — for a PR/branch."),
             commit: z.string().optional().describe("Diff a single commit (sha/ref). Omit base AND commit to check staged changes."),

package/dist/store/hunchStore.js

@@ -443,6 +443,10 @@ export class HunchStore {
         const staleIds = new Set(staleRecords.filter((s) => s.kind === "constraint").map((s) => s.id));
         const staleDecisionIds = new Set(staleRecords.filter((s) => s.kind === "decision").map((s) => s.id));
         const vetoes = this.vetoHits(an, files, staleDecisionIds);
+        const redundant = this.redundantSymbols(an.addedSymbols, files, {
+            movedFrom: [...an.filesRenamed.map((r) => r.from), ...an.filesDeleted],
+            removedNames: new Set(an.removedSymbols.map((s) => s.name)),
+        });
         const directReport = [...direct.values()].map(({ c, files: fs }) => {
             const stale = staleIds.has(c.id);
             const strictBlocks = isStrictBlocker(c, stale);
@@ -460,11 +464,64 @@ export class HunchStore {
             near: [...near.values()].map(({ c, via }) => ({ id: c.id, severity: c.severity ?? "advisory", statement: c.statement, via })),
             regressions: regHits.map((h) => ({ kind: h.kind, name: h.name, decision: h.decision, title: h.title, reason: h.reason, blocking: h.blocking })),
             vetoes: vetoes.map((v) => ({ decision: v.decision, title: v.title, alternative: v.alternative, chosen: v.chosen, tier: v.tier, evidence: v.evidence, blocking: v.blocks })),
+            redundant,
             strictBlockers: directReport.filter((d) => d.strictBlocks).length,
             regBlocking: regHits.filter((h) => h.blocking).length,
             vetoBlocking: vetoes.filter((v) => v.blocks).length,
         };
     }
+    /** Sprawl/"this already exists" guard (ADVISORY, never blocks). A symbol the diff
+     *  ADDS whose name already exists in the indexed graph in a file NOT touched by the
+     *  diff is a likely re-implementation the agent's local context window couldn't see.
+     *  Read-only. Heuristic, so noise is controlled: top-level function/class/const only,
+     *  name length ≥ 4, a stopword list of generic names, deduped, and capped. */
+    redundantSymbols(added, files, opts = {}) {
+        if (!added.length)
+            return [];
+        const KINDS = new Set(["function", "class", "const"]);
+        const STOP = new Set([
+            "index", "handler", "handlers", "default", "main", "run", "start", "stop", "setup", "init",
+            "constructor", "render", "create", "update", "build", "parse", "load", "save", "next", "data",
+            "value", "item", "items", "props", "state", "config", "options", "result", "route", "routes",
+            "app", "server", "client", "test", "tests", "mock", "stub", "helper", "helpers", "util", "utils",
+            "types", "schema", "constants", "common", "shared", "base", "model", "models", "view", "store",
+        ]);
+        // Match only against top-level VALUE declarations already in the graph. A method
+        // (`obj.close()`) or the file node itself sharing a name is not a re-implementation.
+        // ("variable" is kept for forward-compat; the current indexer emits arrow-fn consts
+        // as "function", so const re-implementations are still matched.)
+        const EXISTING_KINDS = new Set(["function", "class", "variable"]);
+        // A symbol carried into a moved/deleted file is being relocated, not duplicated. The
+        // changed-file list uses --diff-filter=ACMR, so a sub-threshold move (Add new + Delete
+        // old) drops the old path — add the move-from / deleted paths back so their lingering
+        // graph entries are not mistaken for a separate "existing" implementation.
+        const changed = new Set(files);
+        for (const p of opts.movedFrom ?? [])
+            changed.add(p);
+        const removedNames = opts.removedNames ?? new Set();
+        // Only compare within the diff's own top-level root(s). A name that also exists in a
+        // test fixture or a separate sub-project (test/, vscode-extension/, site/) is not
+        // sprawl in the source under change — different roots, different ownership.
+        const roots = new Set(files.map((f) => f.split("/")[0]));
+        const symbols = this.json.loadAll("symbols");
+        const out = [];
+        const seen = new Set();
+        for (const sc of added) {
+            const name = sc.name;
+            if (seen.has(name) || name.length < 4 || !KINDS.has(sc.kind) || STOP.has(name.toLowerCase()))
+                continue;
+            if (removedNames.has(name))
+                continue; // the same name was removed in this diff → moved, not duplicated
+            const hit = symbols.find((s) => s.name === name && !changed.has(s.file) && EXISTING_KINDS.has(s.kind) && roots.has(s.file.split("/")[0]));
+            if (hit) {
+                seen.add(name);
+                out.push({ name, kind: sc.kind, existingFile: hit.file });
+                if (out.length >= 10)
+                    break;
+            }
+        }
+        return out;
+    }
     /** Time-travel: the decision history for a target — every decision touching it,
      *  newest-first, with its valid-time window and supersession links. Answers
      *  "what did we believe, and when/why did it change?" (hunch_timeline). */

package/package.json

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