Codex Protocol Guardian

El posicionamiento se fija como «núcleo de gobernanza MCP local + adaptación de entrega estándar». El bucle de cierre es: Contrato -> verificación de desarrollo -> compilación y publicación -> instalación de conexión -> prueba de humo MCP -> diagnóstico -> actualización/reversión. El núcleo solo valida la estructura local, el protocolo y el formato de archivo; no obtiene hechos de plataformas externas, no hace consola centralizada ni programa agentes.

Paquete de gobernanza MCP para mantener las tareas de desarrollo de Codex alineadas con un paquete de requisitos, un sujeto candidato activo, una especificación ejecutable, compuertas independientes y un paquete de revisión trazable.

Este paquete no genera agentes secundarios, no exporta avisos de rol, no ejecuta tareas ni escribe estado de ejecución. Valida la evidencia de gobernanza y puede añadir archivos de hallazgos inmutables; nunca aprueba su propio trabajo. Los módulos heredados de rol, despacho y subagente no están incluidos en la superficie del paquete.

Estructura

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

El servidor MCP se anuncia a sí mismo como codex-protocol-guardian.

Related MCP server: workflow-compliance-enforcer

Límite de superficie

El paquete de gobernanza no tiene superficie de habilidad requerida ni descubrible. Los módulos heredados de rol, aviso, despacho y subagente se eliminaron del paquete. El material de frontend, herramientas externas y webnovela es contenido de dominio opcional y no se carga en el contexto de gobernanza predeterminado. El código nuevo debe usar las funciones públicas de gobernanza que se enumeran a continuación.

El árbol de fuentes puede conservar documentos de habilidad históricos como referencia, pero la compilación del paquete y el cargador de recursos incluyen solo protocolos de gobernanza y la plantilla de especificación ejecutable. Los datos heredados de habilidad, rol y aviso no son un recurso de paquete cargable.

Herramientas

• list_protocols: devuelve el manifiesto de protocolo, los artefactos requeridos, las fases del flujo de trabajo, las compuertas estrictas y la lista de herramientas públicas.

• export_protocol_context: devuelve el contexto completo del protocolo, los cuerpos de protocolo cargados, los hashes, los artefactos requeridos, el flujo de trabajo, las compuertas estrictas y las instrucciones.

• export_execution_plan_template: devuelve plantillas iniciales para los artefactos requeridos .codex/protocol/*, incluida la plantilla de Spec ejecutable y la declaración de límite de módulo y capacidad de comunicación requerida antes del diseño de archivos.

• audit_alignment_packet: comprueba si un paquete final tiene requisitos, plan, protocolo de aceptación, trazabilidad, archivos modificados, evidencia de validación, señal de revisión independiente, autoridad de candidato, descomposición, diseño de solución, alcance y evidencia de compuerta de convergencia. La evidencia de gobernanza faltante se bloquea; no hay bypass heredado.

• validate_candidate_manifest: valida el manifiesto de sujeto único activo.

• transition_candidate: aplica un evento de ciclo de vida legal sin mutación.

• classify_review_finding: decide si un hallazgo permanece en el candidato o requiere un sucesor.

• validate_requirements_decomposition: valida los requisitos atómicos congelados antes de que comience el diseño.

• validate_solution_design: valida alternativas, vinculación exacta de requisitos, límites de módulo y resumen de alcance.

• validate_change_scope: rechaza archivos modificados fuera de la lista de permitidos del diseño.

• validate_finding_ledger: valida huellas de hallazgos, evidencia de cierre, herencia de sucesores y bloqueo de recurrencia.

• validate_finding_archive: valida el archivo de hallazgos persistido y la cadena de candidatos padre.

• read_finding_archive: carga y verifica una ruta de archivo relativa bajo la raíz de archivo de gobernanza configurada.

• append_finding_archive: añade atómicamente un registro de gobernanza con una comprobación de conflicto de resumen esperado; las rutas absolutas y el recorrido .. se rechazan.

Artefactos requeridos

Codex debe mantener estos archivos en el proyecto de destino durante una tarea de desarrollo:

.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

El paquete no escribe estado de ejecución. Su única operación de escritura es la operación explícita de artefacto de gobernanza append_finding_archive, que usa un resumen esperado y reemplazo atómico para evitar actualizaciones perdidas. La raíz del archivo se configura explícitamente mediante AGENT_TEAM_MCP_ARCHIVE_ROOT, o se deriva de AGENT_TEAM_MCP_GOVERNANCE_ROOT y AGENT_TEAM_MCP_PROJECT_NAMESPACE. Sin ninguna de las dos configuraciones, el valor predeterminado es .codex/protocol/current/archives bajo el proyecto actual. Todos los hosts compatibles deben usar la misma raíz de gobernanza y el mismo espacio de nombres.

Asistencia de visión opcional

El proyecto incluye agent-vision-toolkit como una habilidad opcional en src/agent_team_mcp/data/optional_skills/agent-vision-toolkit. Llame a la operación vision_assistance con la capacidad del modelo explícitamente:

• vision_capable=true devuelve mode=skip y no expone la habilidad.

• vision_capable=false devuelve la entrada vision-skills, el mapa de herramientas, los disparadores y el efecto visible para un modelo de solo texto.

Esto es solo un contrato de exposición. No instala dependencias, no llama a una API de visión, no lee credenciales, no hace proxy del tráfico de modelos ni cambia la configuración del host. La habilidad incluida aún requiere una API de visión configurada externamente cuando se usa. Sus candidatos predeterminados compatibles con OpenAI son GLM-4.6V-Flash y GLM-4.1V-Thinking-Flash; configure VISION_API_KEY en el entorno del proyecto y manténgala fuera del control de fuentes. VISION_MODEL selecciona el candidato principal, mientras que VISION_MODELS proporciona la lista de respaldo separada por comas.

Para un entorno de proyecto local, copie el src/agent_team_mcp/data/optional_skills/agent-vision-toolkit/.env.example incluido a la raíz del proyecto como .env y luego complete solo VISION_API_KEY. El .env de la raíz es ignorado por el control de fuentes y se carga automáticamente por la habilidad.

Adaptador de módulo OCR externo (V1)

El grupo de modelos V1 y el enrutador de intención viven fuera de este checkout. Configure OCR_MODULE_ROOT en el directorio local de ese módulo cuando use la operación de adaptador opcional vision_assist. Acepta una solicitud JSON con un booleano vision_capable requerido; los llamadores con visión nativa devuelven skip, mientras que los llamadores de solo texto se reenvían a la raíz fija del adaptador externo.

El módulo externo posee los candidatos de modelo GLM estáticos, las reglas de intención, las llamadas al proveedor y la normalización de resultados. Su .env local contiene la configuración del proveedor. V1 intencionalmente no agrega permisos, inquilinos, colas, descubrimiento de servicios, balanceo de carga, orquestación en la nube ni interfaz de gestión.

list_protocols expone la versión del paquete/protocolo, la compatibilidad de esquema y la política de deprecación, los hosts compatibles, el transporte stdio y la estrategia de raíz de archivo. La versión se obtiene una vez de src/agent_team_mcp/version.py. La versión actual acepta solo schema_version == 1; la migración no se implementa intencionalmente hasta que existan un lector con versiones y un comando de migración.

Comprobación de ejecución local

Instale este checkout en el entorno del proyecto antes de iniciar MCP:

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

Después de reinstalar el paquete, reinicie o vuelva a registrar el proceso MCP para que su manifiesto y recursos de protocolo provengan de este checkout.

Flujo de trabajo

1. Cargue export_protocol_context antes de editar.

2. Cree o actualice los artefactos de protocolo requeridos.

3. Asigne identificadores de requisito estables (R1, R2, ...) e identificadores de aceptación (A1, A2, ...).

4. Congele una descomposición de requisitos antes de escribir un diseño de solución. Cada elemento necesita un resultado observable, límites, no objetivos, dependencias y un identificador de aceptación.

5. Valide un diseño de solución contra la descomposición congelada. El diseño debe elegir entre alternativas y declarar interfaces públicas, responsabilidades, deberes prohibidos, archivos permitidos y un resumen de alcance.

6. Construya specification.md a partir del estándar de Spec ejecutable incluido. Ejecute cada regla contra su proyección de entrada de producción antes de planificar el código.

7. Mantenga un sujeto candidato activo. Archive los sujetos rechazados y superados, vinculados con replaces y superseded_by.

8. Un hallazgo material de requisito, diseño o alcance crea un sucesor; los hallazgos menores pueden corregirse en el candidato actual.

9. Cada paquete gobernado debe llevar un libro de hallazgos. Las huellas repetidas heredadas de una cadena de sucesores bloquean la aceptación hasta que exista evidencia de causa raíz.

10. Reporte compuertas independientes para la deriva de alcance, la independencia de revisión, la completitud de CI, el cierre de trazabilidad, la procedencia de artefactos y el límite de aceptación de ejecución. La completitud de CI también requiere evidencia de plataforma externa para protección de ramas, comprobaciones requeridas, aprobación de CODEOWNER, rechazo de revisión obsoleta y política de cola de fusión.

11. Registre las métricas de proceso por separado: tiempo en estado, iteraciones de revisión, recuento de superados, tasa de rechazo, bloqueadores abiertos, tiempo de entrega, tasa de fallo de cambio y tiempo de recuperación.

12. Antes de cada edición, declare la fase, los identificadores de requisito, los identificadores de aceptación, los archivos permitidos y la evidencia esperada.

13. Antes de elegir archivos para un componente de funcionalidad, declare su única interfaz pública, la división de responsabilidades internas, la dirección de dependencias, el tráfico esperado, el ordenamiento/idempotencia, la contrapresión, el manejo de fallos, el escalado y la observabilidad. Una única interfaz pública no debe serializar todo el trabajo.

14. Divida los archivos internos por responsabilidad y motivo de cambio. No use umbrales fijos de número de líneas ni ponga fachada, lógica de negocio, almacenamiento y comunicación externa en un solo archivo. Los archivos hoja de responsabilidad única siguen siendo válidos.

15. Después de cada edición, compare el diff contra los requisitos, la especificación, el plan de ejecución, el protocolo de aceptación, la trazabilidad y los no objetivos.

16. Registre las desviaciones del plan en decision_log.md.

17. Ejecute la validación y exporte un paquete de revisión.

18. Trate la autoprueba solo como evidencia. La aceptación final requiere revisión independiente, CI o aprobación explícita del usuario.

Matriz de soporte

La primera versión admite solo stdio local. Cursor, VS Code, Windsurf, Gemini, HTTP remoto, OAuth, puertas de enlace multiinquilino y planos de control centralizados son adaptadores o proyectos separados.

Adaptador de proyecto Claude Code (respaldo opcional)

Este checkout incluye una configuración MCP de Claude Code con ámbito de proyecto en .mcp.json. Está intencionalmente separada de la configuración de Codex y apunta a scripts/claude_code_mcp_server.py, que resuelve el directorio src de este checkout antes de iniciar el servidor FastMCP existente.

Instale la dependencia MCP opcional en el entorno de Python visible a Claude Code y luego verifique el servidor del proyecto:

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

Este adaptador de proyecto se conserva para pruebas aisladas y anulaciones deliberadas del proyecto. No es la ruta de registro global. Solo expone las herramientas de gobernanza existentes; no genera agentes, no enruta tareas ni modifica el proceso MCP de Codex.

Adaptador global de Claude Desktop

Para el uso normal de Claude Desktop, instale y registre una copia con ámbito de usuario que esté disponible desde todos los proyectos. El script instala el paquete en un venv local de usuario dedicado y fusiona agent-team-governance-desktop en la configuración global de Claude sin eliminar otros servidores. Detecta primero la ubicación de Microsoft Store 3p (%LOCALAPPDATA%\Claude-3p\claude_desktop_config.json) y luego recurre a la ruta clásica %APPDATA%\Claude\claude_desktop_config.json:

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

Reinicie Claude Desktop después del registro. Esta entrada global es independiente del entorno de Python del checkout. El script escribe una copia de seguridad .bak, reemplaza la configuración mediante un archivo temporal y revierte en caso de una prueba de humo MCP fallida. Desinstale con scripts\unregister_claude_desktop.ps1.

Desktop inicia este servidor MCP en el host de Windows mientras el shell del agente se ejecuta dentro de una VM de Linux por sesión. El registro, por tanto, establece AGENT_TEAM_MCP_GOVERNANCE_ROOT y AGENT_TEAM_MCP_PROJECT_NAMESPACE en lugar de depender del cwd del proceso del host. Los archivos de archivado se escriben en <governance_root>\<namespace>\archives.

Para seleccionar un perfil de Desktop específico, pase -ConfigPath explícitamente. Esto es útil cuando la aplicación se ejecuta con un directorio de datos de usuario migrado:

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

Adaptador global de Claude Code CLI

Para sesiones de Claude Code CLI, registre una entrada de ámbito de usuario que apunte a este checkout. El instalador escribe ~/.claude/.mcp.json, conserva una copia .bak y revierte el archivo si falla la instalación o la validación de humo. El espacio de nombres predeterminado es agent-team-mcp-cli; pase un espacio de nombres específico del proyecto para cada proyecto porque la entrada CLI global no infiere el aislamiento del proyecto:

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

El script registra agent-team-governance-cli con una ruta de wrapper absoluta, por lo que el servidor se puede descubrir desde cualquier directorio de trabajo. Verifíquelo desde un directorio diferente:

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

El wrapper siempre prioriza el directorio src de este checkout antes de importar el paquete. La desinstalación restaura la configuración editada a través de la misma ruta de copia de seguridad: scripts\unregister_claude_code_cli.ps1.

Adaptador global de OpenCode CLI

Para sesiones de OpenCode CLI, registre una entrada stdio local de ámbito de usuario utilizando el mismo servidor vinculado al checkout. OpenCode utiliza un directorio de configuración de estilo XDG en todas las plataformas, incluido Windows: por defecto, la entrada se escribe en %USERPROFILE%\.config\opencode\opencode.jsonc; un opencode.json existente tiene prioridad cuando ambos archivos existen. XDG_CONFIG_HOME tiene prioridad cuando está establecido. El script conserva las entradas mcp hermanas, guarda una copia .bak antes de editar y establece una raíz de archivo estable a nivel de usuario más el espacio de nombres del proyecto:

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

La entrada de OpenCode resultante es mcp.agent-team-governance-opencode con type: "local", un array de comandos que contiene el intérprete de Python absoluto y el wrapper de OpenCode, y las dos variables de entorno de gobernanza. Solo expone las herramientas de gobernanza existentes; no altera el tiempo de ejecución de OpenCode, no gestiona agentes ni modifica la configuración o los procesos de Codex. Elimine solo esta entrada con scripts\unregister_opencode_cli.ps1; la configuración anterior se conserva como <config>.bak.

Configuración de Codex MCP

Utilice el entorno del checkout explícitamente para que MCP no pueda resolver una instalación editable hermana con el mismo nombre de distribución:

[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"

Compilación, Wheel y prueba de humo de 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

El conjunto de pruebas inserta el directorio src de este checkout antes de site-packages para que una instalación editable no relacionada con el mismo nombre de distribución no pueda producir un falso positivo.

Para verificar un artefacto de lanzamiento, instale la wheel en un entorno virtual limpio y ejecute python scripts/mcp_smoke.py. La prueba de humo cubre initialize, tools/list, las herramientas clave de solo lectura y el manejo de entradas no válidas. Las notas de la versión deben registrar la versión, el nombre del archivo de la wheel, el SHA-256, los cambios de esquema y las instrucciones de reversión. requirements-lock.txt se instala en CI antes de la compilación; pip check valida la coherencia y pip-audit es la puerta de seguridad de dependencias.