"Duas horas, no máximo" — o board do Kanban agora responde com um P50 e um P90


Tem um card no board do Kanban. A descrição é boa e termina com “estimativa: 2 horas”. Você entrega a um worker e vai fazer outra coisa. Três horas depois ele ainda está rodando. Seis horas depois, rodando testes. Na nona hora, finalmente, aparece um PR.

Na próxima vez que surge uma tarefa parecida, você escreve “estimativa: 2 horas” de novo. Não por falta de memória, mas porque nada, em lugar nenhum, registra que esse tipo de tarefa levou nove. Estimar raramente falha por falta de metodologia. Falha por falta de feedback.

O Epoch, um plugin da comunidade que agora está no catálogo do Hermes, fecha exatamente esse ciclo: estimar, medir, calibrar.

O que ele faz de fato no board

Três movimentos, todos em momentos com que você já se importa:

  1. No instante em que um worker assume a tarefa, o plugin publica uma estimativa Monte Carlo como comentário da tarefa — P50 e P90, com P80/P95 ao lado, e não um vago “cerca de duas horas”.
  2. Quando aquela execução termina, ele grava as horas de relógio da execução no ledger próprio do Epoch, marcadas com auto_wallclock — medidas, não digitadas por um humano.
  3. A estimativa seguinte se calibra com esses valores reais. Quanto mais execuções, menor o erro.

Ele se pendura em dois hooks do Kanban: kanban_task_claimed e kanban_task_completed. Você não muda seu fluxo de trabalho com tarefas. Se o plugin estiver instalado e o board estiver em uso, a estimativa aparece no card.

Ele também registra uma ferramenta epoch_estimate e um comando de barra /epoch para pedir uma estimativa avulsa.

Três coisas a saber antes de instalar

Primeiro, é um plugin da comunidade, não algo embutido no Hermes. O tier no catálogo é community, o mantenedor é a KyaniteLabs e o requires_hermes é >=0.21.6.

Segundo, ele exige Node 22+ e acesso de rede ao npm na primeira execução. O plugin é uma casca fina; o estimador em si é um processo filho rodando npx -y @kyanitelabs/[email protected], que baixa o Epoch e suas dependências na primeira vez.

Terceiro, o título da tarefa é passado para esse CLI local — os primeiros 80 caracteres, mais a sua dica de três pontos. Nada sai da máquina, mas “fica local” e “não envia nada” são promessas diferentes, e esta é a primeira.

A instalação é um comando:

hermes plugins install epoch

Depois confirme que ele está na lista e habilitado:

hermes plugins list

Plugins passam a valer no próximo ciclo de carregamento. Se você instalou com uma session já rodando e a ferramenta dele não aparece, reiniciar o gateway uma vez é a solução mais simples.

Escrevendo um card que possa realmente ser calibrado

Por padrão, ele recorre a uma estimativa por classe de referência — uma faixa derivada de tarefas históricas do mesmo tipo. Esse padrão é útil desde o primeiro dia, porque o Epoch traz um banco de referência embutido.

O que torna as estimativas precisas, porém, é uma faixa explícita de três pontos na tarefa:

Refactor fee calculation to remove floating point drift

epoch: 2/4/10h

2/4/10h é mais otimista / mais provável / mais pessimista. Com três números, o Monte Carlo tem uma distribuição para amostrar, e P50/P90 passam a significar algo. Sem isso, o plugin só consegue produzir uma faixa por classe de referência — utilizável, mas não tão boa quanto a sua própria entrada.

Mantenha as unidades simples: h para horas, três números separados por barra. “2-10 horas” não é uma estimativa de três pontos.

Onde ele fica deliberadamente estreito

Plugins que mantêm registros do seu trabalho são fáceis de superdimensionar, e a divulgação do Epoch é incomumente específica. Alguns pontos merecem repetição:

  • O ambiente do processo filho é limpo: só PATH, HOME, locale e diretórios temporários, além de variáveis de cache do Node/npm, registry, CA e proxy passam. O ambiente do processo pai, API keys e segredos do Hermes nunca são repassados.
  • A telemetria é forçada a desligar: toda execução do plugin define EPOCH_TELEMETRY=0. A telemetria do Epoch standalone é opt-in; o plugin nunca faz opt-in por você.
  • Os dados ficam em HERMES_HOME/plugin-data/epoch/: estimativas, valores reais e vínculos de execução, compartilhados por todos os profiles.
  • O /epoch é um passthrough restrito: repassa outros subcomandos, mas recusa serve, self-improve e qualquer coisa que altere telemetria ou dados. Em plataformas de gateway ele também recusa subcomandos que escrevem no ledger, a menos que você defina allow_write_slash_on_gateway: true.
  • Comentários são apenas exibição: as estimativas são vinculadas às execuções por um mapeamento guardado ao lado do ledger, então um marcador forjado em um comentário não consegue redirecionar o registro.

O trabalho dos hooks roda em threads de background de vida curta, com um contexto de contextvars copiado, então nunca atrasa a criação do worker. Se o processo terminar antes de um job acabar, uma outbox local do profile o reexecuta no próximo carregamento do plugin.

Três ressalvas que importam

Um: o teto de 12 horas para o registro. Um portão de sanidade aceita apenas execuções entre 0,05 e 12 horas, e no máximo 10× a estimativa. A intenção é óbvia — rejeitar medições claramente erradas —, mas isso também significa que o valor real de uma execução de 14 horas não é registrado. Se as suas tarefas são longas, os dados de calibração ficarão escassos.

Dois: a primeira execução pode travar no npm. As dependências são baixadas no primeiro uso. Com uma política do tipo min-release-age no npm, a versão fixada pode não ter idade suficiente e o download é recusado. O plugin mantém o job na fila e tenta de novo em vez de falhar, então o sintoma é “a estimativa nunca aparece”, não um erro claro. Depois de instalar, dispare-o uma vez manualmente para confirmar que o download funciona.

Três: ele não sabe das 2 horas que você tinha em mente. A faixa de três pontos é sua; o plugin só consegue amostrá-la. Valores de “mais provável” habitualmente otimistas produzem um P50 otimista — exceto que, desta vez, o viés fica registrado e é absorvido pela estimativa seguinte. É aí que ele ganha de um humano, mas isso também significa que as primeiras estimativas merecem desconfiança.

Para quem serve, para quem não serve

Serve: times com tipos de tarefa recorrentes, cards com uma definição de pronto clara e dez segundos de folga para uma faixa de três pontos. Depois de duas ou três semanas, “quanto tempo esse tipo de tarefa leva” deixa de ser questão de memória e humor.

Não serve: exploração pontual (sem classe de referência que valha), projetos que rodam mais de 12 horas por tarefa (o portão os descarta) e hosts totalmente offline que não alcançam o npm.

Uma nota sobre como ele se relaciona com a maquinaria de board do próprio Hermes: o ciclo de vida da tarefa, a revisão e o comportamento de reivindicação são embutidos no Hermes; o Epoch apenas pendura uma camada de estimativa nos hooks de claim e complete. Para entender o board em si, veja o ciclo de vida de revisão do Kanban. Para saber o que mais vale instalar, este detalhamento da varredura em lote do catálogo explica as regras de admissão.

Quando você pode usar isto

A entrada no catálogo foi integrada em 8 de novembro de 2026 (PR #149757), versão 0.7.0, e já está na main. Em uma release estável você pode instalá-lo desde que o requires_hermes esteja satisfeito (>=0.21.6) — o catálogo é lido em tempo de execução, então nenhuma release do Hermes é necessária.

Resumo rápido

Estimativas erram porque ninguém devolve as horas reais. O Epoch dá uma mão em dois momentos no board do Kanban: na hora do claim ele publica uma estimativa Monte Carlo com P50/P90, e na conclusão grava as horas reais em um ledger. O custo é um download do npm na primeira execução e um teto de 12 horas para o que é registrado; o retorno é que, a partir da terceira semana mais ou menos, o número no seu card começa a se parecer com a realidade.