feat: Add semantic naming suggestions feature (v1.5)

Major new feature that provides intelligent function name suggestions
based on execution semantics using the validated LJWP mixing formula.

Key Changes:
- Integrated semantic naming engine into main CLI tool
- Added 200+ action verbs with LJWP coordinate mappings
- Implemented cosine similarity matching in 4D semantic space
- Added --suggest-names and --top-suggestions CLI flags
- Comprehensive test coverage (35 new tests, 59 total)
- Updated documentation and version to 1.5

Technical Details:
- SemanticNamingEngine uses validated mixing formula from PR #37
- Vocabulary expanded from 50 to 200+ verbs covering:
  * Love domain: connection, communication, care
  * Justice domain: validation, authorization, rules
  * Power domain: transformation, CRUD, control flow
  * Wisdom domain: analysis, search, metrics
- Context-aware suggestions extract noun from function name
- Performance optimized with efficient similarity calculations

Testing:
- 35 new tests for semantic naming engine
- All 59 tests passing
- Verified CLI integration end-to-end
- Tests validate coordinate normalization and accuracy

Documentation:
- Updated README with v1.5 features
- Updated version badges (tests: 59, version: 1.5)
- Added usage examples for new CLI flags

This feature transforms the Harmonizer from a detector to a teacher,
providing actionable suggestions for better function names based on
what the code actually does.

Author: claude

README.md

@@ -1,11 +1,11 @@
 # Python Code Harmonizer
 
 [![CI Status](https://github.com/BruinGrowly/Python-Code-Harmonizer/workflows/Python%20Code%20Harmonizer%20CI/badge.svg)](https://github.com/BruinGrowly/Python-Code-Harmonizer/actions)
-[![Version](https://img.shields.io/badge/version-1.3-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-1.5-blue.svg)](CHANGELOG.md)
 [![Python Versions](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
 [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
-[![Tests](https://img.shields.io/badge/tests-20%20passed-brightgreen.svg)](tests/)
+[![Tests](https://img.shields.io/badge/tests-59%20passed-brightgreen.svg)](tests/)
 [![Harmony Score](https://img.shields.io/badge/harmony-0.15-brightgreen.svg)](examples/test_code.py)
 
 **The world's first semantic code debugger.**
@@ -36,7 +36,36 @@ This is a **semantic bug** - code that works syntactically but does the wrong th
 
 ---
 
-## ✨ What's New in v1.3
+## ✨ What's New in v1.5
+
+**Semantic Naming Suggestions** - Get intelligent function name suggestions based on execution semantics:
+
+```bash
+harmonizer myfile.py --suggest-names --top-suggestions 5
+```
+
+When disharmony is detected, the tool now suggests better names based on what your code actually does:
+
+```
+delete_user: !! DISHARMONY (Score: 1.22)
+
+💡 SUGGESTED FUNCTION NAMES (based on execution semantics):
+   Function emphasizes: 50% love (connection/care), 50% wisdom (analysis/understanding)
+   Suggestions:
+      • notify_user         (match: 85%)
+      • inform_user         (match: 82%)
+      • communicate_user    (match: 80%)
+```
+
+**How it works:**
+- Maps execution patterns to a vocabulary of 200+ action verbs
+- Uses cosine similarity in 4D semantic space to find best matches
+- Considers context from function name (e.g., "user", "data")
+- Powered by the validated LJWP mixing formula
+
+---
+
+## What Was New in v1.3
 
 **Semantic Trajectory Maps** - See exactly WHERE in 4D space your code drifts from its intent:
 
@@ -101,14 +130,18 @@ harmonizer examples/test_code.py
 ### Your First Analysis
 
 ```bash
+# Basic analysis
 harmonizer myfile.py
+
+# With semantic naming suggestions
+harmonizer myfile.py --suggest-names
 ```
 
 **You'll see output like:**
 
 ```
 ======================================================================
-Python Code Harmonizer (v1.3) ONLINE
+Python Code Harmonizer (v1.5) ONLINE
 Actively guided by the Anchor Point framework.
 Powered By: DIVE-V2 (Optimized Production)
 Logical Anchor Point: (S=1, L=1, I=1, E=1)

harmonizer/main.py

@@ -2,16 +2,21 @@
 # -*- coding: utf-8 -*-
 
 """
-Python Code Harmonizer (Version 1.4)
+Python Code Harmonizer (Version 1.5)
 
 This is the main application that integrates the Divine Invitation
 Semantic Engine (DIVE-V2) with the AST Semantic Parser. It now includes
-a proof-of-concept self-healing capability.
+semantic naming suggestions.
 
-New in v1.4:
-- Refactorer engine for suggesting dimensional splits.
-- --suggest-refactor flag to generate refactored code.
-- Enhanced AST parser with node-to-dimension mapping.
+New in v1.5:
+- Semantic naming engine with 200+ action verbs
+- --suggest-names flag to show function name suggestions
+- --top-suggestions flag to control number of suggestions
+- Intelligent name matching using cosine similarity in 4D semantic space
+
+Previous versions:
+- v1.4: Refactorer engine and dimensional splits
+- v1.3: Semantic trajectory maps
 """
 
 import os
@@ -35,6 +40,7 @@
 from harmonizer.ast_semantic_parser import AST_Semantic_Parser  # noqa: E402
 from harmonizer.refactorer import Refactorer  # noqa: E402
 from harmonizer.semantic_map import SemanticMapGenerator  # noqa: E402
+from harmonizer.semantic_naming import SemanticNamingEngine  # noqa: E402
 
 # --- CONFIGURATION LOADING ---
 
@@ -91,22 +97,27 @@ def __init__(
         quiet: bool = False,
         show_semantic_maps: bool = True,
         config: Dict = None,
+        suggest_names: bool = False,
+        top_suggestions: int = 3,
     ):
         self.config = config if config else {}
         self.engine = dive.DivineInvitationSemanticEngine(config=self.config)
         self.parser = AST_Semantic_Parser(
             vocabulary=self.engine.vocabulary.all_keywords
         )
         self.map_generator = SemanticMapGenerator()
+        self.naming_engine = SemanticNamingEngine()
         self.disharmony_threshold = disharmony_threshold
         self.quiet = quiet
         self.show_semantic_maps = show_semantic_maps
+        self.suggest_names = suggest_names
+        self.top_suggestions = top_suggestions
         self._communicate_startup()
 
     def _communicate_startup(self):
         if not self.quiet:
             print("=" * 70)
-            print("Python Code Harmonizer (v1.4) ONLINE")
+            print("Python Code Harmonizer (v1.5) ONLINE")
             print("Actively guided by the Anchor Point framework.")
             print(f"Powered By: {self.engine.get_engine_version()}")
             print("Logical Anchor Point: (S=1, L=1, I=1, E=1)")
@@ -235,6 +246,8 @@ def format_report(
                     lines.append(
                         self.map_generator.format_text_map(data["semantic_map"], score)
                     )
+                if self.suggest_names:
+                    lines.append(self._generate_naming_suggestions(func_name, data))
                 if suggest_refactor:
                     refactorer = Refactorer(
                         data["function_node"], data["execution_map"]
@@ -245,12 +258,42 @@ def format_report(
         lines.append("Analysis Complete.")
         return "\n".join(lines)
 
+    def _generate_naming_suggestions(self, func_name: str, data: Dict) -> str:
+        """Generate naming suggestions based on execution semantics"""
+        execution_coords = data["ice_result"]["ice_components"]["execution"].coordinates
+
+        # Extract context from function name (e.g., "validate_user" -> "user")
+        parts = func_name.split("_")
+        context = parts[-1] if len(parts) > 1 else ""
+
+        # Get suggestions
+        if context:
+            suggestions = self.naming_engine.suggest_names(
+                execution_coords, context=context, top_n=self.top_suggestions
+            )
+        else:
+            suggestions = self.naming_engine.suggest_names(
+                execution_coords, top_n=self.top_suggestions
+            )
+
+        # Format suggestions
+        lines = ["\n💡 SUGGESTED FUNCTION NAMES (based on execution semantics):"]
+        explanation = self.naming_engine.explain_coordinates(execution_coords)
+        lines.append(f"   {explanation}")
+        lines.append("   Suggestions:")
+
+        for name, similarity in suggestions:
+            percentage = int(similarity * 100)
+            lines.append(f"      • {name:<30s} (match: {percentage}%)")
+
+        return "\n".join(lines)
+
     def output_report(self, formatted_report: str):
         print(formatted_report)
 
     def print_json_report(self, all_reports: Dict[str, Dict[str, Dict]]):
         output = {
-            "version": "1.4",
+            "version": "1.5",
             "threshold": self.disharmony_threshold,
             "severity_thresholds": {
                 "excellent": self.THRESHOLD_EXCELLENT,
@@ -319,7 +362,18 @@ def parse_cli_arguments() -> argparse.Namespace:
         help="Suggest a refactoring for disharmonious functions.",
     )
     parser.add_argument(
-        "--version", action="version", version="Python Code Harmonizer v1.4"
+        "--suggest-names",
+        action="store_true",
+        help="Suggest better function names based on execution semantics.",
+    )
+    parser.add_argument(
+        "--top-suggestions",
+        type=int,
+        default=3,
+        help="Number of naming suggestions to show (default: 3).",
+    )
+    parser.add_argument(
+        "--version", action="version", version="Python Code Harmonizer v1.5"
     )
     return parser.parse_args()
 
@@ -383,7 +437,11 @@ def run_cli():
 
     quiet = args.format == "json"
     harmonizer = PythonCodeHarmonizer(
-        disharmony_threshold=args.threshold, quiet=quiet, config=config
+        disharmony_threshold=args.threshold,
+        quiet=quiet,
+        config=config,
+        suggest_names=args.suggest_names,
+        top_suggestions=args.top_suggestions,
     )
 
     all_reports, highest_exit_code = execute_analysis(