daniloduuarte/verify-saas

Quand exécuter (la règle qui décide)

Exécuter avec discernement, pas par réflexe. Choisissez le niveau selon la situation:

Situation	Quoi exécuter
Uniquement documentation, notes, commentaires, plan ou spécification	Rien. Dites que ce n'était pas nécessaire.
En cours de travail: entre les éditions, cycle de correction, « est-ce que j'ai cassé les types ? »	Rapide: node .claude/skills/verify-saas/driver.mjs --quick (ou simplement la commande de types, si un seul type a changé)
Fin de chaque tâche ou lot logique, avant le commit	Complet, une fois
Avant tout git push, déploiement ou merge sur la branche principale	Complet, obligatoire. Si le dernier passage complet couvre exactement le commit à soumettre, ne répétez pas.
Nouvelle migration, changement dans package.json, config de build, règles d'accès/authentification	Complet à la fin de ce changement (risque de changement structurel)
Après un git pull ou un merge du travail d'une autre personne	Complet (réancre la référence)

Ne jamais:

• exécuter deux fois de suite sans changement intermédiaire ;
• commencer un second passage avant d'avoir lu le premier ;
• exécuter en parallèle avec un autre build ou test dans le même dossier ;
• exécuter le mode complet au milieu d'un cycle d'ajustements en direct (attendez la demande de commit).

Toujours:

• confirmer que les tests pointent vers une base de données/environnement de test, jamais la production (voir l'avertissement dans le README) ;
• relire son propre diff avant d'exécuter: les imports superflus et les noms de propriétés erronés se repèrent en lisant, pas en gaspillant un passage ;
• lire le rapport entier, pas seulement le code de sortie.

Comment exécuter

À la racine du projet:

node .claude/skills/verify-saas/driver.mjs            # complet
node .claude/skills/verify-saas/driver.mjs --quick    # rapide, ne touche pas à la référence
node .claude/skills/verify-saas/driver.mjs --baseline # recapture l'état actuel comme « bon »

Tout ce qui est spécifique au projet (commandes, dossiers, mots d'alerte, étapes activées ou désactivées) se trouve dans verify-saas.config.json, à la racine du projet. Sans ce fichier, les valeurs par défaut pour Next.js + TypeScript + npm s'appliquent.

Code de sortie: 0 = rien n'a empiré ; 1 = quelque chose a empiré ou était déjà cassé (types, build ou tests).

Première utilisation: adapter au projet (pour l'agent qui lit ceci)

Si l'utilisateur vient d'installer la skill et a demandé de l'adapter à son SaaS, faites dans cet ordre:

1. Lisez le projet (package.json ou équivalent, dossiers de migrations, comment les tests s'exécutent) et ajustez verify-saas.config.json: commandes de types, lint, build et tests, structure.migrationsDir et alertKeywords. Désactivez ("enabled": false) ce que le projet n'a pas.
2. Demandez ce que le métier ne peut pas laisser casser (agenda sans créneau horaire dupliqué, stock sans devenir négatif, solde qui tombe juste, entreprise A sans voir B, paiement reçu deux fois crédité une fois...). N'inventez pas de règles: confirmez avec l'utilisateur et écrivez des tests pour elles, en utilisant docs/exemples-por-nicho.md comme modèle.
3. Confirmez l'environnement de test. Ne lancez jamais de tests contre la production. S'il n'y a pas de base de données ou d'environnement de test, arrêtez et avertissez l'utilisateur.
4. Alors seulement exécutez node .claude/skills/verify-saas/driver.mjs --baseline et montrez le rapport, en indiquant ce qui était déjà cassé (dette) et ce qui a réussi.
5. Dites à l'utilisateur ce qui a été ajusté et qu'il doit réviser les tests écrits.

Comment lire le rapport

Dans l'ordre:

1. Types: réussi/échoué et nombre d'erreurs par rapport à la référence.
2. Lint: comparé par empreinte digitale (fichier:ligne:colonne:règle), pas seulement par comptage. « 5 erreurs avant, 5 après » peut cacher 5 erreurs différentes. La dette ancienne n'est jamais de votre faute ; seules les NOUVELLES comptent.
3. Build: réussi/échoué et liste des routes (si configuré).
4. Tests: réussi/échoué par rapport à la référence.
5. Structure: dépendances nouvelles, supprimées ou avec version changée ; migrations nouvelles, marquées d'un avertissement si elles contiennent des mots d'alerte (sécurité/permissions).

Symboles: ✗ régression (à corriger), ✓ amélioration, = sans changement, ℹ information, ⚠ vérifier si intentionnel.

Après l'impression, le mode complet écrase la référence avec l'état actuel. C'est pourquoi: corrigez les régressions avant de relancer, sinon le second passage traite l'erreur comme « dette ancienne ».

Bonnes pratiques

• La référence (verify-saas.baseline.json) doit être commitée dans le projet ; c'est elle qui permet à la comparaison « depuis la dernière fois » de fonctionner entre sessions et machines.
• Première fois dans le projet: exécutez avec --baseline dans un état dont vous savez qu'il est bon.
• Les migrations sont comparées uniquement par le nom du fichier. La skill n'applique ni ne valide le SQL ; elle signale qu'une nouvelle est apparue et si elle touche à la sécurité.
• La skill n'installe pas les dépendances (npm install est une action plus importante qu'une vérification ne devrait faire seule).
• Si le rapport montre un problème « nouveau » que vous n'avez pas causé, vérifiez si quelqu'un a modifié le dépôt entre les passages (git log -3 --oneline).
• La véritable protection vient des tests que vous écrivez (voir docs/exemples-por-nicho.md). La skill garantit seulement qu'ils s'exécutent et avertit quand quelque chose change.