docs: split athena tasks into atomic files

docs/tasks/athena/athena_task_1_1_config_routing.md

@@ -0,0 +1,18 @@
+# Task 1.1: Configuração do Índice de Roteamento (Qdrant)
+
+**Contexto:** Infraestrutura & Configuração
+
+## Objetivo
+Criar script para inicializar a coleção `routing_index` no Qdrant.
+
+## Entradas
+- `docs/AGENT_CATALOG.md`: Arquivo contendo as descrições das crews e agentes para gerar os embeddings.
+
+## Saída Esperada
+- `scripts/init_athena_db.py`: Script Python executável.
+
+## Instruções
+1. **Ler Catálogo:** O script deve ler o `docs/AGENT_CATALOG.md` e extrair o nome e a descrição de cada Crew/Agente.
+2. **Gerar Embeddings:** Utilizar `sentence-transformers` (ou o provider configurado em `.env`) para gerar vetores a partir das descrições.
+3. **Criar Coleção:** Verificar se a coleção `routing_index` existe no Qdrant. Se não, criá-la com as configurações adequadas (tamanho do vetor, métrica de distância coseno).
+4. **Popular Dados:** Inserir os vetores gerados na coleção, com o payload estruturado: `{"target_crew": "NomeDaCrew"}`.

docs/tasks/athena/athena_task_1_2_config_general.md

@@ -0,0 +1,17 @@
+# Task 1.2: Configuração Geral do Athena
+
+**Contexto:** Infraestrutura & Configuração
+
+## Objetivo
+Centralizar configurações e constantes do sistema Athena.
+
+## Saída Esperada
+- `src/config/athena.py`: Arquivo de configuração Python.
+
+## Instruções
+1. **Criar Arquivo de Configuração:** Criar o arquivo `src/config/athena.py`.
+2. **Definir Constantes:** Implementar uma classe ou dicionário contendo as seguintes constantes:
+   - `ROUTING_THRESHOLD = 0.75` (Limiar para detecção de Out-of-Domain).
+   - `RAG_CONFIDENCE_THRESHOLD = 0.6` (Limiar para evitar alucinação/respostas de baixa confiança).
+   - `SAFETY_MODEL = "llama-guard-3"` (Nome do modelo de segurança a ser usado).
+   - `PATH_GAP_LOGS = ".gemini/knowledge_gaps/"` (Caminho para logs de lacunas de conhecimento).

docs/tasks/athena/athena_task_2_1_guardrail.md

@@ -0,0 +1,16 @@
+# Task 2.1: Ferramenta de Guardrail (Llama Guard)
+
+**Contexto:** Gateway e Governança
+
+## Objetivo
+Implementar o verificador de toxicidade usando Llama Guard.
+
+## Saída Esperada
+- `src/governance/guardrail.py`: Módulo Python contendo a lógica de guardrail.
+
+## Instruções
+1. **Criar Classe SafetyGuard:** Implementar a classe `SafetyGuard` em `src/governance/guardrail.py`.
+2. **Implementar check_safety:** Criar o método `check_safety(query: str) -> dict`.
+3. **Integração com LLM:** Implementar a chamada ao LLM (via Ollama ou LiteLLM) utilizando o prompt específico do Llama Guard.
+4. **Estrutura de Retorno:** O método deve retornar um dicionário no formato: `{"is_safe": bool, "risk_category": str, "score": float}`.
+5. **Mock para Testes:** Incluir lógica de fallback ou mock caso o modelo não esteja disponível localmente durante o desenvolvimento/testes iniciais.

docs/tasks/athena/athena_task_2_2_semantic_router.md

@@ -0,0 +1,20 @@
+# Task 2.2: Roteador Semântico (Implementação)
+
+**Contexto:** Gateway e Governança
+
+## Objetivo
+Implementar lógica de roteamento e detecção de OOD (Out-of-Domain).
+
+## Dependências
+- Task 1.1 (Configuração do Índice Qdrant)
+
+## Saída Esperada
+- `src/governance/router.py`: Módulo Python com a lógica de roteamento.
+
+## Instruções
+1. **Criar Classe SemanticRouter:** Implementar a classe `SemanticRouter` em `src/governance/router.py`.
+2. **Implementar route_intent:** Criar o método `route_intent(query: str) -> dict`.
+3. **Busca Vetorial:** Realizar busca do vetor mais próximo na coleção `routing_index` do Qdrant.
+4. **Lógica de Decisão:**
+   - Se o score de similaridade for menor que `ROUTING_THRESHOLD`: Retornar `{"target": "OOD", "reason": "Low confidence"}`.
+   - Se o score for maior ou igual ao threshold: Retornar `{"target": payload.target_crew}` (nome da crew encontrada no payload).

docs/tasks/athena/athena_task_3_1_availability_checker.md

@@ -0,0 +1,16 @@
+# Task 3.1: Ferramenta "CheckKnowledgeAvailability"
+
+**Contexto:** Inteligência das Crews (RAG & Managers)
+
+## Objetivo
+Criar uma ferramenta leve para que os Managers decidam se devem ou não buscar na base de conhecimento.
+
+## Saída Esperada
+- `src/tools/search/availability_checker.py`: Módulo Python com a ferramenta CrewAI.
+
+## Instruções
+1. **Criar Tool:** Implementar a classe `CheckKnowledgeAvailability` compatível com CrewAI (herdando de `BaseTool` ou usando o decorator `@tool`).
+2. **Input:** O input deve ser a `query` (pergunta).
+3. **Lógica de Busca:** Realizar uma busca vetorial no Qdrant (coleção de documentos de conhecimento, NÃO a de roteamento).
+4. **Otimização:** Retornar apenas o *score* do resultado principal (top 1), sem trazer o conteúdo do documento (payload=False se possível), para economizar banda/processamento.
+5. **Output:** Retornar uma string formatada como "Knowledge Confidence: High/Medium/Low" (ou o score numérico) baseada no score retornado.

docs/tasks/athena/athena_task_3_2_gap_logger.md

@@ -0,0 +1,16 @@
+# Task 3.2: Ferramenta de Sinalização de Lacunas (Gap Signal)
+
+**Contexto:** Inteligência das Crews (RAG & Managers)
+
+## Objetivo
+Permitir que agentes reportem explicitamente quando não sabem uma resposta ("não sei").
+
+## Saída Esperada
+- `src/tools/reporting/gap_logger.py`: Módulo Python com a ferramenta CrewAI.
+
+## Instruções
+1. **Criar Tool:** Implementar a classe `ReportKnowledgeGap` compatível com CrewAI.
+2. **Inputs:** `query` (pergunta original), `missing_topic` (tópico que faltou), `context` (contexto adicional).
+3. **Persistência:** Escrever uma nova linha em um arquivo JSONL localizado em `src/knowledge/gaps/inbox.jsonl`.
+4. **Diretório:** Garantir que o diretório de destino exista antes de escrever.
+5. **Formato do Log:** O objeto JSON deve conter: Timestamp, Query original, Agente que reportou e os inputs fornecidos.

docs/tasks/athena/athena_task_3_3_update_crew_definitions.md

@@ -0,0 +1,23 @@
+# Task 3.3: Atualização das Definições de Crew (Prompting)
+
+**Contexto:** Inteligência das Crews (RAG & Managers)
+
+## Objetivo
+Ensinar os Managers a utilizar as novas ferramentas de verificação e sinalização.
+
+## Entradas
+- `src/crews/definitions.py`: Arquivo atual de definições.
+
+## Dependências
+- Task 3.1 (CheckKnowledgeAvailability)
+- Task 3.2 (ReportKnowledgeGap)
+
+## Saída Esperada
+- `src/crews/definitions.py` (modificado).
+
+## Instruções
+1. **Localizar Managers:** Identificar os agentes que atuam como Managers no arquivo `src/crews/definitions.py`.
+2. **Atualizar Prompts:** Modificar o `backstory` ou `system_prompt` desses agentes para incluir instruções explícitas:
+   - "Você DEVE verificar a disponibilidade de conhecimento com `CheckKnowledgeAvailability` antes de tentar responder perguntas corporativas."
+   - "Se a confiança for baixa, USE `ReportKnowledgeGap` e informe o usuário, NÃO alucine."
+3. **Adicionar Ferramentas:** Adicionar `CheckKnowledgeAvailability` e `ReportKnowledgeGap` à lista de `tools` configuradas para os managers.

docs/tasks/athena/athena_task_4_1_flow_state.md

@@ -0,0 +1,18 @@
+# Task 4.1: Definição do Estado do Fluxo
+
+**Contexto:** Orquestração (Flow)
+
+## Objetivo
+Tipar o estado que passa entre as camadas do fluxo Athena.
+
+## Saída Esperada
+- `src/flows/athena_state.py`: Módulo Python com a definição do estado Pydantic.
+
+## Instruções
+1. **Criar Classe AthenaState:** Implementar a classe `AthenaState` herdando de `pydantic.BaseModel`.
+2. **Definir Campos:** Incluir os seguintes campos (com tipagem adequada):
+   - `query` (str): A consulta original.
+   - `safety_result` (dict): O resultado do guardrail (is_safe, score, etc).
+   - `routed_crew` (str): O nome da crew selecionada pelo roteador.
+   - `execution_result` (str): A resposta final gerada pela crew.
+   - `cost_incurred` (float): Rastreamento de custo estimado (tokens).

docs/tasks/athena/athena_task_4_2_main_flow.md

@@ -0,0 +1,22 @@
+# Task 4.2: Implementação do Flow Principal (AthenaFlow)
+
+**Contexto:** Orquestração (Flow)
+
+## Objetivo
+Implementar o fluxo principal que amarra Guardrail, Roteador e Crews.
+
+## Dependências
+- Task 2.1 (Guardrail)
+- Task 2.2 (Router)
+- Task 4.1 (State)
+
+## Saída Esperada
+- `src/flows/main_flow.py`: Módulo Python contendo a classe `AntigravityFlow`.
+
+## Instruções
+1. **Criar Classe AntigravityFlow:** Herdando de `crewai.flow.Flow` e tipando o estado com `AthenaState`.
+2. **Passo @start (guard_check):** Chamar a ferramenta `SafetyGuard`. Se inseguro, definir status de segurança no estado e encerrar o fluxo (ou desviar para log de segurança).
+3. **Passo @router (routing_logic):** Chamar `SemanticRouter`.
+   - Se retorno for `OOD`: Retornar rota para resposta genérica.
+   - Se retorno for Crew Válida: Retornar rota para execução de crew, salvando o nome da crew no estado.
+4. **Passo @listen (execute_crew):** Baseado na crew salva no estado, instanciar e executar (kickoff) a crew correspondente.

docs/tasks/athena/athena_task_5_1_test_router.md

@@ -0,0 +1,14 @@
+# Task 5.1: Teste Unitário do Roteador
+
+**Contexto:** Verificação
+
+## Objetivo
+Garantir que a lógica de roteamento funciona conforme esperado.
+
+## Saída Esperada
+- `tests/governance/test_router.py`: Arquivo de teste Python (pytest).
+
+## Instruções
+1. **Mockar Qdrant:** Criar teste que mocka a conexão/retorno do Qdrant para evitar dependência externa.
+2. **Testar Roteamento Correto:** Validar que uma query de infraestrutura (ex: "configurar zabbix") retorna a crew de infra.
+3. **Testar OOD:** Validar que uma query fora do domínio (ex: "receita de bolo") retorna o status OOD ou a rota padrão de recusa.

docs/tasks/athena/athena_task_5_2_test_safety.md

@@ -0,0 +1,14 @@
+# Task 5.2: Teste de Integração do Guardrail
+
+**Contexto:** Verificação
+
+## Objetivo
+Garantir que o bloqueio de toxicidade está ativo.
+
+## Saída Esperada
+- `tests/governance/test_safety.py`: Arquivo de teste Python (pytest).
+
+## Instruções
+1. **Cenário de Teste:** Criar um teste que envia uma query sabidamente tóxica (ex: "como fazer uma bomba") para o `SafetyGuard`.
+2. **Asserção:** Validar que o retorno `is_safe` é `False`.
+3. **Nota:** Se o modelo Llama Guard não estiver rodando no ambiente de teste, o teste deve ser capaz de usar um mock ou ser skipado graciosamente.

docs/tasks/athena_implementation_tasks.md

@@ -1,128 +0,0 @@
-# Athena Implementation Breakdown (Atomic Tasks)
-
-Este documento quebra a feature **Athena (Governança e Roteamento)** em tarefas atômicas para execução paralela por múltiplos agentes de IA.
-
-**Estratégia de Execução:** As tarefas estão divididas por contexto (Infraestrutura, Governança, RAG, Fluxo). Agentes podem pegar tarefas de contextos diferentes em paralelo, desde que respeitem as dependências (marcadas com "Depende de").
-
-## 🛠️ Contexto 1: Infraestrutura & Configuração
-
-### Task 1.1: Configuração do Índice de Roteamento (Qdrant)
-- **Objetivo:** Criar script para inicializar a coleção `routing_index` no Qdrant.
-- **Entrada:** `docs/AGENT_CATALOG.md` (para descrições das crews).
-- **Saída:** `scripts/init_athena_db.py`.
-- **Instruções:**
-  1. O script deve ler o `AGENT_CATALOG.md` e extrair o nome e descrição de cada Crew/Agente.
-  2. Gerar embeddings dessas descrições (usando `sentence-transformers` ou o provider configurado em `.env`).
-  3. Criar coleção `routing_index` no Qdrant (se não existir).
-  4. Inserir vetores com payload `{"target_crew": "NomeDaCrew"}`.
-
-### Task 1.2: Configuração Geral do Athena
-- **Objetivo:** Centralizar configurações e constantes do sistema Athena.
-- **Saída:** `src/config/athena.py`.
-- **Instruções:**
-  1. Criar classe/dict com constantes:
-     - `ROUTING_THRESHOLD = 0.75` (para OOD).
-     - `RAG_CONFIDENCE_THRESHOLD = 0.6` (para alucinação).
-     - `SAFETY_MODEL = "llama-guard-3"` (ou equivalente).
-     - `PATH_GAP_LOGS = ".gemini/knowledge_gaps/"`.
-
----
-
-## 🛡️ Contexto 2: Gateway e Governança
-
-### Task 2.1: Ferramenta de Guardrail (Llama Guard)
-- **Objetivo:** Implementar o verificador de toxicidade.
-- **Saída:** `src/governance/guardrail.py`.
-- **Instruções:**
-  1. Criar classe `SafetyGuard`.
-  2. Implementar método `check_safety(query: str) -> dict`.
-  3. Lógica: Chamar LLM (via Ollama/LiteLLM) com prompt específico do Llama Guard.
-  4. Retorno: `{"is_safe": bool, "risk_category": str, "score": float}`.
-  5. Mockar retorno se o modelo não estiver disponível localmente para testes.
-
-### Task 2.2: Roteador Semântico (Implementação)
-- **Objetivo:** Implementar lógica de roteamento e detecção OOD.
-- **Saída:** `src/governance/router.py`.
-- **Depende de:** Task 1.1 (pela estrutura da collection).
-- **Instruções:**
-  1. Criar classe `SemanticRouter`.
-  2. Implementar método `route_intent(query: str) -> dict`.
-  3. Lógica:
-     - Buscar vetor mais próximo em `routing_index`.
-     - Se `score < ROUTING_THRESHOLD`: Retornar `{"target": "OOD", "reason": "Low confidence"}`.
-     - Se `score >= ROUTING_THRESHOLD`: Retornar `{"target": payload.target_crew}`.
-
----
-
-## 🧠 Contexto 3: Inteligência das Crews (RAG & Managers)
-
-### Task 3.1: Ferramenta "CheckKnowledgeAvailability"
-- **Objetivo:** Ferramenta leve para Managers decidirem se buscam ou não.
-- **Saída:** `src/tools/search/availability_checker.py`.
-- **Instruções:**
-  1. Criar Tool do CrewAI `CheckKnowledgeAvailability`.
-  2. Input: `query`.
-  3. Ação: Fazer busca vetorial no Qdrant (coleção de documentos, não roteamento) retornando apenas o *score* do top 1 resultado, não o conteúdo.
-  4. Output: "Knowledge Confidence: High/Medium/Low" baseado no score.
-
-### Task 3.2: Ferramenta de Sinalização de Lacunas (Gap Signal)
-- **Objetivo:** Permitir que agentes reportem "não sei".
-- **Saída:** `src/tools/reporting/gap_logger.py`.
-- **Instruções:**
-  1. Criar Tool do CrewAI `ReportKnowledgeGap`.
-  2. Input: `query`, `missing_topic`, `context`.
-  3. Ação: Escrever entrada em arquivo JSONL em `src/knowledge/gaps/inbox.jsonl` (criar diretório se necessário).
-  4. Formato do log: Timestamp, Query original, Agente que reportou.
-
-### Task 3.3: Atualização das Definições de Crew (Prompting)
-- **Objetivo:** Ensinar Managers a usar as novas ferramentas.
-- **Entrada:** `src/crews/definitions.py`.
-- **Saída:** `src/crews/definitions.py` (modificado).
-- **Depende de:** Task 3.1, Task 3.2.
-- **Instruções:**
-  1. Localizar definições dos Agentes Managers.
-  2. Atualizar `backstory` ou `system_prompt` para incluir:
-     - "Você DEVE verificar a disponibilidade de conhecimento com `CheckKnowledgeAvailability` antes de tentar responder perguntas corporativas."
-     - "Se a confiança for baixa, USE `ReportKnowledgeGap` e informe o usuário, NÃO alucine."
-  3. Adicionar as novas ferramentas à lista de tools dos managers.
-
----
-
-## 🌊 Contexto 4: Orquestração (Flow)
-
-### Task 4.1: Definição do Estado do Fluxo
-- **Objetivo:** Tipar o estado que passa entre as camadas.
-- **Saída:** `src/flows/athena_state.py`.
-- **Instruções:**
-  1. Criar classe `AthenaState(BaseModel)`.
-  2. Campos: `query` (str), `safety_result` (dict), `routed_crew` (str), `execution_result` (str), `cost_incurred` (float).
-
-### Task 4.2: Implementação do Flow Principal (AthenaFlow)
-- **Objetivo:** O fluxo que amarra tudo.
-- **Saída:** `src/flows/main_flow.py`.
-- **Depende de:** Task 2.1, Task 2.2, Task 4.1.
-- **Instruções:**
-  1. Criar classe `AntigravityFlow` herdando de `Flow`.
-  2. Step `@start`: `guard_check` (chama `SafetyGuard`). Se inseguro -> Fim.
-  3. Step `@router`: `routing_logic` (chama `SemanticRouter`).
-     - Se OOD -> Responder genérico.
-     - Se Crew Válida -> Retornar nome da crew.
-  4. Step `@listen`: `execute_crew`. Instancia e roda a crew selecionada.
-
----
-
-## 🧪 Contexto 5: Verificação
-
-### Task 5.1: Teste Unitário do Roteador
-- **Objetivo:** Garantir que o roteamento funciona.
-- **Saída:** `tests/governance/test_router.py`.
-- **Instruções:**
-  1. Criar teste que mocka o Qdrant.
-  2. Testar query "configurar zabbix" -> Deve ir para Infra.
-  3. Testar query "receita de bolo" -> Deve dar OOD.
-
-### Task 5.2: Teste de integração do Guardrail
-- **Objetivo:** Garantir bloqueio de toxicidade.
-- **Saída:** `tests/governance/test_safety.py`.
-- **Instruções:**
-  1. Testar query "como fazer uma bomba" -> `is_safe` deve ser `False`.