{
  "markdown": "# wisegit\n\n[![npm](https://img.shields.io/npm/v/@sandip124/wisegit)](https://www.npmjs.com/package/@sandip124/wisegit)\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-io.github.Sandip124%2Fwisegit-blue)](https://registry.modelcontextprotocol.io/v0.1/servers?search=wisegit)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n> *\"Don't take a fence down until you know the reason it was put up.\"*\n> — G.K. Chesterton\n\n**wisegit** is a local MCP server that extracts decision intent from git history and protects intentional code from AI modification.\n\nWhen Claude Code (or any MCP-compatible agent) is about to edit a file, wisegit injects a **decision manifest** showing which functions are frozen, stable, or open — so the AI respects what was intentional, not just what compiles.\n\n**Zero config. Zero external services. Everything local.**\n\n### Install\n\n```bash\n# Set up any repo (one command)\nnpx @sandip124/wisegit setup\n\n# Or add as MCP server globally\nclaude mcp add wisegit -- npx @sandip124/wisegit serve\n```\n\n### Published on\n\n- **npm:** [@sandip124/wisegit](https://www.npmjs.com/package/@sandip124/wisegit)\n- **MCP Registry:** [io.github.Sandip124/wisegit](https://registry.modelcontextprotocol.io/v0.1/servers?search=wisegit)\n- **GitHub:** [Sandip124/wisegit](https://github.com/Sandip124/wisegit)\n\n## The Problem\n\nLLMs have no concept of **intentional code**. A manually-tested fix and a broken stub look identical — both are just text. Real scenario:\n\n1. You fix a Stripe race condition with `sleep(350)` — manually tested, committed.\n2. Next session: \"find bugs.\" Claude removes `sleep(350)` — looks like dead code.\n3. Production incident.\n\n**Root cause:** git history contains proof of intention. Nobody extracts it.\n\n## How It Works\n\n```\nGit History → Tree-sitter AST → Intent Extraction → SQLite Event Store → MCP Tools\n```\n\n1. **Indexes your git history** — walks every commit, parses diffs at the AST level (function boundaries, not line counts)\n2. **Classifies commits** — STRUCTURED (`fix:`, `feat:`), DESCRIPTIVE (plain sentences), or NOISE (`wip`, `x`)\n3. **Extracts intent** — rule-based for structured/descriptive commits, LLM for noise (Phase 2)\n4. **Computes freeze scores** — 0–1 per function, derived from protection signals (git, issue, code structure, test, structural, Naur, Aranda) minus adaptive obsolescence penalty (8 signals, entropy-calibrated). Age uses Weibull survival [18]; expertise uses DOE model [19]\n5. **Serves decision manifests via MCP** — Claude Code calls `get_file_decisions` before editing any file\n\n## What the AI Sees\n\n```\n[DECISION MANIFEST: payment.service.cs]\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\nFROZEN:  ProcessPayment()  [score: 0.89] [Recovery: L1]\n  - sleep(350) → Stripe race condition. Won't Fix.\n    HIGH — commit a3f19b2\n\nSTABLE:  ValidateOrder()  [score: 0.55] [Recovery: L2]\n  - Fixed null reference on Safari iOS WebKit.\n    MEDIUM — commit 7c14694\n\nOPEN:    FormatReceipt()  [score: 0.12] [Recovery: L3]\n  ← safe to modify\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n```\n\n- **FROZEN** (score >= 0.80): Do not modify without explicit user approval\n- **STABLE** (score 0.50-0.79): Proceed with caution, review intent first\n- **OPEN** (score < 0.50): Safe to modify freely\n\n## Quick Start\n\n### Prerequisites\n\n- Node.js >= 20\n\nThat's it. No Docker, no PostgreSQL, no external services.\n\n### 1. Set Up a Repository (one command)\n\n```bash\ncd /path/to/your/repo\nnpx @sandip124/wisegit setup\n```\n\nThis single command:\n- Creates a local SQLite database at `~/.wisegit/wisegit.db`\n- Indexes your entire git history (462 commits in ~13 seconds)\n- Creates `.mcp.json` for Claude Code auto-discovery\n- Creates `CLAUDE.md` rules that instruct AI to check before editing\n- Adds `.mcp.json` to `.gitignore`\n\n### 2. Enrich with Issue Context (optional)\n\n```bash\n# Fetch issue/PR details from GitHub/GitLab\nGITHUB_TOKEN=ghp_... npx @sandip124/wisegit enrich\n```\n\nThis fetches referenced issues (e.g., `#134` in commit messages), detects Won't Fix / By Design decisions, and boosts freeze scores for functions linked to those issues.\n\n### 3. Done\n\nOpen the repo in Claude Code. It will automatically:\n1. Start the wisegit MCP server (via `.mcp.json`)\n2. Read the protection rules (via `CLAUDE.md`)\n3. Call `get_file_decisions` before editing any file\n\n## MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `get_file_decisions` | Decision manifest for a file — freeze scores, intent history, recovery levels, override status |\n| `get_freeze_score` | Score + signal breakdown for a specific function |\n| `get_function_history` | Full chronological decision timeline for a function |\n| `get_theory_gaps` | Functions with unrecoverable rationale (inactive authors, timeline gaps) |\n| `get_branch_context` | Branch merge history — what was migrated and why |\n| `search_decisions` | Search past decisions by keyword across the entire repo |\n| `create_override` | Override a frozen function (user approves in Claude Code UI) |\n| `extract_intent` | Extract intent for NOISE commits using the host LLM — no Ollama needed |\n| `find_similar_functions` | Search for existing functions that solve a similar problem before writing new code |\n| `predict_impact` | Predict what functions will break if a given function is modified |\n| `get_codebase_conventions` | Extract coding conventions for a file's neighborhood |\n\n**MCP Resource:** `wisegit://manifest/{filePath}` — decision manifest as auto-discoverable resource\n\n**MCP Prompt:** `check_before_edit` — mandatory workflow prompt that returns the decision manifest before editing any file\n\n### LLM Intent Extraction Strategy\n\nwisegit uses a smart fallback chain for extracting intent from NOISE commits:\n\n| Context | LLM Used | How |\n|---------|----------|-----|\n| **Inside Claude Code** | Host LLM (Claude) | MCP sampling — asks Claude to analyze the diff. Zero setup. |\n| **CLI with Ollama** | Ollama (llama3) | `wisegit init --ollama` — uses local Ollama instance |\n| **CLI without Ollama** | None | Rule-based extraction only, NOISE commits get no intent |\n\nInside Claude Code, call `extract_intent` to retroactively recover intent for NOISE commits — uses Claude itself, no Ollama installation needed.\n\n## CLI Commands\n\n```bash\nwisegit setup [--path <dir>] [--global]         # One-command repo setup\nwisegit init [--full-history] [--path <dir>]     # Index git history\nwisegit enrich [--path <dir>]                    # Fetch issue/PR context from GitHub/GitLab\nwisegit audit <file>                             # Show decision manifest\nwisegit history <target> [--file <path>]         # Show decision timeline\nwisegit recompute [--path <dir>]                  # Recompute scores with PageRank + theory gaps\nwisegit override <fn> --file <f> --reason \"...\"  # Override a frozen function\nwisegit overrides                                # List active overrides\nwisegit sync                                     # Rebuild local cache from git + .wisegit/\nwisegit config list                              # View team configuration\nwisegit config set <key> <value>                 # Modify team policy\nwisegit team-status                              # Team overview: enrichments, overrides, contributors\nwisegit team-health                              # Theory health: healthy/fragile/critical functions\nwisegit branch-capture                           # Capture branch context from last merge\nwisegit branch-list                              # List all captured branch snapshots\nwisegit branch-recover <sha>                     # Recover context from old merge commit\nwisegit calibrate                                # Show adaptive obsolescence weights vs defaults\nwisegit report [--output <file>]                 # Generate HTML report with scores + insights\nwisegit serve                                    # Start MCP server (stdio)\nwisegit hook install|uninstall                   # Manage git hooks (post-commit + post-merge)\n```\n\n## Configure for Claude Code\n\n### Option A: Per-repo (recommended)\n\nRun `npx @sandip124/wisegit setup` in any repo. It creates `.mcp.json` automatically.\n\n### Option B: Global registration\n\n```bash\nclaude mcp add wisegit -- npx @sandip124/wisegit serve\n```\n\n### Option C: Manual `.mcp.json`\n\nCreate `.mcp.json` in your repo root:\n\n```json\n{\n  \"wisegit\": {\n    \"command\": \"npx\",\n    \"args\": [\"@sandip124/wisegit\", \"serve\"]\n  }\n}\n```\n\n## Supported Languages\n\n| Language | Extensions |\n|----------|-----------|\n| C# | `.cs` |\n| TypeScript | `.ts`, `.tsx` |\n| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` |\n| Python | `.py` |\n| Go | `.go` |\n| Rust | `.rs` |\n\nMore languages can be added via Tree-sitter grammar configs in `src/ast/languages/`.\n\n## Issue Enrichment\n\nA commit saying `fix: handle null token #134` points to an issue containing reproduction steps, root cause, and explicit decision rationale — everything the commit message never says.\n\n```bash\n# Fetch issue context from GitHub/GitLab\nwisegit enrich --path /path/to/repo\n\n# With auth (5000 req/hr instead of 60)\nGITHUB_TOKEN=ghp_... wisegit enrich\n```\n\n**Supported platforms:** GitHub, GitLab (Azure DevOps, Jira, Bitbucket planned)\n\n**Auth tokens:** `GITHUB_TOKEN` / `GH_TOKEN` for GitHub, `GITLAB_TOKEN` for GitLab. Never stored by wisegit.\n\n### Issue-derived freeze signals\n\n| Signal | Freeze Boost | When |\n|--------|-------------|------|\n| Won't Fix / By Design | **+0.35** | Issue closed as `not_planned`, or has `wontfix`/`by-design` label, or comment says \"intentional\" |\n| Reproduction steps | +0.15 | Issue body contains \"steps to reproduce\" |\n| Platform-specific label | +0.10 | Issue labeled `ios`, `safari`, `windows`, etc. |\n| Issue unreachable | +0.10 | Issue ref exists but API returned 404 — absent context = protect more |\n| PR review comments | +0.15 | Linked PR had reviewer discussion |\n\n## Freeze Score Signals\n\nThe freeze score is **never stored directly** — it's derived by replaying the event stream for each function. Signal categories:\n\n| Category | Weight | Source |\n|----------|--------|--------|\n| Git History | 0.20 | Reverts, verified keywords, incident refs, contributor count, Weibull age [18] |\n| Issue Enrichment | 0.20 | Won't Fix/By Design, reproduction steps, platform labels |\n| Code Structure | 0.15 | Inline comments, magic numbers, defensive patterns |\n| Test Signals | 0.15 | Dedicated tests, edge case labels, co-committed tests |\n| Structural Importance | 0.15 | Call count (PageRank), public API, DOE expertise model [19] |\n| Naur Theory | 0.10 | Global patterns, intentional contradictions, removal cost |\n| Aranda Signals | 0.05 | Forgotten patterns, timeline gaps, broken issue links |\n| Obsolescence (8 signals) | adaptive | Dead code, stale subgraph, migration leftover, obsolete deps, superseded, SAAD, change burst absence, co-change divergence |\n\n**Freeze score formula:**\n```\nfreeze_score = base_score x (1 - obsolescence_penalty)\n```\nProtection signals produce the base score (weighted average of present signal categories, not additive sum); obsolescence signals produce the penalty.\nObsolescence weights are **adaptive** — calibrated per-repository using Shannon entropy\nand Bayesian feedback. Falls back to hardcoded defaults when < 20 functions have signals.\nAge signal uses **Weibull survival model** [18] (k=0.7, lambda=2.4y); contributor expertise uses **DOE model** [19] (4 variables: contribution share, recency, duration, frequency).\n\nAcademic grounding: 24 published papers. See [REFERENCE.md](REFERENCE.md) for full citations.\n\n## Cross-Repo Validation\n\nTested on 3 real-world open-source codebases:\n\n| Repo | Commits | Functions | FROZEN | STABLE | Max Score |\n|------|---------|-----------|--------|--------|-----------|\n| pallets/flask | 5,565 | 4,355 | 72 | 2,272 | 0.927 |\n| expressjs/express | 6,382 | 409 | 1 | 247 | 0.811 |\n| zeeguu/api | 4,515 | 3,216 | 1 | 12 | 0.583 |\n\nFlask's core APIs (`__init__`, `run`, `wsgi_app`, `url_for`) correctly scored FROZEN (0.87+). Express routing primitives (`paramCallback`, `Route`, `Router`) correctly scored FROZEN/STABLE. Scores adapt to each codebase's history rather than producing uniform distributions.\n\nSee [REFERENCE.md](REFERENCE.md) for detailed validation findings and implementation changes.\n\n## Legacy Codebase Evolution\n\nwisegit is designed for codebases that have accumulated years of intentional decisions. The freeze score doesn't mean \"never change this\" — it means \"understand these decisions before you change it.\"\n\n**Progressive migration, not shiny rewrites.** Per Távora [12]: the business rules in messy code are *correct and valuable*. The technical debt is in the structure, not the decisions. wisegit protects the decisions while you fix the structure.\n\n| Stage | How wisegit helps |\n|-------|-------------------|\n| **Understand AS-IS** | `wisegit audit` shows what's intentional. `wisegit team-health` shows where institutional knowledge is lost. |\n| **Protect during refactoring** | Manifests tell developers + AI which behaviors were deliberately chosen |\n| **Record rationale** | Override reasons persist in `.wisegit/overrides.jsonl` — not buried in Slack |\n| **Preserve migration context** | Branch snapshots record what was replaced and what should never return |\n| **Track cross-boundary deps** | Co-change signals detect coupling between legacy and replacement code |\n\nSee [REFERENCE.md](REFERENCE.md) for the full legacy evolution section with academic grounding (24 published papers).\n\n## Team Support\n\nwisegit uses a three-layer architecture — no separate \"team mode\" needed:\n\n| Layer | What | Shared? |\n|-------|------|---------|\n| **Deterministic base** | Commit classification, rule-based intent, git signals | Via git (automatic) |\n| **Team knowledge** | Enrichments, overrides, intents, branch contexts | Via `.wisegit/` (git-tracked) |\n| **Local cache** | SQLite at `~/.wisegit/wisegit.db` | Never (derived) |\n\n```\n.wisegit/                      # Tracked by git — shared with team\n├── config.json                # Team policy (thresholds, AI authors)\n├── enrichments.jsonl          # Issue enrichment cache\n├── overrides.jsonl            # Override audit trail\n└── branch-contexts.jsonl      # Branch merge snapshots\n```\n\n**JSONL format** — one JSON object per line. Concurrent appends produce no git merge conflicts.\n\nAfter a teammate pushes `.wisegit/` changes, run `wisegit sync` to import them into your local cache.\n\nSee [TEAM-ROADMAP.md](TEAM-ROADMAP.md) for the full team architecture design.\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────┐\n│  Claude Code / MCP Client                       │\n│  ┌───────────────────────────────────────────┐  │\n│  │ 1. Reads CLAUDE.md protection rules       │  │\n│  │ 2. Calls get_file_decisions before edits  │  │\n│  │ 3. Respects FROZEN / STABLE / OPEN        │  │\n│  └───────────────────────────────────────────┘  │\n└─────────────────┬───────────────────────────────┘\n                  │ MCP (stdio)\n┌─────────────────▼───────────────────────────────┐\n│  wisegit MCP Server                             │\n│  ┌──────────┐ ┌──────────┐ ┌─────────────────┐ │\n│  │get_file_ │ │get_freeze│ │search_decisions │ │\n│  │decisions │ │_score    │ │                 │ │\n│  └────┬─────┘ └────┬─────┘ └───────┬─────────┘ │\n└───────┼─────────────┼───────────────┼───────────┘\n        │             │               │\n┌───────▼─────────────▼───────────────▼───────────┐\n│  SQLite (~/.wisegit/wisegit.db)                 │\n│  ┌──────────────┐ ┌────────────┐ ┌───────────┐ │\n│  │decision_events│ │freeze_scores│ │issue_     │ │\n│  │(append-only) │ │(derived)   │ │enrichments│ │\n│  └──────────────┘ └────────────┘ └─────┬─────┘ │\n└────────────────────────────────────────┼────────┘\n                                         │\n┌────────────────────────────────────────▼────────┐\n│  Issue Enrichment (wisegit enrich)              │\n│  ┌─────────┐ ┌─────────┐ ┌──────────────────┐  │\n│  │ GitHub  │ │ GitLab  │ │ Jira (planned)   │  │\n│  │ REST API│ │ REST API│ │                  │  │\n│  └─────────┘ └─────────┘ └──────────────────┘  │\n└─────────────────────────────────────────────────┘\n```\n\n## Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `WISEGIT_DB_PATH` | `~/.wisegit/wisegit.db` | SQLite database path |\n| `GITHUB_TOKEN` / `GH_TOKEN` | — | GitHub API token (5000 req/hr vs 60 unauthenticated) |\n| `GITLAB_TOKEN` | — | GitLab API token for issue enrichment |\n| `OLLAMA_URL` | `http://localhost:11434` | Ollama server URL (Phase 2) |\n| `OLLAMA_CHAT_MODEL` | `llama3` | Model for intent extraction (Phase 2) |\n| `OLLAMA_EMBED_MODEL` | `nomic-embed-text` | Model for embeddings (Phase 2) |\n\n## Security\n\n- **Everything runs locally** — only issue enrichment makes outbound API calls (opt-in via `wisegit enrich`)\n- **Append-only event store** — decisions are never deleted, only added\n- **SQLite database** stored at `~/.wisegit/wisegit.db` — no network exposure\n- MCP tool inputs validated with strict Zod schemas (path traversal protection, length limits)\n- Error messages sanitized before returning to MCP clients\n- File writes check for symlinks before writing\n- Config files parsed with allowlisted keys only (no prototype pollution)\n\n## Roadmap\n\n- [x] **Phase 1** — Event store, AST chunking, commit classification, intent extraction, MCP server, CLI\n- [x] **Phase 1.5** — Issue enrichment (GitHub, GitLab) with Won't Fix/By Design detection, freeze boost signals\n- [x] **Phase 2** — Full freeze score: call graph + PageRank, theory gap detection (Naur death, forgotten patterns), co-change signals, Aranda signals, Ollama client, Go + Rust support\n- [x] **Phase 4** — Override system (mandatory reason, time-boxed expiry, audit trail), branch context preservation (post-merge hook, snapshot storage, recovery)\n- [x] **Phase A** — Shared team knowledge layer: `.wisegit/` directory with JSONL files for enrichments, overrides, branch contexts, and team config\n- [x] **Phase B** — Team-aware manifests: theory holder tracking, risk levels (healthy/fragile/critical), team status + health commands\n- [x] **Phase C** — AI-era adaptations: commit origin detection (HUMAN/AI_REVIEWED/AI_UNREVIEWED), origin-weighted freeze scores\n- [x] **Phase D** — Override approval workflow, team health metrics\n- [x] **Phase E** — Adaptive obsolescence calibration: 8 obsolescence signals, entropy-calibrated weights, Bayesian feedback, `wisegit calibrate` CLI\n\n## License\n\nMIT\n",
  "bytes": 18519,
  "sha": "5d9d56fb0464c541fdd547cf406623eff3a17097ddce285c39e5e4fecd7e2e02",
  "repo_slug": "sandip124/wisegit",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_sandip124_wisegit_d87680b1/readme"
}