From 65d3525d80cba355814f7fe7fd02d308164bd0ac Mon Sep 17 00:00:00 2001
From: John O'Keefe <jrokeefe@protonmail.com>
Date: Mon, 2 Feb 2026 11:34:51 -0500
Subject: [PATCH] feat: Add documentation completeness validation

Check 16: Documentation Completeness Validation
- Detect orphaned documentation (files without proper markdown structure)
- Check for inconsistent file naming patterns in docs/api/
- Validate markdown formatting compliance
- Ensure documentation maintains structural integrity

This final check completes the comprehensive documentation validation
suite, ensuring all documentation files follow proper formatting
and naming conventions per PROJECT_GUIDELINES.md standards.
---
 scripts/verify-guidelines.sh | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/scripts/verify-guidelines.sh b/scripts/verify-guidelines.sh
index 030192f..bccaeea 100755
--- a/scripts/verify-guidelines.sh
+++ b/scripts/verify-guidelines.sh
@@ -418,6 +418,33 @@ else
     success_msg "Git analysis skipped"
 fi
 
+###############################################################################
+## Check 16: Documentation Completeness Validation
+###############################################################################
+section "Documentation: Completeness Validation"
+
+echo "Checking for orphaned documentation..."
+if [ -d "docs" ]; then
+    # Check for API docs without corresponding structure
+    ORPHANED_API_FILES=$(find docs/api -name "*.md" -exec grep -L "## \|### " {} \; 2>/dev/null | wc -l)
+    if [ "$ORPHANED_API_FILES" -gt 0 ]; then
+        warning_msg "Found $ORPHANED_API_FILES API docs without proper markdown structure"
+    else
+        success_msg "API documentation structure appears valid"
+    fi
+fi
+
+echo "Checking documentation file naming consistency..."
+if [ -d "docs/api" ]; then
+    # Check for inconsistent naming patterns
+    LOWERCASE_FILES=$(find docs/api -name "*.md" | grep -E "[A-Z]" | wc -l)
+    if [ "$LOWERCASE_FILES" -gt 0 ]; then
+        warning_msg "Found $LOWERCASE_FILES API documentation files with uppercase letters"
+    else
+        success_msg "Documentation file naming appears consistent"
+    fi
+fi
+
 ###############################################################################
 ## Summary
 ###############################################################################