docs: complete stale-pattern checker docs and harden resolver

Align patternsDir fallback with index-sync, guard missing context/,
add reporter remediation, update README/CHANGELOG/CONTRIBUTING,
and add a test showing the index-sync vs stale-pattern distinction.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: root

CHANGELOG.md

@@ -5,10 +5,11 @@ All notable changes to this project will be documented in this file.
 ## [Unreleased]
 
 ### Added
+- **stale-pattern drift checker** — flags pattern files not linked from `ROUTER.md` or `context/*.md`.
 - **broken-link drift checker** — flags Markdown links in scaffold files whose local target file does not exist.
 
 ### Changed
-- README and CONTRIBUTING now list all 11 drift checkers (including `tool-config-sync`, `todo-fixme`, and `broken-link`).
+- README and CONTRIBUTING now list all 12 drift checkers (including `tool-config-sync`, `todo-fixme`, `broken-link`, and `stale-pattern`).
 
 ## [0.3.5] - 2026-05-14
 

CONTRIBUTING.md

@@ -2,7 +2,7 @@
 
 Thanks for your interest in contributing! Here's how to get started.
 
-**New here?** The best starting point is an issue labeled [`good first issue`](https://github.com/theDakshJaitly/mex/labels/good%20first%20issue) — most are self-contained drift checkers, and there are 11 existing checkers to copy from. See [Adding a drift checker](#adding-a-drift-checker) below.
+**New here?** The best starting point is an issue labeled [`good first issue`](https://github.com/theDakshJaitly/mex/labels/good%20first%20issue) — most are self-contained drift checkers, and there are 12 existing checkers to copy from. See [Adding a drift checker](#adding-a-drift-checker) below.
 
 ## Setup
 
@@ -50,7 +50,7 @@ test/                 # Vitest tests
 
 ## Adding a drift checker
 
-New checkers are the most newcomer-friendly contribution. A checker is a small function that inspects scaffold files (or extracted claims) and returns `DriftIssue[]`. There are 11 existing checkers in `src/drift/checkers/` — pick the closest as a template.
+New checkers are the most newcomer-friendly contribution. A checker is a small function that inspects scaffold files (or extracted claims) and returns `DriftIssue[]`. There are 12 existing checkers in `src/drift/checkers/` — pick the closest as a template.
 
 1. **Create `src/drift/checkers/<name>.ts`.** There are two shapes:
    - **Claim-based** — operates on extracted claims, e.g. `checkPaths(claims, projectRoot, scaffoldRoot)` in `path.ts`.

README.md

@@ -96,7 +96,7 @@ Editable source: [docs/diagrams/context-routing.excalidraw](docs/diagrams/contex
 
 ## Drift Detection
 
-Eleven checkers validate your scaffold against the real codebase. Zero tokens, zero AI.
+Twelve checkers validate your scaffold against the real codebase. Zero tokens, zero AI.
 
 | Checker | What it catches |
 |---------|----------------|
@@ -111,6 +111,7 @@ Eleven checkers validate your scaffold against the real codebase. Zero tokens, z
 | **tool-config-sync** | Installed AI tool config files (e.g. `CLAUDE.md`, `.cursorrules`) out of sync with each other |
 | **todo-fixme** | Unresolved `TODO` / `FIXME` markers left in scaffold markdown |
 | **broken-link** | Markdown links to local files that do not exist on disk |
+| **stale-pattern** | Pattern files not linked from `ROUTER.md` or `context/*.md` |
 
 Scoring starts at 100. mex deducts 10 per error, 3 per warning, and 1 per info.
 

src/drift/checkers/stale-pattern.ts

@@ -11,7 +11,11 @@ export function checkStalePatterns(
   projectRoot: string,
   scaffoldRoot: string,
 ): DriftIssue[] {
-  const patternsDir = resolve(scaffoldRoot, "patterns");
+  // Try scaffold root first (deployed as .mex/), then project root
+  let patternsDir = resolve(scaffoldRoot, "patterns");
+  if (!existsSync(patternsDir)) {
+    patternsDir = resolve(projectRoot, "patterns");
+  }
   if (!existsSync(patternsDir)) return [];
 
   const patternFiles = globSync("*.md", { cwd: patternsDir }).filter(
@@ -20,12 +24,11 @@ export function checkStalePatterns(
   if (patternFiles.length === 0) return [];
 
   const referenced = new Set<string>();
-  const sources = [
-    resolve(scaffoldRoot, "ROUTER.md"),
-    ...globSync("*.md", { cwd: resolve(scaffoldRoot, "context") }).map((f) =>
-      resolve(scaffoldRoot, "context", f),
-    ),
-  ];
+  const contextDir = resolve(scaffoldRoot, "context");
+  const contextSources = existsSync(contextDir)
+    ? globSync("*.md", { cwd: contextDir }).map((f) => resolve(contextDir, f))
+    : [];
+  const sources = [resolve(scaffoldRoot, "ROUTER.md"), ...contextSources];
 
   for (const filePath of sources) {
     if (!existsSync(filePath)) continue;

src/reporter.ts

@@ -137,6 +137,8 @@ function remediationFor(code: DriftIssue["code"]): string | null {
       return "Resolve the TODO/FIXME or remove the marker from the scaffold.";
     case "BROKEN_LINK":
       return "Fix the link target path or remove the broken Markdown link.";
+    case "STALE_PATTERN":
+      return "Link the pattern from ROUTER.md or a context/*.md file so agents can discover it.";
     default:
       return null;
   }

test/checkers.test.ts

@@ -570,4 +570,17 @@ describe("checkStalePatterns", () => {
     const issues = checkStalePatterns(tmpDir, tmpDir);
     expect(issues).toHaveLength(0);
   });
+
+  it("still flags patterns only listed in INDEX.md (index-sync covers INDEX ↔ files)", () => {
+    mkdirSync(join(tmpDir, "patterns"), { recursive: true });
+    writeFileSync(join(tmpDir, "ROUTER.md"), "# Router\n");
+    writeFileSync(
+      join(tmpDir, "patterns/INDEX.md"),
+      "| [indexed-only.md](indexed-only.md) | Indexed |\n",
+    );
+    writeFileSync(join(tmpDir, "patterns/indexed-only.md"), "# Indexed only\n");
+    const issues = checkStalePatterns(tmpDir, tmpDir);
+    expect(issues).toHaveLength(1);
+    expect(issues[0].file).toBe("patterns/indexed-only.md");
+  });
 });