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：在不产生变更的情况下应用一个合法的生命周期事件。

• 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. 仅保持一个活动候选主题。归档被拒绝和已被取代的主题，并使用 replaces 和 superseded_by 进行链接。

8. 重大需求、设计或范围问题记录会创建后继候选；次要问题记录可以在当前候选中修复。

9. 每个受治理的数据包都必须附带问题台账。从后继链继承的重复指纹会阻止验收，直到存在根本原因证据。

10. 针对范围漂移、审查独立性、CI 完整性、可追溯性闭合、工件来源和运行时验收边界报告独立门禁。CI 完整性还需要分支保护、必需检查、CODEOWNER 审批、过期审查消除和合并队列策略的外部平台证据。

11. 单独记录流程指标：状态停留时间、审查迭代次数、被取代次数、拒绝率、未解决阻塞项、前置时间、变更失败率和恢复时间。

12. 在每次编辑之前，声明阶段、需求 ID、验收 ID、允许的文件和预期证据。

13. 在为功能组件选择文件之前，声明其单一公共接口、内部职责划分、依赖方向、预期流量、顺序/幂等性、背压、故障处理、扩展性和可观测性。单一公共接口不得将所有工作串行化。

14. 按职责和变更原因拆分内部文件。不要使用固定的行数阈值，也不要把门面、业务逻辑、存储和外部通信放在同一个文件中。单一职责的叶子文件仍然有效。

15. 每次编辑之后，将差异与需求、规范、执行计划、验收协议、可追溯性和非目标进行比较。

16. 在 decision_log.md 中记录计划偏差。

17. 运行验证并导出审查数据包。

18. 仅将自测视为证据。最终验收需要独立审查、CI 或用户的明确批准。

Codex MCP 配置

显式使用检出的环境，以便 MCP 无法解析具有相同发行版名称的同级可编辑安装：

[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 之前，因此具有相同发行版名称的无关可编辑安装无法产生虚假的绿色通过结果。