@davesheffer/hunch 1.9.3 → 1.10.0

package/README.md

@@ -16,10 +16,9 @@ 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.9.3:** Matrix mode gives the whole team one live, private Git memory across fresh
-> clones, worktrees, CLI checks, and MCP assistants. npm publishes with short-lived OIDC
-> credentials, while the editor companion ships as one immutable, publicly verified Open VSX
-> artifact.
+> **New in v1.9.4:** MCP connections stay collision-safe across repositories and simultaneous
+> captures, while generated MCP, hook, plugin, and CI commands pin the exact npm release that
+> created them.
 
 ## Start in five minutes
 
@@ -82,7 +81,7 @@ Git repo that every teammate can access, install the Matrix release on team mach
 have one maintainer run:
 
 ```bash
-npm i -g @davesheffer/hunch@1.9.3
+npm i -g @davesheffer/hunch@1.9.4
 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"
@@ -97,7 +96,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.9.3
+npm i -g @davesheffer/hunch@1.9.4
 git pull
 hunch init
 hunch doctor

package/dist/cli/index.js

@@ -3855,7 +3855,7 @@ program
         // from this file. No diff exists yet, so this is context — "don't re-add X" —
         // not a block; the commit-time `hunch check` does the actual gating.
         const retired = store.retiredForFile(target).filter((r) => r.symbols.length || r.deps.length);
-        const hasContent = ctx.constraints.length || ctx.decisions.length || ctx.bugs.length || ctx.blast_radius.length || retired.length || docGround;
+        const hasContent = ctx.constraints.length || ctx.decisions.length || ctx.bugs.length || ctx.blast_radius.length || ctx.findings.length || retired.length || docGround;
         if (!hasContent)
             return; // no noise on files Hunch hasn't learned yet
         let text = formatContext(ctx).trim();
@@ -4538,6 +4538,34 @@ program
         store.close();
     }
 });
+// ---- findings (the open-observations ledger) --------------------------------
+program
+    .command("findings")
+    .description("LIVE findings — observed gaps/debt with no fix landed yet (audits, measurements, incidents; anchored to a date + evidence, not a commit). Same store method as the hunch_findings MCP tool. Read-only, advisory.")
+    .argument("[scope]", "a path, glob, or symbol (e.g. src/procs/** or dbo.GetOrders); omit for all")
+    .option("--all", "include resolved/stale findings (the full history)")
+    .action((scope, opts) => {
+    const { store } = storeFor();
+    try {
+        const live = (f) => f.triage === "open" || f.triage === "accepted-risk" || f.triage === "scheduled";
+        const list = (scope ? store.liveFindingsFor(scope) : store.recs("findings").filter(opts.all ? () => true : live))
+            .filter(opts.all ? () => true : live);
+        if (!list.length) {
+            console.log(`No ${opts.all ? "" : "live "}findings${scope ? ` for "${scope}"` : ""}. Record one after an audit: /audit (or hunch_record_finding via MCP).`);
+            return;
+        }
+        for (const f of list) {
+            const links = [f.violates_constraint ? `violates ${f.violates_constraint}` : "", f.method ? `re-verify via ${f.method}` : "", f.resolved_commit ? `fixed in ${f.resolved_commit.slice(0, 9)}` : ""].filter(Boolean).join(" · ");
+            console.log(`• [${f.triage}/${f.severity}] ${f.title} (${f.id}, observed ${f.observed_at.slice(0, 10)})`);
+            console.log(`    ${f.observation}`);
+            console.log(`    concerns: ${[...f.affected_files, ...f.affected_symbols].join(", ") || "(unscoped)"}${links ? `\n    ${links}` : ""}`);
+        }
+        console.log(`\n${list.length} finding(s).`);
+    }
+    finally {
+        store.close();
+    }
+});
 // ---- path (shortest dependency chain) --------------------------------------
 program
     .command("path")

package/dist/cli/invocation.js

@@ -6,11 +6,16 @@
  *  same import-safety to be unit-testable. */
 import { fileURLToPath } from "node:url";
 import { probeOllamaNumCtx } from "../synthesis/provider.js";
-/** Published package name — used for OS-agnostic invocations (see below). */
-const PKG = "@davesheffer/hunch";
+import { HUNCH_NPX_PACKAGE_SPEC } from "../core/version.js";
 export function dim(s) {
     return `\x1b[2m${s}\x1b[0m`;
 }
+/** Portable invocation written into committed MCP/provider configuration.
+ * Keep it independently testable so the distribution pin cannot silently
+ * regress to npm's moving latest tag. */
+export function publishedMcpInvocation() {
+    return { command: "npx", args: ["-y", `--package=${HUNCH_NPX_PACKAGE_SPEC}`, "hunch"] };
+}
 /** The doctor command's synthesis-status line(s) for a resolved provider.
  *  Exported for testing — the previous version (a bare provider-name switch,
  *  before the resolveSynthesisProvider preference system existed) had zero
@@ -65,15 +70,16 @@ export function resolveInvocation() {
     // Running from an installed copy (global, local, or npx cache — i.e. NOT a
     // source checkout we're hacking on). The MCP/provider config files we write
     // are committed and shared across a team via git, so they must NOT embed this
-    // machine's absolute path or OS-specific separators. Reference Hunch by its
-    // published package name instead, which `npx` resolves the same on any OS and
-    // any clone. The git hook lives in per-machine .git/hooks (never committed),
-    // so it keeps the PATH-robust absolute-node invocation below.
+    // machine's absolute path or OS-specific separators. Reference the exact
+    // published Hunch package instead, which `npx` resolves the same on any OS
+    // and any clone without floating to a newer release. The git hook lives in
+    // per-machine .git/hooks (never committed), so it keeps the PATH-robust
+    // absolute-node invocation below.
     const installed = !isDev && entry.replace(/\\/g, "/").includes("/node_modules/");
     if (installed) {
         return {
             shell: `${q(process.execPath)} ${q(entry)}`,
-            mcp: { command: "npx", args: ["-y", PKG] },
+            mcp: publishedMcpInvocation(),
         };
     }
     if (isDev) {

package/dist/core/drift.js

@@ -118,6 +118,31 @@ 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));
+    // 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):
+    //    the observation may be fixed, moved, or moot — re-verify (re-run its method)
+    //    and re-record with triage resolved/stale, or refresh its paths.
+    for (const f of store.recs("findings")) {
+        if (f.triage === "resolved" || f.triage === "stale")
+            continue;
+        for (const file of f.affected_files) {
+            if (!file || file.includes("*"))
+                continue; // globs can't dead-ref
+            if (!existsSync(join(root, file))) {
+                findings.push({ kind: "finding-stale", id: f.id, detail: `live finding "${f.title}" references missing file "${file}" — re-verify${f.method ? ` (${f.method})` : ""} and re-record, or mark it stale` });
+            }
+        }
+        if (f.violates_constraint) {
+            const con = store.getRec("constraints", f.violates_constraint);
+            if (!con) {
+                findings.push({ kind: "finding-stale", id: f.id, detail: `live finding "${f.title}" claims to violate ${f.violates_constraint}, which does not exist — link the real rule or record it (hunch_record_correction)` });
+            }
+            else if (con.status === "retired") {
+                findings.push({ kind: "finding-stale", id: f.id, detail: `live finding "${f.title}" violates ${f.violates_constraint}, but that constraint is RETIRED — resolve the finding or re-link it` });
+            }
+        }
+    }
     return { findings };
 }
 /** Resolve a decision file reference without making private-memory paths depend on

package/dist/core/format.js

@@ -21,6 +21,12 @@ export function formatContext(ctx) {
         for (const b of ctx.bugs)
             out.push(`- [${b.status}/${b.severity}] ${b.title} — root cause: ${b.root_cause}${prov(b.provenance)}`);
     }
+    if (ctx.findings.length) {
+        out.push(`\n## 🔍 Known findings (observed, unresolved — no fix landed yet)`);
+        for (const f of ctx.findings) {
+            out.push(`- [${f.triage}/${f.severity}] ${f.title} — ${f.observation}${prov(f.provenance)}\n  (${f.id}; observed ${f.observed_at.slice(0, 10)}${f.violates_constraint ? `; violates ${f.violates_constraint}` : ""}${f.method ? `; re-verify via ${f.method}` : ""})`);
+        }
+    }
     if (ctx.blast_radius.length) {
         out.push(`\n## 💥 Blast radius (transitive dependents)`);
         out.push(ctx.blast_radius.map((d) => `- [d${d.depth}] ${d.via}`).join("\n"));

package/dist/core/ids.js

@@ -43,4 +43,10 @@ export function runbookId(seed) {
 export function constraintId(statement) {
     return "con_" + shortHash(statement.trim().toLowerCase());
 }
+/** Finding id seeded by its title (trim + lowercase, same idiom as constraints):
+ *  re-recording the same observation UPDATES it (e.g. a triage change) instead of
+ *  minting a duplicate. A genuinely new observation deserves a new title. */
+export function findingId(title) {
+    return "fnd_" + shortHash(title.trim().toLowerCase());
+}
 //# sourceMappingURL=ids.js.map

package/dist/core/paths.js

@@ -53,16 +53,16 @@ export function hunchPathsForDir(hunchDir) {
  *  WITHOUT `.hunch` stops the walk: an ancestor `.hunch` above the repo
  *  boundary belongs to some other scope (e.g. a stray ~/.hunch) and must never
  *  hijack a fresh repo — init would scaffold, index, and scan OUTSIDE the repo. */
+export function isDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 export function findRoot(start = process.cwd()) {
     let cur = resolve(start);
-    const isDir = (p) => {
-        try {
-            return statSync(p).isDirectory();
-        }
-        catch {
-            return false;
-        }
-    };
     for (;;) {
         if (isDir(join(cur, HUNCH_DIR)))
             return cur; // a `.hunch` regular file is not a root

package/dist/core/types.js

@@ -218,8 +218,31 @@ export const RunbookSchema = z.object({
     provenance: ProvenanceSchema,
     date: z.string(),
 });
+/** An OBSERVATION — audited knowledge with no diff (the anchor is a date + evidence,
+ *  not a commit). Fills the gap between Bug (broke and got fixed) and Decision (chose
+ *  and changed code): "we looked, we found, we haven't acted yet". Examples: an audit
+ *  that surfaced unscoped tenant queries, a measured perf number, a vendor limit, an
+ *  incident with no code fix. ADVISORY retrieval context (pre-edit grounding + MCP);
+ *  never enters any block path. Lifecycle is `triage`, not valid-time: a finding is
+ *  resolved/stale-marked, never superseded. */
+export const FindingSchema = z.object({
+    id: z.string().describe("fnd_*"),
+    title: z.string(),
+    observation: z.string().default("").describe("what was observed, in plain words"),
+    evidence: z.array(z.string()).default([]).describe("the query/command run + representative output — a finding without evidence is an opinion"),
+    method: z.string().nullable().default(null).describe("rb_* runbook that re-runs the audit (makes the finding re-verifiable)"),
+    severity: z.enum(["low", "medium", "high", "critical"]).default("medium"),
+    triage: z.enum(["open", "accepted-risk", "scheduled", "resolved", "stale"]).default("open"),
+    affected_files: z.array(z.string()).default([]).describe("concrete paths or globs the observation concerns"),
+    affected_symbols: z.array(z.string()).default([]).describe("symbols/objects concerned (e.g. dbo.GetOrders)"),
+    violates_constraint: z.string().nullable().default(null).describe("con_* this finding is a known violation of"),
+    spawned_decision: z.string().nullable().default(null).describe("dec_* recorded in response to this finding"),
+    observed_at: z.string().describe("ISO instant the observation was made — the anchor (findings have no commit)"),
+    resolved_commit: z.string().nullable().default(null).describe("the commit that fixed it (set when triage becomes resolved)"),
+    provenance: ProvenanceSchema,
+});
 /** The entity collections, keyed by their on-disk directory name. */
-export const ENTITY_KINDS = ["components", "edges", "symbols", "decisions", "bugs", "constraints", "runbooks"];
+export const ENTITY_KINDS = ["components", "edges", "symbols", "decisions", "bugs", "constraints", "runbooks", "findings"];
 export const SCHEMAS = {
     components: ComponentSchema,
     edges: EdgeSchema,
@@ -228,6 +251,7 @@ export const SCHEMAS = {
     bugs: BugSchema,
     constraints: ConstraintSchema,
     runbooks: RunbookSchema,
+    findings: FindingSchema,
 };
 /** Default provenance helper for deterministic (extracted) records. */
 export function extracted(confidence, evidence = []) {

package/dist/core/version.js

@@ -16,4 +16,13 @@ export const HUNCH_VERSION = (() => {
         return "0.0.0";
     }
 })();
+/** Exact public npm package consumed by generated CI and shared MCP/provider
+ * configs. A floating package name would let one committed configuration run
+ * different Hunch semantics as npm's latest release changes. */
+export const HUNCH_PACKAGE_SPEC = `@davesheffer/hunch@${HUNCH_VERSION}`;
+/** npm alias used by npx launchers. Giving the fetched package a distinct local
+ * alias prevents npm exec from treating this repository (which has the same
+ * package name) as satisfying the request and then falling through to an older
+ * global `hunch` executable. */
+export const HUNCH_NPX_PACKAGE_SPEC = `hunch-exact@npm:${HUNCH_PACKAGE_SPEC}`;
 //# sourceMappingURL=version.js.map

package/dist/extractors/git.js

@@ -535,7 +535,7 @@ export function commitAndPushHunch(hunchDir, message, opts) {
             // remote .gitignore, local info/exclude, or ambient excludesFile must not
             // be able to silently stop the shared graph's heartbeat.
             for (let index = 0; index < paths.length; index += 128) {
-                if (!run(["-c", `core.attributesFile=${gitNullDevice()}`, "add", "-f", "--", ...paths.slice(index, index + 128)])) {
+                if (!run(["-c", `core.attributesFile=${gitNullDevice()}`, "-c", "core.autocrlf=false", "add", "-f", "--", ...paths.slice(index, index + 128)])) {
                     run(["reset", "-q", "--", "."]);
                     return null;
                 }
@@ -573,9 +573,12 @@ export function commitAndPushHunch(hunchDir, message, opts) {
         // docs the caller verified git-clean BEFORE rewriting, so it can neither weaken the
         // bug_overlay_clobber detection above nor sweep user edits.
         for (const file of opts.alsoStage ?? []) {
+            // core.autocrlf=false on every memory add/checkout: the Git-for-Windows
+            // installer default (system gitconfig autocrlf=true) would re-encode the
+            // graph's JSON bytes in transit, breaking byte-exact content hashes.
             run(opts.push === false
-                ? ["add", "--", file]
-                : ["-c", `core.attributesFile=${gitNullDevice()}`, "add", "--", file]);
+                ? ["-c", "core.autocrlf=false", "add", "--", file]
+                : ["-c", `core.attributesFile=${gitNullDevice()}`, "-c", "core.autocrlf=false", "add", "--", file]);
         }
         // Only sync+push when a memory commit was actually created — never run pull/push against the
         // enclosing repo on an empty stage. Two-way sync: MERGE the remote BEFORE pushing so a push
@@ -600,6 +603,7 @@ export function commitAndPushHunch(hunchDir, message, opts) {
                 "-C", hunchDir,
                 "-c", `core.hooksPath=${hooksDir}`,
                 ...(opts.push === false ? [] : ["-c", `core.attributesFile=${gitNullDevice()}`]),
+                "-c", "core.autocrlf=false",
                 "-c", "commit.gpgsign=false",
                 "commit", "--no-gpg-sign", "--only", "-m", message, "--", ...commitPaths,
             ], { stdio: "ignore", env, timeout: 15_000 });
@@ -1072,6 +1076,7 @@ function adoptContractHead(hunchDir, fetchedHead, contract, env, fingerprint) {
             "-C", hunchDir,
             "-c", `core.hooksPath=${hooksDir}`,
             "-c", `core.attributesFile=${gitNullDevice()}`,
+            "-c", "core.autocrlf=false",
             "reset", "--hard", fetchedHead,
         ], {
             stdio: "ignore", env, timeout: 5_000,
@@ -1123,6 +1128,7 @@ function mergeRemote(hunchDir, env, timeoutMs, contract, allowUnrelatedHistories
                 "-C", hunchDir,
                 "-c", `core.hooksPath=${hooksDir}`,
                 "-c", `core.attributesFile=${gitNullDevice()}`,
+                "-c", "core.autocrlf=false",
                 "-c", "commit.gpgsign=false",
                 ...args,
             ], {

package/dist/integrations/ciAction.js

@@ -8,7 +8,7 @@
  */
 import { mkdirSync, writeFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
-import { HUNCH_VERSION } from "../core/version.js";
+import { HUNCH_PACKAGE_SPEC } from "../core/version.js";
 // `\${{ … }}` keeps GitHub Actions expressions literal inside this template
 // literal (a bare `${` would be JS interpolation).
 export function ciWorkflowYaml() {
@@ -44,7 +44,7 @@ jobs:
         # Pin the same release that generated this file so every assistant and CI
         # evaluate the graph with identical semantics. Dependabot/Renovate (or a
         # deliberate hunch-ci refresh) can advance this in a reviewed change.
-        run: npm install -g @davesheffer/hunch@${HUNCH_VERSION}
+        run: npm install -g ${HUNCH_PACKAGE_SPEC}
 
       - name: Fetch the PR base branch
         # checkout sets up no origin/<base> tracking ref; create it explicitly so

package/dist/integrations/claudemd.js

@@ -20,6 +20,7 @@ export function renderHunchSection(store, root) {
         constraints: store.json.loadAll("constraints").length,
         components: store.json.loadAll("components").length,
         policies: root ? new PolicyRepository(root, store).listPolicies({ publicOnly: true }).length : 0,
+        findings: store.json.loadAll("findings").filter((f) => f.triage === "open" || f.triage === "accepted-risk" || f.triage === "scheduled").length,
     };
     const lines = [];
     lines.push(START);
@@ -27,7 +28,7 @@ export function renderHunchSection(store, root) {
     lines.push("");
     lines.push("This repo has **Hunch** — a curated graph of *why* the code is the way it is " +
         "(decisions, bug history, invariants). It currently holds " +
-        `**${counts.decisions} decisions, ${counts.bugs} bugs, ${counts.constraints} constraints, ${counts.components} components, ${counts.policies} policies**.`);
+        `**${counts.decisions} decisions, ${counts.bugs} bugs, ${counts.constraints} constraints, ${counts.components} components, ${counts.policies} policies${counts.findings ? `, ${counts.findings} open findings` : ""}**.`);
     lines.push("");
     lines.push("**Consult Hunch via the `hunch_*` MCP tools — pick by MOMENT, not from memory:**");
     lines.push("");
@@ -47,6 +48,7 @@ export function renderHunchSection(store, root) {
     lines.push("");
     lines.push("**Before editing:**");
     lines.push("- `hunch_check_constraints(scope)` and `hunch_get_dependents(symbol)` / `hunch_blast_radius(target)` — invariants in scope + who you'd break. (The pre-edit hook injects this per file automatically; call these for PLANNING breadth.)");
+    lines.push("- `hunch_findings(scope?)` — known-but-unfixed gaps in the area (past audits, measurements, incidents) so you inherit them instead of re-discovering them.");
     lines.push("");
     lines.push("**Before committing / merging:**");
     lines.push("- `hunch_conformance()` — does the code still SATISFY recorded intent? Run before and after a refactor.");
@@ -60,6 +62,7 @@ export function renderHunchSection(store, root) {
     lines.push("**After deciding / when corrected:**");
     lines.push("- `hunch_capture_decision(topic?)` → `hunch_record_decision(...)` — interview first, then write; status `proposed` = roadmap intent (shows in `hunch now`).");
     lines.push("- `hunch_record_correction(...)` — a human correction becomes an ENFORCED rule (Never Twice), not a one-session memory.");
+    lines.push("- `hunch_record_finding(...)` — an OBSERVATION with no code change (an audit that found a gap, a measured number, an incident) becomes durable memory anchored to a date + evidence; `/audit` runs the ritual.");
     lines.push("- `hunch_timeline(target)` — decision history when investigating how something evolved.");
     const wiki = root ? wikiSummary(root) : null;
     if (wiki) {

package/dist/integrations/gitignore.js

@@ -50,6 +50,8 @@ const MEM_ENTRIES = [
     ".hunch/shadow/",
     ".hunch/symbols/",
     ".hunch/edges/",
+    ".hunch/runbooks/",
+    ".hunch/findings/",
 ];
 function pathIsWithin(path, parent) {
     const rel = relative(parent, path);

package/dist/integrations/scaffold.js

@@ -76,6 +76,18 @@ Capture the decision for **$ARGUMENTS** into Hunch's graph.
 5. Commit with \`hunch_record_decision\`, passing \`capture_token\` (from step 1) and the confirmed \`topic\`. The artifact is the graph write, not prose.
 6. On CONFLICT for the topic, do NOT auto-supersede — Hunch refuses and presents both; let me choose supersede (link) / split the topic / discard.
 `;
+const AUDIT_CMD = `---
+description: Run an audit and record what it finds into Hunch as findings (observed gaps, no code change)
+---
+Audit **$ARGUMENTS** and record what you find into Hunch's graph.
+
+1. Run the actual check (query/grep/script) — a finding needs EVIDENCE: the exact command you ran plus representative output. Never record a finding you didn't observe.
+2. For each REAL gap: \`hunch_record_finding\` with title, observation, evidence, affected_files/affected_symbols, severity. It grounds future edits to those files automatically.
+3. If the gap violates an existing invariant, link it via \`violates_constraint\`. If the RULE itself is unrecorded, capture the rule FIRST (\`hunch_record_correction\`), then link it.
+4. If the audit is re-runnable, capture the procedure as a runbook and set \`method\` to its rb_* id — that makes the finding re-verifiable, not folklore.
+5. Triage with me inline: open (default) / accepted-risk / scheduled. NEVER mark resolved without the fixing commit (\`resolved_commit\`).
+6. Report: findings recorded (ids), what was checked and came back clean, and what stays unverified.
+`;
 const HEAL_CMD = `---
 description: Reconcile docs/code with Hunch's decision graph (doc≠graph drift), never rewriting prose silently
 ---
@@ -169,6 +181,7 @@ export function writeSlashCommands(root) {
         ["hunch-fragile.md", FRAGILE_CMD],
         ["capture.md", CAPTURE_CMD],
         ["heal.md", HEAL_CMD],
+        ["audit.md", AUDIT_CMD],
     ];
     for (const [name, body] of files) {
         const p = join(dir, name);

package/dist/integrations/team.js

@@ -557,6 +557,7 @@ function materializeValidatedClone(team, teamRoot, overlayRoot, emptyHooks) {
         "-C", overlayRoot,
         "-c", `core.hooksPath=${emptyHooks}`,
         "-c", `core.attributesFile=${gitNullDevice()}`,
+        "-c", "core.autocrlf=false",
         "reset", "--hard", oid,
     ], {
         stdio: "ignore",

package/dist/mcp/roots.js

@@ -0,0 +1,58 @@
+/**
+ * Resolve MCP client roots to the one repository this server may safely serve.
+ *
+ * A server process keeps the cwd it was spawned with, while the client can move to
+ * another workspace or linked worktree. MCP roots are the client-neutral protocol
+ * mechanism for following that change.
+ */
+import { statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { findRoot, HUNCH_DIR, isDir } from "../core/paths.js";
+function toPath(uri) {
+    if (!uri.startsWith("file:"))
+        return "";
+    try {
+        return fileURLToPath(uri);
+    }
+    catch {
+        return "";
+    }
+}
+function rootStart(path) {
+    try {
+        const stat = statSync(path);
+        if (stat.isDirectory())
+            return path;
+        if (stat.isFile())
+            return dirname(path);
+    }
+    catch {
+        // Missing/inaccessible roots are unusable.
+    }
+    return "";
+}
+/**
+ * Returns null when several advertised repositories are equally plausible.
+ * The roots protocol exposes a set of URI/name pairs, not an "active root" bit;
+ * choosing the first Hunch store in that case could silently write repo B's
+ * decision into repo A.
+ */
+export function resolveActiveRoot(rootUris, fallbackCwd) {
+    const candidates = [];
+    for (const uri of rootUris) {
+        const start = rootStart(toPath(uri));
+        if (!start)
+            continue;
+        const root = findRoot(start);
+        if (!candidates.includes(root))
+            candidates.push(root);
+    }
+    if (!candidates.length)
+        return findRoot(fallbackCwd);
+    if (candidates.length === 1)
+        return candidates[0];
+    const withStore = candidates.filter((candidate) => isDir(join(candidate, HUNCH_DIR)));
+    return withStore.length === 1 ? withStore[0] : null;
+}
+//# sourceMappingURL=roots.js.map

package/dist/mcp/server.js

@@ -8,11 +8,13 @@
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { RootsListChangedNotificationSchema } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 import { hunchPaths, findRoot, toPosixTarget } from "../core/paths.js";
+import { resolveActiveRoot } from "./roots.js";
 import { HunchStore } from "../store/hunchStore.js";
 import { selectEmbedder } from "../store/embedder.js";
-import { decisionId } from "../core/ids.js";
+import { decisionId, findingId } from "../core/ids.js";
 import { buildCorrectionConstraint } from "../core/correction.js";
 import { knownRepoDeps } from "../synthesis/tripwires.js";
 import { refreshExistingGrounding } from "../integrations/providers.js";
@@ -53,6 +55,7 @@ const flushNote = (flush, home, mode) => flush === "pushed" ? ` (committed + pus
 const WHY_CAP = 6; // per record-type in hunch_why
 const DEP_CAP = 25; // dependents in hunch_get_dependents
 const QUERY_HITS = 8; // hunch_query matches (was 12)
+const FINDINGS_CAP = 12; // hunch_findings listing
 const SEV_CONSTRAINT = { blocking: 3, warning: 2, advisory: 1 };
 const SEV_BUG = { critical: 4, high: 3, medium: 2, low: 1 };
 const more = (total, cap, hint = "") => total > cap ? `\n  …(+${total - cap} more${hint ? ` — ${hint}` : ""})` : "";
@@ -121,14 +124,41 @@ function resolveFiles(store, target) {
     const files = new Set(resolveSymbols(store, target).map((s) => s.file));
     return files.size ? [...files] : [toPosixTarget(target)];
 }
-export function buildServer(root) {
+function pullBackoff(status, finishedAt, failures) {
+    if (status === "updated" || status === "current") {
+        return { consecutivePullFailures: 0, nextRemotePullAt: finishedAt + 1_000 };
+    }
+    if (status === "busy") {
+        return { consecutivePullFailures: failures, nextRemotePullAt: finishedAt + 100 };
+    }
+    if (status === "unconfigured") {
+        return { consecutivePullFailures: 0, nextRemotePullAt: finishedAt + 30_000 };
+    }
+    const consecutivePullFailures = Math.min(failures + 1, 6);
+    return {
+        consecutivePullFailures,
+        nextRemotePullAt: finishedAt + Math.min(30_000, 1_000 * (2 ** (consecutivePullFailures - 1))),
+    };
+}
+function rebuildFreshIndex(store) {
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const before = store.sourceStamp();
+        store.reindexFresh();
+        const after = store.sourceStamp();
+        if (before === after)
+            return after;
+    }
+    return undefined;
+}
+/** Prepare and validate a complete root context before publishing it to handlers.
+ *  A failed re-home therefore leaves the previous graph fully active. */
+function prepareRoot(root, explicitOverlay, requireIndex) {
     // Team auto-discovery: a committed .hunch/team.json advertises the shared store — a
     // fresh clone (a new teammate, a headless agent, a CI workflow) wires itself BEFORE the
     // store is constructed, so every consumer resolves the same single source of truth.
     // Once that declaration is present it is fail-closed: starting against the public
     // graph after an invalid config, failed first clone, or dead pointer would let both
     // reads and writes silently escape the team's memory spine.
-    const explicitOverlay = !!process.env.HUNCH_PRIVATE_DIR?.trim();
     const teamFile = join(hunchPaths(root).hunch, "team.json");
     const teamAdvertised = !explicitOverlay && existsSync(teamFile);
     const startupTeamConfig = teamAdvertised ? readTeamConfig(root) : null;
@@ -137,18 +167,70 @@ export function buildServer(root) {
     }
     ensureTeamOverlay(root);
     const store = new HunchStore(hunchPaths(root));
-    if (teamAdvertised && (store.mode !== "shared"
-        || !store.privateDir
-        || !existsSync(store.privateDir)
-        || !overlayMatchesTeamRemote(root, join(store.privateDir, "..")))) {
+    try {
+        if (teamAdvertised && (store.mode !== "shared"
+            || !store.privateDir
+            || !existsSync(store.privateDir)
+            || !overlayMatchesTeamRemote(root, join(store.privateDir, "..")))) {
+            throw new Error("the advertised team memory store is unavailable or tracks a different remote; refusing to start MCP on another graph");
+        }
+        const startupTeamRoute = teamAdvertised && store.privateDir
+            ? teamRemoteContract(root, join(store.privateDir, ".."))
+            : null;
+        if (startupTeamRoute)
+            pinSharedRemote(store, startupTeamRoute);
+        let nextRemotePullAt = 0;
+        let consecutivePullFailures = 0;
+        if (store.privateDir) {
+            try {
+                const status = pullHunchStatus(store.privateDir, {
+                    timeoutMs: 5_000,
+                    remote: startupTeamRoute ?? advertisedTeamRemoteContract(root, join(store.privateDir, "..")),
+                });
+                ({ nextRemotePullAt, consecutivePullFailures } = pullBackoff(status, Date.now(), 0));
+            }
+            catch {
+                // Offline / no remote — proceed with the validated local store.
+            }
+        }
+        let indexedSourceStamp;
+        try {
+            indexedSourceStamp = rebuildFreshIndex(store);
+        }
+        catch (error) {
+            if (requireIndex)
+                throw error;
+            console.error("[hunch-mcp] reindex on startup failed:", error.message);
+        }
+        return {
+            root,
+            teamFile,
+            teamAdvertised,
+            startupTeamConfig,
+            startupTeamRoute,
+            store,
+            nextRemotePullAt,
+            consecutivePullFailures,
+            indexedSourceStamp,
+        };
+    }
+    catch (error) {
         store.close();
-        throw new Error("the advertised team memory store is unavailable or tracks a different remote; refusing to start MCP on another graph");
+        throw error;
     }
-    const startupTeamRoute = teamAdvertised && store.privateDir
-        ? teamRemoteContract(root, join(store.privateDir, ".."))
-        : null;
-    if (startupTeamRoute)
-        pinSharedRemote(store, startupTeamRoute);
+}
+export function buildServerWithRootControl(initialRoot) {
+    const explicitOverlay = !!process.env.HUNCH_PRIVATE_DIR?.trim();
+    const initial = prepareRoot(initialRoot, explicitOverlay, false);
+    let root = initial.root;
+    let teamFile = initial.teamFile;
+    let teamAdvertised = initial.teamAdvertised;
+    let startupTeamConfig = initial.startupTeamConfig;
+    let startupTeamRoute = initial.startupTeamRoute;
+    let store = initial.store;
+    let nextRemotePullAt = initial.nextRemotePullAt;
+    let consecutivePullFailures = initial.consecutivePullFailures;
+    let indexedSourceStamp = initial.indexedSourceStamp;
     const matchesStartupTeamRoute = () => {
         if (!teamAdvertised || !store.privateDir || !startupTeamConfig || !startupTeamRoute)
             return !teamAdvertised;
@@ -165,24 +247,9 @@ export function buildServer(root) {
     // session sees memory captured on other machines/worktrees before we index — making the
     // overlay genuinely one source of truth. Remote calls are bounded; request-time failures
     // back off exponentially instead of freezing every tool on the same unavailable remote.
-    let nextRemotePullAt = 0;
-    let consecutivePullFailures = 0;
     const notePull = (status, finishedAt) => {
-        if (status === "updated" || status === "current") {
-            consecutivePullFailures = 0;
-            nextRemotePullAt = finishedAt + 1_000;
-        }
-        else if (status === "busy") {
-            nextRemotePullAt = finishedAt + 100;
-        }
-        else if (status === "unconfigured") {
-            consecutivePullFailures = 0;
-            nextRemotePullAt = finishedAt + 30_000;
-        }
-        else {
-            consecutivePullFailures = Math.min(consecutivePullFailures + 1, 6);
-            nextRemotePullAt = finishedAt + Math.min(30_000, 1_000 * (2 ** (consecutivePullFailures - 1)));
-        }
+        ({ nextRemotePullAt, consecutivePullFailures } =
+            pullBackoff(status, finishedAt, consecutivePullFailures));
     };
     const pullTeamMemory = (force = false) => {
         if (!store.privateDir)
@@ -195,86 +262,146 @@ export function buildServer(root) {
             remote: startupTeamRoute ?? advertisedTeamRemoteContract(root, join(store.privateDir, "..")),
         }), Date.now());
     };
-    if (store.privateDir) {
-        try {
-            pullTeamMemory(true);
-        }
-        catch { /* offline / no remote — proceed with local */ }
-    }
     // A source stamp is acknowledged ONLY after a stable, successful rebuild. If
     // another process changes the atomic JSON tree during the rebuild, retry once;
     // continued churn leaves the marker unset so the next request tries again.
-    let indexedSourceStamp;
     const refreshIndex = () => {
-        for (let attempt = 0; attempt < 2; attempt++) {
-            const before = store.sourceStamp();
-            store.reindexFresh();
-            const after = store.sourceStamp();
-            if (before === after) {
-                indexedSourceStamp = after;
-                return;
-            }
-        }
-        indexedSourceStamp = undefined;
+        indexedSourceStamp = rebuildFreshIndex(store);
     };
-    // Ensure the SQLite index reflects the JSON source of truth on startup.
-    try {
-        refreshIndex();
-    }
-    catch (e) {
-        console.error("[hunch-mcp] reindex on startup failed:", e.message);
-    }
     // Resolve the embedder ONCE for this long-lived process (never throws; null when
     // the optional model isn't installed). The model then loads lazily on the first
     // hunch_query and stays warm — and hybridSearch degrades to FTS until then.
     const embedderReady = selectEmbedder();
     const server = new McpServer({ name: "hunch", version: HUNCH_VERSION });
+    let activeRequests = 0;
+    let pendingRoot = null;
+    let pendingScheduled = false;
+    let closed = false;
+    const activateRoot = (next) => {
+        const canonical = findRoot(next);
+        if (canonical === root)
+            return;
+        const prepared = prepareRoot(canonical, explicitOverlay, true);
+        const previous = store;
+        root = prepared.root;
+        teamFile = prepared.teamFile;
+        teamAdvertised = prepared.teamAdvertised;
+        startupTeamConfig = prepared.startupTeamConfig;
+        startupTeamRoute = prepared.startupTeamRoute;
+        store = prepared.store;
+        nextRemotePullAt = prepared.nextRemotePullAt;
+        consecutivePullFailures = prepared.consecutivePullFailures;
+        indexedSourceStamp = prepared.indexedSourceStamp;
+        previous.close();
+        console.error(`[hunch-mcp] serving Hunch at ${root} (client root)`);
+    };
+    const applyPendingRoot = () => {
+        pendingScheduled = false;
+        if (closed || activeRequests || !pendingRoot)
+            return;
+        const next = pendingRoot;
+        pendingRoot = null;
+        try {
+            activateRoot(next);
+        }
+        catch (error) {
+            console.error(`[hunch-mcp] client root change refused: ${error.message}`);
+        }
+    };
+    const schedulePendingRoot = () => {
+        if (closed || activeRequests || !pendingRoot || pendingScheduled)
+            return;
+        pendingScheduled = true;
+        queueMicrotask(applyPendingRoot);
+    };
+    const setRoot = (next) => {
+        if (closed)
+            throw new Error("MCP server is closed");
+        const canonical = findRoot(next);
+        if (canonical === root) {
+            pendingRoot = null;
+            return;
+        }
+        if (activeRequests) {
+            pendingRoot = canonical;
+            return;
+        }
+        pendingRoot = null;
+        activateRoot(canonical);
+    };
+    const dispose = () => {
+        if (closed)
+            return;
+        closed = true;
+        pendingRoot = null;
+        store.close();
+    };
+    const underlyingClose = server.close.bind(server);
+    server.close = async () => {
+        try {
+            await underlyingClose();
+        }
+        finally {
+            dispose();
+        }
+    };
+    const priorOnClose = server.server.onclose;
+    server.server.onclose = () => {
+        dispose();
+        priorOnClose?.();
+    };
     const registerTool = server.registerTool.bind(server);
     server.registerTool = ((name, config, callback) => registerTool(name, config, async (...args) => {
-        // Routing is live state, not a startup constant. A branch switch or
-        // `hunch shared` can add/remove team.json while this stdio process remains
-        // alive; serving the old store after that boundary would write the wrong
-        // graph. Refuse and require a reconnect instead of attempting an in-place
-        // HunchStore swap while requests may be active.
-        // The explicit process overlay intentionally outranks committed team
-        // discovery for this process, both at startup and at every later request.
-        const teamFileNow = !explicitOverlay && existsSync(teamFile);
-        if (teamFileNow !== teamAdvertised) {
-            return err("The committed team-memory routing changed after this MCP process started. Reconnect Hunch before reading or writing memory.");
-        }
-        const currentTeamConfig = teamFileNow ? readTeamConfig(root) : null;
-        if (teamAdvertised && !matchesStartupTeamRoute()) {
-            return err("The team-memory URL or branch changed after this MCP process started. Refusing the old graph; reconnect Hunch first.");
-        }
-        if (teamFileNow && (!currentTeamConfig
-            || store.mode !== "shared"
-            || !store.privateDir
-            || !overlayMatchesTeamRemote(root, join(store.privateDir, "..")))) {
-            return err("The committed team memory destination is invalid or no longer matches this process. Refusing the stale graph; reconnect Hunch first.");
-        }
-        if (store.mode === "shared" && store.privateDir) {
-            try {
-                pullTeamMemory();
+        activeRequests++;
+        try {
+            // Routing is live state, not a startup constant. A branch switch or
+            // `hunch shared` can add/remove team.json while this stdio process remains
+            // alive; serving the old store after that boundary would write the wrong
+            // graph. Protocol-driven root swaps are prepared atomically and deferred
+            // until this request count reaches zero, so every handler sees one stable
+            // root/store/route epoch for its complete execution.
+            const teamFileNow = !explicitOverlay && existsSync(teamFile);
+            if (teamFileNow !== teamAdvertised) {
+                return err("The committed team-memory routing changed after this MCP process started. Reconnect Hunch before reading or writing memory.");
             }
-            catch { /* offline / lock held / invalid remote — use local */ }
-            // Recompute the full semantic + physical snapshot after the synchronous
-            // network seam. A paired team.json/origin change can occur while fetch is
-            // blocked; serving after that race would attach the old checkout to a new
-            // destination even though the pull itself correctly refused.
+            const currentTeamConfig = teamFileNow ? readTeamConfig(root) : null;
             if (teamAdvertised && !matchesStartupTeamRoute()) {
-                return err("The team-memory route changed during refresh. Refusing to serve a stale or redirected graph; reconnect Hunch first.");
+                return err("The team-memory URL or branch changed after this MCP process started. Refusing the old graph; reconnect Hunch first.");
             }
-            try {
-                if (store.sourceStamp() !== indexedSourceStamp)
-                    refreshIndex();
+            if (teamFileNow && (!currentTeamConfig
+                || store.mode !== "shared"
+                || !store.privateDir
+                || !overlayMatchesTeamRemote(root, join(store.privateDir, "..")))) {
+                return err("The committed team memory destination is invalid or no longer matches this process. Refusing the stale graph; reconnect Hunch first.");
             }
-            catch { /* corrupt/churning local source — serve the last durable indexed view */ }
+            if (store.mode === "shared" && store.privateDir) {
+                try {
+                    pullTeamMemory();
+                }
+                catch { /* offline / lock held / invalid remote — use local */ }
+                // Recompute the full semantic + physical snapshot after the synchronous
+                // network seam. A paired team.json/origin change can occur while fetch is
+                // blocked; serving after that race would attach the old checkout to a new
+                // destination even though the pull itself correctly refused.
+                if (teamAdvertised && !matchesStartupTeamRoute()) {
+                    return err("The team-memory route changed during refresh. Refusing to serve a stale or redirected graph; reconnect Hunch first.");
+                }
+                try {
+                    if (store.sourceStamp() !== indexedSourceStamp)
+                        refreshIndex();
+                }
+                catch { /* corrupt/churning local source — serve the last durable indexed view */ }
+            }
+            const result = await callback(...args);
+            if (teamAdvertised && !matchesStartupTeamRoute()) {
+                return err("The team-memory route changed while the tool was running. Its startup destination was not published; reconnect Hunch before retrying.");
+            }
+            return result;
         }
-        const result = await callback(...args);
-        if (teamAdvertised && !matchesStartupTeamRoute()) {
-            return err("The team-memory route changed while the tool was running. Its startup destination was not published; reconnect Hunch before retrying.");
+        finally {
+            activeRequests--;
+            schedulePendingRoot();
         }
-        return result;
     }));
     // -- hunch_query ----------------------------------------------------------
     server.registerTool("hunch_query", {
@@ -613,6 +740,23 @@ export function buildServer(root) {
             // same-id public record (and vice versa).
             const home = store.captureHome(!!decision.private);
             const existing = home === "private" ? store.getPrivateRec("decisions", id) : store.json.get("decisions", id);
+            // A commit-keyed id intentionally lets a human capture upgrade the machine draft
+            // for that commit. Once the slot is human-confirmed, however, a differently
+            // identified decision must never reuse it: that would silently replace the first
+            // ADR while reporting success (issue #23). Topic is the canonical identity when
+            // both sides have one; otherwise a matching title permits anchoring/refining the
+            // same record without blocking the existing draft-upgrade contract.
+            const sameHumanIdentity = existing?.topic && decision.topic
+                ? decision.topic === existing.topic
+                : existing?.title === decision.title;
+            const conflictsWithHuman = !!existing?.provenance.source.includes("human_confirmed")
+                && !sameHumanIdentity;
+            if (conflictsWithHuman) {
+                return err(`Decision id ${id} already identifies a different human-confirmed decision: ` +
+                    `"${existing.title}"${existing.topic ? ` (topic "${existing.topic}")` : ""}. ` +
+                    `Refusing to overwrite it with "${decision.title}"${decision.topic ? ` (topic "${decision.topic}")` : ""}. ` +
+                    "Record the additional decision without commit, or reuse the incumbent topic/title when refining the same decision.");
+            }
             const source = existing && existing.provenance.source.includes("llm_draft")
                 ? "llm_draft+human_confirmed"
                 : "human_confirmed";
@@ -769,6 +913,96 @@ export function buildServer(root) {
             return err(`Failed to record correction: ${e.message}`);
         }
     });
+    // -- hunch_record_finding (write-back: observations, no diff) ---------------
+    server.registerTool("hunch_record_finding", {
+        title: "Record a finding (an observation with no code change)",
+        description: "Persist an OBSERVATION into Hunch — audited knowledge with no diff: an audit that surfaced a gap (e.g. queries missing tenant scoping), a measured number, a vendor/platform fact, an incident with no code fix. The anchor is a date + evidence, not a commit. Advisory: it grounds future edits to the affected files/symbols (pre-edit hook + hunch_context) and is listed by hunch_findings; it never blocks. Re-record the SAME title to update triage (e.g. triage:'resolved' + resolved_commit once fixed). If the finding is a violation of a rule that ISN'T recorded yet, record the rule first (hunch_record_correction) and link it via violates_constraint.",
+        inputSchema: {
+            finding: z.object({
+                title: z.string().describe("stable one-line name — re-recording the same title updates the finding"),
+                observation: z.string().describe("what was observed, in plain words"),
+                evidence: z.array(z.string()).optional().describe("the query/command run + representative output — a finding without evidence is an opinion"),
+                method: z.string().optional().describe("rb_* runbook that re-runs the audit (makes it re-verifiable)"),
+                severity: z.enum(["low", "medium", "high", "critical"]).optional(),
+                triage: z.enum(["open", "accepted-risk", "scheduled", "resolved", "stale"]).optional().describe("default 'open'. 'resolved' should carry resolved_commit."),
+                affected_files: z.array(z.string()).optional().describe("paths or globs the observation concerns"),
+                affected_symbols: z.array(z.string()).optional().describe("symbols/objects concerned (e.g. dbo.GetOrders)"),
+                violates_constraint: z.string().optional().describe("con_* this finding is a known violation of"),
+                spawned_decision: z.string().optional().describe("dec_* recorded in response"),
+                resolved_commit: z.string().optional().describe("the commit that fixed it (with triage:'resolved')"),
+                private: z.boolean().optional().describe("write into the PRIVATE overlay store instead of the committed repo. Errors if no private store is configured."),
+            }),
+        },
+    }, async ({ finding }) => {
+        try {
+            if (!finding.title.trim())
+                return err("title is required.");
+            if (!finding.observation.trim())
+                return err("observation is required — state what you saw.");
+            const id = findingId(finding.title);
+            const home = store.captureHome(!!finding.private);
+            const existing = home === "private" ? store.getPrivateRec("findings", id) : store.json.get("findings", id);
+            const now = new Date().toISOString();
+            const triage = finding.triage ?? existing?.triage ?? "open";
+            if (triage === "resolved" && !(finding.resolved_commit ?? existing?.resolved_commit)) {
+                return err(`Refusing to mark ${id} resolved without resolved_commit — a resolution claim needs the fixing commit (or use triage:'stale' if it no longer applies).`);
+            }
+            const rec = {
+                id,
+                title: finding.title,
+                observation: finding.observation,
+                evidence: finding.evidence ?? existing?.evidence ?? [],
+                method: finding.method ?? existing?.method ?? null,
+                severity: finding.severity ?? existing?.severity ?? "medium",
+                triage,
+                affected_files: (finding.affected_files ?? existing?.affected_files ?? []).map(toPosixTarget),
+                affected_symbols: finding.affected_symbols ?? existing?.affected_symbols ?? [],
+                violates_constraint: finding.violates_constraint ?? existing?.violates_constraint ?? null,
+                spawned_decision: finding.spawned_decision ?? existing?.spawned_decision ?? null,
+                observed_at: existing?.observed_at ?? now, // first observation wins — updates re-verify, not re-date
+                resolved_commit: finding.resolved_commit ?? existing?.resolved_commit ?? null,
+                provenance: { source: "human_confirmed", confidence: 0.95, evidence: finding.evidence ?? existing?.provenance.evidence ?? [], last_verified: now },
+            };
+            store.putCapture("findings", rec, !!finding.private);
+            store.reindex();
+            const flush = flushCapture(store, hunchPaths(root).hunch, !!finding.private, `hunch: capture ${id}`, startupTeamRoute ?? undefined);
+            const flushed = flushNote(flush, home, store.mode);
+            const where = finding.private
+                ? ` [PRIVATE overlay — not committed to this repo]${flushed}`
+                : home === "private" ? ` [SHARED store — one source of truth for the whole team]${flushed}` : flushed;
+            // Advisory nudges, never gates: an unresolvable constraint link and missing
+            // evidence both record fine, but say so.
+            const danglingCon = rec.violates_constraint && !store.getRec("constraints", rec.violates_constraint)
+                ? `\n\n△ violates_constraint ${rec.violates_constraint} resolves to no known constraint — if the rule isn't recorded yet, hunch_record_correction it and re-record this finding with the real id.`
+                : "";
+            const noEvidence = rec.evidence.length ? "" : "\n\n△ No evidence attached — a finding without the query/output that produced it is an opinion. Re-record with evidence when you have it.";
+            return ok(`${existing ? "Updated" : "Recorded"} finding ${id}: "${rec.title}" (${rec.triage}/${rec.severity}, observed ${rec.observed_at.slice(0, 10)}).${where} It now grounds edits to: ${[...rec.affected_files, ...rec.affected_symbols].join(", ") || "(nothing — add affected_files/symbols so it surfaces at edit time)"}.${danglingCon}${noEvidence}`);
+        }
+        catch (e) {
+            return err(`Failed to record finding: ${e.message}`);
+        }
+    });
+    // -- hunch_findings (read: the open-observations ledger) --------------------
+    server.registerTool("hunch_findings", {
+        title: "Open findings for a scope",
+        description: "List LIVE findings (observed gaps/debt with no fix yet — triage open/accepted-risk/scheduled) concerning a file, glob, or symbol; omit scope for the whole ledger. Call before planning work in an area to inherit past audits instead of re-discovering them. Advisory; resolved/stale findings are excluded unless all:true.",
+        inputSchema: {
+            scope: z.string().optional().describe("a path, glob, or symbol (e.g. src/procs/** or dbo.GetOrders); omit for all"),
+            all: z.boolean().optional().describe("include resolved/stale findings (the full history)"),
+        },
+    }, async ({ scope, all }) => {
+        const live = (f) => f.triage === "open" || f.triage === "accepted-risk" || f.triage === "scheduled";
+        const list = (scope ? store.liveFindingsFor(scope) : store.recs("findings").filter(all ? () => true : live))
+            .filter(all ? () => true : live)
+            .sort((a, b) => (SEV_BUG[b.severity] ?? 0) - (SEV_BUG[a.severity] ?? 0) || a.id.localeCompare(b.id));
+        if (!list.length)
+            return ok(`No ${all ? "" : "live "}findings${scope ? ` for "${scope}"` : ""}. (Record one after an audit with hunch_record_finding.)`);
+        const L = list.slice(0, FINDINGS_CAP).map((f) => {
+            const links = [f.violates_constraint ? `violates ${f.violates_constraint}` : "", f.method ? `re-verify via ${f.method}` : "", f.resolved_commit ? `fixed in ${f.resolved_commit.slice(0, 9)}` : ""].filter(Boolean).join("; ");
+            return `• [${f.triage}/${f.severity}] ${f.title} (${f.id}, observed ${f.observed_at.slice(0, 10)})\n    ${f.observation}\n    concerns: ${[...f.affected_files, ...f.affected_symbols].join(", ") || "(unscoped)"}${links ? `\n    ${links}` : ""}`;
+        });
+        return ok(`${list.length} finding(s)${scope ? ` for "${scope}"` : ""}:\n${L.join("\n")}${more(list.length, FINDINGS_CAP)}`);
+    });
     server.registerTool("hunch_policy_upgrade_correction", {
         title: "Build a proved review proposal from one exact correction",
         description: "Upgrade the exact supported static ESM import-declaration package projection of one captured correction into a deterministic review packet when the baseline is clean. Writes proposal, plan, proof, and evidence artifacts only; never activates, warns, blocks, or grants authority. Unsupported corrections keep their immediate legacy guard and create no policy.",
@@ -1280,7 +1514,16 @@ export function buildServer(root) {
             return err(`Failed to materialize G2 behavior policies: ${e.message}`);
         }
     });
-    return server;
+    return {
+        server,
+        getRoot: () => root,
+        setRoot,
+    };
+}
+/** Back-compatible server construction for tests and callers that do not need
+ *  to drive roots directly. The server still owns and closes its active store. */
+export function buildServer(root) {
+    return buildServerWithRootControl(root).server;
 }
 function provLine(record) {
     const p = record?.provenance;
@@ -1289,12 +1532,44 @@ function provLine(record) {
     const v = p.last_verified ? `, verified ${p.last_verified.slice(0, 10)}` : "";
     return `\n      ⟨${p.source ?? "?"}, confidence ${p.confidence ?? "?"}${v}⟩`;
 }
+/** Query client roots after initialization and follow later list changes.
+ *  Generation ordering prevents a slow stale roots/list response from winning. */
+export function wireClientRoots(control, fallback) {
+    let generation = 0;
+    const syncRoots = async () => {
+        const mine = ++generation;
+        try {
+            if (!control.server.server.getClientCapabilities()?.roots)
+                return;
+            const response = await control.server.server.listRoots();
+            if (mine !== generation)
+                return;
+            const next = resolveActiveRoot((response?.roots ?? []).map((root) => root.uri), fallback);
+            if (!next) {
+                console.error("[hunch-mcp] multiple client roots are equally plausible; keeping the current Hunch root");
+                return;
+            }
+            control.setRoot(next);
+        }
+        catch (error) {
+            // A client without roots support keeps the spawn root. A client-provided
+            // root that fails fail-closed validation is also refused without taking
+            // down the existing, already-validated graph.
+            if (mine === generation) {
+                console.error(`[hunch-mcp] could not apply client roots: ${error.message}`);
+            }
+        }
+    };
+    control.server.server.oninitialized = () => { void syncRoots(); };
+    control.server.server.setNotificationHandler(RootsListChangedNotificationSchema, async () => { await syncRoots(); });
+}
 /** Start the stdio server (called by `hunch mcp`). */
 export async function startServer(cwd = process.cwd()) {
-    const root = findRoot(cwd);
-    const server = buildServer(root);
+    const fallback = findRoot(cwd);
+    const control = buildServerWithRootControl(fallback);
+    wireClientRoots(control, fallback);
     const transport = new StdioServerTransport();
-    await server.connect(transport);
-    console.error(`[hunch-mcp] serving Hunch at ${root} over stdio`);
+    await control.server.connect(transport);
+    console.error(`[hunch-mcp] serving Hunch over stdio (spawn root ${control.getRoot()}; resolving client roots…)`);
 }
 //# sourceMappingURL=server.js.map

package/dist/store/hunchStore.js

@@ -351,6 +351,13 @@ export class HunchStore {
                 fts(r.id, "runbooks", r.task, `${r.trigger.join(" ")} ${r.steps.join(" ")} ${r.gotchas.join(" ")} ${r.outcome} ${r.files.join(" ")}`);
             }
             counts.runbooks = runbooks.length;
+            // Findings (observations — audited, no diff): advisory records, same
+            // FTS-only ride as runbooks (dec_d32af7b821) — no dedicated SQL table.
+            const fnds = this.recs("findings");
+            for (const f of fnds) {
+                fts(f.id, "findings", f.title, `${f.observation} ${f.evidence.join(" ")} ${f.affected_files.join(" ")} ${f.affected_symbols.join(" ")} ${f.triage}`);
+            }
+            counts.findings = fnds.length;
             void j;
         });
         // Reconcile embeddings AFTER the FTS rebuild (model-free): drop vectors whose
@@ -978,6 +985,20 @@ export class HunchStore {
             .filter((c) => (asOf ? inWindow(c.valid_from, c.valid_to, asOf) : c.status !== "retired"))
             .sort((a, b) => sev(b.severity) - sev(a.severity));
     }
+    /** LIVE findings (observations — audited, no diff yet) concerning a file/scope:
+     *  triage open / accepted-risk / scheduled; resolved and stale stay silent. The
+     *  matcher mirrors checkConstraints: an affected entry may be a concrete path or a
+     *  glob, and the queried scope may be either too. Advisory only — findings never
+     *  enter any block path. Sorted worst-first, then id for stable output. */
+    liveFindingsFor(scope) {
+        const t = toPosixTarget(scope);
+        const live = (f) => f.triage === "open" || f.triage === "accepted-risk" || f.triage === "scheduled";
+        return this.recs("findings")
+            .filter(live)
+            .filter((f) => f.affected_files.some((af) => pathMatchesGlob(t, af) || pathMatchesGlob(af, t) || pathRelated(toPosixTarget(af), t))
+            || f.affected_symbols.some((s) => s === scope))
+            .sort((a, b) => (SEV_FINDING[b.severity] ?? 0) - (SEV_FINDING[a.severity] ?? 0) || a.id.localeCompare(b.id));
+    }
     /** The causal chain behind a constraint — the WHY a diff-only reviewer can't see.
      *  Deterministic graph join: constraint → source_decision (the decision that
      *  motivated the guard) → the bug whose root cause spawned it (via
@@ -1420,6 +1441,13 @@ export class HunchStore {
             check("decision", d.id, d.related_files, d.provenance.last_verified);
         for (const c of this.recs("constraints"))
             check("constraint", c.id, c.scope, c.provenance.last_verified);
+        // A LIVE finding whose affected files changed after it was observed/verified may
+        // be silently fixed (or worse) — flag for re-verification (re-run its method).
+        for (const f of this.recs("findings")) {
+            if (f.triage === "resolved" || f.triage === "stale")
+                continue;
+            check("finding", f.id, f.affected_files, f.provenance.last_verified ?? f.observed_at);
+        }
         return out.sort((a, b) => b.changed_at.localeCompare(a.changed_at));
     }
     /** The Context Assembler (DESIGN §2.1/§6): the MINIMAL relevant Hunch slice for
@@ -1445,6 +1473,7 @@ export class HunchStore {
             bugs,
             blast_radius: [...blast.values()].sort((a, b) => a.depth - b.depth).slice(0, 12),
             components: w.components,
+            findings: this.liveFindingsFor(target).slice(0, 8),
             budget_tokens: budget,
         };
         return ctx;
@@ -1459,6 +1488,7 @@ function matchTripwire(tw, addedDeps, scopedAdded) {
 function sev(s) {
     return { blocking: 3, warning: 2, advisory: 1 }[s] ?? 0;
 }
+const SEV_FINDING = { critical: 4, high: 3, medium: 2, low: 1 };
 /** Is a valid-time window open at `asOf`? `valid_from` undefined = always-started
  *  (legacy records). `valid_to` null = still in force. `asOf` undefined disables
  *  filtering (the history-inclusive default). Half-open [from, to) so a record and

package/dist/store/schema.js

@@ -89,7 +89,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
+  kind UNINDEXED,  -- components | edges | symbols | decisions | bugs | constraints | runbooks | findings
   title,
   body,
   tokenize = 'porter unicode61'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.9.3",
+  "version": "1.10.0",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
   "description": "Engineering memory and a deterministic Change Gate for AI-assisted codebases: decisions, rejected approaches, constraints, and bug lineage become portable context and opt-in enforcement for every MCP assistant.",