Twelve of thirteen stale docs were kept alive only by each other A developer built mdsweep, a dependency-free Node.js tool that scans repositories for stale markdown files left behind by coding agents and sorts them into active, stale, and orphan buckets. Testing across 36 repos with roughly 1,200 markdown files revealed that 12 of 13 old files in one reports folder were kept alive only by circular references among themselves, showing that inbound link counts alone cannot distinguish live documentation from dead citation clusters. The tool moves orphans to a timestamped trash directory with an undo command rather than deleting them. My coding agents are prolific note-takers. Every non-trivial session leaves a PLAN.md, a SUMMARY.md, a HANDOFF.md, sometimes a FINAL REPORT V2.md. Across 36 repos on this machine there are about 1,200 markdown files, and I could not tell you which ones anybody still opens. The obvious cleanup is a glob and a date filter: find . -name 'PLAN .md' -o -name 'SUMMARY .md' -mtime +30 -delete I did not run that, because I already knew what it would hit. A PLAN.md from May can still be the file a README points at when it explains why the approach changed. Age alone says nothing about whether a file is load-bearing. So the next rule: keep anything that something else links to. Count inbound references, and if the count is above zero, the file is still wired into the repo. Old and unreferenced means safe to move. That rule survived about a day. Here is the scan that killed it, from a trading repo with a reports/ folder: reports/E F G RESULTS.md 116d stale refs=1 reports/FINAL HONEST PLAN.md 116d stale refs=1 reports/FUNDING HARVEST REPORT.md 116d stale refs=2 reports/HONEST FINDINGS.md 116d stale refs=1 reports/J SUMMARY.md 114d stale refs=1 reports/FINAL REPORT.md 114d stale refs=6 ... 13 files, all 114-116 days old, every one with refs 0 Every file passed the "someone links to it" test. Then I traced where the links came from: grep -rl "J SUMMARY\.md" --exclude-dir=.git . reports/L1 AUDIT REPORT.md L1 AUDIT REPORT.md is in the same folder and is just as dead. I walked all thirteen. Twelve of them had every single inbound link coming from another file inside reports/ . The folder was citing itself in a circle. Only FINAL REPORT.md had a reference from outside: mql5/README.md , and a Python script that actually runs. A reference count of 1 was not evidence that anyone used the file. It was evidence that the agent wrote two files in the same session and made one mention the other. I stopped trying to find a rule that decides. The scanner now sorts into three buckets and hands the ambiguous one back to me: h.grade = h.ageDays <= days ? 'active' // touched recently, leave it : h.refs 0 ? 'stale' // old but linked, I read these by hand : 'orphan'; // old and unlinked, movable Across those 36 repos: 687 active, 172 stale, 176 orphan. The 172 in the middle are exactly the files the glob would have eaten, and the ones the reference rule would have blessed. They are not a category the tool can resolve, so it doesn't pretend to. Orphans get moved rather than deleted. fs.renameSync puts them in .mdsweep/trash/