A pipeline de gates

Uma run não "executa e termina". Ela atravessa uma sequência de gates — Scope, Council, Proof, Validator, Publish — e cada um pode detê-la. Uns são pré-voo, um fecha a run, outro é opcional, o último exige um humano. Juntos são a disciplina que transforma "o agente produziu algo" em "o agente produziu algo verificado". No fim você vai conseguir, de cabeça, dizer qual gate barra o quê — e por que o ReviewGate do ciclo de aprendizado (lições 4 e 8) é membro exato da mesma família.

01 · O que é um "gate" — e o que "fail-closed" significa

Pense num gate como uma catraca de metrô: ela só abre se você apresentar a prova certa (o bilhete). Sem bilhete, ela fica fechada — esse é o padrão. Um gate de software faz o mesmo: ele recebe uma evidência, decide GO ou NO_GO, e na dúvida fica fechado. É isso que "fail-closed" quer dizer: se algo falha, dá erro, ou é ambíguo, o resultado padrão é não deixar passar, não "passar por garantia".

Guarde essa silhueta: nas seções seguintes, cada um dos cinco gates é uma instância dela. Muda qual evidência entra e qual pergunta o losango faz — a forma fail-closed é sempre a mesma.

A mesma ideia em duas camadas

Antes de descer ao código, fixe o conceito nos dois níveis. Clique para alternar entre a explicação simples e a precisa — é a mesma regra, contada para dois leitores diferentes.

02 · A pipeline, em ordem

Aqui está o caminho inteiro de uma run, da rampa de entrada ao ship. Leia da esquerda para a direita: cada caixa é um gate, e abaixo da fileira está a anotação de onde o ReviewGate do ciclo de aprendizado se encaixa (seção 09).

03 · ① Scope Gate — materializa o diretório da run

A rampa de entrada. loadScope(input) (forge/src/scope.ts) copia o GOAL.md, o módulo de plano e o contrato de validação para um diretório de run content-addressed e semeia seu layout. Pense numa obra que recebe uma planta: antes de a primeira parede subir, o canteiro precisa estar montado — fundação, almoxarifado, diário de obra. O Scope Gate é esse canteiro.

A regra-chave: um resume não pode trocar o escopo

Aqui está o ponto de segurança do Scope Gate. Quando você retoma uma run com --resume <run-id>, o goal/plan/contract de agora são comparados com o meta.json salvo. Se qualquer um diverge, ele retorna err('resume mismatch: …'). Você não consegue, por acidente, re-escopar uma run que está retomando — o que evita "continuar" uma run com objetivos diferentes dos originais.

04 · ② Council Gate — veto de pré-voo opcional

runCouncilGate (mission/src/council-gate.ts) roda um board antes de o trabalho começar e retorna uma CouncilDecision agregada (lê consensus.decision). NO_GO significa que a missão não deve prosseguir. É a reunião que decide se o projeto sequer começa — não uma revisão do que ficou pronto. É opcional, mas o núcleo do harness impõe a mesma ideia internamente.

05 · ③ Proof Gate — a espinha determinística

Este é o gate que faz "funciona" significar algo. Cada string unit.proof[] numa missão compila para uma task de comando bash -c que depende da task da unit (compiler.ts:140–157). O Proof Gate lê os estados dessas tasks e falha a run fechada em qualquer saída não-zero. É a diferença entre "o agente disse que fez" e "um comando real saiu 0".

Como a unit vira tasks (a compilação)

O código do gate, condensado

O laço do gate é deliberadamente curto: toda task kind: 'proof' precisa ter saído 0 (status === 'done'); qualquer falha entra num resumo e o gate retorna err. Sem retry, sem degradar para aviso.

// packages/coda/src/proof.ts:55–96 (condensado) — falha fechado, lê o journal
const results = proofTasks.map((task) => {
  const state = stateById.get(task.id);                       // estado vindo do journal
  const outcome = state?.status === 'done' ? 'complete' : 'failed';
  return { unitId: task.metadata.unitId, proofIndex: task.metadata.proofIndex, outcome };
});
// persiste em units/<unitId>/proof-results.jsonl, depois:
const failed = results.filter((r) => r.outcome === 'failed');
if (failed.length > 0) return err(new Error(`Proof Gate failed: ${summary}`)); // run falha fechada

Por que ler o journal e não o checkpoint? (comparativo)

Um detalhe sutil e crucial: o gate lê os estados das tasks do journal de eventos (store.readEvents()), não do checkpoint. O journal é append-only: nada nele é sobrescrito. O checkpoint, sim — uma chamada posterior de runSwarm que compartilha o store pode reescrever o checkpoint.json. Veja o contraste:

06 · ④ Validator Gate — quem constrói não valida

runValidatorGate (coda/src/validator.ts) roda um council independente de validadores mais um painel verificador (verifyPanel) sobre a evidência de cada milestone. A frase que abre o arquivo diz tudo: "Who builds must not validate." O agente que produziu o trabalho nunca é o que assina embaixo. É como um artigo revisado por pares: o autor não é o revisor.

O critério de emissão é estrito: no código, approved é true apenas quando panel.verdict === 'verified' && panel.parkedTier === undefined. Verificado e não estacionado. Qualquer outra coisa — NO_GO, painel rejected, ou um tier que precisa de aprovação — estaciona para revisão humana.

07 · ⑤ Publish Gate — estaciona quando fechado

Qualquer publicação voltada para fora — o curso visual-teach, um manifesto — deve passar por este gate (coda/src/publish.ts). É o único passo irreversível da pipeline (uma vez público, não volta), então é deliberadamente o que um humano assina. É o botão vermelho com tampa: a tampa é o gate.

Por que o gate humano fica exatamente aqui

A posição do ⑤ Publish não é arbitrária — ela cai na fronteira entre o que se desfaz e o que não se desfaz. Tudo à esquerda dessa linha é reversível e roda sozinho; o ship é o primeiro passo irreversível, e por isso é o único que pede uma pessoa (ADR-0005).

08 · Simulador: passe uma run pelos cinco gates

Agora teste a sua intuição. Clique em cada gate para alternar o veredito dele entre GO e NO_GO. O contador mostra quantos gates a run passou antes de ser barrada, e o diagrama acende até onde ela chegou. Lembre da regra fail-closed: o primeiro NO_GO já para tudo.

09 · O ReviewGate do aprendizado é da mesma família

Aqui a lição fecha o ciclo com as lições 4 e 8. O passo de aprendizado do pacote de fusão é protegido por um ReviewGate — e ele é um membro exato desta família de gates. Os cinco gates acima governam o que uma run pode entregar; o ReviewGate governa o que uma run finalizada pode sedimentar em memória e skills. Mesma filosofia fail-closed, aplicada ao auto-aperfeiçoamento do motor: aprenda só com vitórias validadas.

10 · Council vs Validator — o comparativo que mais confunde

Os dois rodam um council; por isso é fácil achar que são a mesma coisa. Não são. Um decide se começar; o outro decide se o que foi produzido pode entregar. Veja lado a lado:

Toda a família num mapa só

Council e Validator são dois membros de uma família de seis. Este mapa comparativo posiciona todos eles em duas dimensões: quando agem (pré-voo → durante → ship → pós-run) e como falham fechado (param a run com err, ou estacionam para um humano). Repare no padrão: os dois últimos da linha — Publish e ReviewGate — são os que tocam o irreversível e o auto-aperfeiçoamento, e ambos escalam para humano.

E para fixar a família inteira de uma vez, a tabela abaixo cruza os cinco gates por quando, o que barra e onde no código:

11 · Caso resolvido: um proof falha numa run real

Junte tudo num caso concreto. Uma unit u1 tem proof: ['pnpm -r typecheck', 'pnpm -w test']; o typecheck quebra. Siga o que cada gate faz — passo a passo — e depois um exercício é seu.

12 · Como isso se encaixa

Você dissecou os cinco gates por dentro. Agora dê um passo atrás: onde essa pipeline liga no resto da máquina? Os gates não são um módulo isolado — são a membrana que envolve toda execução. À esquerda deles está tudo que produz uma run (o loop fechado escolhe a unidade, a cintura estreita roteia, o swarm executa); os gates ficam no meio, peneirando; e à direita está o que sai aprovado — o artefato entregue e o combustível que volta para o ciclo de aprendizado. Repare que o ReviewGate do aprendizado é a mesma silhueta fail-closed (seção 09): a pipeline não termina o ciclo, ela o guarda em dois pontos.

Onde você está na metodologia: as Lições 01–03 montaram o motor, a engenharia reversa do Hermes e a matriz de fusão; as Lições 14–19 detalham a cintura estreita, o funil, esta pipeline de gates, o Council e o swarm que executam uma run. Esta Lição 17 é a peça que decide se o que foi executado pode seguir adiante — em cada fronteira (começar, entregar, publicar, sedimentar). Para ver as 30 peças no mesmo mapa e como cada uma liga na seguinte, abra o mapa interativo da metodologia.

13 · Na prática

Chega de diagrama — eis a pipeline como comandos reais. Você não chama cada gate à mão: eles disparam, em ordem, quando você executa uma run com escopo. O comando canônico é o mesmo da Lição 04, só que aqui o foco é assistir os gates dispararem:

# Executa uma run com escopo: os 5 gates disparam em ordem (Scope → Council → Proof → Validator → Publish).
# --offline mantem tudo hermetico e $0 (adapter offline deterministico); --yes nao para para confirmar.
alembic run --goal GOAL.md --plan alembic.plan.ts --offline --yes

# saida tipica (resumida) — cada gate anuncia seu veredito; o 1o NO_GO faz a run falhar fechada:
#   scope: run-dir materializada em .alembic/runs/<run-id>/
#   proof gate: 2/2 ok          ← cada unit.proof[] saiu 0
#   validator gate: verified    ← council independente aprovou a evidencia
#   run complete: ok
# se um proof sair nao-zero, em vez disso:
#   proof gate: FAILED unit=u1 index=0   → a run para aqui (err), Validator/Publish nem rodam

O ③ Proof Gate não é uma flag — ele nasce do unit.proof[] que você escreve no plano. Cada string vira uma task bash -c que depende da unit (seção 05). É assim que você declara "o que prova esta unidade":

// dentro de alembic.plan.ts — cada string de proof[] vira uma task bash -c que o ③ Proof Gate verifica.
const result = await h.mission({
  title: 'mission title',
  tier: 'T2',
  units: [
    {
      id: 'u1',
      title: 'Implement feature X',
      proof: ['pnpm -r typecheck', 'pnpm -w test'],   // ← 2 proofs → 2 tasks → o gate exige saida 0 em ambas
    },
  ],
  milestones: [{ id: 'm1', title: 'Milestone one' }],
});

E para ligar o passe coordenado do Validador — a peça ADITIVA da seção 06 que roda o veredito multi-lente por tier de risco além do council gate (offline por padrão), sem nunca mudar a decisão nem fazer a run falhar — basta a flag --coordinated:

# Adiciona o passe coordenado do Validador (ADITIVO): grava um veredito sibling por unit,
# mas NUNCA muda a decisao do council gate e NUNCA faz a run falhar (offline por padrao).
alembic run --goal GOAL.md --plan alembic.plan.ts --coordinated --offline --yes

# cada unit ganha um arquivo extra de veredito:
#   .alembic/runs/<run-id>/units/<unit-id>/coordinated-verdict.json

Fonte da forma exata: apps/cli/src/args.ts (as flags offline, coordinated, yes de runArgsSchema) e a seção "Gate pipeline" do CLAUDE.md — o --coordinated roda runCoordinatedValidatorGate sobre as mesmas units e grava units/<id>/coordinated-verdict.json, ADITIVO ao council gate. [uncertain] as linhas de saída acima são ilustrativas da forma "gate: veredito" (não verbatim de um log) — o que é garantido pelo código é o comportamento: Proof falha fechado em saída não-zero e o coordinated-verdict.json é gravado por unit.

Fixe os conceitos (flashcards)

Clique pra virar. Tente lembrar a resposta antes de virar — recuperar fixa mais que reler.