@davesheffer/hunch 1.16.0 → 1.18.0

package/dist/extractors/parse.js

@@ -15,10 +15,27 @@ function bundleFor(spec) {
     return b;
 }
 const STR_QUOTES = /^['"`]|['"`]$/g;
+/** Cap on a stored symbol's bodyText — large enough for review context, small
+ *  enough that a huge function/file doesn't bloat every JSON symbol record. */
+export const MAX_BODY_TEXT_CHARS = 4000;
 export function parseSource(file, source) {
     const spec = languageFor(file);
     if (!spec)
         return null;
+    // Templated text (Helm chart / Jinja CI config) isn't {spec.id} yet — a real
+    // grammar correctly reports ERROR nodes for the delimiters. Still run the
+    // parse below (a well-formed anchor elsewhere in the file still contributes
+    // a real symbol, same as any other YAML file) — just don't let those
+    // expected errors fail-close the whole-repo scan on content that was never
+    // meant to stand alone (#33). Heavy top-level templating can break error
+    // recovery badly enough that even the whole-file root node never forms
+    // (root.type becomes "ERROR", not "stream") — the fallback-symbol synthesis
+    // below covers that case so the file doesn't vanish from the component graph.
+    // String.prototype.search ignores lastIndex (unlike RegExp.test with a /g or
+    // /y flag), so a future templatingMarkers entry can't introduce cross-call
+    // statefulness here even if it forgets to keep its pattern flag-free.
+    const templated = (spec.alwaysTemplatedExtensions?.some((ext) => file.endsWith(ext)) ?? false)
+        || (spec.templatingMarkers?.some((marker) => source.search(marker) !== -1) ?? false);
     const { parser, query } = bundleFor(spec);
     // The native binding caps its scratch buffer at 32 KB unless bufferSize is
     // given — without this, any source >= 32768 bytes throws "Invalid argument"
@@ -72,17 +89,34 @@ export function parseSource(file, source) {
         }
     }
     for (const { kind, def, name } of pendingDefs.values()) {
-        if (!name)
+        const resolvedName = name ?? spec.fallbackDefName?.(file);
+        if (!resolvedName)
             continue;
         const loc = def.endPosition.row - def.startPosition.row + 1;
         symbols.push({
-            name, kind,
+            name: resolvedName, kind,
             startByte: def.startIndex, endByte: def.endIndex, loc,
-            bodyText: def.text.slice(0, 4000),
+            bodyText: def.text.slice(0, MAX_BODY_TEXT_CHARS),
+        });
+    }
+    // Every other successfully-parsed YAML file gets at least a file-root symbol
+    // (fallbackDefName). If templating broke error recovery badly enough that
+    // the doc.def capture never fired, synthesize the same fallback here rather
+    // than let the file silently drop out of the component graph. Push it before
+    // the sort below — parse()'s callers (indexer.ts) rely on symbols staying in
+    // start-byte order.
+    if (templated && spec.fallbackDefName && !symbols.some((s) => s.kind === "file")) {
+        symbols.push({
+            name: spec.fallbackDefName(file),
+            kind: "file",
+            startByte: 0,
+            endByte: source.length,
+            loc: source.split("\n").length,
+            bodyText: source.slice(0, MAX_BODY_TEXT_CHARS),
         });
     }
     symbols.sort((a, b) => a.startByte - b.startByte);
-    return { symbols, imports, calls, parseable: isParseable(tree.rootNode, spec) };
+    return { symbols, imports, calls, parseable: templated || isParseable(tree.rootNode, spec) };
 }
 /** True when every ERROR/MISSING node in the tree sits in an ancestor shape this
  *  language declares as a known grammar limitation (LanguageSpec.toleratedErrorScopes).
@@ -137,25 +171,35 @@ function ascendToDef(node, defNodeTypes) {
     return null;
 }
 /** Map each call site to the innermost symbol whose byte-range contains it.
- *  Keyed by the symbol's `startByte` (a stable per-symbol identity within the
- *  file) rather than its name, so two same-named symbols in one file don't merge
- *  their call sets. The value maps callee name -> `memberOnly` (true iff every
- *  occurrence was a `x.foo()` member call, never a direct `foo()`), so the
- *  indexer can resolve member calls conservatively. */
+ *  Keyed by the symbol's position (index) in `parsed.symbols` — NOT its
+ *  startByte, which is not a reliable per-symbol identity: a language whose
+ *  extractor merges a synthetic whole-file symbol with independently-derived
+ *  symbols (e.g. YAML's fallback-root synthetic symbol alongside Helm's
+ *  regex-derived `define` blocks) can produce two distinct symbols that both
+ *  start at byte 0. Indexing by array position is unique by construction,
+ *  regardless of byte overlap — the caller must consume the exact same
+ *  `parsed.symbols` array (or an equivalently-ordered copy) to look up a
+ *  symbol by the index this function returns. The value maps callee name ->
+ *  `memberOnly` (true iff every occurrence was a `x.foo()` member call, never
+ *  a direct `foo()`), so the indexer can resolve member calls conservatively. */
 export function attributeCalls(parsed) {
     const out = new Map();
     for (const call of parsed.calls) {
         let best = null;
-        for (const s of parsed.symbols) {
+        let bestIndex = -1;
+        for (let i = 0; i < parsed.symbols.length; i++) {
+            const s = parsed.symbols[i];
             if (call.atByte >= s.startByte && call.atByte < s.endByte) {
-                if (!best || s.endByte - s.startByte < best.endByte - best.startByte)
+                if (!best || s.endByte - s.startByte < best.endByte - best.startByte) {
                     best = s;
+                    bestIndex = i;
+                }
             }
         }
         if (best && best.name !== call.callee) {
-            if (!out.has(best.startByte))
-                out.set(best.startByte, new Map());
-            const m = out.get(best.startByte);
+            if (!out.has(bestIndex))
+                out.set(bestIndex, new Map());
+            const m = out.get(bestIndex);
             const prev = m.get(call.callee);
             m.set(call.callee, prev === undefined ? call.member : prev && call.member);
         }

package/dist/integrations/madrManifest.js

@@ -0,0 +1,251 @@
+/**
+ * MADR projection freshness — the manifest and the drift it feeds.
+ *
+ * The export half (madrExport.ts) renders the graph into a disposable MADR
+ * corpus. Nothing, until now, noticed when that corpus went stale: the wiki gets
+ * `wiki-stale` when its inputs move, but an exported ADR file could sit in
+ * `docs/adr/` confidently wrong forever. This closes that seam with the exact
+ * mechanism the wiki already proves out — a content-hash manifest, adopted on
+ * first export, silent when absent.
+ *
+ * Two hashes per file, and they answer different questions:
+ *   - `hash`  — the decision's projected content. Moves when the GRAPH moves,
+ *               so a mismatch means "the projection is behind the graph".
+ *   - `bytes` — the file as written. Moves when a HUMAN edits it, so a mismatch
+ *               means "someone hand-edited a generated file", which the export
+ *               marker warns against but nothing detected.
+ *
+ * Three findings, matching the three ways a projection can rot:
+ *   - madr-stale    the decision changed since export (or the file is gone)
+ *   - madr-edited   a generated file was hand-edited; the next export overwrites it
+ *   - madr-orphan   a generated file whose decision no longer exists in the graph
+ *
+ * All advisory, like every other drift kind: this is a smoke detector, not a
+ * robot that rewrites the corpus. `hunch export-adr` is the heal.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { writeFileAtomic } from "../core/io.js";
+import { hunchPaths } from "../core/paths.js";
+import { toPosixTarget } from "../core/paths.js";
+import { exportMadrCorpus, isRegenerableMadr } from "./madrExport.js";
+const sha16 = (s) => createHash("sha256").update(s).digest("hex").slice(0, 16);
+export function madrManifestPath(root) {
+    return join(hunchPaths(root).hunch, "madr-manifest.json");
+}
+export function readMadrManifest(root) {
+    try {
+        const raw = JSON.parse(readFileSync(madrManifestPath(root), "utf8"));
+        if (!raw || raw.version !== 1 || typeof raw.dir !== "string" || !raw.files || typeof raw.files !== "object")
+            return null;
+        // Drop malformed entries rather than crashing every drift-bearing command,
+        // the same tolerance readWikiManifestAt applies to a bad merge.
+        raw.files = Object.fromEntries(Object.entries(raw.files).filter(([, f]) => f && typeof f === "object" && typeof f.decision === "string" && typeof f.hash === "string"));
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeMadrManifest(root, manifest) {
+    writeFileAtomic(madrManifestPath(root), JSON.stringify(manifest, null, 2) + "\n");
+}
+/** The projected-content hash for one file. Content, not mtime: a re-export that
+ *  changes nothing must not read as drift. */
+export const madrContentHash = (text) => sha16(text);
+/**
+ * Build the manifest for a corpus that was just written.
+ *
+ * `written` carries the bytes actually placed on disk, which may differ from the
+ * rendered text when a file was refused (hand-written corpus in the target dir).
+ * Refused files are absent from the manifest, so they are never later reported
+ * as edited — they were never ours.
+ */
+export function buildMadrManifest(dir, entries, generatedAt) {
+    const files = {};
+    for (const e of entries) {
+        files[e.name] = {
+            decision: e.decisionId,
+            hash: madrContentHash(e.text),
+            bytes: sha16(e.text),
+            generated: generatedAt,
+        };
+    }
+    return { version: 1, dir: toPosixTarget(dir), files };
+}
+/**
+ * Drift for the MADR projection. Fires ONLY where a manifest exists — a repo that
+ * never ran `hunch export-adr` sees zero noise, matching the wiki's rule.
+ *
+ * Takes the PUBLIC decision list, never the overlay union: the projection is a
+ * committable artifact, so its freshness must be computed from exactly the
+ * records that are allowed to reach it. Passing the union here would leak the
+ * existence of overlay decisions into a public drift report.
+ */
+export function computeMadrDrift(publicDecisions, root) {
+    const manifest = readMadrManifest(root);
+    if (!manifest)
+        return []; // never exported → silent
+    const findings = [];
+    // Re-render from the current graph. Numbering is assigned per export, so a file
+    // name is only stable while the decision set is; compare by DECISION id, which
+    // is the thing that actually has identity.
+    const { files } = exportMadrCorpus(publicDecisions, manifest.dir);
+    const currentByDecision = new Map(files.map((f) => [f.decisionId, f]));
+    const liveIds = new Set(publicDecisions.map((d) => d.id));
+    for (const [name, entry] of Object.entries(manifest.files)) {
+        const rel = `${manifest.dir}/${name}`;
+        const abs = join(root, manifest.dir, name);
+        // 1. ORPHAN — the decision left the public graph (deleted, or moved to the
+        //    overlay). The file is now a public artifact with no record behind it,
+        //    which is the shape of a leak as much as of staleness.
+        if (!liveIds.has(entry.decision)) {
+            findings.push({
+                kind: "madr-orphan",
+                id: rel,
+                detail: `generated ADR has no decision in the public graph (${entry.decision} is gone or moved to the overlay) — delete it, or re-run \`hunch export-adr\``,
+            });
+            continue;
+        }
+        // 2. MISSING — manifested but not on disk.
+        if (!existsSync(abs)) {
+            findings.push({
+                kind: "madr-stale",
+                id: rel,
+                detail: `generated ADR for ${entry.decision} is missing from ${manifest.dir}/ — regenerate with \`hunch export-adr\``,
+            });
+            continue;
+        }
+        let onDisk;
+        try {
+            onDisk = readFileSync(abs, "utf8");
+        }
+        catch {
+            continue; // unreadable is an environment problem, not memory drift
+        }
+        // 3. HAND-EDITED — the bytes moved and the marker is still there, so the next
+        //    export silently overwrites human work. Report before that happens.
+        //    A file whose marker was REMOVED is deliberately not ours any more: the
+        //    export already refuses it, and calling that drift would nag forever.
+        if (sha16(onDisk) !== entry.bytes && isRegenerableMadr(onDisk)) {
+            findings.push({
+                kind: "madr-edited",
+                id: rel,
+                detail: `generated ADR was hand-edited — \`hunch export-adr\` will overwrite it. Move the change into decision ${entry.decision} (\`/capture\`), or drop the hunch:generated marker to adopt the file`,
+            });
+        }
+        // 4. STALE — the graph moved underneath the projection.
+        const current = currentByDecision.get(entry.decision);
+        if (current && madrContentHash(current.text) !== entry.hash) {
+            findings.push({
+                kind: "madr-stale",
+                id: rel,
+                detail: `decision ${entry.decision} changed since export — regenerate with \`hunch export-adr\``,
+            });
+        }
+    }
+    // 5. UNEXPORTED — a public decision with no file at all. Only reported once a
+    //    corpus exists, so adopting the export does not immediately indict every
+    //    decision recorded before it.
+    const manifested = new Set(Object.values(manifest.files).map((f) => f.decision));
+    const missing = publicDecisions.filter((d) => !manifested.has(d.id));
+    if (missing.length) {
+        findings.push({
+            kind: "madr-stale",
+            id: manifest.dir,
+            detail: `${missing.length} public decision(s) have no ADR in ${manifest.dir}/ (e.g. ${missing[0].id}) — regenerate with \`hunch export-adr\``,
+        });
+    }
+    return findings;
+}
+export function refreshMadrCorpus(publicDecisions, root, now) {
+    const manifest = readMadrManifest(root);
+    if (!manifest)
+        return null; // never adopted → stay out of the way
+    const { files } = exportMadrCorpus(publicDecisions, manifest.dir);
+    const outDir = join(root, manifest.dir);
+    if (!existsSync(outDir))
+        return null; // corpus deleted wholesale; drift reports it
+    const skippedEdited = [];
+    const kept = [];
+    /** Manifest entries carried through verbatim (hand-edited files we refused to touch). */
+    const preserved = new Map();
+    let written = 0;
+    // Edit detection is keyed by CONTENT, not by file name. Numbering is assigned
+    // per export, so adding one decision shifts every later file to a new name —
+    // a name-keyed check then finds no prior entry for the shifted name, calls the
+    // hand-edited file at that path "stale", and overwrites it (and the removal
+    // sweep would delete it under its old name). Bytes we have ever written are
+    // exactly the manifest's `bytes` values: an on-disk generated file whose hash
+    // is not among them was edited by a human, whatever it is currently called.
+    const knownBytes = new Set(Object.values(manifest.files).map((entry) => entry.bytes));
+    for (const f of files) {
+        const abs = join(outDir, f.name);
+        const prior = manifest.files[f.name];
+        if (existsSync(abs)) {
+            let onDisk;
+            try {
+                onDisk = readFileSync(abs, "utf8");
+            }
+            catch {
+                continue;
+            }
+            // Someone else's file: leave it alone (its decision then surfaces as
+            // "no ADR" drift rather than being silently unrepresented).
+            if (!isRegenerableMadr(onDisk))
+                continue;
+            if (onDisk === f.text) {
+                kept.push(f);
+                continue; // already current — no write, no churn
+            }
+            const bytes = sha16(onDisk);
+            const edited = prior ? bytes !== prior.bytes : !knownBytes.has(bytes);
+            if (edited) {
+                skippedEdited.push(f.name);
+                // Carry the PRIOR entry through untouched (when one exists). Rebuilding
+                // it from the edited bytes would make the file match its own manifest
+                // and the edit would stop being reported — the refresh would quietly
+                // launder a hand edit into the record of what we generated.
+                if (prior)
+                    preserved.set(f.name, prior);
+                continue;
+            }
+        }
+        writeFileAtomic(abs, f.text);
+        kept.push(f);
+        written++;
+    }
+    // Drop generated files the new numbering no longer produces — but ONLY files
+    // whose bytes we wrote. An edited file under its old name is preserved (with
+    // its manifest entry, so madr-edited keeps firing) rather than deleted: this
+    // sweep was the second way a renumbering could destroy a human's edit.
+    let removed = 0;
+    const produced = new Set(files.map((f) => f.name));
+    for (const name of Object.keys(manifest.files)) {
+        if (produced.has(name))
+            continue;
+        const abs = join(outDir, name);
+        if (!existsSync(abs))
+            continue;
+        try {
+            const onDisk = readFileSync(abs, "utf8");
+            if (!isRegenerableMadr(onDisk))
+                continue;
+            if (!knownBytes.has(sha16(onDisk))) {
+                skippedEdited.push(name);
+                preserved.set(name, manifest.files[name]);
+                continue;
+            }
+            rmSync(abs);
+            removed++;
+        }
+        catch { /* best effort */ }
+    }
+    const next = buildMadrManifest(manifest.dir, kept, now);
+    for (const [name, entry] of preserved)
+        next.files[name] = entry;
+    writeMadrManifest(root, next);
+    return { dir: manifest.dir, written, removed, skippedEdited };
+}
+//# sourceMappingURL=madrManifest.js.map

package/dist/mcp/server.js

@@ -73,10 +73,21 @@ const flushNote = (flush, home, mode) => flush === "pushed" ? ` (committed + pus
  *  lands in the committed store publishes on the next push, and an agent writing
  *  strategy/competitive content there is a leak nobody notices until it ships
  *  (2026-08-09: 15 roadmap records caught pre-push only by a release sweep). */
-/** Repo-local term list, read once per server process. The package ships none;
- *  `.hunch/publication.json` is how a repo opts in (see src/core/publication.ts). */
-let vocabularyCache = null;
-const publicationVocabulary = (hunchDir) => (vocabularyCache ??= loadVocabulary(hunchDir));
+/** Repo-local term list, read once per STORE. The package ships none;
+ *  `.hunch/publication.json` is how a repo opts in (see src/core/publication.ts).
+ *  Keyed by hunchDir: the previous scalar memoized the FIRST store's vocabulary
+ *  and served it to every store in the process, so a multi-store consumer would
+ *  leak-scan project B's records against project A's terms — a wrong answer in
+ *  the exact subsystem whose job is catching leaks (GATE-P1-UPSTREAM.md). */
+const vocabularyCache = new Map();
+export const publicationVocabulary = (hunchDir) => {
+    let vocab = vocabularyCache.get(hunchDir);
+    if (!vocab) {
+        vocab = loadVocabulary(hunchDir);
+        vocabularyCache.set(hunchDir, vocab);
+    }
+    return vocab;
+};
 const publicHomeNote = (home, hasPrivate, record, hunchDir) => {
     if (home !== "public")
         return "";
@@ -280,6 +291,9 @@ function prepareRoot(root, explicitOverlay, requireIndex) {
     ensureTeamOverlay(root);
     const store = new HunchStore(hunchPaths(root));
     try {
+        const overlayWarning = store.overlayResolutionWarning(explicitOverlay && existsSync(teamFile));
+        if (overlayWarning)
+            console.error(`[hunch-mcp] ⚠ ${overlayWarning}`);
         if (teamAdvertised && (store.mode !== "shared"
             || !store.privateDir
             || !existsSync(store.privateDir)

package/dist/store/hunchStore.js

@@ -55,6 +55,13 @@ export class HunchStore {
     /** The resolved private-overlay hunch dir (from env or .hunch/local.json), or undefined
      *  when no overlay is configured. Surfaced so `hunch doctor` reflects the true state. */
     privateDir;
+    /** How privateDir was selected. Multi-store consumers can use this instead of
+     *  inferring process-global routing from process.env. */
+    overlaySource;
+    /** Present only when HUNCH_PRIVATE_DIR redirects this store away from the
+     *  repo/worktree-local pointer. Precedence is compatibility-sensitive and stays
+     *  env-first; making the redirection queryable removes the silent footgun. */
+    overlayOverride;
     /** Whether captures auto-commit the store they land in — ON by default in EVERY mode;
      *  `--no-auto-commit` (hunch init/private/shared) persists `autoCommit: false` in
      *  local.json to opt out. Read by the MCP write tools and `hunch sync`. */
@@ -84,7 +91,36 @@ export class HunchStore {
         // local config (.hunch/local.json) so `hunch private` enables it with NO env var, and
         // the MCP server / hook pick it up automatically. Relative paths resolve from root.
         const local = this.localConfig();
-        const priv = process.env.HUNCH_PRIVATE_DIR?.trim() || local.privateDir;
+        const environmentDir = process.env.HUNCH_PRIVATE_DIR?.trim();
+        const configuredDir = local.privateDir
+            ? resolve(this.paths.root, local.privateDir)
+            : undefined;
+        const resolvedEnvironmentDir = environmentDir
+            ? resolve(this.paths.root, environmentDir)
+            : undefined;
+        const priv = resolvedEnvironmentDir || configuredDir;
+        this.overlaySource = resolvedEnvironmentDir
+            ? "environment"
+            : configuredDir
+                ? "local-config"
+                : null;
+        if (resolvedEnvironmentDir && configuredDir) {
+            const canonical = (path) => {
+                try {
+                    return realpathSync(path);
+                }
+                catch {
+                    return resolve(path);
+                }
+            };
+            const comparable = (path) => process.platform === "win32" ? canonical(path).toLowerCase() : canonical(path);
+            if (comparable(resolvedEnvironmentDir) !== comparable(configuredDir)) {
+                this.overlayOverride = {
+                    configuredDir: canonical(configuredDir),
+                    environmentDir: canonical(resolvedEnvironmentDir),
+                };
+            }
+        }
         if (priv) {
             const candidate = resolve(this.paths.root, priv);
             const canonical = (path) => { try {
@@ -118,6 +154,21 @@ export class HunchStore {
         this.mode = priv ? (local.mode ?? "private") : "public";
         this.unified = this.mode === "shared" && !!this.privateJson;
     }
+    /** Human-facing warning for the compatibility-preserving env-first resolution.
+     *  Callers decide where it is safe to emit (CLI/MCP stderr, doctor output); the
+     *  store constructor stays side-effect-free for hooks and embedded consumers. */
+    overlayResolutionWarning(teamConfigBypassed = false) {
+        if (this.overlayOverride) {
+            const effect = this.mode === "shared"
+                ? "all memory reads and captures in this process use the environment path"
+                : "private-overlay reads and private captures in this process use the environment path; public captures remain in the repo";
+            return `HUNCH_PRIVATE_DIR redirects this repo from its configured ${this.mode} memory at ${this.overlayOverride.configuredDir} to ${this.overlayOverride.environmentDir}; ${effect} (routing mode remains ${this.mode}). Unset HUNCH_PRIVATE_DIR to use the configured store.`;
+        }
+        if (this.overlaySource === "environment" && teamConfigBypassed && this.privateDir) {
+            return `HUNCH_PRIVATE_DIR bypasses .hunch/team.json and selects ${this.privateDir} in ${this.mode} mode; team-store auto-discovery is disabled for this process. Unset HUNCH_PRIVATE_DIR to use the advertised team store.`;
+        }
+        return null;
+    }
     /** Where a capture belongs: an explicit private:true always goes to the overlay
      *  (putPrivate throws rather than silently landing public when none is configured);
      *  otherwise the overlay in unified ("shared") mode, else the public store. ONE home
@@ -313,11 +364,35 @@ export class HunchStore {
                 fts(c.id, "components", c.name, `${c.responsibility} ${c.paths.join(" ")}`);
             }
             counts.components = comps.length;
+            const resources = this.recs("resources");
+            const insResource = db.prepare(`INSERT INTO resources VALUES (@id,@schema,@kind,@name,@scope,@locator,@lifecycle,@criticality,@contract_version,@currentness,@metadata,@ps,@pc,@pe,@created_at,@updated_at)`);
+            for (const resource of resources) {
+                insResource.run({
+                    id: resource.id, schema: resource.schema, kind: resource.kind, name: resource.name,
+                    scope: JSON.stringify(resource.scope), locator: resource.locator, lifecycle: resource.lifecycle,
+                    criticality: resource.criticality ?? null, contract_version: resource.contract_version ?? null,
+                    currentness: JSON.stringify(resource.currentness), metadata: JSON.stringify(resource.metadata),
+                    ps: resource.provenance.source, pc: resource.provenance.confidence,
+                    pe: JSON.stringify(resource.provenance.evidence), created_at: resource.created_at, updated_at: resource.updated_at,
+                });
+                fts(resource.id, "resources", resource.name, `${resource.kind} ${resource.scope.join(" ")} ${resource.locator ?? ""} ${resource.lifecycle} ${resource.contract_version ?? ""}`);
+            }
+            counts.resources = resources.length;
             const edges = this.recs("edges");
             const insEdge = db.prepare(`INSERT INTO edges VALUES (@id,@from,@to,@type,@reason,@strength,@ps,@pc,@pe)`);
+            const insResourceRelationship = db.prepare(`INSERT INTO resource_relationships VALUES (@id,@schema,@from,@to,@type,@reason,@strength,@currentness,@environment,@criticality,@contract_version,@metadata,@ps,@pc,@pe)`);
             for (const e of edges) {
                 insEdge.run({ id: e.id, from: e.from, to: e.to, type: e.type, reason: e.reason, strength: e.strength,
                     ps: e.provenance.source, pc: e.provenance.confidence, pe: JSON.stringify(e.provenance.evidence) });
+                if (e.schema === "hunch.resource-relationship/1") {
+                    insResourceRelationship.run({
+                        id: e.id, schema: e.schema, from: e.from, to: e.to, type: e.type, reason: e.reason,
+                        strength: e.strength, currentness: JSON.stringify(e.currentness), environment: e.environment,
+                        criticality: e.criticality ?? null, contract_version: e.contract_version ?? null,
+                        metadata: JSON.stringify(e.metadata), ps: e.provenance.source, pc: e.provenance.confidence,
+                        pe: JSON.stringify(e.provenance.evidence),
+                    });
+                }
             }
             counts.edges = edges.length;
             const syms = this.recs("symbols");
@@ -592,7 +667,11 @@ export class HunchStore {
             }
             // w > 1 (a trigger match) shifts UP, w < 1 shifts DOWN, both clamped.
             const shift = Math.max(-MAX_PRIOR_SHIFT, Math.min(MAX_PRIOR_SHIFT, (1 - w) * PRIOR_SHIFT_SCALE));
-            return { h, pos: pos + shift };
+            // Recorded intent outranks code that merely shares the query's vocabulary. Applied
+            // OUTSIDE the clamp above: that bound keeps the trust dimmer from becoming the sort
+            // key, whereas this is a kind-level tie-break between two different answer types.
+            const memory = MEMORY_KINDS.has(h.kind) ? -MEMORY_PRIOR_SHIFT : 0;
+            return { h, pos: pos + shift + memory };
         });
         scored.sort((a, b) => a.pos - b.pos);
         return scored.slice(0, limit).map((x) => x.h);
@@ -1320,6 +1399,7 @@ export class HunchStore {
         };
         json.put("decisions", closed);
         const edge = {
+            schema: "hunch.edge/1",
             id: edgeId(by.id, oldId, "supersedes"),
             from: by.id,
             to: oldId,
@@ -1327,6 +1407,8 @@ export class HunchStore {
             reason: `${by.id} supersedes ${oldId}`,
             strength: 1,
             provenance: { source: "derived", confidence: 1, evidence: [by.id, oldId] },
+            environment: null,
+            metadata: {},
         };
         json.put("edges", edge);
         return closed;
@@ -1643,6 +1725,18 @@ 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);
+/** 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
+ *  with thousands of indexed symbols a lexical tie let them occupy the whole top-k
+ *  and bury the one live decision — including a topic-chain successor that promotion
+ *  had correctly injected just below the cut line. This lifts memory records by a
+ *  bounded number of positions; it never EXCLUDES a kind (a symbol-name query still
+ *  returns symbols, and a constraint stays reachable), it only breaks the tie toward
+ *  intent. Measured on bench/golden-retrieval.json: Recall@10 70% -> 90%, MRR
+ *  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 numEnv(name, dflt) {
     const v = Number(process.env[name]);
     // >= 0, not > 0: zero is the documented kill-switch (HUNCH_RRF_W_*=0 disables

package/dist/store/jsonStore.js

@@ -12,7 +12,14 @@ import { writeFileAtomic } from "../core/io.js";
  *  index.json array — there can be thousands, and one file per edge would create
  *  enormous git noise. Curated, low-volume entities (components, decisions, bugs,
  *  constraints) are one file per record so they're cleanly reviewable in PRs. */
-const SINGLE_FILE = { symbols: "index.json", edges: "index.json" };
+const SINGLE_FILE = {
+    symbols: "index.json",
+    edges: "index.json",
+    // Resource ids remain readable kind-qualified identities (and may contain '/'),
+    // so the canonical array avoids lossy filename encoding while keeping Git diffs
+    // deterministic through id sorting.
+    resources: "index.json",
+};
 const encode = (v) => JSON.stringify(v, null, 2) + "\n";
 // Sleep primitive for the single-file RMW lock's bounded spin (issue #35);
 // same idiom as core/io.ts's rename backoff.

package/dist/store/schema.js

@@ -29,6 +29,17 @@ CREATE TABLE IF NOT EXISTS components (
   created_at TEXT, updated_at TEXT
 );
 
+CREATE TABLE IF NOT EXISTS resources (
+  id TEXT PRIMARY KEY,
+  schema TEXT, kind TEXT, name TEXT, scope TEXT, locator TEXT,
+  lifecycle TEXT, criticality TEXT, contract_version TEXT,
+  currentness TEXT, metadata TEXT,
+  prov_source TEXT, prov_confidence REAL, prov_evidence TEXT,
+  created_at TEXT, updated_at TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_resources_kind ON resources(kind);
+CREATE INDEX IF NOT EXISTS idx_resources_lifecycle ON resources(lifecycle);
+
 CREATE TABLE IF NOT EXISTS edges (
   id TEXT PRIMARY KEY,
   "from" TEXT, "to" TEXT, type TEXT, reason TEXT, strength REAL,
@@ -38,6 +49,18 @@ CREATE INDEX IF NOT EXISTS idx_edges_from ON edges("from");
 CREATE INDEX IF NOT EXISTS idx_edges_to ON edges("to");
 CREATE INDEX IF NOT EXISTS idx_edges_type ON edges(type);
 
+-- A rebuildable projection over the subset of the existing edge graph carrying
+-- the resource-relationship contract. JSON edges remain the one authority.
+CREATE TABLE IF NOT EXISTS resource_relationships (
+  id TEXT PRIMARY KEY,
+  schema TEXT, "from" TEXT, "to" TEXT, type TEXT, reason TEXT, strength REAL,
+  currentness TEXT, environment TEXT, criticality TEXT, contract_version TEXT,
+  metadata TEXT, prov_source TEXT, prov_confidence REAL, prov_evidence TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_resource_relationships_from ON resource_relationships("from");
+CREATE INDEX IF NOT EXISTS idx_resource_relationships_to ON resource_relationships("to");
+CREATE INDEX IF NOT EXISTS idx_resource_relationships_type ON resource_relationships(type);
+
 CREATE TABLE IF NOT EXISTS symbols (
   id TEXT PRIMARY KEY,
   file TEXT, name TEXT, kind TEXT, signature_hash TEXT,
@@ -89,7 +112,7 @@ CREATE TABLE IF NOT EXISTS embeddings (
 export const FTS_SEARCH_SCHEMA_SQL = /* sql */ `
 CREATE VIRTUAL TABLE IF NOT EXISTS search USING fts5(
   ref UNINDEXED,   -- entity id
-  kind UNINDEXED,  -- components | edges | symbols | decisions | bugs | constraints | runbooks | findings
+  kind UNINDEXED,  -- components | resources | edges | symbols | decisions | bugs | constraints | runbooks | findings
   title,
   body,
   tokenize = 'porter unicode61'
@@ -110,7 +133,7 @@ CREATE INDEX IF NOT EXISTS idx_search_kind ON search(kind);
 /** Drop derived data (used before a full reindex). NOTE: embeddings is omitted on
  *  purpose — see the embeddings table comment above. */
 export const RESET_SQL = /* sql */ `
-DELETE FROM components; DELETE FROM edges; DELETE FROM symbols;
+DELETE FROM components; DELETE FROM resources; DELETE FROM edges; DELETE FROM resource_relationships; DELETE FROM symbols;
 DELETE FROM decisions; DELETE FROM bugs; DELETE FROM constraints;
 DELETE FROM search;
 `;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.16.0",
+  "version": "1.18.0",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
@@ -71,11 +71,12 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@tree-sitter-grammars/tree-sitter-yaml": "^0.6.1",
     "commander": "^15.0.0",
     "tree-sitter": "0.21.1",
     "tree-sitter-go": "^0.23.4",
-    "tree-sitter-python": "^0.23.2",
+    "tree-sitter-python": "0.23.4",
     "tree-sitter-typescript": "^0.23.2",
     "zod": "^4.4.3"
   },