coalledger

CoalLedger — это инструмент обеспечения качества документации, предназначенный для ИИ-агентов по написанию кода, который автор описывает как «CoalMine для документации». Он входит в TheColliery — семейство небольших дополнительных наборов (CoalMine, CoalTipple, CoalBoard, CoalHearth, CoalFace, CoalWash), которые придерживаются доктрины хуков без зависимостей, схем конфигурации из одного источника, контролируемых расходов и отсутствия автоматического редактирования. CoalLedger можно установить отдельно или вместе с остальными компонентами. Основная идея заключается в том, что для кода существуют линтеры, тесты и CI, в то время как документация держится на «надежде»: README, который разошелся с кодом, перевод, который больше не соответствует оригиналу, нерабочая ссылка на установку или устаревший бейдж версии — это скрытые сбои, которым читатель все еще доверяет. CoalLedger сканирует любой документ — README, спецификацию, отчет, перевод — и сравнивает то, что он отображает, с тем, что он утверждает. Семь «канареек», каждая из которых отвечает за свой режим сбоя: 1. doc-grounding — выявляет утверждения, которые не соответствуют источнику истины (коду, данным, оригинальному тексту, реальности); проверка осуществляется в реальном времени из нескольких источников, в офлайн-режиме статус меняется на «не подтверждено». 2. doc-standard — выявляет неполноту документа относительно стандарта для данного типа документа, включая обязательные разделы и недокументированный публичный интерфейс. 3. doc-rot — выявляет устаревшие версии, даты и бейджи, забытые TODO и замененные инструкции. 4. doc-consistency — выявляет противоречия между документами, дрейф терминологии и расхождения в разных языковых версиях. 5. doc-structure — выявляет битые ссылки, якоря, заголовки, таблицы, перекрестные ссылки и отсутствующий alt-текст изображений. 6. doc-quality — выявляет избыточность, неясные формулировки и языковые ошибки, такие как опечатки, грамматика и орфография. 7. doc-leak (ограничено конфигом) — помечает конфиденциальный контент на уровне текста в публичных документах; секреты в виде токенов остаются прерогативой других инструментов. Сообщает только о предполагаемых находках. Сканирование проходит в два этапа. Quick (быстрое) охватывает механические уровни, которые являются детерминированными и фактически бесплатными, и предоставляет только отчеты. Full (полное) добавляет семантические уровни, которые используют суждения модели, являются платными и всегда требуют отдельного согласия. Четыре «канарейки» сочетают механические и семантические уровни; doc-consistency и doc-leak являются чисто семантическими. Встроенный AST-движок CommonMark+GFM без зависимостей обеспечивает структурные проверки, чтобы контент, который отображается корректно, не помечался как ошибка; автор прямо заявляет, что потолок точности соответствует спецификации, а не попиксельному рендерингу GitHub, и особенности хостинга сообщаются как ограничения, а не угадываются. Серьезность ошибки всегда оценивается в контексте, а не механически: битая ссылка в архиве имеет низкий приоритет, та же ссылка в шаге установки — критический. Подтвержденные находки сообщаются отдельно от предполагаемых. Исправления никогда не применяются автоматически; каждый отчет заканчивается меню с предложением безопасных исправлений, исправлений по выбору пользователя или только отчета. Механические уровни по определению не зависят от языка — они ориентируются на структуру, позицию и смысл, а не на английские ключевые слова, а семантические уровни работают на языке самого документа. Отдельной опциональной функцией является напоминание о дрейфе памяти документации (docs memory-drift reminder). Оно ничего не сканирует и не сообщает. Если файлы документации (.md, .mdx, .markdown, .rst, .txt, .adoc, .asciidoc, .org) были отредактированы, но MEMORY.md не был обновлен в рамках сессии, и проект использует конвенцию MEMORY.md, CoalLedger выдает одно тихое системное сообщение, когда агент заканчивает ответ, и затем молчит после обновления MEMORY.md. Эту функцию можно отключить. Она дополняет аналогичный сигнал CoalMine для правок кода; они следят за разными расширениями файлов. Совместимость определяется возможностями, а не таблицей платформ: платформы с хуками жизненного цикла получают проводник запуска сессии, который предлагает нужную «канарейку» в нужное время; платформы без хуков получают вызов через агента по мере возможности; во всех случаях «канарейки» могут быть вызваны вручную по имени. Автор честно размечает уровни поддержки — Claude Code описан как проверенный с помощью живого плагина и внутреннего тестирования, в то время как все остальные платформы (Antigravity, Cursor, Codex, Gemini CLI, Cline, Copilot, claude.ai) помечены как «works with»: созданы для них, но еще не проверены end-to-end. Настройка Antigravity задокументирована с оговоркой, что расположение hooks.json изменилось после обновления и должно быть выведено из документации самого Antigravity; настройка по мертвому пути инертна, но безвредна. Установка для Claude Code представляет собой две команды: добавление из маркетплейса и установка плагина, что также настраивает проводник и напоминание о дрейфе памяти. Другие агенты копируют автономные папки навыков (AST-движок находится внутри папки doc-structure). Пользователям claude.ai рекомендуется не архивировать навыки вручную, так как описания в frontmatter превышают лимит платформы; вместо этого на странице Releases публикуются ZIP-архивы для каждой «канарейки» с сокращенными описаниями и контрольными суммами SHA256. Команды включают одну команду на каждую «канарейку», а также /coalledger:stats (статистика сканирования и находок в рамках сессии) и /coalledger:update (проверка версии и обновление). Конфигурация поддерживает глобальный файл и файл проекта, определяемый из нескольких известных директорий агентов, при этом все еще считывается устаревший корневой путь. Ключи охватывают режим вкл/выкл, язык отчетов, отключенные «канарейки», порог серьезности, переопределение сканирования всего, уровень по умолчанию (quick или full), затвор doc-leak, флаг публичных документов, напоминание о дрейфе памяти, опциональное правило типографики для длинного тире и поведение проверки обновлений. Проект может быть полностью отключен, чтобы навык перестал загружаться. Разрешения сформулированы узко: инструмент читает указанные документы и файлы, на которые они ссылаются; записывает только свои временные файлы и метку обновления; запускает до трех локальных процессов (AST-движок только для чтения, контрольная точка git stash перед исправлениями и — только с согласия — задокументированный пример, который, по утверждению документа, работает), и никогда не редактирует документ самостоятельно. Использование сети опционально: верификация источников в платном уровне Full и проверка самообновления требуют отдельного согласия; хуки и движок никогда не выходят в сеть. API-ключи или npm install не требуются. В вопросах бенчмаркинга проект честен: он запускается без бенчмарков, вместо того чтобы использовать выдуманные цифры. Механический уровень проверяется в репозитории с помощью скрипта верификации (посаженные дефекты обнаруживаются, чистые приманки молчат), и планируется заполнить сводку результатов по итогам первого датированного и версионного запуска, измеряющего полноту обнаружения seeded-дефектов в документации для каждой «канарейки». Лицензия Apache 2.0.