Gate e Central de Governança

O contrato de qualidade diz o que a equipe exige. O gate faz com que seja cumprido. Ele é um único comando do motor, usado da mesma forma pelos hooks do Git, pela CI, pelo comando yuli-mcp gate e pelos hooks dos agentes. O resultado não depende de quem o invoca.

O comando

agent-engine gate --project <raíz> --stage pre-commit|commit-msg|pre-push|ci \
  [--message-file <archivo>] [--base <revisión>] [--format text|json]

Se você omitir --project, é usada a pasta atual. Uma pasta sem Git sempre passa.

O que cada etapa verifica

Os controles

Antitrapaça nos testes

Um agente pressionado para terminar pode “consertar” um teste em vez do código. O Yuli detecta isso.

Nos testes:

• Asserções removidas ou testes apagados.
• Testes pulados: @Disabled, @Ignore, .skip(, xit, #[ignore], skips do pytest ou do unittest, t.Skip.
• Asserções triviais, como assertTrue(true) ou expect(true).toBe(true).
• Valores esperados alterados para que o teste passe.
• catch que captura tudo dentro de um teste.

No build e na CI:

• Cobertura mínima reduzida.
• Testes pulados no build.
• Falhas ignoradas, como npm test || true.
• Script de testes substituído por um vazio.
• Gate de qualidade desativado ou tarefa de testes desabilitada.

Rede de segurança

Se arquivos de código existentes mudarem sem testes de caracterização ou unitários, o gate avisa: a alteração deve preservar o comportamento. Ele nunca bloqueia o commit.

Instalar os hooks do Git

Na Central de Governança, aba Portões, clique em Instalar hooks.

1. O Yuli escreve .githooks/pre-commit, .githooks/commit-msg e .githooks/pre-push.
2. Configura git config --local core.hooksPath .githooks.

Desinstalar hooks remove a configuração e apaga apenas os scripts do Yuli.

Na CI

Os pipelines gerados por Criar CI incluem a etapa “Portões do contrato”, que executa agent-engine gate --stage ci. Assim, a CI aplica as mesmas regras que a sua equipe local.

A Central de Governança

Abra-a pelo trilho direito (Mais ferramentas → Central de Governança) ou pela paleta de comandos: Abrir a Central de Governança. Ela tem 10 abas.

Documentos que ela gera

DORA

A aba Entrega calcula as quatro métricas DORA: frequência de deploy, lead time, taxa de falhas em alterações e MTTR, com as faixas Elite, Alta, Média e Baixa. Ela usa os deploys registrados ou a CI. O Yuli não enxerga um APM de produção.

Revisão independente

Um modelo de outra família revisa a alteração. Nunca é usada a mesma família do modelo que a escreveu. Se nenhum estiver configurado, ela é indicada como indisponível. É obrigatória nos perfis Regulada e Segurança crítica.

Contexto para todos os agentes

Em Agentes → Contexto, a seção “Contexto para todos os agentes” escreve as mesmas regras para cada ferramenta:

O conteúdo vai em um bloco gerenciado; o que você escrever fora dele é respeitado. Por padrão, os arquivos ficam fora do Git; ative isso com Versionar no Git. Cada destino mostra o seu estado: Atualizado, Desatualizado, Não existe ou Editado manualmente.

Regras aprendidas

Quando um mesmo achado aparece 3 vezes ou mais em pelo menos 2 tarefas dentro de 30 dias, ele se torna uma regra em .ai/rules/learned.md. Você pode rejeitá-la em Agentes → Aprendizado; ela só volta a ser proposta se a sua evidência dobrar.

Limites honestos

• DAST (OWASP ZAP), a varredura de contêineres (Trivy ou Grype) e a assinatura (cosign) só são executados se estiverem instalados, e sempre com confirmação. Se faltarem, o Yuli informa e não simula o resultado.
• As regras preventivas e as de IaC são padrões sobre o texto. Cada achado traz o seu arquivo e a sua linha para que uma pessoa o confirme.