~/daily/work 2026-11-20 · published 2026-11-21
Código fresco primeiro, uma vez por sessão
Um hook PreToolUse que faz pull de uma branch padrão limpa na primeira vez que uma sessão toca um repositório e, nos demais casos, só faz fetch e avisa o modelo o que está atrasado.
- harness
- hooks
- git
- python
- ~/project/versatile-sh
O bug que ele previne
Um agente lê código que está três commits atrás do remote, planeja uma mudança em cima dele e abre um pull request que conflita ou reverte algo. Ninguém fez nada errado. O checkout só estava velho.
A regra 12 do harness diz que, na primeira vez que uma sessão toca um repositório, ela faz fetch e o atualiza antes de ler ou mudar código. O pull request #178 adicionou essa regra em 2026-11-20, junto com o hook que a aplica para que ninguém precise lembrar.
O que o hook decide
`hooks/fresh-pull.py` roda antes das ferramentas de arquivo e de shell. Ele descobre o repositório pelo arquivo que está sendo tocado, ou pelo primeiro `cd` de um comando de shell. Age só em repositórios da organização, e só uma vez por sessão e repositório (um arquivo marcador no diretório de cache, limpo após sete dias).
| Estado do checkout | O que o hook faz |
|---|---|
| Limpo, na branch padrão, com upstream | git pull --ff-only, em silêncio |
| Qualquer outro, e está atrasado | git fetch, depois uma linha de contexto para o modelo: quantos commits atrás, em qual branch, se há mudanças locais |
| Qualquer outro, e não está atrasado | Nada |
| Qualquer erro ou timeout (8 segundos por chamada de git) | Silêncio; a chamada da ferramenta segue |
Ele nunca faz stash, reset, rebase nem troca de branch, e nunca bloqueia uma chamada de ferramenta. Quando só fez fetch, a mensagem diz ao modelo para fazer rebase ou merge depois que o dono do trabalho local concordar.
Trade-offs
O hook custa um fetch no primeiro toque, limitado pelo timeout. Em troca, o caso comum, um checkout limpo de `main`, não exige pensar. O caso incomum, uma branch de feature atrasada, vira uma frase no contexto do modelo em vez de uma surpresa na hora do merge.
Duas escolhas vieram da cautela. Primeira, ele prefere não dizer nada a chutar: um fetch que falha é silencioso. Segunda, ele não tenta ser esperto com árvores sujas. Arquivos não rastreados são ignorados ao decidir se uma árvore está suja, mas edições rastreadas interrompem o pull.
Há um interruptor de desligamento (FRESH_PULL=off) e um de ampliação para repositórios fora da organização (FRESH_PULL_ANY=1). Mantive o padrão estreito de propósito: um hook que toca um repositório que não é dele é outro tipo de risco.