# https://github.com/davesheffer/hunch Project Manual

Generated at: 2026-07-12 10:40:42 UTC

## Table of Contents

- [Overview, Repository Layout & System Architecture](#page-1)
- [Change Gate, Constitution & Policy Enforcement](#page-2)
- [Memory Graph, Storage & Data Flow](#page-3)
- [Agent Integrations, Lifecycle Hooks & Synthesis Providers](#page-4)

<a id='page-1'></a>

## Overview, Repository Layout & System Architecture

### Related Pages

Related topics: [Change Gate, Constitution & Policy Enforcement](#page-2), [Memory Graph, Storage & Data Flow](#page-3), [Agent Integrations, Lifecycle Hooks & Synthesis Providers](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/davesheffer/hunch/blob/main/README.md)
- [package.json](https://github.com/davesheffer/hunch/blob/main/package.json)
- [src/cli/index.ts](https://github.com/davesheffer/hunch/blob/main/src/cli/index.ts)
- [src/core/pipeline.ts](https://github.com/davesheffer/hunch/blob/main/src/core/pipeline.ts)
- [src/core/types.ts](https://github.com/davesheffer/hunch/blob/main/src/core/types.ts)
- [src/core/config.ts](https://github.com/davesheffer/hunch/blob/main/src/core/config.ts)
- [src/core/version.ts](https://github.com/davesheffer/hunch/blob/main/src/core/version.ts)
- [src/storage/sqlite.ts](https://github.com/davesheffer/hunch/blob/main/src/storage/sqlite.ts)
- [src/graph/builder.ts](https://github.com/davesheffer/hunch/blob/main/src/graph/builder.ts)
- [src/mcp/server.ts](https://github.com/davesheffer/hunch/blob/main/src/mcp/server.ts)
- [src/providers/index.ts](https://github.com/davesheffer/hunch/blob/main/src/providers/index.ts)
- [src/hooks/lifecycle.ts](https://github.com/davesheffer/hunch/blob/main/src/hooks/lifecycle.ts)

</details>

# Overview, Repository Layout & System Architecture

## Purpose & Scope

`hunch` is a repository-local memory and grounding layer for coding agents (Claude Code, Codex CLI, Cursor Agent, and other MCP-compatible assistants). It builds a derived index from the working tree — symbols, dependency edges, FTS5 full-text, embeddings — and overlays human-authored knowledge (decisions, bugs, constraints, runbooks) so that agents retrieve context with one round-trip instead of grepping the filesystem each session.

A single-binary CLI (`hunch`) exposes commands for graph construction, capture, query, and repair; the same engine powers an MCP server and a VS Code surface, so every agent reads and writes through one resolver (`hunch shared --repo <url>` route introduced in v0.40.0). Source: [README.md:1-40]().

The project is written in TypeScript and runs on Node.js ≥ 22.13. Since v1.0.0 the storage layer uses the built-in `node:sqlite` module, eliminating native build steps and Windows install friction that plagued the prior `better-sqlite3` dependency. Source: [package.json:60-95]().

## Repository Layout

The source tree follows a layered convention: an entrypoint CLI, a transport-agnostic core, storage and graph modules that the core depends on, and provider/hook adapters that vary per environment.

| Path | Responsibility |
|------|----------------|
| `src/cli/` | Argument parsing, command dispatch (`hunch init`, `structure`, `capture`, `heal`, `why`, `fix`, `fragile`, `provider`). Entry point: `src/cli/index.ts`. |
| `src/core/` | Domain primitives — `pipeline.ts` orchestrator, `types.ts` shared shapes, `config.ts` defaults and overrides, `version.ts` build metadata. Pure logic, no I/O imports from `src/cli/` or `src/mcp/`. |
| `src/storage/` | `node:sqlite` wrapper; FTS5 virtual tables, vector table, decision/bug tables. Owns migration scripts. |
| `src/graph/` | Symbol walker and edge builder that turns parsed files into the dependency fan-in / fan-out used by `hunch structure`. |
| `src/providers/` | Synthesis adapters (`claude-cli`, `codex-cli`, `cursor-agent`, `deterministic`) selected via `hunch provider` or `HUNCH_SYNTH_PROVIDER`. Added in v1.7.0 to remove silent subscription guessing. |
| `src/mcp/` | MCP server exposing `hunch_*` tools to Claude Code and other agents. |
| `src/hooks/` | Agent-agnostic lifecycle hooks (v1.6.0) — pre-capture, post-commit, pre-push. |
| `skills/` | Slash-command definitions shipped with the Claude Code plugin (`/hunch:capture`, `/hunch:heal`, `/hunch:why`, `/hunch:fix`, `/hunch:fragile`). |

## System Architecture

The system is a three-tier pipeline: a **transport tier** (CLI / MCP / VS Code) translates user or agent intent into structured calls; a **core tier** validates, grounds, and resolves those calls through a single pipeline; and a **storage tier** persists derived index and author-memorial data inside one SQLite database per repository.

```mermaid
flowchart LR
  A[CLI / MCP / VS Code] --> B[Command Parser]
  B --> C[pipeline.ts]
  C --> D[provider adapter]
  C --> E[graph builder]
  C --> F[storage/sqlite.ts]
  F --> G[(node:sqlite DB)]
  C --> H[hooks/lifecycle]
  H -->|post-commit| G
  H -->|pre-push| C
```

Every write — capture, drift edit, auto-commit (default-on since v0.40.0) — flows through the resolver in `core/pipeline.ts`, which normalises the topic anchor (`auth.session` style) before delegating to a provider adapter and finally to the SQLite layer. The hooks subsystem (`src/hooks/lifecycle.ts`) emits events that other adapters can subscribe to without coupling to a specific agent runtime. Source: [src/core/pipeline.ts:1-80](), [src/hooks/lifecycle.ts:1-60]().

The MCP server in `src/mcp/server.ts` re-exports the same operations as MCP tools (`hunch_structure`, `hunch_capture`, `hunch_heal`, …); the Claude Code plugin installed from v1.1.1 wraps each tool as a slash command, so behaviour stays consistent across surfaces. Source: [src/mcp/server.ts:1-120]().

## Request Lifecycle & Data Flow

A typical `hunch structure <file>` request follows this path:

1. The transport parses arguments and emits a typed `StructureRequest` defined in `src/core/types.ts`.
2. `core/pipeline.ts` resolves the active repo (auto-detected via `hunch shared` resolver), checks the SQLite cache, and either serves from the derived index or rebuilds via `graph/builder.ts`.
3. The response is grounded against any `topic`-anchored decisions or `hunch:topic …` markers in `AGENTS.md` (drift surface introduced in v1.1.0). Collisions surface to the caller; doc≠graph gaps trigger a `fragile` flag.
4. For capture paths, the pipeline prompts the chosen provider (`provider` selection introduced in v1.7.0), writes a record, fires the `post-commit` hook, and returns a structured outcome whose `committed` boolean reflects the truth (v1.2.2 fixed a misleading “committed” reply on skipped commits).

Configuration precedence is lowest-to-highest: built-in defaults in `core/config.ts` → `.hunchrc` → environment variables such as `HUNCH_SYNTH_PROVIDER` → explicit CLI flags. Provider selection in auto-mode only fires when exactly one supported coding-assistant CLI is detected locally, preventing the silent-billing regression that v1.7.0 was published to remove. Source: [src/core/config.ts:1-90](), [src/providers/index.ts:1-70](), [src/core/version.ts:1-30]().

The **Change Gate** added in v1.5.0 sits on top of this lifecycle: any working diff or target is inspected for decisions, constraints, blast radius, and bug history before the first edit, across CLI, MCP, and VS Code uniformly.

---

<a id='page-2'></a>

## Change Gate, Constitution & Policy Enforcement

### Related Pages

Related topics: [Overview, Repository Layout & System Architecture](#page-1), [Memory Graph, Storage & Data Flow](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/core/strictgate.ts](https://github.com/davesheffer/hunch/blob/main/src/core/strictgate.ts)
- [src/core/conformance.ts](https://github.com/davesheffer/hunch/blob/main/src/core/conformance.ts)
- [src/constitution/bootstrap.ts](https://github.com/davesheffer/hunch/blob/main/src/constitution/bootstrap.ts)
- [src/constitution/compiler.ts](https://github.com/davesheffer/hunch/blob/main/src/constitution/compiler.ts)
- [src/constitution/plan.ts](https://github.com/davesheffer/hunch/blob/main/src/constitution/plan.ts)
- [src/constitution/proof.ts](https://github.com/davesheffer/hunch/blob/main/src/constitution/proof.ts)
</details>

# Change Gate, Constitution & Policy Enforcement

## Overview

The Change Gate is the deterministic pre-flight check that sits in front of every mutation an agent (or user) wants to make against a hunch-managed repository. Introduced as a unified surface across the CLI, MCP, and VS Code in v1.5.0, it materializes the project's "memory that gates, not just recalls" philosophy: a working diff or target is inspected before any write, and the gate returns the decisions, constraints, blast radius, and bug history that already matter for that surface `Source: [src/core/strictgate.ts:1-120]()`. The Constitution system layered on top — `bootstrap`, `compiler`, `plan`, `proof` — gives that gate a reproducible policy substrate, while `conformance.ts` enforces the resulting rules against the live graph.

The boundary between the three subsystems is intentional: the **Change Gate** is the *runtime* call site, the **Constitution** is the *build-time* artifact that defines what the gate is allowed to enforce, and **Conformance** is the *audit-time* check that proves the graph still obeys the constitution after the fact.

## The Change Gate

### Inputs and produced context

`strictgate.ts` is the single chokepoint for "I want to change X." A call supplies either a working diff or a target (file, symbol, or topic anchor such as the AGENTS.md `<!-- hunch:topic … -->` markers introduced in v1.1.0), and the gate returns a deterministic bundle of:

- **Active decisions** — the `current` history state of topic-anchored decisions, never the `rejected` branch, joined on the topic key.
- **Constraints** — non-negotiable rules attached to the target, including the safety backstop that v1.2.2 fixed for truthful reporting.
- **Blast radius** — fan-in / dependency-graph reach derived from the FTS5 + vectors index running on `node:sqlite` since v1.0.0.
- **Bug history** — prior incidents linked to the same symbols or directory, sourced from the unified capture resolver introduced in v0.40.0.

Because the gate is deterministic, two agents running the same target on the same graph get byte-identical context — which is what makes the CLI, MCP, and VS Code surfaces interchangeable without re-discovering structure via grep `Source: [src/core/strictgate.ts:120-260]()`.

### Surface parity

The gate is wired into three entry points without divergent code paths:

| Surface | Caller | Notes |
|---------|--------|-------|
| CLI | `hunch` subcommands that mutate or capture | Runs in-process; can short-circuit on a held lock. |
| MCP | `hunch_*` tools exposed to Claude Code (and other MCP clients) since v1.1.1 | Same response shape as CLI. |
| VS Code | Editor-driven flow via the Change Gate panel | Reuses the bundle verbatim. |

The shared hook contract from v1.6.0 — agent-agnostic lifecycle hooks — sits above this layer so any agent runtime can subscribe to `pre-gate`, `post-gate`, and `pre-commit` events without coupling to a specific provider `Source: [src/core/strictgate.ts:260-360]()`.

## The Constitution pipeline

The constitution is not hand-written policy prose; it is *compiled* from the graph and the markdown topic anchors. The pipeline is four stages, each in its own file:

1. **Bootstrap** — `constitution/bootstrap.ts` materializes the inputs: the resolved decisions, constraints, and runbooks picked by the unified resolver, plus the AGENTS.md / CLAUDE.md drift surface. Output is an immutable working set.
2. **Compile** — `constitution/compiler.ts` lowers that working set into a normative policy object: named rules, severities, and the symbols / paths each rule binds to.
3. **Plan** — `constitution/plan.ts` orders rules into an evaluation plan, deduping overlapping bindings and tagging each rule with the gate phase that should enforce it (pre-flight vs. commit-time).
4. **Proof** — `constitution/proof.ts` produces a proof artifact describing *why* the plan is consistent — for example, that no two `current` decisions collide on the same topic — so the gate has a citable rationale when it denies a change `Source: [src/constitution/bootstrap.ts:1-90]()` `Source: [src/constitution/compiler.ts:1-120]()` `Source: [src/constitution/plan.ts:1-110]()`.

The result is that the Change Gate never interprets free-form rules at request time; it evaluates a precomputed plan against the target bundle.

## Conformance and policy enforcement

`core/conformance.ts` is the post-hoc sibling of the gate. Where `strictgate.ts` answers "may this change proceed?", `conformance.ts` answers "did the graph stay in policy?" It replays the constitution's plan against the current graph state, reports drift between the prose surface (AGENTS.md / CLAUDE.md) and the graph spoke (the v1.1.0 doc≠graph detection), and emits a verdict the heal flow can act on `Source: [src/core/conformance.ts:1-150]()`. The deterministic ordering matters here too: conformance output is stable across runs so CI can gate merges on it.

## End-to-end flow

```mermaid
flowchart LR
  A[Working diff or target] --> B[strictgate.ts<br/>Change Gate]
  D[constitution/bootstrap.ts] --> E[constitution/compiler.ts]
  E --> F[constitution/plan.ts]
  F --> G[constitution/proof.ts]
  G --> B
  B --> H{Allow?}
  H -- yes --> I[Capture / commit<br/>v0.40.0 unified resolver]
  H -- no --> J[Deny with decisions + blast radius]
  I --> K[core/conformance.ts<br/>audit]
  K --> L[Heal if drift detected]
```

## Practical implications

- **One loop, every agent.** Because the gate and the constitution behind it are agent-agnostic, swapping the synthesis provider via `hunch provider claude-cli` (v1.7.0) does not change what is enforceable — only who writes the explanation.
- **Truthful outcomes.** v1.2.2 made the gate's auto-commit path honest: skipped commits (held lock, safety backstop, empty stage) are reported as skipped, not as committed, and deferred overlay pushes surface a retry hint rather than a silent success `Source: [src/core/strictgate.ts:360-440]()`.
- **Drift is a first-class signal.** The same topic anchors that the constitution compiles are what `conformance.ts` re-checks, so a prose change in AGENTS.md without a matching graph decision is caught on the next audit, not on the next incident.

---

<a id='page-3'></a>

## Memory Graph, Storage & Data Flow

### Related Pages

Related topics: [Change Gate, Constitution & Policy Enforcement](#page-2), [Agent Integrations, Lifecycle Hooks & Synthesis Providers](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/store/hunchStore.ts](https://github.com/davesheffer/hunch/blob/main/src/store/hunchStore.ts)
- [src/store/db.ts](https://github.com/davesheffer/hunch/blob/main/src/store/db.ts)
- [src/store/schema.ts](https://github.com/davesheffer/hunch/blob/main/src/store/schema.ts)
- [src/store/embedder.ts](https://github.com/davesheffer/hunch/blob/main/src/store/embedder.ts)
- [src/store/compact.ts](https://github.com/davesheffer/hunch/blob/main/src/store/compact.ts)
- [src/store/merge.ts](https://github.com/davesheffer/hunch/blob/main/src/store/merge.ts)
</details>

# Memory Graph, Storage & Data Flow

The Memory Graph is the durable substrate that lets Hunch remember decisions, bugs, constraints, runbooks, and document anchors across agent sessions. It is the join key between every surface Hunch exposes (CLI, MCP, VS Code, Claude Code plugin) and the only place where grounding evidence and drift signals converge before they are surfaced back to an agent.

## Storage Layer

Hunch stores its graph in a single SQLite database opened through Node's built-in `node:sqlite` (since v1.0.0). This replaces `better-sqlite3` and removes native build steps, `prebuild-install`, and Windows `EPERM` issues during global upgrades. `Source: [src/store/db.ts]()`.

The schema is owned by a dedicated module so migrations and derived tables (FTS5 virtual tables, graph edges, vector rows) can evolve without leaking into call sites. `Source: [src/store/schema.ts]()`. The store facade — `hunchStore.ts` — is the only object most callers touch; it owns connection lifetime, transaction boundaries, and the read/write API the rest of the system uses. `Source: [src/store/hunchStore.ts]()`.

Key properties of the storage layer:

- **Embedded engine.** No external service, no native module — the graph lives next to the repo in `.hunch/`.
- **FTS5 + graph + vectors co-resident.** Full-text search, dependency-style edges, and embedding rows share one file, so a single open + transaction yields all three. `Source: [src/store/schema.ts]()`.
- **One writer per process.** The facade serializes writes so capture, heal, and merge never interleave partial rows.

## Memory Graph Model

A "memory" in Hunch is a typed node with a stable id, a `topic` anchor, and grounded metadata. The four primitive node kinds are:

| Kind | Purpose | Anchor field |
|------|---------|--------------|
| `decision` | A design choice, pinned to a topic | `topic` (e.g. `auth.session`) |
| `bug` | A reproducible defect with repro + fix | implicit `topic` |
| `constraint` | A hard rule the agent must honor | implicit `topic` |
| `runbook` | A remediation procedure | implicit `topic` |

`Source: [src/store/schema.ts]()`. The `topic` anchor is the join key for drift detection between the graph and prose files (`AGENTS.md`, `CLAUDE.md`); a decision anchored to `auth.session` can be cross-checked against any doc that claims authority over that topic. `Source: [src/store/hunchStore.ts]()`.

Embeddings live alongside rows so semantic lookup does not require an external index. `Source: [src/store/embedder.ts]()`. Embedding selection is provider-driven (Claude CLI, Codex CLI, Cursor agent, or deterministic fallback) and is configurable per-shell via `HUNCH_SYNTH_PROVIDER` or per-repo via `hunch provider …`. `Source: [src/store/embedder.ts]()`.

## Data Flow

The end-to-end loop is: **capture → write → ground → query → synthesize → drift-check**.

```mermaid
flowchart LR
  A[Agent / MCP tool] -->|capture decision/bug/constraint/runbook| B[hunchStore.write]
  B --> C[(SQLite: rows + FTS5 + vectors)]
  C --> D[read-time grounding]
  A -->|hunch_structure / hunch_why| D
  D --> E[synthesis provider]
  E --> F[grounded answer + topic citations]
  C -->|doc≠graph check| G[drift report in AGENTS.md / CLAUDE.md]
```

1. **Capture.** A `hunch capture` call (CLI, MCP, or skill) lands in `hunchStore.write` with a typed payload and a `topic`. `Source: [src/store/hunchStore.ts]()`.
2. **Persist + index.** The facade writes the row, mirrors it into the FTS5 virtual table, and enqueues an embedding. `Source: [src/store/db.ts]()`.
3. **Compact.** Periodic compaction merges redundant rows, retires superseded decisions, and prunes orphaned edges. `Source: [src/store/compact.ts]()`.
4. **Merge.** When `hunch shared --repo <url>` is used, the unified resolver routes every capture to one home (public or private) and reconciles via `merge.ts`. `Source: [src/store/merge.ts]()`.
5. **Read.** `hunch_structure`, `hunch_why`, and Change Gate lookups open a read transaction, ground against current vs. rejected collisions, and return topic-cited evidence. `Source: [src/store/hunchStore.ts]()`.

## Consistency, Commits, and Drift

Auto-commit is on by default (v0.40.0); the store reports the *real* outcome — skipped commits, held locks, and deferred overlay pushes are surfaced truthfully rather than claimed as committed (v1.2.2 fix). `Source: [src/store/hunchStore.ts]()`. Read-time grounding re-checks each cited node against the current graph state so a `current` decision that has since been `rejected` is not silently cited as authoritative. `Source: [src/store/db.ts]()`. Drift between graph nodes and `AGENTS.md` / `CLAUDE.md` topic blocks is the signal `heal` and the Change Gate act on; the spoke that owns this comparison is the schema + store pair, not the prose file. `Source: [src/store/schema.ts]()`.

---

<a id='page-4'></a>

## Agent Integrations, Lifecycle Hooks & Synthesis Providers

### Related Pages

Related topics: [Overview, Repository Layout & System Architecture](#page-1), [Change Gate, Constitution & Policy Enforcement](#page-2), [Memory Graph, Storage & Data Flow](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/integrations/providers.ts](https://github.com/davesheffer/hunch/blob/main/src/integrations/providers.ts)
- [src/integrations/scaffold.ts](https://github.com/davesheffer/hunch/blob/main/src/integrations/scaffold.ts)
- [src/integrations/claudeConfig.ts](https://github.com/davesheffer/hunch/blob/main/src/integrations/claudeConfig.ts)
- [src/integrations/claudemd.ts](https://github.com/davesheffer/hunch/blob/main/src/integrations/claudemd.ts)
- [src/integrations/hooks.ts](https://github.com/davesheffer/hunch/blob/main/src/integrations/hooks.ts)
- [src/integrations/mergeDriver.ts](https://github.com/davesheffer/hunch/blob/main/src/integrations/mergeDriver.ts)

</details>

# Agent Integrations, Lifecycle Hooks & Synthesis Providers

## Purpose and Scope

The `src/integrations/` directory is the adapter layer between Hunch's grounded memory graph and the coding-agent ecosystem it serves. It does three things at once: (a) **route synthesis** of topic-anchored decisions to whichever local CLI subscription the user selects, (b) **install agent-agnostic lifecycle hooks** so any assistant — Claude Code, Cursor, Codex, VS Code — observes the same pre/post-commit gates, and (c) **bridge the graph with prose files** such as `CLAUDE.md` / `AGENTS.md` and a deterministic merge driver. Together these modules turn Hunch from an index into a working loop that every agent can join without bespoke wiring (`Source: [src/integrations/providers.ts:1-40]()`).

## Synthesis Providers & Selection

`providers.ts` enumerates the four synthesis backends Hunch can bill against: `claude-cli`, `codex-cli`, `cursor-agent`, and `deterministic` (an offline rule-based option). Resolution follows a strict precedence so the CLI never silently guesses a subscription:

| Layer | Mechanism | Source |
| --- | --- | --- |
| Explicit flag | `hunch provider <name>` writes the choice locally | `providers.ts:42-78` |
| Shell/CI env | `HUNCH_SYNTH_PROVIDER` per-invocation override | `providers.ts:80-96` |
| Auto-detect | Lists locally available CLIs; uses a subscription only when exactly one is present, otherwise falls back to `deterministic` | `providers.ts:98-140` |

The detection routine avoids vendor lock-in by probing each CLI's presence and version, returning a normalized enum rather than opaque string IDs (`Source: [src/integrations/providers.ts:100-140]()`). `scaffold.ts` complements this by generating the per-repo skeleton (`hunch init`) and pre-creating the configuration block where the chosen provider is persisted across sessions (`Source: [src/integrations/scaffold.ts:1-60]()`).

## Agent-Agnostic Lifecycle Hooks

Released in v1.6.0, the hook system was deliberately decoupled from any single agent runtime. `hooks.ts` exposes a small contract — `PreContext` and `PostCommit` events — that wrappers translate into the native hook format of each agent (Claude Code `settings.json`, Cursor `hooks.json`, VS Code task hooks, generic shell). The single rule is: if Hunch gates a commit, **every** agent on the repo sees the same gate and the same auto-commit outcome (`Source: [src/integrations/hooks.ts:10-90]()`).

```mermaid
flowchart LR
    A[Agent: edit staged] --> B[hooks.ts dispatch]
    B --> C{PreContext gate}
    C -- groundable --> D[Return topic-anchored decisions]
    C -- ungroundable --> E[Block with constraint list]
    D --> F[Agent commits]
    F --> G[PostCommit hook]
    G --> H[auto-commit truth:<br/>skipped|committed|deferred]
```

The hook module also reports commit outcomes truthfully: a skipped commit (held lock, empty stage, or safety backstop) is no longer claimed as committed, and a deferred overlay push returns a retry hint (`Source: [src/integrations/hooks.ts:92-160]()`). This honesty is what makes the deterministic **Change Gate** (v1.5.0) reproducible across CLI, MCP, and VS Code entry points (`Source: [src/integrations/hooks.ts:160-210]()`).

## Claude Code & MCP Plugin Surface

`claudeConfig.ts` writes the Claude Code plugin manifest, MCP server entry, and the five skill stubs — `/hunch:capture`, `/hunch:heal`, `/hunch:why`, `/hunch:fix`, `/hunch:fragile` — installed via `/plugin marketplace add davesheffer/hunch`. The function is idempotent: re-running `hunch init` overwrites only the Hunch-owned keys in `~/.claude/settings.json`, leaving unrelated user configuration intact (`Source: [src/integrations/claudeConfig.ts:1-80]()`). It also pins the MCP tool names with the `hunch_*` prefix so the host's tool registry cannot collide with adjacent plugins (`Source: [src/integrations/claudeConfig.ts:80-140]()`).

A second surface, `hunch_structure` from v1.2.0, is registered through the same MCP entry: given no target it returns a repo map (components + directories by symbol weight); given a directory it lists files with symbols and fan-in; given a file it returns an outline — eliminating the grep/glob round-trips agents usually spend rediscovering structure (`Source: [src/integrations/claudeConfig.ts:140-200]()`).

## Markdown Anchors & the Merge Driver

`claudemd.ts` is the doc↔graph bridge. It scans `CLAUDE.md` and `AGENTS.md` for `<!-- hunch:topic ... -->` markers and treats them as a third spoke: prose anchors that pin a paragraph to a decision row by hash. Read-time grounding resolves these anchors against the graph and flags drift when the canonical decision moves while the prose still cites the old hash (`Source: [src/integrations/claudemd.ts:1-90]()`). Because teams funnel tribal knowledge into these files, anchoring them is what prevents drift in the first place (`Source: [src/integrations/claudemd.ts:90-160]()`).

`mergeDriver.ts` registers a Git merge driver so topic-anchored blocks merge deterministically: when two branches diverge on the same `<!-- hunch:topic ... -->` section, the driver keeps the row whose hash matches the graph's `current` decision and marks the loser for `rejected` review — never producing a silent textual conflict (`Source: [src/integrations/mergeDriver.ts:1-70]()`). Auto-commit (default since v0.40.0) routes through this driver before the commit is recorded, so the post-commit report handed back to the agent reflects the merged state, not the staged state (`Source: [src/integrations/mergeDriver.ts:70-130]()`).

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: davesheffer/hunch

Summary: Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

## 1. Configuration risk - Configuration risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.host_targets | https://github.com/davesheffer/hunch

## 2. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://github.com/davesheffer/hunch

## 3. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/davesheffer/hunch

## 4. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://github.com/davesheffer/hunch

## 5. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://github.com/davesheffer/hunch

## 6. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/davesheffer/hunch

## 7. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://github.com/davesheffer/hunch

<!-- canonical_name: davesheffer/hunch; human_manual_source: deepwiki_human_wiki -->