@davesheffer/hunch 1.16.0 → 1.17.0

package/README.md

@@ -6,9 +6,10 @@
 [![GitHub stars](https://img.shields.io/github/stars/davesheffer/hunch?color=2742ff&label=%E2%98%85%20star)](https://github.com/davesheffer/hunch)
 [![license](https://img.shields.io/npm/l/@davesheffer/hunch?color=2742ff)](LICENSE)
 
-Hunch is the engineering-memory and architectural-conformance layer for AI-assisted codebases. It
-records the decisions, constraints, rejected approaches, and bug history behind your code, delivers
-the relevant evidence before an assistant changes anything, then checks the result deterministically.
+Hunch is a guarantee: **your agents never re-make a decided decision, and never re-introduce a
+fixed bug.** The mechanism behind it is an engineering-memory and architectural-conformance layer —
+the decisions, constraints, rejected approaches, and bug history behind your code, delivered as
+evidence before an assistant changes anything, with the result checked deterministically after.
 
 Memory starts **advisory**. Nothing blocks until you explicitly trust a precise rule and choose
 strict enforcement.
@@ -16,8 +17,10 @@ strict enforcement.
 **Memory is the input. The product boundary is the receipt:** relevant evidence before an edit,
 then a deterministic check of the change against the rules your team has explicitly trusted.
 
-> **New in v1.13.1:** `hunch_context` exposes that provenance-checked, hard-budgeted delivery
-> envelope as MCP structured output and records exactly which returned items reached the client.
+> **New in v1.17.0:** an exported ADR corpus now tracks the graph automatically and reports its
+> own drift (`madr-stale` / `madr-edited` / `madr-orphan`), and retrieval ranks recorded intent
+> above code symbols that merely share the query's vocabulary — Recall@10 70% → 90% on the
+> curated benchmark.
 
 See the public [roadmap](ROADMAP.md) for what is next and what is deliberately out of scope.
 
@@ -47,8 +50,11 @@ to the same graph. It merges into existing configuration instead of replacing it
 - **Change receipts** — review a working tree, commit, or branch against recorded intent and get a
   cited PASS / WARN / BLOCK result.
 - **Bug lineage** — understand which old incident a line fixed before accidentally undoing it.
-- **Code awareness** — TypeScript, JavaScript, and Python structure feed dependency, blast-radius,
-  and redundancy checks. The reasoning layer works with any language.
+- **Code awareness** — TypeScript, JavaScript, Python, and Go structure feed dependency,
+  blast-radius, and redundancy checks. The reasoning layer works with any language.
+- **ADR interop** — `hunch import-adr` populates the graph from an existing MADR/Nygard corpus;
+  `hunch export-adr` projects it back as standard MADR any ADR reader understands, and the
+  projection then tracks the graph automatically and reports its own drift.
 
 The source of truth is readable JSON in `.hunch/`. A local SQLite index makes retrieval fast but
 is always rebuildable.

package/dist/cli/index.js

@@ -73,6 +73,7 @@ import { adoptProsePrompt } from "../wiki/adopt.js";
 import { topicCollisions, isInForce, liveForTopic } from "../core/topics.js";
 import { ADR_DIR_CANDIDATES, ADR_FILE_RE, mapAdrCorpus } from "../extractors/adrImport.js";
 import { exportMadrCorpus, isRegenerableMadr } from "../integrations/madrExport.js";
+import { buildMadrManifest, writeMadrManifest, refreshMadrCorpus } from "../integrations/madrManifest.js";
 import { pendingEscalations, policyEscalations } from "../core/escalations.js";
 import { premiseEscalations } from "../core/premises.js";
 import { parseDocAnchors, renderDocGrounding } from "../core/docanchors.js";
@@ -500,6 +501,21 @@ program
     else if (!opts.quiet) {
         console.log(`· skipped: ${r.reason}`);
     }
+    // The MADR projection tracks the graph automatically once adopted, the way the
+    // SQLite index does — a user who ran `hunch export-adr` once never runs it again.
+    // Best-effort and last-write-wins-free: a hand-edited file is skipped, not
+    // clobbered, and any failure here must never affect the capture that preceded it.
+    try {
+        const refreshed = refreshMadrCorpus(store.json.loadAll("decisions"), root, new Date().toISOString());
+        if (refreshed && !opts.quiet && (refreshed.written || refreshed.removed || refreshed.skippedEdited.length)) {
+            const skipped = refreshed.skippedEdited.length ? `, ${refreshed.skippedEdited.length} hand-edited file(s) left alone` : "";
+            console.log(`  ↳ ADR corpus refreshed: ${refreshed.written} written, ${refreshed.removed} removed${skipped} (${refreshed.dir}/)`);
+        }
+    }
+    catch (e) {
+        if (!opts.quiet)
+            console.log(`  ↳ ADR corpus refresh skipped safely: ${e.message}`);
+    }
     let graphRefreshed = false;
     let publicCorrectionQueued = false;
     let privateCorrectionQueued = false;
@@ -3097,6 +3113,10 @@ program
         // are OURS (marker-verified) and stale — remove so the corpus stays coherent.
         for (const f of stale)
             rmSync(join(outDir, f));
+        // Adopt the corpus: the manifest is what makes `hunch drift` able to notice
+        // this projection going stale, being hand-edited, or outliving its decision.
+        // Written after the files land, so a failed write never claims freshness.
+        writeMadrManifest(root, buildMadrManifest(dir, files, new Date().toISOString()));
         console.log(`✓ exported ${files.length} ADR(s) to ${dir}${stale.length ? `; removed ${stale.length} stale generated file(s)` : ""}`);
         console.log(`  ↳ Backstage: add to catalog-info.yaml metadata.annotations →  ${backstageAnnotation}`);
     }
@@ -5223,6 +5243,30 @@ program
                 console.log(`· ${f.id} — ${f.detail}`);
             console.log(`\nHeal: run \`hunch wiki --heal\` — regenerates only the stale pages (the wiki is a derived view; never edit it by hand).\n`);
         }
+        // The MADR projection: three kinds, three different human actions — which is
+        // why they are separate sections rather than one "run export-adr" line.
+        const madrStale = kind("madr-stale");
+        if (madrStale.length) {
+            console.log(`${madrStale.length} exported ADR(s) drifted from the graph:\n`);
+            for (const f of madrStale)
+                console.log(`· ${f.id} — ${f.detail}`);
+            console.log(`\nHeal: run \`hunch export-adr\` — the corpus is a disposable projection (the graph stays the source of truth). Normally this never appears: the projection refreshes automatically on every capture.\n`);
+        }
+        const madrEdited = kind("madr-edited");
+        if (madrEdited.length) {
+            console.log(`${madrEdited.length} generated ADR(s) were hand-edited — the next export would overwrite them:\n`);
+            for (const f of madrEdited)
+                console.log(`· ${f.id} — ${f.detail}`);
+            console.log(`\nHeal A (the DECISION is what changed): move the edit into the decision via /capture, then let the projection regenerate — the edit survives because it now lives in the graph.`);
+            console.log(`Heal B (you want to own this file): delete the hunch:generated marker. The export refuses it from then on and it becomes a hand-written ADR.\n`);
+        }
+        const madrOrphan = kind("madr-orphan");
+        if (madrOrphan.length) {
+            console.log(`${madrOrphan.length} generated ADR(s) have no decision behind them any more:\n`);
+            for (const f of madrOrphan)
+                console.log(`· ${f.id} — ${f.detail}`);
+            console.log(`\nHeal: delete the file, or run \`hunch export-adr\` to regenerate the corpus without it. If the decision moved to the private overlay, the file is a PUBLIC artifact of a now-private record — delete it.\n`);
+        }
         // Every drift kind heals here — see bug_drift_heal_asymmetry above. premise-stale
         // shipped in the drift report without a section here, so a repo whose ONLY drift
         // was a dead premise got "N findings" from `hunch drift` and a bare closing line

package/dist/core/drift.js

@@ -11,6 +11,11 @@
  *                 (hash-compared via .hunch/wiki-manifest.json; only when a wiki
  *                 was adopted — see src/wiki/wiki.ts). Advisory, healed by
  *                 `hunch wiki --heal`, never a gate.
+ *   - madr-*:     the exported MADR corpus drifted from the graph — stale (the
+ *                 decision moved), edited (a human changed a generated file the
+ *                 next export would overwrite), or orphan (the decision left the
+ *                 public graph). Only when a corpus was exported; healed by
+ *                 `hunch export-adr`. See src/integrations/madrManifest.ts.
  */
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
@@ -20,6 +25,7 @@ import { evaluatePremises } from "./premises.js";
 import { parseDocAnchors } from "./docanchors.js";
 import { markdownDocs, STALE_MARKER, SRC_REF } from "./docscan.js";
 import { computeWikiDrift } from "../wiki/wiki.js";
+import { computeMadrDrift } from "../integrations/madrManifest.js";
 export function computeDrift(store, root) {
     const findings = [];
     const decisions = store.recs("decisions");
@@ -142,6 +148,12 @@ export function computeDrift(store, root) {
     //    component vanished). Deterministic hash comparison against the manifest;
     //    fires only when a wiki was adopted. Advisory like every other kind here.
     findings.push(...computeWikiDrift(store, root));
+    // 6b. MADR-* — the exported ADR corpus drifted from the graph. PUBLIC decisions
+    //     only: the corpus is a committable artifact, so its freshness must be
+    //     computed from exactly the records allowed to reach it (an overlay record
+    //     leaking into a public drift report is the same class of bug as one
+    //     leaking into the export itself). Fires only where a corpus was exported.
+    findings.push(...computeMadrDrift(store.json.loadAll("decisions"), root));
     // 7. FINDING-STALE — a LIVE finding (observation, no diff) whose anchor evaporated:
     //    an affected file that no longer exists, or a violates_constraint pointing at a
     //    retired/missing rule. Deterministic + advisory (never the exit-code class):

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/store/hunchStore.js

@@ -592,7 +592,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);
@@ -1643,6 +1647,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "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.16.0",
+  "version": "1.17.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.16.0",
+      "version": "1.17.0",
       "runtimeHint": "npx",
       "packageArguments": [
         {