ajuste no guardraild COE

docs/FIX_COER_SEMANTIC_LLM_20260831.md

@@ -0,0 +1,27 @@
+# Ajuste semântico do guardrail COER
+
+## Objetivo
+
+Evitar que o COER confunda negação, reclamação, mudança de intenção ou falta de parâmetros com fala incompreensível.
+
+## Alteração
+
+O prompt de `agent_framework.guardrails.calibrated.prompts.coerencia` foi simplificado para uma responsabilidade única: decidir se existe significado conversacional recuperável.
+
+Foram removidas heurísticas textuais específicas de negação, listas de ações e exemplos de frases usados como regras de decisão. O julgamento continua sendo feito pelo LLM com o perfil `guardrail`.
+
+O COER agora não decide intenção, mudança de intenção, continuidade de transação, completude de parâmetros, validade de parâmetros, escopo ou executabilidade. Essas responsabilidades permanecem no router, runtime transacional, validators e clarification.
+
+## Contrato
+
+- compreensível, mas incompleto/ambíguo para negócio: ALLOW;
+- compreensível com possível mudança de intenção: ALLOW;
+- compreensível faltando parâmetros: ALLOW;
+- compreensível com negação/discordância: ALLOW;
+- sem significado semântico recuperável: BLOCK.
+
+## Testes
+
+- regressão dirigida do COER: 22 PASS;
+- `tests/migration`: 824 PASS / 2 FAIL;
+- os 2 FAIL são preexistentes e não relacionados ao COER.