coalledger

CoalLedger es una herramienta de calidad de documentación dirigida a agentes de codificación de IA, descrita por su autor como "CoalMine para la documentación". Forma parte de TheColliery, una familia de pequeñas suites de complementos (CoalMine, CoalTipple, CoalBoard, CoalHearth, CoalFace, CoalWash) que comparten una doctrina declarada de hooks sin dependencias, esquemas de configuración de fuente única, gasto restringido por consentimiento y sin ediciones automáticas. CoalLedger puede instalarse solo o junto con los demás. La premisa es que el código tiene linters, pruebas y CI, mientras que la documentación depende mayormente de la esperanza: un README que se ha distanciado del código, una traducción que ya no coincide con su contraparte, un enlace de instalación muerto o una insignia de versión desactualizada son fallos silenciosos en los que el lector sigue confiando. CoalLedger escanea cualquier documento (README, especificación, informe, traducción) y compara lo que renderiza con lo que afirma. Siete canarios, uno para cada modo de fallo: 1. doc-grounding: detecta afirmaciones que no coinciden con su fuente de verdad (código, datos, texto original, realidad); se verifica en tiempo real desde múltiples fuentes, degradándose a "no verificado" fuera de línea. 2. doc-standard: detecta incompletitud frente al estándar para ese tipo de documento, incluyendo secciones obligatorias y superficies públicas no documentadas. 3. doc-rot: detecta versiones, fechas e insignias obsoletas, TODOs muertos e instrucciones superadas. 4. doc-consistency: detecta documentos que se contradicen entre sí, deriva de terminología y deriva entre idiomas. 5. doc-structure: detecta enlaces rotos, anclas, encabezados, tablas, referencias y texto alternativo de imágenes. 6. doc-quality: detecta redundancia, prosa confusa y mecánica del lenguaje como erratas, gramática y ortografía. 7. doc-leak (restringido por configuración): marca contenido sensible a nivel de prosa en documentos públicos; los secretos con forma de token se dejan a otras herramientas. Reporta solo hallazgos sospechosos. Los escaneos se ejecutan en dos niveles. Quick cubre capas mecánicas que son deterministas y efectivamente gratuitas, y solo reporta. Full añade las capas semánticas, que utilizan el juicio de un modelo, son de pago y siempre requieren un consentimiento separado. Cuatro de los canarios combinan capas mecánicas y semánticas; doc-consistency y doc-leak son solo semánticos. Un motor AST de CommonMark+GFM integrado y sin dependencias impulsa las comprobaciones estructurales para que el contenido que se renderiza correctamente no sea marcado; el autor es explícito en que su techo de fidelidad es a nivel de especificación, no un renderizado de GitHub perfecto al píxel, y las peculiaridades del host se reportan como límites en lugar de suponerse. La severidad siempre se juzga en contexto en lugar de mecánicamente: un enlace roto en un archivo es bajo, el mismo enlace en un paso de instalación es crítico. Los hallazgos confirmados se reportan separadamente de los sospechosos. Las correcciones nunca se aplican automáticamente; cada reporte termina con un menú que ofrece correcciones seguras, correcciones seleccionadas por el usuario o solo el reporte. Las capas mecánicas son agnósticas al idioma por diseño —se basan en la estructura, posición y significado en lugar de palabras clave en inglés— y las capas semánticas operan en el idioma del propio documento. Una característica separada y opcional es el recordatorio de deriva de memoria de docs (docs memory-drift reminder). No escanea ni reporta nada. Si los archivos de documentación (.md, .mdx, .markdown, .rst, .txt, .adoc, .asciidoc, .org) fueron editados pero MEMORY.md no se actualizó en la sesión, y el proyecto utiliza la convención MEMORY.md, CoalLedger emite un mensaje silencioso del sistema cuando el agente termina de responder, y luego permanece en silencio después de que MEMORY.md se actualiza. Puede desactivarse. Esto complementa el aviso equivalente de CoalMine para ediciones de código; los dos vigilan extensiones de archivo disjuntas. La compatibilidad se basa en capacidades en lugar de estar ligada a una tabla de plataformas: las plataformas con hooks de ciclo de vida reciben un conductor de inicio de sesión que ofrece el canario adecuado en el momento adecuado; las plataformas sin hooks reciben una invocación impulsada por el agente según el mejor esfuerzo; en todos los casos, los canarios pueden invocarse manualmente por nombre. El autor etiqueta los niveles de soporte honestamente: Claude Code se describe como validado con un plugin en vivo y dogfooding, mientras que todas las demás plataformas (Antigravity, Cursor, Codex, Gemini CLI, Cline, Copilot, claude.ai) son "works with": construidas para, pero aún no probadas de extremo a extremo. El cableado de Antigravity está documentado con la advertencia de que la ubicación de hooks.json se movió después de una actualización y debe derivarse nuevamente de la propia documentación de Antigravity; el cableado en una ruta muerta es inerte pero inofensivo. La instalación para Claude Code es un agregado de marketplace de dos comandos y una instalación de plugin, que también configura el conductor y el recordatorio de deriva de memoria. Otros agentes copian carpetas de habilidades autónomas (el motor AST viaja dentro de la carpeta doc-structure). A los usuarios de claude.ai se les aconseja no comprimir manualmente las habilidades porque las descripciones del frontmatter exceden el límite de listado de esa plataforma; en su lugar, se publican ZIPs por canario con descripciones recortadas en la página de Releases con sumas de comprobación SHA256. Los comandos incluyen uno por canario más /coalledger:stats (estadísticas de escaneo y hallazgos locales de la sesión) y /coalledger:update (verificación de versión y manejo de actualizaciones). La configuración admite un archivo global y un archivo por proyecto resuelto desde varios directorios de agentes conocidos, leyéndose aún una ruta raíz heredada. Las claves cubren un modo on/off, idioma del reporte, canarios desactivados, piso de severidad, anulación de escaneo total, nivel predeterminado quick-versus-full, la puerta de doc-leak, una bandera de docs públicos, el aviso de deriva de memoria, una regla de tipografía opcional para el guion largo y el comportamiento de verificación de actualizaciones. Un proyecto puede desactivarse por completo para que la habilidad deje de cargarse allí. Los permisos se declaran estrictamente: lee los documentos nombrados más los archivos a los que apuntan sus enlaces, escribe solo sus propios archivos temporales y la marca de actualización, ejecuta hasta tres cosas locales (el motor AST de solo lectura, un punto de control de git stash antes de las correcciones y —solo con consentimiento— un ejemplo documentado que un documento afirma que funciona), y nunca edita un documento por su cuenta. El uso de la red es opcional: la verificación de fuentes del nivel Full de pago y la verificación de auto-actualización requieren consentimiento separado; los hooks y el motor nunca se conectan en línea. No se necesitan claves API ni npm install. En cuanto al benchmarking, el proyecto es honesto: se lanza sin benchmarks en lugar de con un número inventado. La capa mecánica está restringida por fixtures en el repositorio (defectos plantados encontrados, señuelos limpios silenciosos) a través de un script de verificación, y se planea llenar un resumen de resultados a partir de la primera ejecución fechada y versionada que mida la recuperación de defectos de documentación sembrados, canario por canario. Licenciado bajo Apache 2.0.