Checklist de Revisão dos Agentes¶
Use este checklist antes de concluir qualquer alteração. Ele complementa shared-rules.md e workflow.md.
Arquitetura¶
- A alteração preserva Java-only.
- A comunicação federada alvo continua MQTT 5 com TLS/mTLS.
- REST/OpenAPI continua restrito a administração, consulta e monitoramento.
- Hyperledger Fabric continua sendo a camada de auditoria e governança.
- Chaincodes continuam em Java.
- Artefatos grandes continuam off-chain no Artifact Experiment Service, com hash/URI on-chain.
-
BLOCKCHAINpermanece o único modo suportado e falhas do Fabric bloqueiam a operação.
Dados e Experimentos¶
- O experimento materializa dados em
data/{client_id}/{experiment_id}quando aplicável. - O experimento consome dados locais por
DataComponent, não por leitura direta dedataset.csv. - Caminhos de dados, artefatos, runtime e pesquisa são resolvidos por
ExperimentRuntimePathsquando a mudança tocar experimentos. - Dataset de teste contratual usa
EvaluationDatasetSpece não é materializado emdata/{client_id}/{experiment_id}. - O desenho experimental define coorte, target, split, baseline e critérios de parada.
- Há controle explícito de leakage.
- Há preflight local antes do treinamento.
- Há requisitos de amostra mínima, prevalência mínima ou justificativa quando não se aplicarem.
- Toda especificação e código de experimento ficam em
research/.
Aprendizado Federado¶
- Todo
TrainingLocalModeldeclaraMlAlgorithmSpec. -
ClientMlRuntimeSupportbloqueia algoritmo incompatível antes do acesso aos dados. - Updates locais usam
ClientUpdateMessagepor MQTT. - Modelos globais candidatos usam
GlobalModelPublicationpor MQTT. - A agregação exige quórum, valida hash, dimensão, norma, assinatura e duplicatas.
- Há estratégia para dados não-IID e limite de peso por cliente.
- O modelo global é validado localmente antes de promoção no gêmeo digital.
- Quando há dataset de teste contratual, modelos locais e modelo global candidato são avaliados centralmente sem enviar o teste aos clientes.
Runtimes de ML¶
- Android usa
android_javapara algoritmos leves ouandroid_litertpara modelos treináveis. - ONNX Runtime Android não é tratado como runtime de treinamento federado.
- MacBook Pro M4 usa
macos_apple_silicon_javapara algoritmos Java puros oumacos_apple_silicon_djlpara execução/validação. - DJL Apple Silicon não é tratado como treinamento federado sem
trainable_on_clientesupports_federated_update.
Segurança¶
- Dados brutos não saem do cliente.
- Código, contrato, update local e modelo global têm hash verificável.
- Mensagens críticas são assinadas e verificadas antes do processamento.
- Tópicos MQTT são criados por
MqttTopics.*()e têm escopo por experimento, rodada e cliente. - Payloads críticos têm timestamp, nonce, hash e assinatura.
- Logs e telas não expõem dados sensíveis.
- Paths derivados de entrada externa são normalizados e verificados contra uma raiz permitida.
Monitoramento¶
- O monitor continua configurado para porta fixa
8088. - Métricas por rodada usam
RoundLearningMetricssem dados brutos. - Plano de tarefas usa
ComputePlanTaskMonitorquando aplicável. - Série de performances usa
PerformanceMonitorPointquando aplicável. - Simulação Docker expõe
ContainerRunSummaryquandoFEDERATED_CLIENT_EXECUTION_MODE=docker. - Containers de clientes montam apenas
data/{client_id}/{experiment_id}em modo somente leitura. - O monitor exibe aceite/recusa de contrato e assets do ledger quando a mudança tocar governança.
Documentação e Agentes¶
-
backlog.mdfoi criado ou atualizado para a mudança não trivial. - A documentação de componente afetada foi atualizada.
- Índices foram atualizados quando novos arquivos foram criados.
-
.agents/shared-rules.mdfoi atualizado quando uma regra obrigatória mudou. - Arquivos de entrada (
AGENTS.md,CLAUDE.md,codex/*,.github/copilot-instructions.md) continuam apontando para.agents/README.md. - Termos obsoletos foram removidos ou explicados como históricos.
TDD — Test-Driven Development¶
- Todo código de produção novo tem ao menos um caso de teste correspondente em
ArchitectureComponentTestSuiteou arquivo de teste dedicado. - O teste foi escrito antes da implementação (Red → Green → Refactor).
- O novo caso de teste está registrado no
setUp()da suíte comrun("descrição", this::testNome). - O teste passou pelo ciclo Red (falhou antes da implementação) → Green (passou após implementação) → Refactor.
- Casos de borda foram cobertos: entrada nula/vazia, valores-limite, exceções esperadas.
- Para código de segurança: caminho feliz e caminho de falha estão testados.
- Asserts têm mensagem descritiva.
- Nenhum teste depende de ordem de execução ou estado global entre casos.
Validação¶
-
sh scripts/run-tests.shfoi executado ao final — todos os casos passam (incluindo os novos). - Fluxos Docker foram validados com
sh scripts/run-har-experiment-docker.shquando a mudança tocar simulação de clientes. - O monitor foi verificado em
http://127.0.0.1:8088quando a mudança tocar interface web.