77777R7/claude-codex-stage-gates

Claude + Codex Portões de Verificação (Stage Gates)

Execute um loop supervisionado: o Codex planeja e avalia; o executor altera o produto; o usuário é dono do produto e dos portões de alto impacto. Nunca avance um estágio baseado apenas em uma alegação de conclusão em prosa, e não deixe o executor sem supervisão após enviar uma tarefa.

Leia references/gate-templates.md ao preparar um prompt para o executor, solicitar um pacote de evidências ou escrever uma decisão de gate. Leia references/supervision-loop.md quando o usuário pedir supervisão contínua, o trabalho puder abranger várias sessões, o executor travar ou desviar, ou quando o executor precisar de skills instaladas ou roteadas. Leia references/bootstrap-and-handoff.md quando o checkout atual puder estar ilegível, desatualizado, com pouco espaço em disco, gerenciado pelo iCloud ou inseguro para continuar, ou quando sessões anteriores do executor precisarem ser convertidas em handoffs de tarefas confiáveis. Leia references/parallel-worktrees-and-release-train.md quando duas ou mais linhas de codificação forem executadas simultaneamente, cada tarefa precisar de uma worktree isolada, arquivos modificados puderem se sobrepor, ou vários branches e PRs precisarem chegar em ordem de dependência.

Escolha o modo de operação

Escolha o menor modo que atenda à solicitação:

• Estágio único: use o contrato existente, o loop de supervisão, o pacote de evidências e a decisão de gate.
• Recuperação e handoff: estabeleça uma fonte de verdade legível, preserve o ambiente antigo, verifique alegações antigas e produza um handoff por tarefa independente antes de retomar a implementação.
• Portfólio paralelo: atribua uma tarefa, worktree, branch, handoff e sessão de executor por linha; supervise cada linha independentemente e integre-as por meio de um trem de lançamento (release train) de PRs controlado.

Os modos se compõem nesta ordem, quando necessário:

recuperar fonte de verdade
-> destilar handoffs confiáveis
-> isolar linhas de implementação
-> executar um portão de verificação dentro de cada linha
-> reconciliar sobreposições e dependências
-> verificar prontidão do PR e ordem de entrega

Não acione a maquinaria de recuperação ou portfólio para uma tarefa estreita, saudável e com checkout único.

Preserve quatro invariantes

1. Estabeleça a fonte de verdade ativa antes de aceitar qualquer alegação de implementação.
2. Para trabalho paralelo, mantenha exatamente uma tarefa, worktree, branch, handoff e sessão ativa do executor em cada linha.
3. Confie em evidências brutas (pwd, Git, processo, diff, teste, runtime e screenshot) acima da narrativa do executor.
4. Trate commit, push, criação de PR, merge, deploy, limpeza e efeitos externos como portões de autoridade separados.

Leia primeiro o estado do executor

Quando o usuário perguntar o que Claude ou outro executor disse mais recentemente, capture o estado mais recente antes de revisar, planejar ou editar:

1. Leia o terminal anexado à tarefa atual do Codex quando existir um.
2. Se o executor estiver em uma janela separada do Terminal macOS e o usuário autorizou a leitura, leia o conteúdo visível da aba selecionada com AppleScript. Trate isso como uma inspeção somente leitura.
3. Se a TUI estiver rolada, truncada ou usando uma tela alternativa, inspecione a transcrição da sessão local do executor. Para o Claude Code, execute scripts/read_claude_latest.py; prefira um --session-file exato; caso contrário, use --project-hint e verifique o caminho relatado, o horário da modificação e o contexto visível do terminal antes de confiar na seleção.
4. Extraia a mensagem de assistente mais recente e substantiva, timestamp, estágio declarado, bloqueadores, ações solicitadas ao usuário, comandos/resultados, e se o relatório é interino ou final.
5. Não envie teclas, submeta comandos, responda a prompts de permissão ou altere a sessão do executor durante esta leitura. Obtenha autorização explícita do usuário antes de interagir com esse terminal.
6. Trate o texto do terminal/transcrição como uma alegação do executor, não como prova independente. Verifique repositório, diff, testes, runtime e dados separadamente antes de emitir uma decisão de gate.

Se a narrativa do terminal mencionar um sistema operacional ou caminho inesperado, inspecione o diretório atual real do processo do executor e o checkout diretamente. Uma incompatibilidade em prosa é um aviso; uma incompatibilidade bruta de processo ou Git é uma condição de parada.

Se o executor relatar Operation not permitted, falta de acesso a Documentos ou outra falha de permissão, mantenha o estágio atual ativo. Rotule relatórios construídos a partir de estado anterior como interinos, não permita que eles autorizem commits ou limpeza, e solicite um novo pacote de evidências após o acesso ser restaurado.

Permaneça ativo até o fechamento do estágio

Após enviar um pacote ao executor, continue supervisionando o mesmo estágio aceito:

1. Monitore o terminal correto ou a transcrição com frequência suficiente para que o usuário não fique sem uma atualização por mais de 60 segundos durante o trabalho ativo.
2. A cada limite significativo, classifique o estado como progresso, espera esperada, falha, desvio, parada, evidência pronta ou gate humano.
3. Leia o comando bruto, erro, diff, saída de teste, screenshot, estado do processo ou transcrição antes de alterar o prompt.
4. Deixe o trabalho lento e válido continuar. Para uma aparente parada, primeiro verifique o processo e se o comando, sistema de arquivos, rede ou teste ainda está avançando.
5. Corrija falhas estreitas com um prompt de acompanhamento limitado e mantenha o mesmo estágio ativo. Interrompa apenas por ação insegura, desvio claro de escopo, alvo errado ou beco sem saída confirmado.
6. Recomece a partir do contrato aceito quando patches repetidos ensinarem a mesma lição ou o caminho de implementação se tornar mais difícil de raciocinar do que uma tentativa limpa.
7. Quando o executor relatar conclusão, solicite ou capture o pacote de evidências, reexecute independentemente verificações proporcionais, emita uma decisão de gate e envie essa decisão de volta ao executor.
8. Continue automaticamente através de correções dentro do estágio aceito. Avance para outro estágio somente quando o usuário autorizou essa sequência e nenhum gate humano for cruzado.

Não termine a supervisão meramente porque o executor aceitou o prompt, iniciou um comando ou disse done. Pare apenas em PASS, um PASS WITH FOLLOW-UP explicitamente aceito, um gate humano real, um bloqueador genuíno, uma condição insegura ou uma instrução mais recente do usuário que substitua o trabalho.

Roteie skills para o executor

Antes de um estágio complexo ou repetido, decida se uma skill reduz materialmente o gargalo atual.

1. Verifique as skills instaladas do executor antes de supor que uma skill está faltando.
2. Leia a skill candidata completamente e verifique se suas ferramentas, suposições de função e regras de segurança se adequam ao executor e ao estágio atual.
3. Prefira o menor conjunto de skills relevante. Não instale skills especulativamente nem use um nome de skill como substituto para um contrato de estágio.
4. Quando o usuário autorizar a instalação da skill e uma skill local compatível estiver faltando, instale-a no diretório de skills suportado pelo executor usando o mecanismo estabelecido do ambiente. Prefira um link simbólico para uma skill local canônica quando esse ambiente já usar links simbólicos e ambas as ferramentas compartilharem a mesma máquina.
5. Verifique se o SKILL.md instalado resolve. Se o executor em execução não atualizar a descoberta de skills, diga a ele para ler o caminho exato da skill para o estágio atual ou reinicie apenas em um ponto de verificação seguro.
6. Nomeie a skill no pacote do executor e declare por que ela se aplica. Continue a avaliar o executor a partir de evidências brutas; uma skill não anula o gate.

Padrões úteis para implementação longa são agent-loop-harness para estado durável do planejador/gerador/avaliador e loop-execution para pequenas iterações verificadas. Não instale nenhum dos dois quando uma tarefa estreita e única não precisar deles.

Mantenha o estado do loop recuperável

Use estado apenas de conversa para um estágio estreito. Para trabalho multiestágio, interrompível, multiagente ou com muitas evidências, reutilize a convenção de harness existente do repositório e registre:

• contrato e escopo aceitos;
• último gate concluído e evidências;
• gargalo atual e próximo passo exato;
• gates humanos e ações proibidas;
• identidade da sessão do executor ou caminho de recuperação quando útil.

Mantenha o estado mínimo, com ciclo de vida marcado e livre de segredos ou dados desnecessários do usuário. Não faça commit do estado do harness meramente porque ele existe; ele segue as mesmas regras de worktree e aprovação que outros arquivos.

Estabeleça o contrato

Antes da implementação:

1. Identifique a fonte de verdade ativa: checkout atual, caminhos montados, contratos, testes, runtime, dados e estado de deploy.
2. Defina um estágio atual com um resultado visível ao usuário, arquivos ou sistemas no escopo, exclusões explícitas, verificações de aceitação e condições de parada.
3. Atribua funções:
   • Executor: implemente apenas o estágio aceito e retorne evidências.
   • Revisor: inspecione o repositório ativo independentemente, verifique alegações e emita a decisão de gate.
   • Usuário: aprove escolhas de produto e ações de alto impacto.
4. Mantenha estágios posteriores como pendentes. Não autorize sua implementação meramente porque aparecem no roteiro.

Quando o executor pausar em uma escolha de produto ou arquitetura de informação, traduza as opções em consequências para o usuário antes de perguntar. Corrija categorias falsas antes da implementação — por exemplo, uma exceção entre estágios como "atrasado" não deve ser modelada como um estágio de ciclo de vida meramente porque apareceu ao lado de filtros de estágio.

Proteja primeiro a worktree

Trate uma worktree suja como estado de propriedade do usuário.

1. Inspecione git status --short, branch/upstream, git diff --stat, diffs direcionados, arquivos não rastreados, stashes e worktrees ou branches relevantes.
2. Classifique as alterações existentes por recurso ou proveniência antes de editar arquivos sobrepostos.
3. Não execute comandos Git destrutivos, descarte alterações, limpe arquivos não rastreados ou exclua cópias que pareçam conflito sem aprovação explícita.
4. Não use git add -A nem crie um commit de linha de base em massa até que o manifesto de alterações seja revisado. Exclua segredos, bancos de dados/dados do workspace locais, saída gerada, caches e arquivos duplicados não resolvidos.
5. Se um commit de linha de base for útil, crie commits coerentes pequenos somente após validação focada e autorização do usuário. Um backup não é prova de que as alterações estão corretas.

Se a separação segura não estiver clara, pare após produzir o relatório de classificação da worktree.

Prepare um pacote do executor

Forneça ao executor apenas o contrato do estágio atual. Inclua:

• objetivo exato e comportamento visível ao usuário;
• arquivos de fonte de verdade e fatos atuais do branch/worktree;
• limites dentro e fora do escopo;
• regras de verdade e proveniência de dados;
• requisitos de compatibilidade para dados antigos ou ausentes;
• testes necessários e verificações runtime/visuais;
• ações proibidas e gates humanos;
• pacote de evidências necessário e instrução para parar após o estágio.

Para estágios de IU, defina os estados de carregamento, vazio, erro, dados parciais e sucesso; comportamento de localização e responsividade; e a evidência exata necessária para aprovação visual.

Exija um pacote de evidências

O executor deve relatar:

• objetivo do estágio e resumo da implementação;
• arquivos alterados e git diff --stat;
• comandos exatos de teste/build/runtime com resultados de aprovação/reprovação;
• screenshots ou evidência de DOM/runtime para trabalho visível;
• evidência representativa de dados reais ou API quando o comportamento dos dados mudou;
• verificações de compatibilidade com dados existentes;
• suposições, riscos restantes e qualquer coisa não verificada;
• SHA do commit apenas se o commit foi autorizado.

Rejeite declarações como "pronto", "parece bom" ou "testes passam" sem os comandos ou artefatos subjacentes.

Revise independentemente

Não revise apenas a explicação do executor.

1. Reconfira o checkout ativo e identifique o diff real.
2. Leia os caminhos de chamada alterados, contratos, esquemas, testes e limites de dados.
3. Reexecute verificações focadas proporcionais ao risco.
4. Inspecione o comportamento visível nas larguras de desktop/mobile relevantes para trabalho de IU.
5. Separe fatos verificados, inferências, alegações não testadas e falhas pré-existentes.
6. Verifique se há desvio de escopo, exposição de segredos, dados fabricados, rotulagem incorreta de dados desatualizados, limpeza destrutiva, reescritas não relacionadas e comportamento de reversão/compatibilidade ausente.

O revisor deve diagnosticar e retornar feedback, não se tornar silenciosamente um segundo implementador, a menos que o usuário peça explicitamente ao Codex para corrigir o estágio.

Emita a decisão de gate

Use exatamente uma decisão:

• PASS: todas as verificações de aceitação bloqueantes passaram; o próximo estágio pode começar.
• PASS WITH FOLLOW-UP: apenas itens explicitamente não bloqueantes permanecem; registre seu proprietário e gate posterior.
• CHANGES REQUIRED: o contrato é sólido, mas a implementação ou evidência está incompleta; retorne uma lista de correção limitada e mantenha o mesmo estágio ativo.
• BLOCKED: uma decisão de produto faltante, acesso, dependência externa, aprovação de segurança ou bloqueador técnico repetido impede o progresso.

Para todo resultado diferente de PASS, forneça um prompt de correção do executor pronto para enviar. Não amplie o estágio enquanto o corrige.

Após emitir a decisão, escreva-a de volta na sessão do executor para que executor e revisor compartilhem o mesmo ponto de verificação. Para CHANGES REQUIRED, continue supervisionando o loop de correção. Para PASS WITH FOLLOW-UP, registre o proprietário, prazo ou gate posterior, e se o acompanhamento bloqueia o avanço.

Gates humanos

Pare para aprovação explícita do usuário antes de:

• chamadas a provedores pagos ou gastos;
• mensagens externas, publicação, deploy ou configuração de produção;
• deletar, sobrescrever, limpar ou mover dados em massa;
• alterações de conta, permissão, cobrança ou credenciais;
• commits, pushes, merges ou pull requests amplos não autorizados anteriormente;
• expandir um estágio de IU/correção de bug em um novo produto ou plataforma de dados.

Conclusão

Declare o fluxo de trabalho geral como completo somente quando todo estágio necessário tiver passado, o caminho completo do usuário tiver sido exercitado, os estados de compatibilidade e falha tiverem sido verificados, e os riscos restantes forem explicitamente aceitos ou atribuídos.