coalledger

CoalLedger is a documentation-quality tool aimed at AI coding agents, described by its author as "CoalMine for documentation." It is part of TheColliery, a family of small add-on suites (CoalMine, CoalTipple, CoalBoard, CoalHearth, CoalFace, CoalWash) that share a stated doctrine of zero-dependency hooks, single-source config schemas, consent-gated spending and no automatic edits. CoalLedger can be installed alone or alongside the others. The premise is that code has linters, tests and CI, while documentation mostly has hope: a README that drifted from the code, a translation that no longer matches its counterpart, a dead install link or an outdated version badge are silent failures a reader still trusts. CoalLedger scans any document — README, spec, report, translation — and compares what it renders against what it claims. Seven canaries, one failure mode each: 1. doc-grounding — catches claims that do not match their source of truth (code, data, original text, reality); verified in real time from multiple sources, degrading to "unverified" offline. 2. doc-standard — catches incompleteness against the standard for that kind of document, including required sections and undocumented public surface. 3. doc-rot — catches stale versions, dates and badges, dead TODOs and superseded instructions. 4. doc-consistency — catches documents that contradict each other, terminology drift and cross-language drift. 5. doc-structure — catches broken links, anchors, headings, tables, references and image alt text. 6. doc-quality — catches bloat, unclear prose and language mechanics such as typos, grammar and spelling. 7. doc-leak (config-gated) — flags prose-level sensitive content in public-facing documents; token-shaped secrets are left to other tools. It reports only suspected findings. Scans run in two tiers. Quick covers mechanical layers that are deterministic and effectively free, and reports only. Full adds the semantic layers, which use model judgment, are paid, and always require separate consent. Four of the canaries combine mechanical and semantic layers; doc-consistency and doc-leak are semantic-only. A bundled zero-dependency CommonMark+GFM AST engine powers the structural checks so that content that renders correctly is not flagged; the author is explicit that its fidelity ceiling is spec-level, not pixel-perfect GitHub rendering, and host quirks are reported as limits rather than guessed. Severity is always judged in context rather than mechanically: a broken link in an archive is low, the same link in an install step is critical. Confirmed findings are reported separately from suspected ones. Fixes are never applied automatically; every report ends with a menu offering safe fixes, user-selected fixes, or report only. The mechanical layers are language-agnostic by design — they key off structure, position and meaning rather than English keywords — and the semantic layers operate in the document's own language. A separate, opt-in feature is the docs memory-drift reminder. It scans and reports nothing. If documentation files (.md, .mdx, .markdown, .rst, .txt, .adoc, .asciidoc, .org) were edited but MEMORY.md was not updated in the session, and the project uses the MEMORY.md convention, CoalLedger emits one quiet system message when the agent finishes responding, then stays silent after MEMORY.md is updated. It can be disabled. This complements CoalMine's equivalent nudge for code edits; the two watch disjoint file extensions. Compatibility is capability-keyed rather than tied to a platform table: platforms with lifecycle hooks get a session-start conductor that offers the right canary at the right time; platforms without hooks get best-effort agent-driven invocation; in all cases the canaries can be invoked manually by name. The author labels support tiers honestly — Claude Code is described as validated with a live plugin and dogfooding, while all other platforms (Antigravity, Cursor, Codex, Gemini CLI, Cline, Copilot, claude.ai) are "works with": built for, not yet proven end-to-end. Antigravity wiring is documented with a caveat that the hooks.json location moved after an update and should be re-derived from Antigravity's own docs; wiring at a dead path is inert but harmless. Installation for Claude Code is a two-command marketplace add and plugin install, which also wires the conductor and the memory-drift reminder. Other agents copy self-contained skill folders (the AST engine travels inside the doc-structure folder). claude.ai users are advised not to hand-zip the skills because the frontmatter descriptions exceed that platform's listing cap; instead per-canary ZIPs with trimmed descriptions are published on the Releases page with SHA256 checksums. Commands include one per canary plus /coalledger:stats (session-local scan and findings statistics) and /coalledger:update (version check and update handling). Configuration supports a global file and a per-project file resolved from several known agent directories, with a legacy root path still read. Keys cover an on/off mode, report language, disabled canaries, severity floor, scan-all override, quick-versus-full default tier, the doc-leak gate, a public-facing docs flag, the memory-drift nudge, an optional em-dash typography rule, and update-check behaviour. A project can be switched off entirely so the skill stops loading there. Permissions are stated narrowly: it reads the documents named plus files their links point at, writes only its own scratch files and update stamp, runs up to three local things (the read-only AST engine, a git stash checkpoint before fixes, and — only with consent — a documented example a document claims works), and never edits a document on its own. Network use is opt-in: the paid Full tier's source verification and the self-update check each require separate consent; hooks and engine never go online. No API keys or npm install are needed. On benchmarking, the project is honest: it launches unbenchmarked rather than with an invented number. The mechanical layer is fixture-gated in-repo (planted defects found, clean decoys silent) via a verification script, and a results digest is planned to be filled in from the first dated, versioned run measuring recall on seeded documentation defects, canary by canary. Licensed under Apache 2.0.