Ir para o conteúdo

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.
  • BLOCKCHAIN permanece 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 de dataset.csv.
  • Caminhos de dados, artefatos, runtime e pesquisa são resolvidos por ExperimentRuntimePaths quando a mudança tocar experimentos.
  • Dataset de teste contratual usa EvaluationDatasetSpec e não é materializado em data/{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 TrainingLocalModel declara MlAlgorithmSpec.
  • ClientMlRuntimeSupport bloqueia algoritmo incompatível antes do acesso aos dados.
  • Updates locais usam ClientUpdateMessage por MQTT.
  • Modelos globais candidatos usam GlobalModelPublication por 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_java para algoritmos leves ou android_litert para modelos treináveis.
  • ONNX Runtime Android não é tratado como runtime de treinamento federado.
  • MacBook Pro M4 usa macos_apple_silicon_java para algoritmos Java puros ou macos_apple_silicon_djl para execução/validação.
  • DJL Apple Silicon não é tratado como treinamento federado sem trainable_on_client e supports_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 RoundLearningMetrics sem dados brutos.
  • Plano de tarefas usa ComputePlanTaskMonitor quando aplicável.
  • Série de performances usa PerformanceMonitorPoint quando aplicável.
  • Simulação Docker expõe ContainerRunSummary quando FEDERATED_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.md foi 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.md foi 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 ArchitectureComponentTestSuite ou 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 com run("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.sh foi executado ao final — todos os casos passam (incluindo os novos).
  • Fluxos Docker foram validados com sh scripts/run-har-experiment-docker.sh quando a mudança tocar simulação de clientes.
  • O monitor foi verificado em http://127.0.0.1:8088 quando a mudança tocar interface web.