synapse-hub 2.7.0 → 3.0.0

package/tools/bug_reporter.py

@@ -9,11 +9,9 @@ reproduction steps, distills stacktraces (0 noise), and attaches evidence.
 """
 
 import os
-import re
-import sys
 import json
 import argparse
-from typing import Dict, List, Optional, Any
+from typing import Dict, List, Optional
 from datetime import datetime
 
 try:
@@ -22,8 +20,8 @@ except ImportError:
     try:
         from cache_resolver import compute_error_fingerprint
     except ImportError:
-        def compute_error_fingerprint(err_type: str, err_msg: str, stack_anchor: str = "") -> str:
-            raw = f"{(err_type or '').strip().lower()}:{(err_msg or '').strip()[:200]}"
+        def compute_error_fingerprint(error_type: str, error_msg: str, stack_anchor: str = "") -> str:
+            raw = f"{(error_type or '').strip().lower()}:{(error_msg or '').strip()[:200]}"
             h = 5381
             for b in raw.encode("utf-8", errors="ignore"):
                 h = (((h << 5) + h) + b) & 0xFFFFFFFF
@@ -90,13 +88,13 @@ class BugReporter:
     @staticmethod
     def distill_stack_trace(raw_stack: str, max_lines: int = 5) -> str:
         """Filters noisy framework stack trace down to actionable lines."""
-        lines = [l.strip() for l in raw_stack.splitlines() if l.strip()]
+        lines = [line.strip() for line in raw_stack.splitlines() if line.strip()]
         actionable = []
-        for l in lines:
+        for line in lines:
             # Filter standard framework internals
-            if any(internal in l for internal in ["at Module.", "node_modules", "org.gradle", "sun.reflect", "jdk.internal"]):
+            if any(internal in line for internal in ["at Module.", "node_modules", "org.gradle", "sun.reflect", "jdk.internal"]):
                 continue
-            actionable.append(l)
+            actionable.append(line)
             if len(actionable) >= max_lines:
                 break
         return "\n".join(actionable) if actionable else raw_stack[:300]
@@ -121,7 +119,7 @@ class BugReporter:
         fingerprint = compute_error_fingerprint(rca["type"], error_message, anchor)
 
         steps = steps_executed or [
-            f"1. Navigate to target application under test",
+            "1. Navigate to target application under test",
             f"2. Execute test workflow for {test_title}",
             f"3. Trigger operation causing failure: {error_message[:80]}"
         ]
@@ -144,7 +142,7 @@ class BugReporter:
             report = [
                 f"h2. [BUG][{rca['severity'].upper()}] {test_id}: {test_title} - {error_message[:90]}",
                 "",
-                f"* *Issue Type:* Bug",
+                "* *Issue Type:* Bug",
                 f"* *Error Fingerprint:* {fingerprint}",
                 f"* *Root Cause Category:* {rca['label']}",
                 f"* *Severity / Priority:* {rca['severity']}",
@@ -160,7 +158,7 @@ class BugReporter:
             report.extend([
                 "",
                 "h3. 2. Expected Result",
-                f"Operation completes successfully without errors, assertions pass.",
+                "Operation completes successfully without errors, assertions pass.",
                 "",
                 "h3. 3. Actual Result",
                 f"{{color:red}}*Failure:* {error_message}{{color}}",
@@ -199,7 +197,7 @@ class BugReporter:
             "Application executes workflow smoothly and passes all validations.",
             "",
             "## ❌ 3. Actual Result",
-            f"**Error Encountered:**",
+            "**Error Encountered:**",
             f"```text\n{error_message}\n```",
             "",
             "## 🔍 4. Distilled Stack Trace (0-Noise)",

package/tools/bump_version.py

@@ -42,12 +42,32 @@ if hasattr(sys.stdout, 'reconfigure'):
 REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 
 def parse_semver(v_str: str):
+    """Parses a semantic version string into major, minor, patch integers and optional suffix.
+
+    Args:
+        v_str: The version string to parse (e.g. '2.9.0' or '2.9.0-rc1').
+
+    Returns:
+        A tuple of (major, minor, patch, suffix).
+
+    Raises:
+        ValueError: If the string does not follow semantic versioning.
+    """
     m = re.match(r"^(\d+)\.(\d+)\.(\d+)(.*)$", v_str.strip())
     if not m:
         raise ValueError(f"Invalid semver: '{v_str}'. Must follow major.minor.patch[-suffix]")
     return int(m.group(1)), int(m.group(2)), int(m.group(3)), m.group(4)
 
 def calculate_next_version(current: str, action: str) -> str:
+    """Computes the target version based on an action or explicit semver string.
+
+    Args:
+        current: Current semver version string.
+        action: 'patch', 'minor', 'major', or an explicit target version string.
+
+    Returns:
+        The computed next semver version string.
+    """
     major, minor, patch, suffix = parse_semver(current)
     action = action.lower()
     if action == "patch":
@@ -62,6 +82,14 @@ def calculate_next_version(current: str, action: str) -> str:
         return action
 
 def get_current_version() -> str:
+    """Reads the current canonical version from package.json in the repository root.
+
+    Returns:
+        The version string.
+
+    Raises:
+        ValueError: If package.json is missing or lacks a valid version field.
+    """
     pkg_file = os.path.join(REPO_ROOT, "package.json")
     with open(pkg_file, "r", encoding="utf-8") as f:
         data = json.load(f)
@@ -71,6 +99,16 @@ def get_current_version() -> str:
     return version
 
 def update_json_root_version(rel_path: str, new_ver: str, dry_run: bool = False) -> bool:
+    """Updates the top-level 'version' property in a JSON manifest file.
+
+    Args:
+        rel_path: Relative path to the target JSON file from repo root.
+        new_ver: Target version string.
+        dry_run: If True, previews changes without writing to disk.
+
+    Returns:
+        True if the file was modified or would be updated.
+    """
     full_path = os.path.join(REPO_ROOT, rel_path)
     if not os.path.exists(full_path):
         print(f"  [WARN] File not found: {rel_path}")
@@ -95,6 +133,17 @@ def update_json_root_version(rel_path: str, new_ver: str, dry_run: bool = False)
     return True
 
 def update_file(rel_path: str, pattern: str, replacement: str, dry_run: bool = False) -> bool:
+    """Performs regex replacement within a target file to update version strings.
+
+    Args:
+        rel_path: Relative path to the target file from repo root.
+        pattern: Regular expression pattern matching existing version occurrences.
+        replacement: String replacement containing the new version.
+        dry_run: If True, previews changes without writing to disk.
+
+    Returns:
+        True if matches were found and updated.
+    """
     full_path = os.path.join(REPO_ROOT, rel_path)
     if not os.path.exists(full_path):
         print(f"  [WARN] File not found: {rel_path}")
@@ -117,6 +166,11 @@ def update_file(rel_path: str, pattern: str, replacement: str, dry_run: bool = F
     return True
 
 def run_tests() -> bool:
+    """Executes the test suite and 10 DoD Quality Gates before release.
+
+    Returns:
+        True if all tests and gates pass.
+    """
     print("\n🔍 Running verification suite...")
     cmd = [sys.executable, "-m", "unittest", "discover", "tests", "-p", "test_*.py"]
     res = subprocess.run(cmd, cwd=REPO_ROOT)
@@ -130,10 +184,16 @@ def run_tests() -> bool:
     if res_verify.returncode != 0:
         print("❌ Quality Gates failed! Aborting release.")
         return False
-    print("✅ 9 Quality Gates DoD PASSED.")
+    print("✅ 10 Quality Gates DoD PASSED.")
     return True
 
 def git_commit_and_tag(version: str, push: bool = False):
+    """Creates a conventional Git release commit and tags the repository.
+
+    Args:
+        version: Target version string.
+        push: If True, pushes the commit and tag to git remote origin.
+    """
     print(f"\n📦 Creating Git commit and tag v{version}...")
     subprocess.run(["git", "add", "-A"], cwd=REPO_ROOT, check=True)
     subprocess.run(["git", "commit", "-m", f"chore(release): bump version to v{version}"], cwd=REPO_ROOT, check=True)
@@ -141,7 +201,7 @@ def git_commit_and_tag(version: str, push: bool = False):
     print(f"✅ Git commit and tag v{version} created.")
 
     if push:
-        print(f"🚀 Pushing commit and tags to remote origin...")
+        print("🚀 Pushing commit and tags to remote origin...")
         res = subprocess.run(["git", "branch", "--show-current"], cwd=REPO_ROOT, stdout=subprocess.PIPE, text=True)
         cur_branch = res.stdout.strip()
         if cur_branch == "develop":
@@ -154,9 +214,10 @@ def git_commit_and_tag(version: str, push: bool = False):
                 subprocess.run(["git", "push", "origin", "HEAD", "--tags"], cwd=REPO_ROOT, check=True)
         else:
             subprocess.run(["git", "push", "origin", "HEAD", "--tags"], cwd=REPO_ROOT, check=True)
-        print(f"✅ Remote origin synchronized.")
+        print("✅ Remote origin synchronized.")
 
 def main():
+    """CLI entrypoint for bumping Synapse Hub version synchronously across manifests."""
     parser = argparse.ArgumentParser(description="Atomic Universal Version Bumper for Synapse Hub")
     parser.add_argument("action", nargs="?", default="patch", help="patch | minor | major | <explicit_version> (default: patch)")
     parser.add_argument("--dry-run", action="store_true", help="Preview version changes without writing files")
@@ -217,8 +278,17 @@ def main():
     update_file("README.md", r'(Phiên bản Hub:\*\*\s*`v)[^`]+(`)', rf"\g<1>{new_ver}\g<2>", args.dry_run)
     update_file("README.md", r'(Hub Version:\*\*\s*`v)[^`]+(`)', rf"\g<1>{new_ver}\g<2>", args.dry_run)
     update_file("README.md", r'(Intelligence Core v)[^")\]]+', rf"\g<1>{new_ver}", args.dry_run)
+    update_file("README.md", r'(rev:\s*v)[0-9]+\.[0-9]+\.[0-9]+', rf"\g<1>{new_ver}", args.dry_run)
+    update_file("README.md", r'(Synapse Hub \(Core v)[0-9]+\.[0-9]+\.[0-9]+(\))', rf"\g<1>{new_ver}\g<2>", args.dry_run)
     update_file("README.en.md", r'(Hub Version:\*\*\s*`v)[^`]+(`)', rf"\g<1>{new_ver}\g<2>", args.dry_run)
     update_file("README.en.md", r'(Intelligence Core v)[^")\]]+', rf"\g<1>{new_ver}", args.dry_run)
+    update_file("README.en.md", r'(rev:\s*v)[0-9]+\.[0-9]+\.[0-9]+', rf"\g<1>{new_ver}", args.dry_run)
+    update_file("README.en.md", r'(Synapse Hub \(Core v)[0-9]+\.[0-9]+\.[0-9]+(\))', rf"\g<1>{new_ver}\g<2>", args.dry_run)
+
+    # 9b. SECURITY.md
+    major, minor, _, _ = parse_semver(new_ver)
+    current_branch = f"{major}.{minor}.x"
+    update_file("SECURITY.md", r'(\|\s*`)[0-9]+\.[0-9]+\.x(`\s*\|\s*✅)', rf"\g<1>{current_branch}\g<2>", args.dry_run)
 
     # 10. tools/__init__.py
     update_file("tools/__init__.py", r'(__version__\s*=\s*")[^"]+(")', rf"\g<1>{new_ver}\g<2>", args.dry_run)
@@ -267,8 +337,8 @@ def main():
     print(f"🎉 VERSION BUMP COMPLETE: v{current_ver} ➔ v{new_ver}")
     print("======================================================================")
     print("Next steps:")
-    print(f"  • Publish to NPM : npm publish")
-    print(f"  • Or Git Push    : git push origin HEAD --tags")
+    print("  • Publish to NPM : npm publish")
+    print("  • Or Git Push    : git push origin HEAD --tags")
     print("======================================================================")
 
 if __name__ == "__main__":

package/tools/cache_resolver.py

@@ -313,7 +313,7 @@ def init_db(seed=True, target_db=None):
         try:
             cursor.execute("ALTER TABLE healing_cache ADD COLUMN code_patch TEXT DEFAULT ''")
         except sqlite3.OperationalError:
-            column_exists = True
+            _ = True
 
         # 2. Negative Memory Table (Blacklist of Failed Fix Attempts)
         cursor.execute("""
@@ -362,30 +362,29 @@ def init_db(seed=True, target_db=None):
         # Migrate existing solutions from local DB if initializing global DB for the first time
         if current_db == GLOBAL_DB and os.path.exists(LOCAL_DB):
             try:
-                local_conn = get_db(LOCAL_DB)
-                rows = local_conn.execute("SELECT * FROM healing_cache").fetchall()
-                for r in rows:
-                    cursor.execute("""
-                        INSERT OR IGNORE INTO healing_cache 
-                        (error_signature, module_name, symptom, root_cause, groovy_patch, hit_count)
-                        VALUES (?, ?, ?, ?, ?, ?)
-                    """, (r["error_signature"], r["module_name"], r["symptom"], r["root_cause"], r["groovy_patch"], r["hit_count"]))
-                conn.commit()
-                local_conn.close()
+                with get_db(LOCAL_DB) as local_conn:
+                    rows = local_conn.execute("SELECT * FROM healing_cache").fetchall()
+                    for r in rows:
+                        cursor.execute("""
+                            INSERT OR IGNORE INTO healing_cache
+                            (error_signature, module_name, symptom, root_cause, groovy_patch, hit_count)
+                            VALUES (?, ?, ?, ?, ?, ?)
+                        """, (r["error_signature"], r["module_name"], r["symptom"], r["root_cause"], r["groovy_patch"], r["hit_count"]))
+                    conn.commit()
             except (sqlite3.Error, OSError) as e:
                 sys.stderr.write(f"Notice: Local cache migration skipped: {e}\n")
 
         if seed:
             for s in SEED_SOLUTIONS:
                 cursor.execute("""
-                    INSERT OR IGNORE INTO healing_cache 
+                    INSERT OR IGNORE INTO healing_cache
                     (error_signature, module_name, symptom, root_cause, groovy_patch)
                     VALUES (?, ?, ?, ?, ?)
                 """, (s["error_signature"], s["module_name"], s["symptom"], s["root_cause"], s["groovy_patch"]))
 
             for f in SEED_FAILED_FIXES:
                 cursor.execute("""
-                    SELECT COUNT(*) as cnt FROM failed_fixes 
+                    SELECT COUNT(*) as cnt FROM failed_fixes
                     WHERE error_signature = ? AND attempted_patch = ?
                 """, (f["error_signature"], f["attempted_patch"]))
                 if cursor.fetchone()["cnt"] == 0:
@@ -394,17 +393,17 @@ def init_db(seed=True, target_db=None):
                         VALUES (?, ?, ?, ?)
                     """, (f["error_signature"], f["attempted_patch"], f["failure_reason"], f["agent_role"]))
 
-            for l in SEED_LESSONS_LEARNED:
+            for les in SEED_LESSONS_LEARNED:
                 cursor.execute("""
-                    SELECT COUNT(*) as cnt FROM lessons_learned 
+                    SELECT COUNT(*) as cnt FROM lessons_learned
                     WHERE error_signature = ? AND page_context = ?
-                """, (l["error_signature"], l["page_context"]))
+                """, (les["error_signature"], les["page_context"]))
                 if cursor.fetchone()["cnt"] == 0:
                     cursor.execute("""
-                        INSERT INTO lessons_learned 
+                        INSERT INTO lessons_learned
                         (page_context, error_signature, root_cause, failed_attempt, successful_fix, lesson_summary)
                         VALUES (?, ?, ?, ?, ?, ?)
-                    """, (l["page_context"], l["error_signature"], l["root_cause"], l["failed_attempt"], l["successful_fix"], l["lesson_summary"]))
+                    """, (les["page_context"], les["error_signature"], les["root_cause"], les["failed_attempt"], les["successful_fix"], les["lesson_summary"]))
             conn.commit()
 
 
@@ -552,7 +551,7 @@ def get_failed_fixes(error_signature):
     with get_db() as conn:
         cursor = conn.cursor()
         cursor.execute("""
-            SELECT * FROM failed_fixes 
+            SELECT * FROM failed_fixes
             WHERE error_signature = ? OR error_signature LIKE ?
             ORDER BY created_at DESC
         """, (error_signature, f"%{error_signature}%"))
@@ -587,7 +586,7 @@ def query_solution(error_signature, module_name="GLOBAL", threshold=0.35):
         cursor = conn.cursor()
         # 1. Exact match with module
         cursor.execute("""
-            SELECT * FROM healing_cache 
+            SELECT * FROM healing_cache
             WHERE error_signature = ? AND module_name = ?
         """, (error_signature, module_name))
         row = cursor.fetchone()
@@ -596,7 +595,7 @@ def query_solution(error_signature, module_name="GLOBAL", threshold=0.35):
         # 2. Fallback to GLOBAL match
         if not row:
             cursor.execute("""
-                SELECT * FROM healing_cache 
+                SELECT * FROM healing_cache
                 WHERE error_signature = ? AND module_name = 'GLOBAL'
             """, (error_signature,))
             row = cursor.fetchone()
@@ -605,7 +604,7 @@ def query_solution(error_signature, module_name="GLOBAL", threshold=0.35):
         # 3. Fuzzy search on symptom/error
         if not row:
             cursor.execute("""
-                SELECT * FROM healing_cache 
+                SELECT * FROM healing_cache
                 WHERE error_signature LIKE ? OR symptom LIKE ?
             """, (f"%{error_signature}%", f"%{error_signature}%"))
             row = cursor.fetchone()
@@ -639,8 +638,8 @@ def query_solution(error_signature, module_name="GLOBAL", threshold=0.35):
 
         if row:
             cursor.execute("""
-                UPDATE healing_cache 
-                SET hit_count = hit_count + 1 
+                UPDATE healing_cache
+                SET hit_count = hit_count + 1
                 WHERE id = ?
             """, (row["id"],))
             conn.commit()
@@ -700,57 +699,53 @@ def sync_db():
     init_db(seed=True, target_db=GLOBAL_DB)
     DB_FILE = resolve_db_path(use_local=True)
     init_db(seed=False, target_db=LOCAL_DB)
-    
-    g_conn = get_db(GLOBAL_DB)
-    l_conn = get_db(LOCAL_DB)
-    
-    # 1. Sync positive cache
-    g_rows = g_conn.execute("SELECT * FROM healing_cache").fetchall()
-    for r in g_rows:
-        l_conn.execute("""
-            INSERT INTO healing_cache (error_signature, module_name, symptom, root_cause, groovy_patch, hit_count)
-            VALUES (?, ?, ?, ?, ?, ?)
-            ON CONFLICT(error_signature, module_name) DO UPDATE SET
-                symptom = excluded.symptom,
-                root_cause = excluded.root_cause,
-                groovy_patch = excluded.groovy_patch
-        """, (r["error_signature"], r["module_name"], r["symptom"], r["root_cause"], r["groovy_patch"], r["hit_count"]))
-    l_conn.commit()
-
-    l_rows = l_conn.execute("SELECT * FROM healing_cache").fetchall()
-    for r in l_rows:
-        g_conn.execute("""
-            INSERT INTO healing_cache (error_signature, module_name, symptom, root_cause, groovy_patch, hit_count)
-            VALUES (?, ?, ?, ?, ?, ?)
-            ON CONFLICT(error_signature, module_name) DO UPDATE SET
-                symptom = excluded.symptom,
-                root_cause = excluded.root_cause,
-                groovy_patch = excluded.groovy_patch
-        """, (r["error_signature"], r["module_name"], r["symptom"], r["root_cause"], r["groovy_patch"], r["hit_count"]))
-    g_conn.commit()
-
-    # 2. Sync negative failed fixes
-    g_failed = g_conn.execute("SELECT * FROM failed_fixes").fetchall()
-    for f in g_failed:
-        l_conn.execute("""
-            INSERT OR IGNORE INTO failed_fixes (error_signature, attempted_patch, failure_reason, agent_role)
-            VALUES (?, ?, ?, ?)
-        """, (f["error_signature"], f["attempted_patch"], f["failure_reason"], f["agent_role"]))
-    l_conn.commit()
-
-    # 3. Sync lessons learned
-    g_lessons = g_conn.execute("SELECT * FROM lessons_learned").fetchall()
-    for r in g_lessons:
-        l_conn.execute("""
-            INSERT OR IGNORE INTO lessons_learned 
-            (page_context, error_signature, root_cause, failed_attempt, successful_fix, lesson_summary, hit_count)
-            VALUES (?, ?, ?, ?, ?, ?, ?)
-        """, (r["page_context"], r["error_signature"], r["root_cause"], r["failed_attempt"], r["successful_fix"], r["lesson_summary"], r["hit_count"]))
-    l_conn.commit()
 
-    l_conn.close()
-    g_conn.close()
-    return len(g_rows)
+    with get_db(GLOBAL_DB) as g_conn, get_db(LOCAL_DB) as l_conn:
+        # 1. Sync positive cache
+        g_rows = g_conn.execute("SELECT * FROM healing_cache").fetchall()
+        for r in g_rows:
+            l_conn.execute("""
+                INSERT INTO healing_cache (error_signature, module_name, symptom, root_cause, groovy_patch, hit_count)
+                VALUES (?, ?, ?, ?, ?, ?)
+                ON CONFLICT(error_signature, module_name) DO UPDATE SET
+                    symptom = excluded.symptom,
+                    root_cause = excluded.root_cause,
+                    groovy_patch = excluded.groovy_patch
+            """, (r["error_signature"], r["module_name"], r["symptom"], r["root_cause"], r["groovy_patch"], r["hit_count"]))
+        l_conn.commit()
+
+        l_rows = l_conn.execute("SELECT * FROM healing_cache").fetchall()
+        for r in l_rows:
+            g_conn.execute("""
+                INSERT INTO healing_cache (error_signature, module_name, symptom, root_cause, groovy_patch, hit_count)
+                VALUES (?, ?, ?, ?, ?, ?)
+                ON CONFLICT(error_signature, module_name) DO UPDATE SET
+                    symptom = excluded.symptom,
+                    root_cause = excluded.root_cause,
+                    groovy_patch = excluded.groovy_patch
+            """, (r["error_signature"], r["module_name"], r["symptom"], r["root_cause"], r["groovy_patch"], r["hit_count"]))
+        g_conn.commit()
+
+        # 2. Sync negative failed fixes
+        g_failed = g_conn.execute("SELECT * FROM failed_fixes").fetchall()
+        for f in g_failed:
+            l_conn.execute("""
+                INSERT OR IGNORE INTO failed_fixes (error_signature, attempted_patch, failure_reason, agent_role)
+                VALUES (?, ?, ?, ?)
+            """, (f["error_signature"], f["attempted_patch"], f["failure_reason"], f["agent_role"]))
+        l_conn.commit()
+
+        # 3. Sync lessons learned
+        g_lessons = g_conn.execute("SELECT * FROM lessons_learned").fetchall()
+        for r in g_lessons:
+            l_conn.execute("""
+                INSERT OR IGNORE INTO lessons_learned
+                (page_context, error_signature, root_cause, failed_attempt, successful_fix, lesson_summary, hit_count)
+                VALUES (?, ?, ?, ?, ?, ?, ?)
+            """, (r["page_context"], r["error_signature"], r["root_cause"], r["failed_attempt"], r["successful_fix"], r["lesson_summary"], r["hit_count"]))
+        l_conn.commit()
+
+        return len(g_rows)
 
 
 @retry_on_locked()
@@ -769,7 +764,7 @@ def record_lesson(page_context, error_signature, root_cause, failed_attempt, suc
     with get_db() as conn:
         cursor = conn.cursor()
         cursor.execute("""
-            INSERT INTO lessons_learned 
+            INSERT INTO lessons_learned
             (page_context, error_signature, root_cause, failed_attempt, successful_fix, lesson_summary)
             VALUES (?, ?, ?, ?, ?, ?)
         """, (page_context, error_signature, root_cause, failed_attempt, successful_fix, lesson_summary))
@@ -847,7 +842,7 @@ def get_flaky_telemetry(days=30, min_runs=2, threshold=0.15, target_db=None):
     with get_db(current_db) as conn:
         cursor = conn.cursor()
         cursor.execute("""
-            SELECT 
+            SELECT
                 test_id,
                 COUNT(*) as total_runs,
                 SUM(CASE WHEN status = 'PASS' THEN 1 ELSE 0 END) as pass_count,
@@ -1051,7 +1046,7 @@ def main():
         if sol:
             print("==================================================")
             if sol.get("groovy_patch"):
-                print(f"✅ [CACHE HIT - 0 TOKENS] Found pre-tested solution!")
+                print("✅ [CACHE HIT - 0 TOKENS] Found pre-tested solution!")
                 print(f"Database Scope  : {'LOCAL' if args.local else 'GLOBAL CENTRAL (~/.agent_memory)'}")
                 print(f"Match Strategy  : {sol.get('match_type', 'EXACT')}")
                 print(f"Error Signature : {sol['error_signature']}")
@@ -1104,12 +1099,12 @@ def main():
         if not lessons:
             print("  (Zero relevant lessons in cache yet. Proceeding with clean reasoning.)")
         else:
-            for idx, l in enumerate(lessons, 1):
-                print(f"📌 [Lesson {idx}] Context: {l['page_context']} | Trigger: {l['error_signature']}")
-                print(f"   💡 Rule: {l['lesson_summary']}")
-                if l.get("failed_attempt") or l.get("successful_fix"):
-                    print(f"   ⚠️ Anti-Pattern: {l.get('failed_attempt') or 'N/A'}")
-                    print(f"   ✅ Proven Fix  : {l.get('successful_fix') or 'N/A'}")
+            for idx, les in enumerate(lessons, 1):
+                print(f"📌 [Lesson {idx}] Context: {les['page_context']} | Trigger: {les['error_signature']}")
+                print(f"   💡 Rule: {les['lesson_summary']}")
+                if les.get("failed_attempt") or les.get("successful_fix"):
+                    print(f"   ⚠️ Anti-Pattern: {les.get('failed_attempt') or 'N/A'}")
+                    print(f"   ✅ Proven Fix  : {les.get('successful_fix') or 'N/A'}")
         print("==================================================")
 
     elif args.command == "record-telemetry":

package/tools/check_env.py

@@ -12,7 +12,6 @@ Autonomously detects Target Project or QA Hub (CLI, CWD, ENV).
 
 import os
 import sys
-import shutil
 import shlex
 import platform
 import subprocess
@@ -101,12 +100,14 @@ class DiagnosticRunner:
             return False, str(e)
 
     def check_os(self):
+        """Verifies operating system platform, kernel version, and architecture."""
         os_name = platform.system()
         os_ver = platform.release()
         arch = platform.machine()
         self.log_check("Operating System", "PASS", f"{os_name} {os_ver} ({arch})")
 
     def check_chrome(self):
+        """Checks for Google Chrome, Chromium, Brave, or Playwright browser runtimes."""
         # 1. Search via 'where' (Windows) or 'which' (Unix)
         cmd = "where chrome" if platform.system() == "Windows" else "which google-chrome google-chrome-stable chromium chromium-browser"
         found, out = self.run_command(cmd)
@@ -149,6 +150,7 @@ class DiagnosticRunner:
                        "Download and install Google Chrome from https://www.google.com/chrome/")
 
     def check_java(self):
+        """Verifies presence of Java JRE/JDK runtime via CLI or JAVA_HOME."""
         found, out = self.run_command("java -version")
         if found or "version" in out:
             ver = out.splitlines()[0] if out else "Installed"
@@ -162,6 +164,7 @@ class DiagnosticRunner:
                                "Katalon includes embedded JRE, but for Gradle/Jenkins CLI, install OpenJDK 17.")
 
     def check_katalon(self):
+        """Verifies Katalon Studio / Katalon Runtime Engine installation if applicable."""
         # Context-aware: check if current target is actually a Katalon project
         is_katalon_project = (
             any(self.target_dir.glob("*.prj"))
@@ -196,6 +199,7 @@ class DiagnosticRunner:
             self.log_check("Katalon Studio IDE", "PASS", "Not installed (Optional - not required for Playwright/Cypress/Pytest)")
 
     def check_node_allure(self):
+        """Verifies presence of Node.js runtime for test runners and Allure reports."""
         found_node, node_ver = self.run_command("node -v")
         if found_node:
             self.log_check("Node.js Runtime", "PASS", f"Node.js {node_ver}")
@@ -204,6 +208,7 @@ class DiagnosticRunner:
                            "Install Node.js from https://nodejs.org/ to execute './tools/generate_allure_report.sh serve'")
 
     def check_python_runner(self):
+        """Verifies active Python environment and optional virtual environment presence."""
         py_ver = sys.version.split()[0]
         venv_path = self.target_dir / ".venv"
 
@@ -213,6 +218,7 @@ class DiagnosticRunner:
             self.log_check("Python Virtual Environment", "PASS", f"Python {py_ver} (Optional: create .venv if using auxiliary runners)")
 
     def check_project_structure(self):
+        """Audits folder layout and configuration integrity for Hub or Spoke projects."""
         # 1. QA Hub Repository Check
         is_hub = (self.target_dir / "skills_manifest.json").exists() or (self.target_dir / ".agents" / "skills").is_dir()
         if is_hub:
@@ -301,6 +307,7 @@ class DiagnosticRunner:
                        "Run 'agent-qa setup .' to initialize Clean POM / Playwright configuration for this project.")
 
     def check_network(self):
+        """Audits AUT network reachability via BASE_URL configured in environment."""
         env_file = self.target_dir / ".env"
         if env_file.exists():
             try:
@@ -345,6 +352,7 @@ class DiagnosticRunner:
                            "Check internet connection or enable VPN if corporate network required.")
 
     def run_all(self):
+        """Runs the complete diagnostic suite and returns 0 if all prerequisites pass."""
         print(f"\n{BOLD}{'='*70}{RESET}")
         print(f"{BOLD}{CYAN} ENTERPRISE AUTOMATION - ENVIRONMENT & ONBOARDING DIAGNOSTIC{RESET}")
         print(f"{BOLD}{'='*70}{RESET}")

package/tools/check_version_sync.py

@@ -111,6 +111,33 @@ def extract_versions(repo_root: str) -> Dict[str, str]:
             if m:
                 versions["docs/ARCHITECTURE.md"] = m.group(1)
 
+    # 11. README.md
+    readme_path = os.path.join(repo_root, "README.md")
+    if os.path.exists(readme_path):
+        with open(readme_path, "r", encoding="utf-8") as f:
+            content = f.read()
+            m = re.search(r'rev:\s*v([0-9]+\.[0-9]+\.[0-9]+)', content)
+            if m:
+                versions["README.md"] = m.group(1)
+
+    # 12. README.en.md
+    readme_en_path = os.path.join(repo_root, "README.en.md")
+    if os.path.exists(readme_en_path):
+        with open(readme_en_path, "r", encoding="utf-8") as f:
+            content = f.read()
+            m = re.search(r'rev:\s*v([0-9]+\.[0-9]+\.[0-9]+)', content)
+            if m:
+                versions["README.en.md"] = m.group(1)
+
+    # 13. SECURITY.md
+    sec_path = os.path.join(repo_root, "SECURITY.md")
+    if os.path.exists(sec_path):
+        with open(sec_path, "r", encoding="utf-8") as f:
+            content = f.read()
+            m = re.search(r'\|\s*`([0-9]+\.[0-9]+\.x)`\s*\|\s*✅', content)
+            if m:
+                versions["SECURITY.md"] = m.group(1)
+
     return versions
 
 
@@ -127,7 +154,15 @@ def check_sync(repo_root: str, expected_version: Optional[str] = None) -> Tuple[
     if not target_ver:
         target_ver = next(iter(versions.values()))
 
-    mismatches = {path: ver for path, ver in versions.items() if ver != target_ver}
+    target_prefix = ".".join(target_ver.split(".")[:2]) + ".x"
+    mismatches = {}
+    for path, ver in versions.items():
+        if path == "SECURITY.md":
+            if ver != target_prefix:
+                mismatches[path] = ver
+        elif ver != target_ver:
+            mismatches[path] = ver
+
     if mismatches:
         return False, versions, target_ver
     return True, versions, target_ver
@@ -151,10 +186,12 @@ def main() -> int:
     print(f"Target Version: v{canonical}")
     print("----------------------------------------------------------------------")
 
+    target_prefix = ".".join(canonical.split(".")[:2]) + ".x"
     all_matched = True
     for file_path, ver in sorted(versions.items()):
-        status = "[MATCH]" if ver == canonical else "[MISMATCH]"
-        if ver != canonical:
+        is_match = (ver == target_prefix) if file_path == "SECURITY.md" else (ver == canonical)
+        status = "[MATCH]" if is_match else "[MISMATCH]"
+        if not is_match:
             all_matched = False
         print(f"  {status:<11} {file_path:<26} -> {ver}")