O código diz o que o motor faz; os Architecture Decision Records dizem por quê — e por que as alternativas foram rejeitadas. Cinco ADRs formam a espinha de tudo que você aprendeu: que o Alembic é um motor e não um produto (0001), que o portão humano fica no gasto irreversível (0005), que o Validator é o portão de emissão (0006), que uma chamada de modelo nunca lança (0009), e que o loop de auto-aperfeiçoamento tem gate de Validator (0018). Cada um é uma restrição que a fusão teve que honrar — lidos juntos, eles explicam por que o @alembic/hermes tem a forma que tem e não alguma forma mais fácil.
docs/adr/; dezoito estão aceitos. São append-only — uma decisão posterior substitui uma anterior (nunca a edita), então a trilha é uma história verdadeira, não um instantâneo arrumado.| ADR | A decisão | Como restringe a fusão |
|---|---|---|
| 0001 | Alembic é um motor interno, não um SKU para cliente | Sem UI/billing/onboarding no motor — o @alembic/hermes entrega bibliotecas, não superfícies de produto |
| 0005 | O portão humano fica no ship / gasto irreversível | O ClarifyGateway (Lição 10) é a superfície T4; aprender + distillar rodam sem humano (HITL-free) |
| 0006 | Profundidade frontier em tudo, via o modelo mais barato acima de um piso; o Validator é o portão de emissão | O loop de aprendizado deve passar um piso de qualidade antes de sedimentar — não pode auto-gravar |
| 0009 | Uma chamada de modelo nunca lança; retorna um resultado discriminado | Todo subsistema hermes retorna Result, injeta suas portas e é agnóstico de store |
| 0018 | Internalizar o loop do Hermes como uma passagem propose→dispose com gate de Validator | A pedra angular: revisor propõe, Validator dispõe, nunca auto-aplica |
"Alembic é o motor/plataforma interno da Appfy, não um SKU para cliente hoje." A consequência é nítida: preocupações voltadas ao cliente — uma API pública para venda, billing, onboarding/marketing de tenant — "vivem em produtos … não no motor". É por isso que a fusão portou ferramentas como bibliotecas (um MemoryStore, uma função webSearch) e nunca um app de agente executável com UI. Também deixa uma porta aberta: "Se houver pull de mercado real, produtizar o Alembic como harness-as-a-service … pode virar uma nova decisão" — registrada como um ADR futuro substituindo o escopo deste, nunca uma edição.
Você conheceu isto como a cintura estreita da Lição 14. Como decisão ela diz: toda chamada de modelo passa por run(input): Promise<ModelRunResult>, uma união discriminada, e "run() nunca lança: falhas são valores, não exceções". A opção rejeitada é nomeada — "clientes convencionais que lançam" — porque eles "espalham try/catch pela orquestração … e acoplam chamadores a formatos de erro específicos de provedor". A lista de consequências é a parte que sustenta: retry, circuit-breaking, medição de orçamento e quórum de council "operam todos sobre resultados tipados uniformes". Essa uniformidade é exatamente por que todo subsistema hermes pôde adotar a mesma forma Result sem casos especiais.
A manchete deste ADR é sobre custo (profundidade frontier no corpus inteiro via o modelo mais barato acima de um piso de profundidade), mas sua cláusula sustentadora para a fusão é o princípio de emissão: nada sedimenta sem passar um piso de qualidade. Essa é a regra que o loop de aprendizado teve que obedecer — a proposta de um revisor não é verdade, é um candidato, e um gate decide. O default scoreThresholdGate(0.7) é a codificação conservadora desse piso até o Validator real do @alembic/coda se ligar.
Onde um humano precisa estar no loop? Não no tempo de design — "código numa branch é reversível". O critério decisivo é "reversibilidade/externalidade, não posição no pipeline — o portão fica onde um erro autônomo deixa de ser 'apagar uma branch' e vira dinheiro ou reputação". Então ship e gasto real defaultam para T4-park (fail-closed), enquanto "Destilação (T0–T3 → Signal/Learning) e discover→build são HITL-free". É o princípio que o ClarifyGateway implementa: uma pergunta estruturada e bloqueante é a superfície humana T4, usada só onde a reversibilidade se esgota.
O mais novo dos cinco (aceito em 2026-06-23) é o que autoriza todo o subsistema de aprendizado. O Hermes tinha a peça que faltava — um revisor pós-turno que grava direto na memória durável — mas o Alembic não pôde copiá-la literalmente por duas razões que ele declara claramente:
AIAgent Python para fazer fork como thread daemon" — então o mecanismo vira uma passagem sobre portas injetadas, não uma thread em segundo plano.Leia esses dois pontos e você vê a trilha de ADRs funcionando como um sistema: 0018 não pode simplesmente clonar o Hermes porque 0006 proíbe emissão sem gate e 0009 proíbe lançar — então a única forma que sobra é exatamente o propose→gate→apply sobre portas injetadas que você construiu no Lab 2. A decisão até nomeia as quatro garantias: somente portas injetadas, com gate de Validator e não auto-aplicado, default conservador com um gate mais rico opt-in, e a passagem é fail-closed com Zod na fronteira.
Cada ADR remove opções. 0001 remove "construir um produto". 0009 remove "lançar no erro". 0006 remove "auto-aplicar". 0005 remove "dar gate em tudo" e "dar gate em nada". Quando 0018 é escrito, o espaço de design encolheu tanto que a implementação é quase forçada. É o valor de escrever decisões: um agente futuro não pode "simplificar" reintroduzindo uma opção rejeitada, porque a rejeição é versionada e datada.
AIAgent Python para fork; e o princípio do portão de emissão) e marca a segunda como "mais importante". 0006 proíbe sedimento sem gate, o que força a forma propose→dispose em vez da gravação direta do Hermes.ship e gasto real defaultam para T4-park.