synapse-hub 2.4.3 → 2.6.0

package/tools/senior_code_review.py

@@ -0,0 +1,341 @@
+#!/usr/bin/env python3
+# SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee998). All rights reserved.
+# SPDX-License-Identifier: MIT
+# Project: Synapse-Hub (https://github.com/TeeVee998/Synapse-Hub)
+
+"""
+tools/senior_code_review.py — Senior Developer Quality & Lean Diff Reviewer
+--------------------------------------------------------------------------
+Reviews code changes (uncommitted, staged, or branch) like the senior engineer
+who gets paged when it breaks:
+  1. Bugs & Edge Cases (swallowed errors, broken callers, null/edge handling)
+  2. Security & Data Risk (secrets, injection, unvalidated trust boundaries)
+  3. Scale & Concurrency (blocking calls, race conditions, memory growth)
+  4. Missing Tests (new non-trivial logic without assertions)
+  5. Performance & Hot-loops
+  6. Lean Code & Bloat (unneeded dependencies, duplicate logic, over-engineering)
+
+Usage:
+  python3 tools/senior_code_review.py [target_dir]
+  python3 tools/senior_code_review.py [target_dir] --staged
+  python3 tools/senior_code_review.py [target_dir] --branch main
+  python3 tools/senior_code_review.py [target_dir] --json
+"""
+
+import os
+import sys
+import re
+import json
+import subprocess
+import argparse
+from typing import Dict, List, Any, Optional, Tuple
+
+if hasattr(sys.stdout, 'reconfigure'):
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+        sys.stderr.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+
+
+class Finding:
+    def __init__(self, severity: str, title: str, file_path: str, line_no: int,
+                 what_is: str, problem: str, fix: str, if_skipped: str):
+        self.severity = severity  # "Must fix", "Should fix", "Nice to have"
+        self.title = title
+        self.file_path = file_path
+        self.line_no = line_no
+        self.what_is = what_is
+        self.problem = problem
+        self.fix = fix
+        self.if_skipped = if_skipped
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "severity": self.severity,
+            "title": self.title,
+            "file": self.file_path,
+            "line": self.line_no,
+            "what_is": self.what_is,
+            "problem": self.problem,
+            "fix": self.fix,
+            "if_skipped": self.if_skipped
+        }
+
+
+def get_git_diff(repo_dir: str, target: str = "uncommitted") -> str:
+    """Retrieves git diff based on target: uncommitted, staged, or branch/ref."""
+    cmd = ["git", "diff"]
+    if target == "staged":
+        cmd = ["git", "diff", "--cached"]
+    elif target != "uncommitted":
+        cmd = ["git", "diff", target]
+
+    try:
+        res = subprocess.run(
+            cmd,
+            cwd=repo_dir,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            encoding="utf-8",
+            errors="ignore",
+            check=True
+        )
+        return res.stdout
+    except Exception as e:
+        return ""
+
+
+def parse_diff(diff_text: str) -> List[Dict[str, Any]]:
+    """Parses unified diff output into file hunks and added lines."""
+    files: List[Dict[str, Any]] = []
+    current_file = None
+    current_hunk_line = 0
+
+    file_header_re = re.compile(r'^diff --git a/(.+) b/(.+)$')
+    hunk_header_re = re.compile(r'^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@')
+
+    for line in diff_text.splitlines():
+        fm = file_header_re.match(line)
+        if fm:
+            current_file = {
+                "path": fm.group(2),
+                "added_lines": [],  # (line_no, line_content)
+                "removed_lines": []
+            }
+            files.append(current_file)
+            continue
+
+        if not current_file:
+            continue
+
+        hm = hunk_header_re.match(line)
+        if hm:
+            current_hunk_line = int(hm.group(1))
+            continue
+
+        if line.startswith("+") and not line.startswith("+++"):
+            current_file["added_lines"].append((current_hunk_line, line[1:]))
+            current_hunk_line += 1
+        elif line.startswith("-") and not line.startswith("---"):
+            current_file["removed_lines"].append(line[1:])
+        else:
+            current_hunk_line += 1
+
+    return files
+
+
+def analyze_diff(files: List[Dict[str, Any]], repo_dir: str) -> Tuple[List[Finding], int]:
+    """Inspects diff files against senior dev quality & lean heuristics."""
+    findings: List[Finding] = []
+    lines_cuttable = 0
+
+    has_new_test = False
+    has_new_business_code = False
+
+    # Check overall changes for test balance
+    for f in files:
+        path = f["path"]
+        if "test" in path.lower() or "spec" in path.lower():
+            if f["added_lines"]:
+                has_new_test = True
+        else:
+            ext = os.path.splitext(path)[1].lower()
+            if ext in {".py", ".ts", ".js", ".java", ".groovy", ".go", ".rs"}:
+                if len(f["added_lines"]) > 5:
+                    has_new_business_code = True
+
+    # Rule checks on added lines
+    secret_pattern = re.compile(r'(?:api[_-]?key|password|secret|bearer|token)\s*=\s*[\'"][A-Za-z0-9_\-\.]{8,}[\'"]', re.I)
+    swallowed_catch_py = re.compile(r'except\s*(?:Exception)?\s*:\s*(?:pass|\.\.\.)')
+    swallowed_catch_js = re.compile(r'catch\s*\([^)]*\)\s*\{\s*\}')
+    static_sleep_pattern = re.compile(r'(?:Thread\.sleep|time\.sleep|sleep\(\d{3,}\))')
+    raw_xpath_pattern = re.compile(r'findTestObject|\.locator\(["\']//|\.locator\(["\']xpath=')
+
+    for f in files:
+        path = f["path"]
+        for line_no, content in f["added_lines"]:
+            stripped = content.strip()
+
+            # 1. Security: Hardcoded Credentials
+            if secret_pattern.search(stripped) and "test" not in path.lower():
+                findings.append(Finding(
+                    severity="Must fix",
+                    title="Potential hardcoded secret or token detected",
+                    file_path=path,
+                    line_no=line_no,
+                    what_is="A secret or token literal assignment in source code.",
+                    problem="Exposing credentials in source control allows unauthorized access and fails security scans.",
+                    fix="Extract the secret to an environment variable or encrypted profile config.",
+                    if_skipped="Credentials risk leaking to version control and security audits will fail."
+                ))
+
+            # 2. Correctness: Swallowed Exceptions
+            if swallowed_catch_py.search(stripped) or swallowed_catch_js.search(stripped):
+                findings.append(Finding(
+                    severity="Must fix",
+                    title="Swallowed exception / empty catch block",
+                    file_path=path,
+                    line_no=line_no,
+                    what_is="An exception catch block that suppresses errors without logging or handling.",
+                    problem="Silent failures hide root causes, corrupt downstream state, and lead to mysterious bugs in production.",
+                    fix="Log the exception with actionable context or rethrow a domain-specific error.",
+                    if_skipped="Failures will be completely invisible and impossible to debug under load."
+                ))
+
+            # 3. Flakiness / Concurrency: Static Sleep
+            if static_sleep_pattern.search(stripped):
+                findings.append(Finding(
+                    severity="Should fix",
+                    title="Static sleep detected (pipeline flakiness risk)",
+                    file_path=path,
+                    line_no=line_no,
+                    what_is="A static Thread.sleep or time.sleep delay in execution flow.",
+                    problem="Static delays waste CI time under fast networks and fail randomly under heavy load.",
+                    fix="Replace with a dynamic wait: element visibility check, network idle state, or condition polling.",
+                    if_skipped="Test runs will suffer non-deterministic flakiness and slower CI turnaround."
+                ))
+
+            # 4. Clean POM Architecture: Raw locators in scripts
+            if ("script" in path.lower() or "tests" in path.lower()) and raw_xpath_pattern.search(stripped):
+                findings.append(Finding(
+                    severity="Should fix",
+                    title="Raw selector or object reference inside test script",
+                    file_path=path,
+                    line_no=line_no,
+                    what_is="A raw XPath or direct object call inside a high-level test script.",
+                    problem="Violates Clean POM / Flat Architecture separation of concerns; UI changes break scripts directly.",
+                    fix="Encapsulate this locator and interaction inside a Page Class extending BasePage.",
+                    if_skipped="Any DOM markup change requires updating multiple scripts instead of a single Page Class."
+                ))
+
+            # 5. Lean: Commented-out dead code blocks
+            if (stripped.startswith("//") or stripped.startswith("#")) and len(stripped) > 20:
+                if re.match(r'^(?://|#)\s*(?:const|let|var|def|function|class|import|return)\b', stripped):
+                    lines_cuttable += 1
+                    findings.append(Finding(
+                        severity="Nice to have",
+                        title="Commented-out dead code block",
+                        file_path=path,
+                        line_no=line_no,
+                        what_is="A commented-out code statement left in the diff.",
+                        problem="Dead code creates visual clutter, confuses future maintainers, and rots over time.",
+                        fix="Delete the commented code. Git history preserves past implementations.",
+                        if_skipped="Technical debt and confusion will accumulate across commits."
+                    ))
+
+    # 6. Completeness: Non-trivial logic without any test
+    if has_new_business_code and not has_new_test:
+        findings.append(Finding(
+            severity="Should fix",
+            title="Non-trivial business code added without accompanying tests",
+            file_path="[Multiple files]",
+            line_no=1,
+            what_is="Substantial new implementation code with zero test additions or updates.",
+            problem="Risky logic ships unverified; regressions will not be caught automatically by CI.",
+            fix="Add at least one targeted unit or integration test proving this logic works on edge cases.",
+            if_skipped="Future refactoring risks breaking this behavior silently."
+        ))
+
+    return findings, lines_cuttable
+
+
+def format_report(findings: List[Finding], files: List[Dict[str, Any]], lines_cuttable: int) -> str:
+    """Renders the senior code review report in plain, pragmatic markdown."""
+    must_fix = [f for f in findings if f.severity == "Must fix"]
+    should_fix = [f for f in findings if f.severity == "Should fix"]
+    nice_to_have = [f for f in findings if f.severity == "Nice to have"]
+
+    lines = [
+        "# Senior Developer Quality & Lean Code Review",
+        "",
+        "> **Perspective:** Reviewed like the senior engineer who will be paged when this breaks.",
+        "",
+        f"- **Files Changed:** `{len(files)}`",
+        f"- **Findings:** `{len(findings)}` (`{len(must_fix)}` Must fix, `{len(should_fix)}` Should fix, `{len(nice_to_have)}` Nice to have)",
+        "",
+        "---",
+        "",
+    ]
+
+    if not files:
+        lines.append("ℹ️ **No changes found in the specified target.** Working directory is clean.")
+        return "\n".join(lines)
+
+    if not findings:
+        lines.append("🎉 **Verdict: Looks good. Clean, lean, and ready to ship.**")
+        return "\n".join(lines)
+
+    # Grouped findings
+    count = 1
+    for group_name, group_items in [("🚨 Must Fix (Blockers)", must_fix),
+                                    ("⚠️ Should Fix (Reliability & Scale)", should_fix),
+                                    ("💡 Nice to Have (Lean & Cleanup)", nice_to_have)]:
+        if not group_items:
+            continue
+        lines.append(f"### {group_name}")
+        lines.append("")
+        for item in group_items:
+            loc = f"`{item.file_path}:{item.line_no}`" if item.line_no else f"`{item.file_path}`"
+            lines.append(f"#### {count}. **{item.title}** ({loc})")
+            lines.append(f"- **What this is:** {item.what_is}")
+            lines.append(f"- **Problem:** {item.problem}")
+            lines.append(f"- **Fix:** {item.fix}")
+            lines.append(f"- **If we skip it:** {item.if_skipped}")
+            lines.append("")
+            count += 1
+
+    lines.append("---")
+    lines.append("### Verdict")
+    if must_fix:
+        lines.append(f"❌ **Action Required:** Resolve `{len(must_fix)}` blocker(s) before merging.")
+    elif should_fix:
+        lines.append(f"⚠️ **Caution:** Address `{len(should_fix)}` recommendation(s) to avoid flaky runs or debt.")
+    else:
+        lines.append("✅ **Approved with minor notes:** Safe to proceed.")
+
+    if lines_cuttable > 0:
+        lines.append(f"\n📉 **Lean Opportunity:** ~`{lines_cuttable}` unnecessary line(s) can be safely deleted.")
+
+    return "\n".join(lines)
+
+
+def run_review(repo_dir: str, target: str = "uncommitted", as_json: bool = False) -> int:
+    """Runs the diff extraction and review."""
+    repo_dir = os.path.abspath(repo_dir)
+    diff_text = get_git_diff(repo_dir, target)
+    files = parse_diff(diff_text)
+    findings, lines_cuttable = analyze_diff(files, repo_dir)
+
+    if as_json:
+        payload = {
+            "target": target,
+            "files_count": len(files),
+            "findings_count": len(findings),
+            "lines_cuttable": lines_cuttable,
+            "findings": [f.to_dict() for f in findings]
+        }
+        print(json.dumps(payload, indent=2, ensure_ascii=False))
+        return 0 if not any(f.severity == "Must fix" for f in findings) else 1
+
+    print("\n" + format_report(findings, files, lines_cuttable))
+    return 0 if not any(f.severity == "Must fix" for f in findings) else 1
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Senior Developer Quality & Lean Diff Reviewer (bugs, security, scale, tests, bloat)"
+    )
+    parser.add_argument("target_dir", nargs="?", default=".", help="Repository directory (default: current directory)")
+    parser.add_argument("--staged", action="store_true", help="Review staged git changes")
+    parser.add_argument("--branch", default=None, help="Review changes against a git branch or commit ref")
+    parser.add_argument("--json", action="store_true", help="Output results in JSON format")
+
+    args = parser.parse_args()
+    diff_target = "staged" if args.staged else (args.branch if args.branch else "uncommitted")
+    sys.exit(run_review(args.target_dir, diff_target, args.json))
+
+
+if __name__ == "__main__":
+    main()

package/tools/setup_project.py

@@ -219,7 +219,7 @@ def install_git_pre_push_hook(target_dir):
             with open(manifest_file, "r", encoding="utf-8") as f:
                 pkg_ver = json.load(f).get("version", pkg_ver)
         except (IOError, json.JSONDecodeError, KeyError):
-            pass
+            pkg_ver = "2.4.3"
 
     verify_all_script = os.path.join(SCRIPT_DIR, "verify_all.py").replace("\\", "/")
     analyze_script = os.path.join(SCRIPT_DIR, "analyze_project.py").replace("\\", "/")
@@ -281,7 +281,7 @@ echo "[AI-GUARD - READY] Pushing to remote...\\n"
 
         # Attempt to make executable on Unix-like environments
         try:
-            os.chmod(hook_file, 0o755)
+            os.chmod(hook_file, 0o755)  # nosec B103
         except OSError:
             pass
 
@@ -311,8 +311,8 @@ def ensure_gitignore_protection(target_dir):
                     f.write(f"{e}\n")
             print(f"  {GREEN}[OK] Protected local cache in .gitignore:{RESET} {gitignore_path}")
             return True
-    except OSError:
-        pass
+    except OSError as err:
+        sys.stderr.write(f"Notice: .gitignore update skipped: {err}\n")
     return False
 
 
@@ -358,7 +358,7 @@ fi
             f.write(final_content)
 
         try:
-            os.chmod(hook_file, 0o755)
+            os.chmod(hook_file, 0o755)  # nosec B103
         except OSError:
             pass
 
@@ -372,7 +372,7 @@ def inject_antigravity_global_plugin():
     """
     Automatically injects Synapse-Hub into Antigravity's Global Plugin Directory
     (~/.gemini/config/plugins/synapse-hub).
-    Ensures that running `npx synapse-hub setup` activates the 38 skills and 6 subagents
+    Ensures that running `npx synapse-hub setup` activates the 42 skills and 6 subagents
     globally across ALL projects in Google Antigravity.
     """
     try:
@@ -412,7 +412,7 @@ def inject_antigravity_global_plugin():
                 try:
                     os.unlink(dst)
                 except OSError:
-                    pass
+                    unlinked = False
             if sys.platform == "win32":
                 try:
                     import _winapi
@@ -420,7 +420,7 @@ def inject_antigravity_global_plugin():
                         _winapi.CreateJunction(src, dst)
                         return
                 except (OSError, ImportError, AttributeError):
-                    pass
+                    junction_created = False
             shutil.copytree(src, dst, dirs_exist_ok=True, ignore=shutil.ignore_patterns("__pycache__", "*.pyc", "*.tmp"))
 
         sync_dir(os.path.join(HUB_ROOT, ".agents", "skills"), os.path.join(target_plugin_dir, "skills"))
@@ -679,7 +679,7 @@ def run_setup(target_repo, dry_run=False, profile="auto", no_global=True, no_git
         )
         welcome_url = f"file://{welcome_file}"
     except (ImportError, OSError, ValueError):
-        pass
+        welcome_url = ""
 
     print(f"\n{BOLD}{CYAN}======================================================================{RESET}")
     print(f"{BOLD}{CYAN}            🎉 PROJECT IS NOW 100% AI-READY (LEVEL 5 SETUP)           {RESET}")

package/tools/skill_collision_guard.py

@@ -0,0 +1,231 @@
+#!/usr/bin/env python3
+# SPDX-FileCopyrightText: Copyright (c) 2026 Thế Vị (@TeeVee998). All rights reserved.
+# SPDX-License-Identifier: MIT
+# Project: Synapse-Hub (https://github.com/TeeVee998/Synapse-Hub)
+
+"""
+Tier-2 Skill Routing & Collision Guard (Addy Osmani Pattern)
+------------------------------------------------------------
+Computes pairwise cosine similarity across all SKILL.md descriptions.
+Operates 100% offline with zero LLM tokens using a lightweight suffix-stripping
+stemmer heuristic and TF-IDF word frequency representation.
+
+Enforces:
+  - Warning when description similarity >= 0.50 (semantic proximity)
+  - Critical Error (Quality Gate Failure) when similarity >= 0.75 (ambiguous routing)
+
+Usage:
+  python tools/skill_collision_guard.py [--dir .agents/skills] [--threshold 0.75] [--json]
+"""
+
+import os
+import sys
+import re
+import math
+import json
+import argparse
+from typing import Dict, List, Tuple
+from collections import Counter
+
+# Enforce UTF-8 stdout encoding for Windows console compatibility
+if hasattr(sys.stdout, 'reconfigure'):
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+        sys.stderr.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+
+STOPWORDS = {
+    "a", "about", "above", "after", "again", "against", "all", "am", "an", "and", "any", "are",
+    "aren't", "as", "at", "be", "because", "been", "before", "being", "below", "between", "both",
+    "but", "by", "can", "cannot", "could", "couldn't", "did", "didn't", "do", "does", "doesn't",
+    "doing", "don't", "down", "during", "each", "few", "for", "from", "further", "had", "hadn't",
+    "has", "hasn't", "have", "haven't", "having", "he", "her", "here", "hers", "herself", "him",
+    "himself", "his", "how", "i", "if", "in", "into", "is", "isn't", "it", "it's", "its", "itself",
+    "let's", "me", "more", "most", "mustn't", "my", "myself", "no", "nor", "not", "of", "off", "on",
+    "once", "only", "or", "other", "ought", "our", "ours", "ourselves", "out", "over", "own", "same",
+    "shan't", "she", "should", "shouldn't", "so", "some", "such", "than", "that", "the", "their",
+    "theirs", "them", "themselves", "then", "there", "these", "they", "this", "those", "through",
+    "to", "too", "under", "until", "up", "very", "was", "wasn't", "we", "were", "weren't", "what",
+    "when", "where", "which", "while", "who", "whom", "why", "with", "won't", "would", "wouldn't",
+    "you", "your", "yours", "yourself", "yourselves", "use", "when", "allows", "provides", "designed"
+}
+
+
+def strip_suffix(word: str) -> str:
+    """Lightweight suffix-stripping heuristic (Addy Osmani Tier-2 standard)."""
+    if len(word) <= 4:
+        return word
+    for suffix in ("ing", "tion", "ment", "ness", "able", "ible", "ize", "ise", "ies", "es", "ed", "ly", "al", "s"):
+        if word.endswith(suffix) and len(word) - len(suffix) >= 3:
+            return word[:-len(suffix)]
+    return word
+
+
+def tokenize(text: str) -> List[str]:
+    """Tokenizes text, strips punctuation, removes stopwords and applies suffix stripping."""
+    words = re.findall(r"\b[a-zA-Z0-9_\-]+\b", text.lower())
+    tokens = []
+    for w in words:
+        cleaned = re.sub(r"^[^a-zA-Z0-9]+|[^a-zA-Z0-9]+$", "", w)
+        if len(cleaned) >= 2 and cleaned not in STOPWORDS:
+            tokens.append(strip_suffix(cleaned))
+    return tokens
+
+
+def build_tf_vector(tokens: List[str]) -> Dict[str, float]:
+    """Builds normalized term-frequency vector."""
+    counts = Counter(tokens)
+    total = len(tokens)
+    if total == 0:
+        return {}
+    return {word: count / total for word, count in counts.items()}
+
+
+def cosine_similarity(vec1: Dict[str, float], vec2: Dict[str, float]) -> float:
+    """Computes cosine similarity between two term-frequency vectors."""
+    intersection = set(vec1.keys()) & set(vec2.keys())
+    numerator = sum(vec1[x] * vec2[x] for x in intersection)
+    sum1 = sum(v ** 2 for v in vec1.values())
+    sum2 = sum(v ** 2 for v in vec2.values())
+    denominator = math.sqrt(sum1) * math.sqrt(sum2)
+    if not denominator:
+        return 0.0
+    return float(numerator) / denominator
+
+
+class SkillCollisionGuard:
+    """Audits skill descriptions across repository for routing collisions and ambiguous triggers."""
+
+    def __init__(self, skills_dir: str = ".agents/skills", threshold: float = 0.75, warn_threshold: float = 0.50):
+        self.skills_dir = skills_dir
+        self.threshold = threshold
+        self.warn_threshold = warn_threshold
+
+    def load_descriptions(self) -> Dict[str, str]:
+        """Loads all SKILL.md files and extracts their description strings."""
+        descriptions = {}
+        if not os.path.exists(self.skills_dir):
+            return descriptions
+
+        for root, _, files in os.walk(self.skills_dir):
+            for file in files:
+                if file.lower() == "skill.md":
+                    full_path = os.path.join(root, file)
+                    skill_name, desc = self._extract_frontmatter(full_path)
+                    if skill_name and desc:
+                        descriptions[skill_name] = desc
+        return descriptions
+
+    def _extract_frontmatter(self, path: str) -> Tuple[str, str]:
+        try:
+            with open(path, "r", encoding="utf-8", errors="ignore") as f:
+                content = f.read()
+        except OSError:
+            return "", ""
+
+        match = re.search(r"^---\s*\n(.*?)\n---", content, re.DOTALL)
+        if match:
+            fm = match.group(1)
+            name_m = re.search(r"^name:\s*(.+)$", fm, re.MULTILINE)
+            desc_m = re.search(r"^description:\s*[\"']?(.*?)[\"']?$", fm, re.MULTILINE)
+            name = name_m.group(1).strip() if name_m else os.path.basename(os.path.dirname(path))
+            desc = desc_m.group(1).strip() if desc_m else ""
+            return name, desc
+
+        fallback_name = os.path.basename(os.path.dirname(path))
+        return fallback_name, ""
+
+    def audit(self) -> Tuple[bool, List[Dict[str, any]]]:
+        """
+        Computes pairwise similarity.
+        Returns (is_clean, report_items).
+        """
+        descriptions = self.load_descriptions()
+        names = sorted(list(descriptions.keys()))
+        vectors = {name: build_tf_vector(tokenize(descriptions[name])) for name in names}
+
+        findings = []
+        has_critical = False
+
+        for i in range(len(names)):
+            for j in range(i + 1, len(names)):
+                name_a = names[i]
+                name_b = names[j]
+                sim = cosine_similarity(vectors[name_a], vectors[name_b])
+
+                if sim >= self.threshold:
+                    has_critical = True
+                    findings.append({
+                        "level": "CRITICAL",
+                        "skill_a": name_a,
+                        "skill_b": name_b,
+                        "similarity": round(sim, 3),
+                        "message": f"Critical Collision: '{name_a}' and '{name_b}' have cosine similarity {sim:.3f} >= {self.threshold}"
+                    })
+                elif sim >= self.warn_threshold:
+                    findings.append({
+                        "level": "WARNING",
+                        "skill_a": name_a,
+                        "skill_b": name_b,
+                        "similarity": round(sim, 3),
+                        "message": f"Proximity Warning: '{name_a}' and '{name_b}' have similarity {sim:.3f} >= {self.warn_threshold}"
+                    })
+
+        return (not has_critical), findings
+
+
+def run_guard(skills_dir: str = ".agents/skills", threshold: float = 0.75, warn_threshold: float = 0.50, output_json: bool = False) -> int:
+    guard = SkillCollisionGuard(skills_dir, threshold=threshold, warn_threshold=warn_threshold)
+    passed, findings = guard.audit()
+
+    if output_json:
+        print(json.dumps({
+            "skills_dir": skills_dir,
+            "passed": passed,
+            "threshold": threshold,
+            "warn_threshold": warn_threshold,
+            "findings": findings
+        }, indent=2))
+        return 0 if passed else 1
+
+    print("\n" + "=" * 70)
+    print("  TIER-2 SKILL ROUTING & COLLISION GUARD (ADDY OSMANI PATTERN)")
+    print("=" * 70)
+    print(f"Skills Directory : {skills_dir}")
+    print(f"Collision Threshold: {threshold} (FAIL) | Warning Threshold: {warn_threshold} (WARN)")
+
+    criticals = [f for f in findings if f["level"] == "CRITICAL"]
+    warnings = [f for f in findings if f["level"] == "WARNING"]
+
+    if warnings:
+        print(f"\n⚠️  {len(warnings)} Near-Neighbor Warnings detected (similarity >= {warn_threshold}):")
+        for w in warnings:
+            print(f"   - {w['message']}")
+
+    if criticals:
+        print(f"\n❌ {len(criticals)} CRITICAL COLLISION(S) detected (similarity >= {threshold}):")
+        for c in criticals:
+            print(f"   [FAIL] {c['message']}")
+        print("\n[DoD BLOCKED] High similarity causes routing ambiguity and context contamination.")
+        print("=" * 70 + "\n")
+        return 1
+
+    print(f"\n✅ [PASS] 0 routing collisions detected. All skill descriptions uniquely segmented.\n")
+    print("=" * 70 + "\n")
+    return 0
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Tier-2 Skill Routing & Collision Guard")
+    parser.add_argument("--dir", default=".agents/skills", help="Directory containing skill packages")
+    parser.add_argument("--threshold", type=float, default=0.75, help="Critical similarity threshold (default: 0.75)")
+    parser.add_argument("--warn-threshold", type=float, default=0.50, help="Warning similarity threshold (default: 0.50)")
+    parser.add_argument("--json", action="store_true", help="Output results in JSON format")
+    args = parser.parse_args()
+
+    return run_guard(skills_dir=args.dir, threshold=args.threshold, warn_threshold=args.warn_threshold, output_json=args.json)
+
+
+if __name__ == "__main__":
+    sys.exit(main())