T-300 - Definir no contrato da trilha o resultado e a variante de cada etapa

• Componente: contracts/, em PR próprio, sujeito a autorização.
• Depende de: nenhuma tarefa.
• Data máxima: 04/11/2026
• Estimativa: 3 pontos (Fibonacci)

Entregável

• Campo opcional resultado_id em contracts/events/no-concluido.schema.json.
• Campos opcionais modo_geracao, motivo_sugestao, desfecho_busca e candidatas_simuladas em contracts/domain/trilha-conclusao.schema.json.
• Descrições de no_dominio, elementos_implementados, diagnostico e concentracao atualizadas para dizer que o fluxo atual não os produz.
• Descrição de no_grafo em contracts/domain/comum.schema.json atualizada para o grafo atual.
• Exemplos novos, registrados no manifesto, representando linhas do fluxo atual, com os exemplos existentes mantidos.

Descrição

O evento no-concluido e a coluna trilhas_auditoria.conclusao não têm onde registrar o resultado sobre o qual uma etapa agiu nem qual variante da etapa ocorreu. Esta tarefa acrescenta esses campos ao contrato, de forma aditiva, para que a API os grave (T-301) e o codegen os publique (T-302).

Contexto e decisões tomadas

• O produtor de no-concluido é o codegen. O consumidor é a API, que grava trilhas_auditoria. A API também grava linhas confirmacao sem passar pelo evento, e elas não mudam nesta tarefa.
• Nenhum schema envolvido declara additionalProperties: false. O codegen ignora campos desconhecidos (ModeloContrato com extra="ignore" em codegen/app/contratos/mensagens.py), e a API também (skill consumidores da API). O contrato pode entrar antes dos dois.
• resultado_id é referência e não conteúdo, como as demais referências do evento.
• Os campos novos da conclusão usam vocabulário fechado, com os valores que o codegen já usa. motivo_sugestao repete as constantes de codegen/app/sugestao_adaptacao.py, e desfecho_busca repete os motivos de SemSolucaoMeta mais encontrada.
• Nenhum nome de etapa é criado, e o enum no_grafo não muda. Só a descrição dele muda.
• Nenhum campo é removido nem renomeado (ADR-002).

Escopo

Dentro do escopo

• contracts/events/no-concluido.schema.json, contracts/domain/trilha-conclusao.schema.json e contracts/domain/comum.schema.json.
• Exemplos novos em contracts/examples/ e o registro deles em contracts/examples/manifesto.json.

Fora do escopo

• Alterar contracts/examples/events/no-concluido.json e contracts/examples/domain/trilha-conclusao.json, que continuam válidos e são lidos pelos testes do codegen.

• DTOs, migration e gravação na API (T-301).

• Publicação pelo codegen (T-302).

• Qualquer campo das etapas de extração e reextração.

Requisitos

Autorização

1. Antes de editar contracts/, parar e pedir autorização explícita ao usuário, conforme contract-change (.agents/skills/contract-change/SKILL.md). O pedido informa os três schemas alterados, os três exemplos novos e o manifesto, o produtor (codegen) e o consumidor (API), a compatibilidade (aditiva; eventos e linhas antigas continuam válidos), os riscos (nenhum consumidor quebra, porque os dois ignoram campo desconhecido) e as validações (exemplos, testes dos dois componentes e gate dos quatro componentes). Não implementar os requisitos seguintes antes da autorização.

Evento no-concluido

2. Acrescentar resultado_id (string, format: uuid), opcional. A descrição diz que é o resultado sobre o qual a etapa agiu e enumera os casos. Na decisao, é o resultado decidido. Na sugestao_adaptacao, é o resultado inviável analisado. Na linha decisao que encerra a busca da meta, é a candidata vencedora, e fica ausente quando a busca termina sem solução. Na geracao_codigo com modo_geracao igual a correcao, é o resultado que falhou. Na geracao_codigo com modo_geracao igual a derivado, é o resultado de sucesso da versão de origem. Nas demais etapas, fica ausente.
3. Na descrição de simulacao_id, acrescentar que só a linha de geracao_codigo o traz e que as demais chegam à simulação pelo código do resultado apontado em resultado_id.

Conclusão da trilha

4. Acrescentar modo_geracao, com enum gerado, derivado e correcao, descrito como "Nó geracao_codigo". gerado é o código produzido pelo modelo a partir da regra. derivado é o código da alternativa derivado do código já simulado da versão de origem, sem chamar o modelo, e por isso o prompt_id da linha é o da versão de origem. correcao é o código produzido pelo modelo a partir do código que falhou no worker.
5. Acrescentar motivo_sugestao, com enum proposta, sem_margem, incoerente, nao_suportada e limite, descrito como "Nó sugestao_adaptacao". A descrição diz que só proposta leva a uma versão nova, que a API grava com regras.origem = 'sugestao_adaptacao'.
6. Acrescentar desfecho_busca, com enum encontrada, nao_monotonica, intervalo_esgotado e falha_execucao, e candidatas_simuladas (integer, minimum 0). Os dois são descritos como "Nó decisao, na linha que encerra a busca da meta maior". A descrição diz que a presença de desfecho_busca distingue essa linha da decisão sobre o resultado, e que as execuções candidatas não têm linha própria na trilha e ficam em resultados_simulacao com proposito = 'busca_meta'.
7. Nas descrições de no_dominio, elementos_implementados, diagnostico e concentracao, acrescentar que o fluxo atual não produz o campo. Em elementos_implementados, acrescentar que a declaração de cobertura acontece na execução do código e fica no resultado da simulação.
8. Na descrição do schema, trocar "Só resumo é comum a todos" por um texto que mantenha a regra de não repetir veredito e razão de parada, e acrescentar que a meta e a tentativa também não se repetem, porque a linha as alcança pelo resultado e pela versão.

Vocabulário de etapas

9. Reescrever a descrição de no_grafo em comum.schema.json. Ela deixa de dizer que os oito primeiros nomes são a sequência de 1 a 8 e passa a dizer o que grava cada nome no grafo atual. geracao_codigo cobre geração, derivação e correção do código. delegacao_worker grava uma linha por código, e as execuções candidatas da busca não geram linha. decisao cobre a decisão sobre o resultado e o encerramento da busca da meta. sugestao_adaptacao grava uma linha por resultado inviável analisado. interpretacao_resultado e explicacao estão reservados e nenhum nó os produz hoje. confirmacao é gravado pela API quando o usuário corrige a regra.

Exemplos

10. Não alterar contracts/examples/events/no-concluido.json. O teste test_producer_publica_payload_validado_na_rota_correta, em codegen/tests/app/test_mensageria.py, valida esse exemplo com o DTO NoConcluido e exige que o payload publicado seja igual ao exemplo. Como o DTO descarta campos desconhecidos, um exemplo com os campos novos quebraria o teste até a T-302.
11. Criar três exemplos e registrá-los em contracts/examples/manifesto.json, ao lado dos existentes. events/no-concluido-geracao-derivada.json é uma linha geracao_codigo com modo_geracao igual a derivado, resultado_id, prompt_id e codigo_gerado_id, sem fontes e sem elementos_implementados. events/no-concluido-encerramento-busca.json é uma linha decisao com resultado_id, desfecho_busca igual a encontrada e candidatas_simuladas. domain/trilha-conclusao-sugestao.json é a conclusão de uma linha sugestao_adaptacao com resumo e motivo_sugestao igual a proposta. Os identificadores repetem os dos exemplos existentes quando representam a mesma entidade.

Contexto técnico

• Entradas: schemas e exemplos atuais.
• Saídas: schemas e exemplos com os campos opcionais novos.
• Componentes afetados: contracts/. Produtor e consumidor só passam a usar os campos na T-301 e na T-302.
• Restrições: evolução aditiva; nenhum additionalProperties: false; nenhum nome de etapa novo.
• Referências: contract-change (.agents/skills/contract-change/SKILL.md), validador dos exemplos (contracts/validar-exemplos.py), ADR-002 (docs/adrs/ADR-002.md), contracts/events/no-concluido.schema.json, contracts/domain/trilha-conclusao.schema.json, contracts/domain/comum.schema.json, codegen/app/sugestao_adaptacao.py.

Critérios de aceitação

• python contracts/validar-exemplos.py passa e valida os três exemplos novos.
• Os exemplos existentes de no-concluido e trilha-conclusao continuam válidos sem alteração.
• Os testes do codegen e da API passam sem mudança de código, o que confirma que o contrato entra antes dos dois.
• Um evento com modo_geracao fora do vocabulário é rejeitado pelo schema.
• Um evento com candidatas_simuladas negativo é rejeitado pelo schema.

Definição de concluído (DoD)

• Autorização registrada antes da edição de contracts/.
• python contracts/validar-exemplos.py e git diff --check sem falha.
• Gate dos quatro componentes verde, porque o diff toca contracts/.
• Encerramento informando os testes de produtor e consumidor executados e os que não puderam ser executados.

Observações

• A coluna trilhas_auditoria.resultado_id não pertence a este PR. O schema só documenta o campo do evento.