ultraeval : évaluer une compétence ou une base de code → des documents de correctifs ancrés et exploitables par IA
Le markdown est le programme. Un petit moteur déterministe crée l'environnement d'exécution, génère le workflow multi-agent et impose une porte d'ancrage ; vous (avec des sous-agents déployés) effectuez les recherches, les jugements et la rédaction. Chaque constatation doit aboutir à un véritable fichier:ligne dans la cible — la porte rejette celles qui sont hallucinées — et la sortie est un backlog priorisé ainsi que des cartes TDD par correctif qu'un modèle peut implémenter suivant le cycle rouge→vert→refactor.
Quand l'utiliser
- « Évaluer / auditer / noter / classer cette compétence (ou ce dépôt) » ; « est-elle prête pour la production / répond-elle aux attentes ? »
- « Examiner cette base de code et me donner un plan de correctifs / un backlog TDD. »
- Vérifier l'absence de régressions dans vos propres compétences après des modifications, ou évaluer une compétence tierce avant de lui faire confiance.
Pas pour : une revue de code rapide d'un seul fichier (il suffit de le lire) ; exécuter la suite de tests de la cible elle-même (faites-le directement).
La boucle
init → plan → run(recherche → plan-de-test → exécution+portes → jugement → résultats) → verify → backlog(TDD) → score → render
Tout est un simple appel node <skill-dir>/scripts/ultraeval.mjs <cmd>. Le déploiement de sous-agents est une optimisation encodée par le workflow généré — jamais une exigence.
Entrées à confirmer
- Cible — un chemin vers la compétence/le dépôt à évaluer (ou une URL git que l'utilisateur a déjà clonée localement).
- Type (Kind) —
skilloucodebase(détection automatique : un SKILL.md ⇒ skill). Surchargez avec--kind. - Catégorie — par ex. « agent skill », « CLI », « bibliothèque », « application web », « outil de sécurité ». Oriente la grille d'évaluation de départ.
- Mode —
audit(défauts, par défaut) ·improve(opportunités d'amélioration ancrées) ·deep(les deux). Définissez avec--mode.
Modes et découverte d'améliorations
ultraeval trouve deux types d'éléments, tous deux ancrés et vérifiés :
- Défauts (
audit,deep) — quelque chose ne va pas ; chacun cite un véritablefichier:ligne. - Opportunités (
improve,deep) — une piste d'amélioration ancrée (santé interne et produit/capacité), notée selon impact × effort. Découverte paranalyze(points chauds déterminés/dépendances/churn/lacunes de test) →brainstorm(perspectives divergentes) →brainstorm --rank(intègre les opportunités classées dansfindings.jsonen tant quekind:"opportunity"). La même porte s'applique — une opportunité doit s'ancrer dans du code/des métriques réels, pour ne jamais devenir un vague « tout réécrire ». Voirreferences/analysis-playbook.md.
Pour les modes improve/deep, l'étape plan ajoute les phases Analyze et Brainstorm au workflow généré.
Procédure
1. Créer l'environnement d'exécution.
node <skill-dir>/scripts/ultraeval.mjs init --target <CHEMIN> --out <RUN> [--kind skill|codebase] [--category "<c>"]
Écrit eval.config.json avec les dimensions de départ (voir references/rubric-library.md).
2. Générer le workflow + les contrats des sous-agents.
node <skill-dir>/scripts/ultraeval.mjs plan --run <RUN>
Produit <RUN>/eval.workflow.mjs (un Workflow multi-agent prêt à être lancé, avec les chemins absolus du moteur et de la cible intégrés), <RUN>/agents/*.md (les contrats de répartition), TEST-PLAN.template.md, dimensions.json, findings.schema.json.
3. Exécuter l'évaluation. Lancez le workflow généré avec l'outil Workflow de votre infrastructure :
Workflow({ scriptPath: "<RUN>/eval.workflow.mjs" }). Il enchaîne Research → TestPlan → Execute → Findings → Gate → Judge → Results et s'invoque lui-même les portes du moteur. Si vous n'avez pas d'infrastructure Workflow, exécutez les étapes manuellement : lisez chaque agents/<stage>.md et répartissez un sous-agent selon le contrat. Voir references/orchestration.md. Chaque sous-agent reçoit le chemin ABSOLU <skill-dir>/scripts/ultraeval.mjs — il a son propre répertoire de travail et ne peut pas résoudre un chemin relatif (plan intègre déjà le chemin absolu dans le workflow).
4. Ancrer chaque constatation. Consolidez les résultats dans <RUN>/findings.json (schéma : references/gate-contract.md). Chaque constatation cite evidence[].ref comme chemin:ligne dans la cible ou run:relpath#Lnn dans un journal produit. Ensuite :
node <skill-dir>/scripts/ultraeval.mjs check --run <RUN>
Corrigez findings.json jusqu'à ce qu'il se termine avec le code 0 — réparez ou supprimez les constatations non ancrées ; n'affaiblissez jamais la porte.
5. Vérifier (porte de sortie au vérificateur).
node <skill-dir>/scripts/ultraeval.mjs verify --run <RUN> # écrit VERIFY.todo.json
# remplissez chaque verdict : supported | partial | refuted | unsupported (utilisez des sous-agents sceptiques ; --shards N --shard i pour paralléliser)
node <skill-dir>/scripts/ultraeval.mjs verify --run <RUN> --apply <verdicts.json>
node <skill-dir>/scripts/ultraeval.mjs check --run <RUN> --semantic --require-verify # porte de sortie — ne présentez jamais avant que cela ne réussisse
Une constatation refuted doit être marquée dismissed. Une constatation supported/partial survit.
6. Corriger — le livrable.
node <skill-dir>/scripts/ultraeval.mjs backlog --run <RUN> --tdd
Produit BACKLOG.json (une liste de tâches prioritaire et exploitable par une machine qu'un agent en aval peut exécuter), REMEDIATION.md, et une carte TDD fixes/FIX-*.md par constatation confirmée — chacune avec une spécification ROUGE de test qui échoue d'abord, le changement VERT et une commande VERIFY. Voir references/tdd-remediation.md.
7. Noter + générer le rendu + présenter.
node <skill-dir>/scripts/ultraeval.mjs score --run <RUN> # judges.jsonl + dimensions -> scorecard.json (0-100 + meets-expectations)
node <skill-dir>/scripts/ultraeval.mjs render --run <RUN> # index.html + index.md tableau de bord (affiche le verdict)
score réduit le judges.jsonl du panel de juges et les dimensions de configuration à un verdict pondéré ; une constatation P0 active (ou tout juge votant non, ou un score en dessous du seuil) fixe meets-expectations à faux. Présentez le verdict, le titre du backlog P0/P1 et les chemins (RESULTS.md, BACKLOG.json, fixes/) qu'un agent de correction doit consommer.
Codes de sortie de la CLI : 0 ok / porte passée · 1 porte échouée (check/verify) · 2 erreur d'utilisation ou d'exécution.
8. (optionnel) Exécuter les correctifs. Remettez chaque fixes/FIX-*.md à un agent de construction pour implémenter le TDD — la carte est écrite de manière à pouvoir passer par rouge→vert→refactor sans avoir à redériver le problème.
Le contrat d'ancrage
Une constatation n'est digne de confiance que si ses preuves sont résolues. check ouvre chaque chemin:ligne dans la cible et confirme que la ligne existe et est dans les limites ; une ligne obsolète ou inventée est un échec dur. verify demande ensuite à un sceptique si le contenu cité soutient réellement l'affirmation. Cette double porte (structurelle + sémantique) est l'essence même de l'outil — grammaire complète et règles de réussite/échec dans references/gate-contract.md.
Méthode et grilles d'évaluation
references/eval-playbook.md— la méthode recherche→plan-de-test→exécution→jugement→résultats, et comment construire une grille notée par dimension.references/orchestration.md— le workflow généré, les contrats de répartition des sous-agents et l'invariant du<skill-dir>absolu pour le déploiement.references/gate-contract.md— schéma defindings.json, grammaire des références de preuves et ce qui fait exactement réussir ou échouercheck/verify.references/tdd-remediation.md— la forme deBACKLOG.jsonet le format des cartes TDDfixes/FIX-*.md.references/rubric-library.md— dimensions de départ par catégorie de cible.references/analysis-playbook.md— les signauxanalyze, les perspectives de brainstorming et comment les opportunités restent ancrées.
Sécurité
- ultraeval lit seulement la cible et écrit dans
<RUN>. Il n'exécute jamais le code de la cible ; le sous-agent exécuteur peut exécuter les propres commandes de la cible (tests, portes) — isolez les dépôts non fiables. clean --run <RUN>supprime uniquement les artefacts dérivés de la porte et du rendu et conserve les livrables ;--allsupprime toute l'exécution.