TheColliery Doc-Rot
Answer in the USER'S language; keep technical terms, commands, paths, and check ids verbatim.
Find doc content that time has invalidated. Report CONFIRMED rot; park the merely-old in SUSPECTED.
Parameters
- SCOPE: named files (default when given) | touched doc files this session | whole repo docs —
.md/.mdx/.markdown/.rst/.txt/.adoc/.asciidoc/.org(confirm first if > 20 files). - TIER: Quick = mechanical age-markers only (~free) · Full = semantic staleness judgment (paid). Default from
quickVsFull(.coalledger.json, global + project merge); Full is always a separate consent.
Age-markers (mechanical layer — deterministic detection)
| marker | signal |
|---|---|
| version string | doc names a version older than the project's current one (compare against the version's source of truth, e.g. the manifest) |
| date stamp | a "last updated" / revalidate-by / verified-on date far in the past or already passed |
| dead task marker | TODO / FIXME / "coming soon" / "not yet" with no sign of life |
| stale badge | a hardcoded status/version badge the repo state contradicts |
Detection is deterministic; whether a marker means ROT is not — an old date on an archive is fine, on an install guide it is not.
Method
- Quick: collect age-markers per the table. Old ≠ rotten: a marker alone lands in SUSPECTED.
- Full: judge each marker in context, and hunt UNDATED rot — instructions for a surface that has changed, claims a later doc superseded (pure contradiction between live docs belongs to doc-consistency; rot is the time axis).
- Confirm before CONFIRMED: a finding is CONFIRMED only when the current state contradicts the doc (the version source names a newer version; the referenced surface is gone). Anything inferred stays SUSPECTED.
- Severity by CONTEXT (never a fixed map), then honor
severityFloor: rotten install/security steps readers follow = HIGH-CRITICAL; a stale badge or version mention = MEDIUM; an old date in an archived doc = LOW.scanEverything: truebypasses the floor this run — report everything down tolow— and say so: state thatseverityFloorwas bypassed, never that every scope cut was bypassed (this canary has none to bypass).
Escalation boundary
Whether a claim was EVER true is doc-grounding's job; formal verification of a high-stakes claim escalates to CoalBoard (/coalboard) if that skill is installed. This canary only answers "did time break it".
Grants & denials (CLASSIFY-BLOCK)
| class | step it powers | grant | on denial |
|---|---|---|---|
| read | collect age-markers + check the version source of truth | Read·Grep·Glob |
refuse that file, report it unscanned — never a false clean bill |
| write | Apply safe fixes (unambiguous current-value updates) | Write·Edit (·Bash — checkpoint via git stash/commit) |
report + courier the intended change to the dispatcher; never claim applied |
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
| # | path:line | marker | evidence (current state) | severity | fix |
CONFIRMED table only; SUSPECTED (old-but-unproven) as a separate list, never the main table.
Reporting: call ReportFindings when callable — file/line MUST be the marker's own line, never a paraphrase; 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 (old-but-unproven) 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. An Apply-fixes click = consent to the Apply-safe-fixes class below (unambiguous current-value updates only), composing with — never bypassing — Fix mode. 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.
- Apply safe fixes: only updates whose current value is unambiguous (bump a version string to the manifest's, refresh a date the user confirms, delete a TODO the user confirms dead). Each fix: checkpoint (git stash/commit in a git repo; else copy the file aside — never assume git exists) -> apply -> re-read the changed lines.
- Let me pick: list findings; the user selects.
- Report only: exit unchanged.
NEVER auto-fix: rewriting superseded instructions (a content decision), deleting sections, anything whose current truth you did not verify.
Multilingual
Age-markers are language-agnostic (versions, dates, and badges look the same in any prose language; date FORMATS vary — parse by structure, not an English month name). Semantic judgment degrades to low-confidence flags on a poorly-handled language, 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.