Revisão de código das execuções de agentes

Com os worktrees Git ativados, o agente trabalha numa árvore de ficheiros e num ramo isolados. Os teus ficheiros atuais permanecem intactos e nada é integrado enquanto não aprovares.

A única exceção é o merge automático: se estiver ativado, o Singularity integra o resultado assim que a execução termina com sucesso. Desativa-o em Settings → Git → Worktrees para exigir uma revisão humana.

Abre o separador Review. A vista inicial lista as execuções terminadas que aguardam aprovação, com o agente, o ramo de origem e o ramo base, o número de projetos e de ficheiros, as adições e remoções, bem como a hora relativa.

Seleciona uma execução para abrir o seu separador review:<id>. O diff ocupa o centro; a lista de ficheiros, a discussão e as decisões permanecem reunidas no painel de revisão.

A secção Files apresenta cada ficheiro alterado e as suas estatísticas. Seleciona um para mostrar o seu conteúdo completo: as linhas adicionadas surgem a verde e as remoções a vermelho. Os blocos sem alterações podem ser recolhidos para manter a alteração legível.

Ativa Approve this file quando a alteração te parecer correta. O rodapé do painel acompanha o progresso com x/y approved. Um ficheiro marcado como “Approved — included in merge” fará parte da decisão final.

Usa File note para um comentário geral — arquitetura, um teste em falta ou uma convenção a respeitar. Para uma correção precisa, seleciona código, abre o menu de contexto e escolhe Add note to selection. Sem seleção, o Singularity pede-te primeiro que seleciones código.

As notas mostram o seu âmbito (FILE ou as linhas em causa), podem ser eliminadas e juntam-se ao feedback enviado ao agente quando escolhes Rerun with feedback. A área Discussion permite acrescentar uma mensagem mais geral.

O ficheiro apresentado é editável quando o Singularity registou o caminho físico do worktree. Altera o conteúdo e usa Cmd/Ctrl + S, ou o botão Save. Os estados Saving…, Saved e as notificações de falha confirmam o resultado.

Sem um caminho de worktree registado, o editor mostra Read only — no worktree path recorded. Continuas a poder ler e copiar o conteúdo, mas tens de relançar a execução num worktree corretamente registado para editar o ficheiro a partir da revisão.

• Approve and merge integra todos os ficheiros quando cada um deles está aprovado.
• Merge x/y faz um merge parcial apenas com os ficheiros aprovados; o botão permanece desativado enquanto nenhum ficheiro estiver aprovado.
• Reject recusa a revisão e marca a execução como rejeitada.
• Rerun with feedback devolve a tua mensagem e as tuas anotações ao agente; esta ação exige um feedback não vazio.

Um erro ao carregar o diff, ao guardar ou ao copiar é assinalado sem validar a ação silenciosamente: corrige a causa e tenta novamente.

A ausência de diff corresponde sempre a um estado explícito:

• O agente ainda está a trabalhar. Causa: o ticket continua em curso. Solução: acompanha o progresso no terminal; aparecerá após a chamada de fim de execução.
• Merge já feito. Causa: o merge automático estava ativado. Solução: inspeciona os commits em Graph; desativa o merge automático para as próximas missões.
• Execução direta — sem worktree. Causa: “Use Git worktrees” estava desativado e o agente escreveu na tua árvore de ficheiros. Solução: ativa os worktrees e desativa o merge automático em Settings → Git → Worktrees para as próximas execuções.
• O agente está à espera de uma resposta. Causa: uma pergunta bloqueia a missão. Solução: responde a partir do cartão do kanban; a revisão voltará depois de o agente retomar e terminar.
• O ticket não pode ser revisto. Causa: o seu estado ou os seus metadados não cumprem as condições de revisão. Solução: consulta o estado apresentado e relança uma execução até ao fim num worktree sem merge.

Se nenhuma execução corresponder, o separador mostra simplesmente “No agent work to review”.