Addon de AI Diff Reviewer

Todo Deep Work Plan termina da mesma forma: um Final Review obrigatório que lê o conjunto completo de alterações acumuladas do plano antes de o trabalho poder ser dado como concluído. O seu passe de segurança é o último ponto em que algo pode ser apanhado. Sem ajuda, o único leitor nesse momento é o mesmo agente que escreveu o código.

Este addon coloca um segundo leitor sobre esse diff. Liga o AI Diff Reviewer — listado no marketplace como “AI Diff Reviewer”, versão atual v3.3.16 — ao passe de segurança, onde devolve algo estruturado em vez de prosa: um veredicto, uma tabela de resultados e uma severidade para cada um. Desde a v3, um resultado critical significa que o verificador do addon o confirmou com uma segunda chamada ao modelo ancorada no código; apenas os críticos verificados bloqueiam a conclusão até serem corrigidos ou explicitamente aceites. A revisão é uma comporta, não um comentário.

Desde o padrão 2.3.0 essa revisão local faz parte da linha de base, não é um extra. A integração instala-a; cada Final Review executa-a. O que continua opcional é a superfície de CI — o Fluxo B, onde a mesma revisão controla os pull requests através da GitHub Action.

O limite que torna isto seguro de adotar é deliberadamente estrecho. O revisor é uma skill com licença MIT e fixada por tag, executada pelo agente de código que já utiliza, pelo que nenhum fluxo do Deep Work Plan depende de um serviço comercial, de um fornecedor de CI ou de um segredo. O Fluxo A (apenas local) é o que qualquer repositório integrado recebe; o Fluxo B é oferecido explicitamente e nunca instalado sem pedido. Quem desenvolve pode também recusar o revisor por completo — essa recusa fica registada como exceção declarada, e o verify reporta o repositório como não conforme nesse ponto até que seja instalado.

Quando usar

Dois fluxos de adoção

A deteção da revisão local requer skill + um ficheiro de extensão em um de: .review/extension.md, .github/ai-diff-reviewer/extension.md ou .github/ai-pr-reviewer/extension.md. A skill sozinha não é suficiente.

O que este addon liga (limitado por design)

O addon DWP não reinventa o revisor. Delega instalação, metodologia, o assistente de CI, autoria de extensões, redação de PRs e os ciclos de revisão pós-CI às seis sub-skills da skill upstream (fluxo pai predefinido, generate-extension, setup, open-pr, apply-review, address-review).

A revisão local obrigatória

O create adiciona o passo de revisão local ao passe de segurança de cada Final Review e o execute executa-o. A saída é adicionada sob ## AI Diff Reviewer local review no analysis_results/SECURITY_REVIEW.md local do plano (dentro da pasta própria do plano, nunca na raiz do repositório).

• Revisor em falta — registado, nunca omitido em silêncio: uma skill ou extensão em falta torna-se um resultado local reviewer not installed; o Final Review executa a passagem local quando a skill está presente e, caso contrário, leva o resultado para o relatório de conclusão — a instalação pertence ao consentimento do onboarding ou a uma invocação explícita do addon, nunca é um arranque surpresa.
• Falha suave (apenas invocação): uma revisão que conseguiu iniciar mas termina com erro → avisar uma vez, registar, continuar; nunca reprovar a tarefa por isso.
• Portão após uma passagem completa: os críticos verificados bloqueiam a conclusão do Final Review até serem corrigidos ou explicitamente aceites (BC-07). Afirmativas críticas não verificadas chegam como avisos anotados — visíveis, não bloqueantes, salvo se strict-unverified-criticals: true restaurar a filtragem por afirmativa. Uma revisão que esgotou o seu teto de turnos (incomplete) ou o seu relógio (timeout) não é uma passagem limpa sob rigor bloqueante (BC-04). warning / info são documentados mas não bloqueantes.
• O Fluxo A não precisa de segredo de CI. Uma chave de fornecedor não configurada não deve suprimir a passagem local.

Portão de CI do Fluxo B (opcional)

Action DailybotHQ/ai-diff-reviewer@v3, tipicamente bloqueada por etiqueta (ready), com um trabalho de nome estável AI review gate para proteção de ramos e etiqueta de omissão opcional skip-review-label: skip-ai-review. Desde a v3 o orçamento de revisão segue o nível de risco determinista da alteração — 8/20/30/40 turnos de low a critical sob budget-profile: auto (fixed restaura as constantes anteriores à v3 durante a transição) — e um push que não altera código executa uma ronda apenas do verificador. prompt.md partilhado + extensão alinham metodologia e severidade; local e CI permanecem idênticos em metodologia, enquanto rondas de CI 2+ podem ser mais curtas sob Revisão com Consciência de Iteração e a passagem local permanece completa.

Companheiros de revisão opcionais

Duas sub-skills invocáveis pelo programador fecham o ciclo depois de CI publicar uma revisão; nenhuma é ever um ficheiro de tarefa do plano (quebraria a ordem obrigatória de tarefas finais).

• apply-review percorre os resultados um a um (aplicar / adiar / ignorar) com consentimento. Apenas leitura por padrão; nunca faz commit nem push.
• address-review (novo na v3.1.1) é o ciclo de invocação única: encontra os PR abertos do ramo, verifica que a revisão cobre o head atual, apresenta os resultados com um plano de aplicar/adiar/ignorar e — com um único sim — aplica, faz commits em lotes pequenos de Conventional Commits, faz push e rearma o revisor da forma como o repo o dispara (bloqueio por etiqueta → alterna a etiqueta; disparo por push → confirma a nova execução). Ao contrário de apply-review, faz commit e push; esse é o propósito do ciclo. Em revisões agregadas de um ensemble lê o documento agregado e o marcador ai-pr-reviewer-aggregate.
• O caminho para máquinas é a saída estruturada, não o corpo da revisão: o documento review-output/3.0 (.aiprr/review-output.json, localizado através das saídas structured-output-path e structured-output-sha256) transporta o registo de execução, os resultados com evidência e verificação, os resultados refutados e a comporta. Um corpo de revisão que diz Recommendation: approve não é prova de que a verificação tenha passado — leia primeiro o bloco Highest severity / Strictness gate / Check status do marcador de acompanhamento.

O que mudou na v3

Três versões chegaram a 2026-09-24 (v3.0.0, v3.0.1, v3.1.0) e a v3.1.1 seguiu-se com a sub-skill address-review; as v3.2.0 e v3.2.2 (2026-09-26) tornaram depois esse ciclo consciente do CI e capaz de armar um PR em que o revisor nunca correu. Nenhuma altera a forma como este addon liga o revisor — o Fluxo A, os três caminhos de deteção e a escada de nunca bloquear mantêm-se —, mas mudam aquilo que quem adota recebe.

Dois destes importam mais do que os restantes para a metodologia.

A comporta de críticos verificados endurece o passe de segurança. Antes da v3, um modelo podia afirmar um critical livremente e a comporta seguia a afirmativa. Agora um resultado crítico num Final Review significa que uma segunda chamada ao modelo o confirmou contra o código, e a campanha da versão mediu a diferença: 771 execuções de avaliação pagas em dez campanhas por cerca de $83 no total, com o nível crítico a alcançar 63/63 de recall com precisão adjudicada de 1.0, e rondas incrementais a cortar os tokens de entrada entre 62 e 76 %. Estes números são medições publicadas pelo upstream, não do Deep Work Plan.

economy deliberadamente não é mais barato. O benchmark upstream de 2026-09-16 mediu grok-4.3 em 0 de 5 defeitos conhecidos — aprova sem rever — enquanto grok-4.5 igualou grok-4.6 com 3 de 5 e sem falsos positivos, ao mesmo custo e com um quarto do tempo. Como não existe nenhum modelo xAI mais barato que continue a rever, economy resolve para o mesmo modelo que balanced em vez de ser um nível que não encontra nada; no runner grok, o orçamento de turnos do nível de risco, e não a escolha do modelo, é o que escala o custo. Por isso o caminho xAI passa de cerca de $0.07 para cerca de $0.40–0.75 por revisão através da CLI; Desde o prompt v3.0, uma re-medição de 63 execuções levou o grok-4.3 de 0 de 5 a 83 % de recall sem falsos positivos e com ~31 % menos de custo — mas ainda falha ao escrever o seu ficheiro de resultados cerca de três vezes mais do que o grok-4.5, pelo que o grok-4.5 continua a ser o padrão e o model: grok-4.3 permanece uma escolha explícita de compromisso aceite. Estes números são medições publicadas pelo upstream, não do Deep Work Plan.

Comportamento

• O Fluxo A é a linha de base; o Fluxo B pergunta-se, nunca se assume. Instalar um fluxo sem pedido é uma pegada maior do que permanecer no Fluxo A.
• Reconciliar, não sobrescrever. Skill, extensão ou fluxo de revisão existentes são preservados; preencher apenas lacunas.
• Auth adiada. Os segredos do fornecedor para CI são configurados pelo mantenedor; este addon nunca armazena credenciais.
• Neutro em relação ao fornecedor. Nunca se exige um serviço comercial, um fornecedor de CI nem um segredo; a superfície de CI é a única peça que toca um fornecedor.

Notas

Revisão local obrigatória desde o padrão 2.3.0; superfície de CI opcional. Skill upstream: DailybotHQ/ai-diff-reviewer. Guia de migração upstream: docs/MIGRATION_v3.md. Página de spec: Add-ons.