Codex Protocol Guardian

位置付けは「ローカルMCPガバナンスコア＋標準デリバリー適応」に固定されています。クローズドループは次の通りです： 契約 -> 開発検証 -> ビルドリリース -> インストール接続 -> MCPスモーク -> 診断 -> アップグレード/ロールバック。 コアはローカル構造、プロトコル、アーカイブ形式のみを検証し、外部プラットフォームの事実を取得せず、集中コンソールも持たず、Agentをスケジュールしません。

Codex開発タスクを要件パッケージ、単一のアクティブな候補サブジェクト、実行可能な仕様、独立したゲート、トレーサブルなレビューパケットに整合させるためのMCPガバナンスパッケージ。

このパッケージは子エージェントを生成せず、ロールプロンプトをエクスポートせず、タスクを実行せず、ランタイム状態を書き込みません。ガバナンス証跡を検証し、不変のフィンディングアーカイブを追加できますが、自身の作業を承認することはありません。レガシーロール、ディスパッチ、サブエージェントモジュールはパッケージのサーフェスに含まれません。

構造

project-root
|-- pyproject.toml
|-- README.md
|-- src\agent_team_mcp
|   |-- server.py
|   |-- tools.py
|   |-- protocol_guardian.py
|   `-- data
|       |-- protocol_guardian.json
|       `-- protocols
|           |-- protocol-driven-development.md
|           |-- module-interface-boundary.md
|           |-- code-size-governance.md
|           |-- acceptance-alignment.md
|           `-- traceability-checkpoint.md
`-- tests

MCPサーバーは自身をcodex-protocol-guardianとしてアドバタイズします。

Related MCP server: DoneProof MCP

サーフェス境界

ガバナンスパッケージには、必須または検出可能なスキルサーフェスはありません。レガシーロール、プロンプト、ディスパッチ、サブエージェントモジュールはパッケージから削除されました。フロントエンド、外部ツール、ウェブノベル素材はオプションのドメインコンテンツであり、デフォルトのガバナンスコンテキストには読み込まれません。新しいコードは以下にリストされている公開ガバナンス関数を使用する必要があります。

ソースツリーには参照用の履歴スキルドキュメントが保持される場合がありますが、パッケージビルドとリソースローダーにはガバナンスプロトコルと実行可能仕様テンプレートのみが含まれます。レガシースキル、ロール、プロンプトデータはロード可能なパッケージリソースではありません。

ツール

• list_protocols: プロトコルマニフェスト、必須アーティファクト、ワークフローフェーズ、ハードゲート、公開ツールリストを返します。

• export_protocol_context: 完全なプロトコルコンテキスト、ロードされたプロトコル本文、ハッシュ、必須アーティファクト、ワークフロー、ハードゲート、指示を返します。

• export_execution_plan_template: 必須の.codex/protocol/*アーティファクトのスターターテンプレートを返します。実行可能なSpecテンプレートと、ファイル設計の前に必要なモジュール境界および通信容量宣言を含みます。

• audit_alignment_packet: 最終パケットに要件、計画、受け入れプロトコル、トレーサビリティ、変更ファイル、検証証跡、独立レビューシグナル、候補権限、分解、ソリューション設計、スコープ、収束ゲート証跡があるかどうかをチェックします。欠落しているガバナンス証跡はブロックされます。レガシーバイパスはありません。

• validate_candidate_manifest: 単一アクティブサブジェクトマニフェストを検証します。

• transition_candidate: ミューテーションなしで1つの正当なライフサイクルイベントを適用します。

• classify_review_finding: フィンディングが候補に留まるか、後継が必要かを決定します。

• validate_requirements_decomposition: 設計開始前に凍結されたアトミック要件を検証します。

• validate_solution_design: 代替案、正確な要件バインディング、モジュール境界、スコープダイジェストを検証します。

• validate_change_scope: 設計許可リスト外の変更ファイルを拒否します。

• validate_finding_ledger: フィンディングフィンガープリント、クロージャー証跡、後継継承、再発ブロッキングを検証します。

• validate_finding_archive: 永続化されたフィンディングアーカイブと親候補チェーンを検証します。

• read_finding_archive: 設定されたガバナンスアーカイブルートの下にある相対アーカイブパスをロードして検証します。

• append_finding_archive: 期待ダイジェストの競合チェック付きでガバナンスレコードを原子的に追加します。絶対パスと..トラバーサルは拒否されます。

必須アーティファクト

Codexは開発タスク中にターゲットプロジェクト内でこれらのファイルを保持する必要があります：

.codex/protocol/current/requirements.md
.codex/protocol/current/specification.md
.codex/protocol/current/execution_plan.md
.codex/protocol/current/acceptance_protocol.md
.codex/protocol/current/traceability.md
.codex/protocol/current/decision_log.md

パッケージはランタイム状態を書き込みません。唯一の書き込み操作は明示的なappend_finding_archiveガバナンスアーティファクト操作であり、期待ダイジェストと原子的置換を使用して更新の喪失を防ぎます。アーカイブルートはAGENT_TEAM_MCP_ARCHIVE_ROOTによって明示的に設定されるか、AGENT_TEAM_MCP_GOVERNANCE_ROOTとAGENT_TEAM_MCP_PROJECT_NAMESPACEから導出されます。どちらの設定もない場合、現在のプロジェクトの.codex/protocol/current/archivesにデフォルト設定されます。サポートされているすべてのホストは同じガバナンスルートと名前空間を使用する必要があります。

オプションのビジョン支援

プロジェクトはagent-vision-toolkitをオプションスキルとしてsrc/agent_team_mcp/data/optional_skills/agent-vision-toolkitにベンダー提供しています。モデル機能を明示的に指定してvision_assistance操作を呼び出します：

• vision_capable=trueはmode=skipを返し、スキルを公開しません。

• vision_capable=falseはvision-skillsエントリ、ツールマップ、トリガー、テキストのみのモデルに対する可視効果を返します。

これは公開契約のみです。依存関係をインストールせず、ビジョンAPIを呼び出さず、資格情報を読み取らず、モデルトラフィックをプロキシせず、ホスト設定を変更しません。バンドルされたスキルは、使用時に外部設定されたビジョンAPIが依然として必要です。デフォルトのOpenAI互換候補はGLM-4.6V-FlashとGLM-4.1V-Thinking-Flashです。プロジェクト環境でVISION_API_KEYを設定し、ソース管理から除外してください。VISION_MODELはプライマリ候補を選択し、VISION_MODELSはカンマ区切りのフォールバックリストを提供します。

ローカルプロジェクト環境の場合、バンドルされたsrc/agent_team_mcp/data/optional_skills/agent-vision-toolkit/.env.exampleをプロジェクトルートに.envとしてコピーし、VISION_API_KEYのみを入力します。ルートの.envはソース管理で無視され、スキルによって自動的にロードされます。

外部OCRモジュールアダプター（V1）

V1モデルプールとインテントルーターはこのガバナンスチェックアウトの外部にあります。オプションのvision_assistアダプター操作を使用する場合、OCR_MODULE_ROOTをそのモジュールのローカルディレクトリに設定します。必須のvision_capableブール値を持つJSONリクエストを受け入れます。ネイティブビジョン呼び出し元はskipを返し、テキストのみの呼び出し元は固定された外部アダプタールートに転送されます。

外部モジュールは静的GLMモデル候補、インテントルール、プロバイダー呼び出し、結果正規化を所有します。そのローカル.envにはプロバイダー設定が含まれています。V1は意図的に権限、テナント、キュー、サービスディスカバリ、ロードバランシング、クラウドオーケストレーション、管理UIを追加しません。

list_protocolsはパッケージ/プロトコルバージョン、スキーマ互換性と非推奨ポリシー、サポートされているホスト、stdioトランスポート、アーカイブルート戦略を公開します。バージョンはsrc/agent_team_mcp/version.pyから一度だけ取得されます。現在のリリースはschema_version == 1のみを受け入れます。バージョン付きリーダーと移行コマンドが存在するまで、移行は意図的に実装されていません。

ローカルランタイムチェック

MCPを開始する前に、このチェックアウトをプロジェクト環境にインストールします：

python -m pip install --editable .
python scripts\verify_runtime_source.py
python -m pip install --requirement requirements-lock.txt

パッケージを再インストールした後、MCPプロセスを再起動または再登録して、マニフェストとプロトコルリソースがこのチェックアウトから取得されるようにします。

ワークフロー

1. 編集前にexport_protocol_contextをロードします。

2. 必須のプロトコルアーティファクトを作成または更新します。

3. 安定した要件ID（R1、R2、...）と受け入れID（A1、A2、...）を割り当てます。

4. ソリューション設計を書く前に要件分解を凍結します。各項目には観察可能な結果、境界、非目標、依存関係、受け入れIDが必要です。

5. 凍結された分解に対してソリューション設計を検証します。設計は代替案の中から選択し、公開インターフェース、責任、禁止された義務、許可されたファイル、スコープダイジェストを宣言する必要があります。

6. パッケージ化された実行可能Spec標準からspecification.mdを構築します。コードを計画する前に、すべてのルールをその本番入力プロジェクションに対して実行します。

7. 単一のアクティブな候補サブジェクトを維持します。拒否されたサブジェクトと置き換えられたサブジェクトをreplacesとsuperseded_byでリンクしてアーカイブします。

8. 重要な要件、設計、またはスコープのフィンディングは後継を作成します。軽微なフィンディングは現在の候補で修正される場合があります。

9. すべての管理パケットにはフィンディング台帳が必要です。後継チェーンから継承された繰り返しフィンガープリントは、根本原因の証跡が存在するまで受け入れをブロックします。

10. スコープドリフト、レビュー独立性、CI完全性、トレーサビリティクロージャー、アーティファクト出所、ランタイム受け入れ境界について独立したゲートを報告します。CI完全性には、ブランチ保護、必須チェック、CODEOWNER承認、古いレビューの却下、マージキューポリシーに関する外部プラットフォーム証跡も必要です。

11. プロセスメトリクスを個別に記録します：状態滞在時間、レビュー反復回数、置き換え数、拒否率、未解決ブロッカー、リードタイム、変更失敗率、回復時間。

12. 各編集の前に、フェーズ、要件ID、受け入れID、許可されたファイル、期待される証跡を宣言します。

13. 機能コンポーネントのファイルを選択する前に、その単一の公開インターフェース、内部責任分割、依存関係方向、期待されるトラフィック、順序/冪等性、背圧、障害処理、スケーリング、観測可能性を宣言します。単一の公開インターフェースがすべての作業を直列化してはなりません。

14. 内部ファイルを責任と変更理由で分割します。固定の行数しきい値を使用したり、ファサード、ビジネスロジック、ストレージ、外部通信を1つのファイルにまとめたりしないでください。単一責任のリーフファイルは有効です。

15. 各編集後、差分を要件、仕様、実行計画、受け入れプロトコル、トレーサビリティ、非目標と比較します。

16. 計画逸脱をdecision_log.mdに記録します。

17. 検証を実行し、レビューパケットをエクスポートします。

18. セルフテストは証跡としてのみ扱います。最終受け入れには独立したレビュー、CI、または明示的なユーザー承認が必要です。

サポートマトリックス

最初のリリースはローカルstdioのみをサポートします。Cursor、VS Code、Windsurf、Gemini、リモートHTTP、OAuth、マルチテナントゲートウェイ、集中制御プレーンは別のアダプターまたはプロジェクトです。

Claude Codeプロジェクトアダプター（オプションのフォールバック）

このチェックアウトには、プロジェクトスコープのClaude Code MCP設定が.mcp.jsonに含まれています。これは意図的にCodex設定から分離されており、既存のFastMCPサーバーを開始する前にこのチェックアウトのsrcディレクトリを解決するscripts/claude_code_mcp_server.pyを指しています。

Claude Codeに表示されるPython環境にオプションのMCP依存関係をインストールし、プロジェクトサーバーを検証します：

python -m pip install -e ".[mcp]"
claude mcp list
claude mcp get agent-team-governance

このプロジェクトアダプターは、分離されたテストと意図的なプロジェクトオーバーライドのために保持されています。これはグローバル登録パスではありません。既存のガバナンスツールのみを公開し、エージェントを生成せず、タスクをルーティングせず、Codex MCPプロセスを変更しません。

Claude Desktopグローバルアダプター

通常のClaude Desktop使用では、すべてのプロジェクトから利用可能なユーザースコープのコピーをインストールして登録します。スクリプトはパッケージを専用のユーザーローカルvenvにインストールし、他のサーバーを削除せずにagent-team-governance-desktopをClaudeのグローバル設定にマージします。Microsoft Storeの3p場所（%LOCALAPPDATA%\Claude-3p\claude_desktop_config.json）を最初に検出し、クラシックな%APPDATA%\Claude\claude_desktop_config.jsonパスにフォールバックします：

cd <project-root>
.\scripts\register_claude_desktop.ps1

登録後、Claude Desktopを再起動します。このグローバルエントリはチェックアウトのPython環境から独立しています。スクリプトは.bakバックアップを書き込み、一時ファイルを介して設定を置き換え、MCPスモークが失敗した場合はロールバックします。scripts\unregister_claude_desktop.ps1でアンインストールします。

Desktopは、エージェントシェルがセッションごとのLinux VM内で実行されている間、このMCPサーバーをWindowsホスト上で起動します。したがって、登録はホストプロセスのcwdに依存せず、AGENT_TEAM_MCP_GOVERNANCE_ROOTとAGENT_TEAM_MCP_PROJECT_NAMESPACEを設定します。アーカイブファイルは<governance_root>\<namespace>\archivesの下に書き込まれます。

特定のDesktopプロファイルを対象にするには、-ConfigPathを明示的に渡します。これは、アプリが移行されたユーザーデータディレクトリで実行されている場合に便利です：

.\scripts\register_claude_desktop.ps1 `
  -ConfigPath "$env:LOCALAPPDATA\Claude-3p\claude_desktop_config.json"

Claude Code CLIグローバルアダプター

Claude Code CLIセッションでは、このチェックアウトを指すユーザースコープのエントリを登録します。インストーラーは~/.claude/.mcp.jsonを書き込み、.bakコピーを保持し、インストールまたはスモーク検証が失敗した場合にファイルをロールバックします。デフォルトの名前空間はagent-team-mcp-cliです。グローバルCLIエントリはプロジェクトの分離を推測しないため、プロジェクトごとにプロジェクト固有の名前空間を渡します：

cd <project-root>
.\scripts\register_claude_code_cli.ps1 -ProjectNamespace "billing"

スクリプトはagent-team-governance-cliを絶対ラッパーパスで登録するため、サーバーはどの作業ディレクトリからでも検出可能です。別のディレクトリから確認します：

Set-Location $env:TEMP
claude mcp get agent-team-governance-cli
claude mcp list

ラッパーはパッケージをインポートする前に、常にこのチェックアウトのsrcディレクトリを優先します。アンインストールは同じバックアップパスを通じて編集された設定を復元します：scripts\unregister_claude_code_cli.ps1。

OpenCode CLIグローバルアダプター

OpenCode CLIセッションでは、同じチェックアウトバインドサーバーを使用して、ユーザースコープのローカルstdioエントリを登録します。OpenCodeはWindowsを含むすべてのプラットフォームでXDGスタイルの設定ディレクトリを使用します：デフォルトではエントリは%USERPROFILE%\.config\opencode\opencode.jsoncに書き込まれます。両方のファイルが存在する場合、既存のopencode.jsonが優先されます。XDG_CONFIG_HOMEが設定されている場合は、それが優先されます。スクリプトは兄弟mcpエントリを保持し、編集前に.bakコピーを保存し、安定したユーザーレベルのアーカイブルートとプロジェクト名前空間を設定します：

cd <project-root>
.\scripts\register_opencode_cli.ps1 -ProjectNamespace "billing"
opencode mcp list

結果のOpenCodeエントリはmcp.agent-team-governance-opencodeで、type: "local"、絶対PythonインタープリタとOpenCodeラッパーを含むコマンド配列、および2つのガバナンス環境変数を持ちます。既存のgovernanceツールのみを公開し、OpenCodeのランタイムを変更したり、エージェントを管理したり、Codexの設定やプロセスを変更したりしません。scripts\unregister_opencode_cli.ps1でこのエントリのみを削除します。以前の設定は<config>.bakとして保持されます。

Codex MCP設定

MCPが同じ配布名を持つ兄弟の編集可能なインストールを解決できないように、チェックアウトの環境を明示的に使用します：

[mcp_servers.protocol_guardian]
command = "<project-root>\\.venv\\Scripts\\python.exe"
args = ["-m", "agent_team_mcp.server"]

[mcp_servers.protocol_guardian.env]
AGENT_TEAM_MCP_GOVERNANCE_ROOT = "<project-root>\\.codex\\protocol"
AGENT_TEAM_MCP_PROJECT_NAMESPACE = "agent-team-mcp-cli"

ビルド、ホイール、MCPスモーク

cd <project-root>
.\.venv\Scripts\python.exe -m pytest -q
.\.venv\Scripts\python.exe -m ruff check .
.\.venv\Scripts\python.exe scripts\verify_runtime_source.py
.\.venv\Scripts\python.exe scripts\mcp_smoke.py
.\.venv\Scripts\python.exe -m build

テストスイートは、このチェックアウトのsrcディレクトリをsite-packagesの前に挿入するため、同じ配布名を持つ無関係な編集可能なインストールが誤ったグリーン結果を生成することはありません。

リリースアーティファクトを検証するには、ホイールをクリーンな仮想環境にインストールし、python scripts/mcp_smoke.pyを実行します。スモークはinitialize、tools/list、主要な読み取り専用ツール、および無効な入力処理をカバーします。リリースノートには、バージョン、ホイールファイル名、SHA-256、スキーマ変更、およびロールバック手順を記録する必要があります。requirements-lock.txtはビルド前にCIにインストールされます。pip checkは整合性を検証し、pip-auditは依存関係のセキュリティゲートです。