synapse-hub 2.4.3 → 2.6.0

package/tools/TOOLS_RUNBOOK.md

@@ -75,7 +75,17 @@
 | **Cross-Platform Token & Cost Auditor (Antigravity / Cursor / Claude)** | `tools/count_tokens.py` | `python tools/count_tokens.py` (or `--platform cursor` / `--platform all --list` / `--file <path>`) |
 | **Standalone Executive HTML Dashboard Generator** | `tools/dashboard_generator.py` | `python tools/dashboard_generator.py` (or `agent-qa dashboard [--open]`) |
 | **Real-Time Incremental Watch Mode Sentinel** | `tools/watch_mode.py` | `python tools/watch_mode.py` (or `agent-qa watch [--once]`) |
+| **Technical Debt & Shortcut Harvester ("debt")** | `tools/debt_harvester.py` | `agent-qa debt [path]` (or `python tools/debt_harvester.py --scan`).<br/>*Autonomous:* Scans `shortcut:` markers across repo, generates tracked markdown ledger. |
+| **6-Pillar Senior Git Diff Reviewer ("review")** | `tools/senior_code_review.py` | `agent-qa review [--staged]` (or `python tools/senior_code_review.py`).<br/>*Autonomous:* Reviews diff across Bugs, Security, Concurrency, Missing Tests, Speed, Bloat. |
 | **Upstream Version Check & 1-Click Self-Update** | `tools/update_sentinel.py` | `python tools/update_sentinel.py --check / --update` (or `agent-qa update` / `npx synapse-hub update`) |
+| **Tier-2 Skill Routing & Collision Guard (Gate 9)** | `tools/skill_collision_guard.py` | `python tools/skill_collision_guard.py` (or `verify_all Gate 9` / `--route "<intent>"`) |
+| **GoEx Reversible Sandbox Teardown Stack** | `tools/reversible_sandbox.py` | `python tools/reversible_sandbox.py run --cmd "<cmd>" --rollback "<cleanup>"` |
+| **Multi-Trial Episodic Reflexion Loop (K=3)** | `tools/auto_heal_reflexion.py` | `python tools/auto_heal_reflexion.py --test-cmd "<cmd>" --max-trials 3` |
+| **Voyager Lifelong Page Class SQLite Vault** | `tools/skill_vault.py` | `python tools/skill_vault.py query "<keyword>"` / `stats` / `store` |
+| **Stanford DSPy Declarative QA Signatures** | `tools/dspy_qa_signatures.py` | `python tools/dspy_qa_signatures.py compile-suite --spec <file>` |
+| **Pocock Grilling Primitive & Requirement Interrogation** | `tools/interview_story.py` | `python tools/interview_story.py analyze <story.md>` / `interactive` |
+| **Mutant-Directed Textual Loss Optimizer (TextGrad)** | `tools/textgrad_mutation_optimizer.py` | `python tools/textgrad_mutation_optimizer.py optimize --test-file <path>` |
+| **Tool Function Calling Benchmark (Gorilla BFCL)** | `tools/synapse_qa_bench.py` | `python tools/synapse_qa_bench.py benchmark --top-k 5` |
 
 ---
 
@@ -308,7 +318,7 @@ agent-qa update
 
 ---
 
-### 16. `tools/omni_transpiler.py`
+### 17. `tools/omni_transpiler.py`
 - **Purpose:** Universal Polyglot AST Engine & Cross-Framework Transpiler. Allows a single QA engineer to parse, inventory, and transpile test automation code across Java (Selenium), TypeScript (Playwright), Python, Groovy (Katalon Clean POM), and Cypress in 0 tokens without network calls or LLM hallucinations.
 - **CLI Syntax:**
   ```bash
@@ -324,7 +334,7 @@ agent-qa update
 
 ---
 
-### 17. `tools/bug_reporter.py`
+### 18. `tools/bug_reporter.py`
 - **Purpose:** Auto-Bug Reporter & Root Cause Analysis (RCA) Ticket Generator. Automatically distinguishes AUT bugs (server 500, JS exceptions) from test maintenance issues, distills stack traces, formats reproduction steps, and exports ready-to-paste Jira markup or GitHub Markdown.
 - **CLI Syntax:**
   ```bash
@@ -333,7 +343,7 @@ agent-qa update
 
 ---
 
-### 18. `tools/network_mock_shield.py`
+### 19. `tools/network_mock_shield.py`
 - **Purpose:** API Network Mocking & Chaos Shield Generator. Generates zero-token route interception code and chaos fault injection (Stripe/VNPAY payment success/fail, 401/403 auth, 500 server crash, network latency) for Playwright, Cypress, and Python.
 - **CLI Syntax:**
   ```bash
@@ -343,7 +353,7 @@ agent-qa update
 
 ---
 
-### 19. `tools/smart_visual_masker.py`
+### 20. `tools/smart_visual_masker.py`
 - **Purpose:** Smart Visual Masker & Anti-Flake Engine. Eliminates 99% of false alarms in visual regression testing by disabling CSS animations, freezing SVG spinners, and masking dynamic timestamps, clocks, and avatars.
 - **CLI Syntax:**
   ```bash
@@ -353,7 +363,7 @@ agent-qa update
 
 ---
 
-### 20. `tools/ci_healing_hook.py`
+### 21. `tools/ci_healing_hook.py`
 - **Purpose:** CI/CD Silent Self-Healing Pipeline Hook. Executes inside GitHub Actions / GitLab CI when a locator fails, applies in-place auto-heal, and generates an automated Pull Request draft with diff and confidence score.
 - **CLI Syntax:**
   ```bash
@@ -362,7 +372,7 @@ agent-qa update
 
 ---
 
-### 21. `tools/export_postman_collection.py`
+### 22. `tools/export_postman_collection.py`
 - **Purpose:** Enterprise OpenAPI/Swagger, HAR & Zero-Input Domain Postman Collection v2.1.0 Exporter (Postman Pinnacle Suite). Generates fully structured Postman collections with dynamic pre-request scripts, SLA latency tests, response code assertions, autonomous token/entity chaining, native **AJV JSON Schema Validation**, companion **Data-Driven Testing (DDT) CSV matrix**, and **Autonomous Zero-Input Domain Synthesis** (`--domain [ecommerce|banking|saas]`).
 - **CLI Syntax:**
   ```bash
@@ -379,7 +389,7 @@ agent-qa update
 
 ---
 
-### 22. `tools/generate_jmx_plan.py`
+### 23. `tools/generate_jmx_plan.py`
 - **Purpose:** Apache JMeter 5.x Performance Test Plan XML (.jmx) Generator (JMeter 360° Pinnacle Suite). Ingests OpenAPI specifications, Postman Collections, or HAR recordings to output production-ready JMeter load, stress, spike, and soak test plans with HTTP Cookie & Cache Managers, CSV Data Set Config, Transaction Controllers, Pareto Traffic Shaping (`--weighted-mix`), Deep Data Correlation (CSRF regex & random dynamic selectors), JSR223 Groovy HMAC payload signers, InfluxDB live APM telemetry, PerfMon server agent monitoring, and Multi-Protocol support (HTTP, JDBC, WebSocket, gRPC, Kafka).
 - **CLI Syntax:**
   ```bash
@@ -404,7 +414,7 @@ agent-qa update
 
 ---
 
-### 23. `tools/jtl_analyzer.py`
+### 24. `tools/jtl_analyzer.py`
 - **Purpose:** Apache JMeter JTL Results Analyzer & CI/CD SLA Quality Gatekeeper. Parses `.jtl` (CSV or XML), computes statistical percentiles ($P_{50}, P_{90}, P_{95}, P_{99}$, Throughput, Error Rate), evaluates user SLA thresholds, supports server telemetry correlation (`--telemetry`), and returns deterministic exit code `0` (Pass) or `1` (Fail) to enforce quality gates in automated pipelines.
 - **CLI Syntax:**
   ```bash
@@ -420,7 +430,7 @@ agent-qa update
 
 ---
 
-### 36. `tools/author_integrity.py` (Author Provenance & Anti-Tamper Integrity Guard)
+### 25. `tools/author_integrity.py` (Author Provenance & Anti-Tamper Integrity Guard)
 - **Purpose:** Cryptographic and textual provenance validator enforcing the mandatory author attribution condition of the MIT License:
   *"The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software."*
   Protects original creator **Thế Vị (@TeeVee998)** against unauthorized author stripping or copyright tampering across `LICENSE`, `package.json`, `README.md`, and `pyproject.toml`.
@@ -438,7 +448,7 @@ agent-qa update
 
 ---
 
-### 37. `tools/md_to_xlsx.py` (Enterprise Markdown-to-Excel Converter)
+### 26. `tools/md_to_xlsx.py` (Enterprise Markdown-to-Excel Converter)
 - **Purpose:** Parses Markdown Test Case tables and converts them into professional, styled Excel workbooks (`.xlsx`) with Navy Blue headers, frozen header panes (`A2`), auto-filters, color-coded badges for Risk Level (High/Med/Low) and Priority (Critical/High/Med/Low), and multi-line wrapping.
 - **CLI Syntax:**
   ```bash
@@ -454,7 +464,7 @@ agent-qa update
 
 ---
 
-### 38. `tools/count_tokens.py` (Cross-Platform Token & Cost Auditor)
+### 27. `tools/count_tokens.py` (Cross-Platform Token & Cost Auditor)
 - **Purpose:** Audits and calculates token usage (Uncached Input, KV Cache Read, and Output/Thinking tokens) and estimated API costs across **Google Antigravity, Cursor Agent, and Claude Code**. Supports turn-by-turn breakdown, per-prompt profiling, multi-client session discovery, and cache hit rate tracking.
 - **Trigger Condition:** On-demand after completing a task, turn, or test run to monitor context efficiency, detect token bloat, or calculate LLM cost across any supported AI client.
 - **CLI Syntax:**
@@ -492,7 +502,7 @@ agent-qa update
 
 ---
 
-### 39. `tools/dashboard_generator.py` (Standalone Executive HTML Dashboard)
+### 28. `tools/dashboard_generator.py` (Standalone Executive HTML Dashboard)
 - **Purpose:** Compiles project health metrics, 9 Quality Gates status, AST repository maps, benchmark results, and skills inventory into a single, dependency-free, modern HTML dashboard (`PROJECT_DASHBOARD.html`).
 - **Trigger Condition:** On-demand when presenting project status to stakeholders, QA leads, or managers, or after completing project analysis/audits.
 - **CLI Syntax:**
@@ -510,7 +520,7 @@ agent-qa update
 
 ---
 
-### 40. `tools/watch_mode.py` (Real-Time Incremental Watch Mode Sentinel)
+### 29. `tools/watch_mode.py` (Real-Time Incremental Watch Mode Sentinel)
 - **Purpose:** Continuously monitors repository files for code changes and triggers near-instant (< 100ms) incremental verification (UTF-8 No BOM, absolute machine paths, AST Meta Infer-style fake-pass checks) with an interactive terminal Heads-Up Display (HUD).
 - **Trigger Condition:** During active test development or refactoring sessions to get immediate feedback without manually running commands.
 - **CLI Syntax:**
@@ -525,3 +535,162 @@ agent-qa update
   # 3. Run incremental scan once on all files and exit (ideal for CI/CD pre-commit hooks)
   agent-qa watch --once
   ```
+
+---
+
+### 30. `tools/debt_harvester.py` (Technical Debt & Shortcut Harvester)
+- **Purpose:** Scans code comments across multiple programming languages (`#`, `//`, `/* */`, `--`, `<!-- -->`) for `shortcut: <limit>, <when to upgrade>` annotations left by lazy senior developers, compiling them into a structured Markdown debt ledger or machine-readable JSON.
+- **Trigger Condition:** On-demand when scanning accumulated technical debt, before major releases, or when user asks "scan debt" / "list shortcuts".
+- **CLI Syntax:**
+  ```bash
+  # 1. Scan codebase for shortcuts and display table
+  agent-qa debt
+  python3 tools/debt_harvester.py --scan
+
+  # 2. Scan specific directory and export to markdown ledger
+  agent-qa debt ./src --output DEBT_LEDGER.md
+
+  # 3. Output machine-readable JSON for CI integration
+  agent-qa debt --json
+  ```
+
+---
+
+### 31. `tools/senior_code_review.py` (6-Pillar Senior Git Diff Reviewer)
+- **Purpose:** Performs senior-level engineering code review on uncommitted Git diffs (or staged changes) across 6 core pillars: Bugs & Logic, Security & Boundaries, Real Concurrency & Scale, Missing Tests, Speed & Perf, and Bloat Elimination.
+- **Trigger Condition:** On-demand before committing, submitting a PR, or when user asks "review diff" / "review code" / "senior review".
+- **CLI Syntax:**
+  ```bash
+  # 1. Review all working tree git diff changes
+  agent-qa review
+  python3 tools/senior_code_review.py
+
+  # 2. Review staged changes only
+  agent-qa review --staged
+  python3 tools/senior_code_review.py --staged
+
+  # 3. Output review report as Markdown or JSON
+  agent-qa review --output-md REVIEW_REPORT.md
+  agent-qa review --json
+  ```
+
+---
+
+### 32. `tools/skill_collision_guard.py` (Tier-2 Skill Routing & Collision Guard — Gate 9)
+- **Purpose:** Enforces deterministic skill dispatch and prevents routing collision across internal Hub skills (`.agents/skills/`) and external plugins based on cosine/Jaccard semantic overlap. Guarantees zero ambiguous triggers and acts as DoD Gate 9.
+- **Trigger Condition:** Executed automatically during `verify_all.py` (Gate 9), pre-commit, or on-demand when auditing skill trigger uniqueness.
+- **CLI Syntax:**
+  ```bash
+  # 1. Audit skill overlap and check for collision
+  python3 tools/skill_collision_guard.py
+
+  # 2. Audit with custom similarity threshold (default: 0.75 critical, 0.50 warning)
+  python3 tools/skill_collision_guard.py --threshold 0.80 --warn-threshold 0.45
+
+  # 3. Output machine-readable JSON for CI integration
+  python3 tools/skill_collision_guard.py --json
+  ```
+
+---
+
+### 33. `tools/reversible_sandbox.py` (GoEx Reversible Teardown Sandbox Stack)
+- **Purpose:** Manages a deterministic LIFO undo execution stack for safe test automation and self-healing. Automatically rolls back filesystem mutations, database fixture insertions, and environment changes if a test or patch crashes.
+- **Trigger Condition:** When dispatching destructive mutations, exploratory self-healing patches, or running isolated trial runs.
+- **CLI Syntax:**
+  ```bash
+  # 1. Check current sandbox undo stack status
+  python3 tools/reversible_sandbox.py --status
+
+  # 2. Run reversible stack verification demo
+  python3 tools/reversible_sandbox.py --demo
+  ```
+
+---
+
+### 34. `tools/auto_heal_reflexion.py` (Multi-Trial Episodic Reflexion Loop — K=3)
+- **Purpose:** Implements the Noah Shinn Episodic Reflexion loop for failed automated tests. Performs up to $K=3$ iterative trial-feedback cycles, updating episodic memory and self-correcting locators/code without polluting git history.
+- **Trigger Condition:** When headless test suites fail in runner, or single-pass self-healing fails to resolve complex selector or timing issues.
+- **CLI Syntax:**
+  ```bash
+  # 1. Run multi-trial reflexion self-healing on failing test
+  python3 tools/auto_heal_reflexion.py --test "TC_Checkout_01" --error "ElementClickInterceptedException"
+
+  # 2. Configure custom max trials (default: 3)
+  python3 tools/auto_heal_reflexion.py --test "TC_Login_02" --error "TimeoutException" --max-trials 5
+  ```
+
+---
+
+### 35. `tools/skill_vault.py` (Voyager Lifelong Page Class SQLite Vault)
+- **Purpose:** Persists, indexes, and retrieves verified Clean POM Page Class methods, custom locators, and resilient interaction primitives in a permanent SQLite repository (`~/.agent_memory/skill_vault.db`). Prevents re-inventing known solutions across sessions.
+- **Trigger Condition:** When authoring new Page Classes, searching for proven element interactions, or archiving new successful POM patterns.
+- **CLI Syntax:**
+  ```bash
+  # 1. Query verified Page Class primitives by keyword
+  python3 tools/skill_vault.py --query "table_pagination"
+
+  # 2. List all indexed primitives in the lifelong vault
+  python3 tools/skill_vault.py --list
+
+  # 3. Seed initial baseline POM primitives
+  python3 tools/skill_vault.py --seed-samples
+  ```
+
+---
+
+### 36. `tools/dspy_qa_signatures.py` (Stanford DSPy Declarative QA Signature Engine)
+- **Purpose:** Transforms prompt-based test generation into typed, declarative signatures (`StoryToUniversalIR`, `HealBrokenLocator`, `MutantAssertionSignature`) with formal input/output contracts, eliminating brittle prompt hacking.
+- **Trigger Condition:** When compiling user stories into Universal IR, generating defensive assertions, or verifying agent signature compatibility.
+- **CLI Syntax:**
+  ```bash
+  # 1. Check DSPy engine status and signature registrations
+  python3 tools/dspy_qa_signatures.py --check
+
+  # 2. Run declarative compilation demonstration
+  python3 tools/dspy_qa_signatures.py --demo
+  ```
+
+---
+
+### 37. `tools/interview_story.py` (Pocock Grilling Primitive & Requirement Interrogation)
+- **Purpose:** Analyzes rough user stories and acceptance criteria against the Frontier Interrogation Checklist, identifying ambiguities, missing negative boundaries, unstated auth constraints, and race conditions before coding begins.
+- **Trigger Condition:** Triggered autonomously when a user provides an incomplete story or uses `/grill-me` to sharpen requirements.
+- **CLI Syntax:**
+  ```bash
+  # 1. Interrogate user story text directly
+  python3 tools/interview_story.py "As a user I want to checkout cart"
+
+  # 2. Analyze user story file and output JSON questions
+  python3 tools/interview_story.py docs/specs/order_flow.md --json
+  ```
+
+---
+
+### 38. `tools/textgrad_mutation_optimizer.py` (Mutant-Directed Textual Loss Optimizer)
+- **Purpose:** Uses AST micro-mutants as a "textual loss function" to iteratively refine test assertions and Page Class validation methods until mutation score satisfies $\ge 80\%$.
+- **Trigger Condition:** When newly generated tests fail Gate 8 (Mutation Score $< 80\%$), optimizing assertions to catch all logic mutations.
+- **CLI Syntax:**
+  ```bash
+  # 1. Optimize test script assertions against mutants
+  python3 tools/textgrad_mutation_optimizer.py --file tests/test_checkout.py
+
+  # 2. Optimize with custom target score threshold
+  python3 tools/textgrad_mutation_optimizer.py --file tests/test_login.py --target-score 85.0
+
+  # 3. Output results as JSON
+  python3 tools/textgrad_mutation_optimizer.py --file tests/test_checkout.py --json
+  ```
+
+---
+
+### 39. `tools/synapse_qa_bench.py` (Tool Function Calling Benchmark — Gorilla BFCL)
+- **Purpose:** Evaluates AI Agent tool-selection accuracy, argument validation precision, and multi-turn execution efficiency against standardized enterprise QA scenarios.
+- **Trigger Condition:** On-demand when benchmarking agent model upgrades, evaluating tool prompt updates, or running QA engine evaluations.
+- **CLI Syntax:**
+  ```bash
+  # 1. Run QA function-calling benchmark across all test scenarios
+  python3 tools/synapse_qa_bench.py
+
+  # 2. Output detailed benchmark report as JSON
+  python3 tools/synapse_qa_bench.py --json
+  ```

package/tools/__init__.py

@@ -6,7 +6,7 @@ Repository: https://github.com/TeeVee998/Synapse-Hub
 License: MIT
 """
 
-__version__ = "2.4.3"
+__version__ = "2.6.0"
 __author__ = "Thế Vị (@TeeVee998)"
 
 __all__ = [

package/tools/agent_canary.py

@@ -40,8 +40,8 @@ if not os.path.exists(GLOBAL_DB):
     try:
         import cache_resolver
         cache_resolver.init_db(seed=True)
-    except Exception:
-        pass
+    except Exception as e:
+        sys.stderr.write(f"Notice: Cache init skipped: {e}\n")
 REPORTS_DIR = os.path.join(REPO_ROOT, "reports")
 
 # ANSI Color codes
@@ -207,8 +207,8 @@ class DataCollisionVector(MutationVector):
                     conn.close()
                     if row and ("uniqueCode" in row[0] or "currentTimeMillis" in row[0]):
                         healed = True
-                except Exception:
-                    pass
+                except sqlite3.Error:
+                    healed = False
 
             if not healed:
                 hub_skills_path = os.path.join(REPO_ROOT, ".agents", "skills", "clean-pom-crafter", "SKILL.md")

package/tools/analyze_project.py

@@ -217,8 +217,8 @@ def run_full_analysis(target_repo):
         try:
             with open(report_in_root, "w", encoding="utf-8") as f:
                 f.write(md_content)
-        except Exception:
-            pass
+        except OSError as e:
+            sys.stderr.write(f"Notice: Could not write root report copy: {e}\n")
 
     print(f"\n{BOLD}{CYAN}======================================================================{RESET}")
     print(f"{BOLD}{CYAN}                     EXECUTIVE ANALYSIS COMPLETE                      {RESET}")

package/tools/api_fuzzer.py

@@ -161,7 +161,7 @@ class ApiFuzzer:
                         return True
 
         # 1. Exact loopback / special names
-        if host in ("localhost", "127.0.0.1", "::1", "0.0.0.0"):
+        if host in ("localhost", "127.0.0.1", "::1", "0.0.0.0"):  # nosec B104
             return True
 
         # 2. Check IP address (loopback or private RFC 1918, disallowing link-local metadata like 169.254.169.254)
@@ -172,7 +172,7 @@ class ApiFuzzer:
                 return False
             return ip.is_loopback or ip.is_private
         except ValueError:
-            pass
+            ip = None  # host is a domain name, not an IP literal
 
         # 3. Special-use TLDs (RFC 6761 / RFC 2606)
         if any(host.endswith(tld) for tld in (".local", ".localhost", ".internal", ".test")):
@@ -241,7 +241,7 @@ class ApiFuzzer:
 
         if self.spec_path.startswith(("http://", "https://")):
             req = urllib.request.Request(self.spec_path, headers={"User-Agent": "AgentQA-Fuzzer/2.0"})
-            with urllib.request.urlopen(req, context=self.ssl_context, timeout=10.0) as resp:
+            with urllib.request.urlopen(req, context=self.ssl_context, timeout=10.0) as resp:  # nosec B310
                 raw = resp.read().decode("utf-8")
                 return json.loads(raw)
         else:
@@ -452,7 +452,7 @@ class ApiFuzzer:
         duration_ms = 0.0
 
         try:
-            with urllib.request.urlopen(req, context=self.ssl_context, timeout=self.timeout_sec) as resp:
+            with urllib.request.urlopen(req, context=self.ssl_context, timeout=self.timeout_sec) as resp:  # nosec B310
                 status_code = resp.getcode()
                 response_body = resp.read().decode("utf-8", errors="replace")
         except urllib.error.HTTPError as he:

package/tools/auto_heal.py

@@ -30,6 +30,7 @@ import pinpoint_failure
 import cache_resolver
 import project_state
 import heuristic_locator_matcher
+import auto_heal_reflexion
 
 GREEN = "\033[92m"
 RED = "\033[91m"
@@ -52,9 +53,11 @@ def diagnose_and_plan_heal(target_dir, junit_xml_path=None):
     # 1. Pinpoint failure from JUnit XML or logs
     failure_info = None
     if junit_xml_path and os.path.exists(junit_xml_path):
-        failures = pinpoint_failure.parse_junit_xml(junit_xml_path)
+        failures = getattr(pinpoint_failure, "parse_failures", None) or getattr(pinpoint_failure, "parse_junit_xml", None)
         if failures:
-            failure_info = failures[0]
+            res = failures(junit_xml_path)
+            if res:
+                failure_info = res[0]
 
     if not failure_info:
         # Search for any recent report in Reports/
@@ -99,13 +102,20 @@ def diagnose_and_plan_heal(target_dir, junit_xml_path=None):
         "cache_match": bool(cache_solution),
         "heuristic_match": None,
         "recommended_patch": None,
+        "verbal_reflection": None,
         "episodic_lessons": [l["lesson_summary"] for l in lessons]
     }
 
+    # 2b. Reflexion Verbal Diagnosis
+    healer = auto_heal_reflexion.ClosedLoopHealer(max_trials=3)
+    verbal_reflection = healer.generate_reflection(err_sig, "", "")
+    plan["verbal_reflection"] = verbal_reflection
+
     if lessons:
         print(f"  {CYAN}🧠 [EPISODIC REFLEXION] Top Historical Lessons for Context:{RESET}")
         for idx, l in enumerate(lessons, 1):
             print(f"     {idx}. [{l['page_context']}]: {l['lesson_summary']}")
+    print(f"  {CYAN}💡 [REFLEXION DIAGNOSIS] {verbal_reflection}{RESET}")
 
     if cache_solution:
         print(f"  {GREEN}[MATCH] Found cached resolution (Score: {cache_solution['score']:.2f}):{RESET}")
@@ -164,6 +174,8 @@ def main():
     parser.add_argument("--context", default="GLOBAL", help="Page context for the recorded lesson")
     parser.add_argument("--error", default="UnknownError", help="Error signature for the recorded lesson")
     parser.add_argument("--fix", default="", help="Successful fix for the recorded lesson")
+    parser.add_argument("--reflexion", action="store_true", help="Execute multi-trial reflection loop (K=3)")
+    parser.add_argument("--max-trials", type=int, default=3, help="Max trials for reflexion healing loop")
     args = parser.parse_args()
 
     if args.record_lesson:

package/tools/auto_heal_reflexion.py

@@ -0,0 +1,172 @@
+#!/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)
+
+"""
+Multi-Trial Episodic Reflexion Loop for Autonomous Healing (Noah Shinn / Reflexion Pattern)
+------------------------------------------------------------------------------------------
+Replaces single-shot heuristic locator healing with an iterative, multi-trial reflection
+loop (K=3). When a test fails:
+  1. Evaluator extracts failure stacktrace & symptom.
+  2. Reflexion Generator creates a 2-line verbal diagnosis of why the patch/locator failed.
+  3. Memory Buffer accumulates trials across attempts.
+  4. Actor synthesizes the next patch conditioned on previous reflections.
+  5. Upon pass -> records to positive cache (healing_cache & lessons_learned).
+  6. Upon exhaustion of K=3 -> records to negative cache (failed_fixes) to block blind retries.
+
+Reference:
+  - Noah Shinn et al. (Reflexion: Language Agents with Verbal Reinforcement Learning).
+  - Synapse-Hub Subsystem 2: Section 6.3 of agent_skill_training_analysis.md.
+"""
+
+import os
+import sys
+import json
+import argparse
+from dataclasses import dataclass, asdict
+from typing import List, Optional, Callable, Dict, Any, Tuple
+
+# Enforce UTF-8 stdout encoding for Windows console compatibility
+if hasattr(sys.stdout, 'reconfigure'):
+    try:
+        sys.stdout.reconfigure(encoding='utf-8')
+        sys.stderr.reconfigure(encoding='utf-8')
+    except Exception:
+        pass
+
+SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, SCRIPT_DIR)
+
+import cache_resolver
+
+
+@dataclass
+class ReflexionTrial:
+    trial_number: int
+    patch_attempt: str
+    error_feedback: str
+    verbal_reflection: str
+    is_passing: bool
+
+
+class ClosedLoopHealer:
+    """Orchestrates multi-trial reflection loops for self-healing test automation."""
+
+    def __init__(self, max_trials: int = 3):
+        self.max_trials = max_trials
+        self.memory_buffer: List[ReflexionTrial] = []
+
+    def generate_reflection(self, error_sig: str, patch_attempt: str, previous_error: str) -> str:
+        """
+        Synthesizes a structured 2-line verbal reflection explaining why the previous attempt failed
+        and prescribing the strategic adjustment for the next attempt.
+        """
+        err_lower = (previous_error or error_sig).lower()
+        if "staleelement" in err_lower or "stale" in err_lower:
+            return "Reflection: DOM node re-rendered asynchronously after API call. Adjustment: Must wait for loader/backdrop detachment before re-querying element."
+        elif "intercepted" in err_lower or "click" in err_lower:
+            return "Reflection: Click intercepted by fading overlay/spinner animation. Adjustment: Use smart wait for overlay detachment or bypass via safe JS click."
+        elif "timeout" in err_lower or "nosuchelement" in err_lower:
+            return "Reflection: Static selector did not appear within timeout window. Adjustment: Fallback to Accessibility role/label or dynamic data-testid attribute."
+        elif "assert" in err_lower:
+            return "Reflection: Assertion condition violated actual state. Adjustment: Check if state change was asynchronous or if expected data was corrupted."
+        return f"Reflection: Patch attempt failed with '{error_sig[:80]}'. Adjustment: Re-examine live DOM tree and avoid static sleeps."
+
+    def execute_healing_loop(
+        self,
+        failing_test: str,
+        initial_error: str,
+        patch_synthesizer: Callable[[str, str, List[ReflexionTrial]], str],
+        verifier: Callable[[str, str], Tuple[bool, str]],
+        page_context: str = "GLOBAL"
+    ) -> Tuple[bool, Optional[str], List[ReflexionTrial]]:
+        """
+        Executes up to max_trials attempts.
+        Returns (is_success, winning_patch, trial_history).
+        """
+        self.memory_buffer.clear()
+        current_error = initial_error
+
+        print(f"\n🔄 [REFLEXION LOOP] Starting Multi-Trial Self-Healing (Max K={self.max_trials}) for '{failing_test}'...")
+
+        for t in range(1, self.max_trials + 1):
+            prev_attempt = self.memory_buffer[-1].patch_attempt if self.memory_buffer else ""
+            reflection = self.generate_reflection(initial_error, prev_attempt, current_error)
+
+            print(f"\n  --- Trial {t}/{self.max_trials} ---")
+            print(f"  🧠 Verbal Reflection: {reflection}")
+
+            # Synthesize next patch conditioned on reflection memory
+            candidate_patch = patch_synthesizer(failing_test, reflection, self.memory_buffer)
+            print(f"  🔧 Candidate Patch  : {candidate_patch[:100]}...")
+
+            # Verify patch in headless execution
+            is_pass, new_error = verifier(failing_test, candidate_patch)
+
+            trial = ReflexionTrial(
+                trial_number=t,
+                patch_attempt=candidate_patch,
+                error_feedback=new_error if not is_pass else "PASS",
+                verbal_reflection=reflection,
+                is_passing=is_pass
+            )
+            self.memory_buffer.append(trial)
+
+            if is_pass:
+                print(f"  ✅ [TRIAL {t} SUCCESS] Patch verified passing!")
+                self._record_positive_memory(page_context, initial_error, candidate_patch, reflection)
+                return True, candidate_patch, self.memory_buffer
+            else:
+                print(f"  ❌ [TRIAL {t} FAILED] Error: {new_error[:100]}")
+                current_error = new_error
+
+        print(f"\n⚠️  [REFLEXION EXHAUSTED] Failed after {self.max_trials} trials. Persisting to negative memory blacklist.")
+        self._record_negative_memory(initial_error, self.memory_buffer[-1].patch_attempt, f"Failed across {self.max_trials} multi-trial attempts")
+        return False, None, self.memory_buffer
+
+    def _record_positive_memory(self, page_context: str, error_sig: str, patch: str, reflection: str):
+        try:
+            cache_resolver.record_lesson(
+                page_context=page_context,
+                error_signature=error_sig,
+                root_cause=reflection,
+                failed_attempt="Initial failing code",
+                successful_fix=patch,
+                lesson_summary=reflection
+            )
+        except Exception as e:
+            sys.stderr.write(f"Notice: Failed to record positive memory: {e}\n")
+
+    def _record_negative_memory(self, error_sig: str, failed_patch: str, reason: str):
+        try:
+            cache_resolver.record_failed_fix(
+                error_signature=error_sig,
+                patch=failed_patch,
+                reason=reason,
+                agent_role="failure-analyst"
+            )
+        except Exception as e:
+            sys.stderr.write(f"Notice: Failed to record negative memory: {e}\n")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Multi-Trial Episodic Reflexion Self-Healer")
+    parser.add_argument("--test", default="SampleTest", help="Failing test identifier")
+    parser.add_argument("--error", default="ElementClickInterceptedException", help="Initial error signature")
+    parser.add_argument("--max-trials", type=int, default=3, help="Max trials (default: 3)")
+    args = parser.parse_args()
+
+    healer = ClosedLoopHealer(max_trials=args.max_trials)
+    reflection = healer.generate_reflection(args.error, "", "")
+    print(json.dumps({
+        "test": args.test,
+        "error": args.error,
+        "max_trials": args.max_trials,
+        "initial_reflection": reflection
+    }, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())