docs: initial @soul mapping for Apparatus Verification

agent/conscience_mapping.py

@@ -0,0 +1,6 @@
+"""
+@soul:honesty.grounding Grounding before generation. Consult verified sources before pattern-matching.
+@soul:honesty.source_distinction Source distinction. Every claim must point to a verified source.
+@soul:honesty.audit_trail The audit trail. Every response is logged with inputs and confidence.
+"""
+# This file serves as a registry for the Conscience Validator to prove the apparatus exists.

tools/conscience_validator.py

@@ -0,0 +1,61 @@
+"""
+Conscience Validator — The Apparatus of Honesty.
+
+Scans the codebase for @soul tags and generates a report mapping
+the code's implementation to the principles defined in SOUL.md.
+"""
+
+import os
+import re
+from pathlib import Path
+from typing import Dict, List
+
+class ConscienceValidator:
+    def __init__(self, root_dir: str = "."):
+        self.root_dir = Path(root_dir)
+        self.soul_map = {}
+
+    def scan(self) -> Dict[str, List[Dict[str, str]]]:
+        """Scans all .py and .ts files for @soul tags."""
+        pattern = re.compile(r"@soul:([w.]+)s+(.*)")
+        
+        for path in self.root_dir.rglob("*"):
+            if path.suffix not in [".py", ".ts", ".tsx", ".js"]:
+                continue
+            if "node_modules" in str(path) or "dist" in str(path):
+                continue
+                
+            try:
+                with open(path, "r", encoding="utf-8") as f:
+                    for i, line in enumerate(f, 1):
+                        match = pattern.search(line)
+                        if match:
+                            tag = match.group(1)
+                            desc = match.group(2)
+                            if tag not in self.soul_map:
+                                self.soul_map[tag] = []
+                            self.soul_map[tag].append({
+                                "file": str(path),
+                                "line": i,
+                                "description": desc
+                            })
+            except Exception:
+                continue
+        return self.soul_map
+
+    def generate_report(self) -> str:
+        data = self.scan()
+        report = "# Sovereign Conscience Report\n\n"
+        report += "This report maps the code's 'Apparatus' to the principles in SOUL.md.\n\n"
+        
+        for tag in sorted(data.keys()):
+            report += f"## {tag.replace('.', ' > ').title()}\n"
+            for entry in data[tag]:
+                report += f"- **{entry['file']}:{entry['line']}**: {entry['description']}\n"
+            report += "\n"
+            
+        return report
+
+if __name__ == "__main__":
+    validator = ConscienceValidator()
+    print(validator.generate_report())