Lotofacil-IA

Imported from Hernandesjunio/Lotofacil-IA (AGENTS.md). Install upstream with npx skills add Hernandesjunio/Lotofacil-IA. Copyright stays with the author.

Orientação para agentes de IA

Este arquivo resume intenção, limites e fontes normativas do repositório Lotofacil-IA, para outro agente (ou a mesma sessão noutro contexto) orientar-se sem ler toda a pasta docs/. Não substitui os specs: quando a tarefa alterar semântica, contrato ou métricas, abra os documentos indicados e alinhe código + testes + documentação em conjunto.

Humanos: o ponto de entrada narrativo continua no README.md.

O que é o projeto

Sistema exclusivamente educacional para engenharia de IA aplicada à Lotofácil: demonstrar métricas e comportamentos observados no histórico através de indicadores estatísticos determinísticos, exposição via MCP/HTTP em JSON, composição declarativa de análises e geração reproduzível de jogos candidatos apenas como ilustração de critérios declarados, com explicabilidade (critérios, janela, pesos, filtros, versões).

Não é: previsão de resultados, sugestão de “o que vai sair”, promessa de maior chance ou vantagem no sorteio, recomendação comercial de apostas, nem “IA embarcada” no servidor que interprete linguagem natural em substituição do contrato. Parâmetros como verbosity=full (e projeção/paginação, ADR 0023) controlam completude e formato da resposta para auditoria/ensino — não aumentam validade preditiva nem “precisão” sobre sorteios futuros.

Fontes de verdade (ordem sugerida)

Complementos frequentes: docs/generation-strategies.md, docs/test-plan.md, docs/project-guide.md, docs/prompt-catalog.md, docs/fases-execucao-templates.md (templates atômicos por fase, incluindo extensões).

ADRs (decisões arquiteturais e de processo):

• docs/adrs/0001-fechamento-semantico-e-determinismo-v1.md
• docs/adrs/0002-composicao-analitica-e-filtros-estruturais-v1.md
• docs/adrs/0003-processo-desenvolvimento-bmad-vs-spec-driven.md
• docs/adrs/0004-estrutura-arquitetural-inicial-mcp-dotnet10.md
• docs/adrs/0005-transporte-mcp-e-superficie-tools-v1.md
• docs/adrs/0006-inter-tool-fluidez-pipeline-e-disponibilidade-v1.md — inter-tool, disponibilidade de métricas em rota, pipeline, fluidez, GAPS e cenário pares–entropia
• docs/adrs/0007-agregados-canonicos-de-janela-v1.md — agregados canônicos via summarize_window_aggregates
• docs/adrs/0008-descoberta-superficie-mcp-e-mapeamento-legado-top10-v1.md — descoberta (tools vs resources), janela por extremos, mapeamento legado Top 10
• docs/adrs/0021-apresentacao-resumos-metricas-janela-descricoes-acessiveis-v1.md — tabelas A (escalares e listas curtas) e B (séries); D5 resumo vs. interpretação; abaixo.

Apresentação a leitores (explicação em prosa/tabela, não o envelope JSON do MCP) obedece à ADR 0021: modelo A e B; por defeito resumo padrão (poucos tokens, 1–2 frases alinhadas ao apêndice / glossário); interpretação explícita (comparar valores, aprofundar) só a pedido do utilizador ou regra do host, com mais tokens e conclusões ancoradas nos dados. O que uma métrica é e fórmulas: metric-glossary.md + metric-catalog.md — não inventar definições nem fórmulas fora dessas fontes (nem da ADR).

Stack e forma de entrega

• Implementação alvo: C# / .NET 10, servidor stateless, sem LLM no servidor para cumprir o contrato.
• Fronteira pública: HTTP + tools MCP; respostas JSON com rastreabilidade (dataset_version, tool_version, deterministic_hash conforme contrato).
• Dados: histórico inicialmente por arquivo (CEF); evolução futura de fontes não deve mudar a semântica das métricas documentadas.

A documentação descreve camadas alvo (LotofacilMcp.Domain, Application, Infrastructure, Server). O código em src/ pode estar em fase de materialização; a estrutura e os nomes devem convergir com docs/project-guide.md e ADR 0004, não o contrário.

Como deve ser o trabalho (obrigatório moral do repo)

1. Spec-driven: semântica nasce em docs/; cada entrega é um recorte explícito com testes correspondentes.
2. TDD / contrato primeiro: erros, formas de MetricValue, determinismo e validação estrutural importam tanto quanto “feature”.
3. Fatias verticais pequenas: começar pela V0 (vertical-slice.md) antes de expandir o catálogo.
4. Determinismo: mesmo input válido ⇒ mesmo output canônico; componente estocástico exige seed explícito documentado.
5. Sem defaults ocultos no servidor: parâmetros incertos devem ser clarificados no cliente/host conforme contrato; ver mcp-tool-contract.md.
6. Mudança coordenada: alterar semântica ⇒ atualizar docs + testes + código na mesma linha de raciocínio.

Mapa rápido de pastas

Atalhos por tipo de tarefa

Lembrete de linguagem e produto

Em texto voltado ao utilizador final, evitar linguagem de garantia de acerto, previsão, melhoria de chances no sorteio, “dica do que jogar” ou sinónimos (ex.: dizer o próximo, números fortes, tendência a sair). Indicadores são descritivos e condicionados à janela; “persistência” e “estabilidade” referem-se a padrões no histórico analisado, não a promessa futura. O jogo é azar; no modelo usual, cada combinação simples tem a mesma probabilidade — o produto descreve o passado e ensina métricas, não classifica combinações como “mais prováveis de ganhar”.

Checklist (docs, Content, resources, descrições de tools): educacional; métricas sobre sorteios passados; sem objectivo preditivo; sem promessa de retorno ou acerto.

Última intenção deste arquivo: dar um mapa cognitivo mínimo. Se a sua alteração tornar qualquer seção deste resumo falsa, atualize este arquivo ou o README.md no mesmo conjunto de mudanças.