Codex Protocol Guardian

Позиционирование зафиксировано как «локальное ядро управления MCP + адаптация стандартной поставки». Замкнутый цикл: контракт -> разработка и проверка -> сборка и выпуск -> установка и подключение -> MCP-дымовой тест -> диагностика -> обновление/откат. Ядро проверяет только локальную структуру, протоколы и формат архива, не тянет факты с внешних платформ, не делает централизованную консоль и не управляет агентами.

MCP governance package for keeping Codex development tasks aligned to a requirements package, one active candidate subject, an executable specification, independent gates, and a traceable review packet.

This package does not spawn child agents, export role prompts, execute tasks, or write runtime state. It validates governance evidence and can append immutable finding archives; it never approves its own work. Legacy role, dispatch, and sub-agent modules are not included in the package surface.

Structure

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

The MCP server advertises itself as codex-protocol-guardian.

Related MCP server: workflow-compliance-enforcer

Surface Boundary

The governance package has no required or discoverable skill surface. Legacy role, prompt, dispatch, and sub-agent modules were removed from the package. Frontend, external-tool, and webnovel material is optional domain content and is not loaded into the default governance context. New code must use the public governance functions listed below.

The source tree may retain historical skill documents for reference, but the package build and resource loader include only governance protocols and the executable specification template. Legacy skill, role, and prompt data is not a loadable package resource.

Tools

• list_protocols: returns the protocol manifest, required artifacts, workflow phases, hard gates, and public tool list.

• export_protocol_context: returns the full protocol context, loaded protocol bodies, hashes, required artifacts, workflow, hard gates, and instructions.

• export_execution_plan_template: returns starter templates for the required .codex/protocol/* artifacts, including the executable Spec template and the module-boundary and communication-capacity declaration required before file design.

• audit_alignment_packet: checks whether a final packet has requirements, plan, acceptance protocol, traceability, changed files, validation evidence, an independent review signal, candidate authority, decomposition, solution design, scope, and convergence gate evidence. Missing governance evidence is blocked; there is no legacy bypass.

• validate_candidate_manifest: validates the single-active-subject manifest.

• transition_candidate: applies one legal lifecycle event without mutation.

• classify_review_finding: decides whether a finding stays in the candidate or requires a successor.

• validate_requirements_decomposition: validates frozen atomic requirements before design starts.

• validate_solution_design: validates alternatives, exact requirement binding, module boundaries, and scope digest.

• validate_change_scope: rejects changed files outside the design allow-list.

• validate_finding_ledger: validates finding fingerprints, closure evidence, successor inheritance, and recurrence blocking.

• validate_finding_archive: validates the persisted finding archive and parent candidate chain.

• read_finding_archive: loads and verifies a relative archive path under the configured governance archive root.

• append_finding_archive: atomically appends a governance record with an expected-digest conflict check; absolute paths and .. traversal are rejected.

Required Artifacts

Codex should keep these files in the target project during a development task:

.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

The package does not write runtime state. Its only write operation is the explicit append_finding_archive governance-artifact operation, which uses an expected digest and atomic replacement to prevent lost updates. The archive root is configured explicitly by AGENT_TEAM_MCP_ARCHIVE_ROOT, or derived from AGENT_TEAM_MCP_GOVERNANCE_ROOT and AGENT_TEAM_MCP_PROJECT_NAMESPACE. Without either setting it defaults to .codex/protocol/current/archives under the current project. All supported hosts should use the same governance root and namespace.

Optional Vision Assistance

The project vendors agent-vision-toolkit as an optional skill under src/agent_team_mcp/data/optional_skills/agent-vision-toolkit. Call the vision_assistance operation with the model capability explicitly:

• vision_capable=true returns mode=skip and does not expose the skill.

• vision_capable=false returns the vision-skills entry, tool map, triggers, and the visible effect for a text-only model.

This is an exposure contract only. It does not install dependencies, call a vision API, read credentials, proxy model traffic, or change host configuration. The bundled skill still requires an externally configured vision API when used. Its default OpenAI-compatible candidates are GLM-4.6V-Flash and GLM-4.1V-Thinking-Flash; configure VISION_API_KEY in the project environment and keep it out of source control. VISION_MODEL selects the primary candidate, while VISION_MODELS supplies the comma-separated fallback list.

For a local project environment, copy the bundled src/agent_team_mcp/data/optional_skills/agent-vision-toolkit/.env.example to the project root as .env, then fill only VISION_API_KEY. The root .env is ignored by source control and is loaded automatically by the skill.

External OCR Module Adapter (V1)

The V1 model pool and intent router live outside this governance checkout. Set OCR_MODULE_ROOT to that module's local directory when using the optional vision_assist adapter operation. It accepts a JSON request with a required vision_capable boolean; native-vision callers return skip, while text-only callers are forwarded to the fixed external adapter root.

The external module owns the static GLM model candidates, intent rules, provider calls, and result normalization. Its local .env contains the provider configuration. V1 intentionally does not add permissions, tenants, queues, service discovery, load balancing, cloud orchestration, or management UI.

list_protocols exposes the package/protocol version, schema compatibility and deprecation policy, supported hosts, stdio transport, and archive-root strategy. Version is sourced once from src/agent_team_mcp/version.py. The current release accepts schema_version == 1 only; migration is intentionally not implemented until a versioned reader and migration command exist.

Local Runtime Check

Install this checkout into the project environment before starting MCP:

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

After reinstalling the package, restart or re-register the MCP process so its manifest and protocol resources come from this checkout.

Workflow

1. Load export_protocol_context before editing.

2. Create or refresh the required protocol artifacts.

3. Assign stable requirement ids (R1, R2, ...) and acceptance ids (A1, A2, ...).

4. Freeze a requirements decomposition before writing a solution design. Each item needs an observable result, boundaries, non-goals, dependencies, and an acceptance id.

5. Validate a solution design against the frozen decomposition. The design must choose among alternatives and declare public interfaces, responsibilities, forbidden duties, allowed files, and a scope digest.

6. Build specification.md from the packaged executable Spec standard. Execute every rule against its production input projection before planning code.

7. Keep one active candidate subject. Archive rejected and superseded subjects, linked with replaces and superseded_by.

8. A material requirement, design, or scope finding creates a successor; minor findings may be fixed in the current candidate.

9. Every governed packet must carry a finding ledger. Repeated fingerprints inherited from a successor chain block acceptance until root-cause evidence exists.

10. Report independent gates for scope drift, review independence, CI completeness, traceability closure, artifact provenance, and runtime acceptance boundary. CI completeness also requires external platform evidence for branch protection, required checks, CODEOWNER approval, stale-review dismissal, and merge-queue policy.

11. Record process metrics separately: time in state, review iterations, superseded count, rejection rate, open blockers, lead time, change-fail rate, and recovery time.

12. Before each edit, declare the phase, requirement ids, acceptance ids, allowed files, and expected evidence.

13. Before choosing files for a feature component, declare its single public interface, internal responsibility split, dependency direction, expected traffic, ordering/idempotency, backpressure, failure handling, scaling, and observability. A single public interface must not serialize all work.

14. Split internal files by responsibility and change reason. Do not use fixed line-count thresholds or put facade, business logic, storage, and external communication in one file. Single-responsibility leaf files remain valid.

15. After each edit, compare the diff against requirements, the specification, the execution plan, acceptance protocol, traceability, and non-goals.

16. Record plan deviations in decision_log.md.

17. Run validation and export a review packet.

18. Treat self-test as evidence only. Final acceptance requires independent review, CI, or explicit user approval.

Support Matrix

The first release supports local stdio only. Cursor, VS Code, Windsurf, Gemini, remote HTTP, OAuth, multi-tenant gateways, and centralized control planes are separate adapters or projects.

Claude Code Project Adapter (Optional Fallback)

This checkout includes a project-scoped Claude Code MCP configuration in .mcp.json. It is intentionally separate from Codex configuration and points at scripts/claude_code_mcp_server.py, which resolves this checkout's src directory before starting the existing FastMCP server.

Install the optional MCP dependency in the Python environment visible to Claude Code, then verify the project server:

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

This project adapter is retained for isolated tests and deliberate project overrides. It is not the global registration path. It only exposes the existing governance tools; it does not spawn agents, route tasks, or modify the Codex MCP process.

Claude Desktop Global Adapter

For normal Claude Desktop use, install and register a user-scoped copy that is available from every project. The script installs the package into a dedicated user-local venv and merges agent-team-governance-desktop into Claude's global configuration without removing other servers. It detects the Microsoft Store 3p location (%LOCALAPPDATA%\Claude-3p\claude_desktop_config.json) first and falls back to the classic %APPDATA%\Claude\claude_desktop_config.json path:

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

Restart Claude Desktop after registration. This global entry is independent of the checkout's Python environment. The script writes a .bak backup, replaces the config through a temporary file, and rolls back on a failed MCP smoke. Uninstall with scripts\unregister_claude_desktop.ps1.

Desktop запускает этот MCP-сервер на хосте Windows, в то время как оболочка агента работает внутри виртуальной машины Linux для каждой сессии. Поэтому при регистрации задаются 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 зарегистрируйте запись на уровне пользователя, указывающую на этот checkout. Установщик записывает ~/.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 этого checkout перед импортом пакета. Удаление восстанавливает изменённый конфиг через тот же путь резервной копии: scripts\unregister_claude_code_cli.ps1.

Глобальный адаптер OpenCode CLI

Для сессий OpenCode CLI зарегистрируйте запись локального stdio на уровне пользователя, используя тот же сервер, привязанный к checkout. OpenCode использует каталог конфигурации в стиле XDG на всех платформах, включая Windows: по умолчанию запись записывается в %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, и двумя переменными окружения управления. Она предоставляет только существующие инструменты управления; она не изменяет среду выполнения OpenCode, не управляет агентами и не изменяет конфигурацию или процессы Codex. Удалите только эту запись с помощью scripts\unregister_opencode_cli.ps1; предыдущий конфиг сохраняется как <config>.bak.

Конфиг MCP Codex

Явно используйте окружение checkout, чтобы 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"

Сборка, Wheel и дымовой тест 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 этого checkout перед site-packages, чтобы несвязанная редактируемая установка с тем же именем дистрибутива не могла дать ложный зелёный результат.

Чтобы проверить артефакт релиза, установите wheel в чистое виртуальное окружение и запустите python scripts/mcp_smoke.py. Дымовой тест покрывает initialize, tools/list, ключевые инструменты только для чтения и обработку недопустимого ввода. Примечания к релизу должны фиксировать версию, имя файла wheel, SHA-256, изменения схемы и инструкции по откату. requirements-lock.txt устанавливается в CI перед сборкой; pip check проверяет согласованность, а pip-audit — это шлюз безопасности зависимостей.