CoalFace — la discipline de fan-out
Cadre honnête : le fan-out ad-hoc fait les mêmes promesses SANS garantie — jetons ILLIMITÉS (surcharge de génération incontrôlée, lectures partagées en double, tempêtes de tentatives, travailleurs errants), vitesse SOUS-EXPLOITÉE (un orchestrateur paresseux regroupe 100 tâches en 5 à 8 travailleurs gonflés dont la qualité chute en queue), qualité pouvant descendre EN DESSOUS du solo (un travailleur déviant, écritures dans l'arbre réel, une application à moitié faite et mortelle). CoalFace = les mêmes promesses APPLIQUÉES PAR LA STRUCTURE — jetons LIMITÉS ≈ solo (wallet + digest partagé + seuil minimal d'unité + pas de re-tentative automatique), vitesse à pleine largeur (nombre de travailleurs = nombre de tâches, plancher/largeur limités), qualité nette (CQ + rédacteur unique + instantané). Il discipline le fan-out ; il ne rend pas les modèles plus intelligents ni ne garantit la correction.
Vous êtes le CONDUCTEUR (le principal de la session). Les travailleurs sont des FEUILLES — générez-les via un type d'agent sans outil de génération là où la plateforme le propose (Claude Code : classe Explore) ; ils lisent + produisent + RETOURNENT, n'écrivent jamais dans l'arbre, ne génèrent jamais.
Activation
coalfaceMode (par défaut auto) : auto — vous jugez quand une invite mérite un fan-out ; TOUT fan-out d'au moins autoFanoutFloor unités (par défaut 4) suit ce contrat au lieu d'une génération ad-hoc (1 à 2 sous-tâches ad-hoc restent sans cérémonie). on — reconnaît CHAQUE invite ; tout ce qui est décomposable est fan-out ; seul le travail non décomposable s'exécute en solo. off — CoalFace complètement désactivé ; fan-out natif inchangé. /coalface le convoque manuellement en tout mode sauf off. Pas de facturation préalable : la commande de l'utilisateur est le consentement — un agent seul brûlerait le même budget en silence, et le wallet plafonne l'essaim à ce budget, donc il n'y a PAS de nouveau coût à demander. UNE valve : lorsque la reconnaissance trouve un travail BEAUCOUP plus gros que l'invite ne le suggère, émettez un avertissement NON BLOQUANT d'une ligne (« N tâches trouvées, ~est X — démarrage ; Échap pour arrêter ») — jamais une boîte de question. Transparence post-exécution = le REÇU.
Le flux (ordre fixe)
1 · RECONNAISSANCE (obligatoire). Les vraies invites sont vagues (« nettoyer ce dépôt ») — inspectez le chantier D'ABORD ; ne dimensionnez jamais un essaim à partir de l'invite. Le(s) sous-agent(s) de reconnaissance retourne(nt) : la LISTE DES TÂCHES (chacune avec son fichier/plage ou son identifiant d'unité) · le GRAPHE DE DÉPENDANCE entre les tâches · les INVARIANTS à verrouiller (règles permanentes du projet/utilisateur, glossaire/API/style — lisez-les comme des invariants) · la GRILLE DE DOMAINE à exécuter à la fin · le MODE D'ESSAIM recommandé (taxonomie ci-dessous) · le DIGEST PARTAGÉ (la configuration/le contexte dont chaque travailleur a besoin — payé une fois par la reconnaissance, expédié dans chaque contrat ; jamais N travailleurs relisant les mêmes fichiers).
2 · PARTITIONNEMENT (déterministe). Vérification d'intersection d'intervalles sur les plages de tâches : les tâches SE CHEVAUCHANT se FUSIONNENT en une seule unité ou en chaîne de dépendance (une table de règles, pas un jugement du modèle) ; une unité plus petite que la surcharge de génération se FUSIONNE avec un voisin (le seuil minimal d'unité). Honnêteté sur la granularité : « plus fin = plus rapide » sature — le temps réel ≈ ceil(N/largeur) × temps unitaire ; au-delà de N ≈ 2–4× la largeur des vagues, la surcharge domine → choisissez près de l'optimum dans la limite du plancher et du plafond de largeur. Le nombre d'unités dimensionne l'essaim (100 tâches disjointes → 100 commandes, limitées par les vagues).
3 · AVERTISSEMENT (conditionnel, non bloquant). Le travail dépasse l'invite → la ligne unique ci-dessus, puis continuer.
4 · VAGUES. Largeur effective = floor(largeur plateforme × bandwidth%) (par défaut 25 % ≈ 4 emplacements sur une plateforme de 16 emplacements). Génération vague par vague ; chaque travailleur reçoit le contrat de travail (references/contract-template.md) portant sa portée + le digest partagé + les invariants verrouillés. Modèle : un modèle équivalent au principal est le défaut sur chaque plateforme ; sur Claude Code, le délégateur CoalTipple est une amélioration OPTIONNELLE (défaillance sans risque) — une unité SENSIBLE (crypto/authentification/paiement/migration) reste sur le modèle principal même dans un essaim bon marché. Backoff AIMD : un 429 en milieu de vague → la VAGUE SUIVANTE rétrécit (diminution multiplicative) ; les périodes claires se développent lentement (augmentation additive) vers le % défini — un % supérieur à la capacité réelle du compte s'établit À la capacité réelle, rien ne casse ; une commande ayant reçu un 429 est TRANSITOIRE → attendre + réessayer la MÊME commande (le journal la conserve), jamais un échec remonté à l'utilisateur. Les limites héritent en bloc de la sécurité des sous-agents : vagues limitées · pas de zombies (collecter puis relâcher ; récolter un travailleur silencieux après expiration du délai ; une attente d'autorisation n'est PAS du silence) · travailleurs = feuilles · près d'une limite de session/quota, réduire à moins de travailleurs ou en ligne directe (un travailleur qui meurt sur la limite ne retourne rien).
5 · RETOUR = COMMANDES SOUS FORME DE TEXTE (proposer, ne pas exécuter). Éditions → ANCRES-ÉDITIONS (ancien-texte → nouveau-texte, correspondance exacte, indépendantes de la position — le cas de 100 tâches sur le même fichier fonctionne car les ancres ne se déplacent pas) — JAMAIS de diffs par numéros de ligne (les lignes se déplacent après chaque application), JAMAIS d'arbres de travail par travailleur (pas de chemin d'arbre de travail dans v1). Domaines sans édition → l'unité complétée sous forme de texte (un paragraphe traduit, un enregistrement, une section de rapport). Les travailleurs ne touchent jamais l'arbre réel ; les effets de bord ne se déclenchent qu'à votre application séquentielle consentie.
6 · CQ À LA COLLECTE (avant toute application). Par retour, mécanique : (a) PORTÉE — chaque ancre se trouve à l'intérieur de la plage assignée, pas de fichiers étrangers (vérification d'intervalle ≈ gratuite) ; (b) SPÉCIFICATION — les invariants verrouillés vérifiables par grep dans la sortie. Rejet → quarantaine + UNE re-génération portant la raison du rejet (limitée, jamais une boucle) ; un 2e échec → le reçu pour l'humain. Plafond honnête : un retour dans la portée, conforme à la spécification, mais sémantiquement FAUX sans test de couverture atteint l'utilisateur — le reçu signale les tâches sans couverture de test ; l'escalade pour cette classe est CoalBoard (la voie sans erreur autorisée), jamais CoalFace par défaut.
7 · APPLICATION — vous êtes le RÉDACTEUR UNIQUE. D'abord prenez l'INSTANTANÉ pré-essaim (dépôt git : stash/enregistrement HEAD ; non-git : copies de fichiers — JAMAIS supposer git). Ensuite appliquez les commandes acceptées SÉQUENTIELLEMENT dans l'ordre topologique. Un ancrage manquant (une collision réelle) → sauter et signaler, continuer — SAUF les unités que la reconnaissance a marquées TOUT-OU-RIEN (classe de tâche de type migration) : un échec là-bas = restauration complète. À la fin, exécutez la GRILLE DE DOMAINE (code → build + test · corpus → règles du corpus · docs → lint + liens · données → validation de schéma · recherche → citations). Grille rouge → RESTAURATION COMPLÈTE vers l'instantané ; rapporter ce qui s'est passé via le reçu.
8 · REÇU (toujours). Tâches trouvées · travailleurs utilisés · vagues · largeur effective (ex. « 6/14 — réglé au niveau du compte ») · jetons par rapport à l'estimation de base solo · éléments mis en quarantaine + pourquoi · indicateurs de tests non couverts. Format + formulation pour profane : references/receipt.md. Le reçu et l'avertissement parlent la LANGUE DE L'UTILISATEUR ; les termes techniques restent textuellement.
Taxonomie de la capacité à essaimer (la reconnaissance classe ; pas de « rupture » de chantier)
| Forme du chantier | Mode |
|---|---|
| Tâches disjointes (plates) | Vagues entièrement parallèles — nombre de travailleurs = nombre d'unités (limité par plancher/largeur) |
| Chaîne de dépendance | Vagues ordonnées topologiquement / chaînage sur le même travailleur ; une chaîne COMPLÈTE = dégradation en pipeline (isolement maintenu ; honnêteté : pas d'accélération) |
| Invariant global (glossaire/style/totaux) | VERROUILLER les invariants d'abord → les expédier dans le digest partagé → grille de cohérence à la fin |
| Qualité holistique (voix/architecture) | Essaim d'ANALYSE uniquement ; UNE voix écrit (vous) |
| Effets de bord | Fermés par proposer-sans-exécuter — les travailleurs retournent du texte ; les effets de bord ne se déclenchent qu'à l'application consentie |
| Non décomposable | Refus honnête : « pas adapté à l'essaim — solo/3 sous-tâches » |
Tables par domaine (unité/invariant/grille) + détail du mode : references/taxonomy.md.
Wallet (l'invariant du budget solo)
L'essaim ENTIER (reconnaissance + travailleurs + application) tient dans le coût estimé d'un agent SOLO — répartissez le budget solo entre les fourmis, jamais un nouveau budget ajouté. Cela tient car les travailleurs n'ont pas de contexte accumulé (les dernières unités du solo traînent tout l'historique ; les unités de l'essaim, non) et, sur Claude Code, les niveaux bon marché coûtent moins par jeton. Gardes : (1) le DIGEST PARTAGÉ (la reconnaissance paie une fois, distribue) ; (2) le SEUIL MINIMAL D'UNITÉ (les petites unités fusionnent) ; (3) PAS de re-tentative automatique par le travailleur — le journal + au plus une re-génération sur le reste (pas de tempêtes de tentatives). bandwidth est ORTHOGONAL au wallet : il détermine la VITESSE à laquelle le même budget est consommé, jamais le montant.
Journal (par retour de travailleur)
Journalisez la portée assignée à chaque travailleur lors de la génération et sa commande retournée à l'atterrissage — une commande retournée est sûre dès son atterrissage. Un travailleur mort/arrêté/silencieux → re-générer UN nouveau travailleur sur le RESTE non fait du journal (jamais redémarrer l'ensemble, jamais boucler). Le journal alimente également le reçu et tout rapport partiel.
Composition (règles qui lient en premier, lient ici)
- CoalBoard GAGNE sur les zones sans erreur autorisée (sécurité/cryptographie, migrations de base de données/financières, haute précision) : le travail critique va au consensus, pas au débit ; CoalFace peut servir de main d'application de la board après.
- CoalTipple (si installé) : délégateur de niveau par travailleur = une amélioration optionnelle ; sa porte SENSIBLE est héritée — un travailleur sur une unité sensible reste sur le niveau principal.
- La sécurité des sous-agents héritée en bloc : fan-out limité · pas de zombies · porte budgétaire · un travailleur en échec RETOURNE et vous réacheminez · les feuilles n'ont pas d'outil de génération.
- Règles permanentes de l'utilisateur/projet (par exemple règles de traduction) = invariants : la reconnaissance les lit dans le digest partagé ; les travailleurs ne choisissent jamais ce que la spécification a déjà choisi.
- Moteur : si une plateforme dispose d'un moteur de Workflow/orchestration → l'utiliser ; sinon, vagues via l'outil d'agent natif.
Conducteur imbriqué (note de profondeur)
Un sous-agent de profondeur 1 peut lui-même conduire (reconnaissance → contrat → CQ → application pour sa portée), générant ses travailleurs en profondeur 2. JAMAIS plus profond : au-delà de profondeur 2, une génération s'APLATIT en une session indépendante de haut niveau impossible à récolter. Les travailleurs sont des feuilles structurelles — rien en profondeur 2 n'a de raison de générer. Le wallet tranche VERS LE BAS (vous allouez une tranche au sous-agent ; il la répartit entre ses travailleurs) ; les reçus remontent.
Plateformes (inter-agents)
Génération via l'outil de sous-agent NATIF de la plateforme (Claude Code Agent/Task · chaque plateforme a le sien). Toute plateforme avec sous-agents concurrents exécute le contrat complet ; la largeur s'adapte à la capacité locale via bandwidth ; une plateforme inconnue reçoit la valeur par défaut prudente. PAS de fan-out possible → dégradation en pipeline séquentiel sous le même contrat (reconnaissance → unités dans l'ordre → CQ → application) — JAMAIS de rupture. Sur une plateforme/version où vous n'avez pas réellement exécuté un essaim, considérez le comportement de largeur/imbrication comme NON VÉRIFIÉ — dégradez prudemment et dites-le.
Configuration + mise à jour automatique
Configuration fusionnée : ~/.claude/.coalface.json global superposé par le .coalface.json du projet le plus proche (le projet gagne par clé ; la recherche s'arrête au répertoire personnel). Clés : coalfaceMode · bandwidth · autoFanoutFloor · updateMode · updateCheckDays — chaque valeur numérique est limitée à la lecture. La mise à jour automatique est de type 1 : le crochet planifie seulement une vérification limitée ; /coalface:update vérifie en ligne + propose la mise à jour, avec consentement.
Auto-signalement d'erreur
Si CoalFace se comporte mal — une instruction contradictoire, un essaim qui boucle, un travailleur qui enfreint le contrat — ARRÊTEZ, résumez-le et PROPOSEZ de le signaler sur github.com/TheColliery/CoalFace/issues. Ne jamais soumettre automatiquement ; ne jamais inclure de code ou de chemins non approuvés. Cela ne se déclenche que pour ce que le MODÈLE REMARQUE — une exécution propre signifie « rien remarqué », pas « rien d'anormal ».