ADR-0026: Trava de design da calibração do juiz

Documentação de referência: não é um dispositivo médico

Esta documentação descreve uma implementação de referência avaliada com dados 100% sintéticos. É uma referência de capacidades e prontidão, não uma certificação de conformidade nem aconselhamento jurídico, e não é um dispositivo médico. Não é clinicamente validada e não manipula PHI de produção.

• Status: Accepted
• Data: 2026-06-13
• Responsáveis pela decisão: Waldemar Szemat

Contexto e definição do problema

O arcabouço de avaliação (ADR-0003) pontua duas de suas dimensões de rubrica - fundamentação e fidelidade - com um LLM como juiz. Um juiz só é confiável depois que alguém mediu o quão bem ele concorda com um humano sobre os mesmos casos. Por isso o arcabouço adiciona um portão de calibração: para cada caso de calibração um humano atribui um rótulo e o juiz produz uma pontuação, e a concordância entre eles é medida por dimensão com um kappa de Cohen ponderado.

Uma métrica de calibração só é crível se seu enquadramento, seus bins, seu limiar e a composição de seu corpus forem fixados ANTES de rotular ou pontuar qualquer caso. Se algo disso puder se mover depois que os números estão dentro, a afirmação de concordância se torna infalseável: um resultado baixo sempre poderia ser “consertado” empurrando um bin, baixando a régua ou descartando a dimensão inconveniente. Isso é manipulação do limiar disfarçada de ajuste, e esvazia todo o propósito do portão.

Este registro roda primeiro, de propósito, para que cada fase posterior - a métrica e seu esquema, a passagem de rotulagem humana, a execução única do juiz e a fiação do portão - herde as mesmas constantes congeladas e a mesma nomeação. Como travamos cada decisão de enquadramento, métrica, bin, limiar e corpus para o portão de calibração, em um só lugar, antes de qualquer rotulagem ou pontuação começar, de modo que nenhum ajuste posterior possa resgatar retroativamente a afirmação de concordância?

Fatores de decisão

• Trava anterior aos dados. Cada constante que poderia ser ajustada depois do fato é fixada antes de a primeira etiqueta ser escrita. O congelamento é a credibilidade, não um acréscimo.
• Enquadramento honesto. A métrica mede um avaliador humano contra o juiz. Ela deve ser nomeada e descrita exatamente assim, para que nenhum leitor a confunda com um número de confiabilidade multi-avaliador que ela não é.
• Reprodutibilidade. Um número de concordância replicável supera um oculto: quem tiver acesso à implementação de referência (disponível sob solicitação) deveria poder recomputá-lo.
• Preservação de invariantes. O portão lê apenas as saídas do juiz e nunca altera o juiz (ADR-0003); o invariante de corpus somente sintético (ADR-0018) se mantém.
• Realismo de amostra pequena. O corpus de calibração é deliberadamente pequeno, então cada escolha é dimensionada para um regime de amostra pequena onde um limiar apertado demais simplesmente oscilaria.

Opções consideradas

• Enquadramento: concordância humano-vs-juiz de um único avaliador (escolhida) frente a confiabilidade entre anotadores com múltiplos anotadores (rejeitada: há um único avaliador proprietário por design; um pipeline multi-anotador está fora de escopo e descreveria mal o que o número mede).
• Portão por locale: um portão agrupado com diagnósticos por locale (escolhida) frente a um portão separado por locale (rejeitada: triplica a rotulagem e torna cada estimativa por locale de amostra pequena e propensa a oscilar) frente a portão somente em inglês (rejeitada: deixa es-419 e pt-BR sem portão).
• Visibilidade do corpus: um corpus de calibração comprometido e totalmente visível (escolhida) frente a retê-lo (rejeitada: esconde a reprodutibilidade que é todo o valor) frente a uma amostra parcialmente visível (rejeitada: uma divisão arbitrária sem justificativa limpa).
• Bins: congelar as fronteiras agora como constantes semânticas (escolhida) frente a colocá-las empiricamente a partir de uma execução de distribuição do juiz anterior à rotulagem (rejeitada: atrasa a trava e convida a ajustar os bins aos dados).
• Estratificação: uma mistura realista de produção (escolhida) frente a uma mistura balanceada ou de terços iguais (rejeitadas: nenhuma reflete a distribuição de pontuações que uma mudança real produz).

Resultado da decisão

Opções escolhidas, travadas antes de qualquer rotulagem:

• Enquadramento - concordância humano-vs-juiz de um único avaliador. A métrica é a concordância entre um avaliador humano e o juiz, por dimensão. Ela não é confiabilidade entre anotadores e nunca é descrita como tal: há um único avaliador proprietário por design, então não há um segundo anotador contra o qual ser confiável. Os rótulos de saída da métrica carregam um nome que fixa o enquadramento humano-vs-juiz, de modo que ele não pode derivar para linguagem de confiabilidade em nenhum relatório posterior.
• Métrica - kappa de Cohen com ponderação linear. A concordância é um kappa de Cohen com ponderação linear (scikit-learn, já presente nas dependências de avaliação, então sem nova dependência de execução). A ponderação linear dá crédito parcial a uma discordância de um bin de diferença, o que convém a bins ordenados.
• Dimensões. São calibradas as dimensões apoiadas pelo juiz que bloqueiam uma mudança: fundamentação e fidelidade. O método é depois estendido às dimensões de segurança, que se tornam bloqueadoras do lançamento em vez de sinais de aviso (ver o registro de calibração de escalonamento / autolesão); esta trava de design é o método que essas herdam.
• Bins - constantes semânticas congeladas. A pontuação contínua de cada dimensão é mapeada em três bins ordinais - infiel / parcial / sólido - cujas fronteiras são congeladas agora como constantes semânticas, alinhadas com a leitura de Landis-and-Koch da força de concordância e fixadas sem nenhuma execução de distribuição anterior à rotulagem. Um relatório marginal por bin produzido depois é apenas uma verificação confirmatória; ele não tem autoridade para mover uma fronteira.
• Limiar - congelado antes dos dados. O portão bloqueia quando a concordância agrupada de uma dimensão com portão cai abaixo de um limiar fixo, dimensionado para o regime de amostra pequena e mantido distinto de um colchão de média de corpus ligeiramente superior ao qual o corpus mira, para que o ruído de amostragem não empurre um juiz genuinamente calibrado abaixo da régua. O limiar é congelado antes dos dados; elevá-lo está fora de escopo até que existam mais rótulos, porque neste tamanho de amostra uma régua apertada demais oscilaria. O ponto de operação em si é calibrado por implantação e provido como parte do engajamento.
• Portão por locale - portão agrupado, diagnósticos por locale. Um único kappa agrupado por dimensão sobre todo o corpus multi-locale é o único número bloqueante. Os kappa por locale de es-419 e pt-BR são reportados como diagnósticos não bloqueantes - ruidosos mas direcionais em suas contagens por locale, e rotulados como diagnósticos, não como portão. A direção é deliberada e não deve inverter. Um locale pode ser promovido de diagnóstico a com portão em um marco futuro assim que acumular casos rotulados próprios suficientes.
• Corpus - somente sintético, comprometido e visível. O corpus de calibração - os casos, os rótulos humanos e as pontuações do juiz pré-comprometidas - é somente sintético (ADR-0018) e totalmente visível no repositório, então a concordância é reproduzível de forma independente a partir do corpus comprometido por quem tiver acesso à implementação de referência (disponível sob solicitação). Seu tamanho e estratificação exatos são resolvidos no registro de reequilíbrio de corpus.
• O remédio travado ante o paradoxo de kappa. Uma mistura realista de produção produz marginais enviesadas, e marginais enviesadas podem render um kappa baixo apesar de uma alta porcentagem de concordância bruta - o paradoxo de kappa. Esse risco é aceito, e o remédio é travado: se o corpus comprometido cair no paradoxo, o ÚNICO conserto permitido é reequilibrar o corpus - acrescentar casos borderline e de falha, rerotular, repontuar. Baixar o limiar, mover uma fronteira de bin ou descartar uma dimensão com portão é proibido. As constantes ficam congeladas independentemente do número observado; o reequilíbrio é a única alavanca.
• Retaguarda de detecção. O relatório de calibração carrega, juntos, a estimativa pontual por dimensão, um intervalo de confiança por bootstrap, a distribuição marginal por bin e a porcentagem de concordância bruta. Ler esses quatro juntos distingue uma miscalibração genuína de um paradoxo por viés marginal e encaminha um paradoxo ao reequilíbrio do corpus em vez de a uma edição de fronteira ou limiar.
• Disciplina de ancoragem de rótulos. Os rótulos humanos são comprometidos em um commit anterior ao das pontuações do juiz, então o julgamento humano precede de forma demonstrável a execução do juiz; em cada caso o carimbo de tempo do rótulo humano precede o da pontuação do juiz. Os rótulos não podem ser ajustados a posteriori ao juiz.
• Reafirmação de invariantes. O portão lê apenas as saídas do juiz e não faz nenhuma mudança ao juiz (ADR-0003); o corpus se mantém somente sintético (ADR-0018).

Confirmação

• O número de concordância é falseável: cada constante que poderia ser ajustada depois do fato é fixada antes do primeiro rótulo, e a verificação de vazamento se mantém verde com o corpus de calibração comprometido presente.
• A métrica não adiciona nenhuma nova dependência de execução.
• As fases posteriores leem as constantes congeladas e a nomeação travada deste registro; os bins, o limiar e as dimensões ficam fixados.

Consequências

Positivas

• A afirmação de concordância é falseável e crível: um kappa baixo não pode ser fabricado em silêncio, porque nenhuma constante pode se mover depois que os dados estão dentro.
• A concordância é reproduzível a partir do corpus comprometido: quem tiver acesso à implementação de referência (disponível sob solicitação) pode recomputar a mesma concordância sobre os mesmos casos, rótulos e pontuações comprometidos.
• A nomeação é travada uma vez e se propaga sem ambiguidade por cada superfície de saída posterior.
• O juiz fica intacto: o portão lê apenas as saídas do juiz.

Negativas

• O corpus de calibração comprometido precisa ser reconfirmado contra a verificação de vazamento em vez de se apoiar em uma exclusão padrão.
• A mistura realista de produção carrega o risco aceito do paradoxo de kappa, cuja única resposta sancionada é o reequilíbrio do corpus, comparativamente caro.
• Congelar os bins e o limiar antes dos dados significa que eles não podem ser reajustados à distribuição observada mesmo que depois pareça estranha; o congelamento é o ponto, mas remove essa alavanca de propósito.

Neutras

• O modo de ativação do corpus (auto-ao-estar-presente frente a um caminho de opt-in) é resolvido em um registro posterior, não aqui.
• Elevar o limiar com mais rótulos, e promover um diagnóstico por locale a um locale com portão, são passos futuros documentados, não compromissos presentes.

Prós e contras das opções

Enquadramento humano-vs-juiz de um único avaliador (escolhida)

• Bom, porque descreve exatamente o que o número mede: um avaliador humano contra o juiz.
• Bom, porque a nomeação travada mantém o enquadramento legível em cada superfície.
• Ruim, porque um único avaliador carrega o viés desse avaliador sem um segundo anotador para fazer a média.

Confiabilidade entre anotadores (rejeitada)

• Bom, porque múltiplos anotadores quantificariam a discordância humana diretamente.
• Ruim, porque há um único avaliador proprietário por design, então não há nada contra o qual ser confiável, e o pipeline descreveria mal o número.

Portão agrupado, diagnósticos por locale (escolhida)

• Bom, porque um portão agrupado é viável de rotular e estável o bastante para bloquear, enquanto cada locale ainda recebe um sinal.
• Ruim, porque um portão agrupado pode mascarar uma regressão de um único locale que os ruidosos diagnósticos por locale apenas insinuam.

Corpus de calibração comprometido e totalmente visível (escolhida)

• Bom, porque uma concordância replicável é mais crível que uma oculta, e o corpus é somente sintético então não há preocupação de privacidade.
• Ruim, porque precisa ser reconfirmado contra a verificação de vazamento.

Bins semânticos congelados (escolhida)

• Bom, porque os bins são semânticos, não ajustados à distribuição, então podem ser fixados sem dados e fecham o ajuste posterior.
• Ruim, porque uma fronteira semântica pode não se alinhar perfeitamente com onde o juiz agrupa suas pontuações.

Mais informações

• ADR-0003: Arcabouço de avaliação - o juiz cuja concordância este portão mede, e os invariantes do juiz que o portão lê mas nunca altera.
• ADR-0018: Invariante de dados somente sintéticos - por que o corpus de calibração comprometido e totalmente visível é seguro de incluir no repositório.
• ADR-0027: Reequilíbrio do corpus de calibração - o tamanho e a estratificação exatos do corpus que esta trava de design deixa deliberadamente em aberto.
• ADR-0031: Calibração com portão de escalonamento e autolesão - onde o método é estendido às dimensões de segurança como bloqueadoras do lançamento.
• Landis e Koch, “The Measurement of Observer Agreement for Categorical Data,” Biometrics, 1977: https://www.jstor.org/stable/2529310
• MADR 4.0.0: https://adr.github.io/madr/