Doc-Consistency

Answer in the USER'S language; keep technical terms, commands, paths, and check ids verbatim.

Find places where the doc set disagrees with itself. Report CONFIRMED contradictions; park tensions in SUSPECTED.

Parameters

• SCOPE: a named doc set (default when given) | all docs touching a named topic | whole repo docs—.md/.mdx/.markdown/.rst/.txt/.adoc/.asciidoc/.org (confirm first if > 20 files).
• TIER: two layers. Mechanical (~free): declared translation pairs only (Method 2b). Semantic (Full, paid, always consent-gated): the three drift classes below. Two sentences can contradict with zero textual overlap, so they stay judgment, never pattern-matching.

What counts (three drift classes)

Method

1. Inventory: extract the facts and defined terms each in-scope doc asserts (skip opinions; technical terms stay verbatim—a term is only "drifted" when the CONCEPT diverges, not when prose around it varies).
2. Cross-compare the inventory; pair up disagreements. For cross-language pairs, compare MEANING (a free translation is fine; a contradicting one is drift).
   • 2b. Declared translation pairs (mechanical, ~free, SUSPECTED-only). Pairs come only from translationPairs (.coalledger.json, global + project merge), which the engine reads itself: never copy a pair into a command. Empty (factory default []): the engine reports nothing; never guess pairs from file names. The engine ships INSIDE this skill folder at ./lib/. Substitute your context's skill base dir for <skill base dir>. Run cd "<skill base dir>" && node ./lib/translation-pairs.mjs --list-path first, then write the run list with your file tool to the exact path it prints ({"root": "<absolute project folder>", "docs": []}), then run exactly: cd "<skill base dir>" && node ./lib/translation-pairs.mjs --json --list. The cd is REQUIRED (./lib/ resolves against the skill folder, never your project cwd). The run list's root is the absolute project folder; pair sides are relative to it, forward slashes, no ... No path goes on the command line; the engine reads the root from the run list as data.
     • Checks (all SUSPECTED): pair-invalid (no =, an empty side, a backslash, an absolute path or a .. segment; nothing is read) · pair-source-missing and translation-missing (a side is not a plain file under the root: missing, or refused by the link rule) · translation-older (the counterpart's last commit is before its source's) · translation-undated (no git record: no git, not a repository, or untracked or never committed; it means undated, never older).
     • Dates are each file's last git committer date (git log -1 --format=%cI), never mtime.
     • --json prints { "findings": [...] }. Exit 0 whenever the run completes, findings included; exit 2 on a usage error.
     • Which side is right stays out of this step (Escalation boundary).
3. Which side is right is NOT this canary's call—report the pair and, where a source of truth is obvious, note it; resolving truth is doc-grounding's job (offer to run it on the pair).
4. Severity by CONTEXT (never a fixed map), then honor severityFloor: contradictory instructions readers may follow = HIGH-CRITICAL; contradictory descriptions = MEDIUM; naming inconsistency = LOW. scanEverything: true bypasses the floor this run—report everything down to low—and say so: state that severityFloor was bypassed, never that every scope cut was bypassed (this canary has none to bypass).

Escalation boundary

Adjudicating WHICH of two contradicting claims is true = doc-grounding (fetch/recompute) or, for the error-not-allowed slice, CoalBoard (/coalboard) if that skill is installed. This canary only surfaces the disagreement.

Grants & denials (CLASSIFY-BLOCK)

A denial reaches the WORKER as a visible message and propagates NO further—not to the dispatcher, not as a catchable condition. Every row above states a branch or an explicit death; a step that dies says so in the output. Never report a denied step as done, skipped, or clean.

Output

| # | doc A (path:line) | doc B (path:line) | class | disagreement | severity |

CONFIRMED table only; SUSPECTED (a tension that may be intended, e.g. an archive vs a live doc) as a separate list.

Reporting: call ReportFindings when callable—the schema carries ONE file/line pair per finding, so file/line MUST be doc A's defect site; doc B's location is cited as path:line inside summary/failure_scenario, never a paraphrase—one contradiction is one finding, never split across two. An unresolvable line reports your best guess, named imprecise in the wrap-up, never dropped. Severity prefixed in summary (e.g. [HIGH] …) per the severity-by-context rule above, ranked most-severe first, SUSPECTED tensions as verdict: PLAUSIBLE; chat then carries only the wrap-up line (counts · SUSPECTED list · overflow past 32) + the fix menu, never a restatement. Not callable → the table above, unchanged. No safe-fix class exists here—every fix is a which-side-wins content decision, so an Apply-fixes click degrades to the Let-me-pick path below, never an auto-apply. After any fix round, re-report the same findings with outcome: fixed/skipped/no_change_needed.

Fix mode (choice-gated)

After any report in an interactive session you MUST present this menu via your question tool (skip only when findings are zero or no user is present). NEVER auto-fix a live doc.

• Align to a chosen side: the user picks which doc is right per finding; the other is edited to match, with a checkpoint first (git stash/commit in a git repo; else copy the file aside—never assume git exists).
• Let me pick: list findings; the user selects.
• Report only: exit unchanged.

NEVER auto-fix: every consistency fix is a content decision (which side wins)—there are no "safe" automatic fixes in this canary.

Multilingual

Cross-language comparison IS this canary's core case, worked in the languages the docs are written in. A poorly-handled language degrades to low-confidence SUSPECTED flags, never false alarms.

Problem report

If this canary misbehaves, OFFER to file it at https://github.com/TheColliery/CoalLedger/issues with a user-reviewed summary—never auto-submit.