reviewAndLearn — o passe gated

Como um turno finalizado ensina o próximo — sem virar terra de ninguém. Um revisor propõe escritas duráveis de memória; um gate Validador dispõe; só as aprovadas sedimentam no MemoryStore. A restrição-chave — tirada direto da matriz de fusão e do ADR-0018 — é que o aprendizado é gated, não auto-aplicado. É um ADAPT do fork de background-review do Hermes para o estilo de portas do motor: sem thread de daemon, apenas três portas injetadas.

01 · O que é, afinal, um "passe gated"

Imagine um estagiário que, ao fim de cada tarefa, escreve bilhetes do que aprendeu para o caderno permanente da equipe. Se ele pudesse colar qualquer bilhete direto no caderno, em pouco tempo o caderno estaria cheio de palpites errados e ruído. Então existe um editor: o estagiário propõe o bilhete, o editor aprova ou recusa, e só o aprovado entra no caderno. Esse editor é o gate; o caderno é o MemoryStore; o passe inteiro é o reviewAndLearn.

Por que "fechar" quando dá erro? (fail-closed vs fail-open)

Há duas posturas possíveis diante de um erro de infraestrutura no meio do aprendizado. O Alembic escolhe a conservadora — fail-closed: na dúvida, não aprenda. Compare:

02 · A forma: propor → gate → aplicar — com os três destinos

Agora a versão precisa. Cada proposta percorre o mesmo trilho, e termina em um de três baldes. O losango no gate é a decisão central: aprovou? Repare que a recusa do gate e a falha do store são caminhos diferentes — é o que a seção 05 vai destrinchar.

Guarde a leitura de cima: há um único ponto de decisão por proposta (o losango do gate) e dois jeitos de "não dar certo" depois dele — o gate recusar (→ rejected) ou o store recusar a escrita já aprovada (→ failed). Tudo o mais é o trilho.

03 · O driver pequeno e total

O reviewAndLearn é o orquestrador do passe. Ele é deliberadamente pequeno e total (nunca lança): um summary vazio ou zero propostas faz curto-circuito para um resultado vazio — um passe no-op é válido, espelhando o "Nothing to save." da fonte. Já um erro do proposer ou do gate falha o passe inteiro fechado (err):

// packages/hermes/src/learning/review.ts:54-70
export const reviewAndLearn = async (
  summary: string, deps: ReviewDeps,
): Promise<Result<LearnOutcome, Error>> => {
  if (summary.trim().length === 0) return ok(emptyOutcome());
  const proposed = await deps.proposer(summary);
  if (!proposed.ok) return proposed;                // erro do proposer ⇒ falha fechado
  if (proposed.value.length === 0) return ok(emptyOutcome());
  const acc: OutcomeAcc = { applied: [], rejected: [], failed: [] };
  for (const raw of proposed.value) {
    const stepErr = await processOne(raw, deps, acc);
    if (stepErr) return stepErr;                    // erro do gate / forma ruim ⇒ falha fechado
  }
  return ok({ applied: acc.applied, rejected: acc.rejected, failed: acc.failed });
};

As três portas injetadas vêm num único objeto ReviewDeps — nenhum adapter concreto, nenhuma construção de store dentro do módulo (é o kernel portável, ADR-0009):

// packages/hermes/src/learning/review.ts:29-37
export interface ReviewDeps {
  readonly proposer: ReviewProposer;  // propõe escritas a partir do summary (prod: chamada de modelo)
  readonly gate: ReviewGate;          // decide se cada proposta pode sedimentar (o Validador)
  readonly memory: MemoryStore;       // store durável onde aprovadas são aplicadas (dedup reusado)
}

As duas primeiras portas são tipos de função — assinaturas, não classes. Cada uma recebe uma entrada e devolve um Result (nunca lança). Ver a forma da assinatura deixa claro o que é injetável e por quê:

04 · Os três baldes

O resultado (LearnOutcome) separa três destinos, cada um com sentido próprio. Pense neles como três caixas no fim da esteira:

O tipo deixa isso explícito — e os comentários do código são a melhor legenda:

// packages/hermes/src/learning/types.ts:99-106
export interface LearnOutcome {
  /** Propostas aprovadas pelo gate E escritas com sucesso no store. */
  readonly applied: readonly ReviewProposal[];
  /** Propostas que o gate recusou, cada uma com a razão do gate. */
  readonly rejected: readonly RejectedProposal[];
  /** Propostas que o gate aprovou mas o store rejeitou (ex.: char-budget). */
  readonly failed: readonly RejectedProposal[];
}

Trace passo a passo: um lote de 3 propostas

Veja o reviewAndLearn rodar sobre um lote concreto de três propostas — uma por balde. O for processa em ordem, e cada uma cai no seu balde sem afetar as outras (porque nenhuma é erro):

05 · Por que failed ≠ rejected (a distinção load-bearing)

Esta é a sutileza que carrega a observabilidade do subsistema. Tanto rejected quanto failed são "não entrou na memória" — mas por motivos opostos, e confundi-los esconderia bugs. Uma escrita acima do orçamento (infra) nunca pode ser lida como uma recusa de política (decisão do gate). O processOne separa os dois com cuidado cirúrgico:

// packages/hermes/src/learning/review.ts:78-103 — processOne
const parsed = reviewProposalSchema.safeParse(raw);   // saída de modelo NÃO confiável
if (!parsed.success) return err(new Error(`Invalid review proposal: …`));
const proposal = parsed.data;
const verdict = await deps.gate(proposal);
if (!verdict.ok) return verdict;                      // ERRO do gate ⇒ falha o passe
if (!verdict.value.approved) {
  acc.rejected.push({ proposal, reason: verdict.value.reason }); // gate disse NÃO
  return undefined;                                 // continua o passe
}
const written = await deps.memory.apply(proposal.target, proposal.op);
if (!written.ok) {
  acc.failed.push({ proposal, reason: written.error.message }); // store disse NÃO
  return undefined;                                 // ainda continua
}
acc.applied.push(proposal);

As três maneiras de "não dar certo", lado a lado

Compare os três finais negativos. Repare: recusa (gate ou store) continua o passe e só anota num balde; erro aborta o passe inteiro. Esta tabela é o mapa de decisão do processOne:

06 · O gate padrão: aprender só com vitórias validadas

Até o Validator Gate real do @alembic/coda (ADR-0006) plugar seu próprio ReviewGate por injeção, o padrão conservador aprova uma proposta sse score ≥ 0.7 — a codificação mecânica de "learn only from validated wins", trazida do hermes-mini-loop (§5.1). É puro e total: sempre devolve ok(verdict), nunca lança.

// packages/hermes/src/learning/gate.ts:24-36
export const scoreThresholdGate = (
  min: number = DEFAULT_REVIEW_SCORE_THRESHOLD,   // 0.7
): ReviewGate => {
  return async (proposal) => {
    const approved = proposal.score >= min;        // fronteira INCLUSIVA
    const reason = approved
      ? `score ${proposal.score} ≥ threshold ${min}`
      : `score ${proposal.score} < threshold ${min} (learn only from validated wins)`;
    return ok({ approved, reason });               // puro & total: sempre ok(verdict)
  };
};

A fronteira é inclusiva — 0.69 reprova, 0.70 passa

O operador é >=, não >. Então exatamente 0.70 aprova; qualquer coisa abaixo reprova. Visualize a reta do score com o piso em 0.7:

E a reason não é decorativa: é a string que explica a decisão no outcome (observabilidade). O ramo aprova/recusa escolhe qual template de razão é interpolado:

07 · A sutileza: o veredito é dado, não o Result

Aqui mora a peça mais fácil de errar — e a mais importante. Há dois eixos independentes no retorno do gate. O envelope Result (ok vs err) diz se o gate funcionou. O dado dentro dele (verdict.approved = true/false) carrega a decisão. Uma rejeição é ok({approved:false}) — não err.

08 · A máquina de estados de uma proposta (interativa)

Junte tudo numa simulação. Escolha um cenário abaixo: a figura acende o caminho que aquela proposta percorre e os baldes mostram onde ela cai (ou se o passe inteiro aborta). É o mesmo controle de fluxo do processOne, vivo.

09 · Reforçar, não duplicar

O loop não adiciona nenhuma lógica de dedup própria. Escritas aprovadas fluem pelo dedup já existente do MemoryStore (Lição 07): re-propor uma entrada que já existe é um no-op de sucesso — então é contado como applied, mas o store permanece em uma entrada. Isso espelha a intenção do ON CONFLICT DO UPDATE do mini-loop: reforçar, não empilhar duplicatas.

O schema da proposta valida a saída do modelo na fronteira, antes de qualquer gate ou escrita — incluindo score limitado a [0,1] e o alvo restrito a 'memory' ou 'user'. Um score: 1.5 de um modelo mal-comportado é rejeitado pelo safeParse (e aborta o passe, não vira rejeição de política):

// packages/hermes/src/learning/types.ts:62-71
export const reviewProposalSchema = z.object({
  target: memoryTargetSchema,            // 'memory' (notas do agente) ou 'user' (fatos do usuário)
  op: memoryOpSchema,                     // add / replace / remove
  rationale: z.string(),                  // por que vale lembrar — vai pro outcome (observabilidade)
  score: z.number().min(0).max(1),      // confiança do revisor; o gate compara com o piso
});

O op é uma união discriminada por action: cada operação tem campos distintos, e o schema só aceita uma das três formas. É o que o safeParse verifica antes de o gate sequer rodar:

10 · ADAPT, não port literal — Hermes vs Alembic

Por que "ADAPT" e não "CLONE"? Porque a disciplina foi copiada, mas o encanamento foi remodelado para o motor. O Hermes forka uma thread de background (um daemon Python no runtime AIAgent); o Alembic não tem esse runtime para forkar, então a mesma forma propor→gate→aplicar virou três portas injetadas. Compare lado a lado:

Quem governa cada propriedade — o mapa de ADRs

Cada decisão deste kernel rastreia até uma fonte de verdade no repositório. Este mapa liga propriedade → documento que a fixa, para você não confiar em memória:

Confusões comuns

11 · Como isso se encaixa

Até aqui você olhou o reviewAndLearn por dentro. Agora afaste a câmera: onde esse passe vive na esteira do motor? A resposta curta — ele é o último elo do loop fechado, o que faz a run de hoje deixar uma marca durável para a run de amanhã. Ele só roda depois que todos os gates passaram, e o que ele produz é lido de volta no começo do próximo turno como contexto.

Onde você está na metodologia. O motor do Alembic é um loop: aprender → analisar → executar uma unidade → verificar na fronteira real → decidir, e então recomeçar com o que se aprendeu. O reviewAndLearn é a peça que torna esse “recomeçar com o que se aprendeu” literal e seguro: sem ele, cada run começaria do zero; com ele — e só com o gate no caminho — a memória cresce apenas com vitórias validadas. Para ver a esteira inteira em movimento, abra o mapa interativo da metodologia.

• Lição 04 · O loop fechado — é o ciclo que contém este passe; reviewAndLearn é o último elo (“decidir → recomeçar com o aprendido”) que fecha o loop.
• Lição 07 · MemoryStore — é o store que ele alimenta; o passe não tem dedup próprio, reusa o do store (a seção 09 mostra “reforçar, não duplicar”).
• Lição 17 · A pipeline de gates — é onde o ReviewGate se pluga; o mesmo Validador (ADR-0006) que reprova milestones pode reprovar uma escrita de memória.
• Lição 23 · Lab: o passe de aprendizado — é o lab prático onde você reconstrói este kernel do zero, com testes, fixando os três baldes na mão.

12 · Na prática

Chega de teoria — rode o passe. O aprendizado é opt-in: uma run normal não aprende. Você liga o passe gated com a flag --learn, e roda tudo hermético ($0, sem rede) com --offline. Nesse modo, o proposer é o adapter offline determinístico e o gate é o Validador — exatamente o caminho que você acabou de estudar:

# liga o passe gated (ADR-0018) ao fim de uma run, hermético e $0
alembic run --goal GOAL.md --plan alembic.plan.ts --learn --offline --yes

# … a run executa as unidades e passa pelos gates (Proof + Validador) …
# então, SÓ porque --learn está ligado, vem a última linha do passe:
#   learning gate: 2 applied, 1 rejected

Dois detalhes que conectam direto com as seções anteriores. Primeiro: sem a flag, nada acontece — o aprendizado é aditivo e desligado por padrão, então uma run verde continua verde. Segundo: se não houver adapter de proposer disponível, o passe é pulado (log run:learning-pass-skipped), nunca quebra a run — é a mesma postura fail-closed da seção 05 aplicada ao próprio gatilho.

Quer ir além do resumo de uma linha? O passe inteiro também é exercitado pelos testes do kernel — pnpm --filter @alembic/hermes test roda os 14 casos do review.test.ts (a fronteira 0.69/0.70, failed vs rejected, fail-closed nos erros de proposer/gate) que esta lição destilou. É a prova de que o comportamento que você leu é o comportamento que roda.

Fixe os conceitos (flashcards)

Clique pra virar. Tente lembrar a resposta antes de virar — recuperação ativa fixa mais que reler.