coalledger

CoalLedger est un outil de qualité documentaire destiné aux agents de codage IA, décrit par son auteur comme le « CoalMine pour la documentation ». Il fait partie de TheColliery, une famille de petites suites d'extensions (CoalMine, CoalTipple, CoalBoard, CoalHearth, CoalFace, CoalWash) qui partagent une doctrine de hooks sans dépendance, de schémas de configuration à source unique, de dépenses soumises à consentement et d'absence de modifications automatiques. CoalLedger peut être installé seul ou avec les autres. Le postulat est que le code dispose de linters, de tests et de CI, tandis que la documentation repose principalement sur l'espoir : un README qui a dérivé du code, une traduction qui ne correspond plus à son original, un lien d'installation mort ou un badge de version obsolète sont des échecs silencieux auxquels le lecteur fait toujours confiance. CoalLedger scanne tout document — README, spécification, rapport, traduction — et compare ce qu'il rend avec ce qu'il affirme. Sept canaris, un mode d'échec chacun : 1. doc-grounding — détecte les affirmations qui ne correspondent pas à leur source de vérité (code, données, texte original, réalité) ; vérifié en temps réel via plusieurs sources, passant à « non vérifié » hors ligne. 2. doc-standard — détecte l'incomplétude par rapport à la norme de ce type de document, y compris les sections requises et les surfaces publiques non documentées. 3. doc-rot — détecte les versions, dates et badges obsolètes, les TODOs morts et les instructions supplantées. 4. doc-consistency — détecte les documents qui se contredisent, la dérive terminologique et la dérive entre langues. 5. doc-structure — détecte les liens, ancres, titres, tableaux, références et textes alternatifs d'images cassés. 6. doc-quality — détecte le superflu, la prose confuse et la mécanique linguistique telle que les fautes de frappe, la grammaire et l'orthographe. 7. doc-leak (protégé par config) — signale le contenu sensible au niveau de la prose dans les documents publics ; les secrets ayant une forme de token sont laissés aux autres outils. Il ne rapporte que les découvertes suspectées. Les scans s'exécutent sur deux niveaux. Le niveau Quick couvre les couches mécaniques déterministes et pratiquement gratuites, et ne fait que rapporter. Le niveau Full ajoute les couches sémantiques, qui utilisent le jugement d'un modèle, sont payantes et nécessitent toujours un consentement distinct. Quatre des canaris combinent couches mécaniques et sémantiques ; doc-consistency et doc-leak sont uniquement sémantiques. Un moteur AST CommonMark+GFM intégré et sans dépendance alimente les vérifications structurelles afin que le contenu qui s'affiche correctement ne soit pas signalé ; l'auteur précise que son plafond de fidélité est au niveau des spécifications, et non un rendu GitHub au pixel près, et les particularités de l'hôte sont rapportées comme des limites plutôt que devinées. La sévérité est toujours jugée en contexte plutôt que mécaniquement : un lien cassé dans une archive est mineur, le même lien dans une étape d'installation est critique. Les découvertes confirmées sont rapportées séparément des suspectées. Les corrections ne sont jamais appliquées automatiquement ; chaque rapport se termine par un menu proposant des corrections sûres, des corrections sélectionnées par l'utilisateur ou un simple rapport. Les couches mécaniques sont agnostiques au langage par conception — elles s'appuient sur la structure, la position et le sens plutôt que sur des mots-clés anglais — et les couches sémantiques opèrent dans la langue du document. Une fonctionnalité distincte et optionnelle est le rappel de dérive mémorielle des docs. Il ne scanne et ne rapporte rien. Si des fichiers de documentation (.md, .mdx, .markdown, .rst, .txt, .adoc, .asciidoc, .org) ont été modifiés mais que MEMORY.md n'a pas été mis à jour durant la session, et que le projet utilise la convention MEMORY.md, CoalLedger émet un seul message système discret lorsque l'agent a fini de répondre, puis reste silencieux après la mise à jour de MEMORY.md. Cela peut être désactivé. Cela complète l'incitation équivalente de CoalMine pour les modifications de code ; les deux surveillent des extensions de fichiers disjointes. La compatibilité est basée sur les capacités plutôt que liée à un tableau de plateformes : les plateformes avec des hooks de cycle de vie reçoivent un conducteur de début de session qui propose le bon canari au bon moment ; les plateformes sans hooks bénéficient d'une invocation pilotée par l'agent au mieux ; dans tous les cas, les canaris peuvent être invoqués manuellement par leur nom. L'auteur qualifie honnêtement les niveaux de support — Claude Code est décrit comme validé avec un plugin actif et du dogfooding, tandis que toutes les autres plateformes (Antigravity, Cursor, Codex, Gemini CLI, Cline, Copilot, claude.ai) sont marquées « works with » : conçues pour, mais pas encore prouvées de bout en bout. Le câblage d'Antigravity est documenté avec la mise en garde que l'emplacement de hooks.json a changé après une mise à jour et doit être redérivé des docs d'Antigravity ; un câblage vers un chemin mort est inerte mais inoffensif. L'installation pour Claude Code se fait via un ajout au marketplace et l'installation d'un plugin en deux commandes, ce qui configure également le conducteur et le rappel de dérive mémorielle. Les autres agents copient des dossiers de compétences autonomes (le moteur AST voyage à l'intérieur du dossier doc-structure). Les utilisateurs de claude.ai sont conseillés de ne pas zipper manuellement les compétences car les descriptions du frontmatter dépassent la limite de listing de la plateforme ; à la place, des ZIP par canari avec des descriptions réduites sont publiés sur la page Releases avec des sommes de contrôle SHA256. Les commandes incluent une commande par canari plus /coalledger:stats (statistiques de scan et de découvertes locales à la session) et /coalledger:update (vérification de version et gestion des mises à jour). La configuration supporte un fichier global et un fichier par projet résolu à partir de plusieurs répertoires d'agents connus, avec un chemin racine hérité toujours lu. Les clés couvrent un mode on/off, la langue du rapport, les canaris désactivés, le seuil de sévérité, le forçage scan-all, le niveau par défaut quick-versus-full, la porte doc-leak, un flag de docs publiques, l'incitation de dérive mémorielle, une règle typographique optionnelle pour le tiret cadratin et le comportement de vérification des mises à jour. Un projet peut être entièrement désactivé pour que la compétence ne s'y charge plus. Les permissions sont définies étroitement : il lit les documents nommés plus les fichiers vers lesquels leurs liens pointent, n'écrit que ses propres fichiers temporaires et son marqueur de mise à jour, exécute jusqu'à trois éléments locaux (le moteur AST en lecture seule, un point de sauvegarde git stash avant les corrections, et — uniquement avec consentement — un exemple documenté qu'un document prétend fonctionnel), et ne modifie jamais un document de lui-même. L'utilisation du réseau est optionnelle : la vérification des sources du niveau Full payant et la vérification des mises à jour nécessitent chacune un consentement distinct ; les hooks et le moteur ne se connectent jamais en ligne. Aucune clé API ni npm install n'est requis. Concernant le benchmarking, le projet est honnête : il est lancé sans benchmark plutôt qu'avec un chiffre inventé. La couche mécanique est verrouillée par des fixtures dans le dépôt (défauts plantés trouvés, leurres propres silencieux) via un script de vérification, et un résumé des résultats est prévu pour être rempli lors du premier run daté et versionné mesurant le rappel sur des défauts de documentation ensemencés, canari par canari. Licencié sous Apache 2.0.