Proof It Works (Preuve de fonctionnement)
Cette compétence prend une seule décision : si le travail peut être considéré comme terminé. C'est une porte verrouillée, pas un conseil.
1. Loi fondamentale : Terminé = Prouvé
- Une affirmation n'est pas une preuve. Seul un artefact reproductible qu'un second agent peut inspecter compte.
- Vous ne pouvez pas dire « terminé », « corrigé », « passe » ou « livré » si l'un des éléments de la porte obligatoire de la section 6 est manquant.
- « Devrait fonctionner », « a l'air correct », « théoriquement bien », « compile » ne sont pas des états de complétion.
- Si la preuve est impossible, déclarez
INDISPONIBLE/BLOQUÉ(section 7) — jamaisPASS. Une dérogation écrite de l'utilisateur peut clore unFAILenFAIL-WAIVED(section 7). Une dimension non testable par machine peut resterPENDING USERet se clore enPASS-BY-USERavec l'approbation de l'utilisateur (section 7). Ces trois —FAIL-WAIVED,PENDING USER,PASS-BY-USER— sont les seules sorties sans preuve machine ; aucune n'estPASS. - La preuve doit provenir de l'arbre de travail et du commit de changement nommé dans le rapport (section 3,
Change ref) ; les artefacts obsolètes sont invalides. - Cette compétence ne contrôle que le travail ayant une surface d'exécution ou un livrable de conception. Pour ce travail, son ensemble de preuves minimal (une positive + une inverse) remplace, et ne s'empile pas, sur toute vérification plus légère. Tout travail sans surface d'exécution est hors du périmètre et cette compétence cède entièrement. Elle ne remplace pas une livraison que l'utilisateur a déjà approuvée comme minimale.
2. Niveaux de preuve
Trois niveaux dans un ordre strict : Affirmation (verbal ou raisonnement, aucune preuve) < Artefact (un vrai fichier artefact brut de cette tâche) < Artefact + cas inverse. La porte n'accepte que les deux derniers ; lequel est requis pour un élément est défini par les éléments de la porte du profil sélectionné, pas par une règle globale. Une Affirmation ne soutient jamais un PASS, et aucun élément ne peut être étiqueté au-dessus de ce qu'il est réellement.
3. Liaison / 任务绑定
- En haut de
report.md, citez textuellement la phrase de la demande de l'utilisateur qui définit l'objectif d'acceptation — une instruction telle que « changer X en Y et le prouver » compte ; elle n'a pas besoin de préciser que le travail est terminé. Étiquetez-laObjectif d'acceptation (texte exact de l'utilisateur). Seulement si la demande ne définit aucun objectif d'acceptation (elle ne dit jamais à quoi « terminé » doit ressembler), dites-le en une ligne, demandez à l'utilisateur d'en préciser un, et arrêtez-vous — il n'y a rien à contrôler. Le niveau de preuveAffirmationde la section 2 est un concept distinct et conserve son nom. Change ref(en-tête du rapport) = le commit qui contient le changement testé — pas le commit qui ajoute ce rapport, et pas nécessairement HEAD. Sans git, utilisezsha256 des fichiers modifiés + liste des fichiersau lieu d'un hash. Après que le rapport est commité, HEAD avance ; c'est normal, et le vérificateur juge selonChange ref, pas HEAD.Arbre de travail(en-tête du rapport) est un texte libre, pas une énumération à deux valeurs, ex.tracked clean; .proof/ untracked.- Déclarez les fichiers / fonctions / routes / composants que ce changement a touchés, tirés du diff actuel.
- Chaque profil sélectionné doit avoir au moins un élément de preuve qui atterrit sur ce diff (exécute ou inspecte un chemin touché). Une preuve qui ne touche rien dans le diff =
FAIL, même si tous les artefacts existent. - Une base de référence DESIGN doit avoir une source externe (section 6, proof-profiles.md) ; une base de référence introuvable est une
Affirmationet échoue son élément de porte.
4. Sélectionner le(s) profil(s) de preuve
Choisissez le profil dont le test en une ligne correspond le mieux à la phrase d'objectif d'acceptation de l'utilisateur ; une tâche peut être DESIGN et FEATURE à la fois et doit alors satisfaire les deux. Si aucun profil ne correspond, dites-le en une ligne et arrêtez-vous — ne forcez pas un profil sur un changement sans surface d'exécution.
| Profil | Test en une ligne | Détail |
|---|---|---|
| DESIGN | Vous avez produit une spécification, mise en page, interaction, architecture ou contrat qui doit être montré comme implémenté, pas seulement proposé. | references/proof-profiles.md |
| FEATURE | Vous avez modifié le comportement d'exécution et devez montrer qu'il fonctionne et que les entrées invalides sont rejetées. | references/proof-profiles.md |
| DATAFLOW | Une valeur traverse plusieurs étapes (entrée, transformation, persistance, sortie) et chaque saut doit être montré. | references/proof-profiles.md |
- « Mon design a-t-il été implémenté ? » -> DESIGN. « Est-ce que ça marche ? » -> FEATURE. « Où sont passées les données / sont-elles persistées ? » -> DATAFLOW.
5. Flux d'exécution
Exécutez dans l'ordre. Ne sautez pas et ne réordonnez pas.
- Créez
.proof/<nom-de-la-tâche>/dans le dépôt (nom court en kebab-case). Un artefact n'est pas une preuve tant qu'il n'est pas un fichier ici. - Écrivez 3 à 7 assertions d'acceptation dans
report.mdAVANT de collecter les preuves. Utilisez les 8 colonnesid | assertion | attendu | critère de réussite (vérifiable) | chemin modifié (fichier:fonction/route) | niveau requis | fichier preuve | dépend de. Interdisez « a l'air correct », « semble bien », « fonctionne comme prévu » ; utilisez des conditions vérifiables comme « HTTP 200 avec corps.champ X = Y », « largeur rect = 120px », « jeton invalide retourne 401 ».attenduest le résultat prédit rempli AVANT toute preuve (ex.401 + BAD_CREDENTIALS,largeur rect 240px) ; FEATURE/DATAFLOW doit le remplir sur chaque ligne, DESIGN peut écriren/a. Enregistrez l'heure d'enregistrement dans l'en-tête du rapport commeAttendu enregistré (UTC) : <heure>— le pré-enregistrement est autodéclaré ; pas de hash ou de rituel sur disque.attenduetcritère de réussitesont deux expressions d'une même condition (prédiction vs vérification décidable). Ils ne doivent pas entrer en conflit ; une ligne en conflit doit être corrigée AVANT la collecte. Le statut est décidé uniquement par lecritère de réussitepar rapport à l'observé. Siobservésatisfait le critère mais s'écarte de l'attendu, corrigez l'implémentation pour correspondre à l'attenduou marquez l'assertion commeFAIL— ne réécrivez jamais l'attenduà la valeur observée (section 8).- Remplissez
chemin modifiéavec le fichier/fonction/route que l'assertion exerce ; écrivezn/auniquement pour les lignes DESIGN qui n'exécutent aucun chemin de code. Au moins une assertion doit exécuter un chemin de code modifié dans ce diff et le nommer ; une assertion sur un chemin non touché ne lie pas. FEATURE/DATAFLOW doit avoir au moins une cellulechemin modifiénon-n/a; DESIGN peut utilisern/a. dépend de= identifiants de prérequis séparés par des virgules (vides si aucun), collectés dans l'ordre topologique. Un prérequis est considéré comme satisfait uniquement lorsque son statut estPASSouPASS-BY-USER; s'il est autre chose, la ligne en aval estNON EXÉCUTÉ(section 7) et toutNON EXÉCUTÉfait échouer la porte. Le graphedépend dedoit être acyclique — un cycle estFAIL. Une ligneUSER-JUDGMENTest une feuille : aucune ligne ne peut lister un identifiantUSER-JUDGMENTdansdépend de.
- Pilotez la surface réelle avec des commandes réellement disponibles sur cette machine (ex.
npm run devpour démarrer,curl -i -X POST http://localhost:3000/login -d '{"utilisateur":"a","mot_de_passe":"wrong"}'pour API, un vrai navigateur + DevTools pour UI,tail -fpour les logs). Sauvegardez la sortie brute stdout/stderr/réponse/capture d'écran dans des fichiers numérotés (section 11).brut= la sortie complète telle que capturée, non résumée, extraite ou réordonnée ; la désensibilisation est une transformation unique appliquée au moment de la capture, donc elle ne casse pas « brut ». Remplacez les jetons / mots de passe / clés par***dans le fichier sauvegardé, et enregistrez dans l'index des preuves et à côté de chaque bloc brut collémasqué : <nom du champ> (N occurrence(s))plus le sha256 du fichier, afin qu'un relecteur puisse confirmer qu'il n'y a pas eu d'édition après capture. Ne désensibilisez jamais les codes de statut, les codes d'erreur ou toute valeur dont une assertion dépend. Tout espace réservé de style<启动命令>/<截图工具>laissé dans le rapport = FAIL ; remplacez-le par la commande exacte que vous avez exécutée. - Cas inverse EN PREMIER. Définissez « un comportement modifié » comme chaque branche ajoutée ou modifiée dans le diff (un if/else, garde, validation, ou nouvelle route) ; listez-les tous dans le rapport et donnez à chacun une ligne dans la table d'assertions. Un cas limite est décidable : la même entrée est acceptée (ou se comporte différemment) sur l'implémentation d'avant le changement et rejetée (ou se comporte correctement) après le changement. Capturez la base de référence d'avant le changement en reconstruisant l'original —
git stash, un worktree/checkout du commit d'avant le changement, ou une copie sauvegardée du fichier original — indiquez laquelle dans le rapport, exécutez la même commande dessus, et sauvegardez le résultat sous00-pre-change.log(section 11). Cette « étape montrant qu'il échouerait avant le changement » est la base de référence du cas inverse, jamais une ligne d'assertion terminale-FAIL (section 9). Ensuite, pour chaque comportement modifié, exécutez un cas inverse (mauvaise entrée, permission manquante, valeur limite, précondition retirée) et enregistrez qu'il échoue de la manière attendue. Un mauvais cas qui échouait aussi avant le changement ne compte pas. Si le cas est accepté après le changement, le test n'est pas sur le vrai chemin ; corrigez et recollectez. - Dataflow : avant la collecte, écrivez une ligne de transformation attendue dans
report.md(forme d'entrée -> forme de sortie) et référencez-la à chaque saut. Capturez ensuite un échantillon réel par saut — entrée -> intermédiaire -> persistance -> sortie — avec le même identifiant de corrélation. Pour la persistance, collez la vraie requête de lecture et son retour brut ; réimprimer la valeur que vous avez écrite n'est pas un instantané. Capturez également la base de référence d'avant le changement pour le cas inverse selon l'étape 4 (00-pre-change.log) : elle doit montrer la valeur rejetée atteignant la sortie avant le changement. - Les valeurs observées DESIGN doivent provenir de sources mécaniquement capturées (JSON de style calculé,
getBoundingClientRect,textContentDOM, sortie CDP) sauvegardées dans des fichiers ; ne lisez pas les nombres sur une capture d'écran à l'œil. La base de référence doit donner une tolérance numérique (par côté <=2px, par canal <=8) ; son dépassement = FAIL. Une capture d'écran est uniquement une revue à l'œil humain, jamais la source numérique. - Écrivez le rapport à partir de references/report-template.md ; copiez-le, n'inventez pas de format. Gardez uniquement les sections pertinentes pour le(s) profil(s) sélectionné(s) et supprimez complètement les sections inapplicables — les supprimer ne viole pas « copiez-le, n'inventez pas de format ».
- Jugement de la porte (section 6) : PASS uniquement si chaque élément requis existe au niveau requis, chaque assertion non-
USER-JUDGMENTestPASS/PASS-BY-USER, au moins une assertion porte un verdict machine, et il n'y a pas de cycledépend de; sinon FAIL, INDISPONIBLE/BLOQUÉ, ou PENDING USER (section 7).PorteetRésultatutilisent la même énumération et doivent être identiques.
6. Porte dure (un seul élément manquant = FAIL)
« Terminé » exige que chaque case soit cochée. Un fichier manquant, un cas inverse manquant, un mock sur le vrai chemin, ou une preuve hors du diff est FAIL, indépendamment du récit.
- Complétude (aucun élément inconnu) : le rapport indique le nombre total N d'assertions et liste un statut pour chacune des N assertions. Les seuls statuts légaux sont
PASS | FAIL | NON EXÉCUTÉ | INDISPONIBLE | BLOQUÉ | USER-JUDGMENT | PASS-BY-USER. Un statut vide, un statut en dehors de cet ensemble, ou un nombre listé qui diffère de N est FAIL. PASS exige que chaque ligne non-USER-JUDGMENTsoitPASS/PASS-BY-USERet qu'il n'y ait pas deFAIL/NON EXÉCUTÉ/INDISPONIBLE/BLOQUÉ. USER-JUDGMENTn'est légal que pour une dimension SANS critère machine décidable. Si une machine peut juger la ligne, ou l'a jugée et la condition n'est pas remplie, son statut est ce verdict machine (PASS/FAIL) — jamaisUSER-JUDGMENT. Tout ce qu'une machine peut mesurer doit être sa propre ligne avec un verdict machine. L'assertion liée à ce diff (section 3) ne peut jamais êtreUSER-JUDGMENT. Un rapport dont chaque assertion estUSER-JUDGMENTa une condition PASS trivialement vraie et est FAIL : au moins une ligne doit porter un verdict machine. Testé par machine et ne satisfaisant pas le critère = FAIL, pasUSER-JUDGMENT.dépend deest un DAG : un cycle est FAIL. Un prérequis n'est satisfait que parPASSouPASS-BY-USER; aucune ligne ne peut dépendre d'une ligneUSER-JUDGMENT, donc ces lignes sont des feuilles.- Global : la liaison tient (section 3), au moins une assertion lie au diff (section 5 étape 2) ; une ligne
USER-JUDGMENTne compte jamais comme PASS et ne bloque jamais le PASS d'un autre élément.
| Profil | Ensemble de preuves minimal — tous requis |
|---|---|
| DESIGN | (a) artefact de base avec une source externe : fichier de conception préexistant + commit de création, ou message textuel de l'utilisateur le contenant/l'approuvant, ou une table de spécifications placée comme fichier de base avant tout fichier d'implémentation, avec le bloc de métadonnées fixe (source_type, source_quote_or_path, captured_at_utc, sha256, baseline_method) rempli au moment de la mise en place ; l'ingénierie inverse des valeurs de l'implémentation dans la base est interdite ; (b) capture d'écran réelle du rendu au commit du changement ; (c) comparaison de la taille, couleur, espacement, texte, état pour chaque élément dans le périmètre (périmètre = chaque élément nommé dans le livrable de conception ; listez les éléments exclus et pourquoi), chaque ligne citant la valeur de base et une valeur observée mécaniquement sourcée, avec une tolérance numérique (<=2px par côté, <=8 par canal) déclarée dans la base ; (d) un élément inverse avec une valeur SUR la limite de tolérance (ex. 243px pour une spécification de 240px à +/-2), montrée absente/différente via la sortie brute ; (e) lacunes de spécification déclarées explicitement : Interprétation (lecture de base écrite avant l'implémentation, ajoute uniquement la position/le mappage, ne contredit jamais une valeur utilisateur), Exclu (aucune valeur de base n'existe, écrit textuellement), INDISPONIBLE (la valeur existe mais est non mesurable ici) — Exclu et INDISPONIBLE dans des sections séparées du rapport, aucune omission silencieuse ; (f) >=1 élément de preuve sur le diff. |
| FEATURE | (a) un véritable transcript I/O piloté qui exécute un chemin de code modifié au commit du changement ; (b) un cas inverse par comportement modifié, son entrée invalide sur la limite décidable (acceptée/différente avant le changement, rejetée/correcte après), soutenu par une base de référence pré-changement 00-pre-change.log et une sortie brute montrant le rejet correct — les cas qui échouaient aussi avant le changement ne comptent pas ; (c) commande/action exacte et ref de changement enregistrés ; (d) chaque assertion mappée à un fichier avec un chemin modifié rempli, et >=1 assertion exécute le chemin modifié et nomme le fichier/fonction/route modifié ; (e) aucun mock/stub se substituant à la chaîne ; (f) >=1 élément de preuve sur le diff. |
| DATAFLOW | (0) ligne de transformation attendue (forme d'entrée -> forme de sortie) écrite avant la collecte et référencée à chaque saut ; (a) un instantané par saut (entrée, intermédiaire, persistance, sortie) avec le même identifiant de corrélation ; (b) l'instantané de persistance colle la vraie requête de lecture + le retour brut du magasin, pas une réimpression de la valeur écrite ; (c) la base de référence pré-changement capture... (le texte est tronqué) |
7. Résultats finaux
| Résultat | Définition |
|---|---|
| PASS | Toutes les assertions sont vérifiées. Le changement est prouvé. |
| FAIL | Au moins une assertion est fausse ou un artefact manque. |
| FAIL-WAIVED | L'utilisateur a renoncé par écrit à cette preuve. |
| INDISPONIBLE | Preuve impossible car l'environnement, l'outil ou le droit d'accès manque. |
| BLOQUÉ | Preuve impossible car un prérequis non rempli bloque la collecte. |
| PENDING USER | L'utilisateur doit approuver une dimension non testable par machine. |
| PASS-BY-USER | L'utilisateur a approuvé après inspection manuelle. |
| NON EXÉCUTÉ | Dépendance non satisfaite, l'assertion n'a pas été évaluée. |
8. Règles strictes
attenduest une prédiction, pas une description. Ne mettez jamais à jourattenduavec la valeur observée ; corrigez le code ou marquez FAIL.- Un cycle dans
dépend deest toujours FAIL. - Pas de mock sur le vrai chemin. Si un mock est nécessaire, déclarez-le comme
BLOCKED. - Les artefacts doivent être dans
.proof/<task-name>/. Tout fichier ailleurs n'est pas une preuve valide. - La sortie brute doit être complète et non modifiée (sauf désensibilisation déclarée avec le sha256 du fichier original).
- Les captures d'écran sont pour la revue humaine, jamais comme source de mesure numérique.
9. Flux de travail recommandé
- L'utilisateur demande un changement (ex. « Ajoute la validation de l'email sur la page de login »).
- L'agent implémente le changement.
- L'agent crée
.proof/<task-name>/. - L'agent écrit les assertions dans
report.md(prédictions AVANT preuve). - L'agent exécute le cas inverse (pré-changement) et sauvegarde
00-pre-change.log. - L'agent pilote la vraie surface, capture les résultats.
- L'agent écrit le rapport complet à partir du template.
- L'agent rend le jugement final.
- Le rapport est commité avec le changement.
10. Références
- Template du rapport :
references/report-template.md - Profils de preuve :
references/proof-profiles.md - Exemples :
examples/