77777R7/claude-codex-stage-gates

Claude + Codex Compuertas de Etapa (Stage Gates)

Ejecuta un bucle supervisado: Codex planifica y evalúa; el ejecutor modifica el producto; el usuario es dueño del producto y de las compuertas de alto impacto. Nunca avances una etapa basándote únicamente en una afirmación de finalización textual, y no dejes al ejecutor sin supervisión después de enviar una tarea.

Lee references/gate-templates.md al preparar un prompt para el ejecutor, solicitar un paquete de evidencia o escribir una decisión de compuerta.

Lee references/supervision-loop.md cuando el usuario solicite supervisión continua, el trabajo pueda abarcar varias sesiones, el ejecutor se detenga o desvíe, o el ejecutor necesite instalación o enrutamiento de habilidades.

Lee references/bootstrap-and-handoff.md cuando el checkout actual pueda ser ilegible, estar desactualizado, tener poco espacio en disco, estar gestionado por iCloud, o no sea seguro reanudarlo, o cuando las sesiones anteriores del ejecutor deban convertirse en transferencias de tarea fiables.

Lee references/parallel-worktrees-and-release-train.md cuando se ejecuten dos o más líneas de codificación concurrentemente, cada tarea necesite un worktree aislado, los archivos modificados puedan solaparse, o varias ramas y PRs deban integrarse en orden de dependencia.

Elige el modo de operación

Elige el modo más pequeño que cubra la solicitud:

• Etapa única: usa el contrato existente, el bucle de supervisión, el paquete de evidencia y la decisión de compuerta.
• Recuperación y transferencia: establece una fuente de verdad legible, conserva el entorno anterior, verifica afirmaciones previas y produce una transferencia por tarea independiente antes de reanudar la implementación.
• Portafolio paralelo: asigna una tarea, un worktree, una rama, una transferencia y una sesión de ejecutor por línea; supervisa cada línea de forma independiente e intégralas mediante un tren de lanzamiento de PR controlado.

Los modos se componen en este orden cuando sea necesario:

recuperar fuente de verdad
-> destilar transferencias fiables
-> aislar líneas de implementación
-> ejecutar una compuerta de etapa dentro de cada línea
-> reconciliar solapamientos y dependencias
-> verificar preparación de PR y orden de integración

No invoques la maquinaria de recuperación o portafolio para una tarea estrecha, saludable y de un solo checkout.

Preserva cuatro invariantes

1. Establece la fuente de verdad en vivo antes de aceptar cualquier afirmación de implementación.
2. Para trabajo paralelo, mantén exactamente una tarea, un worktree, una rama, una transferencia y una sesión de ejecutor activa en cada línea.
3. Confía en evidencia bruta de pwd, Git, procesos, diff, tests, tiempo de ejecución y capturas de pantalla por encima de la narración del ejecutor.
4. Trata las acciones de commit, push, creación de PR, merge, despliegue, limpieza y efectos externos como compuertas de autoridad separadas.

Lee primero el estado del ejecutor

Cuando el usuario pregunte qué dijo Claude u otro ejecutor más recientemente, captura el último estado antes de revisar, planificar o editar:

1. Lee la terminal adjunta a la tarea actual de Codex cuando exista.
2. Si el ejecutor se ejecuta en una ventana separada de Terminal de macOS y el usuario autorizó su lectura, lee el contenido visible de la pestaña seleccionada con AppleScript. Trata esto como una inspección de solo lectura.
3. Si la TUI está desplazada, truncada o usa una pantalla alternativa, inspecciona la transcripción de la sesión local del ejecutor. Para Claude Code, ejecuta scripts/read_claude_latest.py; prefiere un --session-file exacto; de lo contrario, usa --project-hint y verifica la ruta reportada, la hora de modificación y el contexto visible de la terminal antes de confiar en la selección.
4. Extrae el último mensaje de asistente sustantivo, la marca de tiempo, la etapa declarada, los bloqueadores, las acciones solicitadas al usuario, los comandos/resultados y si el informe es provisional o final.
5. No envíes pulsaciones de teclas, envíes comandos, respondas a permisos ni modifiques la sesión del ejecutor mientras realizas esta lectura. Obtén autorización explícita del usuario antes de interactuar con esa terminal.
6. Trata el texto de la terminal/transcripción como una afirmación del ejecutor, no como prueba independiente. Verifica el repositorio, diff, pruebas, tiempo de ejecución y datos por separado antes de emitir una decisión de compuerta.

Si la narración de la terminal menciona un sistema operativo o ruta inesperados, inspecciona el directorio actual real del proceso del ejecutor y el checkout directamente. Una discrepancia textual es una advertencia; una discrepancia en el proceso crudo o Git es una condición de parada.

Si el ejecutor reporta Operation not permitted, falta de acceso a Documentos u otro fallo de permiso, mantén la etapa actual activa. Etiqueta los informes construidos a partir de estado anterior como provisionales, no permitas que autoricen commits o limpieza, y solicita un nuevo paquete de evidencia después de que se restaure el acceso.

Mantente activo hasta que la etapa se cierre

Después de enviar un paquete al ejecutor, continúa supervisando la misma etapa aceptada:

1. Sondea la terminal o transcripción correcta con la frecuencia suficiente para que el usuario no esté sin actualización por más de 60 segundos durante el trabajo activo.
2. En cada límite significativo, clasifica el estado como progreso, espera esperada, fallo, desviación, estancamiento, evidencia lista o compuerta humana.
3. Lee el comando crudo, error, diff, salida de prueba, captura de pantalla, estado del proceso o transcripción antes de cambiar el prompt.
4. Deja que el trabajo lento válido continúe. Ante un aparente estancamiento, verifica primero el proceso y si el comando, sistema de archivos, red o prueba aún avanzan.
5. Corrige fallos estrechos con un prompt de seguimiento acotado y mantén la misma etapa activa. Interrumpe solo por acción insegura, desviación clara del alcance, objetivo incorrecto o punto muerto confirmado.
6. Reinicia desde el contrato aceptado cuando parches repetidos enseñen la misma lección o la ruta de implementación se vuelva más difícil de razonar que un intento limpio.
7. Cuando el ejecutor reporte finalización, solicita o captura el paquete de evidencia, vuelve a ejecutar de forma independiente las comprobaciones proporcionales, emite una decisión de compuerta y envía esa decisión de vuelta al ejecutor.
8. Continúa automáticamente a través de correcciones dentro de la etapa aceptada. Avanza a otra etapa solo cuando el usuario haya autorizado esa secuencia y no se haya cruzado ninguna compuerta humana.

No termines la supervisión solo porque el ejecutor aceptó el prompt, inició un comando o dijo done. Detente solo en PASS, un PASS WITH FOLLOW-UP explícitamente aceptado, una compuerta humana real, un bloqueador genuino, una condición insegura o una instrucción de usuario más reciente que reemplace el trabajo.

Enruta habilidades al ejecutor

Antes de una etapa compleja o repetida, decide si una habilidad reduce materialmente el cuello de botella actual.

1. Verifica las habilidades instaladas del ejecutor antes de asumir que falta una habilidad.
2. Lee la habilidad candidata completamente y verifica que sus herramientas, suposiciones de rol y reglas de seguridad se ajusten al ejecutor y a la etapa actual.
3. Prefiere el conjunto de habilidades relevante más pequeño. No instales habilidades especulativamente ni uses un nombre de habilidad como sustituto de un contrato de etapa.
4. Cuando el usuario haya autorizado la instalación de habilidades y falte una habilidad local compatible, instálala en el directorio de habilidades compatible del ejecutor utilizando el mecanismo establecido del entorno. Prefiere un enlace simbólico a una habilidad local canónica cuando ese entorno ya use enlaces simbólicos y ambas herramientas compartan la misma máquina.
5. Verifica que el SKILL.md instalado se resuelva. Si el ejecutor en ejecución no actualiza el descubrimiento de habilidades, indícale que lea la ruta exacta de la habilidad para la etapa actual o reinicia solo en un punto de control seguro.
6. Nombra la habilidad en el paquete del ejecutor y explica por qué aplica. Continúa evaluando al ejecutor a partir de evidencia bruta; una habilidad no anula la compuerta.

Los valores predeterminados útiles para implementaciones largas son agent-loop-harness para estado duradero de planificador/generador/evaluador y loop-execution para iteraciones pequeñas verificadas. No instales ninguno cuando una tarea estrecha de una sola vez no los necesite.

Mantén el estado del bucle recuperable

Usa estado solo de conversación para una etapa estrecha. Para trabajo de múltiples etapas, interrumpible, multiagente o con mucha evidencia, reutiliza la convención de harness existente del repositorio y registra:

• contrato aceptado y alcance;
• última compuerta completada y evidencia;
• cuello de botella actual y siguiente paso exacto;
• compuertas humanas y acciones prohibidas;
• identidad de la sesión del ejecutor o ruta de recuperación cuando sea útil.

Mantén el estado mínimo, marcado con ciclo de vida y libre de secretos o datos de usuario innecesarios. No confirmes el estado del harness solo porque existe; sigue las mismas reglas de worktree y aprobación que otros archivos.

Establece el contrato

Antes de la implementación:

1. Identifica la fuente de verdad en vivo: checkout actual, rutas montadas, contratos, pruebas, tiempo de ejecución, datos y estado de despliegue.
2. Define una etapa actual con un resultado visible para el usuario, archivos o sistemas dentro del alcance, exclusiones explícitas, comprobaciones de aceptación y condiciones de parada.
3. Asigna roles:
   • Ejecutor: implementa solo la etapa aceptada y devuelve evidencia.
   • Revisor: inspecciona el repositorio en vivo de forma independiente, verifica afirmaciones y emite la decisión de compuerta.
   • Usuario: aprueba elecciones de producto y acciones de alto impacto.
4. Mantén las etapas posteriores como pendientes. No autorices su implementación solo porque aparecen en la hoja de ruta.

Cuando el ejecutor se detenga en una elección de producto o arquitectura de información, traduce las opciones en consecuencias para el usuario antes de preguntar al usuario. Corrige categorías falsas antes de la implementación; por ejemplo, una excepción entre etapas como “atrasado” no debe modelarse como una etapa del ciclo de vida solo porque apareció junto a filtros de etapa.

Protege primero el worktree

Trata un worktree sucio como estado perteneciente al usuario.

1. Inspecciona git status --short, rama/upstream, git diff --stat, diffs específicos, archivos no rastreados, stashes y worktrees o ramas relevantes.
2. Clasifica los cambios existentes por característica o procedencia antes de editar archivos superpuestos.
3. No ejecutes comandos destructivos de Git, descartes cambios, limpies archivos no rastreados ni elimines copias que parezcan conflictos sin aprobación explícita.
4. No uses git add -A ni crees un commit de línea base masivo hasta que se revise el manifiesto de cambios. Excluye secretos, bases de datos/datos de workspace locales, salida generada, cachés y archivos duplicados no resueltos.
5. Si un commit de línea base es útil, crea pequeños commits coherentes solo después de una validación enfocada y autorización del usuario. Una copia de seguridad no es prueba de que los cambios sean correctos.

Si la separación segura no está clara, detente después de producir el informe de clasificación del worktree.

Prepara un paquete para el ejecutor

Dale al ejecutor solo el contrato de la etapa actual. Incluye:

• objetivo exacto y comportamiento visible para el usuario;
• archivos fuente de verdad y hechos actuales de rama/worktree;
• límites dentro y fuera del alcance;
• reglas de veracidad y procedencia de datos;
• requisitos de compatibilidad para datos antiguos o faltantes;
• pruebas requeridas y comprobaciones de tiempo de ejecución/visuales;
• acciones prohibidas y compuertas humanas;
• paquete de evidencia requerido e instrucción de detenerse después de la etapa.

Para etapas de UI, define los estados de carga, vacío, error, datos parciales y éxito; comportamiento de localización y respuesta; y la evidencia exacta necesaria para la aprobación visual.

Exige un paquete de evidencia

El ejecutor debe reportar:

• objetivo de la etapa y resumen de implementación;
• archivos modificados y git diff --stat;
• comandos exactos de prueba/construcción/ejecución con resultados de éxito/fallo;
• capturas de pantalla o evidencia de DOM/tiempo de ejecución para trabajo visible;
• evidencia representativa de datos reales o API cuando el comportamiento de los datos haya cambiado;
• comprobaciones de compatibilidad para datos existentes;
• suposiciones, riesgos restantes y cualquier cosa no verificada;
• SHA del commit solo si se autorizó confirmar.

Rechaza afirmaciones como “hecho”, “se ve bien” o “pruebas pasan” sin los comandos o artefactos subyacentes.

Revisa de forma independiente

No revises solo la explicación del ejecutor.

1. Vuelve a verificar el checkout en vivo e identifica el diff real.
2. Lee las rutas de llamada, contratos, esquemas, pruebas y límites de datos cambiados.
3. Vuelve a ejecutar comprobaciones enfocadas proporcionales al riesgo.
4. Inspecciona el comportamiento visible en los anchos de escritorio/móvil relevantes para trabajo de UI.
5. Separa hechos verificados, inferencias, afirmaciones no probadas y fallos preexistentes.
6. Verifica desviación de alcance, exposición de secretos, datos fabricados, etiquetado incorrecto de datos obsoletos, limpieza destructiva, reescrituras no relacionadas y falta de comportamiento de reversión/compatibilidad.

El revisor debe diagnosticar y devolver comentarios, no convertirse silenciosamente en un segundo implementador, a menos que el usuario pida explícitamente a Codex que parchee la etapa.

Emite la decisión de compuerta

Usa exactamente una decisión:

• PASS: todas las comprobaciones de aceptación críticas pasaron; la siguiente etapa puede comenzar.
• PASS WITH FOLLOW-UP: solo quedan elementos explícitamente no bloqueantes; registra su propietario y compuerta posterior.
• CHANGES REQUIRED: el contrato es sólido pero la implementación o evidencia está incompleta; devuelve una lista de corrección acotada y mantén la misma etapa activa.
• BLOCKED: falta una decisión de producto, acceso, dependencia externa, aprobación de seguridad o bloqueador técnico repetido que impide el progreso.

Para cada resultado que no sea PASS, proporciona un prompt de corrección listo para enviar al ejecutor. No amplíes la etapa mientras la corriges.

Después de emitir la decisión, escríbela de vuelta a la sesión del ejecutor para que el ejecutor y el revisor compartan el mismo punto de control. Para CHANGES REQUIRED, continúa supervisando el bucle de corrección. Para PASS WITH FOLLOW-UP, registra el propietario, la fecha límite o compuerta posterior, y si el seguimiento bloquea el avance.

Compuertas humanas

Detente para obtener aprobación explícita del usuario antes de:

• llamadas a proveedores de pago o gastos;
• mensajes externos, publicación, despliegue o configuración de producción;
• eliminar, sobrescribir, limpiar o mover datos masivamente;
• cambios de cuenta, permisos, facturación o credenciales;
• commits, pushes, merges o pull requests amplios no autorizados previamente;
• expandir una etapa de UI/corrección de errores en un nuevo producto o plataforma de datos.

Finalización

Declara el flujo de trabajo general como completo solo cuando cada etapa requerida haya pasado, la ruta de usuario de extremo a extremo se haya ejercitado, los estados de compatibilidad y fallo se hayan verificado, y los riesgos restantes se hayan aceptado o asignado explícitamente.