synapse-hub 2.7.0 → 3.0.1

package/tools/smart_visual_masker.py

@@ -7,11 +7,9 @@ Automatically disables dynamic CSS animations, freezes SVG spinners,
 and masks fluctuating UI elements (timestamps, clocks, avatars, ad banners).
 """
 
-import os
-import re
 import json
 import argparse
-from typing import List, Dict, Any, Tuple
+from typing import List, Optional
 
 
 class SmartVisualMasker:
@@ -56,13 +54,13 @@ class SmartVisualMasker:
         return cls.ANTI_FLAKE_CSS.strip()
 
     @classmethod
-    def generate_playwright_ts_options(cls, additional_selectors: List[str] = None) -> str:
+    def generate_playwright_ts_options(cls, additional_selectors: Optional[List[str]] = None) -> str:
         """
         Generates Playwright TypeScript assertion options with masking and disabled animations.
         """
         selectors = cls.DEFAULT_MASK_SELECTORS + (additional_selectors or [])
         locators_ts = ",\n    ".join([f"page.locator('{sel}')" for sel in selectors])
-        
+
         return f"""await expect(page).toHaveScreenshot('visual-baseline.png', {{
   animations: 'disabled',
   caret: 'hide',
@@ -74,7 +72,7 @@ class SmartVisualMasker:
 }});"""
 
     @classmethod
-    def generate_browser_mask_script(cls, selectors: List[str] = None) -> str:
+    def generate_browser_mask_script(cls, selectors: Optional[List[str]] = None) -> str:
         """
         Generates JavaScript snippet to run inside the live browser
         to immediately freeze DOM animations and paint solid black masks

package/tools/spec_drift_sentinel.py

@@ -206,7 +206,6 @@ def compute_drift(spec_criteria: List[Dict[str, Any]], code_files: List[Tuple[st
         all_code_actions.extend([(file_path, a) for a in actions])
         combined_code += "\n" + content
 
-    combined_code_lower = combined_code.lower()
     code_tokens = tokenize_text(combined_code)
 
     covered_criteria = []
@@ -289,7 +288,7 @@ def generate_markdown_report(result: Dict[str, Any], spec_file: str, code_path:
     md.append("> Generated autonomously by Synapse-Hub `tools/spec_drift_sentinel.py`  ")
     md.append(f"> **Specification:** `{spec_file}` | **Code Target:** `{code_path}`  \n")
     md.append("---")
-    
+
     status_icon = "✅" if result["passed"] else "❌"
     md.append(f"## 📊 Executive Summary: {status_icon} [{result['status']}]")
     md.append(f"- **Alignment Score:** `{result['alignment_score']}%` (Pass threshold: >= 80% & zero Deficit Drift)")

package/tools/swe_qa_aci.py

@@ -216,8 +216,8 @@ class SweQaAci:
             f.write(new_content)
 
         # Diff summary formatting
-        target_lines = [f"- {l}" for l in norm_target.splitlines()]
-        replacement_lines = [f"+ {l}" for l in norm_replacement.splitlines()]
+        target_lines = [f"- {line}" for line in norm_target.splitlines()]
+        replacement_lines = [f"+ {line}" for line in norm_replacement.splitlines()]
         diff_summary = "\n".join(target_lines + replacement_lines)
 
         return {

package/tools/synapse_qa_bench.py

@@ -19,7 +19,7 @@ import os
 import sys
 import json
 import argparse
-from typing import List, Dict, Any, Tuple
+from typing import List, Dict, Any, Optional
 
 # Enforce UTF-8 stdout encoding for Windows console compatibility
 if hasattr(sys.stdout, 'reconfigure'):
@@ -96,7 +96,7 @@ BENCHMARK_CASES = [
 class SynapseQABench:
     """Evaluates agent tool-calling capabilities against standardized QA benchmark cases."""
 
-    def __init__(self, cases: List[Dict[str, Any]] = None):
+    def __init__(self, cases: Optional[List[Dict[str, Any]]] = None):
         self.cases = cases or BENCHMARK_CASES
 
     def run_benchmark(self, tool_resolver_fn=None) -> Dict[str, Any]:
@@ -112,7 +112,7 @@ class SynapseQABench:
         details = []
 
         for case in self.cases:
-            expected_tool = case["expected_tool"]
+            expected_tool = str(case["expected_tool"])
             # Baseline keyword resolver simulation
             selected_tool = expected_tool if tool_resolver_fn is None else tool_resolver_fn(case["intent"])
 

package/tools/sync_agent_rules.py

@@ -47,9 +47,10 @@ HEADER_HASH_TEMPLATE = """# ====================================================
 
 
 def generate_claude_md():
+    """Generates the unified CLAUDE.md file compiling agent rules and standards."""
     return f"""# CLAUDE.md — Synapse-Hub Guidelines for Claude Code
 
-> **Author & Creator:** Thế Vị (@TeeVee998) <https://github.com/TeeVee998/Synapse-Hub>  
+> **Author & Creator:** Thế Vị (@TeeVee998) <https://github.com/TeeVee998/Synapse-Hub>
 > **License:** MIT License (Mandatory Attribution Preservation)
 
 {HEADER_TEMPLATE}
@@ -91,6 +92,7 @@ In accordance with the MIT License, the original copyright notice crediting **Th
 5. **Pragmatic Communication Protocol:**
    - Conversational responses, explanation, and telemetry MUST be in Vietnamese.
    - All codebase assets, test scripts, Page Classes, docstrings, and commits MUST remain strictly in English.
+   - English-First Document Ingestion: When reading bilingual docs (e.g. ARCHITECTURE.en.md vs ARCHITECTURE.md), always read the English version (*.en.md) to save 50–65% BPE tokens.
 
 6. **Lean Senior Dev Protocol (The 7-Rung Ladder & YAGNI):**
    - The best code is the code never written. Solve the whole problem with the least new code.
@@ -100,6 +102,7 @@ In accordance with the MIT License, the original copyright notice crediting **Th
 
 
 def generate_cursorrules():
+    """Generates the .cursorrules file compiling agent rules for Cursor AI."""
     return f"""# .cursorrules — Synapse-Hub Guidelines for Cursor AI
 # Author & Creator: Thế Vị (@TeeVee998) <https://github.com/TeeVee998/Synapse-Hub>
 # License: MIT License (Mandatory Attribution Preservation)
@@ -127,6 +130,7 @@ def generate_cursorrules():
 
 
 def generate_windsurfrules():
+    """Generates the .windsurfrules configuration for Windsurf AI."""
     return f"""# .windsurfrules — Synapse-Hub Guidelines for Windsurf AI
 # Author & Creator: Thế Vị (@TeeVee998) <https://github.com/TeeVee998/Synapse-Hub>
 # License: MIT License (Mandatory Attribution Preservation)
@@ -153,6 +157,7 @@ def generate_windsurfrules():
 
 
 def generate_cursor_mdc():
+    """Generates the .cursor/rules/synapse-qa.mdc file for Cursor IDE."""
     return f"""---
 description: Synapse-Hub Enterprise QA Automation & Testing Rules
 globs: **/*
@@ -177,12 +182,13 @@ Attribution notices must be preserved.
 
 
 def generate_copilot_instructions():
+    """Generates the .github/copilot-instructions.md file for GitHub Copilot."""
     return f"""# GitHub Copilot Custom Instructions for Synapse-Hub
 
 {HEADER_TEMPLATE}
 
-> **Project:** Synapse-Hub Enterprise QA Automation  
-> **Author:** Thế Vị (@TeeVee998) — MIT License  
+> **Project:** Synapse-Hub Enterprise QA Automation
+> **Author:** Thế Vị (@TeeVee998) — MIT License
 
 ## Coding Invariants
 - Enforce Clean Page Object Model (POM) with Flat Architecture.
@@ -210,6 +216,14 @@ TARGET_GENERATORS = [
 
 
 def sync_all(check_only=False):
+    """Synchronizes AGENTS.md rules across all IDE and assistant bridge files.
+
+    Args:
+        check_only: If True, only checks for rule drift without modifying files.
+
+    Returns:
+        0 if clean or synchronized, 1 if drift was detected in check_only mode.
+    """
     drift_detected = False
     for rel_path, gen_fn in TARGET_GENERATORS:
         full_path = os.path.join(REPO_ROOT, rel_path)
@@ -249,6 +263,7 @@ def sync_all(check_only=False):
 
 
 def main():
+    """CLI entrypoint for synchronizing AI agent rules."""
     parser = argparse.ArgumentParser(description="Synchronize AGENTS.md to all AI IDE bridges")
     parser.add_argument("--check", action="store_true", help="Check for drift without modifying files")
     args = parser.parse_args()

package/tools/telemetry_correlator.py

@@ -36,7 +36,7 @@ import csv
 import json
 import math
 import argparse
-from typing import Dict, List, Any, Optional, Tuple
+from typing import Dict, List, Any
 
 # Enforce UTF-8 stdout encoding for Windows/macOS/Linux console compatibility
 if hasattr(sys.stdout, "reconfigure"):
@@ -286,7 +286,8 @@ def main():
     args = parser.parse_args()
 
     if args.sample or not args.jtl or not args.server_metrics:
-        import tempfile, time
+        import tempfile
+        import time
         temp_dir = tempfile.gettempdir()
         temp_jtl = os.path.join(temp_dir, "sample_corr_jmeter.jtl")
         temp_srv = os.path.join(temp_dir, "sample_corr_server.csv")

package/tools/test_impact.py

@@ -175,7 +175,8 @@ def get_git_modified_files(repo_root=None):
             stdout=subprocess.PIPE,
             stderr=subprocess.PIPE,
             text=True,
-            check=True
+            check=True,
+            timeout=30.0
         )
         files = [line.strip() for line in res.stdout.splitlines() if line.strip()]
         return files

package/tools/test_memory_os.py

@@ -27,6 +27,7 @@ import re
 import json
 import sqlite3
 import time
+import uuid
 import difflib
 import argparse
 from datetime import datetime, timezone, timedelta
@@ -48,6 +49,15 @@ SECRET_PATTERNS = [
 ]
 
 
+class ManagedConnection(sqlite3.Connection):
+    """SQLite connection that automatically commits/rollbacks and closes on context exit."""
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        try:
+            super().__exit__(exc_type, exc_val, exc_tb)
+        finally:
+            self.close()
+
+
 class TestMemoryOS:
     """3-Tier Hierarchical QA Memory OS."""
     __test__ = False
@@ -62,8 +72,8 @@ class TestMemoryOS:
         os.makedirs(os.path.dirname(os.path.abspath(self.db_path)), exist_ok=True)
         self._init_db()
 
-    def _get_connection(self) -> sqlite3.Connection:
-        conn = sqlite3.connect(self.db_path)
+    def _get_connection(self) -> ManagedConnection:
+        conn = sqlite3.connect(self.db_path, factory=ManagedConnection)
         conn.row_factory = sqlite3.Row
         return conn
 
@@ -165,7 +175,7 @@ class TestMemoryOS:
                 INSERT INTO recall_memory (session_id, event_type, actor, payload_json, timestamp)
                 VALUES (?, ?, ?, ?, ?)
             """, (session_id, event_type, actor, payload_str, now))
-            return cursor.lastrowid
+            return cursor.lastrowid or 0
 
     def recall_log(self, session_id: str, limit: int = 50) -> List[Dict[str, Any]]:
         """Retrieves recent sequential steps for a session."""
@@ -199,7 +209,7 @@ class TestMemoryOS:
         """Inserts long-term searchable knowledge into archival memory."""
         payload_str = json.dumps(payload) if not isinstance(payload, str) else payload
         now = datetime.now(timezone.utc).isoformat()
-        mem_id = f"mem_arch_{int(time.time() * 1000) % 10000000}"
+        mem_id = f"mem_arch_{int(time.time() * 1000) % 10000000}_{uuid.uuid4().hex[:6]}"
 
         # Flatten text content for semantic/fuzzy search
         text_content = f"{key} {aut_version} {tags} {payload_str}".lower()
@@ -336,7 +346,7 @@ def main():
     subparsers = parser.add_subparsers(dest="subcommand", help="Subcommand to execute")
 
     # init
-    init_parser = subparsers.add_parser("init", help="Initialize memory OS database")
+    subparsers.add_parser("init", help="Initialize memory OS database")
 
     # update-core
     uc_parser = subparsers.add_parser("update-core", help="Update core memory block")

package/tools/textgrad_mutation_optimizer.py

@@ -20,7 +20,7 @@ import sys
 import re
 import json
 import argparse
-from typing import List, Dict, Any, Tuple, Optional
+from typing import List, Dict, Any, Tuple
 
 # Enforce UTF-8 stdout encoding for Windows console compatibility
 if hasattr(sys.stdout, 'reconfigure'):
@@ -33,10 +33,10 @@ if hasattr(sys.stdout, 'reconfigure'):
 SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
 sys.path.insert(0, SCRIPT_DIR)
 
-import micro_mutator
+import micro_mutator  # noqa: E402
 
 try:
-    import textgrad
+    import textgrad  # noqa: F401, E402
     TEXTGRAD_AVAILABLE = True
 except ImportError:
     TEXTGRAD_AVAILABLE = False

package/tools/tms_sync_bridge.py

@@ -78,7 +78,7 @@ class TMSBridge:
                 "issue_type": "Story",
                 "status": "Ready for QA",
                 "assignee": self.user_email,
-                "description": f"As an Enterprise Accountant, I want to reconcile invoices matching ERP records to ensure financial accuracy.",
+                "description": "As an Enterprise Accountant, I want to reconcile invoices matching ERP records to ensure financial accuracy.",
                 "acceptance_criteria": [
                     "Given the accountant is logged in with FINANCE_ROLE",
                     "When navigating to '/billing/invoices' and filtering by date '2026-10-01'",
@@ -161,8 +161,8 @@ class TMSBridge:
         bug_key = f"{proj_clean}-BUG-{int(datetime.now().timestamp()) % 10000}"
 
         repro = reproduction_steps or [
-            f"1. Launch headless browser session via Playwright Live.",
-            f"2. Navigate to target application flow under test.",
+            "1. Launch headless browser session via Playwright Live.",
+            "2. Navigate to target application flow under test.",
             f"3. Execute test action sequence for '{test_case_id}'.",
             f"4. Observe failure: {error_message}"
         ]
@@ -299,9 +299,9 @@ def main():
         if args.json:
             print(json.dumps(story, indent=2))
         else:
-            print(f"\n======================================================================")
+            print("\n======================================================================")
             print(f"      ENTERPRISE ALM STORY PULL: [{story.get('issue_key')}]")
-            print(f"======================================================================")
+            print("======================================================================")
             print(f"  Summary   : {story.get('summary')}")
             print(f"  Status    : {story.get('status')} | Assignee: {story.get('assignee')}")
             print(f"  Source    : {story.get('source')}\n")

package/tools/tot_exploratory_tester.py

@@ -21,9 +21,8 @@ import os
 import sys
 import re
 import json
-import time
 import argparse
-from typing import Dict, Any, List, Optional, Tuple
+from typing import Dict, Any, List, Optional, cast
 
 # Enforce UTF-8 stdout encoding
 if hasattr(sys.stdout, 'reconfigure'):
@@ -43,7 +42,7 @@ class TotExploratoryTester:
     def expand_story(self, story_content: str, max_depth: int = 3, beam_width: int = 3) -> Dict[str, Any]:
         """Decomposes story into a 3-branch Tree of Thoughts with risk scores."""
         # Extract title and criteria
-        lines = [l.strip() for l in story_content.splitlines() if l.strip()]
+        lines = [line.strip() for line in story_content.splitlines() if line.strip()]
         title = lines[0] if lines else "Untitled User Story"
         if title.startswith("#"):
             title = title.lstrip("#").strip()
@@ -93,7 +92,7 @@ class TotExploratoryTester:
         ]
 
         # Beam search selection: sort by risk score descending and take beam_width
-        sorted_branches = sorted(branches, key=lambda b: b["risk_score"], reverse=True)
+        sorted_branches = sorted(branches, key=lambda b: cast(float, b["risk_score"]), reverse=True)
         selected_branches = sorted_branches[:beam_width]
 
         return {
@@ -169,7 +168,7 @@ class TotExploratoryTester:
                 "evidence": evidence
             })
 
-        scored_hypotheses.sort(key=lambda h: h["confidence_score"], reverse=True)
+        scored_hypotheses.sort(key=lambda h: cast(float, h["confidence_score"]), reverse=True)
         winner = scored_hypotheses[0]
 
         recommendations = {
@@ -184,7 +183,7 @@ class TotExploratoryTester:
             "status": "PASS",
             "primary_root_cause": winner["hypothesis"],
             "confidence": winner["confidence_score"],
-            "recommended_fix": recommendations.get(winner["hypothesis"], "Review stacktrace with team"),
+            "recommended_fix": recommendations.get(str(winner["hypothesis"]), "Review stacktrace with team"),
             "ranked_hypotheses": scored_hypotheses
         }
 

package/tools/traffic_session_converter.py

@@ -23,7 +23,7 @@ import re
 import sys
 import json
 import argparse
-from typing import Dict, Any, List, Optional
+from typing import Dict, Any, List
 from urllib.parse import urlparse
 
 # Enforce UTF-8 stdout encoding for Windows console compatibility
@@ -153,14 +153,14 @@ class TrafficConverter:
         lines = [
             "import { test, expect } from '@playwright/test';",
             "",
-            f"/**",
-            f" * Automated Replay of Production Traffic Session",
-            f" * Generated by traffic_session_converter.py (agent-skills Shift-Right Engine)",
+            "/**",
+            " * Automated Replay of Production Traffic Session",
+            " * Generated by traffic_session_converter.py (agent-skills Shift-Right Engine)",
             f" * Total Actions: {len(requests)} verified network interactions",
-            f" */",
+            " */",
             f"test.describe('{test_name}', () => {{",
-            f"  test('replays production user journey with PII masking', async ({{ page, request }}) => {{",
-            f"    // 1. Base navigation",
+            "  test('replays production user journey with PII masking', async ({ page, request }) => {",
+            "    // 1. Base navigation",
             f"    await page.goto('{base_url}');",
             ""
         ]
@@ -185,9 +185,9 @@ class TrafficConverter:
                     formatted_body = json.dumps(body_str)
 
                 lines.append(f"    const resp{step_num} = await request.{method.lower()}('{url}', {{")
-                lines.append(f"      headers: {{ 'Content-Type': 'application/json' }},")
+                lines.append("      headers: { 'Content-Type': 'application/json' },")
                 lines.append(f"      data: {formatted_body}")
-                lines.append(f"    }});")
+                lines.append("    });")
                 lines.append(f"    expect(resp{step_num}.status()).toBe({status});")
             else:
                 lines.append(f"    const resp{step_num} = await request.get('{url}');")

package/tools/universal_ir.py

@@ -9,8 +9,9 @@ whether the target is Playwright, Selenium, Cypress, Katalon, or Appium.
 
 from enum import Enum
 from typing import Dict, List, Optional, Any
-from dataclasses import dataclass, field, asdict
+from dataclasses import dataclass, field
 import json
+import re
 
 
 class ActionType(str, Enum):
@@ -345,8 +346,6 @@ class ProjectIR:
         return cls.from_dict(data)
 
 
-import re
-
 SHARED_VAR_PATTERNS = [
     (r"\b(?:created_id|order_id|user_id|item_id|customer_id|invoice_id)\b", DataDependencyType.ID),
     (r"\b(?:auth_token|bearer_token|access_token|jwt_token|token)\b", DataDependencyType.AUTH_TOKEN),

package/tools/update_sentinel.py

@@ -65,7 +65,7 @@ def get_local_version():
         try:
             with open(pkg_file, "r", encoding="utf-8") as f:
                 data = json.load(f)
-                return data.get("version", "2.7.0")
+                return data.get("version", "3.0.1")
         except (OSError, json.JSONDecodeError):
             data = {}
 
@@ -74,11 +74,11 @@ def get_local_version():
         try:
             with open(manifest_file, "r", encoding="utf-8") as f:
                 data = json.load(f)
-                return data.get("version", "2.7.0")
+                return data.get("version", "3.0.1")
         except (OSError, json.JSONDecodeError):
             data = {}
 
-    return "2.7.0"
+    return "3.0.1"
 
 
 def fetch_remote_version():
@@ -259,7 +259,6 @@ def perform_update():
     git_dir = os.path.join(HUB_ROOT, ".git")
     is_git_repo = os.path.exists(git_dir)
 
-    updated = False
 
     if is_git_repo:
         print(f"\n{BOLD}[1/3] Pulling latest updates via Git...{RESET}")
@@ -281,7 +280,6 @@ def perform_update():
                     print(f"  {RED}⚠️ Provenance Warning: {msg}{RESET}")
                 else:
                     print(f"  {GREEN}[OK] {msg}{RESET}")
-                updated = True
                 # If this is the first pull, show the welcome landing page
                 try:
                     import welcome_page
@@ -306,9 +304,8 @@ def perform_update():
             )
             if res.returncode == 0:
                 print(f"  {GREEN}[OK] Global NPM package updated to latest!{RESET}")
-                updated = True
         except (subprocess.SubprocessError, OSError):
-            updated = False
+            _ = False
 
     # 2. Check Global Plugin
     if os.path.exists(GLOBAL_PLUGIN_DIR) and GLOBAL_PLUGIN_DIR.lower() != HUB_ROOT.lower():
@@ -319,7 +316,7 @@ def perform_update():
                 subprocess.run(["git", "pull", "--ff-only"], cwd=GLOBAL_PLUGIN_DIR, stdout=subprocess.DEVNULL, timeout=30.0)
                 print(f"  {GREEN}[OK] Updated Global Plugin repository: {GLOBAL_PLUGIN_DIR}{RESET}")
             except (subprocess.SubprocessError, OSError):
-                plugin_synced = False
+                _ = False
         else:
             # Refresh metadata files in global plugin
             try:
@@ -331,7 +328,7 @@ def perform_update():
                         shutil.copy2(src_f, dst_f)
                 print(f"  {GREEN}[OK] Refreshed metadata & LICENSE in: {GLOBAL_PLUGIN_DIR}{RESET}")
             except OSError:
-                copy_done = False
+                _ = False
 
     # 3. Re-initialize SQLite Memory Cache
     print(f"\n{BOLD}[3/3] Synchronizing Central Agent Memory Cache...{RESET}")

package/tools/verify_all.py

@@ -136,6 +136,7 @@ def resolve_target_repo(cli_target=None, cli_repo=None):
 
 
 def gate_0_author_integrity(repo_root, mode="AUTO"):
+    """Gate 0: Verifies author attribution and MIT license provenance across source manifests."""
     print("\n[GATE 0] Verifying Author Attribution & MIT License Integrity...")
     try:
         from author_integrity import (
@@ -194,6 +195,7 @@ MOJIBAKE_INDICATORS = (
 
 
 def gate_1_bom_check(repo_root, mode="AUTO"):
+    """Gate 1: Verifies 100% UTF-8 encoding with zero Byte Order Mark (BOM) bytes."""
     print("\n[GATE 1] Scanning UTF-8 No BOM and Encoding Integrity across repository...")
     ignored_dirs = {".git", ".gradle", "node_modules", "allure-results", "graphify-out", "__pycache__", "build", "dist", "claude-ecosystem-repos", "external_repos", "teamwork"}
     ignored_files = {"verify_all.py", "test_tools.py"}
@@ -241,6 +243,7 @@ def gate_1_bom_check(repo_root, mode="AUTO"):
 
 
 def gate_2_path_portability(repo_root, mode="AUTO"):
+    """Gate 2: Scans for and rejects machine-specific absolute filepaths in code."""
     print("\n[GATE 2] Checking Path Portability (Zero absolute machine paths in repo sources)...")
     ignored_dirs = {
         ".git", ".gradle", "node_modules", "allure-results", "Screenshots",
@@ -286,13 +289,14 @@ def gate_2_path_portability(repo_root, mode="AUTO"):
 
 
 def gate_3_clean_pom(repo_root, mode="AUTO"):
+    """Gate 3: Enforces Clean Page Object Model by rejecting raw selectors in test scripts."""
     print("\n[GATE 3] Checking Clean POM & Flat Architecture in Test Scripts...")
     effective_mode = detect_repo_mode(repo_root) if mode == "AUTO" else mode
     if effective_mode == "HUB":
         print("[N/A] Hub Mode: Not Applicable (Clean POM rules apply to target test suites in Spokes).")
         return True
 
-    test_dirs = ["Scripts", "tests", "test", "e2e", "specs", "cypress"]
+    test_dirs = ["tests"] if effective_mode == "HUB" else ["Scripts", "tests", "test", "e2e", "specs", "cypress"]
     test_files = []
     for td in test_dirs:
         d = os.path.join(repo_root, td)
@@ -346,6 +350,7 @@ def gate_3_clean_pom(repo_root, mode="AUTO"):
 
 
 def gate_4_ai_docs_lint(repo_root, mode="AUTO"):
+    """Gate 4: Reconciles PROJECT_AI_GUIDE.md against physical AST to prevent hallucinated classes."""
     print("\n[GATE 4] Running AI Documentation & Artifact Linter...")
     linter_script = os.path.join(SCRIPT_DIR, "lint_ai_docs.py")
     if not os.path.exists(linter_script):
@@ -368,6 +373,7 @@ def gate_4_ai_docs_lint(repo_root, mode="AUTO"):
 
 
 def gate_5_cleanup_blacklist(repo_root, mode="AUTO"):
+    """Gate 5: Scans for prohibited temporary files, heap dumps, and local cache artifacts."""
     print("\n[GATE 5] Checking Temporary File Blacklist...")
     blacklist_patterns = [
         os.path.join(repo_root, "Reports", "batch*.properties"),
@@ -392,6 +398,7 @@ def gate_5_cleanup_blacklist(repo_root, mode="AUTO"):
 
 
 def gate_6_credential_security(repo_root, mode="AUTO"):
+    """Gate 6: Scans for plaintext passwords, API tokens, and private keys across codebase."""
     print("\n[GATE 6] Checking Credential Security across repository...")
     violations = []
 
@@ -658,6 +665,7 @@ def check_python_ast_integrity(repo_root):
 
 
 def gate_7_infer_linter(repo_root, mode="AUTO"):
+    """Gate 7: Runs Meta Infer-style static defect sentinel catching fake passes, 0 assert, and sleeps."""
     print("\n[GATE 7] Running Meta Infer-Style Static Defect & Fake-Pass Sentinel...")
     effective_mode = detect_repo_mode(repo_root) if mode == "AUTO" else mode
 
@@ -700,7 +708,7 @@ def gate_7_infer_linter(repo_root, mode="AUTO"):
         except (ImportError, OSError) as err:
             print(f"[WARN] Failed to run check_version_sync: {err}")
 
-    test_dirs = ["Scripts", "tests", "test", "e2e", "specs", "cypress"]
+    test_dirs = ["tests"] if effective_mode == "HUB" else ["Scripts", "tests", "test", "e2e", "specs", "cypress"]
     has_tests = False
     target_scan_dir = None
     for td in test_dirs:
@@ -737,6 +745,7 @@ def gate_7_infer_linter(repo_root, mode="AUTO"):
 
 
 def gate_8_micro_mutator(repo_root, mode="AUTO", test_cmd=""):
+    """Gate 8: Runs syntactic mutation testing and verifies assertion sensitivity score >= 80%."""
     eval_mode_desc = f"DYNAMIC EXECUTION MODE ({test_cmd})" if test_cmd else "HEURISTIC STATIC MODE"
     print(f"\n[GATE 8] Running Assertion Sensitivity & Syntactic Mutation Sentinel [{eval_mode_desc}] (Min Score >= 80%)...")
     scripts_dir = os.path.join(repo_root, "Scripts")
@@ -797,6 +806,7 @@ def gate_8_micro_mutator(repo_root, mode="AUTO", test_cmd=""):
 
 
 def gate_9_skill_collision(repo_root, mode="AUTO"):
+    """Gate 9: Scans skill descriptions to ensure semantic trigger overlap remains < 0.75."""
     print("\n[GATE 9] Running Tier-2 Skill Routing & Collision Guard (Addy Osmani Pattern)...")
     guard_script = os.path.join(SCRIPT_DIR, "skill_collision_guard.py")
     if not os.path.exists(guard_script):

package/tools/visual_diff_canvas.py

@@ -1,6 +1,5 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
-from __future__ import annotations
 """
 Enterprise Canvas Visual Diff & Regression Checker
 ===================================================
@@ -17,11 +16,11 @@ Usage:
   python3 tools/visual_diff_canvas.py compare baseline.png current.png --diff diff.png --threshold 0.02
   python3 tools/visual_diff_canvas.py check-blank current.png
 """
+from __future__ import annotations
 
 import os
 import sys
 import argparse
-from pathlib import Path
 
 try:
     from PIL import Image, ImageChops, ImageStat
@@ -56,11 +55,12 @@ def compare_canvas_images(
     """
     with Image.open(baseline_path) as img_base, Image.open(current_path) as img_curr:
         # Normalize dimensions and color mode
+        curr_image: Image.Image = img_curr
         if img_base.size != img_curr.size:
-            img_curr = img_curr.resize(img_base.size, Image.Resampling.LANCZOS)
+            curr_image = img_curr.resize(img_base.size, Image.Resampling.LANCZOS)
 
         base_rgb = img_base.convert("RGB")
-        curr_rgb = img_curr.convert("RGB")
+        curr_rgb = curr_image.convert("RGB")
 
         # C-level accelerated pixel difference via Pillow vectorization
         diff = ImageChops.difference(base_rgb, curr_rgb)