@davesheffer/hunch 1.9.4 → 1.10.0

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

@@ -14,7 +14,7 @@ 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";
@@ -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}` : ""})` : "";
@@ -912,6 +913,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/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.4",
+  "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.",