ai-forge (Forge d'IA)

AI Forge Eval

Validation comportementale pour compétences et agents. La notation par rubrique (ai-forge-judge) vous indique si un artefact est bien rédigé. L'évaluation (Eval) vous indique s'il fonctionne.

Fonctionne pour SKILL.md (compétences) et .agent.md (agents). Même flux en 5 phases ; la phase 2 diffère selon le type d'artefact.

---

Phase 0 — Charger ou écrire la suite

OBLIGATOIRE — LIRE references/eval-suite.md pour le format sur disque, le protocole de déclenchement et le tableau de discrimination des assertions.

Vérifiez la présence de evals/evals.json à côté de l'artefact.

• Présent — chargez-le et passez à la Phase 2. Ajoutez des cas si la couverture est insuffisante ; ne remplacez jamais silencieusement des cas existants, sinon la tendance est rompue.
• Absent — rédigez-le en Phase 1 et écrivez-le dans evals/evals.json avant de lancer quoi que ce soit.

Une suite qui ne vit que dans cette conversation ne peut pas détecter une régression le mois prochain. La persistance est ce qui fait la différence entre une opinion et un test.

---

Phase 1 — Rédiger les évaluations

Rédigez 2 à 3 cas d'évaluation. Chaque évaluation est une invite réaliste accompagnée de 3 à 5 assertions.

Préférez les invites tirées d'une sonde de base (ai-forge-create Phase 1b) plutôt que les déclencheurs déclarés par l'artefact lui-même — les assertions écrites à partir de l'artefact ne peuvent que confirmer qu'il fait ce qu'il prétend. Reportez chaque capture dans le champ baseline_failure du scénario.

Pour les compétences : des invites qui devraient activer naturellement la compétence. Les assertions vérifient des comportements spécifiques à la compétence (par exemple "la sortie inclut un récapitulatif de la Phase 1", "le format de la règle NE JAMAIS comporte POURQUOI et À LA PLACE").

Pour les agents : des invites couvrant le périmètre déclaré de l'agent. Les assertions vérifient des comportements observables — fichiers créés, outils appelés, contraintes de ton, limites de périmètre (par exemple "n'a pas modifié de fichiers en dehors de src/lib/", "a ouvert une PR", "le message de commit commence par 'refactor:'").

Règles d'assertion :

• Vérifiable : l'évaluateur peut vérifier à partir de la sortie seule
• Spécifique : "la sortie inclut l'en-tête 'Phase 1'" est préférable à "la sortie est bien structurée"
• Falsifiable : doit pouvoir échouer

Enregistrez les évaluations :

Évaluation 1 : <invite>
Attentes :
- <assertion 1>
- <assertion 2>
- <assertion 3>

---

Phase 2 — Lancement parallèle

Pour chaque évaluation, lancez les runs avec artefact et baseline dans le même message (jamais séquentiellement). En mode benchmark, cela devient N paires d'essais par évaluation — voir le mode Benchmark ci-dessous.

Run avec artefact : donnez-lui l'invite d'évaluation. Pour les compétences : ajoutez "Utilisez la compétence <nom-compétence> pour cette tâche." Pour les agents : collez les instructions complètes de l'agent comme contexte système.

Run baseline : dépend de ce qui est mesuré.

• Nouvel artefact — même invite d'évaluation, aucune instruction de compétence, aucun contexte d'agent. Réponse d'assistant simple.
• Amélioration d'un artefact existant — prenez un instantané de la version actuelle d'abord (cp -r <chemin> <scratch>/snapshot/), puis pointez la baseline sur l'instantané. "Pas d'artefact" est le mauvais contrôle quand la question est de savoir si le changement a aidé ; cela mesure l'existence de l'artefact, pas l'édition.

Capturez immédiatement à la fin : lorsque chaque notification de tâche arrive, enregistrez de quel run il s'agit (plus l'indice d'essai en mode benchmark) et lisez duration_ms et subagent_tokens depuis son bloc <usage> — exacts, pas estimés. Pas de bloc <usage> signifie enregistrez null ; ne substituez jamais une estimation par horloge murale. Ces données n'existent qu'au moment de la notification et ne peuvent pas être reconstruites ultérieurement.

Stockez par évaluation : le texte de sortie with_artifact et baseline, plus duration_ms et tokens pour chaque bras.

---

Phase 3 — Notation

LECTURE OBLIGATOIRE : agents/assayer.md

Pour chaque évaluation, invoquez l'assesseur sur les deux sorties. Passez :

Sortie : <texte de sortie>
Attentes :
- <assertion 1>
- <assertion 2>

L'assesseur retourne par attente :

{ "text": "...", "passed": true, "evidence": "..." }

Calculez taux_réussite = réussi / total par run. Calculez delta = taux_réussite_avec_artefact - taux_réussite_baseline.

Ensuite, classez chaque assertion selon son comportement dans les deux bras — réussit dans les deux (mesure le modèle, pas l'artefact), échoue dans les deux (cassée ou hors de portée), réussit avec et échoue sans (signal réel), échoue avec et réussit sans (l'artefact nuit), ou variance élevée (instable). Voir le tableau dans references/eval-suite.md. Une suite dont toutes les assertions réussissent dans les deux bras rapporte un taux de réussite sain et ne vous apprend rien.

Lisez également la transcription, pas seulement la sortie : le run a-t-il réellement suivi l'artefact, ou a-t-il atteint la bonne réponse malgré lui ? Un travail causé par l'artefact qui n'a rien produit est un candidat à la coupe.

---

Phase 3b — Révision humaine

Avant d'analyser quoi que ce soit par vous-même, présentez les sorties brutes à l'utilisateur.

Remplissez assets/eval-review.html — remplacez __ARTIFACT_NAME__ et __EVAL_DATA__ (un tableau JSON de {id, name, prompt, with_artifact, baseline, assertions}) et écrivez-le à côté de la suite d'évaluation. Présentez-le avec un outil de livraison de fichier si disponible ; sinon donnez le chemin à l'utilisateur. Lisez le feedback.json exporté une fois qu'il a terminé.

La notation par le modèle de sa propre sortie d'artefact est le signal le plus faible ici — un coup d'œil humain capture ce qu'aucune assertion n'a été écrite pour capturer. Sautez uniquement si l'utilisateur décline.

---

Phase 4 — Comparer (optionnel)

LECTURE OBLIGATOIRE : agents/arbiter.md — chargez uniquement lorsque la Phase 4 s'exécute.

Exécutez la Phase 4 quand : delta > 0,1 sur une évaluation, ou les taux de réussite sont en conflit entre évaluations.

Sautez quand : les taux de réussite sont identiques, ou l'utilisateur a demandé uniquement les notes.

Entrée de l'arbitre : Sortie A (non étiquetée), Sortie B (non étiquetée), liste d'attentes. Enregistrez laquelle était laquelle pour la Phase 5.

L'arbitre retourne : score de contenu (1–5), score de structure (1–5), gagnant (A/B/égalité), justification, forces/faiblesses par côté.

Porte de livraison lors de la comparaison de deux versions : livrez uniquement si la nouvelle version gagne ou est à égalité dans chaque scénario, et gagne au moins un. Une version qui gagne largement sur un cas et perd sur un autre a échangé un échec contre un différent — ce n'est pas une amélioration, et le delta agrégé le cachera.

---

Phase 5 — Analyser + Rapporter

LECTURE OBLIGATOIRE : agents/refiner.md — chargez uniquement si la Phase 4 a été exécutée.

Si la Phase 4 a été sautée : allez directement au tableau de benchmark.

Entrée du raffineur : sortie de l'arbitre + mappage d'étiquettes { "A": "with_artifact", "B": "baseline" } (ou inversé). Le raffineur explique pourquoi le gagnant a battu le perdant et présente 1 à 3 améliorations priorisées.

Rendu du tableau de benchmark — une ligne par évaluation plus une ligne Moy, colonnes Évaluation | avec_artefact | baseline | delta | durée_ms (avec / base), comptes et pourcentages de réussite par bras. Ajoutez toutes les assertions non discriminantes ou nuisibles signalées en Phase 3, puis les suggestions d'amélioration du raffineur si elles ont été exécutées.

Si le delta est négatif sur une évaluation, signalez : "L'artefact peut nuire aux performances — révisez le libellé du déclencheur ou les contraintes de périmètre."

---

Phase 6 — Vérification du déclenchement

Les évaluations comportementales répondent à "est-ce que ça fonctionne quand c'est invoqué". Celle-ci répond à "est-ce que ça est invoqué" — la panne la plus courante, et invisible pour toutes les phases ci-dessus.

Exécutez quand la suite a un bloc triggers, ou proposez-la après la Phase 5. OBLIGATOIRE — LIRE references/eval-suite.md pour le protocole, la répartition 60/40 d'échantillons retenus, et la barre de qualité des requêtes. Ne le chargez pas pour un run purement comportemental.

Rapportez le rappel et la précision par répartition (entraînement et échantillons retenus) ainsi que les oublis et faux positifs spécifiques. Un rappel faible avec une précision élevée signifie que la description est trop étroite — élargissez-la. L'inverse signifie qu'elle empiète sur des tâches adjacentes — ajoutez des déclencheurs négatifs.

---

Mode Benchmark

Déclenchez quand l'utilisateur demande de benchmarker, de suivre les régressions, ou de valider une tendance. Le mode benchmark étend les cinq phases avec des essais répétés et un stockage de tendances persisté.

LECTURE OBLIGATOIRE : references/benchmarking.md avant de lancer — le protocole d'essai, les formules d'agrégation, les seuils de validation, et les schémas de résultats d'essai + benchmark.json s'y trouvent. Ne le chargez pas pour une simple évaluation en un seul run.

• Essais — chaque évaluation s'exécute N fois (par défaut 3). Par évaluation, lancez toutes les N paires d'essais (2N sous-agents) dans UN SEUL message, drainez les notifications de cette évaluation en capturant <usage> comme en Phase 2, puis passez à l'évaluation suivante. Ne lancez jamais les essais de toutes les évaluations à la fois.
• Agrégation — node scripts/aggregate-benchmark.cjs --trials <scratch.json> --prior benchmarks/<nom-artefact>.json --artifact <chemin> retourne la moyenne/écart-type par évaluation, les indicateurs d'instabilité et de discrimination, les deltas par rapport au run précédent, et un verdict de validation. S'il ne peut pas s'exécuter (pas de node, script manquant, erreur d'utilisation), rapportez les résultats bruts par essai avec ⚠ pas d'agrégation — validateur indisponible : <raison> et ne calculez pas manuellement un verdict de validation ; un verdict de validation est une affirmation de signification statistique et ne doit pas être estimé. Un verdict d'ÉCHEC bloque toujours.
• Persistance — sauvegardez la charge utile retournée dans benchmarks/<nom-artefact>.json (commité) comme nouvelle baseline de tendance.
• Rapport — Tableau de la Phase 5 avec colonnes moyenne±écart-type plus le verdict de validation. En cas d'échec de validation, le verdict est "régression — pas prêt".

---

NE JAMAIS

• NE JAMAIS lancer les runs avec_artefact et baseline d'un essai séquentiellement À la place : Les deux bras de chaque essai dans le même message. En mode benchmark, toutes les N paires d'essais pour une évaluation vont dans un seul message ; différentes évaluations peuvent être regroupées séquentiellement. Pourquoi : Les bras séquentiels sérialisent le retour d'information ; mais lancer les essais de toutes les évaluations à la fois submerge les notifications et rend la capture <usage> par arrivée peu fiable.

• NE JAMAIS différer la capture d'utilisation jusqu'à la fin des autres runs À la place : Lisez le bloc <usage> (duration_ms, subagent_tokens) de chaque notification dès son arrivée. Pourquoi : Les données <usage> n'existent qu'au moment de la notification et ne peuvent pas être reconstruites ultérieurement.

• NE JAMAIS rapporter un seul essai comme un benchmark À la place : Exécutez au moins N=3 essais pour que la moyenne et l'écart-type soient significatifs. Pourquoi : Un taux de réussite unique semble précis mais cache l'instabilité — une compétence qui réussit vraiment un tiers du temps peut lire 100 % ou 0 % sur un seul essai.

• NE JAMAIS affaiblir un scénario qu'un run avec_artefact a échoué À la place : Renforcez le corps jusqu'à ce que le run réussisse le scénario tel qu'écrit. Pourquoi : Le scénario est l'enregistrement d'un échec réel. L'assouplir rend l'évaluation verte alors que l'échec qu'elle était censée capturer survit intact.

• NE JAMAIS ajuster une description par rapport aux requêtes de déclenchement retenues À la place : Itérez sur la répartition d'entraînement ; examinez les retenues uniquement pour sélectionner la version finale. Pourquoi : Une description ajustée sur son propre ensemble de test obtient de bons scores et généralise moins bien — vous perdez la seule estimation non biaisée que vous aviez.

• NE JAMAIS écrire d'assertions subjectives ("la sortie est claire", "bien formatée", "approfondie") À la place : Vérifiable à partir du texte : "la sortie inclut l'en-tête 'Phase 1'", "aucune règle NE JAMAIS ne manque de clause POURQUOI" Pourquoi : Les assertions subjectives ne donnent aucune vérité terrain à l'assesseur ; la réussite/échec devient arbitraire et non reproductible.

• NE JAMAIS utiliser des invites différentes pour les runs avec et baseline À la place : Invite identique — seule l'instruction d'artefact diffère. Pourquoi : La variation d'invité confond le delta ; elle mesure la qualité de l'invité, pas l'effet de l'artefact.

• NE JAMAIS accepter la sortie de l'assesseur avec des noms de champ non standards À la place : Exigez exactement text, passed, evidence — rejetez name, met, details ou autres. Pourquoi : L'agrégation de la Phase 5 dépend des noms de champ exacts ; des noms silencieusement incorrects produisent des taux de réussite incorrects.