km loureiro/agent-verify

Que fait agent-verify ?

Rendez la chose que vous construisez vérifiable par le mécanisme le moins coûteux capable de la falsifier. Vérifiez via CLI par défaut. Le modèle doit lire ~20 tokens (PASS / FAIL : ligne), jamais un dump DOM ou une capture d'écran.

L'unique règle

Utilisez le mécanisme le plus léger qui peut prouver qu'une fonctionnalité est erronée. Montez en puissance uniquement quand cela ne suffit pas.

assertion interne  →  CLI / curl + code de sortie  →  test DB (TAP)  →  navigateur headless (visuel uniquement, en dernier recours)
   moins cher                                                           plus cher

90% de ce que les agents construisent (logique, données, contrats API, flux) est vérifiable sans navigateur. Réservez le navigateur pour les pixels.

Boucle (par fonctionnalité)

1. Détecter une fois. Exécutez scripts/detect-stack.sh. Il affiche le framework de test et la stack en quelques lignes. N'imposez pas un nouveau framework — utilisez ce qui existe.
2. Construire la fonctionnalité.
3. Écrire UNE vérification minimale en tokens en utilisant la primitive interne / CLI de la stack (voir reference/stacks/). La vérification doit afficher PASS ou une seule ligne FAIL : — jamais de dumps.
4. Ajouter une ligne à VERIFICATION_MAP.md : fonctionnalité | commande | signal de succès. C'est le contrat que l'agent lira la prochaine fois.
5. Exécuter scripts/verify.sh [fonctionnalité] et ne lire que le résultat. Éditer → vérifier → répéter sur le résultat, pas sur les logs.

Ce qu'il NE faut PAS faire

• N'utilisez pas Playwright/le navigateur pour vérifier la logique, les données ou les réponses API. C'est la fuite de tokens que cette compétence vise à arrêter.
• N'imposez pas un rituel TDD. Révélez quelle vérification prouve cette fonctionnalité, pas une procédure. (Une procédure sans contexte ciblé se retourne mesurablement contre elle — voir reference/patterns.md.)
• Ne renvoyez pas la sortie brute dans le contexte. Filtrez dans le sandbox, affichez le résultat. (console.log(result), pas les 10 000 lignes.)
• Ne laissez pas les vérifications grossir. Une fonctionnalité, une vérification rapide et déterministe. Gardez VERIFICATION_MAP.md court — les maps courtes surpassent les longues.

Contrat de sortie (toujours)

PASS auth-login
FAIL create-invoice : attendu 201, reçu 500

Sortie 0 = tout passe. Non nul = quelque chose a échoué. C'est tout ce dont le modèle a besoin.

Quand le navigateur est vraiment inévitable

Uniquement pour l'UI véritablement visuelle (mise en page, style, régression visuelle) et uniquement à la toute fin. Même dans ce cas : une exécution headless, retournez un verdict PASS/FAIL ou un diff — jamais une capture d'écran complète ou le DOM dans le contexte. Voir reference/stacks/nextjs.md.

Fichiers

• scripts/detect-stack.sh — affiche la stack + le runner, minimal en tokens.
• scripts/verify.sh — exécute les vérifications enregistrées, émet uniquement PASS/FAIL + la ligne en échec.
• VERIFICATION_MAP.md — la map courte fonctionnalité→commande (l'agent la maintient).
• reference/stacks/ — recettes prêtes à l'emploi : FastAPI (TestClient interne), Supabase (seed + reset + pgTAP), Next.js (route handlers + recours visuel en dernier).
• reference/patterns.md — motifs de vérification minimaux en tokens + les preuves derrière eux.
• reference/anti-patterns.md — tests instables, faux PASS, garde-fous contre la sur-ingénierie.
• templates/ — points de départ pour la map, un test FastAPI, une seed Supabase.