Como contribuir com RFCs — processo e critérios¶

Tipo: Explanation (Diátaxis) — contexto, raciocínio e justificativas
Audiência: contribuidores atuais e futuros do Anotae
Última atualização: 2026-05-19

1. Por que RFCs existem no Anotae¶

O Anotae lida com dados clínicos de pacientes do SUS. Erros de design em três áreas específicas — criptografia, persistência e IA local — podem ter consequências graves e difíceis de reverter:

Criptografia fraca ou quebrada expõe dados de pacientes a acessos não-autorizados, violando a LGPD (Art. 11 — dados sensíveis de saúde) e podendo gerar responsabilização criminal ao desenvolvedor e ao profissional de saúde.
Migrações de schema incorretas podem corromper o vault SQLite silenciosamente, resultando em perda irreversível de registros clínicos.
Modelos de IA mal integrados podem introduzir alucinações clínicas sem aviso adequado, violando o CFM 2.454/2026 e colocando pacientes em risco.

Por isso, o CLAUDE.md §4.1 estabelece:

"Se a feature toca em criptografia, persistência, ou IA local → exigir RFC pública."

O objetivo não é criar burocracia. O objetivo é forçar uma pausa reflexiva documentada antes de mudanças que são difíceis ou impossíveis de desfazer após o vault de um profissional já estar em uso real.

A política de auto-merge¶

Enquanto o projeto opera com bus factor = 1 (um único mantenedor), as RFCs não podem aguardar revisão de um segundo mantenedor para avançar. A política adotada é o auto-merge documentado: o autor aprova a RFC como mantenedor único, registra a justificativa publicamente em docs/rfc/README.md, e abre prazo de 30 dias para revisão pós-fato pela comunidade.

Essa política será revista em v1.0, quando o projeto passa a exigir explicitamente bus factor ≥ 2 por meio de co-mantenedores recrutados.

2. Quando uma RFC é necessária¶

Mudanças que EXIGEM RFC¶

Área	Exemplos concretos
Criptografia	Trocar Argon2id por bcrypt/scrypt/PBKDF2; trocar ChaCha20-Poly1305 por AES-GCM; alterar parâmetros KDF (m, t, p); mudar esquema de derivação de chave do vault
Schema do vault	Qualquer migration que altere tabelas com dados clínicos (`encounters`, `patients`, `attachments`, `audit_log`); mudança no formato de ciphertext armazenado
Modelos de IA	Adicionar novo backend LLM (substituindo ou adicionando ao llama.cpp); adicionar novo modelo ASR; adicionar embeddings diferentes do multilingual-e5-small; alterar prompts com guardrails clínicos
Stack tecnológica	Substituir PySide6 por outro toolkit de UI; adicionar ORM (SQLAlchemy); trocar PyInstaller por outro empacotador; adicionar runtime JS/Rust ao core Python
Protocolo de comunicação	Alterar schema de mensagens NMH; alterar schema de autenticação do HTTP loopback; alterar o manifesto de vocabulários/PCDTs
Telemetria	Qualquer forma de coleta de dados de uso, mesmo opt-in e anônima

Mudanças que NÃO exigem RFC¶

Adição de novos vocabulários clínicos (entradas CIAP-2, CID-10, SIGTAP, RENAME) sem alteração de schema
Melhorias de UI: novos campos visuais, novos atalhos de teclado, novos temas
Novas calculadoras clínicas (anotae/core/calculators/)
Novos templates SOAP curados em vocabularies/templates/
Correção de bugs que não alteram interfaces públicas ou schema
Documentação (qualquer arquivo em docs/)
Testes adicionais
Atualizações de dependências (exceto troca de dependência crítica de criptografia)
Novos subcomandos CLI que não alteram persistência ou criptografia

Regra heurística: se a mudança pode ser revertida sem perda de dados do usuário e sem risco de segurança, não precisa de RFC.

3. Estrutura de uma RFC¶

O template está em docs/rfc/_template.md (a criar). Até sua criação, toda RFC deve conter as seções abaixo.

Cabeçalho obrigatório¶

# RFC-NNN: Título descritivo

| Campo | Valor |
|---|---|
| **ID** | RFC-NNN |
| **Status** | Rascunho |
| **Autor** | Nome do autor |
| **Data de criação** | AAAA-MM-DD |
| **Versão alvo** | vX.Y |
| **Relacionada a** | Issue #NNN (se houver) |

Seções obrigatórias¶

1. Problema / Motivação
Descreve o problema a ser resolvido. Por que a situação atual é insatisfatória? Inclui impacto no usuário final (profissional de saúde SUS).

2. Proposta técnica
Descrição detalhada da mudança proposta. Inclui: - Pseudocódigo ou assinaturas de função para mudanças de API - Diagrama de sequência para mudanças de protocolo - Script SQL de migration para mudanças de schema

3. Alternativas consideradas
Ao menos duas alternativas com trade-offs explícitos. Por que foram descartadas?

4. Análise de segurança e privacidade
Esta é a seção mais importante para mudanças criptográficas ou de IA. Deve cobrir: - LGPD: impacto nos dados sensíveis de saúde (Art. 11); base legal - CFM 2.454/2026: se a mudança afeta geração ou sugestão clínica, como o humano-no-loop é garantido? - STRIDE: para mudanças criptográficas, análise das ameaças Spoofing, Tampering, Repudiation, Information Disclosure, Denial of Service, Elevation of Privilege - Modelo de ameaças: referência ao docs/THREAT-MODEL.md com indicação das ameaças afetadas

5. Critério de aceite
Lista testável de condições que devem ser verdadeiras quando a RFC for considerada implementada. Exemplos: - "Todos os testes de criptografia em tests/unit/test_crypto.py passam" - "Migration 011 aplica e reverte sem erro em banco vazio e banco com dados" - "Output de inferência inclui [IA] no SOAP exportado"

6. Referências
Links para documentação técnica externa, papers, RFCs anteriores relacionadas, issues.

4. Ciclo de vida de uma RFC¶

Rascunho ──→ Em revisão ──→ Aceita ──→ [implementação]
                        └──→ Recusada
                        └──→ Adiada ──→ (retorna ao ciclo em versão futura)

Como submeter¶

Fork do repositório (ou branch rfc/NNN-titulo-curto se você tiver acesso)
Copie docs/rfc/_template.md como docs/rfc/RFC-NNN-titulo-curto.md
Preencha todas as seções obrigatórias
Abra PR com label rfc e título RFC-NNN: Título
A discussão acontece nos comentários do PR — sem canal separado

Transições de status¶

Transição	Condição
Rascunho → Em revisão	Autor declara o conteúdo estável para revisão
Em revisão → Aceita	Bus factor ≥ 2: 2 aprovações + sem objeções abertas; Bus factor = 1: auto-merge documentado
Em revisão → Recusada	Objeção válida não-resolvida; ou autor retira a proposta
Em revisão → Adiada	Tecnicamente válida, mas dependente de feature ainda não implementada
Aceita → Revogada	Objeção válida apresentada dentro do prazo de revisão pós-fato

Período de revisão¶

Bus factor = 1 (atual): auto-merge documentado + 30 dias para revisão pós-fato pela comunidade. O prazo é registrado em docs/rfc/README.md.
Bus factor ≥ 2 (a partir de v1.0): mínimo 30 dias de período de revisão antes de merge; 2 aprovações de mantenedores listados em MAINTAINERS.md.

5. Critérios de avaliação¶

Um revisor deve verificar se a RFC atende a todos os critérios abaixo.

Critérios de bloqueio (rejeição imediata)¶

Viola CLAUDE.md §2 (privacidade): a mudança proposta enviaria dados clínicos para servidor externo, ou removeria criptografia em repouso.
Viola CLAUDE.md §2 (segurança): uso de eval()/exec(), queries SQL com string interpolation, hardcode de credenciais.
Viola CLAUDE.md §2 (compliance): automatiza decisão clínica sem revisão humana obrigatória; implementa auto-prescrição ou auto-diagnóstico.
Adiciona dependência sem justificativa: cada nova dependência é vetor potencial de ataque à supply chain. A RFC deve demonstrar que não há alternativa com dependências já presentes.

Critérios de qualidade (podem gerar pedido de revisão)¶

A análise STRIDE está presente e cobre as ameaças relevantes?
O critério de aceite é testável (sim/não) ou é vago ("melhora a experiência")?
As alternativas consideradas são genuínas, ou foram criadas apenas para justificar a proposta?
A migration de schema é reversível? Há script de rollback?
Os guardrails CFM 2.454/2026 (aviso de IA, humano-no-loop) estão presentes em toda feature que usa IA generativa?

Critério de compatibilidade LGPD¶

Mudanças que alteram onde ou como dados de pacientes são armazenados devem indicar se o RIPD (docs/PRIVACY-IMPACT-ASSESSMENT.md) precisa ser atualizado. Atualização do RIPD é obrigatória antes de v1.0.

6. RFCs históricas¶

#	Título	Status	Versão alvo
RFC-002	Governança SEI multi-instância	Rascunho	v0.9.x → v2.0
RFC-003	Cadastros estruturados Patient + Professional	Aceita (auto-merge 2026-05-06)	v0.9.x
RFC-004	Editor único Markdown + parser SOAP determinístico	Aceita (auto-merge 2026-05-06)	v0.9.x
RFC-005	Attachments cifrados + RAG retrieval-only	Aceita (auto-merge 2026-05-08)	v0.10–v0.11
RFC-006	Sistema LLM local completo	Aceita (auto-merge 2026-05-08)	v0.11–v0.12
RFC-007	Knowledge Pack Hardening (manifest PCDT schema v2)	Aceita	v0.13-1
RFC-008	Modo Consulta Ao Vivo (ASR streaming + rascunho SOAP)	Aceita	v0.15-1
RFC-009	Análise de laudo local (PDF → seção O do SOAP)	Aceita	v0.15-2

Todas as RFCs aceitas tiveram auto-merge documentado enquanto o projeto opera com bus factor = 1. O raciocínio detalhado de cada uma está em docs/rfc/README.md.

Leitura complementar¶

docs/rfc/README.md — lista oficial e histórico de auto-merge
CLAUDE.md §2 — restrições invioláveis de privacidade, segurança e compliance
CLAUDE.md §4.1 — workflow antes de codar feature nova
docs/THREAT-MODEL.md — modelo STRIDE + LINDDUN com 43 ameaças
docs/PRIVACY-IMPACT-ASSESSMENT.md — RIPD (LGPD)
MAINTAINERS.md — taxonomia de mantenedores por área