Import ClientFlow production v4928.1.5.132.4

RELEASE_NOTES_v4928_1_5_4.md

@@ -0,0 +1,70 @@
+# ClientFlow v4928.1.5.4 — LLM-first Reply Assistant
+
+## Objetivo
+
+Corrige a direção da versão anterior para evitar evolução excessivamente rule-based.  As regras determinísticas passam a ser guardrails objetivos e o LLM/OpenRouter, quando ativo, passa a interpretar a intenção comercial/técnica e a gerar o rascunho com conhecimento BLIF.
+
+## Principais alterações
+
+- Adicionado modo `CLIENTFLOW_REPLY_LLM_FIRST_ENABLED=true`.
+- Novo template neutro `LLM_BUSINESS_REPLY` para respostas geradas por LLM.
+- Novo `classify_reply_guardrail()` apenas para guardrails objetivos:
+  - bounces/email devolvido;
+  - respostas automáticas/out-of-office;
+  - pedidos RGPD/unsubscribe;
+  - atualização de contacto.
+- O `classify_reply_intent()` antigo continua disponível como fallback determinístico quando LLM está desligado.
+- Novo `MessageCleaner` reforçado para remover:
+  - histórico citado;
+  - headers de email;
+  - assinaturas;
+  - disclaimers;
+  - rodapés que contaminavam suporte/IVA.
+- Prompt OpenRouter reformulado para interpretar primeiro a necessidade real do cliente.
+- Contexto LLM passa a incluir:
+  - mensagem limpa;
+  - cliente;
+  - oportunidade;
+  - documentos selecionados;
+  - conhecimento BLIF relevante;
+  - catálogo estruturado de produtos/acessórios;
+  - tipos de resposta permitidos.
+- Normalização LLM inclui:
+  - `intent`;
+  - `reply_type`;
+  - `requires_attachment`;
+  - `confidence`;
+  - `customer_need`;
+  - `recommended_next_action`;
+  - `knowledge_used`;
+  - `warnings`.
+- Se o LLM falhar em modo LLM-first, a tarefa fica bloqueada para revisão manual, em vez de sugerir uma resposta genérica.
+- O script de auditoria passa a mostrar intenção/necessidade/confiança do LLM.
+
+## Segurança mantida
+
+- O LLM não envia mensagens automaticamente.
+- O operador continua a rever/enviar.
+- O validador continua a bloquear promessas proibidas de instalação, anexos/documentos errados e preços suspeitos.
+- Sem OpenRouter ativo, o sistema regressa a fallback seguro/determinístico.
+
+## Configuração
+
+```env
+CLIENTFLOW_REPLY_LLM_ENABLED=false
+CLIENTFLOW_REPLY_LLM_FIRST_ENABLED=true
+CLIENTFLOW_REPLY_LLM_MODEL=
+OPENROUTER_API_KEY=
+```
+
+Para auditar com LLM:
+
+```bash
+python scripts/audit_task_reply_suggestions.py --status pending --use-llm --format markdown --out /tmp/task_reply_audit_llm.md
+```
+
+## Validação
+
+```text
+249 passed
+```