m1nga/loop-system-architect

Architecte de Systèmes en Boucle

Transformez une tâche répétée en un système de contrôle observable capable d'exécuter, de prouver son résultat, de récupérer après une interruption et de s'améliorer sans réécrire son propre objectif.

Choisissez le mode

• Audit : inspectez un workflow existant et signalez les parties manquantes ou en boucle ouverte. Ne modifiez pas sauf demande explicite.
• Conception : produisez le contrat, le schéma d'état, le graphe des rôles, les évaluations et la conception d'exécution.
• Opérationnalisation : implémentez le contrôleur, les adaptateurs, la persistance, les preuves et un chemin d'exécution en une commande.
• Évolution : analysez les exécutions terminées, validez une amélioration proposée de boucle/connaissance/compétence et promouvez-la ou rejetez-la.

Quand l'utilisateur demande de "construire" ou "faire fonctionner", incluez l'Opérationnalisation. Un plan Markdown seul n'est pas une boucle opérationnelle.

Partez de la réalité existante

1. Lisez les instructions du dépôt et les artefacts que l'utilisateur a placés dans le périmètre.
2. Inspectez les outils réels, les points d'entrée, les fichiers d'état, les tests, les planificateurs, les CLI d'agents et l'arbre de travail modifié.
3. Séparez les entrées autoritaires actuelles du matériel de référence. N'utilisez pas la mémoire du modèle pour combler les lacunes.
4. Classez la boucle :
   • Terminale : un objectif avec une ligne d'arrivée démontrable.
   • Récurrente : chaque exécution se termine, tandis que le moniteur/service continue jusqu'à retrait.
5. Indiquez ce qui existe, ce qui manque et ce qui est seulement affirmé avant de modifier quoi que ce soit.

Pour un audit complet, lisez audit-rubric.md.

Exigez une boucle de contrôle fermée

Identifiez et connectez tous ces éléments :

1. objectif et propriétaire ;
2. condition d'achèvement ou condition de succès par exécution ;
3. frontière de la source autoritaire et provenance ;
4. déclencheur et prévol peu coûteux ;
5. capteur et signal collecté ;
6. comparateur, fenêtre et seuil/règle ;
7. contrôleur et espace de décision fini ;
8. actionneur et chemin qui retourne le nouveau résultat au capteur ;
9. état persistant, curseur, journal d'événements et stockage de preuves ;
10. responsabilités de l'orchestrateur, de l'exécuteur et du vérificateur indépendant ;
11. découverte ouverte de capacités/compétences et création de compétences candidates ;
12. limites d'autorité et champs protégés ;
13. évaluations d'acceptation et preuves requises ;
14. tentatives, délais d'attente, backoff, classification des échecs et rollback ;
15. idempotence, déduplication, verrou de concurrence et point d'étranglement des effets de bord ;
16. budgets de tokens, coûts, tours et temps réel ;
17. observabilité, alertes et un état de succès sans opération ;
18. remplacement direct de la vérité active remplacée ;
19. distillation d'expérience et promotion contrôlée ;
20. conditions d'arrêt, pause, kill et retraite.

Un retour capteur-actionneur manquant signifie boucle ouverte. Un état persistant manquant signifie une invite répétée. Une preuve de vérificateur manquante signifie un achèvement auto-affirmé. Un contrôleur/déclencheur manquant signifie une procédure que les humains doivent actionner.

Profil minimal

Toutes les boucles n'ont pas besoin des vingt éléments. Pour une boucle de type cron à opérateur unique — un utilisateur, une machine, faible rayon d'impact, pas d'effets de bord partagés — un contrat avec huit éléments suffit :

1. objectif et propriétaire ;
2. condition de succès (achèvement ou par exécution) ;
3. déclencheur et prévol peu coûteux ;
4. actionneur et son chemin d'effet de bord ;
5. état persistant et curseur ;
6. idempotence/déduplication sur le chemin d'effet de bord ;
7. observabilité : où voir le dernier résultat et la prochaine action ;
8. condition de retraite.

Déclarez les omissions explicitement au lieu de les laisser vides : définissez learning.enabled: false, et définissez capabilities.discovery: "none" avec un champ reason. Le linter accepte les deux. Voir loop.contract.minimal-example.json pour un exemple de contrat minimal valide. Passez au contrat complet lorsque la boucle acquiert des effets de bord partagés, un second opérateur, des locataires externes ou toute forme d'auto-modification.

Produisez un package de boucle

Adaptez les noms au dépôt, mais conservez un contrat canonique lisible par machine et un enregistrement d'état. Les packages de boucle, l'état et les preuves résident dans le projet de l'utilisateur, jamais à l'intérieur de ce package de compétence. Le package par défaut est :

loop/
├── LOOP-CONTRACT.md          contrat opérationnel lisible par humain
├── loop.contract.json       contrat canonique lisible par machine
├── RUN-STATE.json           exécution en cours, curseur, tentatives, prochaine action machine
├── events/                  événements d'exécution en ajout seul ou magasin d'événements équivalent
├── evidence/                reçus lisibles par vérificateur
├── evals/                   vérifications d'acceptation déterministes et sémantiques
├── knowledge/               connaissances promues typées, pas de journaux bruts
├── candidates/              leçons non promues et modifications de compétences
└── scripts/run-loop         contrôleur en une commande ou équivalent natif du projet

Utilisez loop-contract.md pour le contrat de champ. Copiez loop.contract.template.json, remplissez chaque espace réservé, puis exécutez :

python3 scripts/loop_lint.py /chemin/vers/loop.contract.json

Utilisez la copie dans cette compétence lorsque le projet n'a pas intégré le linter. Si rien ne peut être écrit sur le disque, produisez le contrat et le contrôleur sous forme de texte copiable et dites ce qui reste à placer sur le disque avant que la boucle ne soit opérationnelle.

Construisez le contrôleur, pas seulement les instructions

Le contrôleur doit permettre à une invocation d'avancer la boucle sans demander à l'utilisateur de copier-coller entre agents :

1. acquérir un verrou de concurrence et dériver une clé d'idempotence ;
2. charger et lint le contrat et l'état ;
3. vérifier les hachages source figés ou l'autorité source actuelle ;
4. exécuter le déclencheur/prévol peu coûteux et enregistrer un succès sans opération quand aucun travail n'existe ;
5. résoudre les capacités requises ;
6. créer un paquet de contexte minimal pour l'orchestrateur/exécuteur ;
7. exécuter dans un espace de travail isolé lorsque des modifications sont possibles ;
8. capturer les sorties, coûts, appels d'outils, diffs et preuves ;
9. exécuter un vérificateur indépendant qui ne peut pas certifier ses propres écritures ;
10. en cas d'échec, classifier et router une réparation limitée, une tentative, un rollback ou un arrêt ;
11. en cas de succès, promouvoir atomiquement le résultat et mettre à jour l'état actuel ;
12. ajouter un événement/reçu immuable ;
13. invoquer la distillation uniquement lorsque son déclencheur est satisfait ;
14. libérer le verrou et exposer la prochaine action exécutable par la machine.

Indépendance minimale du vérificateur, par moteur :

• Claude Code (ou tout runtime avec sous-agents) : exécutez le vérificateur comme un sous-agent avec un contexte frais qui ne reçoit que le contrat, les vérifications d'acceptation et les chemins de preuves — pas la conversation de l'exécuteur.
• Pas de mécanisme de sous-agent : exécutez le vérificateur comme un processus séparé ou une invocation séparée qui relit les preuves du disque et retourne un verdict contre les vérifications d'acceptation.
• Aucun des deux disponibles : le même contexte vérifiant son propre travail est une auto-révision — de la performance, pas de la vérification. Dites-le dans l'audit au lieu de l'étiqueter comme vérificateur.

Préférez le code déterministe pour les déclencheurs, transitions d'état, vérifications de schéma, permissions, tentatives, hachages et promotion. Utilisez les LLM pour le jugement, la planification, le diagnostic et le contenu qui ne peut pas être décidé mécaniquement.

Découvrez ou créez des compétences sans liste blanche statique

Utilisez la découverte ouverte avec exécution contrôlée :

1. Dérivez un contrat de capacité à partir de la tâche : entrée, sortie, effets de bord, preuves, risque.
2. Recherchez les compétences installées et les capacités du projet par métadonnées et adéquation du contrat.
3. Inspectez la provenance et les dépendances ; n'importez pas l'identité intégrée du projet comme vérité.
4. Isolé une compétence candidate et exécutez des évaluations spécifiques à la capacité.
5. Si aucune ne convient, créez une compétence candidate en isolation avec ses propres exemples et évaluations.
6. Promouvez une version seulement après qu'elle passe les vérifications de sécurité, vie privée, fonctionnelles et de régression.
7. Enregistrez localement par défaut. La publication externe suit la politique distincte de l'environnement propriétaire.

La découverte ouverte n'accorde pas d'autorité ouverte. Les mandats, le périmètre des données, la politique des effets de bord et les permissions d'exécution contraignent toujours chaque compétence.

Distillez l'expérience en connaissances utilisables

Ne nourrissez jamais un journal toujours croissant à chaque agent. Gardez les preuves brutes, les résumés épisodiques, les leçons candidates, les connaissances canoniques, les compétences procédurales et les évaluations séparés.

Exécutez le chemin de promotion :

trace + résultat
→ épisode normalisé
→ leçon candidate
→ dédupliquer et vérifier les conflits
→ rejouer contre les exécutions antérieures et les contre-exemples
→ ombre ou canari
→ promouvoir une version
→ surveiller les exécutions suivantes
→ conserver ou rollback

Déclenchez la distillation en cas d'échec répété, de travail manuel répété, de dérive, de régression de coût, de preuve de résultat significative ou d'une taille d'échantillon configurée — pas simplement parce que le temps a passé. Lisez distillation.md avant de concevoir ou modifier la couche d'apprentissage. Si une compétence de distillation dédiée (comme experience-pack) est installée, laissez-la posséder le workflow de distillation lui-même ; cette compétence conçoit la boucle qui l'invoque.

Le processus d'évolution peut améliorer les SOP, les déclencheurs, le packaging de contexte, les scripts, les compétences, la récupération et les seuils opérationnels dans les limites de l'autorité déléguée. Il ne peut pas réécrire silencieusement l'objectif, la frontière source, la frontière locataire/vie privée, le modèle d'autorité ou l'évaluation qui définit le succès.

Remplacez la vérité active proprement

Pour toute mise à jour acceptée :

1. calculez le graphe d'impact à travers le contrat, le schéma d'état, le code, les tests, la documentation, les vues et les compétences ;
2. déclarez REMPLACE, SUPPRIME et CONSERVE ;
3. mettez à jour tous les dépendants ;
4. supprimez les formulations et valeurs remplacées de la récupération active ;
5. exécutez des scans de contradiction/valeurs obsolètes ;
6. exécutez les évaluations affectées des chemins de succès et d'échec ;
7. exécutez une sonde sans contexte qui doit récupérer exactement une réponse actuelle ;
8. promouvez atomiquement ; conservez les versions antérieures uniquement dans le contrôle de version/l'historique des événements, pas dans le contexte actif.

Calibrez l'autonomie

• Exécutez automatiquement les actions réversibles et limitées lorsque la vérification déterministe et indépendante réussit.
• Utilisez canari, ombre, double vérification et rollback pour les actions automatisées à plus haut risque.
• Arrêtez-vous pour l'utilisateur uniquement lorsque l'autorité manque, qu'une décision requise change l'objectif ou que l'action est matériellement irréversible et pas déjà autorisée.
• Ne faites jamais de l'approbation humaine de routine un actionneur caché dans une boucle présentée comme autonome.

Vérifiez l'achèvement

N'appelez pas la boucle opérationnelle tant que tous ces points ne sont pas vrais :

• une commande ou un événement configuré peut l'avancer sans transfert d'invite ;
• la reprise après interruption reprend à partir de l'état persistant sans refaire le travail accepté ;
• les déclencheurs en double ne peuvent pas dupliquer les effets de bord ;
• une défaillance du vérificateur provoque une réparation limitée ou un arrêt propre ;
• les chemins de succès et d'échec-fermé ont des preuves ;
• une exécution sans travail se termine avec succès et à moindre coût ;
• le statut actuel, le dernier résultat, le coût, l'échec ouvert et la prochaine action sont observables ;
• un candidat d'évolution a été rejoué et soit promu soit correctement rejeté (dispensé dans le profil minimal avec learning.enabled: false) ;
• un agent sans contexte peut expliquer le contrat actuel et la prochaine action à partir des seuls fichiers actifs.

Rapportez séparément : ce qui est implémenté, ce qui a été exercé, ce qui reste dormant faute de capteur en direct et ce qui nécessite encore l'autorité de l'utilisateur.