synapse-hub 2.2.2 → 2.2.3

package/tools/infer_linter.py

@@ -154,21 +154,40 @@ def analyze_script(file_path):
 
 
 def run_infer_linter(target_dir=None):
-    """Scans all Groovy test scripts in target_dir or Scripts/."""
-    scan_dir = target_dir or SCRIPTS_DIR
-    if not os.path.exists(scan_dir):
-        script_files = []
-    elif os.path.isfile(scan_dir):
-        script_files = [scan_dir]
+    """Scans test scripts across Groovy, TypeScript, JavaScript, Python, and Java."""
+    EXTENSIONS = ("*.groovy", "*.ts", "*.js", "*.py", "*.java")
+
+    if target_dir:
+        if os.path.isfile(target_dir):
+            script_files = [target_dir]
+            scan_dir = os.path.dirname(target_dir)
+        elif os.path.isdir(target_dir):
+            scan_dir = target_dir
+            script_files = []
+            for ext in EXTENSIONS:
+                script_files.extend(glob.glob(os.path.join(scan_dir, "**", ext), recursive=True))
+        else:
+            scan_dir = target_dir
+            script_files = []
     else:
-        script_files = glob.glob(os.path.join(scan_dir, "**", "*.groovy"), recursive=True)
+        # Search candidate directories across test frameworks (Katalon, Playwright, Pytest, Cypress)
+        script_files = []
+        scan_dir = SCRIPTS_DIR
+        for cand in ["Scripts", "tests", "test", "e2e", "specs", "cypress"]:
+            cand_path = os.path.join(REPO_ROOT, cand)
+            if os.path.isdir(cand_path):
+                for ext in EXTENSIONS:
+                    script_files.extend(glob.glob(os.path.join(cand_path, "**", ext), recursive=True))
+                if script_files:
+                    scan_dir = cand_path
+                    break
 
     results = []
     critical_count = 0
     warning_count = 0
     clean_count = 0
 
-    for s in sorted(script_files):
+    for s in sorted(set(script_files)):
         res = analyze_script(s)
         results.append(res)
         crit = sum(1 for d in res["defects"] if d["severity"] == "CRITICAL")
@@ -179,17 +198,28 @@ def run_infer_linter(target_dir=None):
             clean_count += 1
 
     total_scripts = len(script_files)
-    health_score = 100.0 if total_scripts == 0 else (((total_scripts - critical_count) / total_scripts) * 100)
-    clean_pct = (clean_count / total_scripts * 100) if total_scripts > 0 else 100.0
+    if total_scripts == 0:
+        health_score = 0.0
+        clean_pct = 0.0
+    else:
+        health_score = round(((total_scripts - critical_count) / total_scripts) * 100, 1)
+        clean_pct = round((clean_count / total_scripts) * 100, 1)
 
     print(f"\n{BOLD}{CYAN}======================================================================{RESET}")
     print(f"{BOLD}{CYAN}    ENTERPRISE STATIC DEFECT & FAKE-PASS SENTINEL (Meta Infer-Style)        {RESET}")
     print(f"{BOLD}{CYAN}======================================================================{RESET}")
-    print(f"  Target Scope            : {total_scripts} Groovy Test Scripts in {os.path.basename(scan_dir)}/")
-    print(f"  Critical Defects        : {RED if critical_count > 0 else GREEN}{critical_count}{RESET} (Swallowed exceptions, empty scripts)")
-    print(f"  Warnings / Suggestions  : {YELLOW if warning_count > 0 else GREEN}{warning_count}{RESET} (Missing explicit asserts, excessive delays)")
-    print(f"  Clean Scripts           : {GREEN}{clean_count}/{total_scripts} ({clean_pct:.1f}%){RESET}")
-    print(f"  Codebase Health Score   : {GREEN if health_score == 100 else YELLOW}{health_score:.1f}%{RESET}")
+    if total_scripts == 0:
+        print(f"  Target Scope            : 0 Test Scripts discovered in {os.path.basename(scan_dir)}/ (No tests found)")
+        print(f"  Critical Defects        : {GREEN}0{RESET}")
+        print(f"  Warnings / Suggestions  : {GREEN}0{RESET}")
+        print(f"  Clean Scripts           : 0/0 (N/A)")
+        print(f"  Codebase Health Score   : {YELLOW}N/A (0 test scripts discovered){RESET}")
+    else:
+        print(f"  Target Scope            : {total_scripts} Test Scripts in {os.path.basename(scan_dir)}/ (Polyglot)")
+        print(f"  Critical Defects        : {RED if critical_count > 0 else GREEN}{critical_count}{RESET} (Swallowed exceptions, empty scripts)")
+        print(f"  Warnings / Suggestions  : {YELLOW if warning_count > 0 else GREEN}{warning_count}{RESET} (Missing explicit asserts, excessive delays)")
+        print(f"  Clean Scripts           : {GREEN}{clean_count}/{total_scripts} ({clean_pct:.1f}%){RESET}")
+        print(f"  Codebase Health Score   : {GREEN if health_score == 100 else YELLOW}{health_score:.1f}%{RESET}")
     print(f"{BOLD}{CYAN}======================================================================{RESET}\n")
 
     # Print defect breakdown if any

package/tools/mcp_excel_server.ps1

@@ -160,7 +160,7 @@ while (($line = $inputReader.ReadLine()) -ne $null) {
                 result = @{
                     protocolVersion = "2024-11-05"
                     capabilities = @{ tools = @{} }
-                    serverInfo = @{ name = "excel-qa-mcp-server"; version = "2.2.2" }
+                    serverInfo = @{ name = "excel-qa-mcp-server"; version = "2.2.3" }
                 }
             }
             [System.Console]::Out.WriteLine(($resp | ConvertTo-Json -Compress -Depth 10))

package/tools/mcp_server.py

@@ -43,7 +43,7 @@ import traffic_session_converter
 import visual_som_helper
 
 SERVER_NAME = "enterprise-agent-qa"
-SERVER_VERSION = "2.2.2"
+SERVER_VERSION = "2.2.3"
 
 MCP_TOOLS = [
     {

package/tools/micro_mutator.py

@@ -68,7 +68,7 @@ ASSERTION_PATTERN = re.compile(
 
 # Tautological / fake assertions that do not test application logic
 TAUTOLOGY_PATTERN = re.compile(
-    r'(?:assert\s+(?:true|1\s*==\s*1)\b|assertEquals\s*\(\s*true\s*,\s*true\s*\)|expect\s*\(\s*true\s*\)\.toBe\s*\(\s*true\s*\)|assertTrue\s*\(\s*true\s*\))',
+    r'(?:assert\s+(?:true|1\s*==\s*1)\b|assert\s+([a-zA-Z_]\w*)\s*==\s*\1\b|assertEquals\s*\(\s*([a-zA-Z_]\w*)\s*,\s*\2\s*\)|expect\s*\(\s*([a-zA-Z_]\w*)\s*\)\.toBe\s*\(\s*\3\s*\)|assertTrue\s*\(\s*true\s*\))',
     re.IGNORECASE
 )
 
@@ -195,7 +195,12 @@ def evaluate_mutants_statically(code: str, mutants: List[Dict[str, Any]]) -> Tup
     - If mutant is inside an unasserted block or swallowed exception: mutant SURVIVES.
     """
     if not mutants:
-        return mutants, 100.0
+        has_asserts = any(
+            ASSERTION_PATTERN.search(l) and not TAUTOLOGY_PATTERN.search(l)
+            for l in code.splitlines()
+            if not l.strip().startswith(("//", "#", "/*"))
+        )
+        return mutants, (100.0 if has_asserts else 0.0)
 
     lines = code.splitlines()
     has_empty_catch = bool(EMPTY_CATCH_PATTERN.search(code))
@@ -245,6 +250,55 @@ def evaluate_mutants_statically(code: str, mutants: List[Dict[str, Any]]) -> Tup
     return mutants, score
 
 
+def evaluate_mutants_dynamically(file_path: str, code: str, mutants: List[Dict[str, Any]], test_cmd: str) -> Tuple[List[Dict[str, Any]], float]:
+    """
+    Executes live mutation testing by injecting mutants into disk file and executing test_cmd.
+    If the test command fails (exit code != 0), the mutant is KILLED by the test suite.
+    If the test command passes (exit code == 0), the mutant SURVIVED (unasserted logic branch).
+    Safely restores original file content in all cases.
+    """
+    if not mutants:
+        return mutants, 0.0
+
+    killed_count = 0
+    abs_path = os.path.abspath(file_path)
+
+    try:
+        for m in mutants:
+            mutated_code = m["mutated_code"]
+            with open(abs_path, "w", encoding="utf-8") as f:
+                f.write(mutated_code)
+
+            try:
+                proc = subprocess.run(
+                    test_cmd,
+                    shell=True,
+                    capture_output=True,
+                    timeout=30,
+                    text=True
+                )
+                if proc.returncode != 0:
+                    m["status"] = "KILLED"
+                    m["reason"] = f"Dynamic test caught mutant: command failed (exit code {proc.returncode})"
+                    killed_count += 1
+                else:
+                    m["status"] = "SURVIVED"
+                    m["reason"] = "Dynamic test suite passed unconditionally: missing assertion for this mutant."
+            except subprocess.TimeoutExpired:
+                m["status"] = "KILLED"
+                m["reason"] = "Mutant triggered execution timeout (> 30s): caught by runtime guard"
+                killed_count += 1
+            except Exception as e:
+                m["status"] = "SURVIVED"
+                m["reason"] = f"Test execution error: {e}"
+    finally:
+        with open(abs_path, "w", encoding="utf-8") as f:
+            f.write(code)
+
+    score = evaluate_mutation_score(killed_count, len(mutants))
+    return mutants, score
+
+
 def scan_directory_for_mutants(target_dir: str) -> List[Dict[str, Any]]:
     """Scans target test/page scripts and generates a collection of mutants."""
     all_mutants = []
@@ -269,21 +323,23 @@ def scan_directory_for_mutants(target_dir: str) -> List[Dict[str, Any]]:
 def evaluate_target(target_path: str, min_score: float = 80.0, test_cmd: str = "") -> Dict[str, Any]:
     """
     Evaluates target file or directory for mutation robustness.
-    Returns complete mutation report dictionary.
+    Dispatches to live test execution if test_cmd is provided, or static heuristic otherwise.
     """
     target = os.path.abspath(target_path)
     all_mutants = []
+    exec_mode = "DYNAMIC" if test_cmd else "STATIC"
 
     if os.path.isfile(target):
         with open(target, "r", encoding="utf-8", errors="ignore") as f:
             code = f.read()
         mutants = generate_mutants_for_code(code, file_path=os.path.basename(target))
-        evaluated_mutants, score = evaluate_mutants_statically(code, mutants)
+        if test_cmd:
+            evaluated_mutants, score = evaluate_mutants_dynamically(target, code, mutants, test_cmd)
+        else:
+            evaluated_mutants, score = evaluate_mutants_statically(code, mutants)
         all_mutants.extend(evaluated_mutants)
     else:
-        # Directory evaluation
         valid_exts = {".groovy", ".py", ".ts", ".js"}
-        total_killed = 0
         for root, _, files in os.walk(target):
             for f in files:
                 if any(f.endswith(ext) for ext in valid_exts):
@@ -293,7 +349,10 @@ def evaluate_target(target_path: str, min_score: float = 80.0, test_cmd: str = "
                             code = fp.read()
                         rel_path = os.path.relpath(file_full, target)
                         f_mutants = generate_mutants_for_code(code, file_path=rel_path)
-                        eval_m, _ = evaluate_mutants_statically(code, f_mutants)
+                        if test_cmd:
+                            eval_m, _ = evaluate_mutants_dynamically(file_full, code, f_mutants, test_cmd)
+                        else:
+                            eval_m, _ = evaluate_mutants_statically(code, f_mutants)
                         all_mutants.extend(eval_m)
                     except Exception:
                         pass
@@ -305,6 +364,18 @@ def evaluate_target(target_path: str, min_score: float = 80.0, test_cmd: str = "
     survived = sum(1 for m in all_mutants if m["status"] == "SURVIVED")
     passed = score >= min_score
 
+    return {
+        "target": target,
+        "mode": exec_mode,
+        "total_mutants": len(all_mutants),
+        "killed": killed,
+        "survived": survived,
+        "mutation_score": score,
+        "min_score": min_score,
+        "passed": passed,
+        "mutants": all_mutants
+    }
+
     return {
         "target": target,
         "total_mutants": len(all_mutants),

package/tools/repo_map.py

@@ -21,10 +21,11 @@ HUB_ROOT = os.path.abspath(os.path.join(SCRIPT_DIR, ".."))
 OUTPUT_TXT = os.path.join(SCRIPT_DIR, "repo_map.txt")
 OUTPUT_JSON = os.path.join(SCRIPT_DIR, "repo_map.json")
 
-# Regex patterns for Groovy classes and methods
-CLASS_PATTERN = re.compile(r'^\s*(?:public\s+)?class\s+(\w+)(?:\s+extends\s+(\w+))?', re.MULTILINE)
+# Regex patterns for Groovy/Java classes and methods
+CLASS_PATTERN = re.compile(r'^\s*(?:public\s+|export\s+)?class\s+(\w+)(?:\s+extends\s+(\w+))?', re.MULTILINE)
+PY_CLASS_PATTERN = re.compile(r'^\s*class\s+(\w+)(?:\(([^)]*)\))?\s*:', re.MULTILINE)
 METHOD_PATTERN = re.compile(
-    r'^\s*(?:@\w+\s+)*(?:public\s+|protected\s+|private\s+)?(?:static\s+)?(?:def\s+|void\s+|[\w<>\[\],]+\s+)?(\w+)\s*\(([^)]*)\)\s*(?:throws\s+[\w,\s]+)?\s*\{',
+    r'^\s*(?:@\w+\s+)*(?:public\s+|protected\s+|private\s+)?(?:static\s+)?(?:async\s+)?(?:def\s+|void\s+|[\w<>\[\],]+\s+)?(\w+)\s*\(([^)]*)\)\s*(?:throws\s+[\w,\s]+)?\s*\{',
     re.MULTILINE
 )
 DOC_PATTERN = re.compile(r'/\*\*(.*?)\*/', re.DOTALL)
@@ -35,7 +36,7 @@ def resolve_target_repo(cli_target=None, cli_repo=None):
     Resolves the target repository path for repo mapping:
     1. Explicit CLI flag: --repo / --path or positional target.
     2. Environment variable: TARGET_PROJECT_DIR.
-    3. Current Working Directory (if different from Hub and has Keywords/ or Scripts/).
+    3. Current Working Directory (if different from Hub and has Keywords/, pages/, or tests/).
     4. Default fallback: QA Hub root (parent of tools/).
     """
     chosen = cli_repo or cli_target
@@ -51,14 +52,15 @@ def resolve_target_repo(cli_target=None, cli_repo=None):
 
     cwd = os.path.abspath(os.getcwd())
     if cwd.lower() != HUB_ROOT.lower():
-        if os.path.exists(os.path.join(cwd, "Keywords")) or os.path.exists(os.path.join(cwd, "Scripts")):
+        markers = ("Keywords", "Scripts", "pages", "tests", "src/pages", "e2e")
+        if any(os.path.exists(os.path.join(cwd, m)) for m in markers):
             return cwd
 
     return HUB_ROOT
 
 
 def extract_class_info(file_path, repo_root=None):
-    """Parses a Groovy file and extracts class name, parent, and exported methods."""
+    """Parses a Groovy, TypeScript, JavaScript, or Python file and extracts class name and methods."""
     with open(file_path, "r", encoding="utf-8", errors="ignore") as f:
         content = f.read()
 
@@ -68,48 +70,72 @@ def extract_class_info(file_path, repo_root=None):
     except ValueError:
         rel_path = os.path.abspath(file_path)
 
-    class_match = CLASS_PATTERN.search(content)
-    if not class_match:
-        return None
-
-    class_name = class_match.group(1)
-    extends_name = class_match.group(2) or ""
-
+    ext = os.path.splitext(file_path)[1].lower()
     methods = []
-    control_keywords = {"if", "for", "while", "switch", "catch", "synchronized"}
-
-    lines = content.splitlines()
-    for idx, line in enumerate(lines):
-        line_clean = line.strip()
-        if not line_clean or line_clean.startswith("//") or line_clean.startswith("/*") or line_clean.startswith("*"):
-            continue
-
-        # If '=' appears before '(', it's a variable assignment / constant declaration, not a method
-        if "=" in line_clean:
-            eq_pos = line_clean.find("=")
-            paren_pos = line_clean.find("(")
-            if paren_pos != -1 and eq_pos < paren_pos:
+    control_keywords = {"if", "for", "while", "switch", "catch", "synchronized", "constructor"}
+
+    if ext in (".groovy", ".java", ".ts", ".js"):
+        class_match = CLASS_PATTERN.search(content)
+        if not class_match:
+            return None
+        class_name = class_match.group(1)
+        extends_name = class_match.group(2) or ""
+
+        lines = content.splitlines()
+        for idx, line in enumerate(lines):
+            line_clean = line.strip()
+            if not line_clean or line_clean.startswith(("//", "/*", "*")):
                 continue
 
-        # Must have parentheses and end with '{' or next line starts with '{'
-        if "(" in line_clean and ")" in line_clean:
-            has_brace = line_clean.endswith("{") or (idx + 1 < len(lines) and lines[idx + 1].strip().startswith("{"))
-            if has_brace:
-                # Match method definition: modifiers + return type + name + (params)
-                m = re.search(r'(?:public\s+|protected\s+|private\s+|static\s+|def\s+|void\s+|[\w<>\[\],]+\s+)+([a-zA-Z_]\w*)\s*\(([^)]*)\)', line_clean)
+            if "=" in line_clean:
+                eq_pos = line_clean.find("=")
+                paren_pos = line_clean.find("(")
+                if paren_pos != -1 and eq_pos < paren_pos:
+                    continue
+
+            if "(" in line_clean and ")" in line_clean:
+                has_brace = "{" in line_clean or (idx + 1 < len(lines) and lines[idx + 1].strip().startswith("{"))
+                if has_brace:
+                    m = re.search(r'(?:public\s+|protected\s+|private\s+|static\s+|async\s+|def\s+|void\s+|[\w<>\[\],]+\s+)*([a-zA-Z_]\w*)\s*\(([^)]*)\)', line_clean)
+                    if m:
+                        name = m.group(1)
+                        params = m.group(2).strip()
+                        if name not in control_keywords and name != class_name:
+                            comment = ""
+                            if idx > 0 and lines[idx - 1].strip().startswith("//"):
+                                comment = lines[idx - 1].strip().lstrip("/ ").strip()
+                            methods.append({
+                                "name": name,
+                                "params": re.sub(r'\s+', ' ', params),
+                                "comment": comment
+                            })
+
+    elif ext == ".py":
+        class_match = PY_CLASS_PATTERN.search(content)
+        if not class_match:
+            return None
+        class_name = class_match.group(1)
+        extends_name = class_match.group(2) or ""
+
+        lines = content.splitlines()
+        for idx, line in enumerate(lines):
+            line_clean = line.strip()
+            if line_clean.startswith("def "):
+                m = re.search(r'def\s+([a-zA-Z_]\w*)\s*\(([^)]*)\):', line_clean)
                 if m:
                     name = m.group(1)
-                    params = m.group(2).strip()
-                    if name not in control_keywords and name != class_name:
-                        # Extract preceding single-line comment if any
+                    params = m.group(2).replace("self,", "").replace("self", "").strip()
+                    if not name.startswith("__") and name not in control_keywords:
                         comment = ""
-                        if idx > 0 and lines[idx - 1].strip().startswith("//"):
-                            comment = lines[idx - 1].strip().lstrip("/ ").strip()
+                        if idx + 1 < len(lines) and '"""' in lines[idx + 1]:
+                            comment = lines[idx + 1].replace('"""', '').strip()
                         methods.append({
                             "name": name,
                             "params": re.sub(r'\s+', ' ', params),
                             "comment": comment
                         })
+    else:
+        return None
 
     # Deduplicate methods preserving order
     seen = set()
@@ -120,6 +146,7 @@ def extract_class_info(file_path, repo_root=None):
             seen.add(sig)
             unique_methods.append(meth)
 
+    lines = content.splitlines()
     return {
         "rel_path": rel_path,
         "class_name": class_name,
@@ -131,13 +158,7 @@ def extract_class_info(file_path, repo_root=None):
 
 
 def build_repo_map(target_repo=None, output_txt=None, output_json=None):
-    """Scans Keywords in target_repo and builds the condensed repo map."""
-    try:
-        from author_integrity import assert_integrity_or_raise
-        assert_integrity_or_raise()
-    except Exception:
-        pass
-
+    """Scans Page Classes across polyglot targets (Groovy, TypeScript, Python) and builds map."""
     repo = target_repo or resolve_target_repo()
     txt_dest = output_txt or OUTPUT_TXT
     json_dest = output_json or OUTPUT_JSON
@@ -146,18 +167,31 @@ def build_repo_map(target_repo=None, output_txt=None, output_json=None):
     total_raw_bytes = 0
     total_raw_lines = 0
 
-    keywords_dir = os.path.join(repo, "Keywords")
-
-    if os.path.isdir(keywords_dir):
-        for root, dirs, files in os.walk(keywords_dir):
-            for fname in sorted(files):
-                if fname.endswith(".groovy"):
-                    full_path = os.path.join(root, fname)
-                    info = extract_class_info(full_path, repo_root=repo)
-                    if info:
-                        classes.append(info)
-                        total_raw_bytes += info["raw_size_bytes"]
-                        total_raw_lines += info["line_count"]
+    candidate_dirs = [
+        os.path.join(repo, "Keywords"),
+        os.path.join(repo, "pages"),
+        os.path.join(repo, "page-objects"),
+        os.path.join(repo, "page_objects"),
+        os.path.join(repo, "src", "pages"),
+        os.path.join(repo, "tests", "pages"),
+    ]
+
+    scanned_files = set()
+    for d in candidate_dirs:
+        if os.path.isdir(d):
+            for root, _, files in os.walk(d):
+                if any(ignored in root for ignored in (".git", "node_modules", "__pycache__", ".venv")):
+                    continue
+                for fname in sorted(files):
+                    if fname.endswith((".groovy", ".ts", ".js", ".py", ".java")):
+                        full_path = os.path.join(root, fname)
+                        if full_path not in scanned_files:
+                            scanned_files.add(full_path)
+                            info = extract_class_info(full_path, repo_root=repo)
+                            if info and info.get("methods"):
+                                classes.append(info)
+                                total_raw_bytes += info["raw_size_bytes"]
+                                total_raw_lines += info["line_count"]
 
     # Sort classes: BasePage first, then alphabetical
     classes.sort(key=lambda c: (0 if c["class_name"] == "BasePage" else 1, c["class_name"]))

package/tools/setup_project.py

@@ -175,7 +175,10 @@ def ensure_project_ai_guide(target_dir, stack_info):
 
 
 def install_git_pre_push_hook(target_dir):
-    """Installs an automated pre-push hook into target project's .git repository."""
+    """
+    Installs or appends an automated pre-push hook into target project's .git repository.
+    Safely backs up any existing pre-push hook (e.g. Husky, Lefthook) to prevent side-effects.
+    """
     git_dir = os.path.join(target_dir, ".git")
     if not os.path.isdir(git_dir):
         print("  [SKIP] Not a Git repository root (.git folder not found). Skipped Git Hook installation.")
@@ -185,37 +188,64 @@ def install_git_pre_push_hook(target_dir):
     os.makedirs(hooks_dir, exist_ok=True)
     hook_file = os.path.join(hooks_dir, "pre-push")
 
+    # Resolve pinned package version
+    manifest_file = os.path.join(HUB_ROOT, "skills_manifest.json")
+    pkg_ver = "2.2.2"
+    if os.path.exists(manifest_file):
+        try:
+            with open(manifest_file, "r", encoding="utf-8") as f:
+                pkg_ver = json.load(f).get("version", pkg_ver)
+        except Exception:
+            pass
+
     verify_all_script = os.path.join(SCRIPT_DIR, "verify_all.py").replace("\\", "/")
     analyze_script = os.path.join(SCRIPT_DIR, "analyze_project.py").replace("\\", "/")
 
-    hook_content = f"""#!/bin/sh
-# Automated Zero-Leakage Pre-Push Hook (Installed by Synapse-Hub)
-# Enforces 8 Quality Gates DoD and syncs project intelligence before pushing.
-
-echo "\\n[AI-GUARD] Running Pre-Push Verification (8 Quality Gates DoD)..."
+    hook_snippet = f"""
+# --- Synapse-Hub Pre-Push Quality Gate (v{pkg_ver}) ---
+echo "\\n[AI-GUARD] Running Pre-Push Verification (Quality Gates DoD)..."
 if command -v npx >/dev/null 2>&1; then
-    npx synapse-hub verify
+    npx synapse-hub@{pkg_ver} verify || npx synapse-hub verify
 elif [ -f "{verify_all_script}" ]; then
     python3 "{verify_all_script}" || python "{verify_all_script}"
 fi
 if [ $? -ne 0 ]; then
     echo "\\n[AI-GUARD - REJECTED] Git Push aborted: Quality Gates verification failed!"
-    echo "Please fix defects or run 'npx synapse-hub verify' locally before pushing.\\n"
+    echo "Please fix defects or run 'npx synapse-hub@{pkg_ver} verify' locally before pushing.\\n"
     exit 1
 fi
 
-echo "[AI-GUARD - PASSED] 8 Quality Gates satisfied. Syncing project health report..."
+echo "[AI-GUARD - PASSED] Quality Gates satisfied. Syncing project health report..."
 if command -v npx >/dev/null 2>&1; then
-    npx synapse-hub analyze
+    npx synapse-hub@{pkg_ver} analyze || npx synapse-hub analyze
 elif [ -f "{analyze_script}" ]; then
     python3 "{analyze_script}" || python "{analyze_script}"
 fi
 echo "[AI-GUARD - READY] Pushing to remote...\\n"
-exit 0
+# --- End Synapse-Hub Quality Gate ---
 """
+
     try:
+        if os.path.exists(hook_file):
+            with open(hook_file, "r", encoding="utf-8", errors="ignore") as f:
+                existing_content = f.read()
+
+            if "Synapse-Hub" in existing_content or "synapse-hub" in existing_content:
+                print(f"  {CYAN}[SKIP] Pre-Push Git Hook already present:{RESET} {hook_file}")
+                return True
+
+            # Safely backup existing hook (e.g. Husky, Lefthook)
+            backup_file = f"{hook_file}.backup"
+            shutil.copy2(hook_file, backup_file)
+            print(f"  {YELLOW}[BACKUP] Existing pre-push hook backed up to:{RESET} {backup_file}")
+
+            # Append non-destructively
+            final_content = existing_content.rstrip() + "\n" + hook_snippet
+        else:
+            final_content = "#!/bin/sh\n" + hook_snippet
+
         with open(hook_file, "w", encoding="utf-8", newline="\n") as f:
-            f.write(hook_content)
+            f.write(final_content)
 
         # Attempt to make executable on Unix-like environments
         try:
@@ -223,7 +253,7 @@ exit 0
         except Exception:
             pass
 
-        print(f"  {GREEN}[OK] Installed automated Pre-Push Git Hook:{RESET} {hook_file}")
+        print(f"  {GREEN}[OK] Configured automated Pre-Push Git Hook:{RESET} {hook_file} (pinned to v{pkg_ver})")
         return True
     except Exception as e:
         print(f"  ⚠️ Could not install Git hook: {e}")