first commit

docs/RELATORIO_FRAMEWORK_NATIVE_100.md

@@ -0,0 +1,110 @@
+# Relatório da refatoração framework-native
+
+## Resultado
+
+A versão foi refatorada para que o backoffice não execute mais grafos LangGraph legados diretamente. Os grafos originais do develop foram movidos para `legacy_reference_disabled/` e deixados apenas como referência/auditoria.
+
+## Arquitetura ativa
+
+O backend ativo usa:
+
+- `app/main.py` como camada de rotas/adapters.
+- `app/workflows/backoffice_native_runtime.py` como runtime de workflows do framework.
+- `src/agent/nodes/*` como nós de domínio.
+- `src/components/clients/*` como services/clients de domínio.
+- `src/agent/local_prompts/*` como prompts de domínio.
+- `config/agents/backoffice_anatel/*` como políticas de guardrails, judges e prompt policy.
+
+## Fluxo checklist ativo
+
+```text
+framework_input_guardrails
+fetch_ticket
+validation
+bypass_rules
+cache_check
+imdb_enrichment
+identity_verification
+speech_enrichment
+knowledge_base_enrichment
+canceling_analysis
+tim_complaint_analysis
+operator_route
+reclassification_analysis
+treatment_decision
+siebel_sr_opening
+framework_output_supervisor
+framework_output_guardrails
+framework_judges
+framework_supervisor_review
+framework_persist
+```
+
+## Fluxo response emulator ativo
+
+```text
+framework_input_guardrails
+start_response_emulation
+fetch_case
+validate_actions
+router
+retrieve_templates
+retrieve_history
+generate_response
+validate_response
+persist_draft / approve_draft / close_case
+framework_output_supervisor
+framework_output_guardrails
+framework_judges
+framework_supervisor_review
+framework_persist
+```
+
+## Diferença em relação à versão anterior
+
+Antes:
+
+```text
+app/main.py registrava routers originais
+rotas originais chamavam src.api.executors
+executors chamavam src.agent.graphs
+src.agent.graphs criava StateGraph diretamente
+```
+
+Agora:
+
+```text
+app/main.py chama backoffice_runtime.execute_workflow
+BackofficeNativeRuntime compila os workflows
+os nós originais são apenas plugins de domínio
+guardrails/judges/supervisor/checkpoint/telemetry entram no runtime
+```
+
+## Limites honestos
+
+A compilação está validada. A execução real depende das mesmas integrações externas do develop: IMDB, Siebel, Speech Analytics, TAIS KB, ABRT, Portabilidade, Autonomous DB, OCI Streaming e credenciais.
+
+## Ajuste aplicado: binding explícito dos guardrails do agente
+
+O runtime nativo agora resolve `config/agents.yaml`, localiza o profile `backoffice_anatel` e carrega explicitamente `guardrails_config_path`:
+
+```text
+config/agents/backoffice_anatel/guardrails.yaml
+```
+
+Com isso, os guardrails continuam sendo **executados pelo framework** (`GuardrailPipeline` e `OutputSupervisor`), mas a política ativa vem do backend/domínio do agente. A metadata do workflow também passa a registrar:
+
+```text
+agent_id
+ guardrails_profile
+ guardrails_config_path
+ active_input_rails
+ active_output_rails
+```
+
+Assim é possível validar em telemetry/debug que o backoffice não está usando apenas `config/guardrails.yaml` global, mas sim a configuração completa do agente:
+
+```text
+INPUT_SIZE, MSK, PINJ, TOX, DLEX_IN, RAGSEC, VLOOP
+REVPREC, DLEX_OUT, OOS, CMP, AOFERTA
+```