koffih/prova-de-conclusão

Prova de conclusão

Você não decide que o trabalho está concluído. Um script decide, a partir de recibos. Seu trabalho é escrever o contrato, produzir as provas e relatar o veredito que o script calcular, palavra por palavra.

Solicitação: $ARGUMENTS

A regra

SEM RECIBO, SEM ALEGAÇÃO.
Um recibo só conta no código em que foi obtido.
O veredito é calculado, nunca escrito à mão.

"Concluído", "corrigido", "funciona", "passa", "pronto", "implantado", "tudo certo", uma marca de verificação, ou qualquer frase que leve o leitor a acreditar em uma destas, é uma alegação. Também "deve funcionar", que é uma alegação com uma desculpa anexada. Toda alegação precisa de uma linha COMPROVADO no registro para a árvore atual, ou não é feita.

O motor

scripts/proof.py na pasta desta skill (normalmente ~/.claude/skills/prova-de-conclusao/scripts/proof.py, ou .claude/skills/prova-de-conclusao/... em um projeto). Biblioteca padrão, Python 3.8+. Configure uma vez por sessão:

P="python3 $(ls -d ~/.claude/skills/prova-de-conclusao .claude/skills/prova-de-conclusao 2>/dev/null | head -1)/scripts/proof.py"

Tudo reside em .proof/ na raiz do projeto: acceptance.md (o contrato, comite-o), contract.lock e contract-log.md (comite-os), receipts.jsonl e artifacts/ (evidências locais, ignoradas pelo git).

Os cinco movimentos

1. Contrato, antes do código

$P init, depois escreva .proof/acceptance.md. Uma linha por critério, quatro campos:

- AC1 :: um usuário logado pode conectar o Gmail e vê "Conectado" :: e2e :: run: npx playwright test tests/gmail-connect.spec.ts
- AC2 :: um e-mail se torna uma tarefa com seu assunto como título :: integracao :: run: pytest tests/test_email_to_task.py -q
- AC3 :: a página de caixa de entrada mostra a nova tarefa sem recarregar :: visual :: see: captura de tela após converter um e-mail

• Um critério declara o que alguém pode observar (um usuário, um chamador, um arquivo, uma linha), não qual código existe. "Adicionou um manipulador" não é um critério.
• O nível é a força da prova que a alegação precisa. Leia references/proof-ladder.md para escolhê-lo: uma alegação de interface precisa de pelo menos e2e ou visual, uma correção de bug precisa de um teste que falhou antes da correção, uma implantação precisa de runtime no alvo implantado.
• run: é o comando exato que sai com 0 apenas se o critério for válido. Escreva como você irá executá-lo. Ser restrito é aceitável (um arquivo de teste), ser vazio não é (true, echo ok, um teste sem asserção).
• Se o usuário deu critérios, use as palavras dele. Se não, deduza-os da solicitação, mostre-os em um bloco curto e prossiga (não espere a menos que um critério seja realmente ambíguo). Adicione uma lista ## Fora do escopo para que ninguém o avalie pelo que não foi solicitado.
• $P freeze. A partir de agora, remover um critério, diminuir um nível ou trocar um comando por um mais fácil aparecerá em contract-log.md e precisará de --reason com a concordância do usuário. Adicionar critérios é sempre permitido.

Para uma alteração de uma linha, o contrato pode ser um critério. Ele ainda existe.

2. Construir, provando enquanto avança

Implemente normalmente. Após cada passo coerente, $P run AC2 (ou $P run --all) e leia o que imprime. Uma linha FALHOU é informação, não um obstáculo a ser contornado: leia a saída, corrija a causa, execute novamente. Para uma correção de bug, execute o novo teste antes da correção e mantenha aquele recibo de falha em mente: um teste de regressão que nunca falhou não prova nada (vermelho, depois verde).

Para critérios see:: produza a evidência (captura de tela do Playwright, saída de curl -i salva em um arquivo, um CSV exportado, um trecho de log), abra e olhe para ela (Leia a imagem, leia o arquivo), depois $P attach AC3 caminho/para/captura.png --note "caixa de entrada após converter, tarefa visível". O arquivo é copiado para .proof/artifacts/, para não perturbar outros recibos. Anexar uma captura de tela que você não olhou é a mesma mentira que citar um teste que você não executou.

3. Veredito

$P run --all      # recibos novos para cada critério run:, na árvore final
$P verdict        # o registro e o veredito; sai com 0 apenas se CONCLUÍDO

Estados: COMPROVADO (recibo passa na árvore atual), FALHOU, PENDENTE (sem recibo), OBSOLETO (código mudou após a prova), INCOMPATÍVEL (o recibo executou outro comando diferente do contrato), SUSPEITO (saiu com 0 mas zero testes rodaram, apenas pulos, uma ferramenta faltando, ou a prova editou a árvore), BLOQUEADO, RENUNCIADO. Vereditos: CONCLUÍDO, CONCLUÍDO COM RENÚNCIAS, BLOQUEADO, NÃO CONCLUÍDO.

Qualquer edição após a última execução, mesmo um comentário, torna os recibos OBSOLETOS. Esse é o ponto: reexecute por último, relate imediatamente depois.

4. Verificação independente

O criador nunca avalia seu próprio trabalho. Quando a tarefa é mais que uma pequena alteração, mexeu em uma interface, uma implantação ou dados, ou foi feita por subagentes, lance um subagente verificador com o prompt em references/checker.md. Ele relê o contrato, reexecuta as provas por conta própria, olha os arquivos anexados, lê o diff para verificar aumento de escopo e adulteração de portão, e retorna ACEITO ou REJEITADO com razões. Um REJEITADO volta para o movimento 2. Quando um subagente disser a você que teve sucesso, trate da mesma forma: git diff --stat, execute a prova dele você mesmo.

5. Relatório

Comece com a linha do veredito exatamente como calculado, depois os recibos:

VEREDITO: CONCLUÍDO   (ou NÃO CONCLUÍDO / BLOQUEADO / CONCLUÍDO COM RENÚNCIAS)

| Critério | Prova | Resultado |
|---|---|---|
| AC1 usuário conecta Gmail, vê "Conectado" | npx playwright test tests/gmail-connect.spec.ts | saída 0, 3 aprovados |
| AC2 e-mail vira tarefa | pytest tests/test_email_to_task.py -q | saída 0, 5 aprovados |
| AC3 caixa de entrada mostra tarefa sem recarregar | .proof/artifacts/AC3-...png (olhado) | tarefa visível no topo |

Verificador: ACEITO (ou REJEITADO: ...)
Não comprovado: nenhum   (ou cada critério aberto, por que, e o próximo passo)
Fora do escopo: ...

Em NÃO CONCLUÍDO, diga isso primeiro e claramente, depois o que está comprovado, o que não está, e o menor próximo passo. Um NÃO CONCLUÍDO claro é um bom relatório. Um CONCLUÍDO que se revela falso custa ao usuário uma sessão de depuração e sua confiança.

Guarda de linguagem

Antes de enviar qualquer mensagem, verifique-a. Estes precisam de um recibo COMPROVADO na árvore atual, ou são removidos:

• concluído, finalizado, completo, corrigido, resolvido, funciona, funcionando, passa, verde, pronto, enviado, implantado, ao vivo, tudo certo, deve funcionar, deve estar corrigido, provavelmente, parece bom, ✅, "Perfeito!", "Ótimo, funcionou"
• "testes passam" quando você executou um subconjunto; "build passa" quando você executou o linter; "implantado" quando você fez push; "corrigido" quando você mudou código e não reproduziu o sintoma.

Diga o que você executou e o que retornou: "pytest tests/test_email_to_task.py: 5 aprovados, saída 0" se sustenta. Quando você não executou: "não verificado ainda".

A tabela completa de desculpas e as formas como uma prova é manipulada está em references/anti-gaming.md. Leia uma vez por projeto; a versão curta: nunca enfraqueça, pule, simule, apague a coisa que prova a alegação, e nunca edite um teste para corresponder a uma saída errada.

Hook de parada (opcional, por projeto)

$P hook --install adiciona um hook de Parada a ./.claude/settings.local.json (--shared para o settings.json versionado). Em um projeto que possui .proof/acceptance.md, quando a sessão tenta encerrar enquanto o veredito não é CONCLUÍDO, o hook a envia de volta uma vez com os critérios abertos, a menos que a última mensagem já contenha VEREDITO: NÃO CONCLUÍDO ou VEREDITO: BLOQUEADO. Ele nunca entra em loop (deixa a segunda parada passar) e não faz nada em projetos sem contrato. Instale-o para trabalhos longos ou não supervisionados; informe o usuário que ele está lá.

Quando a prova não pode ser executada

Sem navegador, sem acesso a staging, um segredo faltando, uma API paga: não substitua por uma prova mais fraca silenciosamente. $P block AC4 --reason "sem credenciais de staging" e relate BLOQUEADO com a coisa exata que está faltando e o comando que a provaria quando ela estiver disponível. $P waive existe apenas para um critério que o usuário explicitamente descarta, nas palavras dele, citadas na razão.

Tarefas pequenas

Um erro de digitação ou uma configuração de uma linha: um critério, um comando, um recibo, uma linha no relatório (VEREDITO: CONCLUÍDO + o comando e seu resultado). A cerimônia reduz; a regra não.