Hadur

Quando vários agentes de IA constroem, cada um, uma parte de um sistema a partir de planos separados, as partes tendem a divergir nos pontos de contato entre elas. Uma função muda de assinatura em um plano e seus chamadores não são atualizados, uma verificação de segurança é descrita e nunca aplicada, uma funcionalidade é construída e nunca conectada a nada. O Hadur confere planos e código a partir de um contrato comum e responde “terminamos?” com um veredito calculado, e não com uma impressão.

O Hadur é um conjunto de ferramentas em Python que transforma a metodologia Contract-First Multi-Plan Review (revisão de vários planos orientada por contrato) em comandos. A equipe escreve um contrato entre planos e um plano por módulo, e o Hadur conduz o ciclo de revisão que vem depois. Ele oferece:

• uma ferramenta de linha de comando, hadur, que abre rodadas de revisão, atribui cada lente a um revisor distinto, registra achados e calcula o veredito;
• um servidor MCP somente de leitura, com cinco ferramentas e três recursos, para que qualquer cliente MCP consulte um projeto;
• um plugin do Claude Code com seis agentes para os papéis da revisão e dois comandos, /hadur-convergence e /hadur-trends;
• sete auditorias estáticas que encontram problemas sem precisar de um revisor humano: descompasso entre a documentação e o código, segurança, infraestrutura, desempenho, acessibilidade, SEO e integração;
• resumos de passagem de sessão, gravados automaticamente antes de uma sessão do Claude Code ser compactada, para que uma sessão longa seja retomada sem perdas;
• uma interface web local e um painel estático.

A revisão alterna duas fases. Em uma rodada, cada revisor independente lê um plano e o contrato e relata achados classificados como Critical, Major ou Minor (crítico, importante ou menor). Em uma onda, agentes de correção resolvem os achados e um verificador separado confere cada correção. O ciclo se repete dentro de uma campanha, a unidade que termina em um veredito.

Cada revisor trabalha sob uma de treze lentes, perguntas fixas que cobrem consistência do contrato, persistência, segurança, qualidade dos testes, alcançabilidade e mais. A décima terceira é uma varredura livre e exige dois revisores distintos.

Uma campanha só converge quando cinco cláusulas se sustentam:

• uma rodada completa cobriu as treze lentes;
• toda lente teve ao menos um despacho limpo, isto é, uma execução de revisor sem nenhum achado Critical ou Major;
• todo achado Critical ou Major em aberto foi reverificado pela lente que o encontrou, em uma versão que contém a correção;
• uma varredura final das treze lentes sobre a versão que será entregue não encontra Critical nem Major;
• o veredito informa sua idade e itemiza cada exceção, como achados encerrados como wontfix.

Duas regras mantêm o ciclo honesto. A evidência nasce apenas dos comandos: achados nunca são editados à mão, porque o registro precisa ser carimbado pelos comandos que sabem qual lente produziu cada achado. E a metodologia exige um revisor adversário, o Breaker, em toda correção de um achado Critical; o Hadur pode impor isso com uma verificação opcional que recusa encerrar um Critical sem um ciclo do Breaker concluído. Nas cerca de 50 passagens do Breaker registradas no próprio projeto, toda primeira correção de um achado Critical foi contornada.

Os testes seguem o mesmo padrão. Um teste que nomeia um modo de falha precisa falhar quando esse defeito é reintroduzido de propósito, e o Hadur executa essas mutações em uma cópia isolada do repositório (um worktree do Git).

O Hadur funciona em dois modos. No modo de planos, o que se revisa é o conjunto de planos, antes de existir qualquer código. No modo de implementação, ele confere as evidências deixadas pela construção: cada afirmação aponta para um teste, e cada mutação registrada foi vista derrubando o seu teste.

O Hadur está em desenvolvimento inicial. A versão atual é a 0.1.0.dev0. Ela ainda não foi publicada no PyPI e é instalada a partir do código-fonte, com Python 3.11 ou superior. O Hadur é distribuído sob a licença MIT.

Serve a equipes cujo projeto se divide em três ou mais planos interdependentes, nas quais a divergência entre planos é o principal risco. Uma campanha completa não é barata: a metodologia estima de 40 a 70 despachos de revisores ao longo de duas a quatro semanas, e uma campanha ainda pode terminar sem convergir, caso em que o veredito nomeia as lentes que continuam com achados em aberto.

O Hadur também declara o seu limite. Ele verifica artefatos, não atenção: consegue mostrar que existem um revisor distinto e um briefing fixado, mas não que alguém leu o código.

O Hadur nasceu da experiência com o Empenho, um projeto SaaS de nove planos que foi de 318 achados Critical a nenhum, ao longo de mais de trinta ondas de correção. Depois foi aplicado a si mesmo: 44 rodadas de revisão em quatro meses produziram 576 achados. Uma auditoria desse registro levou à reescrita da regra de parada nas cláusulas de campanha descritas acima.

Uma análise de lacunas dividiu um conjunto planejado por público: a metade de engenharia foi entregue dentro do Hadur, como os domínios de auditoria, e a metade de comunicação com o negócio (controle de horas, relatórios para clientes e propostas comerciais) passou para o Pontifex, o conjunto de ferramentas de operação da Sigil Labs. O Pontifex lê os achados, as auditorias e o estado do Hadur em mão única, e o Hadur não depende dele.