| name | md-audit |
| description | Detect stale + orphan MD files in docs/. Mechanical scan of git mtime + inbound links; classifies every doc into 5 buckets. Read-only — never moves or deletes. Complement to /doc-audit (content staleness vs existence staleness). |
| version | 1.0 |
| updated | "2026-04-30T00:00:00.000Z" |
| tags | ["architecture","active"] |
| effort | low |
| disable-model-invocation | true |
/md-audit — Existence-Staleness Audit
Usage
node scripts/mdStalenessDetector.js
node scripts/mdStalenessDetector.js --stale-days 60
node scripts/mdStalenessDetector.js --active-days 14
Writes report to output/md_audit_<YYYY-MM-DD>.md.
What it does
Walks docs/ (excludes docs/archive/, docs/drive-files/, docs/research/papers/). For each .md:
- Git mtime via
git log -1 --format=%ct — falls back to filesystem mtime if not in git.
- Counts inbound references across
docs/**/*.md, .claude/**/*.md, CLAUDE.md, MEMORY.md, CONTEXT.md, SESSION_CONTEXT.md, README.md. Matches both wikilinks ([[engine/ROLLOUT_PLAN]]) and literal paths (docs/engine/ROLLOUT_PLAN.md).
- Marks referrers as "active" if they were touched in the last
--active-days window (default 30).
Then classifies each doc into one of five buckets (first-match-wins):
| Bucket | Rule |
|---|
reference-stable | frontmatter stable: true — explicitly durable |
fresh | not stale (≤ --stale-days) |
orphan-candidate | stale + zero inbound refs — strongest archive candidate |
stable-by-reference | stale + at least one active referrer — load-bearing dormant |
stale-but-linked | stale + inbound exists but no active referrer — human judgment |
What it does NOT do
- Does not archive, move, delete, or rewrite anything.
- Does not read content for accuracy. That's
/doc-audit — the sibling skill.
- Does not schedule itself. Run on demand; cron gating deferred per the plan.
Companion skills
/doc-audit — content staleness audit on 7 named groups. Reads each doc, verifies claims against actual codebase state. Targeted + thorough./md-audit (this) — existence staleness across the whole tree. Catches orphans /doc-audit doesn't know about.
Both are needed. /doc-audit checks whether the docs you decided to keep are still accurate. /md-audit finds the docs you forgot.
Plan + acceptance
Plan file: docs/archive/plans/2026-04-21-md-audit-skill.md (S170, drafted research-build).
Phase 3 (gated archival via scripts/archiveStaleMd.js) intentionally not built — first run informs whether the classifier needs tuning before destructive action enters the loop.
Tuning notes
- 90-day threshold — starting point. If first run produces zero orphans, tighten to 60. If it produces >50, tighten the active window or seed
stable: true on known durables.
docs/plans/ — not excluded. Old completed plans archiving is a feature, not a bug.- False positives — top-level reference docs (
SCHEMA.md, STACK.md, SIMULATION_LEDGER.md, SPREADSHEET.md, reference/V3_ARCHITECTURE.md, reference/DEPLOY.md) are candidates for stable: true frontmatter after first review.
Tracking
After every run, append a row to [[../../docs/AUDITS]] Run history table:
- Date, skill (
/md-audit), findings (1-line summary — orphan count / stale count / fresh count), action taken (typically report only; archived N docs if Phase 3 fires), artifact path (output/md_audit_<DATE>.md).
