T-316 - Definir o contrato da explicação da simulação

• Componente: raiz (contracts/ e docs/decisoes/dec-087.md), sujeito a autorização.
• Depende de: T-315 respondida, T-300 e T-304 no develop, porque esta tarefa altera os mesmos schemas e a mesma decisão.
• Data máxima: 10/11/2026
• Estimativa: 3 pontos (Fibonacci)

Entregável

• Campo desfecho_explicacao na conclusão da trilha.
• Descrição de explicacao_id no evento no-concluido alinhada à gravação da explicação reprovada.
• Campo explicacao na simulação de GET /jobs/{id} e descrição da flag de baixa rastreabilidade alinhada à regra que a liga.
• Evento explicacao no stream do job.
• Exemplos novos registrados no manifesto.
• DEC-087 com o acesso à explicação conforme as respostas da PO.

Descrição

A etapa de explicação (T-317) grava a narrativa e publica a conclusão. A API (T-318) liga a flag de baixa rastreabilidade, devolve a narrativa na consulta do job e avisa o frontend pelo stream quando a narrativa fica pronta. Esta tarefa define esses contratos.

Contexto e decisões tomadas

• explicacoes guarda a narrativa com aderencia_conferida, que é false quando algum número citado não corresponde ao apurado. A narrativa reprovada é gravada, para o auditor, e não é exibida ao profissional de RH.
• Hoje a descrição de explicacao_id em no-concluido.schema.json diz que o campo fica ausente "quando não houve narrativa utilizável". Com a gravação da reprovada, o campo passa a vir sempre que existe linha em explicacoes, e só fica ausente quando o modelo não devolveu texto.
• A flag fica em simulacoes.flag_baixa_rastreabilidade e já sai em GET /jobs/{id}. A API a liga quando a etapa termina sem explicação ou com a explicação reprovada.
• O evento resultado do stream anuncia a simulação, e a narrativa chega alguns segundos depois. O evento novo explicacao avisa a tela para buscar o job de novo, no mesmo padrão: carrega referências e desfecho, nunca o texto.
• A DEC-087 nega ao profissional de RH, na matriz, o acesso à explicação gerada pela IA para conferência, e o concede na seção de critérios satisfeitos. A versão assumida na T-315 concede o acesso aos dois papéis.

Escopo

Dentro do escopo

• contracts/domain/trilha-conclusao.schema.json, contracts/events/no-concluido.schema.json, contracts/http/openapi.yaml, os exemplos e o manifesto, e docs/decisoes/dec-087.md.

Fora do escopo

• Implementação no codegen, na API e no frontend.
• A explicação na resposta da consulta de auditoria, que já tem a seção explicacoes (T-304).

Requisitos

1. Antes de editar, pedir autorização conforme contract-change (.agents/skills/contract-change/SKILL.md), informando os arquivos, o produtor do evento e da coluna (codegen), os consumidores (API e frontend), a compatibilidade (campos novos e opcionais; descrições alinhadas) e as validações.
2. Em trilha-conclusao.schema.json, acrescentar desfecho_explicacao, descrito como "Nó explicacao", com enum conferida, reprovada, sem_resposta e provedor_indisponivel. A descrição explica cada valor e diz que só conferida produz narrativa exibível.
3. Em no-concluido.schema.json, reescrever a descrição de explicacao_id. O campo vem sempre que a etapa gravou linha em explicacoes, conferida ou reprovada, e fica ausente quando o modelo não devolveu texto. A linha da etapa traz também resultado_id com o resultado explicado.
4. Em comum.schema.json, na descrição de no_grafo, tirar explicacao dos nomes reservados e dizer que a etapa roda depois da decisão, só em simulação com sucesso.
5. Em openapi.yaml, acrescentar à Simulacao o campo opcional explicacao, com texto e criada_em. Ele vem só quando a explicação do resultado vigente foi conferida. Fica ausente enquanto a explicação não chegou, quando ela faltou ou reprovou, e quando o resultado vigente é uma meta aceita.
6. Reescrever a descrição de flag_baixa_rastreabilidade. Ela fica verdadeira quando a etapa de explicação terminou sem texto ou com o texto reprovado na conferência, e falsa enquanto a explicação não chegou.
7. Acrescentar o schema EventoExplicacao (job_id, simulacao_id, disponivel) ao EventoProgresso, documentá-lo na descrição de GET /jobs/{id}/events ao lado de resultado e incluí-lo no exemplo do stream. disponivel é verdadeiro quando a explicação foi conferida.
8. Criar exemplos novos de conclusão e de evento com desfecho_explicacao e registrá-los em contracts/examples/manifesto.json, sem alterar os exemplos existentes.
9. Na DEC-087, ajustar a linha "Acessar explicação gerada pela IA para conferência" e o "Mapa História × Papel" da US05 conforme as respostas da T-315.

Contexto técnico

• Entradas: as respostas da T-315.
• Saídas: os contratos da explicação.
• Componentes afetados: contracts/ e docs/decisoes/.
• Restrições: evolução aditiva; nenhum campo existente muda de tipo ou de obrigatoriedade; o evento do stream não carrega o texto.
• Referências: contracts/domain/trilha-conclusao.schema.json, contracts/events/no-concluido.schema.json, contracts/http/openapi.yaml, api/src/main/resources/db/changelog/changesets/011-cria-explicacoes.sql, DEC-087 (docs/decisoes/dec-087.md), contract-change (.agents/skills/contract-change/SKILL.md).

Critérios de aceitação

• python contracts/validar-exemplos.py passa com os exemplos novos.
• Os exemplos existentes continuam válidos sem alteração.
• Os testes do codegen e da API passam sem mudança de código.

Definição de concluído (DoD)

• Autorização registrada antes da edição.
• python contracts/validar-exemplos.py e git diff --check sem falha, e gate dos quatro componentes verde.