~/discoveries/work 2026-11-20 · published 2026-11-21
Um portão que o modelo passa fazendo o trabalho
Um hook PreToolUse segura o gh pr create até o checklist de conhecimento da sessão ser registrado. O portão não pergunta a nenhuma pessoa; ele pede ao modelo que termine o trabalho que pulou.
- harness
- hooks
- pull-requests
- python
- ~/project/versatile-sh
A falha que ele ataca
As sessões rodam por repositório. Quando uma sessão encerra um pull request em um projeto, o que ela aprendeu normalmente fica no pull request ou em lugar nenhum. O README pode ser atualizado; o registro na base de conhecimento, uma regra que surgiu, uma nota de que o jeito de trabalhar mudou, muitas vezes não.
A resposta do time é um checklist de cinco linhas: comportamento visível ao usuário (README e docs), registros do projeto, regras e lints, o jeito de trabalhar, e uma última que pergunta se algo de fora da Versatile vazou para os docs. Cada linha termina com um link de pull request, `in this PR` ou `n/a` com um motivo. Um checklist que ninguém é obrigado a ler é decoração, então um hook o impõe.
O que o hook faz
`hooks/pr-gate.py` roda antes de cada chamada de Bash. Não faz nada a menos que o comando seja um `gh pr create` que de fato roda como comando (ele tokeniza a linha de shell, segue `cd` e lê `--repo` e `--head`). Depois verifica se o repositório pertence à organização e se existe um marcador para aquela branch.
Sem marcador: a chamada é negada, com um motivo que é uma lista de tarefas para o modelo. Ele nomeia os passos do checklist, o comando exato de `bin/pr-ready` para registrá-los e a seção do doc que o explica.
bin/pr-ready --readme "in this PR" --records <url> \
--knowledge "n/a: no rule or lint emerged" \
--way "n/a: unchanged" --versatile-only
bin/pr-ready --nothing "a typo fix; nothing was learned or decided"O portão não precisa da aprovação de uma pessoa. O modelo o satisfaz fazendo o checklist. O que a pessoa recebe é o último passo: a mensagem do hook também manda o modelo dizer no chat o que foi atualizado, com links, ou por que nada foi.
Escolhas de design que eu defenderia
- Ele falha aberto. Qualquer exceção dentro do hook deixa o comando passar. Um portão quebrado que bloqueia todo pull request acabaria removido.
- É uma retenção, não um cadeado. O registro expira depois de um dia, e uma variável de ambiente ou um arquivo no diretório de configuração o desliga.
- Não vale para os próprios repositórios do harness. Os pull requests deles são a atualização de conhecimento.
- A saída para uma sessão realmente vazia existe (`--nothing`), mas exige uma string com o motivo. Escrever o motivo é o atrito.
Um portão simbólico pode ser satisfeito simbolicamente. O modelo pode escrever n/a em todas as linhas. O que impede isso é a regra final: o piloto precisa ser avisado no chat, então um n/a preguiçoso fica visível para um humano.
O que não medi
Não tenho a contagem de quantas vezes o portão segurou um pull request nem de quantas respostas foram n/a. O hook entrou em 2026-11-20, e a regra do doc sobre o checklist foi revisada no mesmo dia (o #166 fez o portão citar o doc que uma skill pessoal de mesmo nome não carregaria). Até existir um log de retenções, a afirmação de que o portão melhora os registros é uma hipótese. A primeira coisa a olhar é a proporção de respostas n/a para links.