Glossaire du Domaine EPURE (Source Unique)
Cette page inclut directement le fichier canonique /GLOSSARY.md situé à la racine du dépôt (`# Orchestration du développement semi-automatisé
Vocabulaire métier du pilotage de développement par issues, décisions, branches, validations et agents.
Demandes et décisions
Issue de pilotage : demande principale qui rassemble le dialogue de clarification, les décisions et le périmètre d'une fonctionnalité. Éviter : ticket d'implémentation, pull request.
Plan approuvé : périmètre, critères d'acceptation et graphe de tâches autorisés par un humain pour exécution autonome, sous conditions définies. Éviter : brouillon, simple proposition.
Ticket d'implémentation : unité de travail issue d'un plan approuvé, réalisable et vérifiable séparément. Éviter : issue de pilotage, décision architecturale.
Dépendance bloquante : relation empêchant un ticket de devenir exécutable tant qu'un autre n'est pas résolu conformément au plan. Éviter : lien de parenté, simple référence.
Changement de périmètre : modification significative des exigences, des choix architecturaux ou des dépendances au-delà de l'autorisation du plan approuvé. Éviter : correction technique interne au périmètre.
Architecture cible : ensemble des décisions architecturales acceptées, qu'elles soient déjà réalisées ou non. Éviter : architecture effective.
Architecture effective : organisation et comportement réellement présents dans une version déterminée du code. Éviter : architecture cible.
Acteurs et contrôles
Contributeur autorisé : utilisateur disposant de la permission GitHub effective write ou supérieure sur le dépôt cible, vérifiée au moment de la demande ou de la transition privilégiée. Seule cette permission permet le déclenchement des agents. Éviter : author_association, contributeur historique ou simple ouverture d'issue/PR comme preuve de droit.
Contribution externe : issue ou PR ordinaire soumise par une personne sans permission write ; acceptée comme contribution publique mais jamais comme autorisation d'exécuter des agents ou du code avec secrets privilégiés. Éviter : déclencheur LLM, instruction d'administration.
Revue indépendante : évaluation d'un changement par un agent distinct de celui qui l'a produit, à partir de la spécification et du code soumis. Éviter : autovalidation de l'agent d'implémentation.
Validation automatisée : ensemble des contrôles requis pour déclarer une contribution éligible à une intégration sans approbation humaine individuelle. Éviter : validation humaine d'intégration.
Validation humaine d'intégration : approbation par une personne autorisée de l'intégration d'une fonctionnalité complète dans la branche de développement partagée. Éviter : revue automatisée d'un ticket.
Exception sensible : changement dont le niveau de risque exclut l'intégration automatique, même si les contrôles automatisés sont concluants. Éviter : ticket ordinaire.
Escalade humaine : passage d'un ticket ou d'un plan à l'état technique suspended (label needs-human) requérant une décision ou action humaine avant reprise vers active. Se distingue du Plan annulé (cancelled), qui désactive toute exécution ultérieure. Éviter : échec définitif, annulation, crash silencieux du runner.
Unités d'intégration
Branche de fonctionnalité : branche regroupant les changements de tous les tickets d'une demande approuvée avant l'intégration humaine à la branche de développement partagée. Éviter : branche de ticket, branche stable.
Branche de ticket : branche isolant le changement d'un ticket jusqu'à son intégration à la branche de fonctionnalité. Éviter : branche de fonctionnalité.
Intégration de ticket : admission d'une contribution dans la branche de fonctionnalité après réussite des contrôles automatisés et absence d'exception sensible. Éviter : intégration de fonctionnalité.
Intégration de fonctionnalité : admission d'une branche de fonctionnalité dans la branche de développement partagée après validation humaine. Éviter : intégration de ticket, release.
Intégration sérialisée : traitement ordonné des intégrations de tickets dans une même branche de fonctionnalité, même lorsque leur développement a lieu en parallèle. Éviter : développement séquentiel.
Release : promotion d'un état validé du développement partagé vers la version stable. Éviter : intégration de ticket, intégration de fonctionnalité.
Sécurité et autonomie
Exécuteur d'agent : composant qui réalise une phase de travail autonome sans disposer des droits de publication privilégiés sur GitHub. Éviter : éditeur GitHub, contrôleur de permissions.
Éditeur privilégié : composant qui applique à GitHub des opérations préalablement autorisées et validées, à l'aide d'une identité technique temporaire. Éviter : agent d'implémentation, agent de planification.
Gestion financière externe du LLM : facturation, crédits, éventuels plafonds financiers et quotas de dépense gérés par le fournisseur LLM ou la clé API, sans comptabilité ni budget monétaire dans dev-automation. Éviter : budget de ticket, budget de fonctionnalité, coût calculé en CI.
Garde-fou opérationnel d'agent : limite technique d'exécution appliquée par dev-automation (nombre de tentatives, concurrence, timeout), sans prétendre garantir un coût monétaire. Éviter : plafond de dépense LLM, limite de facturation fournisseur.
Agent de migration : agent chargé de proposer les changements nécessaires à la compatibilité d'une mise à jour de dépendance, sans décider lui-même de sa promotion en développement partagé. Éviter : gestionnaire de dépendances, bot de publication.
PR de visibilité : pull request ouverte en brouillon pour rendre visible une fonctionnalité encore incomplète, sans autoriser son intégration. Éviter : PR prête à intégrer.
Documentation et livraison
Contrôleur de dispatch : logique versionnée dans dev-automation et exécutée par un workflow partagé dans le dépôt appelant, qui authentifie l’auteur de l’événement, contrôle les transitions et délègue aux exécuteurs autorisés (Q21 révisée). Éviter : code expérimental de dev, agent qui exécute des tests non fiables.
Release à déclenchement humain : workflow workflow_dispatch lancé par un humain autorisé qui vérifie une révision figée de dev, avance main uniquement par fast-forward, puis crée le tag et la GitHub Release sur cette même révision. Les actions Git restent automatisées ; leur lancement ne l'est pas. Éviter : push Git manuel obligatoire, promotion automatique au merge dans dev.
Hotfix stable : correctif urgent préparé et validé manuellement pour main, puis réintégré dans dev avant la prochaine promotion fast-forward. Éviter : release sélective de dev, réécriture forcée des branches.
Release intégrale : promotion de l'intégralité du SHA validé de dev, sans sélectionner certains commits ou tickets ; si nécessaire, le comportement non publiable demeure désactivé par des feature flags. Éviter : cherry-pick sélectif d'une feature au moment de la release.
ADR approuvé : décision architecturale acceptée par un humain et intégrée d'abord à dev, puis incluse dans main lors d'une release. Éviter : architecture effective, décision seulement proposée.
Référence documentaire : commit Git immuable contenant les ADR, glossaire et spécification auxquels un ticket est tenu de se conformer. Éviter : dernière version implicite ou non qualifiée.
Promotion fast-forward : déplacement du pointeur de main sur un commit descendant de son SHA actuel, sans commit de fusion ou réécriture d'historique. Éviter : action GitHub « Rebase and merge », qui recrée les commits.
Révision de release : SHA précis de dev sur lequel portent l'approbation humaine, les contrôles et l'avancement de main. Éviter : nom mouvant de branche sans contrôle de SHA.
Réconciliation : relecture déterministe des objets GitHub et correction des états incomplets ou des opérations interrompues, de façon idempotente. Éviter : nouvelle exécution aveugle d'une opération déjà produite.
Plan annulé : plan désactivé pour toute nouvelle exécution et intégration automatique, sans destruction de ses traces ni branches existantes. Éviter : plan terminé, plan suspendu après échec.
Workflow appelant : workflow du dépôt applicatif qui reçoit un événement (par exemple issue_comment) et invoque un Reusable Workflow versionné de dev-automation via workflow_call ; les jobs s’exécutent pour le dépôt appelant. Éviter : relais repository_dispatch obligatoire, exécuteur central implicite.
Dépôt d’automatisation (EPURE) : dépôt public Giskard-AI/epure (Engineered Planning, Unified Review & Execution / Élaboration de Plans, Usinage, Revue et Exécution), indépendant des releases applicatives, qui distribue les workflows réutilisables, Custom Actions, politiques et skills (Q21 révisée, Q81, ADR-0008). Éviter : service hébergé central qui consomme les secrets et quotas des utilisateurs.
Reusable Workflow : workflow GitHub exposé via workflow_call, déclarant une orchestration multi-jobs, les préconditions, permissions et secrets attendus ; exécution sur les ressources du dépôt appelant. Éviter : Custom Action mono-étape, exécution centralisée.
Custom Action : composant GitHub Actions autonome référencé par son action.yml, exécuté comme étape d’un job appelant et héritant de son contexte de sécurité. Éviter : frontière d’isolation entre agents et secrets.
Interface publique V1 : contrat versionné et documenté des Reusable Workflows et des Custom Actions ; les modifications incompatibles requièrent une nouvelle version majeure. Éviter : bibliothèque interne sans garantie de compatibilité.
Mise en service d’un dépôt consommateur
GitHub App du consommateur : application enregistrée et détenue par l’utilisateur ou l’organisation qui adopte dev-automation, installée sur les seuls dépôts sélectionnés et utilisée pour émettre des jetons d’installation temporaires. Elle n’est pas administrée par le mainteneur de dev-automation. Éviter : GitHub App partagée du mainteneur, jeton personnel permanent.
Skill de configuration d’un dépôt : procédure interactive et versionnée, distribuée par dev-automation, qui aide à vérifier les prérequis, enregistrer/installer la GitHub App du consommateur, configurer les variables et secrets locaux, installer workflows et politiques, puis vérifier l’installation. Les opérations sensibles nécessitent l’action ou l’accord de l’administrateur concerné. Éviter : service d’installation hébergé, émission automatique de secrets sans contrôle du propriétaire.
Agent App : GitHub App possédée par le consommateur, réservée aux opérations de développement (issues, branches, commits, PR), sans autorité de promotion d'une release. Éviter : Release App, token d'administration générale.
Release App : GitHub App distincte réservée au workflow humain de promotion dev → main, à la création de tags et de releases. Éviter : Agent App, jeton de développement.
Bootstrap local : première installation de dev-automation dans un dépôt consommateur par un skill exécuté localement, avant que la CI agents ne soit opérationnelle. Éviter : installation déclenchée depuis une issue non authentifiée.
Configuration d'agents par dépôt : fichier .github/agents.yml déclarant les choix locaux autorisés (harness, modèles, limites), dont aucune valeur ne peut abaisser les restrictions du workflow partagé. Éviter : secrets en clair, dérogation de sécurité locale.
Installation idempotente : procédure pouvant être rejouée sans duplication ni écrasement intempestif, précédée d'une inspection et proposant un mode --dry-run. Éviter : réinitialisation aveugle de la configuration.
Distribution et garde-fous (ronde 8)
Référence immuable de workflow/action : SHA Git complet du dépôt dev-automation utilisé pour charger un workflow ou une Custom Action, dont la mise à jour est proposée par une PR Renovate. Éviter : tag mutable v1 présenté comme immuable.
Sandbox de code non fiable : environnement qui empêche des processus lancés sur du code potentiellement hostile de lire les credentials et secrets des agents, publisher ou release. Éviter : simple masquage de logs, action composite considérée comme frontière de sécurité.
Merge automatique conditionnel : merge d'une PR task/* → feature/* après vérification de la CI, de la review IA, de la base d'intégration courante et de l'absence de changement sensible. Éviter : intégration directe sur dev, validation sur une base obsolète.
Contrôle financier fournisseur : limite financière qui peut être fournie par le prestataire LLM (compte, organisation, clé API). Elle n'est pas garantie par dev-automation et peut être indisponible selon le prestataire. Éviter : garantie de plafond global par le workflow, compteur financier GitHub.
Échec transitoire du fournisseur LLM : indisponibilité ou coupure temporaire d'une API (5xx, 408, timeout/coupure réseau) permettant une reprise bornée avec backoff (max_transient_api_retries, comptabilisé par requête HTTP unitaire et non cumulé sur l'ensemble d'une boucle d'outils). Les répétitions réseau/API ne consomment pas le quota de trois corrections de code d'un ticket. Éviter : recommencer sans borne, masquer une panne persistante, mutualiser un unique compteur de reprises sur 20 tours d'outils.
Temporisation de limite de débit LLM (429) : attente automatique lors d'une limitation temporaire de débit (HTTP 429 hors épuisement de quota/facturation) respectant l'indication Retry-After du fournisseur (ou un délai progressif par défaut plafonné à 300 secondes, jusqu'à 10 attentes par requête HTTP), suivie d'une relance sans consommer le quota max_transient_api_retries ni le quota de corrections de code du ticket. Éviter : décompter une pause de rate-limit 429 comme un échec serveur ou attendre indéfiniment sans plafond de sécurité.
Blocage fournisseur LLM : problème de clé, de crédits ou de quota empêchant la poursuite des tâches dépendantes ; signalement GitHub et suspension sans changement automatique de clé ou de fournisseur. Éviter : fallback automatique contournant les plafonds définis par l'utilisateur.
Reprise après suspension (suspended -> active) : réactivation idempotente d'une issue de pilotage ou d'un ticket en état suspended (needs-human) lorsqu'un contributeur autorisé (write ou supérieur) publie une réponse ou relance la commande de phase correspondante, retirant le label needs-human, restaurant le statut active tout en conservant la phase courante (grilling, spec, tickets, implementation) et reprenant au dernier jalon validé. Éviter : bloquer définitivement une issue suspendue après une panne API temporaire ou écraser la phase d'orchestration lors de la suspension.
Épuisement des tentatives de remédiation (remediation_exhausted) : atteinte du plafond de corrections automatisées d'un ticket ou d'une branche de fonctionnalité (max_code_fix_attempts, fixé à 3 par ADR-0012), que l'échec provienne des tests en sandbox isolée, de la revue multi-agents ou de la CI externe, entraînant une escalade humaine. Éviter : confusion avec un dépassement du budget d'horloge du runner (wall_clock_budget_exhausted) ou code d'escalade parallèle non typé.
Réponse LLM invalide après relance corrective (llm_request_invalid) : rejet non transitoire d'une requête LLM (HTTP 400) ou sortie structurée violant encore les invariants du schéma après les relances correctives avec rétroaction de l'erreur de validation ; déclenche une escalade humaine sans consommer le quota de corrections de code du ticket. Éviter : qualifier une sortie invalide d'échec réseau transitoire ou relancer à l'aveugle sans transmettre l'erreur de validation au modèle.
Refus du modèle LLM (llm_refusal) : réponse Anthropic terminée par stop_reason: refusal, signalée par une LLMError de reasonCode REFUSAL ; non relancée, elle déclenche une escalade humaine sans consommer le quota de corrections de code du ticket. Éviter : traiter un refus comme une sortie structurée invalide (llm_request_invalid) ou relancer la même requête.
Configuration de modèle manquante (model_config_missing) : absence d'entrée model sur l'action et d'au moins une clé models.planning, models.implementation ou models.review dans .github/agents.yml ; détectée par resolvePhaseModels (MissingModelConfigError) uniquement sur les commandes appelant un LLM, avant tout appel, et escaladée en needs-human en nommant la ou les clés à renseigner. Aucun modèle de repli n'est substitué, conformément au principe d'absence de bascule automatique de l'ADR-0012. Éviter : modèle par défaut implicite, qualifier l'erreur d'échec d'authentification ou de quota fournisseur.
Orchestration des conversations et des reviews (ronde 9)
État de conversation versionné : documents et décisions intermédiaires d'un entretien conservés dans plan/*, distincts des commentaires GitHub qui servent d'interface humaine. Éviter : dépendance à la mémoire du runner, relecture intégrale systématique des commentaires.
Exécution ordonnée par issue : protocole garantissant une exécution active au maximum pour chaque issue et le traitement/dédoublonnage des commentaires suivants. Éviter : jobs concurrents publiant des décisions contradictoires sur une même issue.
Review IA liée au SHA : verdict portant sur une version exacte de la branche source et le diff réellement examiné ; tout changement du code revu invalide ce verdict. Éviter : review positive réutilisée après modification du code.
Politique de base obsolète (strict / relaxed) : politique par dépôt. strict impose une base actuelle ; relaxed tolère une source en retard sans conflit si le diff approuvé est inchangé et la CI réussit sur son intégration à la dernière cible. Éviter : « pas de conflit Git » considéré seul comme test d'intégration.
Résultat combiné : arbre Git résultant de l'intégration d'une PR à la révision courante de sa branche cible, utilisé par les tests d'intégration avant fusion. Éviter : seuls tests de la branche source avec une cible antérieure.
Traçabilité d'exécution d'agent : métadonnées GitHub associant rôle d'agent, modèle, révision de dev-automation et lien du run aux opérations effectuées. Éviter : publication de secrets ou de données sensibles des prompts.
Validation GitHub et interventions humaines (ronde 10)
GitHub Check ai-review : résultat de review IA publié par l'Agent App sur le SHA analysé, pouvant devenir un contrôle obligatoire de protection de branche. Son producteur autorisé fait partie de sa validité. Éviter : commentaire « LGTM » comme preuve de review, check homonyme émis par un autre acteur.
Merge Queue native : mécanisme GitHub, lorsqu'il est disponible, qui met en file les PR et contrôle leur intégration avec les changements précédents. Sinon, le contrôleur réalise une sérialisation et une validation équivalentes à son niveau sans contourner les règles GitHub. Éviter : supposer la disponibilité sur chaque dépôt public personnel.
Correction par nouveau commentaire : modification d'une décision de planning au moyen d'un commentaire ultérieur, plutôt que par édition rétroactive d'une réponse déjà traitée. Éviter : réinterprétation silencieuse des décisions archivées.
Intervention humaine sur une branche de ticket : commit produit par un contributeur autorisé sur task/*, autorisé mais invalidant les contrôles anciens liés à un SHA ou à un diff obsolètes. Éviter : traiter une ancienne review positive comme valable après une correction humaine.
Déclenchements délégués et maintenance des dépendances (ronde 12)
Autorisation déléguée d'un plan : permission humaine enregistrée pour un ensemble précis d'opérations et de tickets approuvés ; les événements internes peuvent poursuivre ce plan sans devenir de nouvelles approbations. Chaque opération vérifie l'autorisation et l'état courant avant exécution. Éviter : considérer n'importe quel événement GitHub App ou workflow comme un mandat général.
Migration Renovate automatique (auto_migrate) : option administrateur permettant à un agent de proposer des correctifs sur une PR Renovate dont la CI échoue, en consultant les guides de migration ; n'autorise pas à merger vers dev sans approbation humaine. Éviter : exécuter avec secrets le code d'une PR non vérifiée, utiliser une PR arbitraire comme déclencheur.
Migrations, releases et moteurs d’agent (ronde 13)
Provenance Renovate vérifiée : identité de l’application et origine de la PR reconnues par GitHub, plus correspondance avec le dépôt et la branche cible attendus ; condition nécessaire à auto_migrate. Éviter : inférence depuis un titre, label ou nom de branche.
Diagnostic d’échec CI : détermination de la cause probable (régression de code, rupture de compatibilité, infrastructure, cause incertaine) avant toute tentative de modification. Éviter : faire modifier le code par un agent à chaque job rouge.
Release SemVer : promotion humaine fast-forward de dev vers main, suivie de la création contrôlée d’un tag vMAJOR.MINOR.PATCH et d’une GitHub Release sur le même SHA. Éviter : tag déplaçable librement, release déclenchée directement par un agent, rebase and merge appelé fast-forward.
Adaptateur de moteur d’agent : composant implémentant une interface stable de pilotage et de résultats pour un moteur d’agent comme Pi ou Codex, indépendamment de sa CLI. Éviter : exposer dans tout l’orchestrateur les formats propriétaires d’un moteur donné.
Garde-fous de fin d'entretien (ronde 14)
Événement interne autorisé : événement technique produit dans la poursuite d'un plan préalablement approuvé et vérifié par l'orchestrateur ; il n'accorde aucune permission supplémentaire. Éviter : interpréter une réponse de bot comme une commande d'un humain.
Review IA indépendante : évaluation d'une révision par une session distincte de l'agent d'implémentation, avec spec, diff et tests, sans accès aux raisonnements internes de ce dernier ni pouvoir de merge. Éviter : autoprobation par l'implementer, réutilisation d'une review pour un nouveau SHA.
Blocage de fonctionnalité après régression : suspension persistante des merges automatiques vers une branche feature/* lorsqu'une intégration y provoque une régression constatée ; reprise après correction et nouveaux contrôles satisfaisants. Éviter : force-push de réparation, poursuite aveugle des autres merges.
CI minimale requise : ensemble de checks adaptés au dépôt, réellement configurés comme obligatoires avant tout merge automatique de ticket ; l'existence d'un workflow ou d'un check IA seul n'est pas suffisante. Éviter : intégrer automatiquement sur la seule base d'une review IA verte.
Licence et évaluation des agents (Q56–Q58)
Licence du projet (Apache-2.0) : licence choisie pour le code original de dev-automation, permettant la réutilisation commerciale et privée avec obligations de préservation des notices et licence explicite sur les brevets couverts. Éviter : prétendre relicencier en bloc des fichiers tiers ou imposer cette licence aux dépôts consommateurs.
Attribution des composants tiers : conservation des textes de licence, avis de copyright et NOTICE applicables aux contenus effectivement copiés ou redistribués, avec référence à leur provenance et révision. Éviter : assimiler une dépendance installée à une copie embarquée, ou supprimer les mentions MIT/Apache d'origine.
Impeccable (intégration optionnelle) : ensemble de skills et contrôles spécialisés frontend proposé via une Custom Action publique et un skill d'assistance ; activable par dépôt selon sa technologie. Éviter : déclencher systématiquement des contrôles UI sur des dépôts purement backend, ou leur accorder des permissions privilégiées sans nécessité.
iFixAi (intégration optionnelle) : outil d'audit des événements/trajectoires et de tests comportementaux, utilisé prioritairement pour évaluer la sécurité de dev-automation ; l'audit des traces complète sans remplacer l'application de la politique d'autorisation. Éviter : faire du score d'audit un substitut à la séparation des privilèges ou imposer un appel LLM sur chaque PR applicative.
Qualité visuelle et audits (Q59–Q61)
Check de design obligatoire par défaut : check CI Impeccable installé comme contrôle requis des PR frontend et désactivable par choix explicite du dépôt. Le seuil des constats bloquants reste à spécifier. Éviter : audit visuel systématique de dépôts sans interface, « informatif » par défaut.
Trajectoire d'audit minimisée : suite structurée d'événements, permissions et transitions, limitée aux métadonnées vérifiables nécessaires à l'évaluation d'iFixAi, sans secrets ni logs internes complets. Éviter : journal de prompts non filtré, stockage de credentials.
Conception frontend intégrée (Q62–Q65)
Entretien UX/UI unifié : extension de l'issue de pilotage après grill-with-docs utilisant le cadrage Impeccable shape, avec réutilisation des décisions existantes. Éviter : ouvrir une deuxième conversation de conception déconnectée du plan approuvé.
Prototype exploratoire : représentation légère d'une interaction ou interface importante, produite avant approbation sur prototype/* avec données fictives ; captures et informations de prévisualisation liées à l'issue. Éviter : assimiler le prototype à du code prêt à merger automatiquement sur dev.
Contexte produit (PRODUCT.md) : document versionné décrivant utilisateurs, besoins et contraintes produit, distinct des spécifications d'une fonctionnalité. Éviter : confondre contexte produit durable et exigences d'un ticket.
Système de design (DESIGN.md) : document versionné de conventions et choix UX/UI, distinct des décisions propres à un écran (.impeccable/surfaces/*.md). Éviter : règles visuelles contradictoires dispersées dans les prompts d'agents.
Violation de design bloquante : problème nouveau qui correspond soit aux règles bloquantes par défaut d'Impeccable (accessibilité vérifiable, cassures de layout/overflow, non-respect des tokens définis, états d'interaction obligatoires manquants), soit à une règle supplémentaire ajoutée dans DESIGN.md ou .impeccable/surfaces/*.md, identifié par le check CI et empêchant le merge tant qu'il n'est pas corrigé ou explicitement exempté. Éviter : bloquer une PR sur une préférence esthétique subjective ou sur l'ensemble du passif visuel non modifié.
Prévisualisation et transfert design → implémentation (Q66–Q69)
Artifact de prévisualisation : capture, rapport ou fichier HTML produit par une CI et accessible depuis la page du run ou ses artifacts, sans hébergement externe requis. Éviter : assimiler des fichiers HTML complexes à un site navigable servi par un hébergeur.
Preview statique GitHub Pages : publication facultative de prototypes HTML/CSS/JS fictifs et non sensibles accessibles par URL ; une prévisualisation isolée par issue nécessite une stratégie de répertoires/versionnement et de nettoyage. Éviter : supposer une preview native par PR ou y intégrer des secrets et des données privées.
Prototype non réutilisable : code exploratoire produit pour valider un comportement ou une direction UX, sans transfert direct dans le code applicatif final. Seuls les choix design, critères d'acceptation et actifs de référence constituent des entrées pour l'implémentation. Éviter : cherry-pick, copie ou merge automatique du code de prototype/*.
Approbation du graphe de tickets : autorisation humaine donnée après production de la spec et des tickets dépendants ; elle délimite le périmètre exécutable par les agents. Éviter : transformer une approbation d'une simple maquette en autorisation implicite de construire tout le plan.
Modes de prévisualisation complémentaires (Q66 confirmé) : GitHub Actions artifacts/captures, GitHub Pages pour prototypes statiques si configuré, et environnement de preview préexistant du projet. Aucun de ces modes ne nécessite que dev-automation héberge un serveur central. Éviter : rendre obligatoire un hébergeur tiers ou publier par défaut un prototype sensible sur un site public.
Déclenchement des prototypes et hébergement (Q71–Q73)
Détour de prototypage fondé sur une question : branche facultative du flux grilling/ask-matt quand un comportement d'état ou un choix visuel ne peut être validé par la conversation ; prototype traite une question précise et handoff transfère les apprentissages. Impeccable shape complète l'exploration UX, sans règle arbitraire de complexité. Éviter : générer un prototype pour chaque issue frontend ; transformer le code exploratoire en code applicatif.
Rétention de preview hébergée : durée de vie par défaut de 14 jours, configurable par dépôt, suivie d'une suppression automatisée. Éviter : confondre suppression des previews accessibles publiquement et suppression des décisions documentées.
Isolation de preview publiée : séparation effective entre prototype et site de production, avec interdiction de publier secrets et données personnelles. Un simple sous-chemin d'une origine partagée n'est pas une isolation de sécurité suffisante. Éviter : supposer que /previews/42/ peut exécuter du JavaScript non fiable sans risque sur le même domaine que la production.
Publication Pages sur consentement (Q70) : possibilité pour setup-repo d’activer GitHub Pages pour des previews statiques uniquement après accord explicite de l’utilisateur ; configuration désactivée par défaut. Sans activation, les artifacts et captures restent la référence. L’activation exige une séparation du site de production (Q73) et la rétention configurable de 14 jours (Q71). Éviter : publier par défaut des prototypes sur le domaine de production ou assimiler un sous-chemin à une origine isolée.
Isolation d'exécution, état Git hors branches et gouvernance EPURE (Q74–Q83)
Proxy LLM de sandbox (Q74) : processus sidecar local sur le runner GitHub Actions qui détient seul en mémoire la clé API LLM et les tokens d'installation, tandis que l'agent et les sous-processus de test/build du dépôt consommateur s'exécutent dans un conteneur isolé dépourvu de secrets dans ses variables d'environnement. Éviter : injecter OPENAI_API_KEY ou ANTHROPIC_API_KEY directement dans l'environnement où s'exécutent npm test, pytest ou les hooks postinstall.
Traitement en lot des commentaires avec curseur (last_processed_comment_id, Q75) : mécanisme par lequel un job sérialisé par concurrency: issue-<N> lit à son démarrage tous les commentaires humains postés depuis le dernier identifiant traité et les intègre séquentiellement, empêchant toute perte d'événement lorsque la file d'attente GitHub Actions compresse les runs en attente au-delà de deux événements. Éviter : se fier uniquement au payload github.event.comment du webhook déclencheur ou activer cancel-in-progress: true.
Référence Git d'état d'orchestration (refs/epure/state/<issue-number>, Q76) : référence Git dédiée hors branches standard (refs/heads/*) stockant l'état machine d'orchestration (curseur last_processed_comment_id, mandat de plan approuvé avec spec_sha, approved_by, statut active|cancelled, compteurs de tentatives par ticket) avec compare-and-swap atomique Git, doublée d'un tableau de bord Markdown lisible synchronisé dans le corps de l'issue GitHub. Éviter : polluer l'historique des branches applicatives dev et main avec des commits JSON d'état machine ou utiliser uniquement un commentaire d'issue sujet aux écrasements concurrents.
Orchestration réelle multi-fournisseurs (LLMClient) et Publisher GitHub App (Q84–Q90)
Continuité implicite de l'entretien de grill et de la révision de spécification (Q84) : traitement automatique de tout commentaire humain posté sur une issue de pilotage dont la référence refs/epure/state/<issue-number> est en phase grilling (réponse au grill ou ajustement de la synthèse) ou en phase spec (demande de révision des artefacts de spécification sur plan/<issue>-<slug>) sans imposer de répéter une commande slash à chaque tour. Éviter : rejeter les réponses humaines ordinaires sous prétexte qu'elles ne commencent pas par /epure.
Validation humaine de la frontière de Grill (Q85) : passage de l'issue de pilotage en phase grilling avec statut awaiting_human_approval dès que la frontière de l'arbre de décisions est vide (frontier_resolved: true), publiant la synthèse structurée des décisions actées et attendant l'approbation humaine explicite via /epure to-spec (ou un commentaire libre pour rouvrir un round de grill) avant toute rédaction documentaire. Éviter : enchaîner automatiquement la fin du grill avec la génération de la spécification ou la création des sous-issues sans validation humaine de la synthèse de cadrage.
Validation humaine de la spécification (Q85) : séparation explicite entre /epure to-spec (qui génère et commite GLOSSARY.md, docs/adr/NNNN-*.md, docs/specs/<slug>.md et DESIGN.md sur plan/<issue>-<slug>, puis passe l'issue en phase spec / awaiting_human_approval où tout commentaire libre révise la spécification) et /epure to-tickets (qui découpe la spécification validée en un DAG acyclique de tickets GitHub ready-for-agent avec blocked_by et passe l'issue en phase tickets / awaiting_human_approval en attente de /epure approve). Éviter : créer les sous-issues GitHub dès /epure to-spec avant que l'humain ait pu relire et valider la spécification sur plan/<issue>-<slug>.
Jeton d'installation GitHub App éphémère (Q87) : jeton court obtenu en signant un JWT RS256 avec EPURE_AGENT_APP_ID et EPURE_AGENT_APP_PRIVATE_KEY puis en appelant l'API d'installation GitHub du dépôt cible, utilisé par le publisher isolé pour créer branches, commits, tickets, PRs et checks, puis révoqué immédiatement. Éviter : exposer la clé privée PEM au processus agent ou partager un PAT personnel permanent.
Gouvernance Rulesets, Roster de Review Multi-Agents et Squash Sémantique par IA (Q91–Q96)
Séparation des trois Rulesets de gouvernance (epure-feature-governance, epure-dev-governance, epure-release-immutability, Q91 & Q95) : découpage explicite des règles GitHub Repository Rulesets en trois périmètres distincts (refs/heads/feature/* avec Agent App en bypass PR pour le squash-merge autonome des tâches validées et l'intégration directe des artefacts plan/* -> feature/* ; refs/heads/dev exigeant un merge humain dans l'interface GitHub pour toute PR feature/* -> dev, avec required_approving_review_count: 0 par défaut pour la compatibilité mainteneur solo et configurable via --require-pr-approvals <N> ; refs/heads/main et refs/tags/v* réservés à Release App). Éviter : mutualiser dev et feature/* dans un unique Ruleset qui autoriserait l'Agent App à fusionner du code applicatif dans dev sans validation humaine, ouvrir une PR intermédiaire plan/* -> dev bloquée par le Ruleset de dev, ou bloquer un mainteneur solo sur ses propres PRs.
Roster de reviewers spécialisés et transverses (reviewers_dir, Q92 & Q93) : ensemble de définitions de rôles d'audit en lecture seule (<nom>.md) initialisé par setup-repo dans le répertoire du roster du dépôt consommateur, configurable via la clé reviewers_dir de .github/agents.yml ou setup-repo --reviewers-dir <chemin> (.agents/reviewers/ par défaut) (spécialistes domain-backend-reviewer, frontend-reviewer, infra-reviewer ; transverses architecture-reviewer, security-reviewer, spec-parity-reviewer, standards-reviewer, accessibility-reviewer, design-reviewer ; et user-advocate), enrichi lors de /epure plan avec les personas et invariants du domaine, mais toujours chargé à l'exécution depuis la branche de base de confiance (dev) avec repli sur les templates embarqués d'EPURE, et classé comme chemin sensible interdisant toute auto-modification sur task/*. Éviter : charger un prompt de reviewer depuis la branche non fiable task/* inspectée (risque d'auto-approbation par injection de prompt), lier le roster au répertoire propre à un IDE donné, ou dépasser le plafond de 4 reviewers pertinents sélectionnés par diff.
Porte UX orientée personas (user-advocate, modes design-gate et implementation-review, Q96) : sous-agent évaluant le produit selon les personas d'utilisateurs finaux propres au domaine ; intervient d'abord en mode design-gate à l'issue du Grill sur plan/* (conjointement à DESIGN.md) pour enrichir les critères d'acceptation UX des tickets avant /epure approve, puis en mode implementation-review (conjointement au check impeccable-gate) comme contrôle bloquant sur les PRs touchant l'interface. Éviter : reporter toute la validation UX et d'accessibilité après le codage ou ignorer les impasses de parcours multi-rôles.
Synthèse de message de squash sémantique par IA (Q94) : génération juste avant chaque squash-merge, par un modèle léger à température nulle inspectant le diff consolidé de la PR, d'un titre Conventional Commit (type(scope): summary (#PR)) synchronisé sur la PR et d'un corps concis listant les changements effectifs, en utilisant Refs #<ticket> lors de l'intégration task/* -> feature/* et Closes #<issue> / Closes #<ticket> uniquement lors de l'atterrissage sur la branche par défaut dev. Éviter : conserver des messages de commits intermédiaires de debug dans l'historique de feature/* ou dev, ou supposer que Closes #N sur une branche non-default ferme automatiquement le ticket GitHub.
Taxonomie du flux d'orchestration et documentation bilingue (Q97–Q103)
Portes de validation humaine obligatoires (4 jalons, Q101) : les quatre points de décision où l'intervention explicite d'un contributeur autorisé (write ou supérieur) est indispensable et ne peut jamais être déléguée à un agent : (1) lancement /epure plan et réponses au Grill sur l'issue de pilotage, (2) signature du plan approuvé par /epure approve verrouillant spec_sha dans refs/epure/state/<issue>, (3) validation humaine d'intégration par revue et squash-merge humain de la PR finale feature/* -> dev, et (4) release à déclenchement humain (workflow_dispatch de promotion fast-forward dev -> main). Éviter : autoriser l'Agent App à fusionner du code applicatif dans dev ou main sans décision humaine explicite.
Étapes automatisées obligatoires (Q101) : séquence déterministe exécutée par l'orchestrateur sur chaque fonctionnalité approuvée : génération documentaire sur plan/<issue>-<slug> (GLOSSARY.md, docs/adr/, docs/specs/<slug>.md) et création du graphe de tickets d'implémentation avec blocked_by, boucle TDD en sandbox sans secret (npm test, npm run build, verify-contract), revue indépendante multi-agents chargée depuis dev avec auto-remédiation bornée (max_code_fix_attempts = 3) et intégration sérialisée (task/* -> feature/*) par squash sémantique IA, puis revue de synthèse complète sur la PR finale feature/* -> dev. Éviter : contourner la sandbox sans secret ou intégrer une branche task/* sans revue indépendante liée au SHA.
Étapes facultatives ou conditionnelles (Q101) : opérations activées uniquement selon la nature du changement ou la demande explicite d'un contributeur autorisé : détour exploratoire /prototype (Q72) et preview GitHub Pages isolée (Q70, désactivée par défaut), génération de DESIGN.md + user-advocate (design-gate et implementation-review) + impeccable-gate (Q96, activés automatiquement uniquement lorsque le projet ou le diff comporte une surface UI/frontend), commandes de pilotage granulaire (/epure to-spec, /epure to-tickets, /epure status, /epure cancel), et escalade humaine (needs-human) en cas d'exception sensible ou d'épuisement des trois tentatives de correction. Éviter : imposer les contrôles UI Impeccable ou un prototype exploratoire sur des projets ou tickets purement backend/CLI.
Vérification polyglotte et boucle de CI externe multi-workflows (Q104–Q111)
Profil de vérification polyglotte (verification.targets, Q104 & Q108) : déclaration par sous-projet dans .github/agents.yml (générée par setup-repo et repliée au runtime par inspection hybride des manifestes Node/Python/Rust/Go, des orchestrateurs Makefile/Justfile/Taskfile/turbo.json et de l'ensemble des workflows .github/workflows/*.{yml,yaml} hors EPURE), toujours chargée à l'exécution depuis la branche de confiance (dev) et classée comme chemin sensible sur task/*. Éviter : supposer un unique package.json à la racine, un fichier unique nommé ci.yml, ou autoriser une branche task/* à altérer ses propres commandes de test.
Vérification locale de pré-publication (Stage 1, Q105) : exécution dans un clone Git persistant de la sandbox sans secret, avant tout commit ou ouverture de PR, des commandes d'installation, de génération de code (codegen), de typage statique (typecheck), de lint et de tests unitaires/scripts ne nécessitant aucun conteneur de service externe, ciblées selon les path_patterns des fichiers modifiés. Éviter : retourner un succès par défaut en l'absence de package.json racine ou tenter de démarrer en sandbox locale les services lourds (PostgreSQL, Docker multi-stage) relevant de la CI GitHub Actions.
Porte de CI externe multi-workflows et boucle d'auto-réparation (Stage 3, Q106–Q110) : attente déterministe (avec fenêtre d'amorçage et corrélation des filtres on.pull_request/push sur tous les workflows .github/workflows/*.{yml,yaml} hors EPURE) de la complétude des check-runs et workflow_runs externes sur le head_sha d'une PR, suivie en cas d'échec applicatif de l'extraction assainie des annotations et logs d'erreur (~12 Ko) pour alimenter jusqu'à 3 rondes unifiées de remédiation (Review IA + CI externe), avec relance sans pénalité sur panne transitoire d'infrastructure et réconciliation idempotente des PRs déjà ouvertes. Éviter : fusionner task/* -> feature/* avant la fin des workflows CI externes, considérer zéro check-run à $T+0$ comme un succès, ou gaspiller une tentative de code sur un échec réseau du runner.
Routeur LLM multi-fournisseurs, sorties structurées et ergonomie /epure (ADR-0029)
Routeur LLM multi-fournisseurs (LLMClient) : Client HTTP TypeScript sans dépendance externe (inspiré de giskard-llm) routant chaque appel selon le préfixe <provider>/<model> (openai/, azure/, azure_ai/, google/, gemini/, anthropic/ ou un alias nommé déclaré dans la section providers: de .github/agents.yml avec résolution différée os.environ/VAR_NAME), garantissant l'absence de bascule automatique inter-fournisseurs sur erreur d'authentification ou de quota (ADR-0012). Éviter : coupler l'orchestrateur à un unique fournisseur au runtime, stocker des clés API en clair dans .github/agents.yml, ou basculer automatiquement vers un fournisseur de secours en cas d'erreur 401/402/403.
Sortie structurée par schéma (ResponseSchemaSpec<T>) : Contrat associant un JSON Schema strict (transmis nativement au fournisseur via responseSchema, response_format.json_schema ou output_config.format) et un validateur TypeScript d'exécution, remplaçant toute extraction heuristique de JSON par expression régulière. Sur Google Gemini avec outils d'exploration (tools), le client exécute la boucle d'outils puis déclenche un tour final dédié (functionCallingConfig.mode = "NONE") avec responseSchema activé. Éviter : extraire du JSON par expression régulière depuis du texte libre ou désactiver la validation de schéma lorsqu'une boucle d'outils est active.
Aide-mémoire contextuel des commandes /epure (formatEpureCommandsSpoiler) : Bloc Markdown repliable (<details>) inséré systématiquement au pied des commentaires d'issues, des sous-issues de tickets et des descriptions de Pull Requests générés par EPURE, récapitulant les commandes disponibles (/epure plan, /epure to-spec, /epure to-tickets, /epure approve, /epure continue, /epure sync / /epure rebase, /epure status, /epure cancel / /epure stop) et mettant en évidence la prochaine action attendue selon la phase courante. Éviter : publier des commentaires d'orchestration ou des escalades needs-human sans rappeler à l'opérateur humain les commandes de reprise (/epure continue), de synchronisation Git (/epure sync) ou d'annulation disponibles.
Confinement noyau Ubuntu 26.04, formatage sans état RTK et discipline anti-slop (ADR-0030)
Confinement noyau de sandbox (Stage 1) (SandboxNetworkPolicy / buildKernelSandboxedCommand) : Isolation système au niveau du noyau Linux 7.0 (ubuntu-26.04) en deux phases distinctes pour la vérification locale de pré-publication : (1) la phase install (networkPolicy: "https_only") s'exécute sous landrun (Landlock ABI v8) en restreignant les connexions TCP sortantes au seul port 443 et les écritures au répertoire de travail (workDir), /tmp et aux caches de paquets ; (2) les phases codegen, typecheck, lint, test et build (networkPolicy: "offline") s'exécutent totalement hors-ligne sous bubblewrap (--unshare-net --unshare-pid --unshare-ipc --tmpfs /tmp --die-with-parent), avec repli automatique sur landrun sans aucun port TCP autorisé lorsque les namespaces utilisateurs non privilégiés sont indisponibles. En mode d'exécution d'adaptateur d'agent (networkPolicy: "proxy_only"), landrun restreint le réseau au seul port local du proxy (--connect-tcp <proxyPort>). Éviter : exécuter du code ou des tests de dépôt consommateur sans confinement noyau en CI (EPURE_ENFORCE_KERNEL_SANDBOX=true), autoriser le réseau pendant l'exécution des tests unitaires, ou utiliser des conteneurs privilégiés nécessitant sudo.
Formatage et condensation sans état des sorties de test (RTK) (formatAndCondenseStage1CommandOutput) : Filtrage et nettoyage déterministe des journaux de vérification Stage 1 via rtk (rtk-ai/rtk épinglé et géré par Renovate avec quarantaine de 7 jours) configuré en mode 100 % sans état (tracking.enabled = false, telemetry.enabled = false, retriever.mode = "disabled", RTK_TELEMETRY_DISABLED=1, RTK_RECALL=0, RTK_TEE=0, NO_COLOR=1), supprimant les séquences ANSI, les barres de progression et le bruit des fichiers ignorés sans créer aucune base SQLite d'historique ou d'apprentissage, et conservant automatiquement en mémoire la queue brute d'erreur (4 000 derniers caractères) lorsqu'une commande échoue (exit_code !== 0). Éviter : activer la télémétrie, le suivi analytique SQLite (history.db) ou le magasin recall.db de rtk en CI, ou tronquer la pile d'appels brute d'un test en échec avant de la transmettre au modèle de remédiation.
Synchronisation Git inter-branches, continuation CI événementielle, audit Goldfish et exploration Web (ADR-0031)
Synchronisation inter-branches et résolution de conflits 3-way (syncBranchWithBase / /epure sync) : Rattrapage systématique ou déclenché à la demande (/epure sync, alias /epure rebase) de la branche de base (dev -> feature/* et feature/* -> task/*) combiné à l'intégration directe des artefacts de plan/* dans feature/* (fusion additive déterministe de GLOSSARY.md et renumérotation automatique des ADRs docs/adr/NNNN-*.md en collision avec dev). En cas de conflit Git (409), la résolution est assistée par LLM sur les trois versions (base, ours, theirs) pour les fichiers non sensibles et obligatoirement validée par le Sandbox Stage 1 avant commit, avec escalade needs-human en cas d'échec ou de chemin sensible. Éviter : ouvrir une PR intermédiaire plan/* -> dev bloquée par les Rulesets de dev, écraser les entrées GLOSSARY.md ajoutées par une autre issue concurrente, ou commiter une résolution de conflit LLM sans vérification Stage 1.
Continuation événementielle de CI externe (waiting_ticket_ci / waiting_feature_ci / /epure continue) : Persistance dans refs/epure/state/<issue> de la sous-phase d'attente CI (subphase, active_ticket_number, active_task_branch, active_pr_number, active_head_sha) dès la publication de la Pull Request (task/* -> feature/* ou feature/* -> dev) et du check ai-review, suivie de la terminaison immédiate du job GitHub Actions (exit 0) pour libérer le runner pendant l'exécution de la CI externe sur chaque sous-ticket et sur la branche de fonctionnalité, puis réveil par événement (check_suite: completed / workflow_run: completed ou commande /epure continue) pour fusionner, enchaîner le ticket suivant ou exécuter un round de remédiation unifié. Éviter : maintenir un runner GitHub Actions actif en attente passive (sleep) pendant l'exécution des workflows CI externes au risque d'atteindre le plafond de 60 minutes, ou désactiver la CI externe sur les sous-tickets task/*.
Auditeur de spécification Goldfish zéro-contexte (runGoldfishSpecAudit) : Évaluation indépendante de la spécification lors de /epure to-spec (inspirée du modèle Google Elephant-Goldfish) par une session isolée dépourvue de l'historique conversationnel du grill, inspectant uniquement spec_markdown, glossary_markdown, adrs et les fichiers cibles du dépôt selon trois axes (auto-suffisance de compréhension, sobriété Zoom-Out / YAGNI, et Implementation Readiness), suivie d'une passe d'amendement automatique par l'Éléphant avant publication sur plan/*. Éviter : transmettre l'historique des commentaires du grill à l'auditeur de spécification (biais de confirmation de l'Éléphant) ou laisser des décisions implicites uniquement dans les commentaires de l'issue.
Hiérarchie de réutilisation et plancher de sécurité Ponytail 5 (Ponytail 5 Safety Floor) : Règle de discipline de code et de revue (standards-reviewer) imposant (1) l'échelle de priorité de réutilisation (code existant du dépôt -> bibliothèque standard/plateforme -> dépendance déjà installée -> code minimal lisible), (2) la mise à jour complète de tous les appelants, tests et exports impactés (Caller-Reach), et (3) l'interdiction absolue de supprimer une validation aux frontières de confiance, une gestion d'erreur critique, un contrôle de sécurité ou d'accessibilité pour raccourcir le code. Éviter : golf de code sacrifiant un garde-fou de sécurité ou création d'un composant sur mesure lorsqu'un équivalent existe déjà dans le dépôt ou la plateforme.
Outils d'exploration Web publics confinés (web_search / web_fetch) : Outils LLM sans clé API tierce ni abonnement payant interrogeant des sources publiques en lecture seule (DuckDuckGo HTML Lite, GitHub Search API, npm, PyPI, crates.io, MediaWiki), restreints à https:// sur le port 443 avec blocage anti-SSRF strict des adresses IP privées/loopback/link-local/cloud-metadata et encapsulation systématique dans <untrusted_web_content>. Éviter : autoriser des requêtes HTTP non chiffrées ou vers des IPs internes (127.0.0.0/8, 169.254.169.254, RFC1918), transmettre des secrets du runner à des domaines tiers, ou exposer les outils Web pendant la revue multi-agents de PR.
Langage technique contrôlé ASD-STE100 (STE100 Controlled Prompting) : Contrat de rédaction technique dérivé de la norme aéronautique ASD-STE100 appliqué aux prompts système, spécifications, ADRs et critères d'acceptation de tickets d'EPURE, imposant cinq invariants : (1) bijection lexicale stricte avec GLOSSARY.md (1 terme = 1 concept, interdiction des synonymes listés sous _Éviter_), (2) voix active avec acteur grammatical explicite, (3) atomicité procédurale (1 phrase = 1 action), (4) conditionnelles déterministes (QUAND / SI <condition>, ALORS <acteur> DOIT <action>) sans verbe modal flou, et (5) formulation affirmative couplée à Zero-Filler et Auto-Clarity. Éviter : style télégraphique ambigu omettant le sujet de l'action, synonymes libres hors glossaire, voix passive sans acteur (« les fichiers sont vérifiés »), ou modaux flous (« devrait », « pourrait », « si nécessaire »).
Graphe relationnel GitHub, garde-fous d'intégrité et convergence multi-phases (ADR-0032)
Graphe relationnel GitHub natif (sub_issues / dependencies/blocked_by / Tasklist d'issue) : matérialisation dans l'interface GitHub de la hiérarchie parent-enfant entre l'Issue de pilotage et chaque Ticket d'implémentation (sub_issues), des Dépendances bloquantes entre tickets (dependencies/blocked_by référençant l'identifiant numérique de base de données du ticket bloqueur) et d'une liste de tâches Markdown délimitée dans le corps de l'Issue de pilotage, appliquée de manière tolérante aux pannes sans remplacer la Référence Git d'état d'orchestration. Éviter : limiter le graphe de tickets à du texte brut non cliquable ou faire échouer l'orchestration si un endpoint relationnel GitHub renvoie une erreur cosmétique.
Garde-fou d'intégrité inter-tickets (validateTicketIntegrityGuard) : contrôle déterministe exécuté avant toute publication sur une Branche de ticket qui interdit (1) la suppression ou le vidage non autorisé de fichiers de test existants sur la branche de base, (2) la troncature de plus de 30 % des lignes ou symboles publics d'un fichier existant hors du périmètre déclaré du ticket, et (3) la dégradation des commandes de vérification (build, test, lint, typecheck, check) dans les manifestes du dépôt en commandes factices ou alias de tests unitaires. Éviter : autoriser un ticket à supprimer les tests d'un ticket précédent ou à remplacer une commande de compilation par un echo.
Réconciliation sémantique et monotone des ADRs (renumberCollidingAdrs / reconcileAdrsWithLlm) : mécanisme combinant la déduplication déterministe par slug (docs/adr/NNNN-<slug>.md), la renumérotation monotone avec suppression des anciens chemins dupliqués et une passe LLM structurée de cohérence croisée lorsque des ADRs concurrents apparaissent sur dev, alignant les références ADR-NNNN dans les spécifications et le glossaire. Éviter : créer des triplons d'un même ADR sous plusieurs numéros successifs lors des synchronisations inter-branches ou laisser des décisions contradictoires sans mise à jour des références croisées.
Contrat de convergence de fonctionnalité (EpicGoalContract) : engagement vérifiable produit dès la spécification d'une Issue de pilotage, déclarant de façon agnostique le résultat observable de bout en bout (epic_goal_summary), les points d'entrée du dépôt qui doivent exposer ou câbler la fonctionnalité (required_entrypoints), les simulacres interdits en production (forbidden_stubs) et les scénarios d'intégration transversaux (end_to_end_verification_criteria). Éviter : spécifier uniquement des briques isolées sans déclarer les points d'entrée applicatifs où elles doivent être branchées.
Audit de convergence de fonctionnalité zéro-contexte (runEpicConvergenceAudit) : évaluation indépendante exécutée sur la Branche de fonctionnalité après l'intégration de tous les tickets d'une phase et avant l'ouverture de la Pull Request vers dev, dans une session LLM isolée dépourvue de l'historique conversationnel des tickets et dotée d'outils d'exploration en lecture seule, qui vérifie le câblage effectif des required_entrypoints, l'absence de forbidden_stubs et la couverture intégrale du Contrat de convergence de fonctionnalité. Éviter : ouvrir la Pull Request finale feature/* -> dev sur la seule foi de tests unitaires par ticket alors que des modules restent non câblés (« island code »).
Phase de convergence corrective (Phase 2 de tickets / epic_phase) : seconde vague bornée de Tickets d'implémentation ([Phase 2 - Ticket N]) générée, chaînée nativement sur GitHub et exécutée automatiquement par l'orchestrateur lorsque l'Audit de convergence de fonctionnalité zéro-contexte conclut qu'une Branche de fonctionnalité est incomplète (verdict: "INCOMPLETE") et que le nombre de phases exécutées est inférieur au plafond configuré (max_epic_phases, fixé à 2 par défaut). Éviter : boucler indéfiniment sans plafond de phases ou laisser à l'humain la charge de diagnostiquer des oublis de câblage évidents entre tickets.
Non-convergence après phases maximales (epic_convergence_exhausted) : raison d'Escalade humaine (needs-human) déclenchée lorsque l'Audit de convergence de fonctionnalité zéro-contexte détecte encore des modules non câblés, des simulacres interdits ou des critères non satisfaits après l'exécution du nombre maximal autorisé de phases (max_epic_phases). Éviter : présenter une Pull Request feature/* -> dev incomplète comme prête pour validation humaine ou masquer les écarts de convergence restants.
Mutation incrémentale d'espace de travail et repli segmenté des tickets (ADR-0033)
Tampon de mutation incrémentale de ticket (StagedTicketImplementationBuffer) : espace de travail transactionnel en mémoire accumulant les créations (write_repo_file), modifications chirurgicales (patch_repo_file) et suppressions (delete_repo_file) effectuées par le modèle au fil de la boucle d'outils d'un Ticket d'implémentation, isolé de l'état de la Branche de fonctionnalité jusqu'à la fin du tour et soumis intégralement à validateWorkspaceFileOperations, validateTicketIntegrityGuard et à la Vérification locale de pré-publication (Stage 1) avant tout commit sur task/*. Éviter : écriture directe non vérifiée sur la branche Git pendant un appel d'outil, pollution de accumulatedFiles en cas d'échec du tour, ou obligation de répéter dans le JSON final les fichiers déjà écrits via outils.
Repli segmenté fichier par fichier (ChunkedTicketImplementationFallback) : décomposition automatique d'un appel d'implémentation ou de remédiation de ticket en sous-appels ciblés par fichier de filesToTouch (suivis d'un lot de tests unitaires) lorsque l'appel initial échoue par troncature (MAX_TOKENS) ou renvoie une Sortie structurée par schéma vide, conservant les mutations déjà validées dans le Tampon de mutation incrémentale de ticket et abandonnant l'intégralité du tampon sans commit partiel si un sous-appel échoue encore après ses relances de validation. Éviter : escalade immédiate needs-human dès la première troncature d'un ticket multi-fichiers ou publication d'un commit partiel non vérifié sur task/*.
Catalogue compact de contexte de dépôt (CompactWorkspaceFilesContext) : représentation bornée des fichiers connus du dépôt dans le prompt d'implémentation ou de remédiation, qui injecte intégralement (sans jamais tronquer un fichier en son milieu) uniquement les fichiers déjà modifiés par le ticket ou ciblés par filesToTouch dans la limite du budget de prompt, et expose tous les autres fichiers sous forme d'un index chemin (N lignes) consultable à la demande via read_repo_file et search_in_repo_file. Éviter : réinjecter l'intégralité de accumulatedFiles en texte brut à chaque tour de remédiation ou tronquer arbitrairement un fichier source en son milieu.
Pipeline événementiel des workflows et cloisonnement des secrets par environnements (v1.7.0)
Pipeline événementiel des workflows et Custom Actions (epure-ci-actions-flow) : architecture d'orchestration GitHub Actions reliant les événements déclencheurs (issue_comment, check_suite, workflow_run, pull_request, workflow_dispatch), le contrôle d'autorisation préalable sans secret (actions/authorize-command), l'exécution isolée sous environnement GitHub d'agent (actions/orchestrate-issue sous environment: <llm-env>), les portes de contrat PR (actions/epure-contract, actions/impeccable) et la promotion de release (environment: release). Éviter : exposer les secrets d'agent ou de LLM à l'étape d'autorisation initiale ou aux workflows de Pull Request non privilégiés.
Cloisonnement des secrets par environnements GitHub (environnement d'agent <llm-env> et environnement release) : séparation stricte des secrets d'exécution d'agent (EPURE_AGENT_APP_ID, EPURE_AGENT_APP_PRIVATE_KEY, LLM_API_KEY ou variable fournisseur configurée dans .github/agents.yml, associés à un environnement GitHub dédié dont le nom est libre et agnostique du fournisseur LLM — epure-agent par défaut (clé llm_environment de .github/agents.yml, setup-repo --llm-env), autres exemples : llm, openai, anthropic, gemini — requis uniquement après authorize-command) et des secrets de promotion stable (EPURE_RELEASE_APP_ID, EPURE_RELEASE_APP_PRIVATE_KEY associés à l'environnement protégé release avec approbation humaine obligatoire), garantissant zéro exposition de secrets aux workflows publics (conformité Zizmor). Éviter : stocker les clés privées de GitHub App ou les clés API LLM comme secrets globaux du dépôt accessibles à tous les jobs.
`), garantissant une source unique de vérité sans aucune duplication (Q102).
Orchestration du développement semi-automatisé
Vocabulaire métier du pilotage de développement par issues, décisions, branches, validations et agents.
Demandes et décisions
Issue de pilotage : demande principale qui rassemble le dialogue de clarification, les décisions et le périmètre d'une fonctionnalité. Éviter : ticket d'implémentation, pull request.
Plan approuvé : périmètre, critères d'acceptation et graphe de tâches autorisés par un humain pour exécution autonome, sous conditions définies. Éviter : brouillon, simple proposition.
Ticket d'implémentation : unité de travail issue d'un plan approuvé, réalisable et vérifiable séparément. Éviter : issue de pilotage, décision architecturale.
Dépendance bloquante : relation empêchant un ticket de devenir exécutable tant qu'un autre n'est pas résolu conformément au plan. Éviter : lien de parenté, simple référence.
Changement de périmètre : modification significative des exigences, des choix architecturaux ou des dépendances au-delà de l'autorisation du plan approuvé. Éviter : correction technique interne au périmètre.
Architecture cible : ensemble des décisions architecturales acceptées, qu'elles soient déjà réalisées ou non. Éviter : architecture effective.
Architecture effective : organisation et comportement réellement présents dans une version déterminée du code. Éviter : architecture cible.
Acteurs et contrôles
Contributeur autorisé : utilisateur disposant de la permission GitHub effective write ou supérieure sur le dépôt cible, vérifiée au moment de la demande ou de la transition privilégiée. Seule cette permission permet le déclenchement des agents. Éviter : author_association, contributeur historique ou simple ouverture d'issue/PR comme preuve de droit.
Contribution externe : issue ou PR ordinaire soumise par une personne sans permission write ; acceptée comme contribution publique mais jamais comme autorisation d'exécuter des agents ou du code avec secrets privilégiés. Éviter : déclencheur LLM, instruction d'administration.
Revue indépendante : évaluation d'un changement par un agent distinct de celui qui l'a produit, à partir de la spécification et du code soumis. Éviter : autovalidation de l'agent d'implémentation.
Validation automatisée : ensemble des contrôles requis pour déclarer une contribution éligible à une intégration sans approbation humaine individuelle. Éviter : validation humaine d'intégration.
Validation humaine d'intégration : approbation par une personne autorisée de l'intégration d'une fonctionnalité complète dans la branche de développement partagée. Éviter : revue automatisée d'un ticket.
Exception sensible : changement dont le niveau de risque exclut l'intégration automatique, même si les contrôles automatisés sont concluants. Éviter : ticket ordinaire.
Escalade humaine : passage d'un ticket ou d'un plan à l'état technique suspended (label needs-human) requérant une décision ou action humaine avant reprise vers active. Se distingue du Plan annulé (cancelled), qui désactive toute exécution ultérieure. Éviter : échec définitif, annulation, crash silencieux du runner.
Unités d'intégration
Branche de fonctionnalité : branche regroupant les changements de tous les tickets d'une demande approuvée avant l'intégration humaine à la branche de développement partagée. Éviter : branche de ticket, branche stable.
Branche de ticket : branche isolant le changement d'un ticket jusqu'à son intégration à la branche de fonctionnalité. Éviter : branche de fonctionnalité.
Intégration de ticket : admission d'une contribution dans la branche de fonctionnalité après réussite des contrôles automatisés et absence d'exception sensible. Éviter : intégration de fonctionnalité.
Intégration de fonctionnalité : admission d'une branche de fonctionnalité dans la branche de développement partagée après validation humaine. Éviter : intégration de ticket, release.
Intégration sérialisée : traitement ordonné des intégrations de tickets dans une même branche de fonctionnalité, même lorsque leur développement a lieu en parallèle. Éviter : développement séquentiel.
Release : promotion d'un état validé du développement partagé vers la version stable. Éviter : intégration de ticket, intégration de fonctionnalité.
Sécurité et autonomie
Exécuteur d'agent : composant qui réalise une phase de travail autonome sans disposer des droits de publication privilégiés sur GitHub. Éviter : éditeur GitHub, contrôleur de permissions.
Éditeur privilégié : composant qui applique à GitHub des opérations préalablement autorisées et validées, à l'aide d'une identité technique temporaire. Éviter : agent d'implémentation, agent de planification.
Gestion financière externe du LLM : facturation, crédits, éventuels plafonds financiers et quotas de dépense gérés par le fournisseur LLM ou la clé API, sans comptabilité ni budget monétaire dans dev-automation. Éviter : budget de ticket, budget de fonctionnalité, coût calculé en CI.
Garde-fou opérationnel d'agent : limite technique d'exécution appliquée par dev-automation (nombre de tentatives, concurrence, timeout), sans prétendre garantir un coût monétaire. Éviter : plafond de dépense LLM, limite de facturation fournisseur.
Agent de migration : agent chargé de proposer les changements nécessaires à la compatibilité d'une mise à jour de dépendance, sans décider lui-même de sa promotion en développement partagé. Éviter : gestionnaire de dépendances, bot de publication.
PR de visibilité : pull request ouverte en brouillon pour rendre visible une fonctionnalité encore incomplète, sans autoriser son intégration. Éviter : PR prête à intégrer.
Documentation et livraison
Contrôleur de dispatch : logique versionnée dans dev-automation et exécutée par un workflow partagé dans le dépôt appelant, qui authentifie l’auteur de l’événement, contrôle les transitions et délègue aux exécuteurs autorisés (Q21 révisée). Éviter : code expérimental de dev, agent qui exécute des tests non fiables.
Release à déclenchement humain : workflow workflow_dispatch lancé par un humain autorisé qui vérifie une révision figée de dev, avance main uniquement par fast-forward, puis crée le tag et la GitHub Release sur cette même révision. Les actions Git restent automatisées ; leur lancement ne l'est pas. Éviter : push Git manuel obligatoire, promotion automatique au merge dans dev.
Hotfix stable : correctif urgent préparé et validé manuellement pour main, puis réintégré dans dev avant la prochaine promotion fast-forward. Éviter : release sélective de dev, réécriture forcée des branches.
Release intégrale : promotion de l'intégralité du SHA validé de dev, sans sélectionner certains commits ou tickets ; si nécessaire, le comportement non publiable demeure désactivé par des feature flags. Éviter : cherry-pick sélectif d'une feature au moment de la release.
ADR approuvé : décision architecturale acceptée par un humain et intégrée d'abord à dev, puis incluse dans main lors d'une release. Éviter : architecture effective, décision seulement proposée.
Référence documentaire : commit Git immuable contenant les ADR, glossaire et spécification auxquels un ticket est tenu de se conformer. Éviter : dernière version implicite ou non qualifiée.
Promotion fast-forward : déplacement du pointeur de main sur un commit descendant de son SHA actuel, sans commit de fusion ou réécriture d'historique. Éviter : action GitHub « Rebase and merge », qui recrée les commits.
Révision de release : SHA précis de dev sur lequel portent l'approbation humaine, les contrôles et l'avancement de main. Éviter : nom mouvant de branche sans contrôle de SHA.
Réconciliation : relecture déterministe des objets GitHub et correction des états incomplets ou des opérations interrompues, de façon idempotente. Éviter : nouvelle exécution aveugle d'une opération déjà produite.
Plan annulé : plan désactivé pour toute nouvelle exécution et intégration automatique, sans destruction de ses traces ni branches existantes. Éviter : plan terminé, plan suspendu après échec.
Workflow appelant : workflow du dépôt applicatif qui reçoit un événement (par exemple issue_comment) et invoque un Reusable Workflow versionné de dev-automation via workflow_call ; les jobs s’exécutent pour le dépôt appelant. Éviter : relais repository_dispatch obligatoire, exécuteur central implicite.
Dépôt d’automatisation (EPURE) : dépôt public Giskard-AI/epure (Engineered Planning, Unified Review & Execution / Élaboration de Plans, Usinage, Revue et Exécution), indépendant des releases applicatives, qui distribue les workflows réutilisables, Custom Actions, politiques et skills (Q21 révisée, Q81, ADR-0008). Éviter : service hébergé central qui consomme les secrets et quotas des utilisateurs.
Reusable Workflow : workflow GitHub exposé via workflow_call, déclarant une orchestration multi-jobs, les préconditions, permissions et secrets attendus ; exécution sur les ressources du dépôt appelant. Éviter : Custom Action mono-étape, exécution centralisée.
Custom Action : composant GitHub Actions autonome référencé par son action.yml, exécuté comme étape d’un job appelant et héritant de son contexte de sécurité. Éviter : frontière d’isolation entre agents et secrets.
Interface publique V1 : contrat versionné et documenté des Reusable Workflows et des Custom Actions ; les modifications incompatibles requièrent une nouvelle version majeure. Éviter : bibliothèque interne sans garantie de compatibilité.
Mise en service d’un dépôt consommateur
GitHub App du consommateur : application enregistrée et détenue par l’utilisateur ou l’organisation qui adopte dev-automation, installée sur les seuls dépôts sélectionnés et utilisée pour émettre des jetons d’installation temporaires. Elle n’est pas administrée par le mainteneur de dev-automation. Éviter : GitHub App partagée du mainteneur, jeton personnel permanent.
Skill de configuration d’un dépôt : procédure interactive et versionnée, distribuée par dev-automation, qui aide à vérifier les prérequis, enregistrer/installer la GitHub App du consommateur, configurer les variables et secrets locaux, installer workflows et politiques, puis vérifier l’installation. Les opérations sensibles nécessitent l’action ou l’accord de l’administrateur concerné. Éviter : service d’installation hébergé, émission automatique de secrets sans contrôle du propriétaire.
Agent App : GitHub App possédée par le consommateur, réservée aux opérations de développement (issues, branches, commits, PR), sans autorité de promotion d'une release. Éviter : Release App, token d'administration générale.
Release App : GitHub App distincte réservée au workflow humain de promotion dev → main, à la création de tags et de releases. Éviter : Agent App, jeton de développement.
Bootstrap local : première installation de dev-automation dans un dépôt consommateur par un skill exécuté localement, avant que la CI agents ne soit opérationnelle. Éviter : installation déclenchée depuis une issue non authentifiée.
Configuration d'agents par dépôt : fichier .github/agents.yml déclarant les choix locaux autorisés (harness, modèles, limites), dont aucune valeur ne peut abaisser les restrictions du workflow partagé. Éviter : secrets en clair, dérogation de sécurité locale.
Installation idempotente : procédure pouvant être rejouée sans duplication ni écrasement intempestif, précédée d'une inspection et proposant un mode --dry-run. Éviter : réinitialisation aveugle de la configuration.
Distribution et garde-fous (ronde 8)
Référence immuable de workflow/action : SHA Git complet du dépôt dev-automation utilisé pour charger un workflow ou une Custom Action, dont la mise à jour est proposée par une PR Renovate. Éviter : tag mutable v1 présenté comme immuable.
Sandbox de code non fiable : environnement qui empêche des processus lancés sur du code potentiellement hostile de lire les credentials et secrets des agents, publisher ou release. Éviter : simple masquage de logs, action composite considérée comme frontière de sécurité.
Merge automatique conditionnel : merge d'une PR task/* → feature/* après vérification de la CI, de la review IA, de la base d'intégration courante et de l'absence de changement sensible. Éviter : intégration directe sur dev, validation sur une base obsolète.
Contrôle financier fournisseur : limite financière qui peut être fournie par le prestataire LLM (compte, organisation, clé API). Elle n'est pas garantie par dev-automation et peut être indisponible selon le prestataire. Éviter : garantie de plafond global par le workflow, compteur financier GitHub.
Échec transitoire du fournisseur LLM : indisponibilité ou coupure temporaire d'une API (5xx, 408, timeout/coupure réseau) permettant une reprise bornée avec backoff (max_transient_api_retries, comptabilisé par requête HTTP unitaire et non cumulé sur l'ensemble d'une boucle d'outils). Les répétitions réseau/API ne consomment pas le quota de trois corrections de code d'un ticket. Éviter : recommencer sans borne, masquer une panne persistante, mutualiser un unique compteur de reprises sur 20 tours d'outils.
Temporisation de limite de débit LLM (429) : attente automatique lors d'une limitation temporaire de débit (HTTP 429 hors épuisement de quota/facturation) respectant l'indication Retry-After du fournisseur (ou un délai progressif par défaut plafonné à 300 secondes, jusqu'à 10 attentes par requête HTTP), suivie d'une relance sans consommer le quota max_transient_api_retries ni le quota de corrections de code du ticket. Éviter : décompter une pause de rate-limit 429 comme un échec serveur ou attendre indéfiniment sans plafond de sécurité.
Blocage fournisseur LLM : problème de clé, de crédits ou de quota empêchant la poursuite des tâches dépendantes ; signalement GitHub et suspension sans changement automatique de clé ou de fournisseur. Éviter : fallback automatique contournant les plafonds définis par l'utilisateur.
Reprise après suspension (suspended -> active) : réactivation idempotente d'une issue de pilotage ou d'un ticket en état suspended (needs-human) lorsqu'un contributeur autorisé (write ou supérieur) publie une réponse ou relance la commande de phase correspondante, retirant le label needs-human, restaurant le statut active tout en conservant la phase courante (grilling, spec, tickets, implementation) et reprenant au dernier jalon validé. Éviter : bloquer définitivement une issue suspendue après une panne API temporaire ou écraser la phase d'orchestration lors de la suspension.
Épuisement des tentatives de remédiation (remediation_exhausted) : atteinte du plafond de corrections automatisées d'un ticket ou d'une branche de fonctionnalité (max_code_fix_attempts, fixé à 3 par ADR-0012), que l'échec provienne des tests en sandbox isolée, de la revue multi-agents ou de la CI externe, entraînant une escalade humaine. Éviter : confusion avec un dépassement du budget d'horloge du runner (wall_clock_budget_exhausted) ou code d'escalade parallèle non typé.
Réponse LLM invalide après relance corrective (llm_request_invalid) : rejet non transitoire d'une requête LLM (HTTP 400) ou sortie structurée violant encore les invariants du schéma après les relances correctives avec rétroaction de l'erreur de validation ; déclenche une escalade humaine sans consommer le quota de corrections de code du ticket. Éviter : qualifier une sortie invalide d'échec réseau transitoire ou relancer à l'aveugle sans transmettre l'erreur de validation au modèle.
Refus du modèle LLM (llm_refusal) : réponse Anthropic terminée par stop_reason: refusal, signalée par une LLMError de reasonCode REFUSAL ; non relancée, elle déclenche une escalade humaine sans consommer le quota de corrections de code du ticket. Éviter : traiter un refus comme une sortie structurée invalide (llm_request_invalid) ou relancer la même requête.
Configuration de modèle manquante (model_config_missing) : absence d'entrée model sur l'action et d'au moins une clé models.planning, models.implementation ou models.review dans .github/agents.yml ; détectée par resolvePhaseModels (MissingModelConfigError) uniquement sur les commandes appelant un LLM, avant tout appel, et escaladée en needs-human en nommant la ou les clés à renseigner. Aucun modèle de repli n'est substitué, conformément au principe d'absence de bascule automatique de l'ADR-0012. Éviter : modèle par défaut implicite, qualifier l'erreur d'échec d'authentification ou de quota fournisseur.
Orchestration des conversations et des reviews (ronde 9)
État de conversation versionné : documents et décisions intermédiaires d'un entretien conservés dans plan/*, distincts des commentaires GitHub qui servent d'interface humaine. Éviter : dépendance à la mémoire du runner, relecture intégrale systématique des commentaires.
Exécution ordonnée par issue : protocole garantissant une exécution active au maximum pour chaque issue et le traitement/dédoublonnage des commentaires suivants. Éviter : jobs concurrents publiant des décisions contradictoires sur une même issue.
Review IA liée au SHA : verdict portant sur une version exacte de la branche source et le diff réellement examiné ; tout changement du code revu invalide ce verdict. Éviter : review positive réutilisée après modification du code.
Politique de base obsolète (strict / relaxed) : politique par dépôt. strict impose une base actuelle ; relaxed tolère une source en retard sans conflit si le diff approuvé est inchangé et la CI réussit sur son intégration à la dernière cible. Éviter : « pas de conflit Git » considéré seul comme test d'intégration.
Résultat combiné : arbre Git résultant de l'intégration d'une PR à la révision courante de sa branche cible, utilisé par les tests d'intégration avant fusion. Éviter : seuls tests de la branche source avec une cible antérieure.
Traçabilité d'exécution d'agent : métadonnées GitHub associant rôle d'agent, modèle, révision de dev-automation et lien du run aux opérations effectuées. Éviter : publication de secrets ou de données sensibles des prompts.
Validation GitHub et interventions humaines (ronde 10)
GitHub Check ai-review : résultat de review IA publié par l'Agent App sur le SHA analysé, pouvant devenir un contrôle obligatoire de protection de branche. Son producteur autorisé fait partie de sa validité. Éviter : commentaire « LGTM » comme preuve de review, check homonyme émis par un autre acteur.
Merge Queue native : mécanisme GitHub, lorsqu'il est disponible, qui met en file les PR et contrôle leur intégration avec les changements précédents. Sinon, le contrôleur réalise une sérialisation et une validation équivalentes à son niveau sans contourner les règles GitHub. Éviter : supposer la disponibilité sur chaque dépôt public personnel.
Correction par nouveau commentaire : modification d'une décision de planning au moyen d'un commentaire ultérieur, plutôt que par édition rétroactive d'une réponse déjà traitée. Éviter : réinterprétation silencieuse des décisions archivées.
Intervention humaine sur une branche de ticket : commit produit par un contributeur autorisé sur task/*, autorisé mais invalidant les contrôles anciens liés à un SHA ou à un diff obsolètes. Éviter : traiter une ancienne review positive comme valable après une correction humaine.
Déclenchements délégués et maintenance des dépendances (ronde 12)
Autorisation déléguée d'un plan : permission humaine enregistrée pour un ensemble précis d'opérations et de tickets approuvés ; les événements internes peuvent poursuivre ce plan sans devenir de nouvelles approbations. Chaque opération vérifie l'autorisation et l'état courant avant exécution. Éviter : considérer n'importe quel événement GitHub App ou workflow comme un mandat général.
Migration Renovate automatique (auto_migrate) : option administrateur permettant à un agent de proposer des correctifs sur une PR Renovate dont la CI échoue, en consultant les guides de migration ; n'autorise pas à merger vers dev sans approbation humaine. Éviter : exécuter avec secrets le code d'une PR non vérifiée, utiliser une PR arbitraire comme déclencheur.
Migrations, releases et moteurs d’agent (ronde 13)
Provenance Renovate vérifiée : identité de l’application et origine de la PR reconnues par GitHub, plus correspondance avec le dépôt et la branche cible attendus ; condition nécessaire à auto_migrate. Éviter : inférence depuis un titre, label ou nom de branche.
Diagnostic d’échec CI : détermination de la cause probable (régression de code, rupture de compatibilité, infrastructure, cause incertaine) avant toute tentative de modification. Éviter : faire modifier le code par un agent à chaque job rouge.
Release SemVer : promotion humaine fast-forward de dev vers main, suivie de la création contrôlée d’un tag vMAJOR.MINOR.PATCH et d’une GitHub Release sur le même SHA. Éviter : tag déplaçable librement, release déclenchée directement par un agent, rebase and merge appelé fast-forward.
Adaptateur de moteur d’agent : composant implémentant une interface stable de pilotage et de résultats pour un moteur d’agent comme Pi ou Codex, indépendamment de sa CLI. Éviter : exposer dans tout l’orchestrateur les formats propriétaires d’un moteur donné.
Garde-fous de fin d'entretien (ronde 14)
Événement interne autorisé : événement technique produit dans la poursuite d'un plan préalablement approuvé et vérifié par l'orchestrateur ; il n'accorde aucune permission supplémentaire. Éviter : interpréter une réponse de bot comme une commande d'un humain.
Review IA indépendante : évaluation d'une révision par une session distincte de l'agent d'implémentation, avec spec, diff et tests, sans accès aux raisonnements internes de ce dernier ni pouvoir de merge. Éviter : autoprobation par l'implementer, réutilisation d'une review pour un nouveau SHA.
Blocage de fonctionnalité après régression : suspension persistante des merges automatiques vers une branche feature/* lorsqu'une intégration y provoque une régression constatée ; reprise après correction et nouveaux contrôles satisfaisants. Éviter : force-push de réparation, poursuite aveugle des autres merges.
CI minimale requise : ensemble de checks adaptés au dépôt, réellement configurés comme obligatoires avant tout merge automatique de ticket ; l'existence d'un workflow ou d'un check IA seul n'est pas suffisante. Éviter : intégrer automatiquement sur la seule base d'une review IA verte.
Licence et évaluation des agents (Q56–Q58)
Licence du projet (Apache-2.0) : licence choisie pour le code original de dev-automation, permettant la réutilisation commerciale et privée avec obligations de préservation des notices et licence explicite sur les brevets couverts. Éviter : prétendre relicencier en bloc des fichiers tiers ou imposer cette licence aux dépôts consommateurs.
Attribution des composants tiers : conservation des textes de licence, avis de copyright et NOTICE applicables aux contenus effectivement copiés ou redistribués, avec référence à leur provenance et révision. Éviter : assimiler une dépendance installée à une copie embarquée, ou supprimer les mentions MIT/Apache d'origine.
Impeccable (intégration optionnelle) : ensemble de skills et contrôles spécialisés frontend proposé via une Custom Action publique et un skill d'assistance ; activable par dépôt selon sa technologie. Éviter : déclencher systématiquement des contrôles UI sur des dépôts purement backend, ou leur accorder des permissions privilégiées sans nécessité.
iFixAi (intégration optionnelle) : outil d'audit des événements/trajectoires et de tests comportementaux, utilisé prioritairement pour évaluer la sécurité de dev-automation ; l'audit des traces complète sans remplacer l'application de la politique d'autorisation. Éviter : faire du score d'audit un substitut à la séparation des privilèges ou imposer un appel LLM sur chaque PR applicative.
Qualité visuelle et audits (Q59–Q61)
Check de design obligatoire par défaut : check CI Impeccable installé comme contrôle requis des PR frontend et désactivable par choix explicite du dépôt. Le seuil des constats bloquants reste à spécifier. Éviter : audit visuel systématique de dépôts sans interface, « informatif » par défaut.
Trajectoire d'audit minimisée : suite structurée d'événements, permissions et transitions, limitée aux métadonnées vérifiables nécessaires à l'évaluation d'iFixAi, sans secrets ni logs internes complets. Éviter : journal de prompts non filtré, stockage de credentials.
Conception frontend intégrée (Q62–Q65)
Entretien UX/UI unifié : extension de l'issue de pilotage après grill-with-docs utilisant le cadrage Impeccable shape, avec réutilisation des décisions existantes. Éviter : ouvrir une deuxième conversation de conception déconnectée du plan approuvé.
Prototype exploratoire : représentation légère d'une interaction ou interface importante, produite avant approbation sur prototype/* avec données fictives ; captures et informations de prévisualisation liées à l'issue. Éviter : assimiler le prototype à du code prêt à merger automatiquement sur dev.
Contexte produit (PRODUCT.md) : document versionné décrivant utilisateurs, besoins et contraintes produit, distinct des spécifications d'une fonctionnalité. Éviter : confondre contexte produit durable et exigences d'un ticket.
Système de design (DESIGN.md) : document versionné de conventions et choix UX/UI, distinct des décisions propres à un écran (.impeccable/surfaces/*.md). Éviter : règles visuelles contradictoires dispersées dans les prompts d'agents.
Violation de design bloquante : problème nouveau qui correspond soit aux règles bloquantes par défaut d'Impeccable (accessibilité vérifiable, cassures de layout/overflow, non-respect des tokens définis, états d'interaction obligatoires manquants), soit à une règle supplémentaire ajoutée dans DESIGN.md ou .impeccable/surfaces/*.md, identifié par le check CI et empêchant le merge tant qu'il n'est pas corrigé ou explicitement exempté. Éviter : bloquer une PR sur une préférence esthétique subjective ou sur l'ensemble du passif visuel non modifié.
Prévisualisation et transfert design → implémentation (Q66–Q69)
Artifact de prévisualisation : capture, rapport ou fichier HTML produit par une CI et accessible depuis la page du run ou ses artifacts, sans hébergement externe requis. Éviter : assimiler des fichiers HTML complexes à un site navigable servi par un hébergeur.
Preview statique GitHub Pages : publication facultative de prototypes HTML/CSS/JS fictifs et non sensibles accessibles par URL ; une prévisualisation isolée par issue nécessite une stratégie de répertoires/versionnement et de nettoyage. Éviter : supposer une preview native par PR ou y intégrer des secrets et des données privées.
Prototype non réutilisable : code exploratoire produit pour valider un comportement ou une direction UX, sans transfert direct dans le code applicatif final. Seuls les choix design, critères d'acceptation et actifs de référence constituent des entrées pour l'implémentation. Éviter : cherry-pick, copie ou merge automatique du code de prototype/*.
Approbation du graphe de tickets : autorisation humaine donnée après production de la spec et des tickets dépendants ; elle délimite le périmètre exécutable par les agents. Éviter : transformer une approbation d'une simple maquette en autorisation implicite de construire tout le plan.
Modes de prévisualisation complémentaires (Q66 confirmé) : GitHub Actions artifacts/captures, GitHub Pages pour prototypes statiques si configuré, et environnement de preview préexistant du projet. Aucun de ces modes ne nécessite que dev-automation héberge un serveur central. Éviter : rendre obligatoire un hébergeur tiers ou publier par défaut un prototype sensible sur un site public.
Déclenchement des prototypes et hébergement (Q71–Q73)
Détour de prototypage fondé sur une question : branche facultative du flux grilling/ask-matt quand un comportement d'état ou un choix visuel ne peut être validé par la conversation ; prototype traite une question précise et handoff transfère les apprentissages. Impeccable shape complète l'exploration UX, sans règle arbitraire de complexité. Éviter : générer un prototype pour chaque issue frontend ; transformer le code exploratoire en code applicatif.
Rétention de preview hébergée : durée de vie par défaut de 14 jours, configurable par dépôt, suivie d'une suppression automatisée. Éviter : confondre suppression des previews accessibles publiquement et suppression des décisions documentées.
Isolation de preview publiée : séparation effective entre prototype et site de production, avec interdiction de publier secrets et données personnelles. Un simple sous-chemin d'une origine partagée n'est pas une isolation de sécurité suffisante. Éviter : supposer que /previews/42/ peut exécuter du JavaScript non fiable sans risque sur le même domaine que la production.
Publication Pages sur consentement (Q70) : possibilité pour setup-repo d’activer GitHub Pages pour des previews statiques uniquement après accord explicite de l’utilisateur ; configuration désactivée par défaut. Sans activation, les artifacts et captures restent la référence. L’activation exige une séparation du site de production (Q73) et la rétention configurable de 14 jours (Q71). Éviter : publier par défaut des prototypes sur le domaine de production ou assimiler un sous-chemin à une origine isolée.
Isolation d'exécution, état Git hors branches et gouvernance EPURE (Q74–Q83)
Proxy LLM de sandbox (Q74) : processus sidecar local sur le runner GitHub Actions qui détient seul en mémoire la clé API LLM et les tokens d'installation, tandis que l'agent et les sous-processus de test/build du dépôt consommateur s'exécutent dans un conteneur isolé dépourvu de secrets dans ses variables d'environnement. Éviter : injecter OPENAI_API_KEY ou ANTHROPIC_API_KEY directement dans l'environnement où s'exécutent npm test, pytest ou les hooks postinstall.
Traitement en lot des commentaires avec curseur (last_processed_comment_id, Q75) : mécanisme par lequel un job sérialisé par concurrency: issue-<N> lit à son démarrage tous les commentaires humains postés depuis le dernier identifiant traité et les intègre séquentiellement, empêchant toute perte d'événement lorsque la file d'attente GitHub Actions compresse les runs en attente au-delà de deux événements. Éviter : se fier uniquement au payload github.event.comment du webhook déclencheur ou activer cancel-in-progress: true.
Référence Git d'état d'orchestration (refs/epure/state/<issue-number>, Q76) : référence Git dédiée hors branches standard (refs/heads/*) stockant l'état machine d'orchestration (curseur last_processed_comment_id, mandat de plan approuvé avec spec_sha, approved_by, statut active|cancelled, compteurs de tentatives par ticket) avec compare-and-swap atomique Git, doublée d'un tableau de bord Markdown lisible synchronisé dans le corps de l'issue GitHub. Éviter : polluer l'historique des branches applicatives dev et main avec des commits JSON d'état machine ou utiliser uniquement un commentaire d'issue sujet aux écrasements concurrents.
Orchestration réelle multi-fournisseurs (LLMClient) et Publisher GitHub App (Q84–Q90)
Continuité implicite de l'entretien de grill et de la révision de spécification (Q84) : traitement automatique de tout commentaire humain posté sur une issue de pilotage dont la référence refs/epure/state/<issue-number> est en phase grilling (réponse au grill ou ajustement de la synthèse) ou en phase spec (demande de révision des artefacts de spécification sur plan/<issue>-<slug>) sans imposer de répéter une commande slash à chaque tour. Éviter : rejeter les réponses humaines ordinaires sous prétexte qu'elles ne commencent pas par /epure.
Validation humaine de la frontière de Grill (Q85) : passage de l'issue de pilotage en phase grilling avec statut awaiting_human_approval dès que la frontière de l'arbre de décisions est vide (frontier_resolved: true), publiant la synthèse structurée des décisions actées et attendant l'approbation humaine explicite via /epure to-spec (ou un commentaire libre pour rouvrir un round de grill) avant toute rédaction documentaire. Éviter : enchaîner automatiquement la fin du grill avec la génération de la spécification ou la création des sous-issues sans validation humaine de la synthèse de cadrage.
Validation humaine de la spécification (Q85) : séparation explicite entre /epure to-spec (qui génère et commite GLOSSARY.md, docs/adr/NNNN-*.md, docs/specs/<slug>.md et DESIGN.md sur plan/<issue>-<slug>, puis passe l'issue en phase spec / awaiting_human_approval où tout commentaire libre révise la spécification) et /epure to-tickets (qui découpe la spécification validée en un DAG acyclique de tickets GitHub ready-for-agent avec blocked_by et passe l'issue en phase tickets / awaiting_human_approval en attente de /epure approve). Éviter : créer les sous-issues GitHub dès /epure to-spec avant que l'humain ait pu relire et valider la spécification sur plan/<issue>-<slug>.
Jeton d'installation GitHub App éphémère (Q87) : jeton court obtenu en signant un JWT RS256 avec EPURE_AGENT_APP_ID et EPURE_AGENT_APP_PRIVATE_KEY puis en appelant l'API d'installation GitHub du dépôt cible, utilisé par le publisher isolé pour créer branches, commits, tickets, PRs et checks, puis révoqué immédiatement. Éviter : exposer la clé privée PEM au processus agent ou partager un PAT personnel permanent.
Gouvernance Rulesets, Roster de Review Multi-Agents et Squash Sémantique par IA (Q91–Q96)
Séparation des trois Rulesets de gouvernance (epure-feature-governance, epure-dev-governance, epure-release-immutability, Q91 & Q95) : découpage explicite des règles GitHub Repository Rulesets en trois périmètres distincts (refs/heads/feature/* avec Agent App en bypass PR pour le squash-merge autonome des tâches validées et l'intégration directe des artefacts plan/* -> feature/* ; refs/heads/dev exigeant un merge humain dans l'interface GitHub pour toute PR feature/* -> dev, avec required_approving_review_count: 0 par défaut pour la compatibilité mainteneur solo et configurable via --require-pr-approvals <N> ; refs/heads/main et refs/tags/v* réservés à Release App). Éviter : mutualiser dev et feature/* dans un unique Ruleset qui autoriserait l'Agent App à fusionner du code applicatif dans dev sans validation humaine, ouvrir une PR intermédiaire plan/* -> dev bloquée par le Ruleset de dev, ou bloquer un mainteneur solo sur ses propres PRs.
Roster de reviewers spécialisés et transverses (reviewers_dir, Q92 & Q93) : ensemble de définitions de rôles d'audit en lecture seule (<nom>.md) initialisé par setup-repo dans le répertoire du roster du dépôt consommateur, configurable via la clé reviewers_dir de .github/agents.yml ou setup-repo --reviewers-dir <chemin> (.agents/reviewers/ par défaut) (spécialistes domain-backend-reviewer, frontend-reviewer, infra-reviewer ; transverses architecture-reviewer, security-reviewer, spec-parity-reviewer, standards-reviewer, accessibility-reviewer, design-reviewer ; et user-advocate), enrichi lors de /epure plan avec les personas et invariants du domaine, mais toujours chargé à l'exécution depuis la branche de base de confiance (dev) avec repli sur les templates embarqués d'EPURE, et classé comme chemin sensible interdisant toute auto-modification sur task/*. Éviter : charger un prompt de reviewer depuis la branche non fiable task/* inspectée (risque d'auto-approbation par injection de prompt), lier le roster au répertoire propre à un IDE donné, ou dépasser le plafond de 4 reviewers pertinents sélectionnés par diff.
Porte UX orientée personas (user-advocate, modes design-gate et implementation-review, Q96) : sous-agent évaluant le produit selon les personas d'utilisateurs finaux propres au domaine ; intervient d'abord en mode design-gate à l'issue du Grill sur plan/* (conjointement à DESIGN.md) pour enrichir les critères d'acceptation UX des tickets avant /epure approve, puis en mode implementation-review (conjointement au check impeccable-gate) comme contrôle bloquant sur les PRs touchant l'interface. Éviter : reporter toute la validation UX et d'accessibilité après le codage ou ignorer les impasses de parcours multi-rôles.
Synthèse de message de squash sémantique par IA (Q94) : génération juste avant chaque squash-merge, par un modèle léger à température nulle inspectant le diff consolidé de la PR, d'un titre Conventional Commit (type(scope): summary (#PR)) synchronisé sur la PR et d'un corps concis listant les changements effectifs, en utilisant Refs #<ticket> lors de l'intégration task/* -> feature/* et Closes #<issue> / Closes #<ticket> uniquement lors de l'atterrissage sur la branche par défaut dev. Éviter : conserver des messages de commits intermédiaires de debug dans l'historique de feature/* ou dev, ou supposer que Closes #N sur une branche non-default ferme automatiquement le ticket GitHub.
Taxonomie du flux d'orchestration et documentation bilingue (Q97–Q103)
Portes de validation humaine obligatoires (4 jalons, Q101) : les quatre points de décision où l'intervention explicite d'un contributeur autorisé (write ou supérieur) est indispensable et ne peut jamais être déléguée à un agent : (1) lancement /epure plan et réponses au Grill sur l'issue de pilotage, (2) signature du plan approuvé par /epure approve verrouillant spec_sha dans refs/epure/state/<issue>, (3) validation humaine d'intégration par revue et squash-merge humain de la PR finale feature/* -> dev, et (4) release à déclenchement humain (workflow_dispatch de promotion fast-forward dev -> main). Éviter : autoriser l'Agent App à fusionner du code applicatif dans dev ou main sans décision humaine explicite.
Étapes automatisées obligatoires (Q101) : séquence déterministe exécutée par l'orchestrateur sur chaque fonctionnalité approuvée : génération documentaire sur plan/<issue>-<slug> (GLOSSARY.md, docs/adr/, docs/specs/<slug>.md) et création du graphe de tickets d'implémentation avec blocked_by, boucle TDD en sandbox sans secret (npm test, npm run build, verify-contract), revue indépendante multi-agents chargée depuis dev avec auto-remédiation bornée (max_code_fix_attempts = 3) et intégration sérialisée (task/* -> feature/*) par squash sémantique IA, puis revue de synthèse complète sur la PR finale feature/* -> dev. Éviter : contourner la sandbox sans secret ou intégrer une branche task/* sans revue indépendante liée au SHA.
Étapes facultatives ou conditionnelles (Q101) : opérations activées uniquement selon la nature du changement ou la demande explicite d'un contributeur autorisé : détour exploratoire /prototype (Q72) et preview GitHub Pages isolée (Q70, désactivée par défaut), génération de DESIGN.md + user-advocate (design-gate et implementation-review) + impeccable-gate (Q96, activés automatiquement uniquement lorsque le projet ou le diff comporte une surface UI/frontend), commandes de pilotage granulaire (/epure to-spec, /epure to-tickets, /epure status, /epure cancel), et escalade humaine (needs-human) en cas d'exception sensible ou d'épuisement des trois tentatives de correction. Éviter : imposer les contrôles UI Impeccable ou un prototype exploratoire sur des projets ou tickets purement backend/CLI.
Vérification polyglotte et boucle de CI externe multi-workflows (Q104–Q111)
Profil de vérification polyglotte (verification.targets, Q104 & Q108) : déclaration par sous-projet dans .github/agents.yml (générée par setup-repo et repliée au runtime par inspection hybride des manifestes Node/Python/Rust/Go, des orchestrateurs Makefile/Justfile/Taskfile/turbo.json et de l'ensemble des workflows .github/workflows/*.{yml,yaml} hors EPURE), toujours chargée à l'exécution depuis la branche de confiance (dev) et classée comme chemin sensible sur task/*. Éviter : supposer un unique package.json à la racine, un fichier unique nommé ci.yml, ou autoriser une branche task/* à altérer ses propres commandes de test.
Vérification locale de pré-publication (Stage 1, Q105) : exécution dans un clone Git persistant de la sandbox sans secret, avant tout commit ou ouverture de PR, des commandes d'installation, de génération de code (codegen), de typage statique (typecheck), de lint et de tests unitaires/scripts ne nécessitant aucun conteneur de service externe, ciblées selon les path_patterns des fichiers modifiés. Éviter : retourner un succès par défaut en l'absence de package.json racine ou tenter de démarrer en sandbox locale les services lourds (PostgreSQL, Docker multi-stage) relevant de la CI GitHub Actions.
Porte de CI externe multi-workflows et boucle d'auto-réparation (Stage 3, Q106–Q110) : attente déterministe (avec fenêtre d'amorçage et corrélation des filtres on.pull_request/push sur tous les workflows .github/workflows/*.{yml,yaml} hors EPURE) de la complétude des check-runs et workflow_runs externes sur le head_sha d'une PR, suivie en cas d'échec applicatif de l'extraction assainie des annotations et logs d'erreur (~12 Ko) pour alimenter jusqu'à 3 rondes unifiées de remédiation (Review IA + CI externe), avec relance sans pénalité sur panne transitoire d'infrastructure et réconciliation idempotente des PRs déjà ouvertes. Éviter : fusionner task/* -> feature/* avant la fin des workflows CI externes, considérer zéro check-run à $T+0$ comme un succès, ou gaspiller une tentative de code sur un échec réseau du runner.
Routeur LLM multi-fournisseurs, sorties structurées et ergonomie /epure (ADR-0029)
Routeur LLM multi-fournisseurs (LLMClient) : Client HTTP TypeScript sans dépendance externe (inspiré de giskard-llm) routant chaque appel selon le préfixe <provider>/<model> (openai/, azure/, azure_ai/, google/, gemini/, anthropic/ ou un alias nommé déclaré dans la section providers: de .github/agents.yml avec résolution différée os.environ/VAR_NAME), garantissant l'absence de bascule automatique inter-fournisseurs sur erreur d'authentification ou de quota (ADR-0012). Éviter : coupler l'orchestrateur à un unique fournisseur au runtime, stocker des clés API en clair dans .github/agents.yml, ou basculer automatiquement vers un fournisseur de secours en cas d'erreur 401/402/403.
Sortie structurée par schéma (ResponseSchemaSpec<T>) : Contrat associant un JSON Schema strict (transmis nativement au fournisseur via responseSchema, response_format.json_schema ou output_config.format) et un validateur TypeScript d'exécution, remplaçant toute extraction heuristique de JSON par expression régulière. Sur Google Gemini avec outils d'exploration (tools), le client exécute la boucle d'outils puis déclenche un tour final dédié (functionCallingConfig.mode = "NONE") avec responseSchema activé. Éviter : extraire du JSON par expression régulière depuis du texte libre ou désactiver la validation de schéma lorsqu'une boucle d'outils est active.
Aide-mémoire contextuel des commandes /epure (formatEpureCommandsSpoiler) : Bloc Markdown repliable (<details>) inséré systématiquement au pied des commentaires d'issues, des sous-issues de tickets et des descriptions de Pull Requests générés par EPURE, récapitulant les commandes disponibles (/epure plan, /epure to-spec, /epure to-tickets, /epure approve, /epure continue, /epure sync / /epure rebase, /epure status, /epure cancel / /epure stop) et mettant en évidence la prochaine action attendue selon la phase courante. Éviter : publier des commentaires d'orchestration ou des escalades needs-human sans rappeler à l'opérateur humain les commandes de reprise (/epure continue), de synchronisation Git (/epure sync) ou d'annulation disponibles.
Confinement noyau Ubuntu 26.04, formatage sans état RTK et discipline anti-slop (ADR-0030)
Confinement noyau de sandbox (Stage 1) (SandboxNetworkPolicy / buildKernelSandboxedCommand) : Isolation système au niveau du noyau Linux 7.0 (ubuntu-26.04) en deux phases distinctes pour la vérification locale de pré-publication : (1) la phase install (networkPolicy: "https_only") s'exécute sous landrun (Landlock ABI v8) en restreignant les connexions TCP sortantes au seul port 443 et les écritures au répertoire de travail (workDir), /tmp et aux caches de paquets ; (2) les phases codegen, typecheck, lint, test et build (networkPolicy: "offline") s'exécutent totalement hors-ligne sous bubblewrap (--unshare-net --unshare-pid --unshare-ipc --tmpfs /tmp --die-with-parent), avec repli automatique sur landrun sans aucun port TCP autorisé lorsque les namespaces utilisateurs non privilégiés sont indisponibles. En mode d'exécution d'adaptateur d'agent (networkPolicy: "proxy_only"), landrun restreint le réseau au seul port local du proxy (--connect-tcp <proxyPort>). Éviter : exécuter du code ou des tests de dépôt consommateur sans confinement noyau en CI (EPURE_ENFORCE_KERNEL_SANDBOX=true), autoriser le réseau pendant l'exécution des tests unitaires, ou utiliser des conteneurs privilégiés nécessitant sudo.
Formatage et condensation sans état des sorties de test (RTK) (formatAndCondenseStage1CommandOutput) : Filtrage et nettoyage déterministe des journaux de vérification Stage 1 via rtk (rtk-ai/rtk épinglé et géré par Renovate avec quarantaine de 7 jours) configuré en mode 100 % sans état (tracking.enabled = false, telemetry.enabled = false, retriever.mode = "disabled", RTK_TELEMETRY_DISABLED=1, RTK_RECALL=0, RTK_TEE=0, NO_COLOR=1), supprimant les séquences ANSI, les barres de progression et le bruit des fichiers ignorés sans créer aucune base SQLite d'historique ou d'apprentissage, et conservant automatiquement en mémoire la queue brute d'erreur (4 000 derniers caractères) lorsqu'une commande échoue (exit_code !== 0). Éviter : activer la télémétrie, le suivi analytique SQLite (history.db) ou le magasin recall.db de rtk en CI, ou tronquer la pile d'appels brute d'un test en échec avant de la transmettre au modèle de remédiation.
Synchronisation Git inter-branches, continuation CI événementielle, audit Goldfish et exploration Web (ADR-0031)
Synchronisation inter-branches et résolution de conflits 3-way (syncBranchWithBase / /epure sync) : Rattrapage systématique ou déclenché à la demande (/epure sync, alias /epure rebase) de la branche de base (dev -> feature/* et feature/* -> task/*) combiné à l'intégration directe des artefacts de plan/* dans feature/* (fusion additive déterministe de GLOSSARY.md et renumérotation automatique des ADRs docs/adr/NNNN-*.md en collision avec dev). En cas de conflit Git (409), la résolution est assistée par LLM sur les trois versions (base, ours, theirs) pour les fichiers non sensibles et obligatoirement validée par le Sandbox Stage 1 avant commit, avec escalade needs-human en cas d'échec ou de chemin sensible. Éviter : ouvrir une PR intermédiaire plan/* -> dev bloquée par les Rulesets de dev, écraser les entrées GLOSSARY.md ajoutées par une autre issue concurrente, ou commiter une résolution de conflit LLM sans vérification Stage 1.
Continuation événementielle de CI externe (waiting_ticket_ci / waiting_feature_ci / /epure continue) : Persistance dans refs/epure/state/<issue> de la sous-phase d'attente CI (subphase, active_ticket_number, active_task_branch, active_pr_number, active_head_sha) dès la publication de la Pull Request (task/* -> feature/* ou feature/* -> dev) et du check ai-review, suivie de la terminaison immédiate du job GitHub Actions (exit 0) pour libérer le runner pendant l'exécution de la CI externe sur chaque sous-ticket et sur la branche de fonctionnalité, puis réveil par événement (check_suite: completed / workflow_run: completed ou commande /epure continue) pour fusionner, enchaîner le ticket suivant ou exécuter un round de remédiation unifié. Éviter : maintenir un runner GitHub Actions actif en attente passive (sleep) pendant l'exécution des workflows CI externes au risque d'atteindre le plafond de 60 minutes, ou désactiver la CI externe sur les sous-tickets task/*.
Auditeur de spécification Goldfish zéro-contexte (runGoldfishSpecAudit) : Évaluation indépendante de la spécification lors de /epure to-spec (inspirée du modèle Google Elephant-Goldfish) par une session isolée dépourvue de l'historique conversationnel du grill, inspectant uniquement spec_markdown, glossary_markdown, adrs et les fichiers cibles du dépôt selon trois axes (auto-suffisance de compréhension, sobriété Zoom-Out / YAGNI, et Implementation Readiness), suivie d'une passe d'amendement automatique par l'Éléphant avant publication sur plan/*. Éviter : transmettre l'historique des commentaires du grill à l'auditeur de spécification (biais de confirmation de l'Éléphant) ou laisser des décisions implicites uniquement dans les commentaires de l'issue.
Hiérarchie de réutilisation et plancher de sécurité Ponytail 5 (Ponytail 5 Safety Floor) : Règle de discipline de code et de revue (standards-reviewer) imposant (1) l'échelle de priorité de réutilisation (code existant du dépôt -> bibliothèque standard/plateforme -> dépendance déjà installée -> code minimal lisible), (2) la mise à jour complète de tous les appelants, tests et exports impactés (Caller-Reach), et (3) l'interdiction absolue de supprimer une validation aux frontières de confiance, une gestion d'erreur critique, un contrôle de sécurité ou d'accessibilité pour raccourcir le code. Éviter : golf de code sacrifiant un garde-fou de sécurité ou création d'un composant sur mesure lorsqu'un équivalent existe déjà dans le dépôt ou la plateforme.
Outils d'exploration Web publics confinés (web_search / web_fetch) : Outils LLM sans clé API tierce ni abonnement payant interrogeant des sources publiques en lecture seule (DuckDuckGo HTML Lite, GitHub Search API, npm, PyPI, crates.io, MediaWiki), restreints à https:// sur le port 443 avec blocage anti-SSRF strict des adresses IP privées/loopback/link-local/cloud-metadata et encapsulation systématique dans <untrusted_web_content>. Éviter : autoriser des requêtes HTTP non chiffrées ou vers des IPs internes (127.0.0.0/8, 169.254.169.254, RFC1918), transmettre des secrets du runner à des domaines tiers, ou exposer les outils Web pendant la revue multi-agents de PR.
Langage technique contrôlé ASD-STE100 (STE100 Controlled Prompting) : Contrat de rédaction technique dérivé de la norme aéronautique ASD-STE100 appliqué aux prompts système, spécifications, ADRs et critères d'acceptation de tickets d'EPURE, imposant cinq invariants : (1) bijection lexicale stricte avec GLOSSARY.md (1 terme = 1 concept, interdiction des synonymes listés sous _Éviter_), (2) voix active avec acteur grammatical explicite, (3) atomicité procédurale (1 phrase = 1 action), (4) conditionnelles déterministes (QUAND / SI <condition>, ALORS <acteur> DOIT <action>) sans verbe modal flou, et (5) formulation affirmative couplée à Zero-Filler et Auto-Clarity. Éviter : style télégraphique ambigu omettant le sujet de l'action, synonymes libres hors glossaire, voix passive sans acteur (« les fichiers sont vérifiés »), ou modaux flous (« devrait », « pourrait », « si nécessaire »).
Graphe relationnel GitHub, garde-fous d'intégrité et convergence multi-phases (ADR-0032)
Graphe relationnel GitHub natif (sub_issues / dependencies/blocked_by / Tasklist d'issue) : matérialisation dans l'interface GitHub de la hiérarchie parent-enfant entre l'Issue de pilotage et chaque Ticket d'implémentation (sub_issues), des Dépendances bloquantes entre tickets (dependencies/blocked_by référençant l'identifiant numérique de base de données du ticket bloqueur) et d'une liste de tâches Markdown délimitée dans le corps de l'Issue de pilotage, appliquée de manière tolérante aux pannes sans remplacer la Référence Git d'état d'orchestration. Éviter : limiter le graphe de tickets à du texte brut non cliquable ou faire échouer l'orchestration si un endpoint relationnel GitHub renvoie une erreur cosmétique.
Garde-fou d'intégrité inter-tickets (validateTicketIntegrityGuard) : contrôle déterministe exécuté avant toute publication sur une Branche de ticket qui interdit (1) la suppression ou le vidage non autorisé de fichiers de test existants sur la branche de base, (2) la troncature de plus de 30 % des lignes ou symboles publics d'un fichier existant hors du périmètre déclaré du ticket, et (3) la dégradation des commandes de vérification (build, test, lint, typecheck, check) dans les manifestes du dépôt en commandes factices ou alias de tests unitaires. Éviter : autoriser un ticket à supprimer les tests d'un ticket précédent ou à remplacer une commande de compilation par un echo.
Réconciliation sémantique et monotone des ADRs (renumberCollidingAdrs / reconcileAdrsWithLlm) : mécanisme combinant la déduplication déterministe par slug (docs/adr/NNNN-<slug>.md), la renumérotation monotone avec suppression des anciens chemins dupliqués et une passe LLM structurée de cohérence croisée lorsque des ADRs concurrents apparaissent sur dev, alignant les références ADR-NNNN dans les spécifications et le glossaire. Éviter : créer des triplons d'un même ADR sous plusieurs numéros successifs lors des synchronisations inter-branches ou laisser des décisions contradictoires sans mise à jour des références croisées.
Contrat de convergence de fonctionnalité (EpicGoalContract) : engagement vérifiable produit dès la spécification d'une Issue de pilotage, déclarant de façon agnostique le résultat observable de bout en bout (epic_goal_summary), les points d'entrée du dépôt qui doivent exposer ou câbler la fonctionnalité (required_entrypoints), les simulacres interdits en production (forbidden_stubs) et les scénarios d'intégration transversaux (end_to_end_verification_criteria). Éviter : spécifier uniquement des briques isolées sans déclarer les points d'entrée applicatifs où elles doivent être branchées.
Audit de convergence de fonctionnalité zéro-contexte (runEpicConvergenceAudit) : évaluation indépendante exécutée sur la Branche de fonctionnalité après l'intégration de tous les tickets d'une phase et avant l'ouverture de la Pull Request vers dev, dans une session LLM isolée dépourvue de l'historique conversationnel des tickets et dotée d'outils d'exploration en lecture seule, qui vérifie le câblage effectif des required_entrypoints, l'absence de forbidden_stubs et la couverture intégrale du Contrat de convergence de fonctionnalité. Éviter : ouvrir la Pull Request finale feature/* -> dev sur la seule foi de tests unitaires par ticket alors que des modules restent non câblés (« island code »).
Phase de convergence corrective (Phase 2 de tickets / epic_phase) : seconde vague bornée de Tickets d'implémentation ([Phase 2 - Ticket N]) générée, chaînée nativement sur GitHub et exécutée automatiquement par l'orchestrateur lorsque l'Audit de convergence de fonctionnalité zéro-contexte conclut qu'une Branche de fonctionnalité est incomplète (verdict: "INCOMPLETE") et que le nombre de phases exécutées est inférieur au plafond configuré (max_epic_phases, fixé à 2 par défaut). Éviter : boucler indéfiniment sans plafond de phases ou laisser à l'humain la charge de diagnostiquer des oublis de câblage évidents entre tickets.
Non-convergence après phases maximales (epic_convergence_exhausted) : raison d'Escalade humaine (needs-human) déclenchée lorsque l'Audit de convergence de fonctionnalité zéro-contexte détecte encore des modules non câblés, des simulacres interdits ou des critères non satisfaits après l'exécution du nombre maximal autorisé de phases (max_epic_phases). Éviter : présenter une Pull Request feature/* -> dev incomplète comme prête pour validation humaine ou masquer les écarts de convergence restants.
Mutation incrémentale d'espace de travail et repli segmenté des tickets (ADR-0033)
Tampon de mutation incrémentale de ticket (StagedTicketImplementationBuffer) : espace de travail transactionnel en mémoire accumulant les créations (write_repo_file), modifications chirurgicales (patch_repo_file) et suppressions (delete_repo_file) effectuées par le modèle au fil de la boucle d'outils d'un Ticket d'implémentation, isolé de l'état de la Branche de fonctionnalité jusqu'à la fin du tour et soumis intégralement à validateWorkspaceFileOperations, validateTicketIntegrityGuard et à la Vérification locale de pré-publication (Stage 1) avant tout commit sur task/*. Éviter : écriture directe non vérifiée sur la branche Git pendant un appel d'outil, pollution de accumulatedFiles en cas d'échec du tour, ou obligation de répéter dans le JSON final les fichiers déjà écrits via outils.
Repli segmenté fichier par fichier (ChunkedTicketImplementationFallback) : décomposition automatique d'un appel d'implémentation ou de remédiation de ticket en sous-appels ciblés par fichier de filesToTouch (suivis d'un lot de tests unitaires) lorsque l'appel initial échoue par troncature (MAX_TOKENS) ou renvoie une Sortie structurée par schéma vide, conservant les mutations déjà validées dans le Tampon de mutation incrémentale de ticket et abandonnant l'intégralité du tampon sans commit partiel si un sous-appel échoue encore après ses relances de validation. Éviter : escalade immédiate needs-human dès la première troncature d'un ticket multi-fichiers ou publication d'un commit partiel non vérifié sur task/*.
Catalogue compact de contexte de dépôt (CompactWorkspaceFilesContext) : représentation bornée des fichiers connus du dépôt dans le prompt d'implémentation ou de remédiation, qui injecte intégralement (sans jamais tronquer un fichier en son milieu) uniquement les fichiers déjà modifiés par le ticket ou ciblés par filesToTouch dans la limite du budget de prompt, et expose tous les autres fichiers sous forme d'un index chemin (N lignes) consultable à la demande via read_repo_file et search_in_repo_file. Éviter : réinjecter l'intégralité de accumulatedFiles en texte brut à chaque tour de remédiation ou tronquer arbitrairement un fichier source en son milieu.
Pipeline événementiel des workflows et cloisonnement des secrets par environnements (v1.7.0)
Pipeline événementiel des workflows et Custom Actions (epure-ci-actions-flow) : architecture d'orchestration GitHub Actions reliant les événements déclencheurs (issue_comment, check_suite, workflow_run, pull_request, workflow_dispatch), le contrôle d'autorisation préalable sans secret (actions/authorize-command), l'exécution isolée sous environnement GitHub d'agent (actions/orchestrate-issue sous environment: <llm-env>), les portes de contrat PR (actions/epure-contract, actions/impeccable) et la promotion de release (environment: release). Éviter : exposer les secrets d'agent ou de LLM à l'étape d'autorisation initiale ou aux workflows de Pull Request non privilégiés.
Cloisonnement des secrets par environnements GitHub (environnement d'agent <llm-env> et environnement release) : séparation stricte des secrets d'exécution d'agent (EPURE_AGENT_APP_ID, EPURE_AGENT_APP_PRIVATE_KEY, LLM_API_KEY ou variable fournisseur configurée dans .github/agents.yml, associés à un environnement GitHub dédié dont le nom est libre et agnostique du fournisseur LLM — epure-agent par défaut (clé llm_environment de .github/agents.yml, setup-repo --llm-env), autres exemples : llm, openai, anthropic, gemini — requis uniquement après authorize-command) et des secrets de promotion stable (EPURE_RELEASE_APP_ID, EPURE_RELEASE_APP_PRIVATE_KEY associés à l'environnement protégé release avec approbation humaine obligatoire), garantissant zéro exposition de secrets aux workflows publics (conformité Zizmor). Éviter : stocker les clés privées de GitHub App ou les clés API LLM comme secrets globaux du dépôt accessibles à tous les jobs.