@davesheffer/hunch 1.20.2 → 1.20.3

package/README.md

@@ -58,6 +58,9 @@ existing configuration.
   passes, needs attention, or should be blocked.
 - **Past bugs stay useful** — see which old incident a piece of code fixed before accidentally
   undoing it.
+- **Fresh context without lost history** — decisions whose code anchors are still current rank
+  ahead of ones whose files changed after verification; older evidence remains visible and keeps
+  its existing authority.
 - **Understands how code connects** — for TypeScript, JavaScript, Python, Go, PHP, YAML, and Helm, Hunch
   can see what calls or depends on the code you are about to change. Its memory works with any
   language.
@@ -171,7 +174,7 @@ repository, separate from the code repository. Hunch does not host it. Create a
 that every teammate can access, install Hunch on team machines and CI, then have one maintainer run:
 
 ```bash
-npm i -g @davesheffer/hunch@1.20.2
+npm i -g @davesheffer/hunch@1.20.3
 hunch shared --repo git@github.com:acme/project-hunch-memory.git
 git add .gitignore .hunch/team.json
 git commit -m "chore: connect shared Hunch memory"
@@ -186,7 +189,7 @@ printed by Hunch. Omit `--migrate` for a new setup.
 After the pointer commit lands, teammates need Hunch installed and Git access to the memory repo:
 
 ```bash
-npm i -g @davesheffer/hunch@1.20.2
+npm i -g @davesheffer/hunch@1.20.3
 git pull
 hunch init
 hunch doctor
@@ -234,7 +237,7 @@ but stops automatic memory commits and pushes. As a team-coordinated rollback, r
 commit to stop discovery after teammates pull the revert. Existing machines retain their ignored
 local overlay until they are deliberately disconnected; do not delete the memory repo as part of a
 rollback. For this rollout, reinstall the previous published package with
-`npm i -g @davesheffer/hunch@1.20.0`; the release receipt resolves and records the verified rollback
+`npm i -g @davesheffer/hunch@1.20.2`; the release receipt resolves and records the verified rollback
 target from the npm registry instead of trusting Git tags. Pause enforcement first as shown above,
 and keep every team client on the same release before resuming Matrix policy workflows.
 

package/dist/cli/index.js

@@ -1292,7 +1292,7 @@ program
         const emb = await selectEmbedder();
         if (!store.semanticReady(emb)) {
             console.log("· semantic search isn't enabled yet — run `hunch embed` (using keyword search for now).\n");
-            hits = store.search(q, 12);
+            hits = store.rankedSearch(q, 12);
         }
         else {
             hits = await store.hybridSearch(q, 12, { embedder: emb });
@@ -1300,7 +1300,7 @@ program
         }
     }
     else {
-        hits = store.search(q, 12);
+        hits = store.rankedSearch(q, 12);
     }
     if (!hits.length) {
         console.log(`No matches for "${q}".`);
@@ -3904,7 +3904,7 @@ program
         !ctx.landscape?.resources.length &&
         !ctx.landscape?.relationships.length;
     if (empty && !asOf) {
-        const hits = store.search(target, 8);
+        const hits = store.rankedSearch(target, 8);
         if (hits.length) {
             console.log(`No file/symbol resolves for "${target}" — closest graph matches instead:\n`);
             for (const h of hits)

package/dist/extractors/git.js

@@ -2125,6 +2125,53 @@ export function firstCommitForFile(file, cwd) {
 export function lastChangeDate(file, cwd) {
     return gitSafe(["log", "-1", "--format=%aI", "--", file], cwd);
 }
+/**
+ * Newest author date for every changed path selected by a bounded set of repository-relative
+ * Hunch scopes. One Git history walk replaces the per-file process loop used by `staleness()`.
+ *
+ * The return keys are the concrete paths Git observed, not the input scopes: callers can apply
+ * Hunch's own exact/glob/directory matcher without treating Git pathspec interpretation as graph
+ * authority. A failed or oversized read returns null, so freshness stays unknown rather than
+ * partially scoring a record.
+ */
+export function scopedLastChangeDates(scopes, cwd, maxChangedPaths = 4_096) {
+    const pathspecs = [...new Set(scopes)].map((scope) => {
+        const normalized = scope.replaceAll("\\", "/");
+        return /[*?[]/.test(normalized) ? `:(glob)${normalized}` : `:(literal)${normalized}`;
+    });
+    if (pathspecs.length === 0)
+        return new Map();
+    const raw = gitRawSafeIsolated([
+        "-c", "core.quotePath=false",
+        "log", "-z", "--name-only", "--format=HUNCH_DATE:%aI%x00", "--", ...pathspecs,
+    ], cwd, 64 * 1024 * 1024);
+    if (raw === null)
+        return null;
+    const out = new Map();
+    let commitDate = "";
+    for (const rawToken of raw.split("\0")) {
+        // Git inserts one presentation newline between a custom commit format and its
+        // first NUL-delimited path. Remove exactly that byte; a real leading newline in
+        // a path remains as the second byte and therefore cannot alias a normal path.
+        const token = rawToken.startsWith("\n") ? rawToken.slice(1) : rawToken;
+        if (!token)
+            continue;
+        if (token.startsWith("HUNCH_DATE:")) {
+            const candidate = token.slice("HUNCH_DATE:".length);
+            commitDate = Number.isFinite(Date.parse(candidate)) ? candidate : "";
+            continue;
+        }
+        if (!commitDate)
+            continue;
+        const previous = out.get(token);
+        if (!previous || Date.parse(commitDate) > Date.parse(previous)) {
+            out.set(token, commitDate);
+            if (out.size > maxChangedPaths)
+                return null;
+        }
+    }
+    return out;
+}
 /** Batched per-file git metrics for indexing: churn (commits touching the file in
  *  the last `days`; pass 0 to skip) and the most-recent commit (`commit:<sha>`).
  *

package/dist/mcp/server.js

@@ -870,7 +870,7 @@ export function buildServerWithRootControl(initialRoot) {
             !ctx.landscape?.resources.length &&
             !ctx.landscape?.relationships.length;
         if (empty && !asOf) {
-            const hits = store.search(target, 8);
+            const hits = store.rankedSearch(target, 8);
             if (hits.length) {
                 const resolved = hits.map((hit) => ({ hit, record: store.resolve(hit.ref)?.record }));
                 const fallback = {

package/dist/store/hunchStore.js

@@ -18,7 +18,7 @@ import { openDb, withTx } from "./db.js";
 import { RESET_SQL, embedHash } from "./schema.js";
 import { selectEmbedder } from "./embedder.js";
 import { JsonStore } from "./jsonStore.js";
-import { gitCommonDir, gitWorktreeRoot, sameGitPublication } from "../extractors/git.js";
+import { gitCommonDir, gitWorktreeRoot, isolatedHeadSha, sameGitPublication, scopedLastChangeDates, } from "../extractors/git.js";
 import { pathMatchesGlob, pathsRelated } from "../core/glob.js";
 import { currentForTopic, isInForce } from "../core/topics.js";
 import { edgeId } from "../core/ids.js";
@@ -85,6 +85,11 @@ export class HunchStore {
      *  equal to a committed file (dec_d7bad4ccb7). */
     suppressPrivate = false;
     _db = null;
+    /** HEAD-keyed, process-local ranking evidence. It never changes record authority or storage. */
+    decisionFreshnessRoot = "";
+    decisionFreshnessHead = "";
+    decisionFreshnessScopes = new Set();
+    decisionFreshnessChanges = new Map();
     constructor(paths) {
         this.paths = paths;
         this.json = new JsonStore(paths);
@@ -621,7 +626,8 @@ export class HunchStore {
     /** Post-fusion rerank by graph PRIORS (dec_25e277f479): relevance ordering, not
      *  just reachability. Trust weight w = liveness × provenance × recency: liveness 0.6
      *  for superseded/retired/rejected, provenance 1.0 / 0.85 / 0.75 for
-     *  human_confirmed / llm_draft / extracted-inferred, recency 0.7 + 0.3·½^(age/90d).
+     *  human_confirmed / llm_draft / extracted-inferred, recency 0.7 + 0.3·½^(age/90d),
+     *  and proven anchored-file staleness 0.8. Every factor is ranking-only.
      *  Runbook trigger phrases matching the query boost ×1.5 (exact intent beats
      *  keyword luck). Structural refs (symbols/components/edges) stay neutral.
      *
@@ -643,7 +649,7 @@ export class HunchStore {
      *  a stale or low-provenance record visibly dims, an exact runbook-trigger match
      *  visibly promotes, and neither can leapfrog the whole pool. Same measurement
      *  after: 0% evicted from fused ranks 0–8. Deterministic; ties keep fused order. */
-    rerankByPriors(hits, limit, query) {
+    rerankByPriors(hits, limit, query, freshnessRoot = this.paths.root) {
         if (!hits.length)
             return hits; // a SINGLE hit still runs — topic-chain promotion must fire for the lone stale match
         const now = Date.now();
@@ -672,6 +678,10 @@ export class HunchStore {
                 pos: i + 0.5,
             });
         }
+        const decisionsById = new Map(this.recs("decisions").map((decision) => [decision.id, decision]));
+        const staleDecisionIds = this.staleDecisionIds(pool.filter(({ h }) => h.kind === "decisions")
+            .map(({ h }) => decisionsById.get(h.ref))
+            .filter((decision) => !!decision), freshnessRoot);
         const scored = pool.map(({ h, pos }) => {
             const m = this.priorMeta(h.ref, h.kind);
             let w = 1;
@@ -694,6 +704,10 @@ export class HunchStore {
                     if (Number.isFinite(ageDays))
                         w *= 0.7 + 0.3 * Math.pow(0.5, ageDays / 90);
                 }
+                // File-change staleness is a bounded relevance signal only. It cannot retire,
+                // withhold, supersede, or weaken a decision's enforcement authority.
+                if (h.kind === "decisions" && staleDecisionIds.has(h.ref))
+                    w *= STALE_DECISION_PRIOR_WEIGHT;
                 if (q && m.triggers?.some((tr) => q.includes(tr) || tr.includes(q)))
                     w *= 1.5;
             }
@@ -708,6 +722,77 @@ export class HunchStore {
         scored.sort((a, b) => a.pos - b.pos);
         return scored.slice(0, limit).map((x) => x.h);
     }
+    /**
+     * Score only freshness that the existing graph clocks can prove: an anchored path changed after
+     * `provenance.last_verified`. One bounded Git pass fills a HEAD-keyed cache for newly encountered
+     * scopes; repeated MCP/CLI queries perform no history walk until HEAD changes.
+     */
+    staleDecisionIds(decisions, freshnessRoot) {
+        const root = resolve(freshnessRoot);
+        const head = isolatedHeadSha(root);
+        if (!head)
+            return new Set();
+        if (root !== this.decisionFreshnessRoot || head !== this.decisionFreshnessHead) {
+            this.decisionFreshnessRoot = root;
+            this.decisionFreshnessHead = head;
+            this.decisionFreshnessScopes.clear();
+            this.decisionFreshnessChanges.clear();
+        }
+        const eligible = new Map();
+        let scopeCount = 0;
+        for (const decision of decisions) {
+            const verifiedAt = Date.parse(decision.provenance.last_verified ?? "");
+            if (!Number.isFinite(verifiedAt))
+                continue;
+            const scopes = [...new Set(decision.related_files.map(safeFreshnessScope).filter(Boolean))];
+            if (scopes.length === 0 || scopeCount + scopes.length > DECISION_FRESHNESS_SCOPE_QUERY_CAP)
+                continue;
+            scopeCount += scopes.length;
+            eligible.set(decision.id, { verifiedAt, scopes });
+        }
+        let missing = [...new Set([...eligible.values()].flatMap((candidate) => candidate.scopes))]
+            .filter((scope) => !this.decisionFreshnessScopes.has(scope));
+        if (missing.length) {
+            if (this.decisionFreshnessScopes.size + missing.length > DECISION_FRESHNESS_SCOPE_CACHE_CAP) {
+                this.decisionFreshnessScopes.clear();
+                this.decisionFreshnessChanges.clear();
+                missing = [...new Set([...eligible.values()].flatMap((candidate) => candidate.scopes))];
+            }
+            const observed = scopedLastChangeDates(missing, root, DECISION_FRESHNESS_PATH_CACHE_CAP);
+            if (observed) {
+                if (this.decisionFreshnessChanges.size + observed.size > DECISION_FRESHNESS_PATH_CACHE_CAP) {
+                    this.decisionFreshnessScopes.clear();
+                    this.decisionFreshnessChanges.clear();
+                }
+                else {
+                    missing.forEach((scope) => this.decisionFreshnessScopes.add(scope));
+                    observed.forEach((date, path) => {
+                        const previous = this.decisionFreshnessChanges.get(path);
+                        if (!previous || Date.parse(date) > Date.parse(previous))
+                            this.decisionFreshnessChanges.set(path, date);
+                    });
+                }
+            }
+        }
+        const stale = new Set();
+        for (const [decisionId, candidate] of eligible) {
+            if (candidate.scopes.some((scope) => !this.decisionFreshnessScopes.has(scope)))
+                continue;
+            for (const [changedPath, changedAt] of this.decisionFreshnessChanges) {
+                if (Date.parse(changedAt) <= candidate.verifiedAt)
+                    continue;
+                if (candidate.scopes.some((scope) => freshnessScopeMatches(changedPath, scope))) {
+                    stale.add(decisionId);
+                    break;
+                }
+            }
+        }
+        return stale;
+    }
+    /** Fast relevance ranking for task-phrase context fallback: FTS + bounded graph priors, no model. */
+    rankedSearch(query, limit = 12, opts = {}) {
+        return this.rerankByPriors(this.search(query, Math.max(limit, 24)), limit, query, opts.freshnessRoot ?? this.paths.root);
+    }
     /** The prior-bearing metadata for a hit: liveness, provenance, effective date,
      *  and (runbooks) trigger phrases. null = structural ref, neutral prior. */
     priorMeta(ref, kind) {
@@ -779,9 +864,9 @@ export class HunchStore {
             tokenCap: boundedWhole(opts.graphTokenCap, GRAPH_TOKEN_CAP, GRAPH_TOKEN_HARD_MAX),
         }, gw);
         if (!sem.length && !graph.length)
-            return this.rerankByPriors(fts, limit, query);
+            return this.rerankByPriors(fts, limit, query, opts.freshnessRoot ?? this.paths.root);
         // Fuse with headroom so the prior rerank can promote from below the cut line.
-        return this.rerankByPriors(this.rrfFuse(fts, sem, graph, Math.max(limit, 24), gw), limit, query);
+        return this.rerankByPriors(this.rrfFuse(fts, sem, graph, Math.max(limit, 24), gw), limit, query, opts.freshnessRoot ?? this.paths.root);
     }
     /** Runbook-scoped retrieval (roadmap #5): the same FTS+graph(+semantic) fusion,
      *  restricted to the `runbooks` kind — so a "what's the procedure for X" query
@@ -1777,6 +1862,11 @@ const GRAPH_TOKEN_CAP = boundedWhole(numEnv("HUNCH_GRAPH_TOKEN_CAP", 2_000), 2_0
  *  rerankByPriors for the measurement that fixed it at 4. */
 const PRIOR_SHIFT_SCALE = numEnv("HUNCH_PRIOR_SHIFT_SCALE", 12);
 const MAX_PRIOR_SHIFT = numEnv("HUNCH_MAX_PRIOR_SHIFT", 4);
+/** A stale anchored decision stays visible and authoritative; it moves down by at most the shared prior clamp. */
+const STALE_DECISION_PRIOR_WEIGHT = Math.min(1, numEnv("HUNCH_STALE_DECISION_PRIOR_WEIGHT", 0.8));
+const DECISION_FRESHNESS_SCOPE_QUERY_CAP = 256;
+const DECISION_FRESHNESS_SCOPE_CACHE_CAP = 512;
+const DECISION_FRESHNESS_PATH_CACHE_CAP = 4_096;
 /** Memory-record prior: a "why" question is answered by RECORDED INTENT (decisions,
  *  constraints, bugs, runbooks, policies), not by the code symbols that merely share
  *  its vocabulary. Symbols carry a neutral prior (priorMeta -> null), so on a graph
@@ -1789,6 +1879,23 @@ const MAX_PRIOR_SHIFT = numEnv("HUNCH_MAX_PRIOR_SHIFT", 4);
  *  0.402 -> 0.575. Set HUNCH_MEMORY_PRIOR_SHIFT=0 to disable. */
 const MEMORY_PRIOR_SHIFT = numEnv("HUNCH_MEMORY_PRIOR_SHIFT", 12);
 const MEMORY_KINDS = new Set(["decisions", "constraints", "bugs", "runbooks", "policies"]);
+function safeFreshnessScope(value) {
+    const normalized = toPosixTarget(value.trim());
+    if (!normalized || normalized.length > 1_024 || normalized.includes("\0")
+        || isAbsolute(normalized) || /^[a-zA-Z]:/.test(normalized)
+        || normalized === ".." || normalized.startsWith("../") || normalized.includes("/../")
+        || normalized.startsWith("private:"))
+        return null;
+    return normalized.replace(/^\.\//, "");
+}
+function freshnessScopeMatches(path, scope) {
+    try {
+        return pathsRelated(path, scope) || pathMatchesGlob(path, scope);
+    }
+    catch {
+        return false;
+    }
+}
 function numEnv(name, dflt) {
     const v = Number(process.env[name]);
     // >= 0, not > 0: zero is the documented kill-switch (HUNCH_RRF_W_*=0 disables

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.20.2",
+  "version": "1.20.3",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",

package/server.json

@@ -7,13 +7,13 @@
     "source": "github"
   },
   "websiteUrl": "https://hunch-pi.vercel.app",
-  "version": "1.20.2",
+  "version": "1.20.3",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.20.2",
+      "version": "1.20.3",
       "runtimeHint": "npx",
       "packageArguments": [
         {