Codex Protocol Guardian

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

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

構造

<checkout-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としてアドバタイズします。

サーフェス境界

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

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

ツール

• 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で設定され、デフォルトでは現在のプロジェクトの.codex/protocol/current/archivesになります。

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

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. 1つのアクティブ候補サブジェクトを維持します。拒否されたサブジェクトと後継されたサブジェクトは、replacesとsuperseded_byでリンクしてアーカイブします。

8. 重大な要件、設計、またはスコープのフィンディングは後継を作成します。軽微なフィンディングは現在の候補内で修正できます。

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

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

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

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

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

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

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

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

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

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

Codex MCP設定

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

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

検証

cd <checkout-root>
python -m pytest -q
python -m ruff check .
python scripts/verify_runtime_source.py

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