Desvio controlado da especificação (S)

Ponto de vista: IMP — Implementação · Autoridade documental: ESP (histórias aprovadas), GTI (ADR, RFC), PDP/GDA quando aplicável — o implementador não substitui essa autoridade; registra desvios e propostas de forma rastreável.

Este texto disciplina o que ocorre quando, durante a implementação, surgem lacunas, contradições ou ajustes ainda não refletidos nos artefatos oficiais (histórias ESP, ADR, SDD/INF conforme o projeto, PRD/BRD, RFC). O objetivo é impedir que o código ou notas soltas passem a ser verdade silenciosa sem trilha nem aprovação competente.

1. Diagnóstico do encaixe no SinergIA

Área existente	Como reutilizar
Critério de divergência obrigatória (IMP/ESP)	Escalada ao Validador Técnico quando há conflito entre engines ou impacto em segurança, dados pessoais, negócio crítico ou Nível 3 de autonomia — complementa, não substitui, o registro de desvio face à especificação aprovada.
RFC e ADR (GTI)	RFC: debate e questões abertas antes de consolidar decisão; ADR: decisão arquitetural/institucional versionada. Durante a implementação, um desvio com impacto arquitetural ou normativo deve encadear-se aqui, não ficar só no PR.
IRA (SIS)	Análise de efeito em cadeia; obrigatório quando a classificação de impacto (tabela abaixo) o exigir, antes de promover mudança relevante.
Fluxo de vida das histórias	Estados `rascunho` → `refinado` → `aprovado` → `implementado`; a política de pendência documental (secção 7) usa metadados e evidências sem obrigar novo estado no diagrama até o órgão decidir política própria.
DOD	Continua a definir “pronto”; inclui critérios explícitos quando há implementação sob pendência documental resolvida ou explicitamente aceite pelo GTI.
CHG	Cada release deve referenciar histórias e desvios materializados nessa versão (ligação a notas/RFC/ADR).
Linter de Governança e Artefato Orquestrador	Conformidade documental e gates; ver secção 7 (automatização) para verificações adicionais recomendadas.

2. Lacunas do modelo anterior (o que esta página fecha)

Antes desta norma, o framework já exigia rastreabilidade, divergência obrigatória em casos sensíveis e RFC/ADR para decisões — mas não descrevia de forma única: (a) onde registrar proposta provisória do implementador; (b) quando pode codificar antes da aprovação definitiva da documentação oficial; (c) como segregar verdade provisória da oficial; (d) quais classes de impacto disparam proposta formal (RFC/ADR/IRA) vs ajuste local.

3. Proposta de mecanismo

Desvio controlado é qualquer implementação ou alteração de comportamento que não reproduz fielmente a história ESP (ou documento oficial vinculado) no momento da alteração, desde que:

A lacuna ou mudança é classificada (tabela da secção 9).
Existe registro provisório (nota de desvio + vínculos) em IMP/04-evidencias/ ou pasta equivalente acordada — nunca misturado com texto normativo “aprovado” do ESP/GTI sem passagem por revisão.
O PR e os commits referenciam o ID da história e o identificador da nota de desvio (ou RFC/IRA).
A promoção a homologação/produção respeita os bloqueios da classificação (tabela).
A consolidação: após aprovação da autoridade competente, a história oficial (ou ADR/RFC convertido) é actualizada e a pendência é fechada ou a implementação é revertida se a proposta for rejeitada.

Documentação oficial — histórias ESP em estado aprovado ou implementado com critérios de aceite vigentes; ADR/RFC/DOM/etc. com status de aprovação definido pelo GTI ou papel competente; documentos INF/PDP/GDA nos trilhos já previstos no framework.

Documentação provisória do implementador — notas de desvio, rascunhos de RFC colocados no ramo de trabalho, comentários de PR e anexos explicitamente etiquetados como provisórios; não prevalecem sobre a oficial até promoção documental.

Quem cria	Quem aprova “oficial”
Implementador / agente de IMP	Nota de desvio: Validador Técnico (revisão mínima); RFC/ADR: GTI ou fluxo já definido no artefato
PO / arquitetura	Histórias ESP e documentos estruturantes ESP

Expiração / absorção: a provisória absorve-se quando a história (ou ADR) oficial incorpora o conteúdo e a pendência é removida dos metadados; rejeita-se revertendo código ou emitindo decisão registrada (RFC rejeitado ou ADR que explícita manutenção do desenho anterior). Prazos máximos são política do órgão (sugestão: não ultrapassar um ciclo de release sem decisão para classes médias/altas).

4. Fluxo operacional detalhado

stateDiagram-v2
    direction LR
    [*] --> Identificar: lacuna_ou_contradicao
    Identificar --> Classificar: tabela_impacto
    Classificar --> AjusteLocal: classe_A_ou_B
    Classificar --> PropostaFormal: classe_C_a_F
    AjusteLocal --> RegistroMinimo: evidencia_IMP
    PropostaFormal --> DocProvisoria: nota_RFC_IRA
    DocProvisoria --> Implementar: PR_commits
    Implementar --> GateCI: linter_pipeline
    GateCI --> Homologacao: se_permitido_pela_classe
    Homologacao --> DecisaoAutoridade: aprovar_ou_rejeitar
    DecisaoAutoridade --> Consolidar: atualizar_ESP_ADR
    DecisaoAutoridade --> Reverter: rollback_ou_refinamento
    Consolidar --> [*]
    Reverter --> [*]
    RegistroMinimo --> [*]

Passos narrados:

Identificar lacuna ou contradição durante codificação ou revisão cruzada.
Classificar pela tabela (secção 9); em dúvida razoável, subir um nível (ex.: tratar como “reflexo documental restrito” em vez de “só local”).
Se proposta formal for obrigatória: abrir ou atualizar RFC (debate) ou IRA (impacto) conforme já definido nos artefatos; quando fechada, ADR (ou atualização de história ESP) conforme o caso.
Criar documentação provisória: arquivo IMP-EVD-*--desvio-<HIST-ID>.md (ou convenção equivalente) com: data, autor, descrição do desvio, classificação, links PR/commit, história ESP afetada, consequência se rejeitado.
Implementar no ramo; mensagens de commit com ESP-… e referência à nota/RFC.
Gates: CI/CD IMP + Linter; produção só se a tabela permitir e política do órgão não exigir bloqueio adicional.
Autoridade documental decide; consolidação actualiza ESP/ADR e fecha pendências nos YAML; reversão se rejeitado.

5. Regras normativas sugeridas

Responsabilidades

Implementador: classificar, registrar o documento provisório (nota de desvio), não apresentar nota provisória como “aprovada”; escalar quando a classificação for ≥ reflexo documental restrito em caso de dúvida.
Validador Técnico: validar classificação em PRs sensíveis; bloquear promoção quando a política e a tabela exigirem ADR/RFC fechado.
PO / GTI: aprovar alterações à especificação oficial e fechar RFC/ADR.

Critérios de bloqueio (exemplos)

Promoção a produção com mudança arquitetural ou de dados sem ADR (ou extensão oficial) aprovado, quando a tabela assim o exige.
PR que altera contrato de API público sem história ou RFC/IRA vinculados, conforme classe.

Critérios de promoção

DOD cumprido; Linter verde ou exceção documentada pelo GTI; pendências documentais explicitadas e, quando exigido pela classe, resolvidas antes do gate correspondente.

Tratamento de pendências documentais

Listar no YAML da história (campo opcional pendencias-documentais) ou em evidência única indexada — ver fluxo de vida das histórias (secção Implementação com pendência documental).

6. Ajustes por artefato (referência cruzada)

Artefacto	Ajuste esperado no uso
RFC	Abrir durante implementação quando houver incerteza ou impacto além de ajuste local; PR deve citar `GTI-RFC-…` em rascunho ou branch até conversão.
ADR	Consolidação da decisão após debate; código em produção com decisão arquitetural depende de ADR aprovado quando a tabela exige.
PRD / BRD / SDD / histórias ESP	Actualização oficial após aprovação; até lá, nota de desvio + ligação.
Fluxo de vida / DOD	Ver links nas páginas atualizadas.
CHG	Mencionar desvios relevantes na entrada da versão.
Linter / Orquestrador	Políticas adicionais em Linter e Orquestrador.

7. Estados e gates

Política recomendada (A): manter os estados actuais do diagrama oficial e representar implementação à frente da documentação via pendencias-documentais no frontmatter da história (lista de IDs de notas/RFC) e evidências em IMP/04-evidencias/. O estado implementado só é atingido quando o DOD for satisfeito incluindo a política de pendências para aquela classe (pendência resolvida ou explicitamente aceite pelo GTI para ambientes não produtivos, se o órgão permitir).

Política alternativa (B): o órgão pode introduzir um subestado ou estado implementado-pendente-doc no YAML — exige alteração coordenada do diagrama, do Linter e dos relatórios do Orquestrador. Só adoptar se for necessário um gate duro por valor de status.

Efeito no fluxo: não altera a lógica central (ESP como unidade de aceite; GTI como decisão); acrescenta transparência e bloqueios objetivos por classe de impacto.

8. Regras automatizáveis

Ver a secção Coerência código, especificação e desvios em Linter de Governança. Em resumo, o órgão pode automatizar:

presença de ID ESP-* em título ou corpo do PR quando há alteração em pastas de produto;
label pendencia-documental quando o PR referencia nota de desvio;
falha de pipeline se diff de API não tiver ligação a RFC ou história;
bloqueio de merge para main/produção se política exigir ADR fechado para alterações em caminhos sensíveis (lista definida pelo projeto).

O Linter documental não substitui revisão humana de equivalência semântica entre código e requisito.

9. Tabela de classificação de impacto

Classe	Descrição	Proposta formal obrigatória?	Artefacto a atualizar (oficial)	Quem aprova consolidação	Produção antes da aprovação final?
A — Ajuste técnico local	Refactor interno, nomes, formatação, testes sem mudar contrato nem aceite	Não	Nenhum além de commit/PR	N/A	Sim, se DOD e pipeline OK
B — Reflexo documental restrito	Pequeno ajuste de comportamento já implícito na história mas mal especificado (clarificação sem novo requisito)	Não, mas registro provisório obrigatório	Complementar descrição/critérios na mesma história (versão)	PO ou delegado ESP	Sim, com registro e revisão em PR
C — Mudança funcional	Novo comportamento ou alteração de critério de aceite	Sim — história a refinhar/reaprovar ou nova `H*` conforme tipos de demanda	História ESP (+ BRD/PRD se forem fonte de verdade do projeto)	PO / GTI conforme política	Não para comportamento novo face ao `aprovado` vigente — apenas ambientes inferiores até reaprovação, salvo dispensa GTI
D — Mudança arquitetural	Stack, padrões transversais, integrações estruturais	Sim — RFC → ADR (ou ADR directo se sem debate)	ADR GTI (+ INF se aplicável)	Validador Técnico + GTI	Não sem ADR aprovado
E — Mudança de dados	Modelo persistido, ERD, migrações com efeito em domínio	Sim — IRA + GDA quando couber	ERD/DOM/ADR de dados conforme impacto	GDA + Validador Técnico	Não sem consolidação nos artefatos de dados
F — Segurança, privacidade, conformidade	AuthZ/AuthN, PDP, logs com dado pessoal, conformidade legal	Sim — RFC ou ADR + artefatos PDP quando aplicável	ADR, RIPD, histórias HC/HAI conforme caso	Validador Técnico, Encarregado, GTI	Não — alinhar a divergência obrigatória e Nível 3

Se uma mudança tocar mais de uma classe, prevalece a mais restritiva.

10. Exemplos práticos

Cenário 1 — Ajuste técnico pequeno

Renomear variável interna e extrair função sem alterar API ou regras de negócio. Classe A. Commit com refactor: ESP-HNU-0001 — extrai validador. Sem nota de desvio se o órgão não exigir registro para A; se exigir, uma linha na evidência de sprint basta.

Cenário 2 — Ajuste funcional descoberto na implementação

Durante os testes, verifica-se que o campo “telefone” devia ser opcional mas a história dizia obrigatório; negócio confirma que opcional é o correcto. Classe B ou C: se for só clarificação alinhada à intenção já aprovada, B com nota de desvio + atualização de versão da história em refinamento rápido; se mudar SLAs ou jornada, C com reabertura/refinamento e sem produção até história aprovado reflectir o critério.

Cenário 3 — Mudança arquitetural tardia

Descobre-se que o serviço síncrono não cumpre SLA e propõe fila + worker. Classe D. Abrir RFC com questões (infra, custo, operação); após consenso, ADR; IRA se propagar a vários módulos; implementação em ramo com PRs ligados; sem promoção a produção até ADR aprovado e histórias/INF atualizadas conforme decisão.

11. Plano de implementação incremental (no projeto)

Adotar convenção de arquivos de nota de desvio em IMP/04-evidencias/.
Exigir no template de PR os campos: história ESP, classe (A–F), link nota/RFC se ≠ A.
Configurar labels e regras de branch no repositório de código.
Estender o Linter/Orquestrador quando existir implementação técnica desses componentes.

Ver também: Modelo de Construção · Rastreabilidade integral · Tipos de demanda

← CI/CD — Operacionalização · Visão Geral IMP →