🇬🇧 English version 💻 Code source (AGPL) : github.com/patlegu/cyber-agent-engine

La rigueur comme livrable

Les cinq articles précédents de cette série ont décrit des frontières techniques : jetons plutôt que valeurs réelles, politique fail-closed, topologie hors-boîte, audit borné et packaging reproductible. Ce dernier article change d’angle. Il ne parle pas de ce que cyber-agent-engine fait, mais de comment il a été construit — et pourquoi ce comment fait partie du livrable au même titre que le code.

La thèse est simple à énoncer et plus difficile à tenir : sur un projet où un LLM finit par obtenir des droits d’exécution sur un pare-feu de production, la qualité ne peut pas être un rattrapage. Elle se prouve à chaque étape, ou elle ne se prouve pas du tout. Ça s’est traduit par un choix structurant fait avant d’écrire la première ligne de core/ : découper le produit en sous-projets indépendants, chacun porté par sa propre chaîne spec → plan → exécution, plutôt que d’avancer par gros commits opportunistes sur un unique fil de développement.

Concrètement, le dépôt contient un dossier docs/superpowers/specs/ et son pendant docs/superpowers/plans/, où chaque sous-projet laisse une trace écrite avant d’être codé. On y trouve, par exemple, 2026-07-22-coeur-confiance-surete-design.md (le socle décrit dans l’article 1 et 2 de cette série — politique, tokenisation, audit), 2026-07-22-portabilite-modeles-runtime-design.md et 2026-07-22-assemblage-runtime-design.md (articles 4 et 5 — sortir le LLM de la boîte, assembler le runtime multi-serveur), ou encore 2026-07-23-durcissement-exploitation-design.md et 2026-07-23-ci-release-design.md, qui couvrent le durcissement opérationnel et la chaîne de release. Chaque design a son plan d’exécution correspondant dans plans/ — un document découpé en tâches numérotées, avec pour chacune la liste des fichiers touchés, les interfaces attendues et les commandes de vérification à faire tourner avant de committer. Cette série d’articles elle-même a suivi le même circuit : 2026-07-23-vitrine-blog-series-design.md puis 2026-07-23-vitrine-blog-series-fr.md dans plans/. La méthode ne s’applique pas qu’au runtime ; elle s’applique aussi à sa propre vitrine.

Ce découpage en sous-projets n’est pas cosmétique. Il fixe une frontière de contexte : un sous-agent qui implémente la tâche 3 du plan « cœur de confiance » n’a pas besoin de connaître le détail de la chaîne CI ou du packaging Docker pour bien faire son travail — il a le plan de son sous-projet, la tâche courante, et le code déjà en place. Ça réduit la dérive : moins de contexte à porter, moins de raccourcis pris par fatigue de fenêtre de contexte.

La boucle : implémenter, relire, corriger, relire encore

Le cœur de la méthode est une boucle répétée à chaque tâche d’un plan. Elle se lit ainsi :

Chaque tâche du plan est confiée à un sous-agent implémenteur qui démarre sur un contexte frais — le plan, la tâche, le code existant, rien de plus. C’est délibéré : un contexte qui s’accumule au fil de dizaines de tâches finit par contenir plus de bruit que de signal, et un agent fatigué de contexte a tendance à couper des coins qu’un agent frais ne coupe pas.

Une fois la tâche implémentée, elle passe en revue — pas la revue finale, une revue par tâche, qui vérifie deux choses distinctes : la conformité au spec (est-ce que ce qui a été codé correspond à ce que le plan demandait, ni plus ni moins) et la qualité intrinsèque (nommage, complexité, gestion d’erreurs, tests). Quand cette revue remonte des findings, ils ne sont pas corrigés par l’agent qui vient d’écrire le code — un sous-agent de correction dédié reprend les findings un par un, applique les fixes, et le tout repasse en revue. La boucle se referme quand la revue ne trouve plus rien à redire, et on passe à la tâche suivante.

Cette séparation implémenteur / relecteur / correcteur reprend un principe de revue de code classique — celui qui écrit le code n’est pas le mieux placé pour juger s’il est bon, parce qu’il a déjà rationalisé ses propres choix pendant qu’il écrivait. Appliqué à des sous-agents, ce principe devient mécanique plutôt que discipliné : la revue est un rôle distinct, convoqué systématiquement, pas une étape qu’on peut sauter un jour de retard.

Une fois toutes les tâches d’un sous-projet closes, il reste une dernière étape avant merge : une revue finale de branche, volontairement adversariale. Elle ne relit pas tâche par tâche — elle prend la branche entière comme un tout et cherche activement ce qui a pu passer entre les mailles des revues locales : une régression introduite par la tâche 7 sur un invariant posé à la tâche 2, une incohérence entre deux modules qui, pris isolément, avaient l’air corrects. C’est la différence entre relire une lettre phrase par phrase et la relire en entier une fois terminée : les deux passes trouvent des choses différentes.

Test-first et garde-fous à l’exécution

La boucle de revue attrape ce qu’un humain (ou un agent) sait chercher. Elle n’attrape pas structurellement les dérives qu’on ne pense pas à vérifier à chaque passage. C’est pour ça que le projet s’appuie aussi sur des tests d’enforcement — des tests qui ne valident pas un comportement métier, mais une propriété structurelle du code, en la scannant directement via son arbre syntaxique (AST) plutôt qu’en la devinant à l’œil.

Trois exemples concrets, tous dans tests/ :

tests/test_spdx_headers.py vérifie que chaque fichier source first-party (core/, coordinator/, agents/, clients/, server.py) porte bien l’en-tête SPDX-License-Identifier: AGPL-3.0-or-later dans ses trois premières lignes. Le test parcourt l’arborescence, collecte les fichiers manquants, et échoue avec la liste précise si un seul en manque — pas de vérification manuelle à refaire à chaque nouveau fichier créé par un sous-agent.

tests/test_runtime_messages_english.py est plus intéressant parce qu’il ne cherche pas une chaîne fixe mais un motif structurel. Le projet impose que les messages opérateur runtime (ce qui part dans un raise, dans un appel de logging, dans un print, ou dans les champs reason=/error= d’une réponse) soient en anglais. Plutôt que de grepper des mots français, le test parse chaque fichier en AST, parcourt les nœuds Raise et les appels aux méthodes de logging (debug, info, warning, error, exception, etc.), et signale toute constante chaîne littérale contenant un caractère accentué français dans ces positions précises. Le fichier documente lui-même sa limite : le français sans accent (« timeout serveur ») n’est pas détecté — le test garde la régression du cas courant, il ne remplace pas le sweep initial qui a assuré la complétude. C’est un garde-fou assumé comme partiel, pas comme une preuve totale.

tests/test_lint_surface_consistency.py protège contre un type de régression plus insidieux : le drift silencieux de configuration. La liste des chemins couverts par ruff check apparaît à trois endroits différents — ci.yml, release.yml, et [tool.mypy].files dans pyproject.toml. Rien n’empêche mécaniquement quelqu’un (humain ou agent) d’ajouter un module à core/ sans l’ajouter aux trois. Le test lit pyproject.toml en TOML et chaque workflow en YAML, extrait la commande ruff check de chacun, et compare l’ensemble de chemins aux fichiers mypy.files. Si un des trois dérive, le test échoue — un drop silencieux de chemin devient un test rouge, pas un trou de couverture qu’on découvre six mois plus tard.

Le point commun de ces trois garde-fous : aucun n’attend qu’un humain (ou un agent) se souvienne de vérifier une propriété transversale. Ils la transforment en assertion exécutable, jouée à chaque pytest -q, y compris en CI. C’est le complément mécanique de la revue par tâche : la revue attrape ce que quelqu’un a pensé à chercher sur cette tâche ; le test d’enforcement attrape ce que personne n’a besoin de repenser à chaque tâche, parce que la propriété est vérifiée structurellement sur tout le dépôt.

Ce que ça apporte

Mis bout à bout, ces trois mécanismes — sous-projets spec → plan → exécution, boucle implémenteur/relecteur/correcteur par tâche suivie d’une revue adversariale de branche, garde-fous AST — visent le même objectif : une qualité élevée dès le départ, plutôt qu’un audit de rattrapage une fois le produit « fini ». Trois effets concrets s’en dégagent.

D’abord, un contexte frais par tâche limite la dérive qu’un contexte surchargé finit toujours par produire — moins de choses à tenir en tête, moins de compromis pris pour aller vite. Ensuite, la revue systématique (par tâche et finale) sépare structurellement l’écriture du jugement, plutôt que de compter sur l’autodiscipline de celui qui vient d’écrire le code. Enfin, les garde-fous AST rendent la non-régression prouvée plutôt qu’espérée sur les quelques propriétés qui comptent le plus pour ce projet précis : licence AGPL respectée fichier par fichier, surface anglaise du runtime, cohérence des configurations de lint.

Les limites, honnêtement

Cette méthode n’est pas une preuve de correction. C’est une discipline qui augmente la probabilité de détecter un problème avant qu’il n’atteigne main, pas une garantie qu’aucun problème n’existe. Trois limites méritent d’être dites clairement plutôt que glissées sous le tapis.

D’abord, elle coûte en itérations. Une tâche qui revient deux ou trois fois dans la boucle implémenteur → revue → correction avant d’être « clean » prend plus de temps qu’une tâche codée une fois et jugée bonne sans vérification. Ce coût est assumé — c’est le prix payé pour ne pas le payer plus tard, en incident — mais il est réel, et il n’a pas de raison de disparaître avec l’expérience du projet.

Ensuite, la qualité du résultat dépend directement de la qualité du plan et du spec de départ. Une revue par tâche vérifie la conformité au plan ; si le plan lui-même a un trou, un angle mort de conception, une hypothèse implicite fausse, la boucle peut produire du code parfaitement conforme à un plan imparfait. La revue finale adversariale de branche existe en partie pour rattraper ce cas — regarder l’ensemble plutôt que chaque brique — mais elle ne remplace pas un travail de spec sérieux en amont.

Enfin, les garde-fous AST ne couvrent que ce qu’on a pensé à encoder. Le test sur les messages runtime le dit lui-même dans son docstring : il détecte l’accentuation française, pas l’absence totale de tournures françaises. Un garde-fou protège une propriété précise contre la régression ; il ne protège rien contre ce qu’on n’a pas anticipé qu’il fallait protéger. C’est une méthode, pas une garantie — et le dire explicitement fait partie de la rigueur qu’elle prétend apporter.

Ceci clôt la série sur cyber-agent-engine. Le premier article posait les cinq principes de la frontière de confiance ; les articles suivants ont détaillé la tokenisation (article 2), la politique fail-closed (article 3), la topologie hors-boîte (article 4) et l’assemblage exploitable en confiance (article 5). Celui-ci referme la boucle en montrant comment ces cinq briques ont elles-mêmes été construites.

Pour aller plus loin :

• Article 1 — un LLM avec les droits d’admin sur ton firewall — la thèse générale que cette méthode de construction avait pour mandat de tenir de bout en bout.
• Agents en Production — migration Qwen2.5 — la lignée d’expériences LoRA/agents qui a précédé cyber-agent-engine, et où une bonne partie des leçons de rigueur en amont ont été apprises à la dure.