O Portão da Compreensão: Transformando o Entendimento Humano em Restrição de Engenharia

O post anterior tratou a compreensão como um problema de medição. Este é o que aconteceu quando parei de tratá-la assim e construí o instrumento. Três semanas depois de publicar o conceito, aqui está o primeiro mapa de cobertura de compreensão de um repositório que eu mesmo mantenho — boleto.ts, uma pequena biblioteca TypeScript para boletos brasileiros, desenvolvida predominantemente por meio de código mediado por agentes ao longo dos últimos nove meses: dos 42 commits que tocam seu diretório de código-fonte, 29 carregam a autoria de um agente — o agente de código Copilot do GitHub, em sua maioria, com agentes da Anthropic por trás de vários outros.

Quatro de seis módulos estão escuros: nenhum humano registrado detém compreensão atual e comprovada sobre eles. Os dois que escaparam estão apenas EM RISCO (AT_RISK). E o mapa esconde sua melhor descoberta naquela palavra "compreendedor", à qual eu chegarei — porque a única entidade que o instrumento atualmente reconhece como responsável por manter o módulo assinatura da biblioteca fora da escuridão não sou eu, e não é uma pessoa.

O instrumento é o comprehension-coverage, open source desde esta semana: uma especificação, uma implementação de referência em Python e uma CLI em Kotlin que reproduz a referência byte a byte. Tudo o que é citado neste post é saída real de execuções registradas — o repositório fixa os commits, as configurações e as invocações exatas.

O que conta como evidência — e o que é apenas atividade

O mapa é construído a partir de eventos de evidência, não de impressões. Na v0.1, um evento é uma de três coisas extraídas do histórico puro do git: autoria manual, autoria mediada por agente (detectada por trailers de co-autoria e identidades de bot, e descontada — instruir um agente constrói alguma teoria, mas a pesquisa sobre a lacuna de compreensão diz que nem de longe tanto quanto escrever você mesmo) e atestações explícitas — um registro assinado de que uma pessoa percorreu novamente um módulo.

O que não rende nada: fazer merge do diff de um agente sem ler, assistir aos tokens sendo transmitidos, ter seu nome no repositório. A especificação é direta sobre o que isso significa para as afirmações do instrumento, e a frase que carrega o peso filosófico é a decisão constitucional C2: a ferramenta é "um detector de evidências com um modelo explícito de obsolescência, nunca um detector de compreensão". Ela não afirma saber do que alguém se lembra. Ela calcula quão obsoleta a evidência disponível de lembrança se tornou. Tudo de honesto e tudo de errado que o mapa diz decorre dessa distinção.

Como a evidência decai

A evidência apodrece em dois relógios. O relógio primário é o churn: a compreensão de um módulo que foi reescrito debaixo de você está obsoleta, não importa o que diga o calendário. O relógio secundário é o próprio tempo, porque a pesquisa sobre a curva do esquecimento é inequívoca ao afirmar que a teoria desvanece mesmo quando o código permanece parado. A pontuação cai pela metade a cada volume de churn equivalente a uma reescrita completa desde a evidência, com uma meia-vida de tempo corrido como piso.

A parte interessante é que a primeira execução real discutiu com a especificação e venceu. A especificação provisória fixava a meia-vida de tempo corrido em 180 dias, de forma plana. Executada contra uma década de histórico do expressjs/express como ensaio geral, esse piso produziu um falso positivo óbvio: apagou a posição de um contribuidor cujo módulo praticamente não havia mudado desde seu trabalho substancial nele — antigo e estático estava sendo punido como antigo e sobrescrito, exatamente o oposto da intenção do projeto. A correção que sobreviveu ao experimento é um piso escalado por quiescência: a meia-vida de tempo corrido se estende até o triplo conforme um módulo fica quieto, e volta à taxa base conforme o churn se aproxima de uma reescrita completa. A alternativa — simplesmente alongar o piso plano para 540 dias — foi rejeitada por um motivo que os dados do express sozinhos não poderiam mostrar: ela também concede um alívio de decaimento de 2,16× a evidências que o módulo já eliminou por churn, o que silenciosamente rebaixa o churn de relógio primário a sugestão. Todo o experimento — variantes, pontuações, a opção rejeitada e o porquê — é público no CALIBRATION.md do repositório, e a mudança entrou como um commit citando a execução que a forçou. Os parâmetros seguem provisórios. O processo para alterá-los, não.

O módulo escuro, rastreado

Tome o itf — o codificador de código de barras interleaved 2 of 5, um dos dois módulos que marquei como críticos, e o que bloqueia o portão. A saída de remediação da própria ferramenta, na íntegra:

Leia a linha do meio novamente. Ao ser perguntado quem por último deteve evidência de compreensão deste módulo, o instrumento responde com o nome de um bot. O rastro por trás disso confere com o histórico bruto: a evidência de 137 dias é um lote de commits de abril de 2026 feitos pelo agente de código Copilot do GitHub, que retrabalhou itf.ts, helpers.ts e svg.ts em uma única passada — e é por isso que três módulos compartilham a mesma linha de evidência mais forte. A evidência mais forte do módulo main é mais recente, 83 dias, e pertence a um commit escrito diretamente por um agente da Anthropic, carregando seu próprio trailer de co-autoria. Ambos os caminhos de detecção de agente — identidade de bot e trailer — estão disparando sobre histórico real, e o que eles revelam é uma biblioteca cuja vida registrada inteira, em alguns módulos, é atividade de agente: evidência descontada decaindo sem ninguém reevidenciando por trás.

E eu? Eu conduzi cada uma dessas sessões com agentes. Revisei os pull requests. Fiz os merges. O mapa não registra nada disso — no boleto, o módulo que justifica a existência desta biblioteca, não há nenhum evento de evidência sob minha identidade. Não decaído: ausente. Minha contribuição real a este código — prompts, revisões, decisões de merge — acontece em classes de evidência que a v0.1 não ingere. Guarde esse pensamento.

Onde o instrumento está errado

Os critérios de aceitação da especificação exigiam que o primeiro teste de campo produzisse pelo menos um resultado que o dono do repositório pudesse refutar a partir da verdade de campo — não esperavam por um, exigiam. Ele produziu dois, e eles se entrelaçam.

O primeiro: boleto está EM RISCO em vez de ESCURO porque tem exatamente um compreendedor — copilot-swe-agent[bot], pontuando 0,7218 contra um limiar de 0,5. Uma identidade de bot acumulou evidência de autoria descontada suficiente para se qualificar como compreendedor. Este é o modelo executando fielmente suas próprias regras até o absurdo: a evidência mediada por agente é descontada porque um agente não detém teoria transferível em que uma equipe possa se apoiar às 3 da manhã — e, ainda assim, nada na v0.1 impede que a própria identidade do agente cruze a linha. A consequência é pior do que cosmética. O portão falha apenas em ESCURO por padrão, então, se o itf não estivesse na lista de críticos, uma mudança de agente no meu módulo de código de barras de pagamento entraria com merge sob um portão verde cujo único "compreendedor" de sustentação é o Copilot. A falha está registrada no repositório como uma issue, deliberadamente marcada como não corrigir até que esta execução tenha sido reportada — o primeiro teste de campo do instrumento merecia ser observado honestamente, não higienizado em um sucesso.

A segunda falha é a imagem espelhada, e o post do conceito a previu: eu sou a pessoa que mais plausivelmente detém a teoria desta biblioteca, e pontuo perto de zero em todo lugar, exceto nos testes. O ensaio geral no express revelou o mesmo padrão primeiro — mantenedores atuais que demonstravelmente entendem aquele código, porque revisam cada mudança consequente e conduzem as releases, pontuam quase nada nos módulos centrais. As pessoas que entendem código hoje cada vez mais revisam; a v0.1 só vê autoria. É aqui que "evidência de compreensão não é compreensão" deixa de ser uma ressalva e se torna um princípio de projeto: ambas as falhas são classes de evidência ausentes, não limiares mal calibrados. A correção para o bot é excluir identidades de agente das contagens de compreendedores; a correção para mim é uma classe de evidência REVIEWED alimentada pela forge, cuja interface a especificação já reserva. Nenhuma das duas correções é um número mais brando. A ferramenta pode errar de maneiras que o conceito sobrevive — desde que erre em voz alta, em público, com a falha nomeada.

O portão

O que um pipeline de CI faz com esse mapa? A política que executo tem três cores. VERDE: os módulos tocados têm um compreendedor atual; nada muda. ÂMBAR: a cobertura é rala ou obsoleta; um compreendedor designado entra na revisão — o mapa se torna uma regra de roteamento. VERMELHO: o módulo está escuro; mudanças de agente não podem ser mescladas até que alguém reestabeleça a compreensão — percorrendo genuinamente o módulo de novo e atestando isso, a única classe de evidência deliberadamente manual que a v0.1 entrega. No boleto.ts hoje o portão sai vermelho no itf, o que é exatamente correto: a próxima mudança naquele codificador deveria custar a alguém uma manhã de realmente entendê-lo.

Duas complicações, porque um controle que não pode ser criticado é um controle que acaba sendo burlado. Primeira, a fadiga de âmbar: um aviso que dispara na maioria das mudanças é ruído, e os limiares que decidem o âmbar são juízos de valor que precisarão da mesma disciplina de calibração dos parâmetros de decaimento — o estágio humano serial que toda esta série vem rastreando se move mais para cima na cadeia outra vez, para quem ajusta o portão. Segunda, o paradoxo da válvula de emergência. O módulo mais propenso a te acordar às 3 da manhã é precisamente o escuro, e um portão que bloqueia a correção do incidente é um portão que será apagado até sexta. Então o portão vem com uma escapatória: --break-glass "<incident-ref>" converte uma saída vermelha em aviso — e grava um registro de diagnóstico de incidente assinado e datado no repositório, nomeando quem fez a sobreposição e para qual incidente. Aqui está a reviravolta que mais me agrada, e seu limite honesto. Quem diagnosticou um módulo escuro sob fogo acabou de realizar o ato mais forte de construção de compreensão que existe, então o registro da escapatória é evidência futura genuína — o próprio bypass do portão alimenta o mapa. Mas, na v0.1, esse registro deliberadamente não pontua: o leitor reconhece a classe de evidência reservada e a ignora, avisando em voz alta. Uma escapatória que fabricasse instantaneamente um compreendedor seria uma torneira de compreensão self-service, e eu verifiquei que o ciclo fecha corretamente — quebre o vidro, rode a ferramenta de novo, e o módulo continua escuro até que um humano ateste de verdade.

A série, resolvida

Seis posts atrás, esta série começou com uma afirmação sobre a engenharia sobrevivendo aos agentes. Cada post tornou explícita uma peça do trabalho invisível. Intenção, tornada explícita antes que a inferência gaste um token. Delegação, tornada explícita como uma passagem de bastão projetada em vez de um prompt esperançoso. Atenção, mantida engajada em vez de espectadora. Julgamento, compilado em funções de aptidão que o build pode impor. Entendimento, tornado observável como um mapa com regiões escuras nele. E agora o último passo, que é o menor e o mais consequente: o estado observável convertido em política. Os cinco primeiros posts tornaram a camada humana explícita. O último a torna aplicável.

Vou encerrar com compromissos em vez de conclusões, porque este conceito foi publicado com condições de refutação anexadas e o instrumento deve ser mantido no mesmo padrão. O preprint Substrate Collapse aposta em uma previsão falsificável — sistemas que parecem saudáveis em métricas de autoria mas medem baixo em compreensão devem sofrer desproporcionalmente em incidentes inéditos — e, conforme dados de incidentes se acumulam contra estes mapas, eu vou rodar aquele protocolo e publicar o resultado de qualquer maneira. Toda mudança de parâmetro continuará entrando no CALIBRATION.md como registro público do instrumento discutindo com sua própria especificação, começando pelas duas falhas acima: identidades de agente excluídas das contagens de compreendedores, e a classe REVIEWED implementada, ambas agora que esta execução está registrada. E em doze meses eu vou reler as seis afirmações que esta série fez e pontuá-las em público.

O mapa do boleto.ts me disse que a biblioteca com a qual sou mais identificado é compreendida, segundo a evidência, por nenhum humano — inclusive, segundo a evidência, por mim.

Um instrumento capaz de dizer isso sobre o seu próprio trabalho merece estar no build.

https://github.com/tiarebalbi/comprehension-coverage/issues/29