T-036 - Escrever a regra de referência e seus resultados como exemplo para a LLM

[pedro-fs-garcia]

T-036 - Escrever a regra de referência e seus resultados como exemplo para a LLM

• Componente: worker, codegen
• Depende de: T-033, T-034
• Data máxima: 2026-09-21 (seg)

Descrição

Gerar um exemplo de código de um a regra de negócio hipotética que o modelo de LLM possa usar como referência para gerar código de regras reais.

worker e codegen precisam de um caso determinístico para desenvolver contra, antes de a LLM entrar no circuito. Sem isso, um erro na execução do sandbox e um erro na geração de código ficam indistinguíveis, e depurar exige mexer nos dois ao mesmo tempo.

Esta tarefa entrega uma regra real do domínio, escrita à mão contra o contrato de T-034, com resultado conhecido e estável.

Tanto o código quanto os resultados obtidos serão utilizados como referência para a geração de código por LLM e para a conferência de cobertura.

Escopo

Dentro do escopo

• Código Python que implementa "marca 40, +0,3% para vendedores, novembro/2025", escrito manualmente conforme o contrato de T-034.
• A representação da regra correspondente, conforme o schema de T-004.
• Execução na imagem de T-033, produzindo apuracao_base, apuracao_simulada e a decomposição.
• Conferência manual, fora do container, da diferença contra o baseline de novembro - o mesmo cálculo que T-066 automatiza.
• Registro do resultado esperado, para uso como valor de referência em T-076.

Fora do escopo

• Qualquer geração por LLM (T-055).
• Execução pelo worker (T-064) - aqui a imagem é executada diretamente.
• Conferência de cobertura (T-056), que atua sobre código gerado.

Requisitos

• O código é escrito à mão e não passa pela LLM em nenhum momento: seu valor está justamente em ser determinístico.
• A regra escolhida é real do domínio e exercita marca, cargo e percentual - o núcleo inteiro.
• As asserções invariantes de T-031 passam nesta execução.

Contexto técnico

• Entradas: imagem do sandbox (T-033); contrato (T-034); baseline de novembro (T-032); schema da representação (T-004).
• Saídas: código de referência versionado; representação correspondente; resultado esperado registrado.
• Componentes afetados: repositório de fixtures compartilhado por worker, codegen e testes de ponta a ponta.
• Restrições: o valor esperado depende do baseline.

Critérios de aceitação

• O código roda na imagem do sandbox e produz saída válida contra o schema.
• A saída do container traz apuracao_base, apuracao_simulada e a decomposição.
• apuracao_base é idêntica ao baseline de novembro, conferido fora do container.
• A diferença absoluta e percentual contra o baseline está registrada como valor esperado.
• As três asserções invariantes passam.
• O resultado esperado está registrado como fixture, reutilizável por T-076.
• Reexecutar produz exatamente o mesmo resultado.

Definição de concluído (DoD)

• Todos os critérios de aceitação foram atendidos.
• Testes automatizados foram adicionados ou atualizados quando aplicável.
• Os testes existentes passam.
• O código segue as convenções e padrões de qualidade do projeto.
• Documentação, migrações, contratos ou configurações exigidos foram atualizados.
• Nenhuma regressão conhecida ou problema não resolvido foi introduzido pela tarefa.
• As alterações foram confirmadas e estão prontas para revisão/mesclagem.
• A implementação foi verificada no ambiente apropriado.

Observações / Decisões

Esta tarefa existe para conter cascata. Ela dá a worker e codegen um alvo fixo e verificável, de modo que uma falha no M3 seja localizável num componente só. Sem ela, o primeiro teste real do pipeline seria também o primeiro teste da geração por LLM - dois pontos de falha novos ao mesmo tempo.

Efeito cascata recebido: o valor esperado depende do baseline de T-032. Se aquele artefato for reapurado, esta fixture e a asserção de T-076 mudam junto.