@davesheffer/hunch 1.4.1 → 1.4.2

package/README.md

@@ -1,326 +1,44 @@
 # 🧠 Hunch — Architectural Conformance for AI code
 
-[![GitHub stars](https://img.shields.io/github/stars/davesheffer/hunch?color=2742ff&label=%E2%98%85%20star)](https://github.com/davesheffer/hunch)
 [![npm version](https://img.shields.io/npm/v/@davesheffer/hunch?color=2742ff&label=npm)](https://www.npmjs.com/package/@davesheffer/hunch)
-[![npm downloads](https://img.shields.io/npm/dw/@davesheffer/hunch?color=2742ff)](https://www.npmjs.com/package/@davesheffer/hunch)
+[![GitHub stars](https://img.shields.io/github/stars/davesheffer/hunch?color=2742ff&label=%E2%98%85%20star)](https://github.com/davesheffer/hunch)
 [![license](https://img.shields.io/npm/l/@davesheffer/hunch?color=2742ff)](LICENSE)
-[![node](https://img.shields.io/badge/node-%E2%89%A522.13-2742ff)](https://nodejs.org)
-[![MCP](https://img.shields.io/badge/MCP-native-2742ff)](https://modelcontextprotocol.io)
-
-> **Your repo remembers *what* changed. Hunch makes it remember *why*** — the decisions, the
-> trade-offs, the bugs you already paid for — and keeps every AI coding session consistent with them.
-> When a change would quietly undo something you decided on purpose, Hunch notices and shows the
-> receipt: which decision, and which past bug it protects you from. A linter checks *patterns*;
-> Hunch understands your *architecture* (layering, must-reach, dependency direction) — deterministically,
-> from a **git-native** graph, across any MCP assistant.
-
-```bash
-npm i -g @davesheffer/hunch
-cd your-repo && hunch init    # 2 minutes; advisory by default — nothing blocks until you say so
-
-# teach it one architectural rule, in plain words — with the why
-hunch conform --add "controllers never reach the DB directly — go through the service layer" \
-  --assert not-calls --subject listOrders --object dbQuery --why "the Mar-2025 N+1 incident"
-
-hunch conform     # ✅ deterministic check — and when you're ready, --strict wires it into CI
-```
-
-> Here's the moment it earns its keep: an AI "optimizes" your controller to query the DB directly.
-> Pattern tools stay **green** — it's a legitimate internal import, no bad pattern to match.
-> Hunch quietly flags it: *"listOrders now reaches dbQuery · why this matters: the Mar-2025 N+1
-> incident · protects against a repeat of bug_0317."* You decide what happens next — advisory
-> shows the note, **strict** (opt-in) holds the change. Watch the whole loop in 15 seconds:
-> [`demo/architectural-conformance.sh`](demo/architectural-conformance.sh).
-
-**It helps twice — before the change, and after:**
-- **Before** — the recorded rule rides into the AI's context. In a reproducible benchmark ([`bench/`](bench/architectural-conformance.md): n=90, three models, 3 invariant classes), that alone cut architectural drift **58% → 16%** (one model: **67% → 0%**).
-- **After** — reminders help, but models still drift even when told (the same benchmark measured it). So a deterministic check — [`hunch check`](https://hunch-pi.vercel.app/docs#ci) on commit or in your PR gate — catches what reminders miss, always with the receipt, **no model in the loop**. Advisory first; you choose the [firmness](https://hunch-pi.vercel.app/docs#firmness).
-
-<sub>Works with **Claude Code, Cursor, Copilot, Windsurf & Google Antigravity** from one shared, git-native graph.</sub>
-
-### 📚 **[Read the full documentation → hunch-pi.vercel.app/docs](https://hunch-pi.vercel.app/docs)**
-
-The docs site is the complete reference — setup, every CLI command and MCP tool, the
-guards, troubleshooting. This README is the tour. Jump to:
-[Install](https://hunch-pi.vercel.app/docs#install) ·
-[MCP setup](https://hunch-pi.vercel.app/docs#mcp) ·
-[Firmness](https://hunch-pi.vercel.app/docs#firmness) ·
-[CLI reference](https://hunch-pi.vercel.app/docs#cli) ·
-[Troubleshooting](https://hunch-pi.vercel.app/docs#doctor)
-
-> 🆕 **v1.3.0** — retrieval that follows the graph: live decisions outrank superseded ones, human-vouched outrank drafts, and a query that hits history surfaces the topic's *current* decision (Recall@10 90→100% on the committed golden set). Plus `hunch now` + the roadmap-as-proposed-decisions, session-deduped hook grounding (~100× smaller on repeats), content-matched blocking gates, and duplicate auto-drafts skipped before the LLM is called. [Full changelog →](https://hunch-pi.vercel.app/changelog)
-
-## The problem
-
-Every AI coding session starts from zero. The model re-reads your code, re-guesses the
-intent, and happily "fixes" the thing you deliberately did last month — because the
-*reasoning* behind the code lives in PRs, Slack, and people's heads, not in the repo.
-
-**Hunch** captures that reasoning as a **byproduct of normal work** — commits and test
-failures — stores it as a git-tracked graph next to your code, and feeds it back to
-Claude Code so every session is grounded in the decisions, bugs, and invariants that
-came before. Local-first, no documentation toil, no SaaS.
 
-## How it works
+> **Your repo remembers *what* changed. Hunch makes it remember *why*** — and keeps every
+> AI coding session consistent with the decisions, trade-offs, and bugs you already paid for.
+> Local-first, git-native, works with Claude Code, Cursor, Copilot, Windsurf & Codex.
 
-```
-   commit / test failure              .hunch/  (git-tracked JSON)            Claude Code
- ┌───────────────────────┐         ┌──────────────────────────┐         ┌──────────────┐
- │ post-commit hook   ───┼────────▶│ Decisions  (why a change) │────────▶│ MCP tools     │
- │ record-bug         ───┼────────▶│ Bugs       (root causes)  │  read   │ /hunch-* cmds │
- │ structured diff +     │  write  │ Constraints(invariants)   │◀────────│ CLAUDE.md     │
- │ Claude (or heuristic) │         │ Components / Symbols/Edges │         │ CLI           │
- └───────────────────────┘         └──────────────────────────┘         └──────────────┘
-```
-
-- **Index** (no LLM): Hunch maps your repo — how functions, files, and components
-  connect — so it can see the ripple effect of any change.
-- **Learn**: each commit becomes a structured **Decision** (an ADR); a failing test
-  becomes a **Bug** with its likely cause; recurring or severe bugs are promoted
-  into **Constraints** (do-not-break rules) and flag the riskiest parts of the code.
-- **Ground**: any MCP assistant reads it through an **MCP server**, an auto-maintained
-  **`CLAUDE.md`**, and **slash commands** — every answer cites `provenance`
-  (source + confidence + evidence), so nothing is a blind assertion.
-
-→ Concepts in depth: [the reasoning graph](https://hunch-pi.vercel.app/docs#graph) ·
-[provenance](https://hunch-pi.vercel.app/docs#provenance) ·
-[time-travel](https://hunch-pi.vercel.app/docs#time-travel)
-
-## Why Hunch is different
-
-"Memory for coding agents" is getting crowded, but most of it is a *server-side, ephemeral,
-single-vendor* RAG cache over your current code. Hunch is the opposite on every axis — and that
-combination is the moat:
-
-| | Typical agent memory | **Hunch** |
-|---|---|---|
-| **Storage** | server-side / a vendor's cloud | **git-tracked JSON in your repo** — diff it, review it in PRs, sync it over `git push` |
-| **Lifetime** | the session; often auto-expiring | the **lifetime of the codebase** — non-destructive supersede/veto keeps the *why-it-changed* trail |
-| **Clients** | one vendor's agent | **client-agnostic** — one `.hunch/` graph serves Claude Code, Cursor, Copilot & Windsurf via MCP |
-| **What's stored** | opaque extracted "facts" | **structured ADRs** — decisions with rejected-alternatives, bug lineage, and invariants |
-| **Enforcement** | advisory / just-in-time hints | **fail-closed guards** — no model in the block path; a commit fails only on a rule you've vouched for |
-| **Trust** | take it on faith | **provenance on every record** (source + confidence + evidence) and a measurable retrieval signal (`hunch eval`) |
-
-The short version: **git tracks *what* changed; Hunch tracks *why*** — locally, durably, and under
-your control, with guards that actually hold the line instead of just suggesting.
-
-## Decision-grounding: memory that stays true to the doc
-
-Architectural Conformance keeps the *code* honest to the graph (**graph ≠ code**). Decision-grounding
-is its complement — it keeps your *docs* honest to the graph (**doc ≠ graph**). A comment or a README
-says one thing; the decision that actually governs the file says another. Both are "memory that stays
-true"; you want both.
-
-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.
-- **`hunch wiki`** — a generated component wiki + **specs ledger** rendered *from* the graph. Every repo
-  doc is graded deterministically (✅ grounded / ⚠ stale / ◻ unverified); a stale doc is **adopted** — a
-  wiki-managed copy re-pinned to the current decision with the correction inline, while your original
-  file is never touched (and the copy retires once you heal the original). Freshness is hash-gated:
-  `hunch drift` names exactly which pages went stale, `hunch wiki --heal` regenerates only those, and
-  `hunch wiki --check` is the CI gate. With a private overlay, `hunch wiki --private` renders the FULL
-  graph into the overlay repo — nothing private ever lands in the committed wiki.
-
-  ```bash
-  npm run build && bash demo/wiki.sh   # watch a spec go stale, get adopted + healed, then released
-  ```
-
-→ [docs](https://hunch-pi.vercel.app/docs#grounding)
-
-## Getting started
+## Install
 
 ```bash
-npm install -g @davesheffer/hunch   # Node ≥ 22.13; puts `hunch` on your PATH
-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
-graph — merging idempotently into existing files. **Reload your assistant in the repo**
-afterward to pick up the `hunch_*` tools. Each teammate runs `hunch init` once; the
-`.hunch/` content is shared via git.
-
-> Synthesis is billed to **your coding-assistant subscription** (Claude/Codex/Cursor CLI),
-> **never** a pay-per-token API key — and falls back to a deterministic heuristic if no CLI
-> is present. Details: [Synthesis & billing](https://hunch-pi.vercel.app/docs#synthesis).
->
-> **Deep Synthesis** (`backfill --deep` / `sync --deep`): gathers several independent takes on a
-> change and reconciles them into one more-trustworthy note — trusting it more when they agree.
-> Add `--verify` to fact-check the note against the commit and drop anything it doesn't support.
-> It always stays *advisory* until you confirm it. Subscription-only; falls back to a single
-> draft when only one assistant is available.
-> On Windows, prefer `hunch init` over a global `claude mcp add`; if tools don't appear,
-> `hunch doctor` heals it ([why](https://hunch-pi.vercel.app/docs#windows)).
-
-**Full walkthrough →** [Getting started](https://hunch-pi.vercel.app/docs#install) ·
-[MCP & assistants](https://hunch-pi.vercel.app/docs#mcp) ·
-[MCP tools](https://hunch-pi.vercel.app/docs#mcp-tools) ·
-[slash commands](https://hunch-pi.vercel.app/docs#slash) ·
-[the full CLI reference](https://hunch-pi.vercel.app/docs#cli)
-
-## Enforcement: memory that holds the line
-
-Hunch isn't just recall — it's a set of **guards** that stop the AI (and you) from undoing
-intentional design. All ride the same rails: the pre-edit hook, `hunch check`, the
-`hunch_merge_verdict` MCP tool, and the CI Constraint Guard. How hard they push is one
-committed knob — [**firmness**](https://hunch-pi.vercel.app/docs#firmness)
-(`off` → `advisory` → `firm` → `strict`).
-
-### Never Twice — corrections become enforced invariants
-
-You tell the agent "no, never call the pay-per-token API here," it complies once, and next
-session it does it again — because the feedback was stored as advisory text. Hunch closes
-that loop: a correction is captured as a first-class **Constraint** (`human_confirmed`) via
-`hunch_record_correction`, and from then on the **same hook + CI guard** hold *every*
-assistant to it. → [docs](https://hunch-pi.vercel.app/docs#never-twice)
-
-### Causal Merge Verdict — does this change re-open a closed bug?
-
-A diff-only reviewer sees *what* changed; it can't see that the line you're deleting is the
-fix for an incident. Hunch can — `hunch_merge_verdict` replays a diff against the graph and
-returns a cited **BLOCK / WARN / PASS**:
-
-```text
-VERDICT: ⛔ BLOCK — this change breaks a recorded invariant or re-opens a known bug.
-
-⛔ pay() must verify the session before charging — con_pay
-   🧠 why: "Charge must verify the session first" (dec_pay)
-   🐞 guards against: Double-charge on unverified session (bug_…)
-```
-
-No model in the loop, so it's safe as a merge gate — it blocks only on a high-confidence rule
-you've confirmed, and warns on everything softer. → [docs](https://hunch-pi.vercel.app/docs#merge-verdict)
-
-### Decision Guard (Veto) — re-introducing a *rejected* approach is blocked
-
-The most expensive reversal is re-adding an approach a decision **rejected** (latency, a
-forbidden dependency) — code that never existed, so a diff reviewer is blind to it. A
-decision remembers what it rejected; re-introduce that approach and Hunch blocks it with
-the receipt of what you rejected and why. → [docs](https://hunch-pi.vercel.app/docs#veto)
-
-### Redundancy Guard — "this already exists"
-
-An agent works from a *local* context window, so it re-implements a helper that already
-lives three modules over, or re-adds a dependency the codebase already has — sprawl a
-diff-only reviewer can't see, but Hunch's symbol graph can. Add a function or class already
-defined elsewhere and `hunch check` / the CI guard / `hunch_merge_verdict` flag it with the
-existing location. **Advisory** — it never blocks, and it's tuned to stay quiet so a refactor
-that just moves code isn't mistaken for a duplicate. → [docs](https://hunch-pi.vercel.app/docs#redundancy)
-
-See also **[Decision-grounding](#decision-grounding-memory-that-stays-true-to-the-doc)** — the doc ≠ graph
-complement: topic anchors, read-time grounding in the pre-edit hook, and a deterministic `anchor-stale`
-drift check (`hunch drift`) that fails CI when a file still points at a superseded decision.
-
-Plus the **Regression Guard** (re-adding deliberately-retired code) and the
-**[CI Constraint Guard](https://hunch-pi.vercel.app/docs#ci)** (`hunch ci` — a PR gate that
-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 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
-
-The `.hunch/` JSON is the **source of truth** — diffable, reviewable in PRs, synced for free
-over `git push` / `pull`. `hunch init` sets things up so concurrent edits from different
-teammates merge cleanly instead of throwing conflict markers, and it's **OS-agnostic** —
-Windows / macOS / Linux teammates share one memory with no per-machine fixups.
-→ [docs](https://hunch-pi.vercel.app/docs#team)
-
-### Branches & worktrees
-
-Memory follows you across every branch and **git worktree**, with no per-worktree setup — a
-fresh `git worktree add` on any branch sees the same decisions, bugs, and invariants. Create one
-already wired in with **`hunch worktree <path> [-b <branch>]`**, or just run `hunch init` / `hunch
-shared` (or `hunch private`) once and every worktree picks it up. Parallel worktrees never corrupt or lose memory, and
-`hunch doctor` confirms a worktree is sharing.
-
-Need one **single source of truth** for memory in any repo (private or public)?
-Use **`hunch shared --repo <url>`**. Every capture — decisions, bugs, constraints, runbooks —
-routes to one shared overlay repo and, by default, auto-commits + pushes so teammates/other
-worktrees stay in sync automatically. It also publishes a committed **`.hunch/team.json`**
-pointing at the store, so a fresh clone auto-connects on `hunch init` (agents and CI wire up
-the same way via the MCP server) — everyone, on every branch, resolves the same memory.
-
-## 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: 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`** 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)
-
-The decision half of the loop is automatic (the post-commit hook). Light up the bug/constraint
-half by wrapping your test run — it captures failures as **Bugs** (recurrences auto-promote
-**Constraints**) and resolves fixed ones, preserving the runner's exit code:
-
-```bash
-hunch test                  # runs `npm test`; any runner: hunch test -- pytest -q
+npm i -g @davesheffer/hunch
+cd your-repo && hunch init      # 2 minutes; advisory by default — nothing blocks until you say so
+hunch backfill --since 90d      # optional: seed memory from recent git history
 ```
 
-Drop `npx hunch test` into CI, and `hunch ci` to scaffold the PR merge gate.
-→ [docs](https://hunch-pi.vercel.app/docs#ci)
+Reload your assistant and ask: *"why is X built this way?"* — it answers from the graph, with receipts.
 
-## Semantic search (optional)
+## The moment it earns its keep
 
-`hunch query` uses fast keyword search out of the box. For recall on paraphrases, opt into
-**local embeddings** (`npm i -g @huggingface/transformers && hunch embed`) — local, free, and
-opt-in, and it never drifts from your committed memory.
+An AI "optimizes" your controller to query the DB directly. Linters stay green — no bad
+pattern to match. Hunch flags it: *"listOrders now reaches dbQuery · why: the Mar-2025 N+1
+incident · protects against bug_0317."* You decide what happens next — advisory shows the
+note; **strict** (opt-in) holds the change.
 
-## VS Code
+Measured ([`bench/`](bench/architectural-conformance.md), n=90, three models): recorded rules
+in context cut architectural drift **58% → 16%**. The deterministic check catches the rest —
+no model in the loop.
 
-A companion **[VS Code extension](vscode-extension/)** (on
-[Open VSX](https://open-vsx.org/extension/davesheffer/hunch-vscode) — VS Code / Cursor /
-Windsurf / VSCodium) brings the graph into the editor: a tree of decisions / invariants /
-bugs / bug-lineage / fragility / stale records, CodeLens summaries, hover with bug history,
-invariants in the Problems panel, an interactive component graph, and a status-bar invariant
-counter. It reads the committed `.hunch/` JSON directly; writes delegate to the `hunch` CLI.
+## What you get
 
-## Architecture
+- **Memory as a byproduct of work** — every commit becomes a decision, failing tests become bug lineage; no documentation chore
+- **Every answer with receipts** — decisions cite the why, the rejected alternatives, and the bug they protect against
+- **Guards that hold the line** — corrections become permanent rules; drift and re-opened bugs get caught deterministically
+- **Verification pipeline** (v1.4) — the agent can't end a turn claiming success on unverified edits
+- **One graph, every assistant** — plain git-tracked JSON in `.hunch/`, served over MCP; no SaaS, $0, works offline
 
-Everything lives under `.hunch/` as plain git-tracked JSON — the source of truth; a fast local
-index is built from it and is throwaway. Subscription-billed synthesis (never a pay-per-token
-API key) with a no-LLM fallback, and atomic writes so an interrupted write can't corrupt your
-memory. → [the docs](https://hunch-pi.vercel.app/docs) for the conceptual model.
+## Learn more
 
-## Develop
+**[Documentation](https://hunch-pi.vercel.app/docs)** · **[Cookbook](https://hunch-pi.vercel.app/cookbook)** · **[Changelog](https://hunch-pi.vercel.app/changelog)** · **[15-second demo](demo/architectural-conformance.sh)**
 
-Hunch is open source — pure TypeScript ESM, Node ≥ 22.13, licensed **Apache-2.0**. Contributions
-welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) and the [repo](https://github.com/davesheffer/hunch).
+Apache-2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.4.1",
+  "version": "1.4.2",
   "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).",