feat: Add HeadyLens module and optimize drift check

HeadySystems_v13/apps/heady_lens/README.md

@@ -0,0 +1,6 @@
+# HeadyLens
+
+Transparency module to capture and report system explanations.
+
+## Overview
+HeadyLens is responsible for providing transparency into the system's operations, capturing explanations, and reporting them.

HeadySystems_v13/apps/heady_lens/__init__.py

@@ -0,0 +1,3 @@
+"""
+HeadyLens Module
+"""

HeadySystems_v13/apps/heady_lens/core.py

@@ -0,0 +1,37 @@
+"""
+Core HeadyLens Logic
+"""
+import time
+from typing import Dict, List, Any
+
+class HeadyLens:
+    """
+    Captures and reports system explanations.
+    """
+    def __init__(self):
+        self.explanations: List[Dict[str, Any]] = []
+
+    def capture(self, source: str, message: str, metadata: Dict[str, Any] = None):
+        """
+        Captures an explanation event.
+        """
+        event = {
+            "timestamp": time.time(),
+            "source": source,
+            "message": message,
+            "metadata": metadata or {}
+        }
+        self.explanations.append(event)
+        print(f"[HeadyLens] Captured: {message} from {source}")
+
+    def report(self) -> List[Dict[str, Any]]:
+        """
+        Returns all captured explanations.
+        """
+        return self.explanations
+
+    def clear(self):
+        """
+        Clears the explanation log.
+        """
+        self.explanations = []

HeadySystems_v13/apps/heady_lens/demo.py

@@ -0,0 +1,33 @@
+"""
+HeadyLens Demo
+"""
+import sys
+import os
+
+# Ensure we can import from the module
+# Appending HeadySystems_v13 root to sys.path
+current_dir = os.path.dirname(os.path.abspath(__file__))
+repo_root = os.path.abspath(os.path.join(current_dir, "../../../"))
+if repo_root not in sys.path:
+    sys.path.append(repo_root)
+
+try:
+    from HeadySystems_v13.apps.heady_lens.core import HeadyLens
+except ImportError:
+    # Fallback if run from different context
+    from apps.heady_lens.core import HeadyLens
+
+def main():
+    print("Initializing HeadyLens Demo...")
+    lens = HeadyLens()
+
+    lens.capture("SystemBoot", "System initialized successfully.")
+    lens.capture("AuthModule", "User logged in.", {"user_id": 42})
+
+    report = lens.report()
+    print("\n--- HeadyLens Report ---")
+    for item in report:
+        print(f"[{item['timestamp']}] {item['source']}: {item['message']}")
+
+if __name__ == "__main__":
+    main()

HeadySystems_v13/scripts/docs/check_drift.py

@@ -18,7 +18,7 @@ def main() -> int:
         return 1
 
     changed = [line.strip() for line in diff.splitlines() if line.strip()]
-    watched_changes = [path for path in changed if any(path.startswith(prefix) for prefix in WATCH_PATHS)]
+    watched_changes = [path for path in changed if path.startswith(tuple(WATCH_PATHS))]
     if watched_changes and "docs/" not in " ".join(changed):
         print("Docs drift detected: operational changes without docs updates.")
         return 1