no xaur/verify-finite

Vérifier Finite

Finite a deux surfaces, et la plupart des fonctionnalités nécessitent les deux. Les agents éditent les designs via les outils MCP sur /mcp (les six outils doc6 ; call pilote les outils classiques sur /mcp/classic). Les personnes observent dans le navigateur : la liste des designs sur / et le canevas sur /design/?id=<designId>. Une preuve pilote le côté agent avec call et vérifie le côté personne dans la page, ou l'inverse pour les commentaires.

Le harnais est e2e/headless.mjs. .agents/skills/finite-headless/SKILL.md est sa référence de commandes (sélecteurs qui atteignent les racines shadow, les iframes sandboxées, --agent, Python). Lisez-le une fois avant votre première session. Cette compétence ajoute l'isolation, un diagnostic, un dossier de preuves, des exécutions avant/après et la carte des fonctionnalités.

Chaque commande ci-dessous s'exécute depuis la racine du dépôt :

V=.agents/skills/verify-finite/scripts/verify.sh

Les variables shell ne survivent pas entre les appels d'outils. Répétez V=... et RUN=... au début de chaque appel.

Étapes

1. Choisir les fonctionnalités. Trouvez les fonctionnalités que votre modification touche dans le tableau « Quelles fonctionnalités une modification touche » dans features/README.md.
2. Lancer une exécution de votre code. Pour une correction de bug, lancez également une exécution du code avant la correction (voir « Avant et après »).
3. Diagnostiquer chaque exécution jusqu'à ce qu'elle n'affiche que des lignes ok.
4. Piloter chaque point d'entrée dans chaque fichier de fonctionnalité sélectionné, en sauvegardant les preuves au fur et à mesure.
5. Nettoyer chaque exécution que vous avez lancée, y compris celles qui ont échoué.
6. Rapporter au format décrit dans « Rapport ».

Vous avez terminé lorsque chaque point d'entrée de chaque fonctionnalité sélectionnée est prouvé, ignoré avec une raison, ou a échoué avec ses preuves, et que $V list n'affiche rien en cours d'exécution.

Lancement

$V launch                          # construit le serveur, finite.wasm et l'application web, puis les démarre
$V launch --no-build               # réutilise les dernières constructions ; refusé si le code a changé depuis leur création
$V launch --width 390 --height 844 # une page de taille téléphone (la valeur par défaut est 1440 × 900)
$V launch --at main                # une exécution d'un autre commit, dans un dépôt temporaire (voir « Avant et après »)

Cela affiche RUN=<run>. Conservez cet identifiant : chaque autre commande le prend. Une construction à froid prend environ 2 minutes, et une construction sans rien à faire quelques secondes. Définissez le délai d'attente Bash à 600000. --no-build ne sauvegarde que les quelques secondes d'une construction sans rien à faire, donc en cas de doute, ne l'utilisez pas.

Le lancement est prêt lorsqu'il affiche Finite at http://127.0.0.1:<port>. Le harnais attend /api/health et charge la liste des designs avant d'afficher cette ligne. Le dossier de données démarre vide, et il n'y a pas de données d'initialisation, de migrations ni de connexion. Une personne publie des commentaires en tant qu'« Invité », et les agents publient en tant qu'« Agent » sauf si vous passez --agent <nom>.

Chaque exécution est une session séparée (verify-<run>) avec son propre port libre, dossier de données temporaire et profil Chrome, afin que les exécutions puissent se dérouler côte à côte. Ne pilotez jamais un Finite que vous n'avez pas lancé. vp run dev sert les designs réels de l'utilisateur depuis crates/server/data, et l'application de bureau sert également les propres données de l'utilisateur. Le diagnostic échoue sur une session qui s'est attachée au serveur de quelqu'un d'autre.

Une exécution s'arrête automatiquement après 30 minutes d'inactivité. Après cela, doctor échoue : nettoyez et relancez.

Diagnostic

$V doctor $RUN

Il ne fait que lire l'état, et chaque ligne indique ok ou FAIL. Il vérifie cinq choses :

• La session est active et possède un dossier privé finite-headless-data-*.
• /api/health répond ok avec la version dans package.json.
• La version en cours d'exécution correspond au code. Il compare un hachage des entrées de construction (crates/, apps/web/, le harnais, les fichiers de verrouillage, y compris les fichiers non suivis) avec le hachage du code à partir duquel l'exécution a été construite. Les modifications apportées à la documentation, aux compétences ou aux tests ne comptent pas.
• Un Chrome, Chromium ou Edge est présent pour get_screenshot.
• La page répond.

Ensuite, il affiche la console de la page depuis le dernier appel. Exécutez-le d'abord, après toute surprise, et avant de capturer la preuve finale. En cas de FAIL, nettoyez et relancez plutôt que de continuer. Après avoir modifié le code, la vérification de construction échoue intentionnellement : nettoyez et relancez.

Pilotage

$V h $RUN <commande> ... exécute n'importe quelle commande e2e/headless.mjs pour cette exécution. Les commandes que vous utiliserez le plus :

$V h $RUN call create_design '{"name":"Vérifier"}'      # côté agent : affiche designId "<id>"
$V h $RUN call create_artboard @input.json            # JSON en ligne, @fichier, ou - pour stdin
$V h $RUN design <designId>                           # côté personne : ouvrir le canevas, attendre les artboards
$V h $RUN snapshot --selector main                    # arbre d'accessibilité, ce qu'une personne voit
$V h $RUN click 'button[title="Commentaire (C)"]'
$V h $RUN click '[data-artboard] >>> h1' --shift      # Shift-clic
$V h $RUN upload 'input[type=file]' card.html         # sélectionner un fichier, comme le ferait le sélecteur OS
$V h $RUN api GET /api/designs/<designId>             # le design stocké, commentaires inclus

Utilisez ces poignées stables. Ce sont les noms et titres accessibles de l'application :

Où	Poignée
Liste de designs	en-tête Designs, bouton Nouveau design, zone de recherche Rechercher des designs par nom, un lien par carte de design
Barre supérieure du canevas	lien ← Designs, button[title="Variables CSS utilisées par chaque artboard, dans chaque mode"] (Tokens), button[title="Chaque commentaire, ouvert et résolu"] (Commentaires, avec le nombre d'ouverts dans son nom), Importer, Exporter, une puce par agent présent
Outils du canevas	barre d'outils Outils : button[title="Pointeur (V)"], button[title="Commentaire (C)"] ; touches v, c, Shift+1 (ajuster), =/- (zoom)
Boîte de commentaire	zone de texte Ajouter un commentaire, button[title="Changer votre nom"], [data-selection-count], bouton Envoyer, épingles nommées Commentaire : <premier message>
Fil de commentaire	[role=dialog] nommé Fil de commentaire : boutons Supprimer, Résoudre/Rouvrir, Fermer, Modifier sur votre message le plus récent, zone de texte Répondre
Panneaux	aside[aria-label=Commentaires] avec onglets Ouverts N / Résolus N ; section[aria-label=Tokens] avec form[aria-label="Ajouter un token"] ; nav[aria-label=Pages] ; [role=menu][aria-label=Exportation] ; aside[aria-label=Importation] avec un status
Contenu d'artboard	[data-artboard="<artboardId>"] >>> <css> ; les attributs data-name des agents survivent dans le DOM

Préférez ces poignées aux coordonnées. Les coordonnées sont uniquement pour les artboards sandboxés (script), que les sélecteurs ne peuvent pas atteindre. click prend du CSS, pas du texte, donc les boutons sans titre sont sélectionnés par position : [role=dialog] button --nth 1, avec query listant l'ordre.

La saisie de texte comporte deux pièges. type ajoute à ce qu'un champ contient, et key Meta+a ne sélectionne pas le texte via CDP. Pour remplacer le texte d'un champ, exécutez $V h $RUN eval "document.execCommand('selectAll')" avec le champ focalisé, puis type.

Appels en arrière-plan

wait_for_comments bloque jusqu'à ce qu'une personne commente, donc il doit s'exécuter pendant que vous pilotez la page :

$V bg $RUN 02-attente call wait_for_comments '{"designId":"<D>","timeoutSeconds":30}'
# ...piloter la page...
$V await $RUN 02-attente 30      # bloque jusqu'à ce que l'appel revienne, puis affiche .verify/<run>/02-attente.txt

Lisez le résultat avec await, jamais en lisant le fichier directement : le fichier n'apparaît qu'une fois que l'appel est revenu. L'appel en arrière-plan survit entre les appels d'outils.

Preuves

Tout va dans .verify/<run>/ dans le dépôt. .gitignore le couvre, et le nettoyage le conserve.

$V save $RUN 01-commentaire-poste snapshot --selector main     # la commande, sa sortie et son code de sortie
$V shot $RUN 02-canevas                                      # .verify/<run>/02-canevas.png
$V shot $RUN 03-panneau --selector 'aside[aria-label=Commentaires]'

save prend n'importe quelle commande headless, call inclus, et écrit <nom>.txt contenant la commande, sa sortie et [exit N]. Numérotez les noms pour que l'exécution se lise dans l'ordre. Lisez chaque PNG avec l'outil de lecture avant de vous y fier. Les images get_screenshot et toute capture d'écran de page prise sans chemin se retrouvent dans le dossier temporaire de la session. Le nettoyage les copie dans .verify/<run>/tool-images/, et le journal du serveur dans .verify/<run>/server.log. Les fichiers que vous créez comme entrée de test, comme un fichier à importer, vont également dans .verify/<run>/.

Une preuve répond à ces normes :

• Le chemin réel. L'action d'une personne passe par la page (clic, touche, saisie, téléversement), et l'action d'un agent passe par un call MCP. Utilisez l'API REST uniquement pour lire l'état stocké. Écrire via celle-ci ignore l'interface utilisateur que vous prouvez.
• Action et résultat. Sauvegardez l'étape qui fait la chose et l'état après celle-ci, pas seulement une capture d'écran finale.
• Effets secondaires. Montrez le changement stocké ainsi qu'affiché. api GET /api/designs/<id> renvoie meta, nodes et comments tels que le serveur les a sauvegardés, et un outil de lecture d'agent (get_comments, get_tokens, get_tree_summary) montre ce que le prochain agent verra.
• Les deux directions pour les fonctionnalités en direct. L'édition d'un agent doit apparaître dans la page sans rechargement. Le commentaire d'une personne doit atteindre un agent en attente.
• Pas de simulations. L'exécution utilise le vrai serveur, le vrai navigateur et de vraies sessions MCP.
• Une console propre. Terminez avec $V save $RUN <n>-console console. Une exception ou une requête échouée là-bas gâche la preuve.

Avant et après

Une correction de bug est prouvée lorsque le même parcours échoue sur l'ancien code et réussit sur le nouveau. Exécutez les deux côte à côte :

$V launch --at main     # RUN=<avant> : un dépôt temporaire de main, installé et construit (environ une minute)
$V launch               # RUN=<après> : ce dépôt

Pilotez les mêmes étapes dans les deux, avec les mêmes noms de preuves. L'exécution avant doit montrer le bug. Si ce n'est pas le cas, votre parcours n'atteint pas le bug, et l'exécution après ne prouve rien concernant la correction. --at prend n'importe quelle référence git : une branche, un tag, un commit, ou HEAD lorsque votre correction n'est pas encore commitée. Le diagnostic nomme la réf et le commit à partir desquels une exécution a été construite. Le nettoyage supprime le dépôt temporaire et conserve ses preuves.

Nettoyage

$V cleanup $RUN

Cela arrête le démon de cette exécution. Le démon arrête le serveur qu'il a engendré (SIGTERM, donc les designs sont sauvegardés en premier) et le Chrome qu'il a lancé, puis supprime leurs données temporaires et leur profil. Ensuite, le nettoyage copie le journal du serveur et les images des outils dans le dossier de preuves, supprime le dépôt temporaire d'une exécution --at, et liste ce qu'il a conservé. Il ne touche à rien d'autre, donc les autres sessions, vp run dev et l'application de bureau continuent de fonctionner.

$V list affiche les exécutions de ce dépôt qui sont toujours en cours ou qui ont laissé un dépôt derrière elles. Nettoyez chacune avec $V cleanup <run>, jamais pkill. $V prune [jours] supprime les preuves des exécutions nettoyées plus anciennes que ce nombre de jours (7 par défaut). Ne supprimez jamais une exécution dont vous êtes sur le point de rapporter les preuves.

Rapport

Terminez avec un bloc par fonctionnalité que vous avez pilotée :

<ID fonctionnalité> via <point d'entrée> : prouvé | ignoré | échoué
  preuves : .verify/<run>/<fichiers>
  raison (ignoré ou échoué) : <la commande que vous avez exécutée et ce qui manquait ou était incorrect>

Donnez ensuite les identifiants d'exécution, le résultat du diagnostic pour chacun, et, pour une correction, les preuves de l'exécution avant qui montrent le bug. Signalez un point d'entrée ignoré comme ignoré, même si un autre point d'entrée a prouvé le même comportement.

Aide

scripts/verify.sh prend ces commandes : launch, doctor, h, save, shot, bg, await, cleanup, list et prune. Exécutez-le sans arguments pour leurs arguments. C'est une fine couche au-dessus de e2e/headless.mjs : la session est verify-<run>, et les preuves vont dans .verify/<run>/.