O loop nunca declara vitória por conta própria. Quatro portões separam uma tarefa do "entregue" — Escopo, Prova, Curso e Publicação — e um deles é o coração de todo o método: o Portão da Prova. Ele aceita apenas evidência no limite real — você de fato executou e atingiu o caminho real — nunca uma afirmação, um mock ou uma asserção verde que você mesmo escreveu.
Um portão é um ponto de controle com uma regra: você não passa até que uma condição específica seja verdadeira — e a condição é verificada, não presumida. O loop tem quatro deles, e juntos eles são o contrato do que "pronto" significa. Ninguém — nem uma pessoa com pressa, nem uma IA confiante — pode liberar uma tarefa com um aceno. Ou a condição do portão é atendida, ou o trabalho não está pronto. Ponto final.
Os quatro portões, na ordem em que um trabalho os encontra: Escopo pergunta "o 'pronto' está escrito como algo que podemos de fato medir?" Prova pergunta "executamos de verdade e vimos funcionar?" Curso pergunta "existe uma lição clara e autossuficiente explicando o resultado?" E Publicação pergunta "o resultado está em um lugar onde pode ser encontrado e usado?" Cada um é um sim/não que você pode apontar — nunca um palpite.
Por que se dar ao trabalho de transformar "pronto" em quatro verificações duras? Porque "pronto" é a palavra mais reivindicada em excesso em qualquer projeto. É barato dizer que algo funciona e caro mostrar que funciona. Os portões existem para que a coisa cara — mostrar — seja a única que conta. O portão do meio, Prova, é onde mora a maior parte do perigo, então a maior parte desta lição mora lá também.
Pense nisso como… as eclusas de um canal. Um barco não pode simplesmente flutuar de um nível de água para o próximo porque se sente pronto — cada eclusa tem que encher fisicamente antes que o portão abra, em ordem, um de cada vez. A eclusa não se importa com o quão confiante o capitão está; ela se importa se a água está realmente nivelada. Os portões do loop são essas eclusas: a água precisa subir de verdade antes que o próximo portão abra.
Cada passo do loop é LEARN → ANALYZE → EXECUTE one bounded unit → VERIFY at the real boundary → DECIDE. O Portão de Escopo é resolvido antes de o loop começar a girar (é o done-when mensurável da lição 2). O Portão da Prova é o que o passo VERIFY precisa superar a caminho do DECIDE — não é uma fase separada, é a barra à qual o VERIFY é submetido. Os portões de Curso e Publicação disparam uma vez, na convergência, quando o objetivo inteiro é atingido.
Ajuda ler cada portão como uma função booleana sobre a realidade: scopeMet(), proofMet(), courseMet(), publishMet(). O "pronto" da execução é o e lógico dos quatro. Como cada um retorna um valor derivado de algo observado — uma medição, o código de saída de um comando, um arquivo que existe, uma URL que resolve — não há lugar para uma opinião se infiltrar. Esse é o ponto inteiro: o contrato é imposto por evidência, não por confiança.
Aqui estão os quatro, da esquerda para a direita, do jeito que o trabalho flui por eles. Um trabalho tem que superar cada um antes que o próximo abra — e se algum falhar, o trabalho é devolvido, não liberado. Repare que o segundo está destacado: esse é o coração do método, e o resto da lição dá zoom nele.
O "pronto" é escrito como algo que você pode medir — um número a atingir, um teste a passar, um comportamento a observar. Um objetivo vago não consegue abrir este portão.
A mudança foi executada no limite real — o comando real, o caminho real, a saída real — e observada funcionando. Uma afirmação ou um mock não contam.
O resultado vem com um curso visual-teach autossuficiente e multi-lição — uma pessoa consegue aprender o que foi construído sem ler o código.
O entregável é enviado para algum lugar acessível — um gist privado, um site no Pages — e a URL é reportada de volta. Um resultado que ninguém alcança não está entregue.
O Escopo é fixado no início e relido a cada passo (pode ser afinado, nunca ampliado em silêncio). A Prova é imposta em todo VERIFY — cada unidade delimitada tem que provar a si mesma antes de o loop avançar. Curso e Publicação são portões de convergência: disparam quando o objetivo inteiro é atingido, transformando um resultado que funciona em algo que uma pessoa consegue aprender e alcançar. O Portão de Publicação ganha sua própria lição (lição 11); o Portão de Curso é o tema da lição 10.
É fácil pensar que entregar código é a linha de chegada. Neste harness não é: um resultado que você não consegue explicar é tratado como ainda-não-pronto, porque a próxima pessoa (ou o próximo agente) não consegue construir sobre ele com segurança. O Portão de Curso força a construção a terminar em entendimento, não apenas em bytes — que é exatamente por que esta própria página existe.
Dos quatro, o Portão da Prova é aquele em torno do qual o método inteiro foi construído. Sua regra é curta e implacável: "pronto" exige evidência no limite real — você executou e atingiu o caminho real — nunca uma afirmação, um mock ou uma asserção verde. Vamos destrinchar isso, porque cada palavra é estrutural.
Uma afirmação é qualquer um dizendo "funciona" — inclusive uma IA muito fluente que soa completamente certa. O Portão da Prova não aceita afirmações, não importa quem as faça. Um mock é um substituto: uma versão falsa da coisa que sempre responde direitinho, usada para evitar tocar no sistema real. Mocks são úteis enquanto se constrói, mas não provam nada sobre a realidade, então não abrem este portão. Uma asserção verde é a mais traiçoeira: um teste que passa — mas só porque foi escrito para passar, ou só verifica a metade fácil, ou roda contra o mock em vez do limite real. Verde não é o mesmo que verdadeiro.
O que de fato abre o portão é o oposto dos três: você pega a coisa real, executa, empurra pelo caminho real que importa e observa o que acontece de verdade. Então você aponta para aquilo — o comando, a saída, a página que carregou, o valor que voltou. Se você não consegue apontar para a evidência, o portão fica fechado e o trabalho não está pronto.
Pense nisso como… um paraquedas. A etiqueta de embalagem diz "inspecionado — OK". O rótulo é uma afirmação. Uma dobra de treino sobre a mesa é um mock. Um teste unitário que confirma que a etiqueta foi preenchida é uma asserção verde. Nenhum deles é a coisa que você de fato quer, que é: o velame abriu, no ar, num salto real. O Portão da Prova é o harness se recusando a contar qualquer coisa menos que o velame abrindo.
O Portão da Prova em uma frase
Se você não consegue apontar para o momento em que a coisa real fez o trabalho real, você tem uma afirmação — e uma afirmação não é "pronto".
O limite é onde quer que a mudança encontre a realidade e possa falhar: o endpoint HTTP de fato retorna 400, o binário de fato sai com 0, a página de fato renderiza num navegador, o arquivo de fato cai no disco, a migração de fato roda contra um schema real. Provar contra uma camada interna que você controla totalmente (uma função que você acabou de escrever, um mock que você configurou) é o erro clássico — isso testa a sua intenção, não o mundo. Escolha a costura mais externa pela qual a unidade é responsável e atinja essa.
Um teste é evidência só quando exercita o limite real e poderia genuinamente falhar. Três formas de o "verde" mentir: ele roda contra um mock em vez da dependência real; ele afirma algo trivialmente verdadeiro (a função retorna um valor, não o valor certo); ou foi escrito depois do fato para casar com o que o código já faz. O Portão da Prova pergunta a qualquer verificação verde: que coisa real isto tocou, e como teria ficado vermelho se o trabalho estivesse errado?
Às vezes você genuinamente não consegue atingir o caminho real — sem credenciais, um serviço está fora, o ambiente está faltando. A regra então não é "mockar e dizer que está pronto". É parar e perguntar, pronto para decisão: exponha exatamente o que está bloqueado, o que você executaria se desbloqueado, e as opções — para que uma pessoa possa tomar uma decisão limpa. Falsificar a prova para seguir em frente é a única coisa que o portão existe para impedir.
Os portões são um contrato, e um contrato só funciona se todos o honrarem da mesma forma. Neste harness três tipos de participante encontram o Portão da Prova — a pessoa que observa, o modelo de linguagem que faz o raciocínio e o agente (uma ferramenta de CLI) que faz a execução — e cada um tem um dever claro. Eles não são audiências separadas a quem se dirigir; são três mãos no mesmo portão.
Você lê o resultado do jeito que um inspetor lê um laudo: você procura a prova, não a confiança. "Funciona" não vale nada; um comando que você pode reexecutar e uma saída que você pode ver valem tudo. Os portões são o seu contrato — são o que permite você ficar fora da execução e ainda confiar no "pronto".
Toda vez que você toca no caminho, a prova antiga fica obsoleta — então você prova de novo, contra o limite real. E se o limite estiver inalcançável, você não falsifica: você para e pergunta, pronto para decisão, expondo o que está bloqueado e quais são as opções, para que a pessoa possa tomar uma decisão limpa.
Quem construiu a mudança não pode ser quem a prova. Um agente separado — o Validador — roda a verificação no limite. Um autor corrigindo a própria prova é exatamente o conflito que o Portão da Prova remove; a independência é o que faz a evidência valer a confiança.
"O Validador nunca é o construtor" é o mesmo princípio de um segundo par de olhos num deploy, ou de um contador diferente assinando os livros. O construtor tem interesse na mudança passar; esse viés é humano e inevitável, então o harness roteia a prova por alguém (algo) sem ele. Numa execução multi-agente o orquestrador entrega a unidade delimitada a um agente e a verificação a outro — a independência é estrutural, não uma questão de boas intenções.
Quando um LLM atinge um limite inalcançável, "parar e perguntar" só é útil se o pedido for completo. Pronto para decisão significa: aqui está exatamente o que está bloqueado, aqui está a evidência que eu tenho, aqui estão as 2–3 opções com seus trade-offs, e aqui está a minha recomendação. Isso permite à pessoa desbloquear com uma única resposta em vez de uma rodada de perguntas — e mantém a pessoa na observabilidade, nunca na execução (a disciplina AFK da lição 5).
Prova não é uma ideia — são algumas linhas que qualquer um pode reexecutar. Quando uma unidade supera o Portão da Prova, a evidência é capturada para que a pessoa possa auditá-la depois sem estar na sala. Aqui está a mesma unidade delimitada registrada de duas formas: uma afirmação (que o portão rejeita) e a prova que a substituiu (que o portão aceita). Leia ambas e a diferença fica óbvia.
# unit: /search must reject an empty query with 400 # status: claimed done note: "added the guard, looks correct, should return 400 now" ← uma AFIRMAÇÃO test: "wrote test_empty_query — it passes" ← VERDE, mas contra um router mock # Proof Gate: REJECTED — no real boundary was hit.LOOP-LOG.md — a mesma unidade, agora COM prova
# unit: /search must reject an empty query with 400 # VERIFY — run the REAL endpoint, observe the REAL response $ curl -s -o /dev/null -w "%{http_code}\n" "localhost:8000/search?q=" 400 ← observado no limite real $ curl -s -o /dev/null -w "%{http_code}\n" "localhost:8000/search?q=shoes" 200 ← o caminho feliz ainda funciona # Proof Gate: PASSED — evidence above, re-runnable. Validator: agent-B (not the builder).
A prova acima é só o curl atingindo o serviço em execução e imprimindo o código de status com -w "%{http_code}". Você inicia o serviço, depois roda as duas chamadas e lê os números com os próprios olhos — 400 para a query vazia, 200 para uma real. Esse par observado é a evidência; vai direto para o LOOP-LOG.md, o arquivo que a pessoa lê para auditar uma execução (você vai conhecer o log na lição 5).
Se o fato de que você precisa mora na web e não no repositório — um comportamento atual de uma API, uma versão, uma especificação — o caminho da fonte confiável é o CLI da Bright Data (brightdata search "…"), nunca um palpite e nunca WebSearch/WebFetch; isso é a lição 9. Mesmo princípio, limite diferente: evidência acima de recordação.
Aqui está o portão em ação. Abaixo está uma mudança proposta real — o próprio guarda do /search do log acima — anotada do jeito que um Validador a revisa. As pílulas no topo são a leitura de relance do Validador sobre como a mudança move as coisas. Os pontos cor de argila são notas fixadas exatamente na linha de que tratam; uma é bloqueante, o que significa que o Portão da Prova fica fechado até ser resolvida. Clique em qualquer linha pontilhada para ler a nota e encontre o bloqueador.
Pense nisso como… um fiscal de obra percorrendo o canteiro com uma prancheta. Dá o sinal verde para a maioria das coisas, mas prega uma etiqueta vermelha na única viga que está fora da norma — e essa única etiqueta vermelha basta para reter o certificado. A nota bloqueante é essa etiqueta vermelha.
Adiciona um guarda em GET /search para que um q vazio retorne 400, não o índice inteiro. 1 arquivo alterado · +6 −1
Cada linha com ponto cor de argila carrega uma nota. 1 é bloqueante — é a razão pela qual esta mudança não superou o Portão da Prova ainda. Veja se você consegue encontrá-la.
A nota bloqueante fica na linha do teste porque o teste passa contra FakeRouter() — um mock — não o endpoint real. Isso é uma asserção verde sem nenhuma evidência no limite real por trás: ela prova a intenção do autor, não o comportamento do mundo. A correção é a prova da seção anterior — um curl real contra o serviço em execução mostrando 400 para ?q= e 200 para uma query real. Até essa evidência observada existir, o portão está corretamente fechado.
Este widget é a mesma superfície de revisão que um Validador usa, levantada inteira e com namespace para poder viver dentro desta lição. Tudo é inline — abra do file:// e simplesmente funciona.
A disciplina inteira se reduz a uma bifurcação. Uma unidade chega ao VERIFY; o Portão da Prova pede evidência no limite real. Sim → ela passa e o loop avança. Não → ela volta, todas as vezes. Não existe uma terceira porta rotulada "perto o suficiente".
A única regra
O portão não tem porta para "provavelmente". Ou a evidência existe e você aponta para ela, ou a unidade não está pronta — e se você realmente não consegue alcançar o limite, você para e pergunta em vez de falsificar.
Veja o portão fazer seu trabalho em uma unidade, do começo ao fim. A tarefa: "fazer /search rejeitar uma query vazia com um 400." Um autor reporta que está pronto. O Portão da Prova discorda — duas vezes — antes de finalmente abrir. Cada momento é o portão recusando um impostor diferente do "pronto".
Uma frase confiante e nada para apontar. O Portão da Prova não lê intenções — ele lê evidência. Rejeitado: nenhum limite foi atingido. Vá provar.
O teste roda contra FakeRouter(), um mock — ele afirma a intenção do autor, não o comportamento do endpoint real. Verde aqui prova que o falso funciona. Rejeitado: uma asserção verde contra um mock não é evidência no limite real.
curl "localhost:8000/search?q=" → 400, e curl "localhost:8000/search?q=shoes" → 200. Observado no limite real, reexecutável, capturado no log. Um agente diferente — o Validador — rodou. Aprovado: agora existe algo para apontar.
O que o portão produziu
Duas rejeições e uma aprovação — e a única diferença entre "rejeitado" e "pronto" foi um par de códigos de status que alguém de fato viu voltarem do serviço real. A afirmação e o teste verde não mudaram nada da realidade; o curl mudou. Isso é o Portão da Prova merecendo seu lugar como o coração do loop.
Lê só na entrada, evidência na saída — toda afirmação tem uma fonte reexecutável, e a linha do Validador registra que quem provou não foi quem construiu.
# VERIFY — fix/empty-query — Validator: agent-B (builder was agent-A) $ curl -s -o /dev/null -w "%{http_code}\n" "localhost:8000/search?q=" # → 400 $ curl -s -o /dev/null -w "%{http_code}\n" "localhost:8000/search?q=shoes" # → 200 # Proof Gate: PASSED. evidence above. unit done; loop may DECIDE.
Quatro portões compõem o contrato do "pronto" — Escopo, Prova, Curso, Publicação — e eles são verificados, nunca presumidos. O do meio é o coração: o Portão da Prova aceita evidência no limite real e nada mais. Uma afirmação não é prova. Um mock não é prova. Uma asserção verde que você não consegue rastrear até o caminho real não é prova. Você executou, você atingiu a costura real, você viu funcionar, e você consegue apontar para isso — ou o trabalho não está pronto.
As três mãos nesse portão o mantêm honesto: a pessoa confia na evidência acima das afirmações, o LLM reprova depois de qualquer mudança e para-e-pergunta quando o limite está fora de alcance, e o agente mantém o Validador separado do construtor. Carregue isso e o resto do harness — as execuções AFK, as equipes multi-agente, a publicação — permanece confiável, porque tudo a jusante é construído sobre uma prova que você mesmo poderia reexecutar.