Wisegit

wisegit

「なぜ設置されたのかが分かるまでは、柵を取り外してはいけない。」 — G.K. Chesterton

wisegit は、git の履歴から意思決定の意図を抽出し、意図して書かれたコードを AI による変更から保護するローカル MCP サーバーです。

Claude Code（または MCP 互換のエージェント）がファイルを編集しようとすると、wisegit はどの関数が凍結済み、安定、または変更可能かを示す意思決定マニフェストを挿入します。これにより AI は、単にコンパイルできるかどうかだけでなく、意図された内容を尊重します。

設定不要。外部サービス不要。すべてローカルで完結します。

インストール

# Set up any repo (one command)
npx @sandip124/wisegit setup

# Or add as MCP server globally
claude mcp add wisegit -- npx @sandip124/wisegit serve

公開先

• npm： @sandip124/wisegit
• MCP Registry： io.github.Sandip124/wisegit
• GitHub： Sandip124/wisegit

問題点

LLM には意図して書かれたコードという概念がありません。手動でテスト済みの修正も、壊れたスタブも同じように見えます。どちらも単なるテキストだからです。実際の例を示します。

1. Stripe の競合状態を sleep(350) で修正し、手動でテストしてコミットします。
2. 次のセッションで「バグを探して」と指示します。Claude は sleep(350) をデッドコードに見えるため削除します。
3. 本番環境でインシデントが発生します。

根本原因： git の履歴には意図の証拠が含まれています。それを抽出する人はいません。

仕組み

Git History → Tree-sitter AST → Intent Extraction → SQLite Event Store → MCP Tools

1. git の履歴をインデックス化します — すべてのコミットをたどり、AST レベルで差分を解析します（行数ではなく関数の境界を使用）。
2. コミットを分類します — STRUCTURED（fix:、feat:）、DESCRIPTIVE（通常の文章）、または NOISE（wip、x）に分類します。
3. 意図を抽出します — STRUCTURED／DESCRIPTIVE なコミットにはルールベース、NOISE には LLM を使用します（フェーズ 2）。
4. 凍結スコアを算出します — 保護シグナル（git、issue、コード構造、テスト、構造、Naur、Aranda）から、適応型の陳腐化ペナルティ（8 つのシグナル、エントロピーで較正）を差し引いて、関数ごとに 0～1 の値を算出します。経過時間には Weibull 生存モデル [18]、専門知識には DOE モデル [19] を使用します。
5. MCP 経由で意思決定マニフェストを提供します — Claude Code はファイルを編集する前に get_file_decisions を呼び出します。

AI に表示される内容

[DECISION MANIFEST: payment.service.cs]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
FROZEN:  ProcessPayment()  [score: 0.89] [Recovery: L1]
  - sleep(350) → Stripe race condition. Won't Fix.
    HIGH — commit a3f19b2

STABLE:  ValidateOrder()  [score: 0.55] [Recovery: L2]
  - Fixed null reference on Safari iOS WebKit.
    MEDIUM — commit 7c14694

OPEN:    FormatReceipt()  [score: 0.12] [Recovery: L3]
  ← safe to modify
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

• FROZEN（スコア >= 0.80）：ユーザーの明示的な承認なしに変更しないでください。
• STABLE（スコア 0.50-0.79）：慎重に進め、まず意図を確認してください。
• OPEN（スコア < 0.50）：自由に変更しても安全です。

クイックスタート

前提条件

• Node.js >= 20

これだけです。Docker、PostgreSQL、外部サービスは不要です。

1. リポジトリをセットアップする（コマンド 1 つ）

cd /path/to/your/repo
npx @sandip124/wisegit setup

このコマンド 1 つで、次の処理を行います。

• ~/.wisegit/wisegit.db にローカルの SQLite データベースを作成します。
• git の全履歴をインデックス化します（462 コミットを約 13 秒で処理）。
• Claude Code が自動検出できるよう .mcp.json を作成します。
• 編集前の確認を AI に指示するルールを記載した CLAUDE.md を作成します。
• .mcp.json を .gitignore に追加します。

2. Issue のコンテキストを追加する（任意）

# Fetch issue/PR details from GitHub/GitLab
GITHUB_TOKEN=ghp_... npx @sandip124/wisegit enrich

参照されている issue（例：コミットメッセージ内の #134）を取得し、「Won't Fix」や「By Design」の決定を検出して、それらの issue に関連付けられた関数の凍結スコアを引き上げます。

3. 完了

リポジトリを Claude Code で開きます。次の処理が自動的に実行されます。

1. wisegit MCP サーバーを起動します（.mcp.json 経由）。
2. 保護ルールを読み込みます（CLAUDE.md 経由）。
3. ファイルを編集する前に get_file_decisions を呼び出します。

MCP ツール

ツール	説明
get_file_decisions	ファイルの決定マニフェスト — 凍結スコア、意図の履歴、復旧レベル、オーバーライドの状態
get_freeze_score	特定の関数のスコアとシグナルの内訳
get_function_history	関数の決定履歴を時系列順にすべて表示
get_theory_gaps	根拠を復旧できない関数（活動していない作成者、タイムラインの欠落）
get_branch_context	ブランチのマージ履歴 — 移行された内容とその理由
search_decisions	リポジトリ全体を対象に、キーワードで過去の決定を検索
create_override	凍結された関数をオーバーライド（ユーザーが Claude Code UI で承認）
extract_intent	ホストの LLM を使って NOISE コミットの意図を抽出 — Ollama は不要
find_similar_functions	新しいコードを書く前に、同様の問題を解決する既存の関数を検索
predict_impact	指定した関数を変更した場合に、どの関数が壊れるかを予測
get_codebase_conventions	ファイルの周辺コードからコーディング規約を抽出

MCP リソース： wisegit://manifest/{filePath} — 自動検出可能なリソースとしての決定マニフェスト

MCP プロンプト： check_before_edit — ファイルを編集する前に決定マニフェストを返す必須ワークフロープロンプト

LLM による意図抽出戦略

wisegit は、NOISE コミットから意図を抽出するために、スマートなフォールバックチェーンを使用します。

コンテキスト	使用する LLM	方法
Claude Code 内	ホストの LLM（Claude）	MCP サンプリング — Claude に差分の分析を依頼します。セットアップは不要です。
Ollama を使用する CLI	Ollama（llama3）	wisegit init --ollama — ローカルの Ollama インスタンスを使用します
Ollama を使用しない CLI	なし	ルールベースの抽出のみを行い、NOISE コミットから意図は取得しません

Claude Code 内で extract_intent を呼び出すと、NOISE コミットの意図をさかのぼって復旧できます。Claude 自身を使用するため、Ollama のインストールは不要です。

CLI コマンド

wisegit setup [--path <dir>] [--global]         # One-command repo setup
wisegit init [--full-history] [--path <dir>]     # Index git history
wisegit enrich [--path <dir>]                    # Fetch issue/PR context from GitHub/GitLab
wisegit audit <file>                             # Show decision manifest
wisegit history <target> [--file <path>]         # Show decision timeline
wisegit recompute [--path <dir>]                  # Recompute scores with PageRank + theory gaps
wisegit override <fn> --file <f> --reason "..."  # Override a frozen function
wisegit overrides                                # List active overrides
wisegit sync                                     # Rebuild local cache from git + .wisegit/
wisegit config list                              # View team configuration
wisegit config set <key> <value>                 # Modify team policy
wisegit team-status                              # Team overview: enrichments, overrides, contributors
wisegit team-health                              # Theory health: healthy/fragile/critical functions
wisegit branch-capture                           # Capture branch context from last merge
wisegit branch-list                              # List all captured branch snapshots
wisegit branch-recover <sha>                     # Recover context from old merge commit
wisegit calibrate                                # Show adaptive obsolescence weights vs defaults
wisegit report [--output <file>]                 # Generate HTML report with scores + insights
wisegit serve                                    # Start MCP server (stdio)
wisegit hook install|uninstall                   # Manage git hooks (post-commit + post-merge)

Claude Code の設定

オプション A：リポジトリごと（推奨）

任意のリポジトリで npx @sandip124/wisegit setup を実行します。.mcp.json が自動的に作成されます。

オプション B：グローバル登録

claude mcp add wisegit -- npx @sandip124/wisegit serve

オプション C：.mcp.json を手動で設定

リポジトリのルートに .mcp.json を作成します。

{
  "wisegit": {
    "command": "npx",
    "args": ["@sandip124/wisegit", "serve"]
  }
}

対応言語

言語	拡張子
C#	.cs
TypeScript	.ts, .tsx
JavaScript	.js, .jsx, .mjs, .cjs
Python	.py
Go	.go
Rust	.rs

src/ast/languages/ に Tree-sitter 文法設定を追加することで、対応言語を増やせます。

Issue の情報補完

fix: handle null token #134 というコミットは、再現手順、根本原因、明確な決定の根拠が記載された Issue を参照しています。これらは、コミットメッセージには決して書かれない情報です。

# Fetch issue context from GitHub/GitLab
wisegit enrich --path /path/to/repo

# With auth (5000 req/hr instead of 60)
GITHUB_TOKEN=ghp_... wisegit enrich

対応プラットフォーム： GitHub、GitLab（Azure DevOps、Jira、Bitbucket は対応予定）

認証トークン： GitHub 用の GITHUB_TOKEN / GH_TOKEN、GitLab 用の GITLAB_TOKEN。wisegit に保存されることはありません。

Issue 由来の凍結シグナル

シグナル	凍結への加算	条件
修正しない／仕様どおり	+0.35	Issue が not_planned としてクローズされている、wontfix / by-design ラベルが付いている、またはコメントに「intentional」と記載されている
再現手順	+0.15	Issue の本文に「steps to reproduce」が含まれている
プラットフォーム固有のラベル	+0.10	Issue に ios、safari、windows などのラベルが付いている
Issue にアクセスできない	+0.10	Issue 参照が存在するものの API が 404 を返した場合 — コンテキストが欠けている場合は、より強く保護します
PR のレビューコメント	+0.15	関連する PR でレビュアーによる議論があった

Freeze Score Signals

フリーズスコアは直接保存されることはありません。各関数のイベントストリームを再生して算出されます。シグナルのカテゴリは次のとおりです。

カテゴリ	重み	ソース
Git 履歴	0.20	リバート、検証済みキーワード、インシデント参照、コントリビューター数、ワイブル年齢 [18]
イシューの補足情報	0.20	Won't Fix／By Design、再現手順、プラットフォームラベル
コード構造	0.15	インラインコメント、マジックナンバー、防御的パターン
テストシグナル	0.15	専用テスト、エッジケースラベル、同時コミットされたテスト
構造的重要性	0.15	呼び出し回数（PageRank）、公開 API、DOE 専門性モデル [19]
Naur 理論	0.10	グローバルパターン、意図的な矛盾、削除コスト
Aranda シグナル	0.05	忘れられたパターン、タイムラインの空白、リンク切れのイシュー
陳腐化（8 シグナル）	適応型	デッドコード、古くなったサブグラフ、移行の残骸、陳腐化した依存関係、置き換え済み、SAAD、変更バーストの欠如、共同変更の乖離

フリーズスコアの計算式：

freeze_score = base_score x (1 - obsolescence_penalty)

保護シグナルは基本スコア（存在するシグナルカテゴリの加重平均であり、合計ではありません）を算出し、陳腐化シグナルはペナルティを算出します。 陳腐化の重みは適応型で、シャノンエントロピーとベイズフィードバックを使用してリポジトリごとに調整されます。シグナルがある関数が20個未満の場合は、ハードコードされたデフォルト値にフォールバックします。 年齢シグナルにはワイブル生存モデル[18]（k=0.7、lambda=2.4y）を使用し、コントリビューターの専門性にはDOE モデル[19]（4 つの変数：貢献の割合、最近性、期間、頻度）を使用します。

学術的な根拠：公開論文24件。引用の全一覧はREFERENCE.mdを参照してください。

リポジトリ横断の検証

実際のオープンソースコードベース3件でテスト済みです。

リポジトリ	コミット	関数	FROZEN	STABLE	最大スコア
pallets/flask	5,565	4,355	72	2,272	0.927
expressjs/express	6,382	409	1	247	0.811
zeeguu/api	4,515	3,216	1	12	0.583

Flask のコア API（__init__、run、wsgi_app、url_for）は正しく FROZEN（0.87 以上）と判定されました。Express のルーティングプリミティブ（paramCallback、Route、Router）は正しく FROZEN／STABLE と判定されました。スコアは一様な分布を生み出すのではなく、各コードベースの履歴に応じて調整されます。

検証結果と実装の変更点の詳細はREFERENCE.mdを参照してください。

レガシーコードベースの進化

wisegit は、長年にわたって意図的な決定が積み重ねられてきたコードベースを想定して設計されています。フリーズスコアは「これは決して変更してはいけない」という意味ではなく、「変更する前に、これらの決定を理解してください」という意味です。

見栄えのよい全面書き換えではなく、段階的な移行。 Távora [12]によれば、雑然としたコードに含まれるビジネスルールは正しく、価値があります。技術的負債があるのは構造であって、決定ではありません。wisegit は、構造を修正する間もその決定を保護します。

段階	wisegit の支援内容
現状を理解する	wisegit audit は何が意図的なものかを示します。wisegit team-health は、組織的な知識がどこで失われているかを示します。
リファクタリング中に保護する	マニフェストは、どの振る舞いが意図的に選ばれたかを開発者と AI に伝えます
根拠を記録する	オーバーライドの理由は .wisegit/overrides.jsonl に保存され、Slack に埋もれません
移行の背景を維持する	ブランチスナップショットは、何が置き換えられたか、何を二度と戻してはならないかを記録します
境界をまたぐ依存関係を追跡する	共同変更シグナルが、レガシーコードと置き換え後のコードの結合を検出します

学術的な根拠（公開論文24件）を含む、レガシーコードベースの進化に関する全セクションはREFERENCE.mdを参照してください。

チームサポート

wisegit は 3 層アーキテクチャを採用しているため、別個の「チームモード」は必要ありません。

層	内容	共有？
決定論的な基盤	コミットの分類、ルールベースの意図、git シグナル	git 経由（自動）
チームナレッジ	エンリッチメント、オーバーライド、意図、ブランチコンテキスト	.wisegit/ 経由（git で追跡）
ローカルキャッシュ	~/.wisegit/wisegit.db の SQLite	共有しません（派生データ）

.wisegit/                      # Tracked by git — shared with team
├── config.json                # Team policy (thresholds, AI authors)
├── enrichments.jsonl          # Issue enrichment cache
├── overrides.jsonl            # Override audit trail
└── branch-contexts.jsonl      # Branch merge snapshots

JSONL 形式 — 1 行につき JSON オブジェクトが 1 つです。並行して追記しても、git のマージコンフリクトは発生しません。

チームメイトが .wisegit/ の変更をプッシュした後、wisegit sync を実行してローカルキャッシュにインポートしてください。

チームアーキテクチャの設計全体については、TEAM-ROADMAP.md を参照してください。

アーキテクチャ

┌─────────────────────────────────────────────────┐
│  Claude Code / MCP Client                       │
│  ┌───────────────────────────────────────────┐  │
│  │ 1. Reads CLAUDE.md protection rules       │  │
│  │ 2. Calls get_file_decisions before edits  │  │
│  │ 3. Respects FROZEN / STABLE / OPEN        │  │
│  └───────────────────────────────────────────┘  │
└─────────────────┬───────────────────────────────┘
                  │ MCP (stdio)
┌─────────────────▼───────────────────────────────┐
│  wisegit MCP Server                             │
│  ┌──────────┐ ┌──────────┐ ┌─────────────────┐ │
│  │get_file_ │ │get_freeze│ │search_decisions │ │
│  │decisions │ │_score    │ │                 │ │
│  └────┬─────┘ └────┬─────┘ └───────┬─────────┘ │
└───────┼─────────────┼───────────────┼───────────┘
        │             │               │
┌───────▼─────────────▼───────────────▼───────────┐
│  SQLite (~/.wisegit/wisegit.db)                 │
│  ┌──────────────┐ ┌────────────┐ ┌───────────┐ │
│  │decision_events│ │freeze_scores│ │issue_     │ │
│  │(append-only) │ │(derived)   │ │enrichments│ │
│  └──────────────┘ └────────────┘ └─────┬─────┘ │
└────────────────────────────────────────┼────────┘
                                         │
┌────────────────────────────────────────▼────────┐
│  Issue Enrichment (wisegit enrich)              │
│  ┌─────────┐ ┌─────────┐ ┌──────────────────┐  │
│  │ GitHub  │ │ GitLab  │ │ Jira (planned)   │  │
│  │ REST API│ │ REST API│ │                  │  │
│  └─────────┘ └─────────┘ └──────────────────┘  │
└─────────────────────────────────────────────────┘

環境変数

変数	デフォルト値	説明
WISEGIT_DB_PATH	~/.wisegit/wisegit.db	SQLite データベースのパス
GITHUB_TOKEN / GH_TOKEN	—	GitHub API トークン（未認証の場合は 60 req/hr、認証済みの場合は 5000 req/hr）
GITLAB_TOKEN	—	課題のエンリッチメントに使用する GitLab API トークン
OLLAMA_URL	http://localhost:11434	Ollama サーバーの URL（フェーズ 2）
OLLAMA_CHAT_MODEL	llama3	意図の抽出に使用するモデル（フェーズ 2）
OLLAMA_EMBED_MODEL	nomic-embed-text	埋め込みに使用するモデル（フェーズ 2）

セキュリティ

• すべてローカルで実行されます — 外部 API 呼び出しを行うのは課題のエンリッチメントのみです（wisegit enrich でオプトイン）
• 追記専用のイベントストア — 決定が削除されることはなく、追加のみ可能です
• SQLite データベース は ~/.wisegit/wisegit.db に保存されます — ネットワークに公開されません
• MCP ツールの入力は厳格な Zod スキーマで検証されます（パストラバーサル保護、長さ制限）
• MCP クライアントに返す前にエラーメッセージをサニタイズします
• ファイルを書き込む前にシンボリックリンクを確認します
• 設定ファイルは許可リストに登録されたキーのみで解析されます（プロトタイプ汚染なし）

ロードマップ

• フェーズ 1 — イベントストア、AST チャンキング、コミット分類、意図の抽出、MCP サーバー、CLI
• フェーズ 1.5 — 「修正しない」／「仕様どおり」の検出とフリーズブーストシグナルを含む、課題のエンリッチメント（GitHub、GitLab）
• フェーズ 2 — 完全なフリーズスコア：呼び出しグラフ + PageRank、理論のギャップ検出（Naur の死、忘れられたパターン）、共変更シグナル、Aranda シグナル、Ollama クライアント、Go + Rust のサポート
• フェーズ 4 — オーバーライドシステム（必須理由、期限付き有効期限、監査証跡）、ブランチコンテキストの保持（マージ後フック、スナップショット保存、復元）
• フェーズ A — 共有チームナレッジレイヤー：エンリッチメント、オーバーライド、ブランチコンテキスト、チーム設定用の JSONL ファイルを含む .wisegit/ ディレクトリ
• フェーズ B — チーム対応マニフェスト：理論保有者の追跡、リスクレベル（健全／脆弱／重大）、チームステータス + ヘルスコマンド
• フェーズ C — AI 時代への適応：コミットの起源検出（HUMAN/AI_REVIEWED/AI_UNREVIEWED）、起源で重み付けしたフリーズスコア
• フェーズ D — オーバーライド承認ワークフロー、チームヘルスメトリクス
• フェーズ E — 適応型陳腐化キャリブレーション：8 つの陳腐化シグナル、エントロピーでキャリブレーションした重み、ベイズフィードバック、wisegit calibrate CLI

ライセンス

MIT