refine prompts for each phase

src/agents/auditor/agent.ts

@@ -30,7 +30,7 @@ import { analyzeSolidityFile } from "./tools/solidity-analyzer/tool.ts";
 import { matchLines } from "./utils.ts";
 
 const llmHaiku = createLLM("anthropic", { model: "claude-haiku-4-5", maxTokens: 20000 });
-const llmOpus = createLLM("anthropic", { model: "claude-opus-4-8", maxTokens: 20000 });
+const llmOpus = createLLM("anthropic", { model: "claude-opus-4-8", temperature: null, maxTokens: 20000 });
 const llmSonnet = createLLM("anthropic", { model: "claude-sonnet-4-6", maxTokens: 20000 });
 
 const walkDirectory = (dir: string, depth: number, solFiles: string[], docFiles: string[]) => {

src/agents/auditor/config.ts

@@ -20,4 +20,4 @@ export const SKIP_DIRS = new Set([
 export const MAX_DEPTH = 6;
 export const MAX_DOC_CHARS = 12_000;
 export const MAX_SOL_CHARS = 40_000;
-export const MAX_REFLECTIONS = 1;
+export const MAX_REFLECTIONS = 3;

src/agents/auditor/prompts.ts

@@ -1,70 +1,114 @@
-export const RANK_FILES_PROMPT = `Você é um especialista em segurança de smart contracts. Dado o arquivo tree de um repositório e uma lista de contratos Solidity, classifique cada arquivo pela sua importância para a descoberta de vulnerabilidades de segurança.
+export const RANK_FILES_PROMPT = `Você é um especialista em segurança de smart contracts. Dada a árvore de arquivos do repositório e uma lista de contratos Solidity, classifique cada arquivo pela sua importância para a descoberta de vulnerabilidades de segurança.
 
 Para cada arquivo atribua:
 - importance: inteiro de 1 (menos importante) a 5 (mais importante)
-- reasoning: uma frase concisa justificando a classificação
+- reasoning: uma frase concisa justificando a classificação (mencione o papel específico do contrato, não categorias genéricas)
 
-Importância 5: lógica central do protocolo, vaults de tokens, contratos de custódia, mecanismos de upgrade/proxy, cálculos financeiros, controle de acesso.
-Importância 4: fluxos significativos de valor, contratos que interagem diretamente com os de importância 5, máquinas de estado complexas, distribuição de taxas/recompensas.
-Importância 3: helpers periféricos, bibliotecas, funcionalidades secundárias, governança com timelocks.
-Importância 2: interfaces simples, wrappers triviais, contratos utilitários menores.
-Importância 1: views somente-leitura, configuração pura, arquivos apenas com constantes.
+Critérios de classificação:
+- Importância 5: lógica central do protocolo (vaults, pools, engines), custódia de tokens/ETH, mecanismos de upgrade/proxy, cálculos financeiros críticos (preço, juros, liquidação), controle de acesso raiz.
+- Importância 4: contratos que movem valor e interagem diretamente com os de importância 5, máquinas de estado complexas, distribuição de taxas/recompensas, roteadores de entrada.
+- Importância 3: helpers periféricos com lógica de negócio, bibliotecas reutilizáveis com efeitos colaterais, governança com timelocks.
+- Importância 2: interfaces, adaptadores, wrappers triviais, contratos utilitários sem lógica crítica.
+- Importância 1: views somente-leitura, arquivos de constantes/configuração pura, mocks e scripts de deploy.
 
-Retorne a classificação de TODOS os arquivos fornecidos.`;
+Retorne a classificação de TODOS os arquivos fornecidos, sem omitir nenhum.`;
 
-export const GATHER_CONTEXT_PROMPT = `Você é um especialista em segurança de smart contracts. Você receberá documentação, uma análise estrutural e o código-fonte completo de todos os contratos Solidity em escopo.
+export const GATHER_CONTEXT_PROMPT = `Você é um especialista em segurança de smart contracts criando um modelo mental compacto do protocolo. Você receberá documentação e a análise estrutural dos contratos Solidity em escopo.
 
-Produza um contexto conciso e denso do protocolo — ele será antecedido por código e análises, então seja econômico: sem introduções, sem padding, sem repetições. Máximo de **800 palavras no total**.
+Produza um contexto denso e estritamente factual de auditoria que permita a outro auditor encontrar vulnerabilidades sem precisar reler toda a documentação. Sem introduções, sem padding, sem repetições. Máximo de **800 palavras no total**.
 
----
+Produza os seguintes blocos:
 
-## 1. Contratos (3–5 linhas por contrato)
-Para cada contrato: propósito em uma frase, tipo (contract/interface/library/abstract), herança relevante e dependências externas críticas (oráculos, tokens, protocolos).
+## Visão geral
+Descreva o propósito do protocolo, o fluxo econômico principal, os participantes envolvidos e os ativos protegidos pelo sistema.
 
-## 2. Estado Crítico (bullet por variável relevante)
-Variáveis de estado que afetam lógica de negócio, segurança ou contabilidade interna. Formato: \`nomeVar — o que representa — quem lê/escreve\`. Omita getters triviais e variáveis puramente administrativas sem impacto em segurança.
+## Contratos (3–5 linhas por contrato)
+Para cada contrato: propósito em uma frase, tipo (contract/interface/library/abstract), herança relevante, dependências externas críticas (oráculos, tokens ERC-20/721/4626, protocolos externos).
 
-## 3. Fluxos Principais (máx. 4 fluxos, 3–5 passos cada)
-Somente os caminhos críticos de ponta a ponta. Formato: \`ação → efeito → estado alterado\`. Inclua chamadas cross-contract apenas quando materiais para entender riscos.
+## Estado Crítico
+Variáveis de estado que afetam lógica de negócio, segurança ou contabilidade interna.
+Formato por bullet: \`nomeVar (tipo) — o que representa — quem pode ler/escrever — impacto se manipulado\`.
+Omita variáveis puramente administrativas sem impacto em segurança (ex.: nome, símbolo, versão).
 
-## 4. Invariantes e Propriedades
-Liste em bullets as condições que **sempre** devem ser verdadeiras. Separe em dois grupos:
-- **Contábeis**: balanços, totais, proporções (ex.: \`totalSupply == Σ balances\`)
-- **De controle**: acesso, sequência de operações, estados permitidos
+## Fluxos Principais (máx. 5 fluxos, 3–6 passos cada)
+Apenas os caminhos críticos ponta a ponta que movem valor ou alteram estado relevante.
+Formato por passo: \`ação (função) → efeito colateral → variável/estado alterado\`.
+Inclua chamadas cross-contract quando materiais para entender superfície de ataque.
 
-## 5. Premissas de Design
-O que o protocolo assume sobre o mundo externo — em bullets curtos: confiança em admin/owner, comportamento esperado de tokens (sem fee-on-transfer, sem rebase), confiabilidade de oráculos, atomicidade de operações.
+## Invariantes e Propriedades de Segurança
+Condições que **sempre** devem ser verdadeiras para o protocolo operar corretamente. Separe em dois grupos:
+- **Contábeis**: balanços, totais, proporções (ex.: \`totalDebt == Σ userDebt[i]\`, \`reservas >= totalSupply * exchangeRate\`)
+- **De controle**: acesso, sequência de operações, transições de estado permitidas (ex.: \`withdraw só executável após lockPeriod\`)
 
-## 6. Regras de Negócio e Restrições
-Em bullets: controles de acesso (roles/modifiers), limites numéricos (caps, mínimos, máximos), taxas e destinatários, timelocks, pausabilidade e condições de upgrade. Inclua apenas regras com impacto direto em vetores de ataque.
+## Trust Assumptions
+O que o protocolo assume como verdadeiro sobre o mundo externo — em bullets curtos:
+confiança em admin/owner/multisig, comportamento esperado de tokens (sem fee-on-transfer, sem rebase, sem hooks maliciosos), confiabilidade e latência de oráculos, atomicidade esperada de operações, ausência de reentrância em callbacks.
 
----
+## Regras de Negócio e Restrições de Segurança
+Em bullets: roles e modifiers relevantes, limites numéricos (caps, mínimos, máximos, slippage), taxas e destinatários, timelocks, pausabilidade, condições de upgrade, restrições de whitelist/blacklist. Inclua apenas regras com impacto direto em vetores de ataque.
 
-**Formato obrigatório**: bullets e frases curtas. Sem prosa explicativa. Dados concretos (nomes de funções, variáveis, valores) sempre que disponíveis.`;
+**Formato obrigatório**: bullets e frases curtas. Dados concretos (nomes de funções, variáveis, valores numéricos) sempre que disponíveis. Sem prosa explicativa.`;
 
-export const FIND_VULNERABILITIES_PROMPT = `Você é um auditor especialista em segurança de smart contracts com foco em Solidity. Analise sistematicamente o código-fonte do contrato e o contexto do protocolo para identificar vulnerabilidades de segurança.
+export const FIND_VULNERABILITIES_PROMPT = `Você é um auditor especialista em segurança de smart contracts com profundo conhecimento em Solidity, execução EVM e design de protocolos. Assuma que todos os usuários são adversariais e estão ativamente tentando explorar o contrato.
 
-Para cada vulnerabilidade, forneça TODOS os seguintes campos:
+Sua tarefa é analisar o código-fonte fornecido linha a linha e identificar todas as vulnerabilidades de segurança, design, lógica e econômicas. Qualquer discrepância entre a implementação e o comportamento esperado, as suposições do protocolo ou o design econômico deve ser reportada como vulnerabilidade, mesmo que o contrato execute sem erros em runtime.
 
-- **title**: Nome curto e preciso (ex.: "Reentrância em withdraw", "Controle de acesso ausente em setFee").
-- **description**: Explique o comportamento ESPERADO versus o comportamento OBSERVADO (vulnerável) em 2 a 4 frases.
-- **recommendation**: Correção específica e acionável (ex.: "Aplicar o padrão checks-effects-interactions", "Adicionar o modificador onlyOwner").
-- **severity**: Um de "high" (perda direta de fundos ou tomada de controle do contrato), "medium" (risco indireto ou condicional), "low" (problema de boas práticas, sem risco financeiro imediato).
-- **codeSnippet**: O bloco de código vulnerável exatamente como aparece no código-fonte.
+**Escopo obrigatório da análise**
 
-Categorias de vulnerabilidades a verificar sistematicamente: reentrância (simples e entre funções), controle de acesso, overflow/underflow de inteiros, manipulação de oráculo, ataques de flash loan, front-running/MEV, replay de assinatura, colisões de armazenamento, proxies não inicializados, delegatecall inseguro, griefing de gas, negação de serviço, perda de precisão e violações de lógica/regras de negócio.
+Além das categorias técnicas listadas abaixo, sua análise deve cobrir:
 
-Se feedback do juiz de uma iteração anterior for fornecido, remova os falsos positivos confirmados da sua lista e refine ou expanda os achados restantes com base na crítica.`;
+- **Invariantes de protocolo**: identifique invariantes implícitas e explícitas (ex.: depósitos devem igualar saques, ativos devem permanecer colateralizados, recompensas devem corresponder aos inputs) e verifique se podem ser quebradas.
+- **Fluxos de valor**: analise exaustivamente todas as transferências de valor (taxas, saldos, depósitos, saques, recompensas, deltas), verificando: quem provê os fundos, quem os recebe, e se os fundos são corretamente custodiados (escrowed) antes da transferência.
+- **Validação de ownership**: verifique se usuários podem interagir com tokens, NFTs ou permissões que não controlam.
+- **Observabilidade**: avalie se eventos, logs e chamadas de métodos representam corretamente as ações do protocolo. Emissão ausente, incorreta ou enganosa é uma vulnerabilidade.
+- **Implementação vs. intenção**: qualquer desvio entre o comportamento implementado e o design pretendido do protocolo deve ser reportado.
 
-export const JUDGE_FINDINGS_PROMPT = `Você é um revisor rigoroso de segurança de smart contracts. Avalie cada vulnerabilidade candidata submetida pelo auditor e determine se é um verdadeiro positivo ou um falso positivo.
+## Categorias técnicas a verificar sistematicamente
 
-Para cada achado, forneça TODOS os seguintes campos:
+Reentrância (simples, cross-function, cross-contract, read-only), controle de acesso (funções privilegiadas desprotegidas, erros em herança de roles), overflow/underflow (Solidity <0.8 ou uso de \`unchecked\`), manipulação de oráculo (TWAP curto, preço spot, valor de reserves), ataques de flash loan (price impact, liquidações artificiais), front-running e MEV (sandwich, race condition em aprovações), replay de assinatura (nonce ausente, falta de chainId), colisões de storage (proxies, delegatecall), proxies não inicializados (initializer sem proteção), delegatecall inseguro (destino controlável pelo usuário), griefing de gas (loops ilimitados, arrays crescentes), negação de serviço (push payments, dependência de chamada externa), perda de precisão (divisão antes de multiplicação, truncamento acumulativo), lógica de negócio (violação de invariantes, casos de borda em math financeira, race conditions de estado), eficiência de gas, boas práticas.
 
-- **review**: Análise detalhada (3 a 6 frases) explicando por que a vulnerabilidade é ou não real. Referencie código específico, invariantes do protocolo, pré-condições e controles mitigadores.
-- **isFalsePositive**: true se o achado NÃO for explorável na prática; false se for uma vulnerabilidade real.
-- **confidence**: Número inteiro de 0 a 100 refletindo sua confiança no veredicto.
-- **exploitablePaths**: Array de strings. Se for verdadeiro positivo, forneça caminhos concretos confirmando a explorabilidade com valores reais. Cada rastreamento deve descrever os passos do atacante com entradas/valores realistas (ex.: "1. Atacante chama deposit(100 ETH) 2. Contrato do atacante no fallback chama withdraw() novamente antes da atualização do saldo 3. Atacante drena 100 ETH duas vezes"). Se for falso positivo, forneça o raciocínio que bloqueia o exploit.
+## Formato de saída
 
-Um achado é falso positivo somente se: o caminho de exploit for inacessível dados os controles de acesso ou pré-condições, já estiver totalmente mitigado pelo código, exigir condições impossíveis ou economicamente inviáveis, ou for explicitamente documentado como comportamento esperado nas premissas do protocolo.
+Para cada vulnerabilidade encontrada, forneça OBRIGATORIAMENTE todos os campos abaixo. Cada entrada deve ser **atômica**: reporte exatamente um problema por entrada. Não agrupe múltiplos problemas em um único achado, mesmo que ocorram na mesma função ou linha. Não há limite para o número de vulnerabilidades reportadas.
 
-Você deve fornecer exatamente um objeto de revisão por achado, na mesma ordem em que os achados foram apresentados.`;
+- **title**: Nome curto e preciso (ex.: "Reentrância em \`withdraw\`", "Controle de acesso ausente em \`setFee\`").
+- **description**: Descreva (a) o comportamento **esperado** pelo protocolo, (b) o comportamento **observado** no código vulnerável, e (c) o impacto concreto se explorado. Mínimo 3 frases, máximo 5.
+- **exploit_scenario**: Descreva um cenário concreto e passo a passo de como um atacante exploraria a vulnerabilidade.
+- **recommendation**: Correção específica e acionável com referência ao padrão ou mecanismo correto (ex.: "Aplicar checks-effects-interactions: mover \`balances[msg.sender] -= amount\` para antes da chamada externa").
+- **severity**: Exatamente um de: \`"high"\` (perda direta de fundos ou tomada de controle do contrato), \`"medium"\` (risco indireto ou condicional), \`"low"\` (problema de boas práticas, sem risco financeiro imediato).
+- **location**: Função e/ou número de linha onde o problema ocorre.
+- **codeSnippet**: O trecho exato e completo do código vulnerável, copiado literalmente do código-fonte. **Proibido** usar reticências (\`...\`), omissões, pseudocódigo ou paráfrases. Inclua as linhas exatas conforme aparecem no arquivo, com indentação original preservada. Se o snippet for maior que 40 linhas, inclua o intervalo completo sem cortes.
+
+## Regra de completude
+
+Reporte vulnerabilidades mesmo que não sejam imediatamente exploráveis. Vulnerabilidades podem ser de segurança, inconsistências de design, desalinhamentos econômicos ou falhas de observabilidade. Se nenhuma vulnerabilidade for encontrada, retorne um array vazio.
+
+## Processamento de feedback de revisão
+
+Se feedback de uma iteração anterior for fornecido:
+- Remova todos os achados marcados como falso positivo com confiança ≥ 80%.
+- Para achados marcados como falso positivo com confiança < 80%, reavalie e inclua apenas se houver argumento novo.
+- Adicione novos achados se o feedback apontar superfícies de ataque não cobertas.`;
+
+export const JUDGE_FINDINGS_PROMPT = `Você é um revisor rigoroso de segurança de smart contracts com profundo conhecimento em Solidity, execução EVM e design de protocolos. Avalie cada vulnerabilidade candidata submetida pelo auditor e determine se é um verdadeiro positivo ou um falso positivo.
+
+Para cada achado, forneça OBRIGATORIAMENTE todos os campos abaixo:
+
+- **review**: Análise técnica detalhada (3 a 6 frases) explicando o veredicto. Referencie: (a) o código específico envolvido, (b) invariantes ou premissas do protocolo que confirmam ou bloqueiam o exploit, (c) pré-condições necessárias para exploração, (d) controles mitigadores existentes que o auditor pode ter ignorado. Seja preciso — cite nomes de funções, variáveis e valores.
+- **isFalsePositive**: \`true\` se o achado NÃO for explorável na prática; \`false\` se for uma vulnerabilidade real.
+- **confidence**: Inteiro de 0 a 100 refletindo sua certeza no veredicto. Use < 60 apenas quando existir ambiguidade genuína no código.
+- **exploitablePaths**: Array de strings.
+  - Se verdadeiro positivo (\`isFalsePositive: false\`): forneça 1 a 3 caminhos concretos de exploit, cada um com passos numerados, entradas realistas e estado do contrato antes/depois. Ex.: ["1. Atacante chama flashLoan(500k USDC). 2. No callback, chama deposit() inflando reserves. 3. Chama withdraw() com preço manipulado. 4. Lucra 50k USDC. Estado: reserves inflado temporariamente, totalShares inalterado."].
+  - Se falso positivo (\`isFalsePositive: true\`): forneça o raciocínio exato que bloqueia cada caminho de exploit tentado pelo auditor.
+
+## Critérios para falso positivo (aplique com rigor — não seja permissivo)
+
+1. O caminho de exploit é bloqueado por controle de acesso verificável no código.
+2. A vulnerabilidade já é totalmente mitigada por outro mecanismo no código (ex.: nonReentrant, require com validação suficiente).
+3. A condição necessária para o exploit é impossível ou economicamente inviável dado o modelo do protocolo (ex.: requer ser o próprio contrato, ou lucro < custo de gas em qualquer cenário realista).
+4. O comportamento é explicitamente documentado como intencional nas premissas de design do protocolo.
+
+## Critérios para verdadeiro positivo
+- Existe pelo menos um caminho de exploit concreto e realista que viola uma invariante ou permite extração de valor não autorizada.
+- Não exige condições impossíveis nem assume acesso privilegiado não disponível ao atacante.
+- Inclui qualquer discrepância entre a implementação e a intenção, premissas ou objetivos documentados — mesmo que o contrato opere sem erros em runtime. Isso abrange problemas de segurança, inconsistências de design, desalinhamentos econômicos e falhas de observabilidade, independentemente de exploitabilidade direta.`;

src/config/llm.ts

@@ -7,7 +7,7 @@ export type LLMProvider = "google" | "openrouter" | "anthropic";
 
 export interface LLMOptions {
   model?: string;
-  temperature?: number;
+  temperature?: number | null;
   maxTokens?: number;
 }
 
@@ -18,7 +18,7 @@ export function createLLM(overrideProvider?: LLMProvider, options?: LLMOptions):
     case "openrouter":
       return new ChatOpenRouter({
         model: options?.model || process.env.OPENROUTER_MODEL || "google/gemini-3.1-flash-lite",
-        temperature: options?.temperature ?? 0.2,
+        ...(options?.temperature !== null && { temperature: options?.temperature ?? 0.2 }),
         apiKey: process.env.OPENROUTER_API_KEY,
         maxTokens: options?.maxTokens ?? 4096,
       });
@@ -26,7 +26,7 @@ export function createLLM(overrideProvider?: LLMProvider, options?: LLMOptions):
     case "anthropic":
       return new ChatAnthropic({
         model: options?.model || process.env.ANTHROPIC_MODEL || "claude-sonnet-4-6",
-        temperature: options?.temperature ?? 0.2,
+        ...(options?.temperature !== null && { temperature: options?.temperature ?? 0.2 }),
         apiKey: process.env.ANTHROPIC_API_KEY,
         maxTokens: options?.maxTokens ?? 4096,
       });
@@ -36,7 +36,7 @@ export function createLLM(overrideProvider?: LLMProvider, options?: LLMOptions):
       return new ChatGoogleGenerativeAI({
         apiKey: process.env.GOOGLE_API_KEY || "",
         model: options?.model || process.env.MODEL_NAME || "gemini-2.5-flash",
-        temperature: options?.temperature ?? 0.2,
+        ...(options?.temperature !== null && { temperature: options?.temperature ?? 0.2 }),
         maxOutputTokens: options?.maxTokens ?? 4096,
       });
   }