New features: Route Stickness, Handoff, Clarification, Read-Only/Transactional, Long Term Memory

docs/JUDGES_TRANSACTIONAL_SAMPLING_FIX.md

@@ -0,0 +1,33 @@
+# Judges obrigatórios em interações transacionais
+
+## Problema
+
+Mesmo com `always_run_for_transactional: true`, os judges podiam ser ignorados
+pela amostragem porque o nó `judge` enviava apenas `context`, `route`, `intent` e
+`mcp_results`. Os campos transacionais produzidos pelo runtime não chegavam ao
+`JudgePipeline`.
+
+## Correção
+
+O nó `judge` agora repassa:
+
+- `transaction_status`
+- `confirmation_required`
+- `confirmation_received`
+- `tool_policy_result`
+- `selected_tool_call`
+- `pending_tool_call`
+- `mcp_results` como evidência
+
+O `JudgePipeline` detecta transações por múltiplos sinais e avalia
+`always_run_for_transactional` antes de aplicar `sample_rate`.
+
+Com a configuração abaixo, consultas comuns continuam sendo amostradas em 25%,
+mas turnos `AWAITING_CONFIRMATION`, `COMPLETED`, `FAILED` ou `CANCELLED` executam
+os judges sempre.
+
+```yaml
+enabled: true
+sample_rate: 0.25
+always_run_for_transactional: true
+```

docs/PERFORMANCE_OPTIMIZATIONS_MCP_JUDGES_RAG.md

@@ -0,0 +1,14 @@
+# Otimizações de execução MCP, RAG e Judges
+
+- `mcp_tools` permanece allowlist; somente a consulta selecionada por `selection_keywords` é executada.
+- Extração `strategy: hybrid` tenta `pattern` regex antes do perfil LLM.
+- RAG é ignorado quando MCP bem-sucedido é suficiente, salvo perguntas de política/regra.
+- `mcp_results` é fornecido como evidência ao groundedness judge.
+- `judges.yaml` aceita `sample_rate` e `always_run_for_transactional`.
+- Consultas estruturadas simples podem retornar resposta determinística sem LLM do agente.
+
+## Mudança de consulta para ação transacional
+
+A route stickiness é preemptada quando uma keyword explícita configurada em `routing.yaml` identifica outra intent/agente. Assim, uma sessão em `retail_order_tracking` muda para `retail_support_exchange_return` ao receber pedidos como “devolver pedido”. Além disso, respostas diretas de tools read-only são bloqueadas quando a mensagem contém `selection_keywords` de qualquer tool transacional registrada.
+
+As palavras de ação ficam em `config/tools.yaml`; o runtime não mantém aliases de domínio hardcoded.