fh-tools : quatorze outils déterministes pour les agents de code
fh-tools, c'est là où la doctrine déterministe devient concrète : quatorze petits outils que les agents de code appellent au lieu de deviner. Chacun répond à une question, chacun y répond pareil à chaque fois, et chacun dit clairement s'il a rendu un verdict ou buté sur un problème technique.
Ce que vous y gagnez. Des faits à la demande pour vos agents, dans le langage que vous aimez pour écrire des outils, sans serveur ni environnement partagé, et un vérificateur de conformité qui refuse tout outil dont la sortie varie.
1. Les quatorze outils
| Outil | Répond à |
|---|---|
| fh-toolgate | ce dépôt respecte-t-il le contrat des outils ? |
| fh-envlint | .env et .env.example sont-ils d'accord ? |
| fh-testgap | quelles lignes ajoutées aucun test n'exerce ? |
| fh-edit-apply | appliquer ce correctif à ce contenu |
| fh-edit-diagnose | pourquoi ce correctif ne s'est-il pas appliqué ? |
| fh-bench-score | ce changement est-il une amélioration ? |
| fh-repomap | à quoi ressemble ce dépôt ? |
| fh-secret-scan | ce texte contient-il un identifiant secret ? |
| fh-changelog | qu'est-ce qui a changé sur cette plage ? |
| fh-deps | cet ensemble de dépendances est-il reproductible ? |
| fh-trace-query | avons-nous déjà vu cette panne ? |
| fh-pr | que dit cette demande de fusion ? |
| fh-story-lint | ce découpage en stories est-il conforme ? |
| fh-spec-lint | cette spécification énonce-t-elle un contrat ? |
2. Le contrat
Un outil est un exécutable qui lit un objet JSON sur l'entrée standard et écrit un objet JSON sur la sortie standard. Pas une bibliothèque, pas un serveur, pas un greffon. N'importe quel langage convient ; il n'y a ni port ni démon ; et le déterminisme se teste de l'extérieur : rejouer l'entrée, comparer les octets.
Chaque outil porte un tool.json : nom, version, une description de 120 caractères au plus (elle se trouve dans le contexte du modèle à chaque tour où l'outil est chargé), point d'entrée, schémas d'entrée et de sortie, codes de sortie, programmes système requis, deterministic: true, et un coût de contexte estimé.
| Code de sortie | Sens |
|---|---|
| 0 | succès |
| 1 | une réponse valide avec un verdict négatif |
| 2 | refus : l'opération n'est pas permise |
| 3 et plus | erreur technique, jamais un verdict |
La différence entre 1 et 3 porte toute la charge. Un vérificateur absent du PATH a un jour produit un rouge qui ressemblait à un défaut du code, et coûté une journée de fausse piste.
3. La conformité : trois rejeux, des octets identiques
echo '{"repo": "fh-tools/fh-envlint"}' | python3 fh-tools/fh-toolgate/src/fh_tool_verify.pyLe vérificateur lit le manifeste, lance le point d'entrée, et rejoue chaque cas déclaré trois fois en exigeant une sortie identique à l'octet près. Un outil dont la sortie varie ne part pas. Un petit lanceur, fh-tool <nom>, exécute n'importe quel outil d'après son manifeste pour que les appelants n'aient jamais à gérer des chemins, et un serveur d'outils les expose à n'importe quel agent.
4. La paire d'édition, séparée exprès
fh-edit-apply applique un correctif ; fh-edit-diagnose explique pourquoi l'un ne s'est pas appliqué. C'est le second qui a de la valeur : ce qui revient après une modification ratée décide si le modèle répare son travail ou recommence de zéro.
Pièges
Un exécutant qui appelle un modèle n'est pas un outil, même s'il vit dans le même dépôt. Le nôtre le dit ; il produit des runs bruts, et un vrai outil les note, si bien que chacun peut renoter des runs publiés sans posséder le matériel.
Utile ? Dites-nous ce qu'il faut mesurer ensuite.