synapse-hub 2.7.0 → 3.0.1

package/tools/infer_linter.py

@@ -16,6 +16,7 @@ import sys
 import re
 import json
 import glob
+import ast
 import html as html_lib
 import argparse
 from datetime import datetime
@@ -44,7 +45,7 @@ RESET = "\033[0m"
 
 # Optional Tree-Sitter Integration for compiler-grade AST parsing across TS/Java/C#
 try:
-    import tree_sitter  # type: ignore
+    import tree_sitter  # type: ignore # noqa: F401
     HAS_TREE_SITTER = True
 except ImportError:
     HAS_TREE_SITTER = False
@@ -76,15 +77,19 @@ def parse_with_tree_sitter(file_path, content):
         return None
 
 # Generic Detection regexes (including Cypress .should and .and assertions)
+# Note: Standalone expect(...) without chained matcher is caught as DANGLING_ASSERTION_NO_MATCHER.
 ASSERTION_PATTERN = re.compile(
-    r'\b(verify[A-Za-z0-9_]*|assert[A-Za-z0-9_]*|waitForToast|checkStatus|assertEquals|assertTrue|assertFalse|assertThat|expect|ensure[A-Z][A-Za-z0-9_]*Exists)\b|\.should\s*\(|\.and\s*\('
+    r'\b(verify[A-Za-z0-9_]*|assert[A-Za-z0-9_]*|waitForToast|checkStatus|assertEquals|assertTrue|assertFalse|assertThat|expect|ensure[A-Z][A-Za-z0-9_]*Exists)\b'
+    r'|\.should\s*\('
+    r'|\.and\s*\(',
+    re.MULTILINE
 )
 
 # Rule L1 & L5: Empty catch / swallowed exceptions across JS/TS/Groovy/Java and Python
-# Also catches try/catch that only console.log or promise .catch(() => {})
+# Also catches try/catch that only console.log/logger.error or promise .catch(() => {})
 EMPTY_CATCH_PATTERN = re.compile(
-    r'(?:catch\s*(?:\([^\)]*\))?\s*\{\s*(?:console\.(?:log|warn|error)\([^)]*\);?\s*)?\}'
-    r'|\.catch\s*\(\s*(?:\([^)]*\)|[a-zA-Z0-9_]+)?\s*=>\s*\{\s*(?:console\.(?:log|warn|error)\([^)]*\);?\s*)?\}\s*\)'
+    r'(?:catch\s*(?:\([^\)]*\))?\s*\{\s*(?:(?:console|logger|log)\.(?:log|warn|error|info)\([^)]*\);?\s*)?\}'
+    r'|\.catch\s*\(\s*(?:\([^)]*\)|[a-zA-Z0-9_]+)?\s*=>\s*\{\s*(?:(?:console|logger|log)\.(?:log|warn|error|info)\([^)]*\);?\s*)?\}\s*\)'
     r'|\bexcept(?:\s+[^:]*)?:\s*(?:pass|\.\.\.)(?:\s*$|\s*#))',
     re.MULTILINE
 )
@@ -96,16 +101,48 @@ BENIGN_TRY_CALL_PATTERN = re.compile(
     r'^[\w\.]*\.(?:reconfigure|chmod|flush)\s*\('
 )
 
-# Rule L3: Tautological assertions (e.g. expect(true).toBe(true), assert r == r, expect(true).toBeTruthy())
+# Rule L3: Tautological assertions (e.g. expect(true).toBe(true), assert r == r, assert f() == f(), assert len(x) >= 0)
 TAUTOLOGY_PATTERN = re.compile(
-    r'(?:expect\s*\(\s*(?:true|1)\s*\)\s*\.\s*(?:toBe|toEqual|toBeTruthy)\s*\(\s*(?:true|1)?\s*\)'
+    r'(?:expect(?:\.soft|\.poll)?\s*\(\s*(?:true|1|null|undefined)\s*\)\s*\.\s*(?:toBe|toEqual|toBeTruthy|toBeNull|toBeUndefined)\s*\(\s*(?:true|1|null|undefined)?\s*\)'
+    r'|expect(?:\.soft|\.poll)?\s*\(\s*([a-zA-Z0-9_]+)\s*\)\s*\.\s*(?:toBe|toEqual)\s*\(\s*\1\s*\)'
     r'|\bassert\s+(?:True|true|1\s*==\s*1)\b'
-    r'|\bassert\s+([a-zA-Z0-9_]+)\s*==\s*\1\b'
-    r'|assertEquals\s*\(\s*(?:true|1)\s*,\s*(?:true|1)\s*\)'
+    r'|\bassert\s+([a-zA-Z0-9_\.]+(?:\([^)]*\))?)\s*==\s*\1\b'
+    r'|\bassert\s+(?:len\s*\([^)]*\)|[a-zA-Z0-9_\.]+\.(?:length|size\(\)))\s*(?:>=\s*0|>\s*-(?:1|0))\b'
+    r'|assertEquals\s*\(\s*(?:true|1|null)\s*,\s*(?:true|1|null)\s*\)'
     r'|assertTrue\s*\(\s*(?:true|1)\s*\))',
     re.IGNORECASE
 )
 
+
+def find_dangling_expects(clean_code, raw_lines):
+    """
+    Detects dangling expect(...) calls lacking chained matchers (e.g. expect(page) without .toBeVisible()).
+    Correctly handles nested parentheses like expect(page.locator('#id')).
+    """
+    dangling = []
+    pattern = re.compile(r'(?:await\s+)?\bexpect(?:\.soft|\.poll)?\s*\(')
+    for m in pattern.finditer(clean_code):
+        start_idx = m.end()
+        depth = 1
+        pos = start_idx
+        while pos < len(clean_code) and depth > 0:
+            ch = clean_code[pos]
+            if ch == '(':
+                depth += 1
+            elif ch == ')':
+                depth -= 1
+            elif ch in (';', '\n') and depth > 0:
+                # Malformed unclosed expect
+                break
+            pos += 1
+        if depth == 0:
+            rest = clean_code[pos:].lstrip()
+            if not rest.startswith('.'):
+                line_no = clean_code[:m.start()].count("\n") + 1
+                raw_line = raw_lines[line_no - 1].strip() if line_no <= len(raw_lines) else ""
+                dangling.append((line_no, raw_line))
+    return dangling
+
 # Rule L4: Unawaited Playwright assertions in JS/TS
 # Expanded with all standard Playwright async matchers and optional .not modifier
 PLAYWRIGHT_ASYNC_MATCHERS = (
@@ -135,7 +172,7 @@ THREAD_SLEEP_PATTERN = MS_DELAY_PATTERN
 
 def strip_comments_and_strings(source_code, preserve_newlines=True):
     """
-    Lexically strips block comments, line comments, multiline strings, 
+    Lexically strips block comments, line comments, multiline strings,
     and quoted literals while preserving line numbering.
     Prevents false-positive / false-negative matches in AST linter.
     """
@@ -173,7 +210,7 @@ def _is_benign_empty_catch(clean_code, match_start):
         if not stripped:
             continue
         if re.match(r'try\s*(?:[:{]|$)', stripped):
-            return bool(body_lines) and all(BENIGN_TRY_CALL_PATTERN.match(l) for l in body_lines)
+            return bool(body_lines) and all(BENIGN_TRY_CALL_PATTERN.match(bl) for bl in body_lines)
         body_lines.append(stripped)
     return False
 
@@ -185,7 +222,7 @@ def load_config(repo_root=None, config_path=None):
             with open(config_path, "r", encoding="utf-8") as f:
                 return json.load(f)
         except (OSError, json.JSONDecodeError):
-            config_data = {}
+            _ = False
 
     root = repo_root or REPO_ROOT
     candidates = [
@@ -300,7 +337,7 @@ def format_junit(report_data):
     return "\n".join(lines)
 
 
-def classify_file_role(file_path: str) -> str:
+def classify_file_role(file_path: str, content: str = "") -> str:
     """
     Classifies a source file into:
       - 'CONFIG': Configuration files (playwright.config, cypress.config, conftest, wdio.conf, jest.config)
@@ -324,6 +361,8 @@ def classify_file_role(file_path: str) -> str:
         return "PAGE_OBJECT"
     if re.search(r'(^|_)basepage\b', base) or re.search(r'[a-z0-9_]page\.(ts|js|py|groovy|java)$', base):
         return "PAGE_OBJECT"
+    if content and (re.search(r'\bclass\s+[A-Za-z0-9_]*Page\b', content) or re.search(r'\bextends\s+BasePage\b', content)):
+        return "PAGE_OBJECT"
 
     # 3. Helpers & Fixtures / Tools & Utilities / Benchmarks
     if any(p in ("fixtures", "helpers", "utils", "support", "tools", "bin", "benchmarks", "benchmark") for p in parts):
@@ -348,13 +387,16 @@ def classify_file_role(file_path: str) -> str:
 
 def analyze_script(file_path, baseline_set=None, disabled_rules=None):
     """Performs static rule scanning on a single test script or automation asset."""
-    role = classify_file_role(file_path)
-
     try:
         rel_path = os.path.relpath(file_path, REPO_ROOT)
     except ValueError:
         rel_path = os.path.abspath(file_path)
 
+    with open(file_path, "r", encoding="utf-8", errors="ignore") as f:
+        content = f.read()
+
+    role = classify_file_role(file_path, content=content)
+
     # Config files have zero test assertions by definition
     if role == "CONFIG":
         return {
@@ -364,14 +406,11 @@ def analyze_script(file_path, baseline_set=None, disabled_rules=None):
             "is_clean": True
         }
 
-    with open(file_path, "r", encoding="utf-8", errors="ignore") as f:
-        content = f.read()
-
     defects = []
 
     # Lexically strip comments and string literals for accurate analysis
     clean_code = strip_comments_and_strings(content, preserve_newlines=True)
-    clean_lines = [l.strip() for l in clean_code.splitlines()]
+    clean_lines = [line.strip() for line in clean_code.splitlines()]
 
     raw_lines = content.splitlines()
 
@@ -402,12 +441,14 @@ def analyze_script(file_path, baseline_set=None, disabled_rules=None):
             elif arg.isdigit():
                 delay_val = int(arg)
                 if delay_val > 0:
-                    d_type = "EXCESSIVE_HARD_DELAY" if delay_val >= 3000 else "HARD_DELAY_ANTI_PATTERN"
+                    is_excessive = delay_val >= 3000
+                    d_type = "EXCESSIVE_HARD_DELAY" if is_excessive else "HARD_DELAY_ANTI_PATTERN"
+                    sev = "CRITICAL" if (is_excessive and role == "TEST_SCRIPT") else "WARNING"
                     defects.append({
                         "type": d_type,
-                        "severity": "WARNING",
+                        "severity": sev,
                         "line": idx,
-                        "message": f"Static sleep of {delay_val}ms found ('{raw_line}'). Replace with dynamic Smart Wait (waitForElement/networkidle)."
+                        "message": f"Static sleep of {delay_val}ms found ('{raw_line}'). {'Prohibited in test scripts by AGENTS.md Rule 1.4. ' if is_excessive else ''}Replace with dynamic Smart Wait (waitForElement/networkidle)."
                     })
                     continue
             elif re.match(r'^[a-zA-Z_][a-zA-Z0-9_]*$', arg) and not line.strip().startswith("cy.wait"):
@@ -428,12 +469,14 @@ def analyze_script(file_path, baseline_set=None, disabled_rules=None):
                 if delay_val > 0:
                     delay_ms = int(delay_val * 1000)
                     delay_str = f"{delay_val:g}"
-                    d_type = "EXCESSIVE_HARD_DELAY" if delay_ms >= 3000 else "HARD_DELAY_ANTI_PATTERN"
+                    is_excessive = delay_ms >= 3000
+                    d_type = "EXCESSIVE_HARD_DELAY" if is_excessive else "HARD_DELAY_ANTI_PATTERN"
+                    sev = "CRITICAL" if (is_excessive and role == "TEST_SCRIPT") else "WARNING"
                     defects.append({
                         "type": d_type,
-                        "severity": "WARNING",
+                        "severity": sev,
                         "line": idx,
-                        "message": f"Static sleep of {delay_str}s ({delay_ms}ms) found ('{raw_line}'). Replace with dynamic Smart Wait (waitForElement/networkidle)."
+                        "message": f"Static sleep of {delay_str}s ({delay_ms}ms) found ('{raw_line}'). {'Prohibited in test scripts by AGENTS.md Rule 1.4. ' if is_excessive else ''}Replace with dynamic Smart Wait (waitForElement/networkidle)."
                     })
             except ValueError:
                 if re.match(r'^[a-zA-Z_][a-zA-Z0-9_]*$', arg):
@@ -447,8 +490,8 @@ def analyze_script(file_path, baseline_set=None, disabled_rules=None):
     # Test Script Specific Invariants (Do NOT apply to Page Objects or Helpers)
     if role == "TEST_SCRIPT":
         executable_lines = [
-            l for l in clean_lines 
-            if l and not l.startswith("import ") and not l.startswith("package ") and not l.startswith("from ")
+            line for line in clean_lines
+            if line and not line.startswith("import ") and not line.startswith("package ") and not line.startswith("from ")
         ]
         # Rule 1: Empty Test Script
         if len(executable_lines) == 0:
@@ -470,6 +513,68 @@ def analyze_script(file_path, baseline_set=None, disabled_rules=None):
                     "message": f"Tautological assertion detected ('{raw_line}'). Test assertion always evaluates to True without testing system state."
                 })
 
+        # Rule 4.1: Dangling expect(...) calls without chained matcher
+        for d_line, d_raw in find_dangling_expects(clean_code, raw_lines):
+            defects.append({
+                "type": "DANGLING_ASSERTION_NO_MATCHER",
+                "severity": "CRITICAL",
+                "line": d_line,
+                "message": f"Dangling expect() call without matcher detected ('{d_raw}'). expect() returns an expectation object and does not perform any assertion without a matcher (e.g. .toBeVisible(), .toHaveText())."
+            })
+
+        # Rule 4.2: Python AST Compiler-Grade Verification for .py Test Scripts
+        if file_path.endswith(".py"):
+            try:
+                tree = ast.parse(content, filename=file_path)
+                for node in ast.walk(tree):
+                    if isinstance(node, ast.Assert):
+                        if isinstance(node.test, ast.Compare) and len(node.test.ops) == 1:
+                            op = node.test.ops[0]
+                            right = node.test.comparators[0]
+                            if isinstance(op, ast.Eq):
+                                if ast.dump(node.test.left) == ast.dump(right):
+                                    line_no = getattr(node, "lineno", 1)
+                                    raw_line = raw_lines[line_no - 1].strip() if line_no <= len(raw_lines) else ""
+                                    defects.append({
+                                        "type": "TAUTOLOGICAL_ASSERTION",
+                                        "severity": "CRITICAL",
+                                        "line": line_no,
+                                        "message": f"Tautological assertion detected via AST ('{raw_line}'). Both sides of comparison evaluate to identical AST expressions."
+                                    })
+                            elif isinstance(op, (ast.GtE, ast.Gt)):
+                                if isinstance(node.test.left, ast.Call) and getattr(node.test.left.func, 'id', None) == 'len':
+                                    if isinstance(right, ast.Constant):
+                                        if (isinstance(op, ast.GtE) and right.value == 0) or (isinstance(op, ast.Gt) and right.value < 0):
+                                            line_no = getattr(node, "lineno", 1)
+                                            raw_line = raw_lines[line_no - 1].strip() if line_no <= len(raw_lines) else ""
+                                            defects.append({
+                                                "type": "TAUTOLOGICAL_ASSERTION",
+                                                "severity": "CRITICAL",
+                                                "line": line_no,
+                                                "message": f"Tautological assertion detected via AST ('{raw_line}'). len() is non-negative by definition."
+                                            })
+                        elif isinstance(node.test, ast.Constant) and node.test.value is True:
+                            line_no = getattr(node, "lineno", 1)
+                            raw_line = raw_lines[line_no - 1].strip() if line_no <= len(raw_lines) else ""
+                            defects.append({
+                                "type": "TAUTOLOGICAL_ASSERTION",
+                                "severity": "CRITICAL",
+                                "line": line_no,
+                                "message": f"Tautological assertion detected via AST ('{raw_line}'). Constant True assertion."
+                            })
+                    elif isinstance(node, ast.Expr) and isinstance(node.value, ast.Call):
+                        if getattr(node.value.func, 'id', None) == 'expect':
+                            line_no = getattr(node, "lineno", 1)
+                            raw_line = raw_lines[line_no - 1].strip() if line_no <= len(raw_lines) else ""
+                            defects.append({
+                                "type": "DANGLING_ASSERTION_NO_MATCHER",
+                                "severity": "CRITICAL",
+                                "line": line_no,
+                                "message": f"Dangling expect() call without matcher detected via AST ('{raw_line}')."
+                            })
+            except SyntaxError:
+                _ = False  # synapse-ignore
+
         # Rule 5 (L4): Unawaited Playwright Assertions in JS/TS
         if file_path.endswith((".ts", ".tsx", ".js", ".jsx")):
             for match in UNAWAITED_EXPECT_PATTERN.finditer(clean_code):
@@ -544,6 +649,15 @@ def analyze_script(file_path, baseline_set=None, disabled_rules=None):
                     "message": "Test case file contains executable logic but has no verification or assertion statements."
                 })
 
+    seen_keys = set()
+    deduped = []
+    for d in defects:
+        k = (d.get("type"), d.get("line"))
+        if k not in seen_keys:
+            seen_keys.add(k)
+            deduped.append(d)
+    defects = deduped
+
     active_defects = []
     disabled = {r.upper() for r in (disabled_rules or [])}
     norm_rel = rel_path.replace("\\", "/")
@@ -740,7 +854,7 @@ def run_infer_linter(target_dir=None, output_path=None, strict: bool = False,
         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("  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)")
@@ -777,7 +891,7 @@ def run_infer_linter(target_dir=None, output_path=None, strict: bool = False,
             sys.stderr.write(f"Notice: Target report write failed: {err}\n")
 
     if strict:
-        fake_pass_count = sum(1 for r in results for d in r["defects"] if d["type"] in ("FAKE_PASS_NO_ASSERTION", "NO_ASSERTION_IN_TEST"))
+        fake_pass_count = sum(1 for r in results for d in r["defects"] if d["type"] in ("FAKE_PASS_NO_ASSERTION", "NO_ASSERTION_IN_TEST", "DANGLING_ASSERTION_NO_MATCHER"))
         return 0 if (critical_count == 0 and fake_pass_count == 0) else 1
     return 0 if critical_count == 0 else 1
 

package/tools/interview_story.py

@@ -16,7 +16,6 @@ Reference:
   - Synapse-Hub Subsystem 6: Section 6.7 of agent_skill_training_analysis.md.
 """
 
-import os
 import sys
 import re
 import json

package/tools/jtl_analyzer.py

@@ -163,16 +163,16 @@ def parse_csv_jtl(filepath: str) -> Tuple[Dict[str, SamplerStats], SamplerStats]
                 # Column names can vary slightly across JMeter versions
                 elapsed = float(row.get("elapsed") or row.get("Elapsed") or row.get("time") or 0)
                 label = row.get("label") or row.get("Label") or "Unknown"
-                
+
                 success_val = row.get("success") or row.get("Success") or "true"
                 success = str(success_val).strip().lower() in ("true", "1")
-                
+
                 ts_val = row.get("timeStamp") or row.get("Timestamp") or row.get("t") or 0
                 timestamp = int(float(ts_val))
-                
+
                 bytes_val = row.get("bytes") or row.get("Bytes") or 0
                 bytes_recv = int(float(bytes_val))
-                
+
                 resp_code = row.get("responseCode") or row.get("ResponseCode") or row.get("rc") or "200"
 
                 if label not in per_sampler:
@@ -236,7 +236,7 @@ def evaluate_sla(
 ) -> Tuple[bool, List[str]]:
     """Evaluates computed aggregate metrics against SLA limits."""
     violations: List[str] = []
-    
+
     if sla_p95 is not None and agg_stats["p95_ms"] > sla_p95:
         violations.append(f"P95 Latency SLA Breached: {agg_stats['p95_ms']}ms > {sla_p95}ms")
 
@@ -261,7 +261,7 @@ def format_table(per_sampler_data: List[Dict[str, Any]], agg_data: Dict[str, Any
     lines = []
     header_str = " | ".join(h.ljust(col_w[i]) for i, h in enumerate(headers))
     sep_str = "-+-".join("-" * col_w[i] for i in range(len(headers)))
-    
+
     lines.append(header_str)
     lines.append(sep_str)
 
@@ -271,7 +271,7 @@ def format_table(per_sampler_data: List[Dict[str, Any]], agg_data: Dict[str, Any
         if len(label) > 28:
             label = label[:25] + "..."
         err_str = f"{row['errors']} ({row['error_rate_pct']}%)"
-        
+
         row_str = " | ".join([
             label.ljust(col_w[0]),
             str(row["samples"]).rjust(col_w[1]),
@@ -301,7 +301,7 @@ def generate_markdown_report(
 ) -> str:
     """Generates GitHub / GitLab Markdown report for Pull Request annotations."""
     status_badge = "✅ **PASSED**" if passed else "❌ **FAILED (SLA BREACHED)**"
-    
+
     lines = [
         "# 🚀 Apache JMeter Performance & Load Test Report",
         "",
@@ -377,7 +377,7 @@ def main():
         with open(temp_jtl, "w", encoding="utf-8", newline="") as f:
             writer = csv.writer(f)
             writer.writerow(["timeStamp", "elapsed", "label", "responseCode", "responseMessage", "threadName", "dataType", "success", "failureMessage", "bytes", "sentBytes", "grpThreads", "allThreads", "URL", "Latency", "IdleTime", "Connect"])
-            
+
             # Generate 200 synthetic rows
             import time
             base_time = int(time.time() * 1000)
@@ -387,7 +387,7 @@ def main():
                 writer.writerow([base_time + (i * 100), 280 + (i % 80), "[POST] /api/v1/orders", "201", "Created", "Thread 1-2", "text", "true", "", 2048, 512, 10, 10, "http://api.local/orders", 270, 0, 20])
             for i in range(5):
                 writer.writerow([base_time + (i * 100), 1500, "[POST] /api/v1/orders", "500", "Internal Error", "Thread 1-2", "text", "false", "DB Timeout", 512, 512, 10, 10, "http://api.local/orders", 1490, 0, 25])
-        
+
         args.jtl_file = temp_jtl
         print(f"🔬 [SAMPLE MODE] Generated synthetic benchmark JTL: {temp_jtl}")
 
@@ -414,7 +414,7 @@ def main():
     print("=" * 90)
 
     # Print SLA Verdict
-    print(f"\n🎯 [QUALITY GATE SLA VERDICT]")
+    print("\n🎯 [QUALITY GATE SLA VERDICT]")
     if passed:
         print("✅ ALL PERFORMANCE SLAs PASSED! Ready for deployment/merge.")
     else:

package/tools/lint/__init__.py

@@ -0,0 +1,30 @@
+"""
+Synapse Hub — Static Quality & Policy Sentinels (tools.lint)
+-----------------------------------------------------------
+Domain package grouping all static code defect, encoding, license,
+and AI documentation drift verification tools.
+"""
+
+from tools import (
+    author_integrity,
+    check_version_sync,
+    git_pre_commit_guard,
+    infer_linter,
+    lint_ai_docs,
+    skill_collision_guard,
+    skillspector,
+    spec_drift_sentinel,
+    validate_groovy_scripts,
+)
+
+__all__ = [
+    "author_integrity",
+    "check_version_sync",
+    "git_pre_commit_guard",
+    "infer_linter",
+    "lint_ai_docs",
+    "skill_collision_guard",
+    "skillspector",
+    "spec_drift_sentinel",
+    "validate_groovy_scripts",
+]

package/tools/lint_ai_docs.py

@@ -281,8 +281,50 @@ def lint_docs(repo_root):
                     if mname not in valid_methods:
                         errors.append(f"[{doc}:{line_no}] Non-existent method referenced: '{cname}.{mname}()' (Class '{cname}' does not define this method)")
 
+    # 6. Documentation Metrics Consistency (Detects stale skill/tool/gate numbers)
+    metric_errors = check_doc_metrics_consistency(repo_root)
+    errors.extend(metric_errors)
+
     return errors, warnings
 
+
+def check_doc_metrics_consistency(repo_root):
+    """Verifies that documented counts (skills, tools, DoD gates) accurately match disk."""
+    errors = []
+    skills_dir = os.path.join(repo_root, ".agents", "skills")
+    tools_dir = os.path.join(repo_root, "tools")
+
+    if not os.path.isdir(skills_dir) or not os.path.isdir(tools_dir):
+        return errors
+
+    skills_count = len([d for d in os.listdir(skills_dir) if os.path.isdir(os.path.join(skills_dir, d)) and os.path.exists(os.path.join(skills_dir, d, "SKILL.md"))])
+    tools_count = len([f for f in os.listdir(tools_dir) if f.endswith(".py") and f != "__init__.py"])
+
+    obsolete_patterns = [
+        (re.compile(r'\b(42|50)\s+(kỹ năng|skills?)\b', re.IGNORECASE), f"Obsolete skill count detected (real count: {skills_count})"),
+        (re.compile(r'\b(60|68)\s+(công cụ|tools?)\b', re.IGNORECASE), f"Obsolete tool count detected (real count: {tools_count})"),
+        (re.compile(r'\b9\s+Cổng\s+Chất\s+Lượng\b', re.IGNORECASE), "Obsolete gate count detected: must refer to 10 Cổng Chất Lượng DoD (Gate 0–9)"),
+    ]
+
+    docs_to_check = [
+        os.path.join(repo_root, "README.md"),
+        os.path.join(repo_root, "README.en.md"),
+        os.path.join(repo_root, "docs", "ARCHITECTURE.md"),
+        os.path.join(repo_root, "docs", "CONTRIBUTING.md"),
+    ]
+
+    for doc_path in docs_to_check:
+        if not os.path.exists(doc_path):
+            continue
+        rel_doc = os.path.relpath(doc_path, repo_root)
+        with open(doc_path, "r", encoding="utf-8", errors="ignore") as f:
+            for line_no, line in enumerate(f, 1):
+                for pattern, msg in obsolete_patterns:
+                    if pattern.search(line):
+                        errors.append(f"[{rel_doc}:{line_no}] {msg}: '{line.strip()}'")
+
+    return errors
+
 def main():
     import argparse
     parser = argparse.ArgumentParser(description="Enterprise AI Documentation & Artifact Linter")

package/tools/lookup_tc.py

@@ -87,7 +87,7 @@ def normalize_testcase_data(raw_data):
             return raw_data["testcases"]
         if "items" in raw_data and isinstance(raw_data["items"], list):
             return raw_data["items"]
-        
+
         flat = []
         for k, v in raw_data.items():
             if isinstance(v, dict):

package/tools/matrix_sharder.py

@@ -52,13 +52,15 @@ def estimate_test_duration(file_path: str, full_path: str) -> float:
     if os.path.exists(CACHE_DB_PATH):
         try:
             conn = sqlite3.connect(CACHE_DB_PATH)
-            cur = conn.cursor()
-            cur.execute("CREATE TABLE IF NOT EXISTS test_runtimes (test_path TEXT PRIMARY KEY, duration REAL)")
-            cur.execute("SELECT duration FROM test_runtimes WHERE test_path = ?", (file_path,))
-            row = cur.fetchone()
-            conn.close()
-            if row and row[0]:
-                return float(row[0])
+            try:
+                cur = conn.cursor()
+                cur.execute("CREATE TABLE IF NOT EXISTS test_runtimes (test_path TEXT PRIMARY KEY, duration REAL)")
+                cur.execute("SELECT duration FROM test_runtimes WHERE test_path = ?", (file_path,))
+                row = cur.fetchone()
+                if row and row[0]:
+                    return float(row[0])
+            finally:
+                conn.close()
         except sqlite3.Error:
             conn = None
 
@@ -93,14 +95,14 @@ def shard_tests_lpt(test_files: List[str], target_dir: str, num_shards: int) ->
     tests_with_cost.sort(key=lambda x: x[1], reverse=True)
 
     # 3. Initialize shards
-    shards = [{"shard_index": i + 1, "total_duration": 0.0, "tests": []} for i in range(num_shards)]
+    shards: List[Dict[str, Any]] = [{"shard_index": i + 1, "total_duration": 0.0, "tests": []} for i in range(num_shards)]
 
     # 4. Greedily assign to the shard with the least current cumulative duration
     for test_file, dur in tests_with_cost:
         # Find shard with min duration
-        min_shard = min(shards, key=lambda s: s["total_duration"])
+        min_shard = min(shards, key=lambda s: float(s["total_duration"]))
         min_shard["tests"].append(test_file)
-        min_shard["total_duration"] = round(min_shard["total_duration"] + dur, 2)
+        min_shard["total_duration"] = round(float(min_shard["total_duration"]) + dur, 2)
 
     return shards
 
@@ -119,9 +121,9 @@ def main():
     if args.json:
         print(json.dumps({"total_tests": len(test_files), "shards_count": args.shards, "shards": shards}, indent=2))
     else:
-        print(f"\n======================================================================")
+        print("\n======================================================================")
         print(f"      DURATION-BALANCED TEST MATRIX SHARDER ({args.shards} PARALLEL WORKERS)    ")
-        print(f"======================================================================")
+        print("======================================================================")
         print(f"  Target Scope : {target_dir}")
         print(f"  Total Tests  : {len(test_files)} files\n")
 
@@ -137,7 +139,7 @@ def main():
         durations = [s["total_duration"] for s in shards]
         delta = max(durations) - min(durations) if durations else 0
         print(f"⚡ Shard Imbalance Delta: {delta:.1f}s (Optimal parallel distribution)")
-        print(f"======================================================================\n")
+        print("======================================================================\n")
 
     return 0
 

package/tools/mcp/__init__.py

@@ -0,0 +1,16 @@
+"""
+Synapse Hub — Model Context Protocol (MCP) Servers (tools.mcp)
+--------------------------------------------------------------
+Domain package grouping all standard MCP services: core QA automation
+MCP server and offline Excel spreadsheet manipulation server.
+"""
+
+from tools import (
+    mcp_excel_server,
+    mcp_server,
+)
+
+__all__ = [
+    "mcp_excel_server",
+    "mcp_server",
+]

package/tools/mcp_excel_server.py

@@ -23,7 +23,7 @@ if hasattr(sys.stdout, 'reconfigure'):
     except Exception:
         pass
 
-SERVER_VERSION = "2.7.0"
+SERVER_VERSION = "3.0.1"
 
 NS_MAIN = "{http://schemas.openxmlformats.org/spreadsheetml/2006/main}"
 NS_REL = "{http://schemas.openxmlformats.org/officeDocument/2006/relationships}"
@@ -88,7 +88,7 @@ def read_sheet_rows(xlsx_path: str, sheet_name: Optional[str] = None, max_rows:
                 for c in row.iter(f"{NS_MAIN}c"):
                     cell_type = c.attrib.get("t")
                     val_elem = c.find(f"{NS_MAIN}v")
-                    raw_val = val_elem.text if val_elem is not None else ""
+                    raw_val = (val_elem.text or "") if val_elem is not None else ""
 
                     if cell_type == "s" and raw_val.isdigit():
                         idx = int(raw_val)