@davesheffer/hunch 1.9.4 → 1.10.1

package/dist/extractors/testreport.js

@@ -56,7 +56,8 @@ export function parseTestReport(output) {
         // Collect the following more-indented diagnostic block as the message.
         const baseIndent = leadingSpaces(raw);
         const block = [];
-        for (let j = i + 1; j < lines.length; j++) {
+        let j = i + 1;
+        for (; j < lines.length; j++) {
             const ln = lines[j];
             if (ln.trim() === "") {
                 block.push("");
@@ -68,6 +69,11 @@ export function parseTestReport(output) {
         }
         const diag = block.join("\n").trim();
         failMap.set(name, { test: name, message: diag ? `${name}\n${diag}` : name });
+        // Skip the consumed diagnostic block (issue #51): re-visiting it let
+        // TAP-looking text QUOTED INSIDE an error message (assertion diffs in this
+        // very repo quote "ok N - …" lines) parse as real results — a phantom pass
+        // can mark a previously-open bug fixed without any test having re-run.
+        i = j - 1;
     }
     // A test can legitimately appear as both (flaky retry) — trust the failure.
     for (const name of failMap.keys())

package/dist/integrations/claudemd.js

@@ -3,8 +3,9 @@
  * context loaded every session for free"). We own ONLY the region between the
  * HUNCH markers — any user-authored content outside it is preserved verbatim.
  */
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
-import { join, dirname } from "node:path";
+import { readFileSync, existsSync, mkdirSync } from "node:fs";
+import { writeFileAtomic } from "../core/io.js";
+import { basename, join, dirname } from "node:path";
 import { wikiSummary } from "../wiki/wiki.js";
 import { PolicyRepository } from "../constitution/repository.js";
 const START = "<!-- HUNCH:START — auto-generated, do not edit by hand -->";
@@ -20,6 +21,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 +29,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 +49,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 +63,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) {
@@ -100,12 +104,14 @@ export function upsertSection(file, section, fallbackTitle) {
         content = `${fallbackTitle}\n\n${section}\n`;
     }
     mkdirSync(dirname(file), { recursive: true }); // e.g. .github/ for copilot-instructions
-    writeFileSync(file, content);
+    // Atomic: this file carries the USER'S prose around the managed block — a torn
+    // write must not be able to truncate it (issue #43).
+    writeFileAtomic(file, content);
     return file;
 }
 /** Insert/replace the HUNCH section in CLAUDE.md, preserving everything else. */
 export function updateClaudeMd(root, store) {
-    return upsertSection(join(root, "CLAUDE.md"), renderHunchSection(store, root), `# ${root.split("/").pop()}`);
+    return upsertSection(join(root, "CLAUDE.md"), renderHunchSection(store, root), `# ${basename(root)}`);
 }
 function sev(s) {
     return { blocking: 3, warning: 2, advisory: 1 }[s] ?? 0;

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/providers.js

@@ -17,7 +17,8 @@
  * Every writer MERGES into existing files (preserving other servers / user prose)
  * and is idempotent, so re-running `hunch init` is safe.
  */
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { readFileSync, existsSync, mkdirSync } from "node:fs";
+import { writeFileAtomic } from "../core/io.js";
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
 import { renderHunchSection, upsertSection, updateClaudeMd } from "./claudemd.js";
@@ -135,7 +136,9 @@ function tomlStr(s) {
 }
 function writeJson(file, obj) {
     mkdirSync(dirname(file), { recursive: true });
-    writeFileSync(file, JSON.stringify(obj, null, 2) + "\n");
+    // Atomic: these files hold the USER'S merged servers/hooks — a torn write would
+    // leave them unparseable, which every writer here then refuses to touch (#43).
+    writeFileAtomic(file, JSON.stringify(obj, null, 2) + "\n");
     return file;
 }
 /** Provider hook commands live in tracked config files, so use the structured
@@ -148,7 +151,14 @@ function hookCommand(inv, provider) {
 function isHunchProviderHook(entry) {
     const e = entry && typeof entry === "object" ? entry : null;
     const command = typeof e?.command === "string" ? e.command : "";
-    return /(?:@davesheffer\/hunch|[\\/]index\.(?:js|ts))/.test(command) && /\bhook\b/.test(command);
+    // Anchored to the exact shape hookCommand() writes — JSON-quoted parts ending
+    // in "hook" "--provider" "<name>" — plus a Hunch launcher (the pinned npm
+    // package spec, or a quoted …/index.js|ts path for source installs). The old
+    // unanchored /index\.(js|ts)/ + /\bhook\b/ pair classified FOREIGN entries
+    // like `node ./hook/index.js` as ours and silently deleted them, violating
+    // the leave-every-foreign-hook-in-place contract (con_8460b6770f, issue #41).
+    return /(?:@davesheffer\/hunch|[\\/]index\.(?:js|ts)")/.test(command)
+        && /\s"hook"(?:\s+"--provider"\s+"[a-z]+")?\s*$/.test(command);
 }
 /** Merge our command entries into a standard `{ hooks: { Event: [] } }` file.
  * We replace only old Hunch commands and leave every foreign hook in place. */
@@ -255,7 +265,7 @@ export function writeCodexConfig(root, inv) {
     }
     base = base.trimEnd();
     mkdirSync(dirname(file), { recursive: true });
-    writeFileSync(file, base ? `${base}\n\n${block}\n` : `${block}\n`);
+    writeFileAtomic(file, base ? `${base}\n\n${block}\n` : `${block}\n`);
     return file;
 }
 /** AGENTS.md — the cross-tool ambient-instruction standard (Codex and a growing
@@ -273,7 +283,7 @@ export function writeCursorRule(root, store) {
     const file = join(root, ".cursor", "rules", "hunch.mdc");
     const body = `---\ndescription: Hunch engineering memory — consult the hunch_* MCP tools before editing\nalwaysApply: true\n---\n\n${renderHunchSection(store, root)}\n`;
     mkdirSync(dirname(file), { recursive: true });
-    writeFileSync(file, body);
+    writeFileAtomic(file, body);
     return file;
 }
 /** Windsurf (Cascade): .windsurf/mcp_config.json — same `mcpServers` shape as
@@ -308,7 +318,7 @@ export function writeWindsurfRule(root, store) {
     const file = join(root, ".windsurf", "rules", "hunch.md");
     const body = `---\ntrigger: always_on\ndescription: Hunch engineering memory — consult the hunch_* MCP tools before editing\n---\n\n${renderHunchSection(store, root)}\n`;
     mkdirSync(dirname(file), { recursive: true });
-    writeFileSync(file, body);
+    writeFileAtomic(file, body);
     return file;
 }
 /** Cursor's hook API is beta, but its project-level config accepts this standard

package/dist/integrations/scaffold.js

@@ -3,7 +3,8 @@
  *   - .mcp.json          → registers the `hunch` MCP server with Claude Code
  *   - .claude/commands/* → user-triggered slash commands for the §5 workflows
  */
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { readFileSync, existsSync, mkdirSync } from "node:fs";
+import { writeFileAtomic } from "../core/io.js";
 import { join, dirname } from "node:path";
 /** Merge a `hunch` server entry into .mcp.json, preserving other servers.
  *  A non-empty file we cannot parse THROWS instead of being silently replaced
@@ -28,7 +29,9 @@ export function writeMcpJson(root, inv) {
     }
     json.mcpServers = json.mcpServers ?? {};
     json.mcpServers.hunch = { command: inv.command, args: [...inv.args, "mcp"] };
-    writeFileSync(file, JSON.stringify(json, null, 2) + "\n");
+    // Atomic: .mcp.json holds the user's other servers — a torn write would leave
+    // it unparseable, which this writer then refuses to touch (issue #43).
+    writeFileAtomic(file, JSON.stringify(json, null, 2) + "\n");
     return file;
 }
 const WHY_CMD = `---
@@ -76,6 +79,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
 ---
@@ -156,25 +171,39 @@ export function installClaudeHooks(root, hookCmd) {
     if (existed && before === next)
         return { path: file, action: "unchanged" };
     mkdirSync(dirname(file), { recursive: true });
-    writeFileSync(file, next);
+    writeFileAtomic(file, next);
     return { path: file, action: existed ? "updated" : "created" };
 }
+/** Ownership marker for generated slash commands: its presence means Hunch may
+ *  refresh the file; deleting the line hands the file to the user for good. */
+const CMD_MARKER = "<!-- hunch:generated — refreshed by hunch init; delete this line to take ownership -->";
 export function writeSlashCommands(root) {
     const dir = join(root, ".claude", "commands");
     mkdirSync(dir, { recursive: true });
     const written = [];
+    const skipped = [];
     const files = [
         ["hunch-why.md", WHY_CMD],
         ["hunch-fix.md", FIX_CMD],
         ["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);
-        writeFileSync(p, body);
+        // Generic names (capture/heal/audit) are plausibly the USER'S OWN commands;
+        // hunch-prefixed names are namespaced ours. Overwrite an existing file only
+        // when it carries the ownership marker or the hunch- namespace — never
+        // silently replace user content (issue #42). Pre-marker Hunch installs skip
+        // once and report; re-adopt by deleting the file and re-running init.
+        if (existsSync(p) && !name.startsWith("hunch-") && !readFileSync(p, "utf8").includes("hunch:generated")) {
+            skipped.push(p);
+            continue;
+        }
+        writeFileAtomic(p, `${body}\n${CMD_MARKER}\n`);
         written.push(p);
     }
-    return written;
+    return { written, skipped };
 }
 //# sourceMappingURL=scaffold.js.map

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

@@ -5,10 +5,26 @@
  * another workspace or linked worktree. MCP roots are the client-neutral protocol
  * mechanism for following that change.
  */
-import { statSync } from "node:fs";
+import { realpathSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { findRoot, HUNCH_DIR, isDir } from "../core/paths.js";
+/** One canonical spelling per directory. `findRoot` only resolve()s, but a
+ *  client's roots/list URI can spell the same repo differently — VS Code sends
+ *  a lowercase drive letter (`c:\…`) while the spawn cwd has `C:\…`, and Git
+ *  for Windows can surface 8.3/short names. Raw string comparison then treats
+ *  ONE repo as different roots: a full re-prepare (new store + reindex) on
+ *  every connect, or a false "multiple roots equally plausible" refusal
+ *  (issue #54). realpathSync.native returns the on-disk spelling for all of
+ *  these; fall back to the input when the path is transiently unreadable. */
+export function canonicalRootPath(root) {
+    try {
+        return realpathSync.native(root);
+    }
+    catch {
+        return root;
+    }
+}
 function toPath(uri) {
     if (!uri.startsWith("file:"))
         return "";
@@ -44,12 +60,12 @@ export function resolveActiveRoot(rootUris, fallbackCwd) {
         const start = rootStart(toPath(uri));
         if (!start)
             continue;
-        const root = findRoot(start);
+        const root = canonicalRootPath(findRoot(start));
         if (!candidates.includes(root))
             candidates.push(root);
     }
     if (!candidates.length)
-        return findRoot(fallbackCwd);
+        return canonicalRootPath(findRoot(fallbackCwd));
     if (candidates.length === 1)
         return candidates[0];
     const withStore = candidates.filter((candidate) => isDir(join(candidate, HUNCH_DIR)));

package/dist/mcp/server.js

@@ -11,10 +11,10 @@ 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 { canonicalRootPath, 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";
@@ -55,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}` : ""})` : "";
@@ -277,8 +278,11 @@ export function buildServerWithRootControl(initialRoot) {
     let pendingScheduled = false;
     let closed = false;
     const activateRoot = (next) => {
-        const canonical = findRoot(next);
-        if (canonical === root)
+        // canonicalRootPath: a case/8.3 spelling difference must not read as a
+        // DIFFERENT repo — that closed the live store and re-prepared everything
+        // on every same-repo client connect (issue #54).
+        const canonical = canonicalRootPath(findRoot(next));
+        if (canonical === canonicalRootPath(root))
             return;
         const prepared = prepareRoot(canonical, explicitOverlay, true);
         const previous = store;
@@ -385,12 +389,18 @@ export function buildServerWithRootControl(initialRoot) {
                 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 */ }
             }
+            // Stamp check in EVERY mode, not only shared: a CLI capture or post-commit
+            // hook in another terminal writes JSON that mtime-invalidated loadAll sees
+            // immediately, while the SQLite FTS/graph index this long-lived process
+            // serves would stay frozen at startup — split-brain answers within one
+            // session (JSON-backed tools fresh, query/structure/dependents stale)
+            // until restart (issue #49).
+            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.");
@@ -912,6 +922,96 @@ export function buildServerWithRootControl(initialRoot) {
             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.",

package/dist/store/compact.js

@@ -58,6 +58,12 @@ export function planCompaction(input, opts) {
                 continue; // d is being removed → its references don't count
             if (d.supersedes)
                 refDec.add(d.supersedes);
+            // superseded_by is a reference too: supersedeIn() sets old.superseded_by
+            // without requiring the successor's `supersedes`, so removing a later-
+            // rejected successor would leave the surviving record with a dangling
+            // pointer AND permanently non-live for its topic (issue #36).
+            if (d.superseded_by)
+                refDec.add(d.superseded_by);
             if (d.caused_by_bug)
                 refBug.add(d.caused_by_bug);
         }

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
@@ -753,11 +760,14 @@ export class HunchStore {
         const symbols = this.recs("symbols");
         const components = this.recs("components");
         const asOf = opts.asOf;
-        const matchedSymbols = symbols.filter((s) => s.file === target || s.name === target || s.id === target || s.file.endsWith(target));
+        // pathRelated, not bare endsWith: "scenario.ts".endsWith("io.ts") is true,
+        // so an unanchored suffix pulled unrelated files' records into why()/the
+        // pre-edit grounding block (issue #32). Segment-anchored matching only.
+        const matchedSymbols = symbols.filter((s) => s.file === target || s.name === target || s.id === target || pathRelated(s.file, target));
         const symIds = new Set(matchedSymbols.map((s) => s.id));
         const fileSet = new Set(matchedSymbols.map((s) => s.file));
         const isPath = target.includes("/") || target.includes(".");
-        const fileMatch = (files) => files.some((f) => f === target || (isPath && (f.endsWith(target) || target.endsWith(f))) || fileSet.has(f));
+        const fileMatch = (files) => files.some((f) => f === target || (isPath && pathRelated(f, target)) || fileSet.has(f));
         return {
             target,
             decisions: decisions.filter((d) => (fileMatch(d.related_files) || d.related_components.some((c) => components.find((x) => x.id === c && fileMatch(x.paths))))
@@ -978,6 +988,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 +1444,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 +1476,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 +1491,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
@@ -1495,7 +1528,9 @@ const RRF_W_GRAPH = numEnv("HUNCH_RRF_W_GRAPH", 0.5);
 const GRAPH_GAMMA = numEnv("HUNCH_GRAPH_GAMMA", 0.25);
 function numEnv(name, dflt) {
     const v = Number(process.env[name]);
-    return Number.isFinite(v) && v > 0 ? v : dflt;
+    // >= 0, not > 0: zero is the documented kill-switch (HUNCH_RRF_W_*=0 disables
+    // a stream); rejecting it silently re-enabled the default weight (issue #33).
+    return Number.isFinite(v) && v >= 0 ? v : dflt;
 }
 /** Pack a vector's exact bytes for SQLite. Explicit offset+length so a SUBARRAY
  *  view (byteOffset != 0) writes only its slice, not the whole backing buffer.