agentseed-mcp 0.3.0

package/README.ja.md

@@ -0,0 +1,320 @@
+<div align="center">
+
+<img src="docs/logo.png" width="96" alt="AgentSeed logo">
+
+# AgentSeed
+
+**AI コーディングエージェントのための反幻覚ゲート。**
+
+AI は存在しない API を捏造し、何も実行せずに「テスト全部通った」と言い、
+自信満々に偽のコードを納品します。**AgentSeed は「完了」と宣言する前に
+それを止めるゲート**——ゼロ依存のプラグインで、コードを検証してから
+「完了」にします。「完了」= **観測された事実**であり、自己申告ではありません。
+
+[![License](https://img.shields.io/badge/license-Apache_2.0-green)](LICENSE)
+[![Version](https://img.shields.io/badge/version-0.3.0-blue)](https://gitcode.com/badhope/AgentSeed/releases)
+[![CI](https://github.com/Morningstar202604/AgentSeed/actions/workflows/ci.yml/badge.svg)](https://github.com/Morningstar202604/AgentSeed/actions/workflows/ci.yml)
+[![Platforms](https://img.shields.io/badge/platform-Cursor%20%7C%20VS%20Code%20%7C%20Claude%20Code%20%7C%20Copilot-blue)](https://agent-plugins.org)
+
+[English](./README.md) · [中文](./README.zh.md) · **日本語**
+
+⭐ **気に入ったら Star を——幻覚コードを出荷する前に、開発者がガードレールに
+出会える最良のシグナルです。**
+
+</div>
+
+---
+
+## なぜ必要か
+
+LLM は幻覚を起こします——コードではそれは**捏造 API・未定義の識別子・
+偽のテスト合格・過剰な宣言**を意味します：
+
+- **15.1%** のコード幻覚は、存在しない・インポートされていない API を呼ぶこと
+  （[arXiv:2404.00971](https://arxiv.org/abs/2404.00971)）。
+- **10% 未満**の幻覚コードしかテストを落とさない——**約 90% は CI をすり抜ける**
+  （[arXiv:2404.00971](https://arxiv.org/abs/2404.00971)）。
+- **60%+** のモデル出力エラーは**見た目では検証不能**（FAVA、[SoK](https://arxiv.org/abs/2502.18468)）。
+
+プロンプトだけのガードレールは「柔らかい」：モデルは検証に同意したふりをして
+スキップできます。**AgentSeed は指示を「硬いゲート」に結びつけます**——
+証拠はモデルの自己申告ではなく、実行されたコードから来ます。
+
+## 30 秒でわかる AgentSeed
+
+ドロップインの [Agent Plugins](https://agent-plugins.org) 1.0.0 プラグイン
+（Skill + MCP サーバー + 任意のクライアント Hook + CI ゲート）が約束する
+3 つのこと：
+
+| 約束 | 実現方法 |
+| --- | --- |
+| **🚫 API を捏造しない** | `verify_code` が **12+ 言語**のコードを解析し、「呼ばれたのに定義もインポートもされていない」シンボルを検出 |
+| **🚫 偽の「完了」を出さない** | `scan_hallucination` がスタブ・過剰宣言・捏造主張を（**英語+中国語+CJK**）検出；`sandbox_run` が実行時主張を実際に実行して証明 |
+| **🚫 検証をスキップさせない** | Skill がワークフローを制約、**クライアント Hook** が `Write`/`Edit` を未検証ファイルでブロック、`guard_cli gate` が CI で同じルールを終了コードで強制 |
+
+1.0.0 仕様が意図的に残した 2 つの穴も埋めます：
+
+| Agent Plugins 1.0.0 の穴 | AgentSeed の答え |
+| --- | --- |
+| 強制メカニズムがない（skill は任意） | `verify-before-code` skill + 任意の**クライアント強制 Hook** で検証をスキップ不可に |
+| 公式 linter がない | `check_plugin` は**最初の厳格な 1.0.0 linter**——しかも AgentSeed 自身が自分の linter を通る（`ok: true`） |
+
+## 幻覚を捕まえる現場を見る
+
+```python
+# エージェントが「書き終えた」コード。magic_unknown() を呼ぶ——
+# 存在せず、インポートもされていない API：
+
+def f():
+    return magic_unknown()      # ← 幻覚 API
+
+# タスクが「完了」になる前に：
+$ verify_code(source=..., language="python")
+{
+  "language": "python",
+  "suspects": ["magic_unknown"]       # ← 検出、ブロック
+}
+```
+
+```text
+# 「完了」宣言も生き残れない：
+"The feature is production ready, all tests pass. Trust me."
+
+$ scan_hallucination(source=...)
+{
+  "hits": [
+    {"word": "all tests pass",   "group": "oversold",  "line": 1},
+    {"word": "production ready", "group": "oversold",  "line": 1},
+    {"word": "trust me",         "group": "oversold",  "line": 1}
+  ],
+  "clean": false                        # ← 検出、ブロック
+}
+```
+
+判定は**約束ではなく計測値**：シード固定の合成コーパス（5 欠陥クラス、
+欠陥 100 + クリーン 40 モジュール）で **precision 1.0 · recall 1.0**
+（tp=100, fp=0, fn=0）——回帰テストでロックイン済み。
+方法と正直な限界は [docs/BENCHMARK.md](./docs/BENCHMARK.md)。
+
+## ゲートの仕組み
+
+1. **コーディング前** — SDD 契約を読み、一文で宣言する。
+2. **実装** — 本物のコードだけ：プレースホルダーも捏造 API も禁止。
+3. **「完了」の前** — `verify_code` + `scan_hallucination` を実行；実行時主張は
+   `sandbox_run` で証明；構造は `schema_validate` で検証。
+4. **言語監査** — 完了報告に証拠を添付；過剰語彙は禁止。
+5. **すべてのチェックが通った時だけ**「完了」を許す。
+
+## クイックスタート
+
+**A — リリースをダウンロード（git 不要）：**
+
+```bash
+# https://gitcode.com/badhope/AgentSeed/releases から最新アセットを取得
+# またはインストーラーでクライアントに配線：
+bash install.sh --client auto --hooks        # macOS / Linux
+./install.ps1 -Client auto -Hooks            # Windows PowerShell
+# --client: claude | opencode | cursor | manual
+# --hooks / -Hooks: Claude Code 強制 Hook も登録
+```
+
+**B — クローン：**
+
+```bash
+git clone https://gitcode.com/badhope/AgentSeed.git
+# ミラー：https://gitcode.com/badhope/AgentSeed · https://gitee.com/badhope/AgentSeed
+```
+
+1. `AgentSeed/` ディレクトリを Agent Plugins 対応クライアント（Cursor、
+   VS Code、Claude Code、Copilot…）に**ドロップ**する。ビルドもインストールも不要。
+2. クライアントが `plugin.json` + `mcp.json` から `verify-before-code` skill と
+   `agentseed` MCP サーバーを自動発見。
+3. **これだけ。** 以降すべてのコーディングタスクがゲートされます：
+   契約 → 実装 → 検証 → 証拠。
+
+単体実行、または人間の PR にも同じ CI ゲート：
+
+```bash
+python3 server/guard_engine.py              # セルフチェック
+python3 -m unittest discover -s server      # 160+ ユニットテスト
+python3 server/guard_cli.py gate --root .   # CI 相当のハードゲート
+python3 server/guard_cli.py check . --ci    # プラグイン適合のみ
+python3 server/guard_cli.py scan src/ --strict
+```
+
+> **Windows 注記：** `mcp.json` は `python3` でサーバーを起動します。多くの
+> Windows 環境ではそのエイリアスは Microsoft Store のスタブです。`command` を
+> `["python", "server/guard_server.py"]` に変更するか、インタプリタの絶対パスを
+> 指定してください。
+
+## 8 つの MCP ツール
+
+必須依存**ゼロ**——純 Python 標準ライブラリ。オプション拡張で 2 ツールが
+業界標準エンジンにアップグレードされます（下記）。
+
+| ツール | ブロックするもの | 技術 |
+| --- | --- | --- |
+| `verify_code` | 捏造 API / 未定義シンボル | Python AST + 設定駆動の汎用語彙パス（12+ 言語） |
+| `check_contract` | 仕様に違反するコード | requires/prohibits 契約チェック |
+| `check_imports` | 幻覚パッケージ（slopsquatting） | stdlib + known_packages ホワイトリスト検証 |
+| `scan_hallucination` | プレースホルダー、誇張、捏造 | 3 グループ 28+ シグナル、EN + CJK |
+| `check_plugin` | 不適合なプラグイン | 厳格 1.0.0 linter |
+| `sandbox_run` | 実行せずに「テスト合格」 | 決定的実行チャネル（メモリ有界出力） |
+| `schema_validate` | 不正な構造化出力 | JSON Schema 検証 |
+| `record_verification` | 証跡の永続化欠如 | `PLUGIN_DATA` 配下の JSONL 監査トレイル |
+
+### 言語カバレッジ（正直な範囲）
+
+| 言語 | `verify_code` 解析 |
+| --- | --- |
+| Python | フル AST スコープウォーク（pyflakes 時はマージ）、行番号付き |
+| TypeScript / JavaScript | 語彙正規表現パス（誤検出クラスを明記） |
+| Go · Rust · Java · C · C++ · C# · PHP · Ruby · Kotlin · Swift | 設定駆動の汎用語彙パス |
+| その他の言語 | `LangSpec` レジストリに追加するだけ——エンジン変更不要 |
+
+正直な限界：属性呼び出し（`obj.m()`）、マクロ、ファイル横断シンボルは解析しません。
+Ruby の括弧なし呼び出しは対応済み。
+
+正直な限界：属性呼び出し（`obj.m()`）、マクロ、ファイル横断シンボルは解析しません。
+
+### 他の言語も本当に検出する——実測済み
+
+同じルールが全登録言語に適用されます：「未定義のシンボルの裸呼び出し」は、構文が何であれ
+幻覚です：
+
+```python
+# Go       detect_undefined_symbols("func main() { process_data() }", "go")  -> ["process_data"]
+# Rust     fn main() { let x = load_config() }        -> ["load_config"]
+# Java     class A { void m() { connect_db() } }      -> ["connect_db"]
+# C        int main() { ghost(); return 0; }          -> ["ghost"]
+# Kotlin   fun main() { fetch_users() }               -> ["fetch_users"]
+# Swift    func run() { connect() }                   -> ["connect"]
+# Ruby     def run; authenticate; end                 -> ["authenticate"]
+# TypeScript function run() { connectDb() }           -> ["connectDb"]
+```
+
+Go · Rust · Java · C · C++ · C# · PHP · Ruby · Kotlin · Swift · TypeScript で実測——
+全言語が捏造呼び出しを検出し、各言語のクリーンコードは**誤検出ゼロ**。
+
+
+## クライアント強制 Hook モード
+
+Skill は「説得」、**Hook はクライアント境界で「強制」**します。AgentSeed を
+Claude Code hook として登録すると、すべての `Write`/`Edit`/`MultiEdit` が
+自動スキャンされます——どのプロンプトもスキップできません：
+
+```bash
+python3 server/guard_hook.py register --client claude   # 冪等、settings にマージ
+python3 server/guard_hook.py --file path/to/source.py   # 任意のファイルを直接スキャン
+```
+
+- **PreToolUse** は内容がディスクに書かれる**前**に検査。ブロック検出は終了コード
+  `2` で、エージェントは指摘された行を直す必要があります。
+- **PostToolUse** はインライン内容のない書き込みパスで保存後ファイルを再検査。
+- **失敗ポリシー（正直な範囲）：** インフラ問題（stdin 不正・ファイル不可読・
+  未知のツール形状）は決して作業をブロックしません（fail-open）。ブロックするのは
+  検出結果だけです。
+
+## プラットフォーム対応
+
+| クライアント | 状態 | 備考 |
+| --- | --- | --- |
+| Claude Code | ✅ 検証済み | skills + MCP + 任意の強制 Hook |
+| opencode | ✅ 検証済み | `~/.config/opencode/opencode.json` |
+| Cursor | ⚪ 仕様互換* | プロジェクトへコピー；安定プラグインディレクトリ未確定 |
+| VS Code (+Copilot) | ⚪ 仕様互換* | MCP サポートは展開中 |
+| Cline / Windsurf | ⚪ 仕様互換* | stdio サーバーエントリをそのままマッピング |
+
+\* 正直な注記：形式は仕様互換・動作見込みですが、メンテナー未実測。
+検証できたら PR でこの表を更新してください。
+
+## オプション依存
+
+```bash
+pip install -r server/requirements.txt
+```
+
+| 拡張 | アップグレード内容 | 未導入時 |
+| --- | --- | --- |
+| `jsonschema` | `schema_validate` → 完全 Draft 2020-12 | 内蔵サブセット検証 |
+| `pyflakes` | `verify_code` → pyflakes F821 解析 | 内蔵 AST ウォーク |
+| `pyyaml` | SKILL.md frontmatter → 完全 YAML | 内蔵ライトパーサー |
+
+## 設定（`agentseed.config.json`）
+
+| キー | 効果 |
+| --- | --- |
+| `allowlist` | スキャン除外（内蔵のテスト慣用句リストを置換） |
+| `severities` | グループ別の重大度上書き（`error` \| `warning` \| `info`） |
+| `timeout` | デフォルト `sandbox_run` タイムアウト（秒、1–120） |
+| `extra_tokens` | 実行時に幻覚ワードプールを拡張 |
+| `suppress_symbols` | `verify_code` が決してフラグしない名前（`suppressed` に表示） |
+| `known_packages` | `check_imports` が既知とするパッケージ（stdlib + 一般的 + このリスト） |
+| `sandbox_allowed_prefixes` | `sandbox_run` が起動できる**実行ファイルのホワイトリスト**；PATH 解決・区切り境界強制（省略=無制限） |
+| `sandbox_env` | `"inherit"` \| `"scrub"` —— `scrub` は認証情報らしき環境変数を起動前に除去 |
+
+未知キーは stderr に警告——タイポは決して黙殺されません。
+
+> ⚠️ **セキュリティ注記：** `sandbox_run` はユーザーの権限で実プロセスを実行します。
+> クライアントはユーザー承認の後ろに置いてください。共有/CI 環境では
+> `sandbox_allowed_prefixes` を設定。コマンドは実行前に `PATH` 解決され、悪意ある
+> `cwd` がホワイトリスト名を偽装できません。未解決・未一致のコマンドは実行せず
+> 拒否（終了コード -10）。
+
+## 互換性とグレースフルデグラデーション
+
+| ホスト能力 | 得られるもの |
+| --- | --- |
+| フル Agent Plugins | ドロップイン：skill + MCP 自動発見、`${PLUGIN_DATA}` 設定尊重 |
+| MCP 対応クライアント | 登録で 8 ツールすべて |
+| skill のみのクライアント | skill ワークフロー；検証は `guard_cli.py` を shell 経由で実行 |
+| ターミナル / CI | 終了コード付き CLI ゲート |
+
+## 内蔵ガードレールライブラリ（EN / 中文 / 日本語）
+
+`PROMPT-POOL`（20+ のコピペ即使用プロンプト）· `HALLUCINATION-PATTERNS`
+（5 クラス失敗モードカタログ）· `VERIFICATION-CHECKLIST`（実行可能な完了
+チェックリスト）· `SDD-CONTRACT`（全タスクが満たすべき契約）·
+`VENDOR-SOLUTIONS`（ベンダー手法の導入マップ）。
+
+## 代替案との比較
+
+| | プロンプト専用 skill | 静的 import linter（MCP） | **AgentSeed** |
+| --- | --- | --- | --- |
+| コードに触れる | ❌ プロンプトのみ | ✅ import グラフ | ✅ AST + 語彙（12+ 言語） |
+| 検証ツールを実行 | ❌ | lint ゲート | ✅ 8 MCP ツール（sandbox 含む） |
+| 幻覚言語スキャン | ❌ | ❌ | ✅ stub/oversold/fabricated、EN + CJK |
+| 強制力 | 軟（skill 文面） | CI ゲート | **硬**：skill + MCP + hook + CLI 終了コード |
+| 1.0.0 適合 linter | ❌ | ❌ | ✅ 最初 |
+
+## FAQ
+
+**特定の LLM が必要？** いいえ——クライアント非依存・モデル非依存。ゲートは
+skill + MCP + hook + CI が実行するもので、モデルには依存しません。
+
+**ゼロ依存？** はい。MCP サーバーは純 Python 標準ライブラリです。
+
+**既存の AGENTS.md / CLAUDE.md と共存できる？** できます——補完関係です。
+あちらはプロジェクト事実（散文・説得力）、AgentSeed は行動契約とハード強制を
+担います。
+
+**新しい言語にどう拡張する？** `server/engine/symbols.py` に `LangSpec` を
+1 件追加するだけ——設定のみ、エンジン変更なし。
+
+## コントリビューション
+
+Issue・PR・アイデア歓迎——未収録の幻覚パターンも issue でどうぞ。
+詳細は [CONTRIBUTING.md](./CONTRIBUTING.md)。
+
+## ライセンス
+
+Apache-2.0 © AgentSeed。 [LICENSE](./LICENSE)。
+
+---
+
+<div align="center">
+
+⭐ **AgentSeed が幻覚コードの出荷を防いだなら、Star を——それは「ガードレールは
+役に立つ」という最良のシグナルです。**
+
+</div>

package/README.md

@@ -0,0 +1,318 @@
+<div align="center">
+
+<img src="docs/logo.png" width="96" alt="AgentSeed logo">
+
+# AgentSeed
+
+**The anti-hallucination gate for AI coding agents.**
+
+AI agents invent APIs. They claim "all tests pass" without running anything.
+They ship confident, fabricated code. **AgentSeed is the gate that stops it** —
+a zero-dependency plugin that verifies code *before* it is marked done, so
+"done" means *observed fact*, not self-report.
+
+[![License](https://img.shields.io/badge/license-Apache_2.0-green)](LICENSE)
+[![Version](https://img.shields.io/badge/version-0.3.0-blue)](https://gitcode.com/badhope/AgentSeed/releases)
+[![CI](https://github.com/Morningstar202604/AgentSeed/actions/workflows/ci.yml/badge.svg)](https://github.com/Morningstar202604/AgentSeed/actions/workflows/ci.yml)
+[![Platforms](https://img.shields.io/badge/platform-Cursor%20%7C%20VS%20Code%20%7C%20Claude%20Code%20%7C%20Copilot-blue)](https://agent-plugins.org)
+
+**English** · [中文](./README.zh.md) · [日本語](./README.ja.md)
+
+⭐ **Like this project? Star it — it helps developers find guardrails before they ship hallucinated code.**
+
+</div>
+
+---
+
+## Why you need this
+
+LLMs hallucinate — and in code that means **invented APIs, undefined
+identifiers, fake test passes, and confident overclaims**:
+
+- **15.1%** of code hallucinations call APIs that don't exist or were never imported ([arXiv:2404.00971](https://arxiv.org/abs/2404.00971)).
+- **<10%** of hallucinated code fails tests — **~90% slips past CI** ([arXiv:2404.00971](https://arxiv.org/abs/2404.00971)).
+- **60%+** of model-output errors are *unverifiable* on their face (FAVA, [SoK](https://arxiv.org/abs/2502.18468)).
+
+Prompt-only guardrails are soft: a model can *agree* to verify and then skip
+it. **AgentSeed binds the instruction to a hard gate** — the evidence comes
+from running code, not from the model's own word.
+
+## What AgentSeed is — in 30 seconds
+
+A drop-in [Agent Plugins](https://agent-plugins.org) 1.0.0 plugin
+(Skill + MCP server + optional client hook + CI gate) that makes three
+promises:
+
+| Promise | How it's kept |
+| --- | --- |
+| **🚫 No invented APIs** | `verify_code` parses your code in **12+ languages** and flags any symbol that is called but never defined or imported |
+| **🚫 No fake "done"** | `scan_hallucination` catches stubs, overclaims, and fabricated claims in **English and CJK**; `sandbox_run` proves runtime claims by actually running them |
+| **🚫 No skipped verification** | the Skill gates the workflow, the **client hook** blocks `Write`/`Edit` on files that don't pass, and `guard_cli gate` enforces the same rules in CI with exit codes |
+
+It also fills the two gaps the 1.0.0 spec deliberately leaves open:
+
+| Gap in Agent Plugins 1.0.0 | AgentSeed's answer |
+| --- | --- |
+| No enforcement mechanism (skills are optional to follow) | `verify-before-code` skill + optional **client-enforced hook** make verification non-skippable |
+| No official conformance linter | `check_plugin` is the **first strict 1.0.0 linter** — and AgentSeed passes its own linter (`ok: true`) |
+
+## See it catch a hallucination
+
+```python
+# Your coding agent just "finished" this — it calls magic_unknown(),
+# an API that doesn't exist and was never imported:
+
+def f():
+    return magic_unknown()      # ← hallucinated API
+
+# AgentSeed, before the task can be marked done:
+$ verify_code(source=..., language="python")
+{
+  "language": "python",
+  "suspects": ["magic_unknown"]       # ← caught, blocking
+}
+```
+
+```text
+# And the agent's completion claim doesn't survive either:
+"The feature is production ready, all tests pass. Trust me."
+
+$ scan_hallucination(source=...)
+{
+  "hits": [
+    {"word": "all tests pass",   "group": "oversold",  "line": 1},
+    {"word": "production ready", "group": "oversold",  "line": 1},
+    {"word": "trust me",         "group": "oversold",  "line": 1}
+  ],
+  "clean": false                        # ← caught, blocking
+}
+```
+
+The verdict is **measured, not promised**: on a seeded synthetic corpus
+(5 defect classes, 100 defective + 40 clean modules) AgentSeed scores
+**precision 1.0 · recall 1.0** (tp=100, fp=0, fn=0) — locked in by a
+regression test. Methodology and honest limits:
+[docs/BENCHMARK.md](./docs/BENCHMARK.md).
+
+## How the gate works
+
+1. **Before coding** — load the SDD contract and state it in one sentence.
+2. **Implement** — real code only: no placeholders, no invented APIs.
+3. **Before "done"** — run `verify_code` + `scan_hallucination`; prove runtime
+   claims with `sandbox_run`; validate structure with `schema_validate`.
+4. **Language audit** — completion reports attach evidence; overclaim
+   vocabulary is banned.
+5. Only when **all checks pass** may the task be marked complete.
+
+## Quick start
+
+**Option A — download a release (no git needed):**
+
+```bash
+# grab the latest asset from https://gitcode.com/badhope/AgentSeed/releases
+# or use the installer, which wires it into your client:
+bash install.sh --client auto --hooks        # macOS / Linux
+./install.ps1 -Client auto -Hooks            # Windows PowerShell
+# --client: claude | opencode | cursor | manual
+# --hooks / -Hooks: also register the Claude Code enforcement hook
+```
+
+**Option B — clone:**
+
+```bash
+git clone https://gitcode.com/badhope/AgentSeed.git
+# mirrors: https://gitcode.com/badhope/AgentSeed · https://gitee.com/badhope/AgentSeed
+```
+
+1. **Drop** the `AgentSeed/` directory into any Agent Plugins–capable client
+   (Cursor, VS Code, Claude Code, Copilot…). No build, no install.
+2. The client auto-discovers the `verify-before-code` skill and the
+   `agentseed` MCP server from `plugin.json` + `mcp.json`.
+3. **That's it.** Every coding task is now gated: contract → implement →
+   verify → evidence.
+
+Run it standalone or gate a human PR with the same rules:
+
+```bash
+python3 server/guard_engine.py              # self-check demo
+python3 -m unittest discover -s server      # 160+ unit tests
+python3 server/guard_cli.py gate --root .   # CI-equivalent hard gate
+python3 server/guard_cli.py check . --ci    # plugin conformance only
+python3 server/guard_cli.py scan src/ --strict
+```
+
+> **Windows note:** `mcp.json` launches the server via `python3`. On many
+> Windows installs that alias is a Microsoft Store stub; change `command` to
+> `["python", "server/guard_server.py"]` or use your interpreter's absolute path.
+
+## The 8 MCP tools
+
+Zero *required* dependencies — pure Python standard library; optional extras
+upgrade two tools to industry-standard engines (see below).
+
+| Tool | Catches | Technique |
+| --- | --- | --- |
+| `verify_code` | Invented APIs / undefined symbols | Python AST + config-driven lexical passes (12+ languages) |
+| `check_contract` | Code violates a written spec | requires/prohibits contract check |
+| `check_imports` | Hallucinated packages (slopsquatting) | stdlib + known-packages allowlist check |
+| `scan_hallucination` | Placeholder code, overclaims, fabricated content | 28+ signals in 3 groups, EN + CJK |
+| `check_plugin` | Non-conformant plugin packaging | Strict 1.0.0 linter |
+| `sandbox_run` | "Tests pass" without running anything | Deterministic execution channel (bounded-memory output) |
+| `schema_validate` | Invalid structured output | JSON Schema validation |
+| `record_verification` | No persistent evidence trail | JSONL audit trail under `PLUGIN_DATA` |
+
+### Language coverage (honest scope)
+
+| Language | `verify_code` analysis |
+| --- | --- |
+| Python | full AST scope walk (+ pyflakes when installed), line numbers |
+| TypeScript / JavaScript | lexical regex pass (documented false-positive classes) |
+| Go · Rust · Java · C · C++ · C# · PHP · Ruby · Kotlin · Swift | config-driven generic lexical pass |
+| any other language | add a `LangSpec` registry entry — no engine change |
+
+Honest limits: attribute calls (`obj.m()`), macros, and cross-file symbols
+are not analyzed; Ruby's paren-less calls are supported.
+
+Honest limits: attribute calls (`obj.m()`), macros, and cross-file symbols
+are not analyzed; Ruby's paren-less calls are supported.
+
+### It really catches other languages — live-tested
+
+The same rule applies to every registered language: a bare call to a symbol
+that is never defined is a hallucination, whatever the syntax:
+
+```python
+# Go       detect_undefined_symbols("func main() { process_data() }", "go")  -> ["process_data"]
+# Rust     fn main() { let x = load_config() }        -> ["load_config"]
+# Java     class A { void m() { connect_db() } }      -> ["connect_db"]
+# C        int main() { ghost(); return 0; }          -> ["ghost"]
+# Kotlin   fun main() { fetch_users() }               -> ["fetch_users"]
+# Swift    func run() { connect() }                   -> ["connect"]
+# Ruby     def run; authenticate; end                 -> ["authenticate"]
+# TypeScript function run() { connectDb() }           -> ["connectDb"]
+```
+
+Verified across Go · Rust · Java · C · C++ · C# · PHP · Ruby · Kotlin ·
+Swift · TypeScript — every language flags its invented call, and clean
+code in each language reports **zero false positives**.
+
+
+## Client-enforced hook mode
+
+Skills persuade; **hooks enforce at the client boundary**. Register AgentSeed
+as a Claude Code hook and every `Write`/`Edit`/`MultiEdit` is scanned
+automatically — no prompt can skip it:
+
+```bash
+python3 server/guard_hook.py register --client claude   # idempotent, merges settings
+python3 server/guard_hook.py --file path/to/source.py   # scan any file directly
+```
+
+- **PreToolUse** inspects the incoming content *before* it lands on disk; a
+  blocking finding exits `2`, and the agent must fix the flagged lines.
+- **PostToolUse** re-checks saved files on write paths without inline content.
+- **Failure policy (honest):** infrastructure problems (bad stdin, unreadable
+  files) never block work — fail-open; only positive scan findings block.
+
+## Platform support
+
+| Client | Status | Notes |
+| --- | --- | --- |
+| Claude Code | ✅ verified | skills + MCP + optional enforcement hook |
+| opencode | ✅ verified | `~/.config/opencode/opencode.json` |
+| Cursor | ⚪ spec-compatible* | copy into project; no stable plugin dir yet |
+| VS Code (+Copilot) | ⚪ spec-compatible* | MCP support rolling out |
+| Cline / Windsurf | ⚪ spec-compatible* | stdio server entry maps directly |
+
+\* honest states: formats are spec-compatible and expected to work, but not yet
+exercised by the maintainers. If you verify one, open a PR updating this table.
+
+## Optional dependencies
+
+```bash
+pip install -r server/requirements.txt
+```
+
+| Extra | Upgrades | Without it |
+| --- | --- | --- |
+| `jsonschema` | `schema_validate` → full Draft 2020-12 | built-in subset validator |
+| `pyflakes` | `verify_code` → pyflakes F821 analysis | built-in AST walk |
+| `pyyaml` | SKILL.md frontmatter → full YAML | built-in lite parser |
+
+## Configuration (`agentseed.config.json`)
+
+| Key | Effect |
+| --- | --- |
+| `allowlist` | scan exclusions (replaces built-in test-idiom list) |
+| `severities` | per-group severity override (`error` \| `warning` \| `info`) |
+| `timeout` | default `sandbox_run` timeout, seconds (1–120) |
+| `extra_tokens` | extend the hallucination word pool at runtime |
+| `suppress_symbols` | names `verify_code` never flags (reported in `suppressed`) |
+| `known_packages` | packages `check_imports` treats as known (stdlib + common + this list) |
+| `sandbox_allowed_prefixes` | **allowlist of executables** `sandbox_run` may launch; PATH-resolved, separator-boundary enforced (absent = unrestricted) |
+| `sandbox_env` | `"inherit"` \| `"scrub"` — `scrub` drops credential-looking env vars |
+
+Unknown keys are warned on stderr — a typo is never silently ignored.
+
+> ⚠️ **Security note:** `sandbox_run` executes real processes with your user's
+> permissions. Gate it behind user approval; set `sandbox_allowed_prefixes` in
+> shared/CI environments. Commands resolve through `PATH` to absolute paths
+> before execution, so a hostile `cwd` cannot shadow an allowlisted binary;
+> unmatched commands are refused (exit -10) without running.
+
+## Compatibility & graceful degradation
+
+| Host capability | What you get |
+| --- | --- |
+| Full Agent Plugins | drop-in: skill + MCP auto-discovered, `${PLUGIN_DATA}` config honored |
+| MCP-capable client | all 8 tools via registration |
+| Skills-only client | skill workflow; verification degrades to `guard_cli.py` via shell |
+| Plain terminal / CI | CLI gates with exit codes |
+
+## Built-in guardrail library (EN / 中文 / 日本語)
+
+`PROMPT-POOL` (20+ copy-paste guardrail prompts) · `HALLUCINATION-PATTERNS`
+(5-class failure-mode catalog) · `VERIFICATION-CHECKLIST` (executable
+end-of-task checklist) · `SDD-CONTRACT` (the contract every task must
+satisfy) · `VENDOR-SOLUTIONS` (adoption map of vendor techniques).
+
+## Why AgentSeed vs. alternatives
+
+| | Prompt-only guardrail skills | Static import linters (MCP) | **AgentSeed** |
+| --- | --- | --- | --- |
+| Touches code | ❌ prompt only | ✅ import graphs | ✅ AST + lexical (12+ langs) |
+| Runs verification tools | ❌ | lint gates | ✅ 8 MCP tools incl. sandbox |
+| Hallucination-language scan | ❌ | ❌ | ✅ stub/oversold/fabricated, EN + CJK |
+| Enforcement | soft (skill text) | CI gate | **hard**: skill + MCP + hook + CLI exit codes |
+| 1.0.0 conformance linter | ❌ | ❌ | ✅ first |
+
+## FAQ
+
+**Does it need a specific LLM?** No — client-agnostic and model-agnostic; the
+gate is enforced by skill + MCP + hooks + CI, not by any model.
+
+**Zero dependencies?** Yes. The MCP server is pure Python standard library.
+
+**Does it work with our existing AGENTS.md / CLAUDE.md?** Yes — it
+complements them. Those files carry project facts (prose, persuasive);
+AgentSeed carries the behavior contract and the hard enforcement.
+
+**How do I extend it to another language?** Add a `LangSpec` registry entry in
+`server/engine/symbols.py` — one config, no engine change.
+
+## Contributing
+
+Issues, PRs and ideas welcome — or open an issue for a hallucination pattern
+we haven't catalogued yet. See [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## License
+
+Apache-2.0 © AgentSeed. See [LICENSE](./LICENSE).
+
+---
+
+<div align="center">
+
+⭐ **If AgentSeed saved you from shipping hallucinated code, star the repo — it's the best signal that guardrails matter.**
+
+</div>