Proof It Works
Esta habilidade possui uma decisão: se o trabalho pode ser chamado de concluído. É um portão rígido, não um conselho.
1. Lei central: Concluído = Comprovado
- Uma afirmação não é evidência. Apenas um artefato reproduzível que um segundo agente possa inspecionar conta.
- Você não pode dizer pronto, corrigido, passando, ou enviado enquanto qualquer item de portão obrigatório na seção 6 estiver faltando.
- "Deve funcionar", "parece certo", "teoricamente ok" e "compila" não são estados de conclusão.
- Se a prova for impossível, declare UNAVAILABLE/BLOCKED (seção 7) — nunca PASS. Uma renúncia por escrito do usuário pode fechar um FAIL como FAIL-WAIVED (seção 7). Uma dimensão não testável por máquina pode permanecer PENDING USER e fechar como PASS-BY-USER após aprovação do usuário (seção 7). Essas três —
FAIL-WAIVED,PENDING USER,PASS-BY-USER— são as únicas saídas que não são evidência de máquina; nenhuma delas é PASS. - A evidência deve vir da árvore de trabalho e do commit de alteração nomeado no relatório (seção 3,
Change ref); artefatos desatualizados são inválidos. - Esta habilidade controla apenas trabalho com uma superfície de tempo de execução ou um entregável de design. Para esse trabalho, seu conjunto mínimo de evidências (um positivo + um reverso) substitui, não se acumula a, qualquer verificação mais leve. Trabalho sem superfície de tempo de execução está fora do escopo e esta habilidade cede inteiramente. Ela não substitui uma entrega que o usuário já aprovou como mínima.
2. Níveis de evidência
Três níveis em ordem estrita: Claim (verbal ou raciocínio, evidência zero) < Artifact (um arquivo de artefato bruto real da superfície desta tarefa) < Artifact + caso reverso. O portão aceita apenas os dois últimos; qual deles um item precisa é definido pelos itens de portão do perfil selecionado, não por uma regra global. Um Claim nunca suporta PASS, e nenhum item pode ser rotulado acima do que realmente é.
3. Binding / 任务绑定
- No topo de
report.md, cite textualmente a frase da solicitação do usuário que define o alvo de aceitação — uma instrução como "altere X para Y e prove" conta; não precisa afirmar que o trabalho está concluído. Rotule-a comoAcceptance target (user verbatim). Somente se a solicitação não definir nenhum alvo de aceitação (nunca diz como o "concluído" deve ser), diga isso em uma linha, peça ao usuário para declarar um e pare — não há nada para controlar. O nível de evidênciaClaimna seção 2 é um conceito separado e mantém seu nome. Change ref(cabeçalho do relatório) = o commit que contém a alteração sob teste — não o commit que adiciona este relatório, e não necessariamente HEAD. Sem git, usesha256 dos arquivos alterados + lista de arquivosem vez de um hash. Após o relatório ser commitado, HEAD avança; isso é normal, e o verificador julga porChange ref, não por HEAD.Working tree(cabeçalho do relatório) é texto livre, não um enum de dois valores, por exemplo,tracked clean; .proof/ untracked.- Declare os arquivos / funções / rotas / componentes que esta alteração tocou, obtidos do diff atual.
- Cada perfil selecionado deve ter pelo menos um item de evidência que atinja este diff (executa ou inspeciona um caminho tocado). Evidência que não toca nada no diff = FAIL, mesmo que todos os artefatos existam.
- Uma linha de base DESIGN deve ter uma fonte externa (seção 6, proof-profiles.md); uma linha de base não rastreável é um
Claime falha em seu item de portão.
4. Selecione o(s) perfil(is) de prova
Escolha o perfil cujo teste de uma linha melhor se ajusta à frase de alvo de aceitação do usuário; uma tarefa pode ser DESIGN e FEATURE ao mesmo tempo e deve então satisfazer ambas. Se nenhum perfil corresponder, diga isso em uma linha e pare — não force um perfil em uma alteração sem superfície de tempo de execução.
| Perfil | Teste de uma linha | Detalhe |
|---|---|---|
| DESIGN | Você produziu uma especificação, layout, interação, arquitetura ou contrato que deve ser mostrado implementado, não apenas proposto. | references/proof-profiles.md |
| FEATURE | Você alterou o comportamento em tempo de execução e deve mostrar que funciona e que entrada inválida é rejeitada. | references/proof-profiles.md |
| DATAFLOW | Um valor cruza múltiplos estágios (entrada, transformação, persistência, saída) e cada salto deve ser mostrado. | references/proof-profiles.md |
- "Meu design foi implementado" -> DESIGN. "Isso funciona" -> FEATURE. "Para onde os dados foram / eles foram persistidos" -> DATAFLOW.
5. Fluxo de execução
Execute em ordem. Não pule ou reordene.
- Crie
.proof/<task-name>/no repositório (nome curto em kebab-case). Um artefato não é prova até ser um arquivo aqui. - Escreva 3-7 afirmações de aceitação em
report.mdANTES de coletar evidências. Use as 8 colunasid | assertion | expected | pass criterion (checkable) | changed path (file:function/route) | level required | evidence file | depends on. Proíba "parece correto", "parece bem", "funciona como esperado"; use condições verificáveis como "HTTP 200 com body.field X = Y", "largura do retângulo = 120px", "token inválido retorna 401".expectedé o resultado previsto preenchido ANTES de qualquer evidência (por exemplo,401 + BAD_CREDENTIALS,largura do retângulo 240px); FEATURE/DATAFLOW deve preenchê-lo em cada linha, DESIGN pode escrevern/a. Registre o horário de registro no cabeçalho do relatório comoExpected registered (UTC): <time>— o pré-registro é autodeclarado; nenhum hash ou ritual em disco.expectedepass criterionsão duas expressões de uma condição (previsão vs. verificação decidível). Elas não devem entrar em conflito; uma linha conflitante deve ser corrigida ANTES da coleta. O status é decidido exclusivamente pelopass criterioncontraobserved. Seobservedatender ao critério, mas desviar deexpected, corrija a implementação para alinhar comexpectedou marque a afirmação como FAIL — nunca reescrevaexpectedpara o valor observado (seção 8).- Preencha
changed pathcom o arquivo/função/rota que a afirmação exercita; escrevan/aapenas para linhas DESIGN que não executam nenhum caminho de código. Pelo menos uma afirmação deve executar um caminho de código alterado neste diff e nomeá-lo; uma afirmação em um caminho não tocado não vincula. FEATURE/DATAFLOW deve ter pelo menos uma célulachanged pathnãon/a; DESIGN pode usarn/a. depends on= ids de pré-requisitos separados por vírgula (vazio se nenhum), coletados em ordem topológica. Um pré-requisito conta como satisfeito apenas quando seu status éPASSouPASS-BY-USER; se for qualquer outra coisa, a linha downstream éNOT RUN(seção 7) e qualquerNOT RUNfaz o portão FAIL. O grafodepends ondeve ser acíclico — um ciclo é FAIL. Uma linhaUSER-JUDGMENTé uma folha: nenhuma linha pode listar um idUSER-JUDGMENTemdepends on.
- Dirija a superfície real com comandos realmente disponíveis nesta máquina (por exemplo,
npm run devpara iniciar,curl -i -X POST http://localhost:3000/login -d '{"user":"a","pass":"wrong"}'para API, um navegador real + DevTools para UI,tail -fpara logs). Salve stdout/stderr/response/screenshot brutos em arquivos numerados (seção 11).raw= a saída completa como capturada, não resumida, extraída ou reordenada; a dessensibilização é uma transformação única aplicada no momento da captura, portanto não quebra "bruto". Substitua tokens / senhas / chaves por***no arquivo salvo e registre no índice de evidências e ao lado de cada bloco bruto coladoredacted: <nome do campo> (N ocorrência(s))mais o sha256 do arquivo, para que um revisor possa confirmar que nenhuma edição pós-captura ocorreu. Nunca dessensibilize códigos de status, códigos de erro ou qualquer valor do qual uma afirmação dependa. Qualquer placeholder do tipo<启动命令>/<截图工具>deixado no relatório = FAIL; substitua-o pelo comando exato que você executou. - Caso reverso PRIMEIRO. Defina "um comportamento alterado" como cada ramificação adicionada ou modificada no diff (um if/else, guarda, validação ou nova rota); liste cada um no relatório e dê a cada um uma linha na tabela de afirmações. Um caso de limite é decidível: a mesma entrada é aceita (ou se comporta de forma diferente) na implementação anterior à alteração e rejeitada (ou se comporta corretamente) após a alteração. Capture a linha de base anterior à alteração reconstruindo o original —
git stash, uma worktree/checkout do commit anterior à alteração ou uma cópia salva do arquivo original — declare qual no relatório, execute o mesmo comando exato nele e salve o resultado como00-pre-change.log(seção 11). Este "mostrar que falharia antes da alteração" é a linha de base do caso reverso, nunca uma linha de afirmação FAIL terminal (seção 9). Em seguida, para cada comportamento alterado, execute um caso reverso (entrada errada, permissão ausente, valor de limite, pré-condição removida) e registre que ele falha da maneira esperada. Um caso ruim que também falhou antes da alteração não conta. Se o caso for aceito após a alteração, o teste não está no caminho real; corrija e recolete. - Dataflow: antes de coletar, escreva uma linha de transformação esperada em
report.md(forma de entrada -> forma de saída) e referencie-a em cada salto. Em seguida, capture uma amostra real por salto — entrada -> intermediário -> persistência -> saída — com o mesmo id de correlação. Para persistência, cole a consulta de leitura real e seu retorno bruto; reimprimir o valor que você escreveu não é um snapshot. Capture também a linha de base anterior à alteração para o caso reverso conforme etapa 4 (00-pre-change.log): ela deve mostrar o valor rejeitado atingindo a saída antes da alteração. - Os valores observados por DESIGN devem vir de fontes capturadas mecanicamente (JSON de estilo computado,
getBoundingClientRect,textContentdo DOM, saída do CDP) salvas como arquivos; não leia números de uma captura de tela a olho nu. A linha de base deve fornecer uma tolerância numérica (por lado <=2px, por canal <=8); excedê-la = FAIL. Uma captura de tela é apenas revisão por olho humano, nunca a fonte numérica. - Escreva o relatório a partir de references/report-template.md; copie-o, não invente um formato. Mantenha apenas as seções relevantes para o(s) perfil(is) selecionado(s) e exclua as seções inaplicáveis em sua totalidade — excluí-las não viola "copie-o, não invente um formato".
- Julgamento do portão (seção 6): PASS apenas se cada item obrigatório existir no nível obrigatório, toda afirmação não
USER-JUDGMENTforPASS/PASS-BY-USER, pelo menos uma afirmação carregar um veredito de máquina, e não houver ciclo emdepends on; caso contrário FAIL, UNAVAILABLE/BLOCKED, ou PENDING USER (seção 7).GateeResultusam o mesmo enum e devem ser idênticos.
6. Portão rígido (qualquer item faltando = FAIL)
"Concluído" requer que cada caixa esteja marcada. Um arquivo faltando, caso reverso faltando, mock no caminho real ou evidência fora do diff é FAIL independentemente da narrativa.
- Completude (sem itens desconhecidos): o relatório afirma o total de afirmações N e lista um status para cada uma das N afirmações. Os únicos status legais são
PASS | FAIL | NOT RUN | UNAVAILABLE | BLOCKED | USER-JUDGMENT | PASS-BY-USER. Um status vazio, um status fora deste conjunto ou uma contagem listada que difere de N é FAIL. PASS requer que toda linha nãoUSER-JUDGMENTsejaPASS/PASS-BY-USERe nenhumFAIL/NOT RUN/UNAVAILABLE/BLOCKED. USER-JUDGMENTé legal apenas para uma dimensão SEM critério de máquina decidível. Se uma máquina pode julgar a linha, ou a julgou e a condição não se sustenta, seu status é aquele veredito de máquina (PASS/FAIL) — nuncaUSER-JUDGMENT. Qualquer coisa que uma máquina possa medir deve ser sua própria linha com um veredito de máquina. A afirmação vinculada a este diff (seção 3) nunca pode serUSER-JUDGMENT. Um relatório cuja toda afirmação éUSER-JUDGMENTtem uma condição PASS vacuamente verdadeira e é FAIL: pelo menos uma linha deve carregar um veredito de máquina. Testado por máquina e não atendendo ao critério = FAIL, nãoUSER-JUDGMENT.depends oné um DAG: um ciclo é FAIL. Um pré-requisito é satisfeito apenas porPASSouPASS-BY-USER; nenhuma linha pode depender de uma linhaUSER-JUDGMENT, então tais linhas são folhas.- Global: vinculação se mantém (seção 3), pelo menos uma afirmação vincula ao diff (seção 5 etapa 2); uma linha
USER-JUDGMENTnunca conta como PASS e nunca bloqueia o PASS de outro item.
| Perfil | Conjunto mínimo de evidências — todos obrigatórios |
|---|---|
| DESIGN | (a) artefato de linha de base com uma fonte externa: arquivo de design pré-existente + commit de criação, ou a mensagem textual do usuário contendo/aprovando-o, ou uma tabela de especificação incluída como arquivo de linha de base antes de qualquer arquivo de implementação existir, com o bloco de meta fixo (source_type, source_quote_or_path, captured_at_utc, sha256, baseline_method) preenchido no momento da inclusão; engenharia reversa de valores da implementação para a linha de base é proibida; (b) captura de tela de renderização real no commit de alteração; (c) comparação de tamanho, cor, espaçamento, texto, estado para cada elemento no escopo (escopo = todo elemento nomeado no entregável de design; liste elementos excluídos e o motivo), cada linha citando valor da linha de base e um valor observado mecanicamente, com tolerância numérica (<=2px por lado, <=8 por canal) declarada na linha de base; (d) um item reverso com um valor NO limite de tolerância (por exemplo, 243px para uma especificação de 240px em +/-2), mostrado ausente/incompatível via saída bruta; (e) lacunas de especificação declaradas explicitamente: Interpretation (leitura da linha de base escrita antes da implementação, adiciona apenas posição/mapeamento, nunca contradiz um valor de usuário), Excluded (nenhum valor de linha de base existe, escrito textualmente), UNAVAILABLE (valor existe mas não mensurável aqui) — Excluded e UNAVAILABLE em seções separadas do relatório, sem omissão silenciosa; (f) >=1 item de evidência no diff. |
| FEATURE | (a) um transcrição real de I/O dirigida que executa um caminho de código alterado no commit de alteração; (b) um caso reverso por comportamento alterado, sua entrada inválida no limite decidível (aceita/diferente antes da alteração, rejeitada/correta após), apoiada por uma linha de base anterior à alteração 00-pre-change.log e saída bruta mostrando rejeição correta — casos que também falharam antes da alteração não contam; (c) comando/ação exato e change ref registrados; (d) toda afirmação mapeada para um arquivo com um changed path preenchido, e >=1 afirmação executa o caminho alterado e nomeia o arquivo/função/rota alterado; (e) nenhum mock/stub substituindo a cadeia; (f) >=1 item de evidência no diff. |
| DATAFLOW | (0) linha de transformação esperada (forma de entrada -> forma de saída) escrita antes da coleta e referenciada em cada salto; (a) um snapshot por salto (entrada, intermediário, persistência, saída) com o mesmo id de correlação; (b) snapshot de persistência cola a consulta de leitura real + retorno bruto do armazenamento, não uma reimpressão do valor escrito; (c) análise de saída traça de volta todos os valores de forma não ambígua a um valor de entrada no mesmo snapshot, com a linha de transformação esperada listada na seção de análise; (d) linha de base anterior à alteração 00-pre-change.log por caso reverso, mostrando o valor rejeitado atingindo a saída antes da alteração; (e) >=1 item de evidência no diff. |
7. Status legais e tratamentos
Status é ponta, não escala. Um portão possui um status; uma linha de afirmação possui um status. NOT RUN, UNAVAILABLE e BLOCKED são estados terminais da linha de afirmação que não podem ser convertidos após o fato. PENDING USER é um estado de espera; a ação do usuário pode movê-lo para PASS-BY-USER ou mantê-lo como FAIL.
FAIL: O item de evidência ou condição não foi atendido. O portão falha.NOT RUN: A linha de afirmação não foi executada porque um pré-requisito não foi satisfeito (seção 5). QualquerNOT RUNno final faz o portão FAIL. Se um pré-requisito falha, suas dependências transitivas são todasNOT RUN; odepends ondeve ser verificado na ordem topológica (seção 5, etapa 2) para que este efeito em cascata seja capturado — o grafo completo deve ser verificado a partir das raízes primeiro.UNAVAILABLE: A evidência não pode ser coletada (por exemplo, serviço externo fora do ar, licença expirada, ambiente não provisionado). O portão pode declararUNAVAILABLEglobalmente; uma única linhaUNAVAILABLEfaz o portão FAIL.BLOCKED: Uma dependência (pessoa, equipe, revisão de segurança, aprovação legal) não está neste momento disponível. Semelhante aUNAVAILABLE, mas geralmente sinaliza um bloqueio humano ou organizacional. Uma única linhaBLOCKEDfaz o portão FAIL.PENDING USER→PASS-BY-USER: Um item de julgamento humano onde um critério de máquina é impossível. O agente marcaPENDING USER, aguarda aprovação explícita do usuário, então avança paraPASS-BY-USER. Se o usuário recusar, a linha permanece como está e o portão é FAIL.PASS-BY-USERé funcionalmente equivalente aPASSpara o propósito de satisfazer pré-requisitos.FAIL-WAIVEDé para depuração — veja a seção 9.
8. Violações de integridade de evidência
As violações a seguir quebram a confiabilidade do relatório e resultam em FAIL imediato, mesmo que o portão pareça verde:
expectedalterado após a coleta (o arquivo raw de evidência não corresponde mais à previsão); verificado comparando o hash sha256 do arquivo raw com o registrado no índice de evidências no momento da coleta.- Renderizações de captura de tela com visibilidade
hidden,none,opacity: 0, fora da janela de visualização, ou deslocadas; verificado porcheckVisibility()do navegador ou equivalente. - Saída truncada: a saída raw é maior (em bytes) do que o arquivo raw salvo; verificado por contagem de linhas ou tamanho de arquivo.
- Evidência pré-alterada coletada após o pós-alteração (selo de tempo do
00-pre-change.logapós a coleta pós-alteração); verificado pela ordenação de selo de tempo no índice de evidências. - Prompt do usuário ou pergunta de confirmação ignorada: qualquer interação
PENDING USERque nunca foi resolvida; verificado por qualquer statusPENDING USERnão resolvido no final do julgamento.
9. Depuração
O modo de depuração não substitui a prova. É uma fase de solução de problemas que precede a coleta de evidências. Quando ativado:
- O agente escreve um log de depuração em
.proof/<task-name>/debug.mddetalhando a linha do tempo de tentativa e erro:- O que você esperava que acontecesse (por exemplo, "Comando curl na URL de desenvolvimento").
- O que realmente aconteceu (por exemplo, "Erro de conexão recusada").
- O que você tentou a seguir (por exemplo, "Verificou se o servidor de desenvolvimento está em execução").
- Resultado (por exemplo, "Servidor iniciado, curl agora funciona").
- A fase de depuração termina quando o agente pode executar a coleta de prova real. O log de depuração não é evidência.
- O modo de depuração termina automaticamente quando a primeira coleta de evidência começa.
- Se a depuração falhar em resolver (depois de 5 tentativas ou a critério do agente), o portão é
FAIL-WAIVED.FAIL-WAIVEDé um estado de portão terminal que sinaliza que a prova foi tentada mas não pôde ser concluída; um agente ou revisor humano pode aceitar a renúncia em um relatório de depuração. Uma modificação do desenvolvedor ou mudança de ambiente pode transformar umFAIL-WAIVEDem umPASSem uma execução posterior. UmFAIL-WAIVEDnunca conta como PASS para qualquer propósito.
10. Relatório de encerramento
Depois que o portão passar ou falhar, imprima uma seção de encerramento que inclui:
- Resultado geral: PASS / FAIL / UNAVAILABLE / BLOCKED / FAIL-WAIVED
- Resumo das afirmações: número de PASS, FAIL, NOT RUN, UNAVAILABLE, BLOCKED, USER-JUDGMENT, PASS-BY-USER
- Quaisquer itens bloqueados ou não disponíveis com explicação
- Data e hora de conclusão do relatório
11. Convenções de nomenclatura de evidências
00-pre-change.log— captura de linha de base para caso reverso01-positive-case.<ext>— evidência de caso positivo02-reverse-case.<ext>— captura de caso reverso03-dataflow-stage-<name>.<ext>— snapshot de estágio de dataflowscreenshot-<description>.png— capturas de telaartifact-<description>.json— artefatos de dados como estilos computados