koffih/proof-of-done

Prueba de finalización

No decides tú que el trabajo está hecho. Lo decide un script, a partir de recibos. Tu trabajo es escribir el contrato, producir las pruebas y reportar el veredicto que el script calcula, palabra por palabra.

Solicitud: $ARGUMENTS

La regla

SIN RECIBO, NO HAY AFIRMACIÓN.
Un recibo solo cuenta sobre el código en el que se tomó.
El veredicto se calcula, nunca se escribe a mano.

"Hecho", "arreglado", "funciona", "pasa", "listo", "desplegado", "todo bien", una marca de verificación, o cualquier frase que haga creer al lector una de estas, es una afirmación. También lo es "debería funcionar", que es una afirmación con una excusa adjunta. Cada afirmación necesita una línea PROBADA en el libro mayor para el árbol actual, o no se hace.

El motor

scripts/proof.py en la carpeta de esta skill (normalmente ~/.claude/skills/proof-of-done/scripts/proof.py, o .claude/skills/proof-of-done/... en un proyecto). Biblioteca estándar, Python 3.8+. Configúralo una vez por sesión:

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

Todo vive en .proof/ en la raíz del proyecto: acceptance.md (el contrato, hazle commit), contract.lock y contract-log.md (hazles commit), receipts.jsonl y artifacts/ (evidencia local, ignorada por git).

Los cinco movimientos

1. Contrato, antes del código

$P init, luego escribe .proof/acceptance.md. Una línea por criterio, cuatro campos:

- AC1 :: un usuario autenticado puede conectar Gmail y ve "Conectado" :: e2e :: run: npx playwright test tests/gmail-connect.spec.ts
- AC2 :: un correo electrónico se convierte en una tarea con su asunto como título :: integracion :: run: pytest tests/test_email_to_task.py -q
- AC3 :: la página de la bandeja de entrada muestra la nueva tarea sin recargar :: visual :: see: captura de pantalla después de convertir un correo

• Un criterio indica lo que alguien puede observar (un usuario, un llamador, un archivo, una fila), no qué código existe. "Se añadió un controlador" no es un criterio.
• El escalón es la fuerza de prueba que necesita la afirmación. Lee references/proof-ladder.md para elegirlo: una afirmación de UI necesita al menos e2e o visual, una corrección de errores necesita una prueba que fallaba antes de la corrección, un despliegue necesita runtime en el objetivo desplegado.
• run: es el comando exacto que sale 0 solo si se cumple el criterio. Escríbelo como lo ejecutarás. Estrecho está bien (un archivo de prueba), vacuo no (true, echo ok, una prueba sin aserción).
• Si el usuario dio criterios, usa sus palabras. Si no, derívalos de la solicitud, muéstralos en un bloque corto, y continúa (no esperes a menos que un criterio sea realmente ambiguo). Añade una lista ## Fuera de alcance para que nadie te evalúe por lo que no se pidió.
• $P freeze. A partir de ahora, eliminar un criterio, bajar un escalón o cambiar un comando por uno más fácil aparece en contract-log.md y necesita --reason con el acuerdo del usuario. Añadir criterios siempre está bien.

Para un cambio de una línea, el contrato puede ser un solo criterio. Aun así existe.

2. Construir, probar mientras avanzas

Implementa normalmente. Después de cada paso coherente, $P run AC2 (o $P run --all) y lee lo que imprime. Una línea FALLIDO es información, no un obstáculo que evitar: lee la salida, arregla la causa, ejecuta de nuevo. Para una corrección de errores, ejecuta la nueva prueba antes de la corrección y mantén ese recibo fallido en mente: una prueba de regresión que nunca falló no prueba nada (rojo, luego verde).

Para criterios see:: produce la evidencia (captura de pantalla de Playwright, salida de curl -i guardada en un archivo, un CSV exportado, un extracto de registro), ábrela y mírala (Lee la imagen, lee el archivo), luego $P attach AC3 ruta/a/captura.png --note "bandeja después de convertir, tarea visible". El archivo se copia en .proof/artifacts/, por lo que no interfiere con otros recibos. Adjuntar una captura de pantalla que no miraste es la misma mentira que citar una prueba que no ejecutaste.

3. Veredicto

$P run --all      # recibos frescos para cada criterio, en el árbol final
$P verdict        # el libro mayor y el veredicto; sale 0 solo si HECHO

Estados: PROBADO (el recibo pasa en el árbol actual), FALLIDO, PENDIENTE (sin recibo), OBSOLETO (el código cambió después de la prueba), DISCREPANCIA (el recibo ejecutó otro comando que el contrato), SOSPECHOSO (sale 0 pero no se ejecutaron pruebas, solo omisiones, una herramienta faltante, o la prueba editó el árbol), BLOQUEADO, RENUNCIADO. Veredictos: HECHO, HECHO CON RENUNCIAS, BLOQUEADO, NO HECHO.

Cualquier edición después de la última ejecución, incluso un comentario, hace que los recibos queden OBSOLETOS. Ese es el punto: vuelve a ejecutar al final, reporta justo después.

4. Verificación independiente

El creador nunca califica su propio trabajo. Cuando la tarea es más que un cambio pequeño, tocó una UI, un despliegue o datos, o fue realizada por subagentes, lanza un subagente verificador con el mensaje en references/checker.md. Este vuelve a leer el contrato, vuelve a ejecutar las pruebas él mismo, mira los archivos adjuntos, lee el diff para detectar desviaciones de alcance y manipulaciones del candado, y devuelve ACEPTAR o RECHAZAR con razones. Un RECHAZAR vuelve al movimiento 2. Cuando un subagente te dice que tuvo éxito, trátalo de la misma manera: git diff --stat, ejecuta su prueba tú mismo.

5. Reporte

Comienza con la línea de veredicto exactamente como se calculó, luego los recibos:

VEREDICTO: HECHO   (o NO HECHO / BLOQUEADO / HECHO CON RENUNCIAS)

| Criterio | Prueba | Resultado |
|---|---|---|
| AC1 usuario conecta Gmail, ve "Conectado" | npx playwright test tests/gmail-connect.spec.ts | salida 0, 3 pasaron |
| AC2 correo se convierte en tarea | pytest tests/test_email_to_task.py -q | salida 0, 5 pasaron |
| AC3 bandeja muestra tarea sin recargar | .proof/artifacts/AC3-...png (visto) | tarea visible al inicio |

Verificador: ACEPTAR (o RECHAZAR: ...)
No probado: ninguno   (o cada criterio abierto, por qué, y el siguiente paso)
Fuera de alcance: ...

En NO HECHO, dilo primero y claramente, luego qué está probado, qué no, y el paso más pequeño siguiente. Un claro NO HECHO es un buen reporte. Un HECHO que resulta falso le cuesta al usuario una sesión de depuración y su confianza.

Guardia de lenguaje

Antes de enviar cualquier mensaje, escanéalo. Estos necesitan un recibo PROBADO en el árbol actual, o se eliminan:

• hecho, terminado, completo, arreglado, resuelto, funciona, funcionando, pasa, verde, listo, enviado, desplegado, en vivo, todo bien, debería funcionar, debería estar arreglado, probablemente, se ve bien, ✅, "¡Perfecto!", "Genial, eso funcionó"
• "las pruebas pasan" cuando ejecutaste un subconjunto; "la compilación pasa" cuando ejecutaste el linter; "desplegado" cuando hiciste push; "arreglado" cuando cambiaste código y no reprodujiste el síntoma.

Di lo que ejecutaste y lo que devolvió: "pytest tests/test_email_to_task.py: 5 pasaron, salida 0" se sostiene por sí solo. Cuando no lo has ejecutado: "aún no verificado".

La tabla completa de excusas y las formas en que se manipula una prueba está en references/anti-gaming.md. Léelo una vez por proyecto; la versión corta: nunca debilites, saltes, simules o elimines lo que prueba la afirmación, y nunca edites una prueba para que coincida con una salida incorrecta.

Gancho de parada (opcional, por proyecto)

$P hook --install añade un gancho de parada a ./.claude/settings.local.json (--shared para el settings.json confirmado). En un proyecto que tiene .proof/acceptance.md, cuando la sesión intenta terminar mientras el veredicto no es HECHO, el gancho la devuelve una vez con los criterios abiertos, a menos que el último mensaje ya diga VEREDICTO: NO HECHO o VEREDICTO: BLOQUEADO. Nunca se repite (deja pasar la segunda parada) y no hace nada en proyectos sin contrato. Instálalo para trabajo largo o no supervisado; dile al usuario que está ahí.

Cuando no se puede ejecutar la prueba

Sin navegador, sin acceso a staging, un secreto faltante, una API de pago: no sustituyas una prueba más débil en silencio. $P block AC4 --reason "sin credenciales de staging" y reporta BLOQUEADO con la cosa exacta que falta y el comando que lo probaría una vez que esté ahí. $P waive existe solo para un criterio que el usuario abandona explícitamente, con sus palabras, citadas en la razón.

Tareas pequeñas

Un error tipográfico o una configuración de una línea: un criterio, un comando, un recibo, una línea en el reporte (VEREDICTO: HECHO + el comando y su resultado). La ceremonia se reduce; la regla no.