@davesheffer/hunch 1.1.0 → 1.2.0

package/README.md

@@ -105,35 +105,21 @@ is its complement — it keeps your *docs* honest to the graph (**doc ≠ graph*
 says one thing; the decision that actually governs the file says another. Both are "memory that stays
 true"; you want both.
 
-The anchor is one optional field. A decision can carry a **`topic`** — the thing it's the current answer
-for (e.g. `"auth.session"`) — and topic gives you a query contract: **current** (the one live answer),
-**history** (the supersede trail), and **rejected** (what was ruled out and why). It's fully
-backward-compatible: `topic` defaults to `null`, there's **no schema bump**, and existing graphs load
-unchanged.
-
-- **Read-time grounding.** The pre-edit (PreToolUse) hook now surfaces a file's topic-anchored decisions
-  *before* the AI writes — with doc-precedence framing ("follow the graph, not a stale doc") and what each
-  decision **rejected**, so the model doesn't happily re-add the approach you already ruled out.
-- **`anchor-stale` drift — deterministic, no guessing.** A new drift kind fires when a file is still
-  anchored to a **superseded** decision while a **current** one exists for its topic. It shows up in
-  `hunch doctor` and in a CI-gateable `hunch drift`:
-
-  ```bash
-  hunch drift        # ⛔ exits non-zero on anchor-stale drift or a topic collision (>1 live decision)
-  ```
-
-  It only fires on **explicit** topic anchors — no semantic guessing, no false positives on prose it can't
-  read.
-- **Capture, gated.** `hunch_record_decision` now enforces a store-scoped **uniqueness guard**: it refuses
-  a *second* live decision for a topic (you're never silently governed by two). The richer path is the new
-  **`hunch_capture_decision`** tool — it returns a one-question-at-a-time grilling protocol plus a
-  capture-session token; `record_decision` accepts an optional `capture_token`. Un-token'd writes still
-  work, they just get a nudge toward `/capture`. **`hunch_current_decision(topic)`** returns the one answer
-  that currently governs a topic.
-- **`hunch reconcile-topics`.** A git merge is the one thing that can create two live decisions for a
-  topic. This scans for it and exits non-zero — wire it into a post-merge hook or CI.
-- **`hunch heal`** + the **`/capture`** and **`/heal`** slash commands (scaffolded by `hunch init`) do
-  **read-only** doc↔graph reconciliation — they surface the mismatch and never rewrite your prose silently.
+A decision can be anchored to a **topic** (e.g. `"auth.session"`), and a topic always has one live
+answer: the **current** decision, its **history**, and what was **rejected** along the way. Existing
+graphs are unaffected until you opt in.
+
+- **Read-time grounding.** Before the AI edits a file — or a markdown doc like `AGENTS.md` — it's told
+  which decision is *current* (follow the graph, not a stale doc) and what was **rejected**, so it
+  doesn't re-add the approach you already ruled out.
+- **Drift, caught deterministically.** Prose or a file still describing a **superseded** decision is
+  flagged in `hunch doctor`, and `hunch drift` exits non-zero so CI can gate on it. It only fires on
+  explicit anchors — never a semantic guess.
+- **Capture, interviewed.** `/capture` walks a decision to a resolved state — topic, rationale, and
+  rejected alternatives — before it's written, and the graph refuses to hold **two live decisions on
+  one topic**. `hunch reconcile-topics` catches the one case a git merge can create, for human resolution.
+- **`hunch heal`** + the **`/heal`** slash command do **read-only** doc↔graph reconciliation — they show
+  exactly what disagrees and never rewrite your prose silently.
 
 → [docs](https://hunch-pi.vercel.app/docs#grounding)
 
@@ -145,8 +131,18 @@ cd your-repo
 hunch init                          # scaffold .hunch/, index, install hooks, wire up assistants
 hunch backfill --since 90d          # cold start: seed decisions from recent git history
 hunch why src/auth/session.ts       # …then ask your assistant: "why is X built this way?"
+hunch structure src/auth            # the map, from the graph — no grep rounds
 ```
 
+**Claude Code users — one-step plugin install** (MCP tools + `/hunch:capture`, `/hunch:heal`, `/hunch:why`, `/hunch:fix`, `/hunch:fragile`):
+
+```text
+/plugin marketplace add davesheffer/hunch
+/plugin install hunch@hunch
+```
+
+Then `hunch init` in each repo you want remembered (the plugin brings the tools; init builds the graph + hooks).
+
 `hunch init` scaffolds `.hunch/`, indexes the repo, installs the git hooks,
 writes `.mcp.json` + slash commands + an auto-maintained `CLAUDE.md`, and wires up **every
 detected assistant** (Claude Code, Cursor, VS Code/Copilot, Windsurf, Codex, Google Antigravity) to the same
@@ -230,12 +226,10 @@ Plus the **Regression Guard** (re-adding deliberately-retired code) and the
 comments the affected `con_`/`dec_` ids and fails on a blocking one).
 
 Name the actual violation — `record-constraint "…" --scope "src/**" --severity blocking
---forbid-dep "lodash"` — and it blocks the *real* change across the file's whole life instead
-of relaxing to advisory after the file is edited again. The dep matcher reads the **parsed
-import**, so a comment or string naming the module can't false-positive and a submodule
-(`lodash/groupBy`) is still caught; a correction your assistant records gets the same matcher
-automatically. (`--match <regex>` remains a lint-grade textual fallback.) None of these are a
-bypass-proof boundary — deliberate indirection can still route around any rule.
+--forbid-dep "lodash"` — and it blocks the *real* change for the file's whole life, while staying
+quiet on edits that don't break the rule. A comment or string that merely mentions the module can't
+false-positive. None of these are a bypass-proof boundary — deliberate indirection can still route
+around any rule.
 
 ## Working as a team
 
@@ -263,24 +257,15 @@ the same way via the MCP server) — everyone, on every branch, resolves the sam
 ## Private memory (public repo, private context)
 
 Open-source your code without open-sourcing your *reasoning*. **`hunch private`** sets up a
-separate private store in one command — Hunch unions it into every query and guard **locally**
-(MCP and the pre-edit hook see your sensitive decisions/bugs/constraints) while your public
-`.hunch/` stays clean. It writes a gitignored `.hunch/local.json` so it's auto-detected — **no
-env var, no shell-profile edit** (and `HUNCH_PRIVATE_DIR` still overrides per-shell). **Opt-in,
-default-off** (no config → fully inert), and **leak-safe by construction**: committed files and
-the CI PR comment render *public-only*, so a private record can't reach a public surface. Record
-sensitive items with `private: true` (`hunch_record_decision` / `hunch_record_correction`);
-post-commit synthesis can route there too. Every capture is **auto-committed by default** to the
-store it lands in — the private repo is committed + pushed; a public capture is committed to
-`.hunch/` only and rides your next push (Hunch never pushes or merges your code branch) —
-recursion-safe, staging only `.hunch/`. Opt out with `--no-auto-commit`.
+separate private store in one command: your local queries, guards, and assistants see the
+sensitive decisions — but they're never committed to the public repo, and public outputs (like
+the CI PR comment) **can never contain them, by construction**. Opt-in, default-off; captures are
+auto-committed to the store they land in (opt out with `--no-auto-commit`), and Hunch never
+touches your code branch.
 
 Already published a repo *with* its `.hunch/` memory and want it private after the fact?
-`hunch private --repo <url> --migrate` does it in one shot: it **moves** your existing public
-records into the overlay (union by id — nothing is lost), empties the public store, untracks +
-gitignores the `.hunch/` memory tree, and regenerates the assistant grounding (CLAUDE.md, AGENTS.md,
-…) so the repo becomes **code-only**. It commits the private overlay for you and prints the one
-`git` command to commit the now-clean public repo.
+**`hunch private --repo <url> --migrate`** moves the existing memory into the private store —
+nothing lost — and leaves the public repo code-only, telling you the one `git` command left to run.
 → [docs](https://hunch-pi.vercel.app/docs#private)
 
 ## Continuous learning (CI)

package/dist/cli/index.js

@@ -45,7 +45,7 @@ import { updateClaudeMd } from "../integrations/claudemd.js";
 import { writeMcpJson, writeSlashCommands, installClaudeHooks } from "../integrations/scaffold.js";
 import { scaffoldProviders, regenerateGrounding, refreshExistingGrounding } from "../integrations/providers.js";
 import { healClaudeConfigCaseSplit } from "../integrations/claudeConfig.js";
-import { formatContext } from "../core/format.js";
+import { formatContext, formatStructure } from "../core/format.js";
 import { readConfig, writeConfig, FIRMNESS_LEVELS, isFirmness } from "../core/config.js";
 import { blockingInScope, vetoInScope, proposedEditLines } from "../core/hookpolicy.js";
 import { loadGoldenSet, evaluateGraphLift } from "../eval/harness.js";
@@ -708,6 +708,7 @@ program
     const { store, root } = storeFor();
     // Lookup mode: scoped runbook retrieval (search within runbooks, not the whole graph).
     if (opts.find) {
+        store.reindex(); // reflect out-of-band JSON edits before searching (mirrors `hunch query`)
         const emb = opts.semantic ? await selectEmbedder() : undefined;
         const hits = await store.searchRunbooks(opts.find, 5, { embedder: emb });
         if (!hits.length)
@@ -1842,6 +1843,21 @@ program
         store.close();
     }
 });
+// ---- structure (graph-served orientation — the anti-grep) -------------------
+program
+    .command("structure")
+    .description("The indexed shape of the repo, a directory, a file, or a symbol — orient from the graph instead of grep rounds. No target: repo map. Read-only.")
+    .argument("[target]", "a directory, file path, or exact symbol name (omit for the repo map)")
+    .action((target) => {
+    const { store } = storeFor();
+    try {
+        store.reindex(); // reflect out-of-band JSON edits before reading the graph
+        console.log(formatStructure(store.structure(target)));
+    }
+    finally {
+        store.close();
+    }
+});
 // ---- impact (PR impact — read-only, advisory) ------------------------------
 program
     .command("impact")

package/dist/core/format.js

@@ -43,4 +43,50 @@ export function formatContext(ctx) {
         trimmed = trimmed.slice(0, lastNl);
     return trimmed + "\n… (trimmed to budget)\n";
 }
+/** Render a StructureView as a compact orientation brief (hunch_structure). */
+export function formatStructure(v) {
+    const NL = "\n";
+    if (v.kind === "none")
+        return `Nothing indexed matches "${v.target}" — not a known file, directory, or symbol. Run hunch index if the repo changed, or hunch_query for fuzzy search.`;
+    if (v.kind === "repo") {
+        const out = [`# Repo structure (from the graph — no grep needed)`];
+        if (v.components.length) {
+            out.push(`${NL}## Components`);
+            for (const c of v.components)
+                out.push(`- ${c.name}: ${c.responsibility} (${c.paths.join(", ")})`);
+        }
+        out.push(`${NL}## Directories (by symbol count)`);
+        for (const d of v.dirs.slice(0, 20))
+            out.push(`- ${d.dir} — ${d.files} file(s), ${d.symbols} symbol(s)`);
+        if (v.dirs.length > 20)
+            out.push(`  …(+${v.dirs.length - 20} more)`);
+        return out.join(NL);
+    }
+    if (v.kind === "dir") {
+        const out = [`# ${v.dir}/ — ${v.files.length} indexed file(s)`];
+        for (const f of v.files) {
+            const syms = f.symbols.slice(0, 8).map((s) => `${s.name}${s.fan_in ? ` (fan-in ${s.fan_in})` : ""}`).join(", ");
+            out.push(`- ${f.file}: ${syms}${f.symbols.length > 8 ? ` …(+${f.symbols.length - 8})` : ""}`);
+        }
+        return out.join(NL);
+    }
+    if (v.kind === "file") {
+        const out = [`# ${v.file} — outline (${v.symbols.length} symbol(s))`];
+        for (const sy of v.symbols) {
+            out.push(`- ${sy.name} [${sy.kind}] loc ${sy.loc}, fan-in ${sy.fan_in}, fan-out ${sy.fan_out}`);
+            if (sy.callers.length)
+                out.push(`    called by: ${sy.callers.join("; ")}`);
+        }
+        return out.join(NL);
+    }
+    const out = [`# "${v.matches[0]?.name}" — ${v.matches.length} definition site(s)`];
+    for (const m of v.matches) {
+        out.push(`- ${m.name} [${m.kind}] @ ${m.file} (fan-in ${m.fan_in}, fan-out ${m.fan_out})`);
+        if (m.callers.length)
+            out.push(`    called by: ${m.callers.join("; ")}`);
+        if (m.callees.length)
+            out.push(`    reaches:   ${m.callees.join("; ")}`);
+    }
+    return out.join(NL);
+}
 //# sourceMappingURL=format.js.map

package/dist/mcp/server.js

@@ -19,7 +19,7 @@ import { refreshExistingGrounding } from "../integrations/providers.js";
 import { revParse, asOfDate, revExists, lastChangeDate, rangeFiles, rangeDiff, commitFiles, commitDiff, stagedFiles, stagedDiff, pullHunch } from "../extractors/git.js";
 import { flushCapture } from "../integrations/sync.js";
 import { ensureTeamOverlay } from "../integrations/team.js";
-import { formatContext } from "../core/format.js";
+import { formatContext, formatStructure } from "../core/format.js";
 import { compareCandidates } from "../core/compare.js";
 import { checkConformance } from "../core/conformance.js";
 import { renderMarkdown, renderImpact, verdict } from "../core/checkreport.js";
@@ -528,6 +528,14 @@ export function buildServer(root) {
             return err(`Failed to compute merge verdict: ${e.message}`);
         }
     });
+    // -- hunch_structure (graph-served orientation — the anti-grep) ------------
+    server.registerTool("hunch_structure", {
+        title: "The indexed shape of the repo / a dir / a file / a symbol",
+        description: "Orient WITHOUT grep/glob rounds: the graph already holds the repo's structure. No target → repo map (components + directories by symbol weight). A directory → its files with their symbols. A file → its outline (symbols, fan-in/out, callers). An exact symbol name → its definition site(s) with one-hop neighbors. Call this FIRST when exploring unfamiliar code — it tells you exactly which file to read, instead of searching for it.",
+        inputSchema: {
+            target: z.string().optional().describe("A directory, file path, or exact symbol name. Omit for the repo map."),
+        },
+    }, async ({ target }) => ok(formatStructure(store.structure(target))));
     // -- hunch_pr_impact (read-only impact surface — advisory, never gates) ----
     server.registerTool("hunch_pr_impact", {
         title: "PR impact: the dependency + memory surface of a change",

package/dist/store/hunchStore.js

@@ -705,6 +705,70 @@ export class HunchStore {
             decisions: [...decisions.values()],
         };
     }
+    /** Structure view (hunch_structure / hunch structure): serve the indexed shape of
+     *  the repo so an agent ORIENTS from the graph instead of running grep/glob rounds.
+     *  Resolution: no target -> repo map; a directory -> its files+symbols; a file ->
+     *  its outline; a symbol name -> exact definition site(s) with one-hop neighbors.
+     *  Deterministic, read-only, straight from the derived index. */
+    structure(target) {
+        if (!target || !target.trim()) {
+            const components = this.recs("components").map((c) => ({ id: c.id, name: c.name, responsibility: c.responsibility, paths: c.paths }));
+            const rows = this.db.prepare(`SELECT file, count(*) AS n FROM symbols GROUP BY file`).all();
+            const dirs = new Map();
+            for (const r of rows) {
+                const dir = r.file.includes("/") ? r.file.slice(0, r.file.lastIndexOf("/")) : ".";
+                const e = dirs.get(dir) ?? { files: 0, symbols: 0 };
+                e.files++;
+                e.symbols += r.n;
+                dirs.set(dir, e);
+            }
+            return {
+                kind: "repo",
+                components,
+                dirs: [...dirs.entries()].map(([dir, v]) => ({ dir, ...v })).sort((a, b) => b.symbols - a.symbols),
+            };
+        }
+        const t = toPosixTarget(target.trim()).replace(/\/+$/, "");
+        // FILE: exact path or unique suffix
+        const fileRows = this.db.prepare(`SELECT id, name, kind, loc, fan_in, fan_out FROM symbols WHERE file = ? ORDER BY fan_in DESC, name`).all(t);
+        const fileHit = fileRows.length ? t : this.db.prepare(`SELECT DISTINCT file FROM symbols WHERE file LIKE ?`).all(`%/${t}`).map((r) => r.file);
+        const file = typeof fileHit === "string" ? fileHit : fileHit.length === 1 ? fileHit[0] : null;
+        if (file) {
+            const syms = fileRows.length ? fileRows : this.db.prepare(`SELECT id, name, kind, loc, fan_in, fan_out FROM symbols WHERE file = ? ORDER BY fan_in DESC, name`).all(file);
+            return {
+                kind: "file",
+                file,
+                symbols: syms.map((r) => ({ ...r, callers: this.edgeNeighbors(r.id, "in", 5) })),
+            };
+        }
+        // DIRECTORY: any indexed file under the prefix
+        const dirFiles = this.db.prepare(`SELECT file, name, kind, fan_in FROM symbols WHERE file LIKE ? ORDER BY file, fan_in DESC`).all(`${t}/%`);
+        if (dirFiles.length) {
+            const byFile = new Map();
+            for (const r of dirFiles) {
+                const list = byFile.get(r.file) ?? [];
+                list.push({ name: r.name, kind: r.kind, fan_in: r.fan_in });
+                byFile.set(r.file, list);
+            }
+            return { kind: "dir", dir: t, files: [...byFile.entries()].map(([f, symbols]) => ({ file: f, symbols })) };
+        }
+        // SYMBOL: exact name
+        const named = this.db.prepare(`SELECT id, name, kind, file, fan_in, fan_out FROM symbols WHERE name = ? LIMIT 10`).all(t);
+        if (named.length) {
+            return {
+                kind: "symbol",
+                matches: named.map((m) => ({ ...m, callers: this.edgeNeighbors(m.id, "in", 6), callees: this.edgeNeighbors(m.id, "out", 6) })),
+            };
+        }
+        return { kind: "none", target: t };
+    }
+    /** Labelled one-hop edge neighbors of a node ("in" = who reaches it, "out" = what it reaches). */
+    edgeNeighbors(id, dir, limit) {
+        const sql = dir === "in"
+            ? `SELECT e."from" AS nb FROM edges e WHERE e."to" = ? AND e.type IN ('calls','depends_on','imports','contains') LIMIT ?`
+            : `SELECT e."to" AS nb FROM edges e WHERE e."from" = ? AND e.type IN ('calls','depends_on','imports','contains') LIMIT ?`;
+        return this.db.prepare(sql).all(id, limit).map((r) => this.nodeLabel(r.nb));
+    }
     /** Constraints whose scope glob matches a path/glob (hunch_check_constraints).
      *  By default only ACTIVE invariants are returned — a retired constraint is no
      *  longer enforced. Pass `{ asOf }` to instead return the invariants in force at

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
   "description": "Architectural Conformance for AI-generated code: a git-native graph that deterministically blocks AI changes which break your architecture — the semantic invariants (layering, must-reach, dependency direction) pattern-SAST can't express — grounded in the decisions and bugs behind each rule, across any MCP assistant (Claude Code, Cursor, Copilot, Windsurf, Codex).",