DEVX-64: feat: add skip_ref_prefixes config to check_agent_docs

src/devx/tools/check_agent_docs.py

@@ -117,6 +117,7 @@ def _check_file(
     legitimate_indicators: list[str],
     repo_path_prefixes: list[str],
     min_path_ref_length: int,
+    skip_ref_prefixes: list[str],
 ) -> list[str]:
     """Check a single file for stale references."""
     issues: list[str] = []
@@ -147,6 +148,9 @@ def _check_file(
             # Only check references that look like repo paths
             if not any(ref.startswith(prefix) for prefix in repo_path_prefixes):
                 continue
+            # Skip references matching configured skip prefixes (e.g. aspirational test files)
+            if any(ref.startswith(prefix) for prefix in skip_ref_prefixes):
+                continue
             candidate = repo_root / ref
             if not candidate.exists():
                 issues.append(f"{rel_path}:{lineno}: references non-existent file '{ref}'")
@@ -179,6 +183,9 @@ def cli() -> None:
     min_len_raw = cfg.get("min_path_ref_length")
     min_path_ref_length: int = int(min_len_raw) if isinstance(min_len_raw, int) else MIN_PATH_REF_LENGTH_DEFAULT
 
+    skip_prefixes_raw = cfg.get("skip_ref_prefixes", [])
+    skip_ref_prefixes: list[str] = [str(d) for d in skip_prefixes_raw] if isinstance(skip_prefixes_raw, list) else []
+
     deleted_files: set[str] = set()
     deleted_raw = cfg.get("deleted_files", [])
     if isinstance(deleted_raw, list):
@@ -209,6 +216,7 @@ def cli() -> None:
             legitimate_indicators,
             repo_path_prefixes,
             min_path_ref_length,
+            skip_ref_prefixes,
         )
         all_issues.extend(issues)