synapse-hub 2.6.0 → 2.7.0

package/tools/test_memory_os.py

@@ -0,0 +1,409 @@
+#!/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)
+
+"""
+Hierarchical QA Test Memory OS (Letta / MemGPT Pattern)
+-------------------------------------------------------
+Provides a 3-tier persistent memory operating system for test automation:
+  1. Core Memory: Fast key-value blocks for active environment context (AUT URL, auth token expiry, flags).
+  2. Recall Memory: Sequential event log of recent test execution steps and subagent actions.
+  3. Archival Memory: Long-term searchable knowledge base of locator mutations and flaky patterns,
+                      version-scoped by AUT release (e.g. v2.1 vs v2.2) to eliminate memory rot.
+  4. Memory Hygiene: Garbage collection and secret scrubbing (zero plaintext tokens/passwords).
+
+Usage:
+  python tools/test_memory_os.py init --db-path .agent_memory/qa_memory.db
+  python tools/test_memory_os.py update-core --block auth_state --data '{"token_expiry": "..."}'
+  python tools/test_memory_os.py archival-insert --key LOCATOR_MUTATION --payload '{"page": "LoginPage", ...}' --aut-version "v2.1"
+  python tools/test_memory_os.py archival-search --query "Login submit button" --aut-version "v2.1" --json
+  python tools/test_memory_os.py gc --scrub-secrets --max-age-days 30
+"""
+
+import os
+import sys
+import re
+import json
+import sqlite3
+import time
+import difflib
+import argparse
+from datetime import datetime, timezone, timedelta
+from typing import Dict, Any, List, Optional, Tuple
+
+# Enforce UTF-8 stdout encoding
+if hasattr(sys.stdout, 'reconfigure'):
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+        sys.stderr.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+
+
+SECRET_PATTERNS = [
+    re.compile(r'["\']?(?:password|passwd|pwd|secret|apiKey|api_key|token|bearer)["\']?\s*[:=]\s*["\']?([^"\'\s,;]{8,})["\']?', re.IGNORECASE),
+    re.compile(r'Bearer\s+([a-zA-Z0-9_\-\.]{15,})', re.IGNORECASE),
+    re.compile(r'-----BEGIN (?:RSA )?PRIVATE KEY-----[\s\S]*?-----END (?:RSA )?PRIVATE KEY-----'),
+]
+
+
+class TestMemoryOS:
+    """3-Tier Hierarchical QA Memory OS."""
+    __test__ = False
+
+    def __init__(self, db_path: Optional[str] = None):
+        if db_path:
+            self.db_path = db_path
+        else:
+            repo_root = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+            self.db_path = os.path.join(repo_root, ".agent_memory", "qa_memory.db")
+
+        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)
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    def _init_db(self):
+        with self._get_connection() as conn:
+            # 1. Core Memory Table
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS core_memory (
+                    block_key TEXT PRIMARY KEY,
+                    data_json TEXT NOT NULL,
+                    updated_at TEXT NOT NULL
+                )
+            """)
+            # 2. Recall Memory Table
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS recall_memory (
+                    id INTEGER PRIMARY KEY AUTOINCREMENT,
+                    session_id TEXT NOT NULL,
+                    event_type TEXT NOT NULL,
+                    actor TEXT NOT NULL,
+                    payload_json TEXT NOT NULL,
+                    timestamp TEXT NOT NULL
+                )
+            """)
+            conn.execute("CREATE INDEX IF NOT EXISTS idx_recall_session ON recall_memory(session_id, timestamp)")
+
+            # 3. Archival Memory Table
+            conn.execute("""
+                CREATE TABLE IF NOT EXISTS archival_memory (
+                    id TEXT PRIMARY KEY,
+                    key TEXT NOT NULL,
+                    aut_version TEXT DEFAULT 'latest',
+                    payload_json TEXT NOT NULL,
+                    tags TEXT DEFAULT '',
+                    text_content TEXT NOT NULL,
+                    created_at TEXT NOT NULL
+                )
+            """)
+            conn.execute("CREATE INDEX IF NOT EXISTS idx_archival_key_ver ON archival_memory(key, aut_version)")
+
+    # ----------------- Tier 1: Core Memory -----------------
+
+    def update_core(self, block_key: str, data: Any) -> Dict[str, Any]:
+        """Updates or inserts a core memory block."""
+        data_str = json.dumps(data) if not isinstance(data, str) else data
+        now = datetime.now(timezone.utc).isoformat()
+        with self._get_connection() as conn:
+            conn.execute("""
+                INSERT INTO core_memory (block_key, data_json, updated_at)
+                VALUES (?, ?, ?)
+                ON CONFLICT(block_key) DO UPDATE SET
+                    data_json=excluded.data_json,
+                    updated_at=excluded.updated_at
+            """, (block_key, data_str, now))
+
+        return {
+            "status": "PASS",
+            "block_key": block_key,
+            "updated_at": now
+        }
+
+    def get_core(self, block_key: str) -> Optional[Dict[str, Any]]:
+        """Retrieves a core memory block."""
+        with self._get_connection() as conn:
+            row = conn.execute("SELECT data_json, updated_at FROM core_memory WHERE block_key = ?", (block_key,)).fetchone()
+            if row:
+                try:
+                    parsed = json.loads(row["data_json"])
+                except Exception:
+                    parsed = row["data_json"]
+                return {
+                    "block_key": block_key,
+                    "data": parsed,
+                    "updated_at": row["updated_at"]
+                }
+        return None
+
+    def list_core(self) -> List[Dict[str, Any]]:
+        """Lists all core memory blocks."""
+        with self._get_connection() as conn:
+            rows = conn.execute("SELECT block_key, data_json, updated_at FROM core_memory ORDER BY block_key").fetchall()
+            results = []
+            for r in rows:
+                try:
+                    parsed = json.loads(r["data_json"])
+                except Exception:
+                    parsed = r["data_json"]
+                results.append({"block_key": r["block_key"], "data": parsed, "updated_at": r["updated_at"]})
+            return results
+
+    # ----------------- Tier 2: Recall Memory -----------------
+
+    def recall_insert(self, session_id: str, event_type: str, actor: str, payload: Any) -> int:
+        """Inserts an event into recall memory log."""
+        payload_str = json.dumps(payload) if not isinstance(payload, str) else payload
+        now = datetime.now(timezone.utc).isoformat()
+        with self._get_connection() as conn:
+            cursor = conn.execute("""
+                INSERT INTO recall_memory (session_id, event_type, actor, payload_json, timestamp)
+                VALUES (?, ?, ?, ?, ?)
+            """, (session_id, event_type, actor, payload_str, now))
+            return cursor.lastrowid
+
+    def recall_log(self, session_id: str, limit: int = 50) -> List[Dict[str, Any]]:
+        """Retrieves recent sequential steps for a session."""
+        with self._get_connection() as conn:
+            rows = conn.execute("""
+                SELECT id, session_id, event_type, actor, payload_json, timestamp
+                FROM recall_memory
+                WHERE session_id = ?
+                ORDER BY id ASC
+                LIMIT ?
+            """, (session_id, limit)).fetchall()
+            events = []
+            for r in rows:
+                try:
+                    payload = json.loads(r["payload_json"])
+                except Exception:
+                    payload = r["payload_json"]
+                events.append({
+                    "id": r["id"],
+                    "session_id": r["session_id"],
+                    "event_type": r["event_type"],
+                    "actor": r["actor"],
+                    "payload": payload,
+                    "timestamp": r["timestamp"]
+                })
+            return events
+
+    # ----------------- Tier 3: Archival Memory -----------------
+
+    def archival_insert(self, key: str, payload: Any, aut_version: str = "latest", tags: str = "") -> str:
+        """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}"
+
+        # Flatten text content for semantic/fuzzy search
+        text_content = f"{key} {aut_version} {tags} {payload_str}".lower()
+
+        with self._get_connection() as conn:
+            conn.execute("""
+                INSERT INTO archival_memory (id, key, aut_version, payload_json, tags, text_content, created_at)
+                VALUES (?, ?, ?, ?, ?, ?, ?)
+            """, (mem_id, key, aut_version, payload_str, tags, text_content, now))
+
+        return mem_id
+
+    def archival_search(self, query: str, aut_version: Optional[str] = None, top_k: int = 3) -> Dict[str, Any]:
+        """Searches archival memory with semantic token matching and fuzzy ratio."""
+        query_lower = query.lower()
+        tokens = set(re.findall(r'\b[a-z0-9_]{3,}\b', query_lower))
+
+        with self._get_connection() as conn:
+            if aut_version:
+                rows = conn.execute(
+                    "SELECT id, key, aut_version, payload_json, tags, text_content, created_at FROM archival_memory WHERE aut_version = ?",
+                    (aut_version,)
+                ).fetchall()
+            else:
+                rows = conn.execute(
+                    "SELECT id, key, aut_version, payload_json, tags, text_content, created_at FROM archival_memory"
+                ).fetchall()
+
+        scored = []
+        for r in rows:
+            text = r["text_content"]
+            # 1. Token overlap score
+            text_tokens = set(re.findall(r'\b[a-z0-9_]{3,}\b', text))
+            if tokens:
+                token_score = len(tokens.intersection(text_tokens)) / len(tokens)
+            else:
+                token_score = 0.0
+
+            # 2. Fuzzy sequence similarity
+            fuzzy_ratio = difflib.SequenceMatcher(None, query_lower, text[:200]).ratio()
+
+            # Combined score: 60% token overlap + 40% fuzzy match
+            score = round((0.6 * token_score) + (0.4 * fuzzy_ratio), 3)
+
+            if score > 0.15 or (tokens and tokens.intersection(text_tokens)):
+                try:
+                    payload = json.loads(r["payload_json"])
+                except Exception:
+                    payload = r["payload_json"]
+
+                scored.append({
+                    "id": r["id"],
+                    "similarity_score": score,
+                    "key": r["key"],
+                    "aut_version": r["aut_version"],
+                    "timestamp": r["created_at"],
+                    "payload": payload
+                })
+
+        scored.sort(key=lambda x: x["similarity_score"], reverse=True)
+        results = scored[:top_k]
+
+        return {
+            "status": "PASS",
+            "query": query,
+            "aut_version": aut_version or "all",
+            "matches_found": len(results),
+            "results": results
+        }
+
+    # ----------------- Hygiene & Secret Scrubbing -----------------
+
+    def scrub_string(self, text: str) -> Tuple[str, int]:
+        """Masks detected secrets in text."""
+        scrubbed = text
+        count = 0
+        for pat in SECRET_PATTERNS:
+            matches = list(pat.finditer(scrubbed))
+            if matches:
+                count += len(matches)
+                for m in matches:
+                    val = m.group(0)
+                    scrubbed = scrubbed.replace(val, "[MASKED_SECRET]")
+        return scrubbed, count
+
+    def gc(self, scrub_secrets: bool = True, max_age_days: int = 30) -> Dict[str, Any]:
+        """Performs garbage collection and secret scrubbing."""
+        scrub_count = 0
+        deleted_recall = 0
+
+        with self._get_connection() as conn:
+            # 1. Clean old recall logs
+            cutoff = (datetime.now(timezone.utc) - timedelta(days=max_age_days)).isoformat()
+            cur = conn.execute("DELETE FROM recall_memory WHERE timestamp < ?", (cutoff,))
+            deleted_recall = cur.rowcount
+
+            # 2. Scrub secrets in core memory
+            if scrub_secrets:
+                rows = conn.execute("SELECT block_key, data_json FROM core_memory").fetchall()
+                for r in rows:
+                    new_val, c = self.scrub_string(r["data_json"])
+                    if c > 0:
+                        scrub_count += c
+                        conn.execute("UPDATE core_memory SET data_json = ? WHERE block_key = ?", (new_val, r["block_key"]))
+
+                # Scrub archival memory
+                a_rows = conn.execute("SELECT id, payload_json, text_content FROM archival_memory").fetchall()
+                for ar in a_rows:
+                    new_p, cp = self.scrub_string(ar["payload_json"])
+                    new_t, ct = self.scrub_string(ar["text_content"])
+                    if cp > 0 or ct > 0:
+                        scrub_count += (cp + ct)
+                        conn.execute("UPDATE archival_memory SET payload_json = ?, text_content = ? WHERE id = ?", (new_p, new_t, ar["id"]))
+
+        # Database file size check
+        db_size_mb = 0.0
+        if os.path.exists(self.db_path):
+            db_size_mb = round(os.path.getsize(self.db_path) / (1024 * 1024), 2)
+
+        return {
+            "status": "PASS",
+            "db_path": self.db_path,
+            "db_size_mb": db_size_mb,
+            "max_size_limit_mb": 50.0,
+            "size_status": "PASS" if db_size_mb <= 50.0 else "WARNING_OVERSIZED",
+            "secrets_scrubbed": scrub_count,
+            "expired_recall_records_deleted": deleted_recall
+        }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Hierarchical QA Test Memory OS (Letta Pattern)")
+    parser.add_argument("--db-path", help="Path to SQLite database file")
+    subparsers = parser.add_subparsers(dest="subcommand", help="Subcommand to execute")
+
+    # init
+    init_parser = subparsers.add_parser("init", help="Initialize memory OS database")
+
+    # update-core
+    uc_parser = subparsers.add_parser("update-core", help="Update core memory block")
+    uc_parser.add_argument("--block", required=True, help="Core memory block key")
+    uc_parser.add_argument("--data", required=True, help="JSON or text payload")
+
+    # get-core
+    gc_parser = subparsers.add_parser("get-core", help="Retrieve core memory block")
+    gc_parser.add_argument("--block", required=True, help="Core memory block key")
+
+    # archival-insert
+    ai_parser = subparsers.add_parser("archival-insert", help="Insert long-term knowledge into Archival Memory")
+    ai_parser.add_argument("--key", required=True, help="Knowledge key (e.g. LOCATOR_MUTATION)")
+    ai_parser.add_argument("--payload", required=True, help="JSON data payload")
+    ai_parser.add_argument("--aut-version", default="latest", help="AUT release version (e.g. v2.1)")
+    ai_parser.add_argument("--tags", default="", help="Comma-separated search tags")
+
+    # archival-search
+    as_parser = subparsers.add_parser("archival-search", help="Search archival memory by query")
+    as_parser.add_argument("--query", required=True, help="Search query string")
+    as_parser.add_argument("--aut-version", help="Filter by AUT release version")
+    as_parser.add_argument("--top-k", type=int, default=3, help="Max results to return")
+    as_parser.add_argument("--json", action="store_true", help="Print JSON output")
+
+    # gc
+    clean_parser = subparsers.add_parser("gc", help="Garbage collection and secret scrubbing")
+    clean_parser.add_argument("--scrub-secrets", action="store_true", default=True, help="Scrub sensitive credentials")
+    clean_parser.add_argument("--max-age-days", type=int, default=30, help="Max age for recall logs")
+
+    args = parser.parse_args()
+    mem = TestMemoryOS(db_path=args.db_path)
+
+    if args.subcommand == "init":
+        print(json.dumps({"status": "PASS", "db_path": mem.db_path, "initialized": True}, indent=2))
+
+    elif args.subcommand == "update-core":
+        try:
+            parsed_data = json.loads(args.data)
+        except Exception:
+            parsed_data = args.data
+        res = mem.update_core(args.block, parsed_data)
+        print(json.dumps(res, indent=2))
+
+    elif args.subcommand == "get-core":
+        res = mem.get_core(args.block)
+        print(json.dumps(res or {"status": "NOT_FOUND", "block": args.block}, indent=2))
+
+    elif args.subcommand == "archival-insert":
+        try:
+            parsed_payload = json.loads(args.payload)
+        except Exception:
+            parsed_payload = args.payload
+        mid = mem.archival_insert(args.key, parsed_payload, aut_version=args.aut_version, tags=args.tags)
+        print(json.dumps({"status": "PASS", "id": mid, "key": args.key, "aut_version": args.aut_version}, indent=2))
+
+    elif args.subcommand == "archival-search":
+        res = mem.archival_search(args.query, aut_version=args.aut_version, top_k=args.top_k)
+        print(json.dumps(res, indent=2))
+
+    elif args.subcommand == "gc":
+        res = mem.gc(scrub_secrets=args.scrub_secrets, max_age_days=args.max_age_days)
+        print(json.dumps(res, indent=2))
+
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

package/tools/tot_exploratory_tester.py

@@ -0,0 +1,240 @@
+#!/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)
+
+"""
+Tree/Graph-of-Thoughts Exploratory Testing Engine (Princeton ToT & ETH GoT Pattern)
+----------------------------------------------------------------------------------
+Expands linear user stories into deliberative non-linear exploration trees:
+  1. Multi-Branch Deliberation: Generates Happy Path, Boundary/Race, and Negative/Chaos branches.
+  2. Risk-Scored Beam Search: Evaluates thought states and prunes low-risk tautological paths.
+  3. Clean POM Synthesis: Produces structured test scenarios ready for Clean POM Page Classes.
+  4. Multi-Hypothesis RCA: Diagnoses test failures across competing failure hypotheses (DOM_TIMEOUT, ASYNC_RACE, DB_LOCK, BACKEND_500).
+
+Usage:
+  python tools/tot_exploratory_tester.py expand-story --story-file docs/stories/US_PAYMENT.md --max-depth 3 --beam-width 3
+  python tools/tot_exploratory_tester.py rca-hypotheses --error-log reports/failed.log
+"""
+
+import os
+import sys
+import re
+import json
+import time
+import argparse
+from typing import Dict, Any, List, Optional, Tuple
+
+# Enforce UTF-8 stdout encoding
+if hasattr(sys.stdout, 'reconfigure'):
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+        sys.stderr.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+
+
+class TotExploratoryTester:
+    """Tree-of-Thoughts Engine for Exploratory QA and Root Cause Analysis."""
+
+    def __init__(self, repo_root: Optional[str] = None):
+        self.repo_root = repo_root or os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+
+    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()]
+        title = lines[0] if lines else "Untitled User Story"
+        if title.startswith("#"):
+            title = title.lstrip("#").strip()
+
+        # Extract keywords
+        keywords = re.findall(r'\b[a-zA-Z]{4,}\b', story_content.lower())
+        is_checkout = any(k in keywords for k in ["cart", "checkout", "pay", "order", "price"])
+        is_auth = any(k in keywords for k in ["login", "auth", "token", "password", "sso"])
+
+        context_domain = "FINANCIAL_CHECKOUT" if is_checkout else ("AUTH_SESSION" if is_auth else "GENERAL_CRUD")
+
+        # 3 Branches:
+        # 1. Happy Path
+        # 2. Boundary / Session Interruption / Race Condition
+        # 3. Negative / Chaos / Backend Fault
+        branches = [
+            {
+                "branch_id": "BRANCH_HAPPY_PATH",
+                "name": "Standard Happy Business Path",
+                "risk_score": 0.25,
+                "thoughts": [
+                    {"step": 1, "thought": "Navigate to initial entity view and ensure clean pre-conditions."},
+                    {"step": 2, "thought": "Populate valid payload attributes and trigger submit action."},
+                    {"step": 3, "thought": "Verify success confirmation modal and assert database record creation."}
+                ]
+            },
+            {
+                "branch_id": "BRANCH_BOUNDARY_RACE",
+                "name": "Boundary, Session Interruption & Concurrency Path",
+                "risk_score": 0.88,
+                "thoughts": [
+                    {"step": 1, "thought": "Simulate session expiration or token invalidation mid-flow."},
+                    {"step": 2, "thought": "Perform rapid double-click on submission action to probe race condition."},
+                    {"step": 3, "thought": "Assert idempotency: strictly 1 transaction created, duplicate blocked gracefully."}
+                ]
+            },
+            {
+                "branch_id": "BRANCH_NEGATIVE_CHAOS",
+                "name": "Negative Error Handling & Chaos Fault Path",
+                "risk_score": 0.72,
+                "thoughts": [
+                    {"step": 1, "thought": "Inject malformed/boundary input payload exceeding maximum character limits."},
+                    {"step": 2, "thought": "Simulate backend 500 error or database connection timeout via route stub."},
+                    {"step": 3, "thought": "Assert user-friendly error toast, zero data corruption, and retry availability."}
+                ]
+            }
+        ]
+
+        # Beam search selection: sort by risk score descending and take beam_width
+        sorted_branches = sorted(branches, key=lambda b: b["risk_score"], reverse=True)
+        selected_branches = sorted_branches[:beam_width]
+
+        return {
+            "status": "PASS",
+            "story_title": title,
+            "domain": context_domain,
+            "max_depth": max_depth,
+            "beam_width": beam_width,
+            "total_branches_explored": len(branches),
+            "highest_risk_branch": selected_branches[0]["branch_id"],
+            "branches": selected_branches,
+            "clean_pom_recommendations": [
+                f"Implement {context_domain}Page extending BasePage",
+                "Encapsulate double-click debounce in clickSubmitSafe()",
+                "Assert boundary toast in verifyErrorMessageDisplayed()"
+            ]
+        }
+
+    def rca_hypotheses(self, error_log: str, hypotheses: Optional[List[str]] = None) -> Dict[str, Any]:
+        """Performs multi-hypothesis Root Cause Analysis on test failures."""
+        if not hypotheses:
+            hypotheses = ["DOM_TIMEOUT", "ASYNC_RACE", "DB_LOCK", "BACKEND_500", "STALE_SELECTOR"]
+
+        log_lower = error_log.lower()
+        scored_hypotheses = []
+
+        for hyp in hypotheses:
+            score = 0.0
+            evidence = []
+
+            if hyp == "DOM_TIMEOUT":
+                if "timed out" in log_lower or "waitfortimeout" in log_lower or "5000ms" in log_lower:
+                    score += 0.85
+                    evidence.append("Found timeout or waiting duration signature in log")
+                if "element is not visible" in log_lower or "tobevisible" in log_lower:
+                    score += 0.10
+                    evidence.append("Element visibility expectation failed")
+
+            elif hyp == "ASYNC_RACE":
+                if "click intercepted" in log_lower or "animation" in log_lower or "detached" in log_lower:
+                    score += 0.90
+                    evidence.append("Overlay or detachment signature points to async race condition")
+                if "networkidle" in log_lower or "pending" in log_lower:
+                    score += 0.15
+                    evidence.append("Pending network requests active during action")
+
+            elif hyp == "DB_LOCK":
+                if "deadlock" in log_lower or "lock" in log_lower or "sql" in log_lower or "unique constraint" in log_lower:
+                    score += 0.88
+                    evidence.append("Database lock or constraint collision detected in trace")
+
+            elif hyp == "BACKEND_500":
+                if re.search(r'\b500\b', log_lower) and not re.search(r'\b500\d+ms\b', log_lower) and ("http" in log_lower or "status" in log_lower or "server error" in log_lower or "internal" in log_lower):
+                    score += 0.95
+                    evidence.append("HTTP 500 status code explicitly logged")
+                elif "internal server error" in log_lower:
+                    score += 0.95
+                    evidence.append("Internal Server Error explicitly logged")
+
+            elif hyp == "STALE_SELECTOR":
+                if "locator" in log_lower or "selector" in log_lower or "xpath" in log_lower:
+                    score += 0.70
+                    evidence.append("Locator or selector syntax mentioned in failure message")
+
+            # Baseline confidence
+            if not evidence:
+                score = 0.10
+                evidence.append("No direct signature found; baseline background likelihood")
+
+            scored_hypotheses.append({
+                "hypothesis": hyp,
+                "confidence_score": round(min(1.0, score), 3),
+                "evidence": evidence
+            })
+
+        scored_hypotheses.sort(key=lambda h: h["confidence_score"], reverse=True)
+        winner = scored_hypotheses[0]
+
+        recommendations = {
+            "DOM_TIMEOUT": "Replace hardcoded delay with page.waitForLoadState('networkidle') or element.waitFor({state: 'visible'})",
+            "ASYNC_RACE": "Use clickSafe() helper with overlay detachment waiting or dispatchEvent('click')",
+            "DB_LOCK": "Randomize entity code prefix via DataGenerator.uniqueCode('AUTO_') and enforce teardown cleanup",
+            "BACKEND_500": "Inspect backend server logs for uncaught 500 NullPointerException or DB connection pool exhaustion",
+            "STALE_SELECTOR": "Run tools/agentless_patcher.py heal-failure to update stale attribute to ARIA role"
+        }
+
+        return {
+            "status": "PASS",
+            "primary_root_cause": winner["hypothesis"],
+            "confidence": winner["confidence_score"],
+            "recommended_fix": recommendations.get(winner["hypothesis"], "Review stacktrace with team"),
+            "ranked_hypotheses": scored_hypotheses
+        }
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Tree-of-Thoughts Exploratory Testing Engine")
+    subparsers = parser.add_subparsers(dest="subcommand", help="Subcommand to execute")
+
+    # expand-story
+    exp_p = subparsers.add_parser("expand-story", help="Expand User Story into Tree of Thoughts")
+    exp_p.add_argument("--story-file", required=True, help="Path to story markdown file or text string")
+    exp_p.add_argument("--max-depth", type=int, default=3, help="Max thought tree depth")
+    exp_p.add_argument("--beam-width", type=int, default=3, help="Beam search width")
+    exp_p.add_argument("--out-graph", help="Optional path to output graph JSON")
+
+    # rca-hypotheses
+    rca_p = subparsers.add_parser("rca-hypotheses", help="Diagnose failure via multi-hypothesis RCA")
+    rca_p.add_argument("--error-log", required=True, help="Path to error log or log string")
+    rca_p.add_argument("--hypotheses", help="Comma-separated hypotheses list")
+
+    args = parser.parse_args()
+    tester = TotExploratoryTester()
+
+    if args.subcommand == "expand-story":
+        content = args.story_file
+        if os.path.exists(args.story_file):
+            with open(args.story_file, "r", encoding="utf-8", errors="replace") as f:
+                content = f.read()
+        res = tester.expand_story(content, max_depth=args.max_depth, beam_width=args.beam_width)
+        if args.out_graph:
+            os.makedirs(os.path.dirname(os.path.abspath(args.out_graph)), exist_ok=True)
+            with open(args.out_graph, "w", encoding="utf-8") as f:
+                json.dump(res, f, indent=2)
+        print(json.dumps(res, indent=2))
+        sys.exit(0)
+
+    elif args.subcommand == "rca-hypotheses":
+        log_content = args.error_log
+        if os.path.exists(args.error_log):
+            with open(args.error_log, "r", encoding="utf-8", errors="replace") as f:
+                log_content = f.read()
+        hyp_list = [h.strip() for h in args.hypotheses.split(",")] if args.hypotheses else None
+        res = tester.rca_hypotheses(error_log=log_content, hypotheses=hyp_list)
+        print(json.dumps(res, indent=2))
+        sys.exit(0)
+
+    else:
+        parser.print_help()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

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.5.0")
+                return data.get("version", "2.7.0")
         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.5.0")
+                return data.get("version", "2.7.0")
         except (OSError, json.JSONDecodeError):
             data = {}
 
-    return "2.5.0"
+    return "2.7.0"
 
 
 def fetch_remote_version():

package/tools/welcome_page.py

@@ -48,7 +48,7 @@ def get_hub_metadata() -> Dict[str, Any]:
     """Retrieves version and catalog count from skills_manifest.json."""
     manifest_path = os.path.join(HUB_ROOT, "skills_manifest.json")
     meta = {
-        "version": "2.6.0",
+        "version": "2.7.0",
         "totalSkills": 42,
         "author": "Thế Vị (@TeeVee998)",
         "repo": "https://github.com/TeeVee998/Synapse-Hub"