Refactor code and improve documentation

HeadySystems_v13/Heady_it1_v_1_0_0.py

@@ -6,16 +6,25 @@
 ROOT = Path(__file__).resolve().parent
 OUTPUT_DIR = ROOT / "heady_iterations" / "it1"
 
-def main():
-    OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+def generate_manifest(output_dir: Path) -> None:
+    """
+    Generates the manifest file for Iteration 1.
+
+    Args:
+        output_dir: The directory where the manifest should be written.
+    """
+    output_dir.mkdir(parents=True, exist_ok=True)
     payload = {
         "iteration": 1,
         "version": "1.0.0",
         "stage_name": "stage-1",
         "description": "Iteration 1 scaffold."
     }
-    (OUTPUT_DIR / "manifest.json").write_text(json.dumps(payload, indent=2) + "
-", encoding="utf-8")
+    (output_dir / "manifest.json").write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+
+def main() -> None:
+    """Main entry point for Iteration 1 scaffold."""
+    generate_manifest(OUTPUT_DIR)
     print(f"Iteration 1 output written to {OUTPUT_DIR}")
 
 if __name__ == "__main__":

HeadySystems_v13/Heady_it2_v_1_0_0.py

@@ -6,16 +6,25 @@
 ROOT = Path(__file__).resolve().parent
 OUTPUT_DIR = ROOT / "heady_iterations" / "it2"
 
-def main():
-    OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+def generate_manifest(output_dir: Path) -> None:
+    """
+    Generates the manifest file for Iteration 2.
+
+    Args:
+        output_dir: The directory where the manifest should be written.
+    """
+    output_dir.mkdir(parents=True, exist_ok=True)
     payload = {
         "iteration": 2,
         "version": "1.0.0",
         "stage_name": "stage-2",
         "description": "Iteration 2 scaffold."
     }
-    (OUTPUT_DIR / "manifest.json").write_text(json.dumps(payload, indent=2) + "
-", encoding="utf-8")
+    (output_dir / "manifest.json").write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+
+def main() -> None:
+    """Main entry point for Iteration 2 scaffold."""
+    generate_manifest(OUTPUT_DIR)
     print(f"Iteration 2 output written to {OUTPUT_DIR}")
 
 if __name__ == "__main__":

HeadySystems_v13/Heady_it3_v_1_0_0.py

@@ -6,16 +6,25 @@
 ROOT = Path(__file__).resolve().parent
 OUTPUT_DIR = ROOT / "heady_iterations" / "it3"
 
-def main():
-    OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+def generate_manifest(output_dir: Path) -> None:
+    """
+    Generates the manifest file for Iteration 3.
+
+    Args:
+        output_dir: The directory where the manifest should be written.
+    """
+    output_dir.mkdir(parents=True, exist_ok=True)
     payload = {
         "iteration": 3,
         "version": "1.0.0",
         "stage_name": "stage-3",
         "description": "Iteration 3 scaffold."
     }
-    (OUTPUT_DIR / "manifest.json").write_text(json.dumps(payload, indent=2) + "
-", encoding="utf-8")
+    (output_dir / "manifest.json").write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+
+def main() -> None:
+    """Main entry point for Iteration 3 scaffold."""
+    generate_manifest(OUTPUT_DIR)
     print(f"Iteration 3 output written to {OUTPUT_DIR}")
 
 if __name__ == "__main__":

HeadySystems_v13/Heady_it4_v_1_0_0.py

@@ -6,16 +6,25 @@
 ROOT = Path(__file__).resolve().parent
 OUTPUT_DIR = ROOT / "heady_iterations" / "it4"
 
-def main():
-    OUTPUT_DIR.mkdir(parents=True, exist_ok=True)
+def generate_manifest(output_dir: Path) -> None:
+    """
+    Generates the manifest file for Iteration 4.
+
+    Args:
+        output_dir: The directory where the manifest should be written.
+    """
+    output_dir.mkdir(parents=True, exist_ok=True)
     payload = {
         "iteration": 4,
         "version": "1.0.0",
         "stage_name": "stage-4",
         "description": "Iteration 4 scaffold."
     }
-    (OUTPUT_DIR / "manifest.json").write_text(json.dumps(payload, indent=2) + "
-", encoding="utf-8")
+    (output_dir / "manifest.json").write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
+
+def main() -> None:
+    """Main entry point for Iteration 4 scaffold."""
+    generate_manifest(OUTPUT_DIR)
     print(f"Iteration 4 output written to {OUTPUT_DIR}")
 
 if __name__ == "__main__":

HeadySystems_v13/codex_builder_v13.py

@@ -25,8 +25,20 @@
 DESTRUCTIVE_PATTERNS = ["write", "delete", "rm", "exec", "shell", "edit_file"]
 
 class AtomicWriter:
+    """Handles atomic file writing operations to ensure data integrity."""
+
     @staticmethod
     def write_json(path: str, data: Dict[str, Any]) -> str:
+        """
+        Writes a JSON object to a file atomically.
+
+        Args:
+            path: The path to the file to write.
+            data: The JSON serializable data to write.
+
+        Returns:
+            The SHA256 hash of the written content.
+        """
         # FIX: Ensure directory defaults to '.' if empty to prevent cross-device link errors
         directory = os.path.dirname(path)
         if not directory:
@@ -56,6 +68,16 @@ def write_json(path: str, data: Dict[str, Any]) -> str:
 
     @staticmethod
     def write_text(path: str, content: str) -> str:
+        """
+        Writes text content to a file atomically.
+
+        Args:
+            path: The path to the file to write.
+            content: The text content to write.
+
+        Returns:
+            The SHA256 hash of the written content.
+        """
         directory = os.path.dirname(path)
         if not directory:
             directory = "."
@@ -81,8 +103,16 @@ def write_text(path: str, content: str) -> str:
         return file_hash
 
 class GovernanceGenerator:
+    """Generates governance configuration."""
+
     @staticmethod
     def generate_lock_file() -> Dict[str, Any]:
+        """
+        Generates the governance lock file content.
+
+        Returns:
+            A dictionary containing the governance lock configuration.
+        """
         return {
             "mode": "release",
             "repo": "HeadyConnection-Org/governance",
@@ -93,8 +123,16 @@ def generate_lock_file() -> Dict[str, Any]:
         }
 
 class GatewayConfigurator:
+    """Generates gateway configuration."""
+
     @staticmethod
     def generate_config() -> Dict[str, Any]:
+        """
+        Generates the gateway configuration.
+
+        Returns:
+            A dictionary containing the gateway configuration.
+        """
         return {
             "bind": "127.0.0.1",
             "allowHosts": ["127.0.0.1", "localhost"],
@@ -118,13 +156,13 @@ def generate_config() -> Dict[str, Any]:
             ]
         }
 
-def main():
-    print(f"Starting Codex Builder {GENERATOR_VERSION}...")
-
-    # Use timezone-aware UTC datetime
-    manifest = {"files": [], "generated_at": datetime.datetime.now(datetime.timezone.utc).isoformat()}
+def generate_registry() -> str:
+    """
+    Generates the REGISTRY.json file.
 
-    # 1. Registry
+    Returns:
+        The SHA256 hash of the generated file.
+    """
     registry_data = {
         "schema_version": "1.0.0",
         "as_of_date": datetime.datetime.now(datetime.timezone.utc).strftime("%Y-%m-%d"),
@@ -139,20 +177,35 @@ def main():
             "audit_enabled": True
         }
     }
-    h_reg = AtomicWriter.write_json("REGISTRY.json", registry_data)
-    manifest["files"].append({"path": "REGISTRY.json", "sha256": h_reg})
+    return AtomicWriter.write_json("REGISTRY.json", registry_data)
 
-    # 2. Governance Lock
+def generate_governance_lock() -> str:
+    """
+    Generates the governance.lock file.
+
+    Returns:
+        The SHA256 hash of the generated file.
+    """
     gov_lock = GovernanceGenerator.generate_lock_file()
-    h_gov = AtomicWriter.write_json("governance.lock", gov_lock)
-    manifest["files"].append({"path": "governance.lock", "sha256": h_gov})
+    return AtomicWriter.write_json("governance.lock", gov_lock)
 
-    # 3. Gateway Config
+def generate_gateway_config() -> str:
+    """
+    Generates the mcp-gateway-config.json file.
+
+    Returns:
+        The SHA256 hash of the generated file.
+    """
     gateway_conf = GatewayConfigurator.generate_config()
-    h_gw = AtomicWriter.write_json("mcp-gateway-config.json", gateway_conf)
-    manifest["files"].append({"path": "mcp-gateway-config.json", "sha256": h_gw})
+    return AtomicWriter.write_json("mcp-gateway-config.json", gateway_conf)
 
-    # 4. Directories
+def create_directories(manifest: Dict[str, Any]) -> None:
+    """
+    Creates necessary directories and .gitkeep files.
+
+    Args:
+        manifest: The manifest dictionary to update with created files.
+    """
     dirs_to_create = [
         "prompts/registry",
         "prompts/receipts",
@@ -167,7 +220,13 @@ def main():
             h_keep = AtomicWriter.write_text(keep_path, "")
             manifest["files"].append({"path": keep_path, "sha256": h_keep})
 
-    # 5. Context Docs
+def generate_context_docs() -> str:
+    """
+    Generates the CONTEXT.md file.
+
+    Returns:
+        The SHA256 hash of the generated file.
+    """
     context_md = f"""# Heady Sovereign Node
 > Generated by {GENERATOR_NAME} {GENERATOR_VERSION}
 > DO NOT EDIT. This file is deterministically derived from REGISTRY.json.
@@ -182,7 +241,32 @@ def main():
 * **Governance:** Locked (v1.2.0)
 * **PromptOps:** Enforced
 """
-    h_ctx = AtomicWriter.write_text("CONTEXT.md", context_md)
+    return AtomicWriter.write_text("CONTEXT.md", context_md)
+
+def main():
+    """Main entry point for the Codex Builder."""
+    print(f"Starting Codex Builder {GENERATOR_VERSION}...")
+
+    # Use timezone-aware UTC datetime
+    manifest = {"files": [], "generated_at": datetime.datetime.now(datetime.timezone.utc).isoformat()}
+
+    # 1. Registry
+    h_reg = generate_registry()
+    manifest["files"].append({"path": "REGISTRY.json", "sha256": h_reg})
+
+    # 2. Governance Lock
+    h_gov = generate_governance_lock()
+    manifest["files"].append({"path": "governance.lock", "sha256": h_gov})
+
+    # 3. Gateway Config
+    h_gw = generate_gateway_config()
+    manifest["files"].append({"path": "mcp-gateway-config.json", "sha256": h_gw})
+
+    # 4. Directories
+    create_directories(manifest)
+
+    # 5. Context Docs
+    h_ctx = generate_context_docs()
     manifest["files"].append({"path": "CONTEXT.md", "sha256": h_ctx})
 
     # 6. Manifest

HeadySystems_v13/docs/patents/IDF-20260122-01-heady-nature.md

@@ -0,0 +1,5 @@
+# Heady Nature
+
+**Patent Pending**
+
+This document describes the Heady Nature component of the Heady System.

HeadySystems_v13/ops/spire/register_workloads.sh

@@ -1,2 +1,23 @@
 #!/usr/bin/env bash
-echo "[spire] Workload registration stub"
+# Registers workloads for each application in the HeadySystems apps directory.
+# Enforces vertical isolation by assigning unique SPIFFE IDs.
+
+APPS_DIR="$(dirname "$0")/../../apps"
+
+if [ ! -d "$APPS_DIR" ]; then
+    echo "Error: apps directory not found at $APPS_DIR"
+    exit 1
+fi
+
+echo "[spire] Starting workload registration..."
+
+for app in "$APPS_DIR"/*; do
+    if [ -d "$app" ]; then
+        app_name=$(basename "$app")
+        spiffe_id="spiffe://headysystems.com/ns/default/sa/$app_name"
+        echo "[spire] Registering workload: $app_name -> $spiffe_id"
+        # In a real implementation, this would call 'spire-server entry create ...'
+    fi
+done
+
+echo "[spire] Workload registration complete."