Le Catalogue des Façades

À quoi sert un catalogue de façades

Le harness agentique du Synedre n'est pas un monolithe : c'est une constellation de petits points d'entrée exécutables — des scripts Python sous synedre/ et des binaires sous bin/. Chacun porte un rôle unique. Le catalogue des façades recense ces points d'entrée avec, pour chacun, sa famille, son rôle en une ligne et son mode d'invocation type. Le but : qu'un ingénieur reprenant le dépôt retrouve rapidement quel script fait quoi, sans relire des centaines de fichiers.

Le principe directeur est simple — un module, une façade. Quand un domaine du système (l'email client, le scan antivirus, le déploiement) doit être touché, il existe un point d'entrée unique et obligatoire. On ne contourne jamais une façade : c'est elle qui porte les garde-fous.

Méthode d'extraction et couverture

Les descriptions du catalogue ne sont pas inventées : elles sont extraites programmatiquement du premier docstring ou commentaire de tête de chaque fichier. Pour le Python, une boucle lit le docstring du module ; pour les binaires bin/*, la première ligne de description non-bannière. Quand un fichier ne porte qu'un en-tête boilerplate (@author / @copyright), le vrai docstring est repêché quelques lignes plus bas. Ce repêchage n'est pas systématique, et la fiabilité de chaque entrée est annotée plutôt que survendue.

La couverture est suivie explicitement : on distingue le total réel de fichiers sur disque du nombre effectivement détaillé dans le catalogue.

Catégorie	Total réel sur disque	Couvert
synedre/*.py	~180	tous listés ou rattachés à une famille
bin/* (entrées exécutables)	~80 entrées	scripts exécutables détaillés ; fichiers de données et caches non détaillés un-à-un

Drift détecté. Une vérification croisée entre le crontab et le contenu réel de synedre/ révèle plusieurs dizaines d'entrées cron mortes : elles pointent vers des fichiers Python supprimés ou renommés. Le catalogue documente cet écart au lieu de le masquer — un catalogue honnête recense aussi ses propres trous. Ces entrées sont à nettoyer.

La légende des invocations

Chaque façade porte un mode d'invocation type. Comprendre ce vocabulaire suffit à savoir comment un script est censé être déclenché.

Code	Signification
cron	Lancé par le scheduler, souvent via un wrapper-watchdog commun
CLI	Appelé à la main en ligne de commande
skill	Façade derrière un skill Claude Code (.claude/skills/<nom>/)
hook	Hook Claude Code (SessionStart / UserPromptSubmit / PreToolUse / PostToolUse / Stop)
lib	Module importé, pas un point d'entrée autonome
worker	Daemon ou boucle drainant une file en base

Le socle commun et la couche de données

Toutes les familles convergent vers une base de données unique, accédée exclusivement à travers une façade Python PostgreSQL. Aucun script ne parle à la base en direct : il passe par cette façade, qui centralise la connexion, et par une façade d'environnement qui charge les variables de configuration. Les secrets vivent dans des fichiers d'environnement hors-dépôt (gitignorés) — jamais en clair dans le code ni dans la documentation.

Au-dessus de cette couche se trouve un socle de façades transverses, partagées par toutes les autres familles.

Façade	Rôle	Invocation
Façade PostgreSQL	Accès Python à la base unique pour tous les automates	lib
Helper connexion sandbox	Connexion base pour les agents en bac à sable	lib
Façade d'environnement	Chargement centralisé des variables de configuration	lib
Logger structuré	Logging obligatoire pour tous les automates	lib
Wrapper cron	Watchdog autonome des automates planifiés	cron
Façade IA	Couche agnostique multi-fournisseurs (embed / complete)	lib
Invocation d'agent	Appeler un agent du Synedre depuis n'importe quel automate	CLI / lib
Filtre PII	Purge les données personnelles avant tout envoi au pipeline LLM	lib

Atlas et l'orchestration

La famille atlas porte le cœur orchestrateur : recevoir un email entrant, classifier son intention (run, chantier, question, bruit), puis agir. Une règle de doctrine encadre l'invocation des agents : un agent est toujours appelé via un terminal pseudo-tty (node-pty) qui capture son flux de pensée pour audit, jamais en mode opaque.

Façade	Rôle	Invocation
Poll inbox	Relève la boîte d'orchestration à intervalle régulier	cron
Classifier d'intent	Classifie l'intention d'un message via LLM	lib / CLI
Spawn	Lance une intelligence headless pour agir sur les messages classifiés	worker
Ship-via-email	Déclenche une mise en production par email, avec triple vérification anti-usurpation	CLI
Monitoring post-ship	Surveille après mise en production, avec rollback automatique unique	cron
Cycle ReAct par tâche	Exécute le cycle raisonnement-action d'une tâche	worker
Détecteur de dérive	Auto-pause les tâches bloquées trop longtemps ou trop coûteuses en tokens	cron
QA post-deploy	Contrôle qualité à deux niveaux après déploiement	cron / CLI

Les chantiers

La famille chantiers matérialise le workflow de création en plusieurs étapes : lire la demande, auditer les agents disponibles, rédiger une lettre de mission, recruter explicitement l'équipe, créer le squelette atomique (chantier + travaux + tâches). La façade officielle « chantier depuis email » exécute ces étapes sous contrainte.

Façade	Rôle	Invocation
Chantier depuis email	Création d'un chantier client à partir d'un email entrant	CLI / skill
Live chantier	Suivi en direct des événements agents sur un chantier	CLI
Lettre de mission	Génère un brouillon de lettre de mission	lib
Auto-explode discovery	Pipeline LLM transformant une découverte en tâches d'implémentation	worker
Estimateur de tokens	Estime le coût en tokens et recommande un modèle par tâche	lib
Détecteur de patterns	Repère les patterns récurrents dans les itérations de tâches	cron
QA de validation	Validation qualité d'un travail par son équipe	worker
Scanner de leads	Détecte les leads entrants depuis les réservations de rendez-vous	cron / skill

Audits, qualité et sécurité

Une famille entière veille sur la santé du système : audits nocturnes des automates, du schéma de base, des dépendances, des backups ; pentest automatisé ; audit d'accessibilité ; monitoring HTTP des sites en production. Le principe : observer en continu, alerter, et n'appliquer un correctif automatique que sous garde-fou strict.

Façade	Rôle	Invocation
Audit des automates	Audit nocturne de tous les automates	cron
Audit du schéma	Audit quotidien du schéma de base vs convention de nommage	cron
Surveillance des backups	Vérification quotidienne des sauvegardes de base	cron
Test de restauration	Test mensuel de restaurabilité d'un dump de base	cron
Pentest	Pentest automatisé	CLI / skill
Audit d'accessibilité	Audit WCAG 2.2 AA	CLI
Monitoring uptime	Monitoring HTTP des sites en production	cron
QA gate (relecture)	Verdict heuristique de relecture qualité (go / avec réserves / no-go)	CLI
Audit infra	Audit infra unifié vaisseau-mère et tenants	CLI / skill
Audit OSS-safety	Scan du cœur OSS contre toute fuite de lexique propre à un tenant	CLI
Smoke test multi-tenant	Test de fumée des sites, échec si réponse HTTP en erreur serveur	CLI

Mémoire, cicatrices et apprentissage

Cette famille porte la boucle d'apprentissage du système : récolte des cicatrices depuis l'historique git, requalification par LLM, injection des cicatrices actives au démarrage de session via des hooks, consolidation mémoire nocturne, et recall sémantique par recherche vectorielle. La mémoire vit sur trois niveaux — mémoire de travail, second cerveau Zettelkasten, mémoire sémantique vectorielle — mais la base de données reste la seule source de vérité.

Façade	Rôle	Invocation
Récolte de cicatrices	Récolte automatique des cicatrices depuis l'historique git	cron
Requalification de cicatrices	Reclassification LLM par lots des cicatrices	cron
Injection au démarrage	Hook reconnectant la mémoire active en début de session	hook
Injection avant outil	Hook injectant les cicatrices avant exécution d'un outil	hook
Leçon post-chantier	Drafte une rétrospective pédagogique après un chantier	CLI / skill
Consolidation nocturne	Consolidation de la mémoire pendant la nuit	cron
Recall sémantique	Recherche vectorielle retrouvant la note pertinente	CLI / skill
Indexation du second cerveau	Indexe le Zettelkasten dans la base sémantique	cron
Suivi du contexte	Estimation du budget contexte consommé en session	lib / skill
Hard-floor immuable	Chargement et validation du manifest des blocs P0 immuables	lib / skill

Inbox et email client

Une règle dure gouverne cette famille : l'intelligence n'envoie jamais directement un email à un client. Tout passe par une façade email unique, en deux temps — un brouillon, puis un envoi explicite après validation humaine. Un hook bloque toute tentative d'utiliser un client SMTP en direct. Les identifiants de boîte vivent dans un fichier d'environnement hors-dépôt ; leurs valeurs n'apparaissent nulle part dans le code ni la documentation.

Façade	Rôle	Invocation
Email client	Workflow d'envoi : brouillon, relecture, envoi, archivage	CLI (façade unique)
Garde façade email	Hook imposant la façade email obligatoire	hook
Sync inbox	Relève la boîte de réception vers la base	cron
Inbox direct	Connexion directe au serveur de mail, en repli d'urgence	CLI / skill
Scan antivirus PJ	Façade de scan des pièces jointes avant ouverture	CLI / skill
Ton de voix	Résolution du registre de rédaction par lead ou client	lib
Sync rendez-vous	Synchronise les réservations vers le pipeline CRM	cron
Alerte de coût	Vérifie le cumul mensuel d'API LLM contre le budget	cron

Blog, SEO et contenu

La famille contenu porte la publication DB-first : moteur de publication, nettoyage d'articles, génération de couvertures et de carrousels, surveillance des doublons SEO, génération de descriptions produit, et une sous-famille de traductions FR → EN (et DE) couvrant l'interface, le contenu de base et les fiches produit.

Façade	Rôle	Invocation
Moteur de publication	Publication DB-first d'articles	CLI / skill
Hygiène blog	Nettoyage automatique des articles	cron
Générateur de couvertures	Génère les images de couverture d'articles	cron / CLI
Générateur de carrousels	Produit des carrousels sociaux au format carré	CLI
Radar de cannibalisation	Détecte les doublons et quasi-doublons SEO	cron
Générateur de fiches produit	Rédige les descriptions de produits	CLI
Traduction de contenu	Complète les champs FR-only en EN dans la base	CLI

Agents navigateur

Une famille pilote Playwright pour les automatisations web. Sa doctrine de protection est instructive : un proxy SOCKS traite la réputation d'adresse mais pas la détection comportementale du navigateur ; certaines actions exigent donc un navigateur visible sur une machine résidentielle. La classification de la protection précède toujours le code du flux.

Façade	Rôle	Invocation
Agent navigateur	Automate Playwright avec sortie résidentielle via proxy	lib
Worker navigateur	Worker à navigateur visible sur machine résidentielle	worker
File de jobs navigateur	Interface de la file de jobs navigateur	CLI
Capture d'écran	Capture des pages via Chromium headless	CLI / lib
Scan de flotte	Scan de la flotte de sites	cron / CLI

Banque, facturation et finance

La famille finance couvre la synchronisation bancaire, l'import de relevés avec anti-doublons, la facturation récurrente et les relances, ainsi que le suivi des correctifs de production. Les opérations d'écriture sur une base de production passent par un wrapper sécurisé dédié.

Façade	Rôle	Invocation
Sync bancaire	Point d'entrée cron du domaine banque	cron / skill
Import de relevé	Parse un export bancaire avec dédoublonnage	CLI / skill
Facturation récurrente	Cron quotidien de facturation récurrente	cron
Relances	Cron quotidien de relances et rapprochement	cron

Déploiement, ship et infra

Cette famille incarne la règle dure d'asymétrie entre déployer et mettre en production. ./deploy est toujours le travail de l'intelligence : elle déploie en préprod sans demander. ./ship est la mise en production, geste manuel exclusif du Fondateur — l'intelligence n'y touche jamais. Sur le vaisseau-mère lui-même, déployer signifie un rebuild en direct, sans préprod. Et avant tout déploiement, on committe : les modifications non committées sont perdues au rebuild.

Façade	Rôle	Invocation
Helpers de déploiement	Fonctions communes aux scripts de déploiement	lib
Validation deploy.yaml	Parse et valide la config de déploiement	lib
Vérification git propre	Vérifie que l'arbre git est propre avant déploiement	CLI
Write SQL sécurisé en prod	Wrapper sécurisé pour toute écriture SQL en production	CLI
Bootstrap tenant	Initialise un nouveau tenant depuis le template	CLI
Provisioning	Provisionne automatiquement une machine pour un client	CLI
Health check post-ship	Contrôle de santé et rollback automatique après mise en production	CLI
Sauvegarde chiffrée	Backup chiffré des fichiers critiques vers stockage objet	cron / CLI
Restore depuis stockage	Restauration d'une base depuis une sauvegarde objet	CLI

Les hooks Claude Code

Au-delà des familles ci-dessus, un sous-système entier vit dans des fichiers de configuration de hooks. Les hooks câblent les façades aux moments-clés du cycle de vie d'une session : démarrage, avant et après chaque outil, soumission de prompt, et fin de session.

Moment	Rôle du hook
SessionStart	Réinitialise le suivi de contexte, charge le brief de session, injecte la mémoire active
PreToolUse:Bash	Garde-fou écriture en production, façade email obligatoire, injection des cicatrices
PreToolUse:Edit|Write	Injection des cicatrices avant modification de fichier
PreToolUse:Agent	Injection des cicatrices avant invocation d'agent
PostToolUse	Tracking automatique du contexte, log des cycles ReAct, télémétrie agent
Stop	Libération des locks de chantier, garde-fou git-clean (bloque si l'arbre git n'est pas propre), cascade de synchronisation chantier

Le garde-fou « git non committé au moment du Stop » est ce qui matérialise la doctrine de commit en flux : aucun travail terminé ne reste non committé. Le hook bloque la fin de session tant que l'arbre n'est pas propre.

Notes de fiabilité

Un bon catalogue est honnête sur ses limites. Trois réserves accompagnent celui-ci :

• Les scripts dont le seul en-tête était du boilerplate ont vu leur vrai rôle repêché plus bas dans le fichier — aucun rôle n'a été inventé, et les cas incertains sont annotés.
• La colonne « invocation » mélange du certain (présence vérifiée dans le crontab) et de l'inféré (mention « cron quotidien » lue dans un docstring). Pour la vérité d'ordonnancement, seul l'examen direct du scheduler fait foi.
• Le mapping skill ↔ façade est sourcé des fiches de skill, qui n'ont pas toutes été ouvertes une à une : à confirmer au cas par cas.

C'est l'esprit du catalogue : recenser fidèlement, signaler le drift, et ne jamais survendre la certitude.