coalledger

CoalLedger é uma ferramenta de qualidade de documentação voltada para agentes de codificação de IA, descrita por seu autor como "CoalMine para documentação". Faz parte do TheColliery, uma família de pequenas suítes de complementos (CoalMine, CoalTipple, CoalBoard, CoalHearth, CoalFace, CoalWash) que compartilham uma doutrina declarada de hooks sem dependências, esquemas de configuração de fonte única, gastos controlados por consentimento e nenhuma edição automática. O CoalLedger pode ser instalado sozinho ou junto com os demais. A premissa é que o código possui linters, testes e CI, enquanto a documentação baseia-se majoritariamente na esperança: um README que se distanciou do código, uma tradução que não corresponde mais à sua contraparte, um link de instalação morto ou um badge de versão desatualizado são falhas silenciosas nas quais o leitor ainda confia. O CoalLedger escaneia qualquer documento — README, especificação, relatório, tradução — e compara o que ele renderiza com o que ele afirma. Sete canários, um modo de falha para cada: 1. doc-grounding — detecta afirmações que não correspondem à sua fonte de verdade (código, dados, texto original, realidade); verificado em tempo real a partir de múltiplas fontes, degradando para "não verificado" offline. 2. doc-standard — detecta incompletudes em relação ao padrão para aquele tipo de documento, incluindo seções obrigatórias e superfícies públicas não documentadas. 3. doc-rot — detecta versões, datas e badges obsoletos, TODOs mortos e instruções superadas. 4. doc-consistency — detecta documentos que se contradizem, deriva de terminologia e deriva entre idiomas. 5. doc-structure — detecta links quebrados, âncoras, cabeçalhos, tabelas, referências e texto alternativo de imagens. 6. doc-quality — detecta verbosidade, prosa confusa e mecânicas de linguagem, como erros de digitação, gramática e ortografia. 7. doc-leak (controlado por config) — sinaliza conteúdo sensível em nível de prosa em documentos voltados ao público; segredos com formato de token são deixados para outras ferramentas. Ele reporta apenas descobertas suspeitas. Os escaneamentos ocorrem em dois níveis. O Quick cobre camadas mecânicas que são determinísticas e efetivamente gratuitas, e apenas reporta. O Full adiciona as camadas semânticas, que utilizam julgamento de modelo, são pagas e sempre exigem consentimento separado. Quatro dos canários combinam camadas mecânicas e semânticas; doc-consistency e doc-leak são apenas semânticos. Um motor AST CommonMark+GFM integrado e sem dependências alimenta as verificações estruturais para que o conteúdo que renderiza corretamente não seja sinalizado; o autor é explícito que seu teto de fidelidade é nível de especificação, não a renderização pixel-perfect do GitHub, e as peculiaridades do host são reportadas como limitações em vez de suposições. A severidade é sempre julgada no contexto, e não mecanicamente: um link quebrado em um arquivo é baixo, o mesmo link em uma etapa de instalação é crítico. Descobertas confirmadas são reportadas separadamente das suspeitas. Correções nunca são aplicadas automaticamente; cada relatório termina com um menu oferecendo correções seguras, correções selecionadas pelo usuário ou apenas o relatório. As camadas mecânicas são agnósticas a idiomas por design — elas se baseiam em estrutura, posição e significado, em vez de palavras-chave em inglês — e as camadas semânticas operam no próprio idioma do documento. Um recurso separado e opcional é o lembrete de deriva de memória (memory-drift) de docs. Ele não escaneia nem reporta nada. Se arquivos de documentação (.md, .mdx, .markdown, .rst, .txt, .adoc, .asciidoc, .org) foram editados, mas o MEMORY.md não foi atualizado na sessão, e o projeto usa a convenção MEMORY.md, o CoalLedger emite uma mensagem de sistema silenciosa quando o agente termina de responder, permanecendo em silêncio após a atualização do MEMORY.md. Ele pode ser desativado. Isso complementa o incentivo equivalente do CoalMine para edições de código; os dois monitoram extensões de arquivo distintas. A compatibilidade é baseada em capacidade, e não vinculada a uma tabela de plataformas: plataformas com hooks de ciclo de vida recebem um condutor de início de sessão que oferece o canário certo no momento certo; plataformas sem hooks recebem a invocação orientada pelo agente conforme a possibilidade; em todos os casos, os canários podem ser invocados manualmente pelo nome. O autor rotula os níveis de suporte honestamente — o Claude Code é descrito como validado com um plugin ativo e dogfooding, enquanto todas as outras plataformas (Antigravity, Cursor, Codex, Gemini CLI, Cline, Copilot, claude.ai) são "works with": construídas para, mas ainda não provadas de ponta a ponta. A fiação do Antigravity é documentada com a ressalva de que a localização do hooks.json mudou após uma atualização e deve ser redescoberta a partir da própria documentação do Antigravity; a fiação em um caminho morto é inerte, mas inofensiva. A instalação para o Claude Code é um add de marketplace e instalação de plugin de dois comandos, que também configura o condutor e o lembrete de deriva de memória. Outros agentes copiam pastas de habilidades autocontidas (o motor AST viaja dentro da pasta doc-structure). Usuários de claude.ai são aconselhados a não compactar as habilidades manualmente porque as descrições do frontmatter excedem o limite de listagem daquela plataforma; em vez disso, ZIPs por canário com descrições reduzidas são publicados na página de Releases com checksums SHA256. Os comandos incluem um por canário, além de /coalledger:stats (estatísticas de escaneamento e descobertas locais da sessão) e /coalledger:update (verificação de versão e manipulação de atualização). A configuração suporta um arquivo global e um arquivo por projeto resolvido a partir de vários diretórios de agentes conhecidos, com um caminho raiz legado ainda sendo lido. As chaves cobrem um modo on/off, idioma do relatório, canários desativados, piso de severidade, override de escanear tudo, nível padrão quick-versus-full, o gate do doc-leak, uma flag de docs voltados ao público, o incentivo de deriva de memória, uma regra de tipografia opcional para travessão (em-dash) e comportamento de verificação de atualização. Um projeto pode ser totalmente desligado para que a habilidade pare de carregar ali. As permissões são declaradas de forma restrita: ele lê os documentos nomeados e os arquivos para os quais seus links apontam, escreve apenas seus próprios arquivos temporários e carimbo de atualização, executa até três coisas locais (o motor AST de leitura, um checkpoint de git stash antes das correções e — apenas com consentimento — um exemplo documentado que um documento afirma funcionar), e nunca edita um documento por conta própria. O uso de rede é opcional: a verificação de fonte do nível Full pago e a verificação de auto-atualização exigem consentimentos separados; hooks e o motor nunca ficam online. Não são necessárias chaves de API ou npm install. Sobre benchmarking, o projeto é honesto: ele é lançado sem benchmarks em vez de com um número inventado. A camada mecânica é validada no repositório via script de verificação (defeitos plantados são encontrados, iscas limpas permanecem silenciosas), e um resumo de resultados está planejado para ser preenchido a partir da primeira execução datada e versionada medindo a revocação em defeitos de documentação semeados, canário por canário. Licenciado sob Apache 2.0.