@davesheffer/hunch 0.1.0

package/dist/integrations/hooks.js

@@ -0,0 +1,80 @@
+/**
+ * Git post-commit hook installer (DESIGN.md §4 / §6). The hook fires the
+ * learning loop after every commit. Loop-guarded via the HUNCH_SYNC env var, and
+ * backgrounded so it never slows a commit down. Existing hooks are preserved —
+ * we append a guarded block rather than clobbering.
+ */
+import { readFileSync, writeFileSync, existsSync, chmodSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { hooksDir } from "../extractors/git.js";
+const MARK = "# >>> hunch post-commit >>>";
+const ENDMARK = "# <<< hunch post-commit <<<";
+function block(invocation) {
+    return [
+        MARK,
+        'if [ -z "$HUNCH_SYNC" ]; then',
+        "  export HUNCH_SYNC=1",
+        `  ( ${invocation} sync --from-hook --quiet >/dev/null 2>&1 || true ) &`,
+        "fi",
+        ENDMARK,
+    ].join("\n");
+}
+export function installPostCommitHook(root, invocation) {
+    const dir = hooksDir(root);
+    const abs = dir.startsWith("/") ? dir : join(root, dir);
+    mkdirSync(abs, { recursive: true });
+    const hookPath = join(abs, "post-commit");
+    const blk = block(invocation);
+    if (!existsSync(hookPath)) {
+        writeFileSync(hookPath, `#!/bin/sh\n${blk}\n`);
+        chmodSync(hookPath, 0o755);
+        return { path: hookPath, action: "created" };
+    }
+    const cur = readFileSync(hookPath, "utf8");
+    if (cur.includes(MARK)) {
+        // replace our managed block (invocation may have changed)
+        const updated = cur.replace(new RegExp(`${escapeRe(MARK)}[\\s\\S]*?${escapeRe(ENDMARK)}`), blk);
+        if (updated === cur)
+            return { path: hookPath, action: "unchanged" };
+        writeFileSync(hookPath, updated);
+        chmodSync(hookPath, 0o755);
+        return { path: hookPath, action: "updated" };
+    }
+    const appended = cur.endsWith("\n") ? `${cur}${blk}\n` : `${cur}\n${blk}\n`;
+    writeFileSync(hookPath, appended);
+    chmodSync(hookPath, 0o755);
+    return { path: hookPath, action: "appended" };
+}
+function escapeRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+const PRE_MARK = "# >>> hunch pre-commit (constraint guard) >>>";
+const PRE_END = "# <<< hunch pre-commit <<<";
+/** Install a pre-commit constraint guard (DESIGN §4 enforcement). Advisory by
+ *  default (prints invariants in scope, never blocks); pass strict to fail the
+ *  commit on a blocking invariant. Preserves any existing pre-commit hook. */
+export function installPreCommitHook(root, invocation, strict = false) {
+    const dir = hooksDir(root);
+    const abs = dir.startsWith("/") ? dir : join(root, dir);
+    mkdirSync(abs, { recursive: true });
+    const hookPath = join(abs, "pre-commit");
+    const cmd = `${invocation} check --staged${strict ? " --strict" : ""}`;
+    const blk = [PRE_MARK, strict ? cmd : `${cmd} || true`, PRE_END].join("\n");
+    if (!existsSync(hookPath)) {
+        writeFileSync(hookPath, `#!/bin/sh\n${blk}\n`);
+        chmodSync(hookPath, 0o755);
+        return { path: hookPath, action: "created" };
+    }
+    const cur = readFileSync(hookPath, "utf8");
+    if (cur.includes(PRE_MARK)) {
+        const updated = cur.replace(new RegExp(`${escapeRe(PRE_MARK)}[\\s\\S]*?${escapeRe(PRE_END)}`), blk);
+        if (updated === cur)
+            return { path: hookPath, action: "unchanged" };
+        writeFileSync(hookPath, updated);
+        return { path: hookPath, action: "updated" };
+    }
+    writeFileSync(hookPath, cur.endsWith("\n") ? `${cur}${blk}\n` : `${cur}\n${blk}\n`);
+    chmodSync(hookPath, 0o755);
+    return { path: hookPath, action: "appended" };
+}
+//# sourceMappingURL=hooks.js.map

package/dist/integrations/mergeDriver.js

@@ -0,0 +1,41 @@
+/**
+ * Wires up the structured `.hunch/` git merge driver (store/merge.ts):
+ *   - `.gitattributes` (committed) routes the .hunch JSON files through merge=hunch,
+ *   - local git config maps merge=hunch to `hunch merge-driver …` (per clone, so
+ *     each teammate runs `hunch init` to register it).
+ */
+import { execFileSync } from "node:child_process";
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { writeFileAtomic } from "../core/io.js";
+// Route the .hunch JSON records through the structured driver — but NOT the
+// manifest (an id-less `{schema_version}` object the driver can't merge by id; a
+// normal text merge with conflict markers is the right behavior for it).
+const ATTR_LINES = [".hunch/**/*.json merge=hunch", ".hunch/manifest.json merge=text"];
+export function installMergeDriver(root, invShell) {
+    // 1. .gitattributes — committed, shared with the team so the routing travels.
+    const attrPath = join(root, ".gitattributes");
+    let text = existsSync(attrPath) ? readFileSync(attrPath, "utf8") : "";
+    let attrAction = "present";
+    for (const line of ATTR_LINES) {
+        if (!text.split(/\r?\n/).some((l) => l.trim() === line)) {
+            const sep = text && !text.endsWith("\n") ? "\n" : "";
+            text += sep + line + "\n";
+            attrAction = "written";
+        }
+    }
+    if (attrAction === "written")
+        writeFileAtomic(attrPath, text);
+    // 2. Local git config — the driver definition is per-clone (it references this
+    //    machine's node + cli path), so it is NOT committed; teammates re-run init.
+    const driver = `${invShell} merge-driver "%O" "%A" "%B" "%P"`;
+    try {
+        execFileSync("git", ["config", "merge.hunch.name", "hunch structured JSON merge"], { cwd: root });
+        execFileSync("git", ["config", "merge.hunch.driver", driver], { cwd: root });
+    }
+    catch {
+        return { action: `${attrAction} .gitattributes — but \`git config\` failed (not a git repo?)` };
+    }
+    return { action: `${attrAction} .gitattributes + registered merge.hunch driver` };
+}
+//# sourceMappingURL=mergeDriver.js.map

package/dist/integrations/scaffold.js

@@ -0,0 +1,74 @@
+/**
+ * Writes the two remaining Claude Code integration surfaces (DESIGN.md §7):
+ *   - .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 { join } from "node:path";
+/** Merge a `hunch` server entry into .mcp.json, preserving other servers. */
+export function writeMcpJson(root, inv) {
+    const file = join(root, ".mcp.json");
+    let json = {};
+    if (existsSync(file)) {
+        try {
+            json = JSON.parse(readFileSync(file, "utf8"));
+        }
+        catch {
+            json = {};
+        }
+    }
+    json.mcpServers = json.mcpServers ?? {};
+    json.mcpServers.hunch = { command: inv.command, args: [...inv.args, "mcp"] };
+    writeFileSync(file, JSON.stringify(json, null, 2) + "\n");
+    return file;
+}
+const WHY_CMD = `---
+description: Explain why a file or symbol is the way it is, from Hunch
+---
+Use the \`hunch_why\` MCP tool on **$ARGUMENTS** (a file path or symbol name).
+
+Then summarize, with citations:
+- the **decisions** that shaped it (id + rationale),
+- the **constraints** that must not break,
+- the **bug history** behind it (root causes).
+
+Cite record ids and their provenance/confidence. If Hunch returns nothing,
+say so plainly and suggest running \`hunch index\` or \`hunch backfill\`.
+`;
+const FIX_CMD = `---
+description: Fix a bug grounded in Hunch (past root causes, constraints, blast radius)
+---
+We are fixing: **$ARGUMENTS**
+
+Follow the Hunch-grounded workflow (DESIGN §5) — do NOT skip the memory lookups:
+1. \`hunch_bug_lineage("$ARGUMENTS")\` — has this class of bug happened before? what was the root cause and the fix?
+2. Identify the suspect symbol/file, then \`hunch_get_dependents(<symbol>)\` to learn the blast radius.
+3. \`hunch_check_constraints(<scope>)\` — list invariants you must preserve.
+4. Propose a fix that honors past root causes AND constraints. Apply it and run the tests.
+5. If the fix encodes a non-trivial choice, \`hunch_record_decision(...)\` so the next session is grounded in it.
+`;
+const FRAGILE_CMD = `---
+description: Report the most fragile parts of this codebase, with evidence
+---
+Ask Hunch for the fragility ranking (run \`hunch fragile\` or query Hunch),
+then produce a **fragility report with evidence**: the specific files/functions,
+the bug history behind them, their churn and fan-in, and any missing guards.
+Avoid generic advice — every claim must cite a Hunch record or metric.
+`;
+export function writeSlashCommands(root) {
+    const dir = join(root, ".claude", "commands");
+    mkdirSync(dir, { recursive: true });
+    const written = [];
+    const files = [
+        ["hunch-why.md", WHY_CMD],
+        ["hunch-fix.md", FIX_CMD],
+        ["hunch-fragile.md", FRAGILE_CMD],
+    ];
+    for (const [name, body] of files) {
+        const p = join(dir, name);
+        writeFileSync(p, body);
+        written.push(p);
+    }
+    return written;
+}
+//# sourceMappingURL=scaffold.js.map

package/dist/mcp/server.js

@@ -0,0 +1,233 @@
+/**
+ * MCP server — the structured two-way API into the Hunch (DESIGN.md §7 / App. A).
+ * Exposes read tools (query/why/bug_lineage/check_constraints/get_dependents) and
+ * a write tool (record_decision). Registered with Claude Code via .mcp.json.
+ *
+ * STDIO PROTOCOL RULE: stdout carries JSON-RPC — never console.log here. All
+ * diagnostics go to stderr.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { hunchPaths, findRoot } from "../core/paths.js";
+import { HunchStore } from "../store/hunchStore.js";
+import { selectEmbedder } from "../store/embedder.js";
+import { decisionId } from "../core/ids.js";
+import { revParse } from "../extractors/git.js";
+import { formatContext } from "../core/format.js";
+const ok = (text) => ({ content: [{ type: "text", text }] });
+const err = (text) => ({ content: [{ type: "text", text }], isError: true });
+// Read-side token budgets: every tool result is injected into a Claude Code
+// session, so an uncapped list pollutes the context window. Cap each list to its
+// highest-signal head (records are pre-sorted by severity/confidence) and tell the
+// caller what was withheld rather than truncating silently.
+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 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}` : ""})` : "";
+/** Resolve a free-form target (symbol id / name / file path) to symbol records. */
+function resolveSymbols(store, target) {
+    const syms = store.json.loadAll("symbols");
+    const byId = syms.find((s) => s.id === target);
+    if (byId)
+        return [byId];
+    const byName = syms.filter((s) => s.name === target);
+    if (byName.length)
+        return byName;
+    return syms.filter((s) => s.file === target || s.file.endsWith(target));
+}
+export function buildServer(root) {
+    const store = new HunchStore(hunchPaths(root));
+    // Ensure the SQLite index reflects the JSON source of truth on startup.
+    try {
+        store.reindex();
+    }
+    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: "0.1.0" });
+    // -- hunch_query ----------------------------------------------------------
+    server.registerTool("hunch_query", {
+        title: "Query Hunch",
+        description: "Full-text + graph search across the engineering memory (decisions, bugs, constraints, components, symbols). Returns ranked records with provenance. Use this to ask 'why' questions about the codebase.",
+        inputSchema: { query: z.string().describe("A natural-language question or keywords.") },
+    }, async ({ query }) => {
+        const hits = await store.hybridSearch(query, QUERY_HITS, { embedder: await embedderReady });
+        if (!hits.length)
+            return ok(`No matches for "${query}".`);
+        const lines = hits.map((h) => {
+            const r = store.resolve(h.ref);
+            return `• [${h.kind}] ${h.ref} — ${h.title}\n    ${h.snippet}${provLine(r?.record)}`;
+        });
+        return ok(`Top matches for "${query}":\n\n${lines.join("\n")}`);
+    });
+    // -- hunch_why ------------------------------------------------------------
+    server.registerTool("hunch_why", {
+        title: "Explain why a file/symbol is the way it is",
+        description: "Return the decisions, bugs, and constraints that explain a file path or symbol — the 'why' and the 'what must not break', with evidence.",
+        inputSchema: { target: z.string().describe("A file path (e.g. src/auth/session.ts) or symbol name.") },
+    }, async ({ target }) => {
+        const w = store.why(target);
+        // Highest-signal first, then cap: invariants by severity, decisions by
+        // confidence, bugs by severity — so a hot file's trim drops the tail, not
+        // the records that matter most.
+        const decisions = [...w.decisions].sort((a, b) => (b.provenance.confidence ?? 0) - (a.provenance.confidence ?? 0));
+        const constraints = [...w.constraints].sort((a, b) => (SEV_CONSTRAINT[b.severity] ?? 0) - (SEV_CONSTRAINT[a.severity] ?? 0));
+        const bugs = [...w.bugs].sort((a, b) => (SEV_BUG[b.severity] ?? 0) - (SEV_BUG[a.severity] ?? 0));
+        const parts = [`Why for "${target}":`];
+        if (decisions.length)
+            parts.push(`\nDECISIONS:\n${decisions.slice(0, WHY_CAP).map((d) => `  • ${d.id} [${d.status}] ${d.title}\n      ${d.decision}${provLine(d)}`).join("\n")}${more(decisions.length, WHY_CAP, "narrow the target")}`);
+        if (constraints.length)
+            parts.push(`\nCONSTRAINTS (must not break):\n${constraints.slice(0, WHY_CAP).map((c) => `  • ${c.id} [${c.severity}] ${c.statement}${provLine(c)}`).join("\n")}${more(constraints.length, WHY_CAP)}`);
+        if (bugs.length)
+            parts.push(`\nBUG HISTORY:\n${bugs.slice(0, WHY_CAP).map((b) => `  • ${b.id} [${b.status}/${b.severity}] ${b.title}\n      root cause: ${b.root_cause}${provLine(b)}`).join("\n")}${more(bugs.length, WHY_CAP)}`);
+        if (w.components.length)
+            parts.push(`\nCOMPONENTS: ${w.components.map((c) => `${c.name} (${c.id})`).join(", ")}`);
+        if (w.symbols.length)
+            parts.push(`\nSYMBOLS: ${w.symbols.slice(0, WHY_CAP * 2).map((s) => `${s.name} [fan-in ${s.metrics.fan_in}, churn ${s.metrics.churn_90d}]`).join(", ")}${more(w.symbols.length, WHY_CAP * 2)}`);
+        if (parts.length === 1)
+            parts.push("\n(No recorded decisions/bugs/constraints yet for this target.)");
+        return ok(parts.join("\n"));
+    });
+    // -- hunch_bug_lineage ----------------------------------------------------
+    server.registerTool("hunch_bug_lineage", {
+        title: "Find related bugs and their lineage",
+        description: "Given a symptom description or a symbol, return matching bugs with their lineage (introduced → fixed → recurrence) so the agent doesn't re-discover past root causes.",
+        inputSchema: { symptom_or_symbol: z.string().describe("A symptom description or a symbol/file.") },
+    }, async ({ symptom_or_symbol }) => {
+        const bugs = store.bugLineage(symptom_or_symbol);
+        if (!bugs.length)
+            return ok(`No matching bugs for "${symptom_or_symbol}".`);
+        const lines = bugs.map((b) => {
+            const l = b.lineage;
+            return `• ${b.id} [${b.status}/${b.severity}] ${b.title}\n    symptom: ${b.symptom}\n    root cause: ${b.root_cause}\n    lineage: introduced=${l.introduced_commit ?? "?"} fixed=${l.fixed_commit ?? "?"} recurrence_of=${l.recurrence_of ?? "—"} → decision=${l.spawned_decision ?? "—"} constraint=${l.spawned_constraint ?? "—"}${provLine(b)}`;
+        });
+        return ok(`Bugs related to "${symptom_or_symbol}":\n\n${lines.join("\n")}`);
+    });
+    // -- hunch_check_constraints ---------------------------------------------
+    server.registerTool("hunch_check_constraints", {
+        title: "Check invariants in scope",
+        description: "Return constraints whose scope matches a glob/path, sorted by severity. Call this BEFORE editing code to avoid breaking intentional invariants.",
+        inputSchema: { scope: z.string().describe("A path or glob, e.g. src/auth/** or src/auth/session.ts") },
+    }, async ({ scope }) => {
+        const cons = store.checkConstraints(scope);
+        if (!cons.length)
+            return ok(`No constraints in scope "${scope}".`);
+        const lines = cons.map((c) => `• ${c.id} [${c.severity}/${c.enforcement}] ${c.statement}\n    rationale: ${c.rationale}${provLine(c)}`);
+        return ok(`Constraints affecting "${scope}":\n\n${lines.join("\n")}`);
+    });
+    // -- hunch_get_dependents -------------------------------------------------
+    server.registerTool("hunch_get_dependents", {
+        title: "Blast radius (transitive dependents)",
+        description: "Return everything that transitively depends on a symbol/component (callers + dependent components) so a change's blast radius is known before editing.",
+        inputSchema: { symbol: z.string().describe("A symbol id, symbol name, or file path.") },
+    }, async ({ symbol }) => {
+        const matches = resolveSymbols(store, symbol);
+        const ids = matches.length ? matches.map((s) => s.id) : [symbol];
+        const all = new Map();
+        for (const id of ids)
+            for (const d of store.getDependents(id))
+                if (!all.has(d.id))
+                    all.set(d.id, d);
+        const deps = [...all.values()].sort((a, b) => a.depth - b.depth);
+        if (!deps.length)
+            return ok(`Nothing depends on "${symbol}" (leaf node, or not indexed).`);
+        // Nearest dependents first (sorted by depth); cap the tail so a high-fan-in
+        // symbol can't flood the session context.
+        const lines = deps.slice(0, DEP_CAP).map((d) => `  • [depth ${d.depth}] ${d.via} (${d.id})`);
+        return ok(`Blast radius of "${symbol}" — ${deps.length} dependent(s):\n${lines.join("\n")}${more(deps.length, DEP_CAP, "closest shown first")}`);
+    });
+    // -- hunch_context (surgical retrieval) -----------------------------------
+    server.registerTool("hunch_context", {
+        title: "Assemble the minimal relevant Hunch slice for a task",
+        description: "Given a file or symbol you're about to work on, return the MINIMAL relevant memory — invariants to preserve, decisions explaining the design, bug history not to reintroduce, and the blast radius — as a compact brief. Call this FIRST when starting work on something.",
+        inputSchema: {
+            target: z.string().describe("A file path or symbol you're about to edit."),
+            budget_tokens: z.number().optional().describe("Rough token budget for the brief (default 1500)."),
+        },
+    }, async ({ target, budget_tokens }) => {
+        return ok(formatContext(store.assembleContext(target, budget_tokens ?? 1500)));
+    });
+    // -- hunch_record_decision (write-back) -----------------------------------
+    server.registerTool("hunch_record_decision", {
+        title: "Record a decision (write-back)",
+        description: "Persist a new Decision (ADR) into Hunch with provenance. Use after making a non-trivial design choice so future sessions are grounded in it.",
+        inputSchema: {
+            decision: z.object({
+                title: z.string(),
+                context: z.string().optional(),
+                decision: z.string().optional(),
+                consequences: z.array(z.string()).optional(),
+                alternatives_rejected: z.array(z.string()).optional(),
+                related_files: z.array(z.string()).optional(),
+                related_components: z.array(z.string()).optional(),
+                status: z.enum(["proposed", "accepted", "rejected", "superseded"]).optional(),
+                commit: z.string().optional(),
+            }),
+        },
+    }, async ({ decision }) => {
+        try {
+            // Commit-keyed on the CANONICAL full sha (resolved via git rev-parse), so a
+            // human passing the short sha they see in `commit` produces the SAME id as
+            // the auto-sync path (which keys on the full sha) — UPGRADING the auto-draft
+            // instead of duplicating it. If the ref can't be resolved to a real full
+            // sha, fall back to the title/manual namespace so we never key on a raw,
+            // unverified string that could collide with (or orphan) a real commit id.
+            const resolved = decision.commit ? revParse(decision.commit, root) : null;
+            const fullSha = resolved && /^[0-9a-f]{40}$/.test(resolved) ? resolved : null;
+            const id = fullSha ? decisionId(fullSha) : decisionId(`manual:${decision.title}`);
+            // Preserve the ADR lineage: upgrading an auto-draft yields the composite
+            // provenance the design specifies.
+            const existing = store.json.get("decisions", id);
+            const source = existing && existing.provenance.source.includes("llm_draft")
+                ? "llm_draft+human_confirmed"
+                : "human_confirmed";
+            const rec = {
+                id,
+                title: decision.title,
+                status: decision.status ?? "accepted",
+                context: decision.context ?? existing?.context ?? "",
+                decision: decision.decision ?? existing?.decision ?? "",
+                consequences: decision.consequences ?? [],
+                alternatives_rejected: decision.alternatives_rejected ?? [],
+                related_components: decision.related_components ?? existing?.related_components ?? [],
+                related_files: decision.related_files ?? existing?.related_files ?? [],
+                supersedes: existing?.supersedes ?? null,
+                caused_by_bug: existing?.caused_by_bug ?? null,
+                commit: decision.commit ?? existing?.commit ?? null,
+                provenance: { source, confidence: 0.95, evidence: decision.related_files ?? existing?.provenance.evidence ?? [] },
+                date: new Date().toISOString(),
+            };
+            store.json.put("decisions", rec);
+            store.reindex();
+            const note = decision.commit && !fullSha ? ` (note: commit "${decision.commit}" could not be resolved — recorded as a standalone decision, not linked to a commit)` : "";
+            return ok(`Recorded decision ${id}: "${rec.title}" (status ${rec.status}, ${source}).${note}`);
+        }
+        catch (e) {
+            return err(`Failed to record decision: ${e.message}`);
+        }
+    });
+    return server;
+}
+function provLine(record) {
+    const p = record?.provenance;
+    if (!p)
+        return "";
+    const v = p.last_verified ? `, verified ${p.last_verified.slice(0, 10)}` : "";
+    return `\n      ⟨${p.source ?? "?"}, confidence ${p.confidence ?? "?"}${v}⟩`;
+}
+/** Start the stdio server (called by `hunch mcp`). */
+export async function startServer(cwd = process.cwd()) {
+    const root = findRoot(cwd);
+    const server = buildServer(root);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`[hunch-mcp] serving Hunch at ${root} over stdio`);
+}
+//# sourceMappingURL=server.js.map

package/dist/store/compact.js

@@ -0,0 +1,100 @@
+const DAY_MS = 86_400_000;
+export function planCompaction(input, opts) {
+    const maxAgeDays = opts.maxAgeDays ?? 180;
+    const minConfidence = opts.minConfidence ?? 0.35;
+    const ageDays = (iso) => {
+        const t = Date.parse(iso);
+        return Number.isNaN(t) ? 0 : (opts.now - t) / DAY_MS; // unparseable date → treat as new (don't prune)
+    };
+    // Step 1: INTRINSIC low-value reason (ignoring cross-references). Curated records
+    // (accepted / human-confirmed / open bugs / constraints) are never candidates.
+    const decReason = (d) => {
+        if (d.status === "accepted" || d.provenance.source.includes("human_confirmed"))
+            return null;
+        const low = d.provenance.confidence < minConfidence;
+        const old = ageDays(d.date) >= maxAgeDays;
+        if (d.status === "rejected")
+            return "rejected draft";
+        if (d.status === "superseded" && old)
+            return `superseded, ${Math.round(ageDays(d.date))}d old`;
+        if (d.status === "proposed" && low && old)
+            return `stale low-confidence draft (${d.provenance.confidence}, ${Math.round(ageDays(d.date))}d)`;
+        return null;
+    };
+    const bugReason = (b) => {
+        if (b.provenance.source.includes("human_confirmed"))
+            return null;
+        // Only fixed, low-confidence bugs that did NOT anchor a lineage (spawned a
+        // constraint OR a decision) are prunable; open/investigating/regressed are kept.
+        if (b.status === "fixed" && b.provenance.confidence < minConfidence && !b.lineage.spawned_constraint && !b.lineage.spawned_decision) {
+            return "resolved low-confidence bug";
+        }
+        return null;
+    };
+    const decReasons = new Map();
+    for (const d of input.decisions) {
+        const r = decReason(d);
+        if (r)
+            decReasons.set(d.id, r);
+    }
+    const bugReasons = new Map();
+    for (const b of input.bugs) {
+        const r = bugReason(b);
+        if (r)
+            bugReasons.set(b.id, r);
+    }
+    // Step 2: greatest-fixpoint reference safety. Start with ALL candidates, then
+    // repeatedly drop any candidate that a SURVIVING record (one not currently slated
+    // for removal) still points to. References from records that are themselves being
+    // removed don't protect anything — so two dead drafts can't keep each other alive,
+    // and reference cycles among removable records resolve correctly.
+    const remDec = new Set(decReasons.keys());
+    const remBug = new Set(bugReasons.keys());
+    for (;;) {
+        const refDec = new Set();
+        const refBug = new Set();
+        for (const d of input.decisions) {
+            if (remDec.has(d.id))
+                continue; // d is being removed → its references don't count
+            if (d.supersedes)
+                refDec.add(d.supersedes);
+            if (d.caused_by_bug)
+                refBug.add(d.caused_by_bug);
+        }
+        for (const b of input.bugs) {
+            if (remBug.has(b.id))
+                continue;
+            if (b.lineage.recurrence_of)
+                refBug.add(b.lineage.recurrence_of);
+            if (b.lineage.spawned_decision)
+                refDec.add(b.lineage.spawned_decision);
+        }
+        for (const c of input.constraints) {
+            if (c.source_decision)
+                refDec.add(c.source_decision); // constraints are never removed → always survivors
+        }
+        let changed = false;
+        for (const id of [...remDec])
+            if (refDec.has(id)) {
+                remDec.delete(id);
+                changed = true;
+            }
+        for (const id of [...remBug])
+            if (refBug.has(id)) {
+                remBug.delete(id);
+                changed = true;
+            }
+        if (!changed)
+            break;
+    }
+    const remove = [];
+    for (const d of input.decisions)
+        if (remDec.has(d.id))
+            remove.push({ kind: "decisions", id: d.id, title: d.title, reason: decReasons.get(d.id) });
+    for (const b of input.bugs)
+        if (remBug.has(b.id))
+            remove.push({ kind: "bugs", id: b.id, title: b.title, reason: bugReasons.get(b.id) });
+    // constraints are invariants — intentionally never auto-removed.
+    return { remove, considered: input.decisions.length + input.bugs.length };
+}
+//# sourceMappingURL=compact.js.map

package/dist/store/db.js

@@ -0,0 +1,19 @@
+/** Thin wrapper around better-sqlite3 for the derived index. */
+import Database from "better-sqlite3";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { SCHEMA_SQL } from "./schema.js";
+export function openDb(sqlitePath) {
+    mkdirSync(dirname(sqlitePath), { recursive: true });
+    const db = new Database(sqlitePath);
+    db.pragma("busy_timeout = 5000");
+    db.exec(SCHEMA_SQL);
+    return db;
+}
+/** In-memory db (tests / ephemeral queries). */
+export function openMemoryDb() {
+    const db = new Database(":memory:");
+    db.exec(SCHEMA_SQL);
+    return db;
+}
+//# sourceMappingURL=db.js.map