Trinta lições que ensinam um sistema real: como o motor Alembic é construído, o que foi destilado por engenharia reversa do Hermes Agent, quais capacidades foram fundidas (e quais foram deliberadamente ignoradas) e o loop fechado auto-evolutivo que resultou — mais a disciplina de ports que sustenta tudo, uma história de guerra de engenharia, um mergulho profundo em cada subsistema @alembic/hermes, o motor inteiro em que a fusão se conecta e o método por trás dele, e por fim dois labs práticos, tópicos avançados e um capstone. Cada afirmação vem dos próprios mapas, ADRs e código do projeto.
@alembic/hermes@alembic/hermes com código verbatim. Motor & método (14–21): o motor em que tudo se conecta — cintura estreita, funil, invariantes, gates, council/verifier, swarm — e o método (engenharia reversa + framework CLONE/ADAPT/MERGE/IGNORE). Labs & avançado (22–30): dois labs práticos, tópicos avançados e o capstone. Cada lição é um arquivo HTML com diagramas, fluxos, demos interativos e quizzes. Alterne claro/escuro no botão ◐ Tema.Os dois sistemas, a decisão que os funde, o loop auto-evolutivo, a disciplina de ports e a história de guerra do vitest-orphan.
As seis camadas do Alembic (L-1 contratos até L4 clientes), a cintura estreita — um contrato Result que nunca lança — e o funil de destilação T0→T3 que transforma fontes cruas em Learnings.
O que é o Hermes Agent, seu catálogo de ferramentas reconstruído tool-a-tool, e o loop de aprendizado fechado (§1.10) que virou a pedra angular da fusão.
A decisão CLONE / ADAPT / MERGE / IGNORE para cada capacidade — por que o loop de aprendizado é a chave, por que o cliente MCP está parado, e por que delegação é IGNORE (o swarm já existe).
Memória de snapshot congelado + passe propor→gate-do-Validador→dispor (ADR-0018) + o ciclo do curador. Por que é gated, não auto-aplicável (ADR-0006).
FsPort, adapter, Clock e idFactory injetados; Result + Zod + never-throws em cada fronteira. O porquê (testabilidade, determinismo, store-agnosticismo — ADR-0009) com código real.
O incidente (16 workers órfãos, ~1550% de CPU), as duas causas, a correção em duas camadas (config endurecida + wrapper que mata o grupo de processos) e como foi verificada.
Sete referências, uma por subsistema @alembic/hermes: API pública, tipos/schemas Zod, a lógica central em código real, as invariantes e o que os testes cobrem.
MEMORY.md/USER.md, add/replace/remove por substring única, o delimitador §, limites 2200/1375, e estado snapshot-vs-live.
reviewAndLearn: o passe gatedpropor→gate→aplicar, o port ReviewGate, scoreThresholdGate(0.7), os buckets aplicado/rejeitado/falho, e controle de fluxo fail-closed.
runCuratorO port Clock, ativo→stale→arquivado, never-delete, os gates pinned/agent-only, e a âncora +Infinity never-active.
Promise + registro de resolvers + timeout, monotonicIdFactory, Zod de pergunta/resposta com validação cruzada, a regra leave-pending.
Ports WebBackend + Compressor, createFetchBackend sobre o fetch global (sem dep), clamp de maxResults, defesa em profundidade.
list=metadata / view=body, CRUD, segurança de path, e o parser de frontmatter escalar sem dependências.
Ports TranscriptionBackend/VisionBackend, fetch backends, Zod na fronteira, e por que o caminho de ML local é IGNORADO.
O motor Alembic em si (o contrato, o funil, as invariantes, os gates, o motor de decisão, o swarm) e o método de engenharia reversa + fusão que produziu o projeto inteiro.
ModelRunResult discriminado em ok (nunca lança), e runWithGuards — Zod-in → try/catch → circuit-breaker → retry → rede de segurança externa.
O ETL de 4 tiers (T0 $0 → T1 ~$0 → T2 metered → T3 council+verifier), o gate verified-GO, e as três invariantes de segurança (PII, orçamento, append-only).
run-never-throws · adapter/store-agnóstico · IDs content-addressed & run-dir determinístico · dissenso preservado pelo Verifier. Quatro, não seis.
Scope → Council → Proof → Validator → Publish, cada um fail-closed — e onde o ReviewGate do loop de aprendizado entra na mesma família.
DebateEngine (fases seriais / membros paralelos), pontuação 0–10, o Verifier maker-checker read-only, e o painel N-lens como gate de emissão T3+.
orchestrator → lead → worker, fila gated por dependências, depth-bound (MAX_DEPTH=2), isolamento por git-worktree, park T4, resume crash-safe.
Como os dois mapas foram construídos: o código vence, tiers de profundidade honestos, Proof-Gate em tudo, builder ≠ validator. A disciplina por trás da fusão.
CLONE / ADAPT / MERGE / IGNORE de ponta a ponta — duas perguntas, um 2×2 e quatro vereditos resolvidos (loop de aprendizado, MCP, delegate, neutts).
Pôr a teoria em prática: dois labs que constroem subsistemas reais, seis deep-dives nas decisões/disciplinas que sustentam tudo, e um capstone que monta a máquina inteira.
Mão na massa: escreva um NoteStore minúsculo do zero — FsPort injetado, Zod na fronteira, Result + never-throws, bounded — espelhando como memory/skills foram feitos. Com exercício "sua vez".
Mão na massa: fie reviewAndLearn a partir de três ports injetados (proposer + ReviewGate + MemoryStore); veja um turno dividir em aplicado/rejeitado/falho, e force cada bucket.
As decisões que moldaram a fusão: ADR-0001 (engine não produto), 0005 (gate humano), 0006 (gate de emissão do validador), 0009 (cintura estreita), 0018 (o loop gated) — e como se restringem.
Profundo no fix do vitest-orphan: grupos de processos, detached:true, kill(-pgid), o wrapper safe-test.mjs, o vitest.config.ts endurecido, e o sweep pós-run. Estende a Lição 06.
ADR-0011: redação de PII antes do egress, fail-closed em tudo, o guarda contra path-traversal, Zod na fronteira, isolamento CL4R1T4S e proveniência content-addressed.
A escada de Tiers T0–T4 + o marcador LOCAL, o registro de 11 modelos, pickCheapestForTier, e o BudgetGuard fail-closed onde um teto não-positivo significa só free-tier.
IDs de run content-addressed (runIdFor), o run-dir determinístico, o ban do VM-de-plano a Date.now()/Math.random(), e o seam de Clock/id-factory injetado que mantém o replay honesto.
A receita: como adicionar um novo subsistema @alembic/hermes — ports-and-injection, Result+Zod, sem nova dep, vitest.config.ts por pacote, test:safe. Um checklist que um agente futuro segue.
O quadro completo: o loop destilar→aprender→sedimentar→podar, o que foi entregue (7 subsistemas, ~565 testes), a fronteira parada (cliente MCP, corpus, design/GTM), e um quiz cruzado.
alembic reais (plan → run → gates → inspect, funil offline, resume, gate T4) + montador de comando.@alembic/hermes · traçar uma chamada de modelo pela cintura estreita e um corpus pelo funil de 4 tiers · nomear as quatro invariantes e os cinco gates · rodar a decisão CLONE/ADAPT/MERGE/IGNORE você mesmo · construir um subsistema ports-and-injection e um passe de aprendizado gated com suas próprias mãos · caminhar pela trilha de ADRs · raciocinar sobre tiers, custo, determinismo e segurança de primeiros princípios · e seguir a receita para adicionar um subsistema novo. Cada lição termina com um quiz.