Codex Protocol Guardian

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 indicaciones de roles, no ejecuta tareas ni escribe estado en tiempo de ejecución. Valida evidencia de gobernanza y puede anexar archivos de hallazgos inmutables; nunca aprueba su propio trabajo. Los módulos heredados de roles, despacho y subagentes no están incluidos en la superficie del paquete.

Estructura

<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

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

Límite de superficie

El paquete de gobernanza no tiene una superficie de habilidades requerida o detectable. Los módulos heredados de roles, indicaciones, despacho y subagentes se eliminaron del paquete. El material de frontend, herramientas externas y novelas web es contenido de dominio opcional y no se carga en el contexto de gobernanza predeterminado. El código nuevo debe usar las funciones de gobernanza públicas que se enumeran a continuación.

El árbol de fuentes puede conservar documentos de habilidades 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 habilidades, roles e indicaciones 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ímites 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, una señal de revisión independiente, autoridad del candidato, descomposición, diseño de solución, alcance y evidencia de compuerta de convergencia. La evidencia de gobernanza faltante se bloquea; no hay derivación heredada.

• 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 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 digitales 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 principales.

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

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

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 en tiempo de ejecución. Su única operación de escritura es la operación explícita de artefacto de gobernanza append_finding_archive, que utiliza un resumen esperado y reemplazo atómico para evitar actualizaciones perdidas. La raíz del archivo se configura mediante AGENT_TEAM_MCP_ARCHIVE_ROOT, o por defecto a .codex/protocol/current/archives bajo el proyecto actual.

Comprobación de tiempo 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 empaquetado. 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 reemplazados, 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 digitales repetidas heredadas de una cadena de sucesores bloquean la aceptación hasta que exista evidencia de causa raíz.

10. Informe compuertas independientes para desviación de alcance, independencia de revisión, completitud de CI, cierre de trazabilidad, procedencia de artefactos y límite de aceptación de tiempo 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, descarte de revisiones obsoletas y política de cola de fusión.

11. Registre métricas de proceso por separado: tiempo en estado, iteraciones de revisión, recuento de reemplazados, tasa de rechazo, bloqueadores abiertos, tiempo de entrega, tasa de fallos 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, división de responsabilidades internas, dirección de dependencias, tráfico esperado, ordenamiento/idempotencia, contrapresión, manejo de fallos, escalado y 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 recuento 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 con 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 como evidencia únicamente. La aceptación final requiere revisión independiente, CI o aprobación explícita del usuario.

Configuración de MCP de Codex

Use 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 = "<checkout-root>/.venv/Scripts/python.exe"
args = ["-m", "agent_team_mcp.server"]

Verificar

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

La suite 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 resultado verde falso.