synapse-hub 2.2.4 → 2.4.0

package/README.md

@@ -1,608 +1,339 @@
-# 🧠 Synapse Hub — Trung Tâm Trí Tuệ & Mạng Lưới Kỹ Năng Cho AI Agent
+# 🧠 Synapse Hub — AI Test Quality Linter & Guardrails for Automated Testing
+### *Bộ Linter & Chốt Chặn Chất Lượng Test Dành Cho Thời Đại AI Viết Code*
 
-[🇻🇳 Tiếng Việt](#-synapse-hub--trung-tâm-trí-tuệ--mạng-lưới-kỹ-năng-cho-ai-agent) | [🇬🇧 English Edition](#-english-edition)
+[🇻🇳 Tiếng Việt](README.md) | [🇬🇧 English Edition](README.en.md)
 
-> **Bộ não trí tuệ dùng chung và mạng lưới kỹ năng tự hành, tăng cường năng lực cho các trợ lý AI (Google Antigravity, Cursor, Windsurf, Claude Code) trên mọi hệ sinh thái kiểm thử tự động.**  
+> **Định vị cốt lõi:** Bộ Linter & Guardrails độc lập (zero external dependencies cho core engine & DoD gates) bảo vệ độ tin cậy của test suite khi AI viết code — Phát hiện & ngăn chặn test "pass ảo" (0 assert, tautology), loại bỏ hoàn toàn sleep cố định, nén 95% log CI/CD, và chuẩn hóa cấu trúc Clean POM. Các tính năng nâng cao (xuất bảng Excel chuẩn doanh nghiệp, so sánh ảnh Canvas) sử dụng thư viện mở rộng tùy chọn (`openpyxl`, `Pillow`).  
+> **Module mở rộng:** Sẵn sàng kết nối 38 kỹ năng QA chuyên sâu, 6 vai trò AI Swarm và 9 Cổng kiểm định DoD hỗ trợ Playwright, Cypress, Pytest và Katalon.  
 > **Tác giả:** Thế Vị ([@TeeVee998](https://github.com/TeeVee998))  
-> **Phiên bản Hub:** `v2.2.4` | **Quy mô:** 28 Kỹ năng chuẩn hóa, 6 Vai trò AI Swarm, 7 Quy tắc cốt lõi, 20+ Công cụ tự động.
-
----
-
-## 🌟 1. Tổng quan & Mục đích Kiến trúc
-
-**Synapse Hub** là tầng trí tuệ đa tác tử tách rời (**Decoupled Shared Intelligence Core**), đóng vai trò như một **"Bộ não dùng chung"**, tách biệt hoàn toàn khỏi mã nguồn của từng dự án cụ thể. Dự án trang bị cho AI agents đội ngũ Sub-Agent QC chuyên biệt (Multi-Agent Swarm), quy trình tự chữa lành (Self-Healing), khả năng thấu hiểu mã nguồn cấp độ AST và các cổng chất lượng nghiêm ngặt (Quality Gates)—cho phép tự động hóa kiểm thử chuẩn xác tuyệt đối trên mọi codebase mà không làm bẩn repository mục tiêu.
-
-```mermaid
-flowchart TD
-    subgraph Hub["🧠 Synapse Hub (Intelligence Core v2.2.4)"]
-        Skills[".agents/skills/ (28 Skills)"]
-        Agents[".agents/agents/ (6 Specialized Roles)"]
-        Rules[".agents/rules/ (7 Core Rules)"]
-        Tools["tools/ (20+ Universal Python Tools)"]
-        Workflows[".agents/workflows/"]
-    end
-
-    subgraph ChatSession["💬 AI Agent Workspace / Chat Session"]
-        Hub -->|Mount/Add Workspace| ChatSession
-    end
-
-    subgraph Projects["📁 Các Dự Án Mục Tiêu (Target Projects)"]
-        ProjectA["Dự án A<br/>(PROJECT_AI_GUIDE.md + Source Code)"]
-        ProjectB["Dự án B<br/>(PROJECT_AI_GUIDE.md + Test Code)"]
-        ProjectC["Dự án C<br/>(PROJECT_AI_GUIDE.md + App Code)"]
-        Other["Dự án khác..."]
-    end
-
-    ProjectA -->|Mount Workspace| ChatSession
-    ProjectB -.->|Mount Workspace| ChatSession
-    ProjectC -.->|Mount Workspace| ChatSession
-    Other -.->|Mount Workspace| ChatSession
-```
-
-### 💎 Lợi Ích Đột Phá Khi Sử Dụng Synapse Hub:
-
-#### 1. 🧠 Khả Năng Suy Nghĩ Có Chiều Sâu (System-2 Reasoning & Cognitive Forcing)
-* **Xóa bỏ chế độ "Autocomplete vô thức":** Khi đối mặt với lỗi kiểm thử hoặc yêu cầu viết test mới, AI không tự tiện sinh code ngẫu nhiên theo trực giác mà bị **ép buộc đi qua quy trình tư duy 4 bước (Cognitive Forcing Pipeline)**:
-  1. *Trích xuất bất biến (Invariants):* Điều gì bắt buộc không bao giờ được phép xảy ra?
-  2. *Giả định phản nghiệm (Popper Falsification):* Đặt ra 3 kịch bản lập trình viên làm hàm chạy sai nhưng test ngây ngô vẫn pass (False Negatives).
-  3. *Tự phản biện (Self-Debate):* Tự chứng minh tại sao assertion chuẩn bị viết sẽ bắt chết cả 3 kịch bản lỗi trên.
-  4. *Sinh code phòng vệ:* Chỉ xuất mã khi đã vượt qua 3 tầng lập luận.
-* **Tự đối kháng Red-Team vs Blue-Team:** Tự động tiêm đột biến AST (`tools/micro_mutator.py`) vào code kiểm thử để kiểm tra xem test suite có thực sự bắt được bug thật hay không. Bắt buộc **Điểm đột biến (Mutation Score) $\ge 80\%$** mới cho phép hoàn thành tác vụ.
-
-#### 2. ⚡ Siêu Tiết Kiệm Token (Cắt Giảm 85% – 95% Chi Phí Context)
-* **Log Distillation (Giảm 95% token log):** Công cụ `tools/distill_log.py` tự động lọc sạch 95% log rác dài lê thê của CLI/Gradle/Playwright, chỉ giữ lại đúng ~10 dòng chứa dòng lỗi và exception (< 50 tokens) thay vì ném 3.000 dòng log làm loãng context.
-* **AST Repo Mapping (Giảm 90% token đọc file):** Công cụ `tools/repo_map.py` nén 500+ method signatures vào đúng một bản đồ tóm tắt < 600 tokens. AI nắm toàn bộ hàm và class mà **không bao giờ phải mở đọc cả file 4.000 dòng** gây nổ context window ("Context Window Blowout").
-* **Compact AOM (Giảm 90% token HTML):** Không bao giờ dump cả trang HTML DOM 50.000 dòng vào prompt; công cụ trích xuất cây Accessibility Object Model (AOM) tương tác dưới 500 tokens.
-* **Zero-Token SQLite Memory Cache:** Ghi nhận và tra cứu kinh nghiệm sửa bug qua cơ sở dữ liệu SQLite ngoại tuyến (`~/.agent_memory/global_cache.db`) bằng thuật toán vector cosine similarity với chi phí **0 token context**.
-* **Chống suy thoái ngữ cảnh ("Context Rot" & "Lost-in-the-Middle"):** Đảm bảo AI luôn duy trì sự minh mẫn, không bao giờ bị ảo giác hay quên logic nghiệp vụ ngay cả trong các phiên làm việc dài trên 100.000 tokens.
-
-#### 3. 📊 So Sánh Hiệu Năng Thực Tế:
-
-| Tiêu chí đánh giá | Cách làm thông thường (Naive AI Prompting) | Khi sử dụng Synapse Hub 🧠 |
-| :--- | :---: | :---: |
-| **Token tiêu thụ / mỗi lần fix lỗi** | 15.000 – 40.000 tokens *(đọc cả file lớn, dump cả log)* | **300 – 800 tokens (Tiết kiệm > 90%)** |
-| **Tỷ lệ Fake-Pass (Test pass ảo, 0 assert)** | 30% – 50% *(AI có xu hướng nuốt lỗi để báo PASS)* | **0% (Chặn đứng bởi Truth Anchor & 9 DoD Gates)** |
-| **Trí nhớ sửa lỗi xuyên phiên (Cross-Session)** | Quên sạch ngay khi mở tab chat mới | **Bền vững qua SQLite Central Cache (0 token)** |
-| **Hiện tượng quên ngữ cảnh (Context Rot)** | Xảy ra nhanh chóng sau 40k – 60k tokens | **Miễn nhiễm nhờ 3 tầng Progressive Disclosure** |
-| **Thời gian tự phục hồi lỗi (MTTR)** | 5 – 15 phút mò mẫm thử nghiệm | **< 1 giây (Tra cứu kinh nghiệm có sẵn)** |
-
-*(Lưu ý: 300–800 token là chi phí ngữ cảnh động của từng lượt sửa lỗi vi mô (micro-turn payload) nhờ repo_map và distill_log; chưa tính chi phí nạp hệ thống/rules ban đầu của IDE ~7.000 tokens).*
-
----
-
-## 🚀 2. Hướng Dẫn Bắt Đầu & Tích Hợp (3 Cách Dùng)
+> **Phiên bản Hub:** `v2.4.0` | **Quy mô:** 38 Kỹ năng chuẩn hóa, 6 Vai trò AI Agent, 51 Lệnh CLI & 60+ Công cụ kiểm thử chuyên sâu, 9 Cổng kiểm định DoD.
 
 [![npm version](https://img.shields.io/npm/v/synapse-hub.svg?style=flat-square&color=blue)](https://www.npmjs.com/package/synapse-hub)
-[![node version](https://img.shields.io/badge/node-%3E%3D16.0.0-brightgreen.svg?style=flat-square)](https://nodejs.org)
+[![node version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg?style=flat-square)](https://nodejs.org)
+[![python version](https://img.shields.io/badge/python-%3E%3D3.10-blue.svg?style=flat-square)](https://python.org)
 [![license](https://img.shields.io/badge/license-MIT-green.svg?style=flat-square)](https://github.com/TeeVee998/Synapse-Hub/blob/main/LICENSE)
+[![Ecosystem](https://img.shields.io/badge/AI%20Ecosystem-Antigravity%20%7C%20Cursor%20%7C%20Claude%20%7C%20Copilot%20%7C%20Windsurf-orange.svg?style=flat-square)](#)
 
 ---
 
-### ⚡ Khởi Động Siêu Tốc: Đúng 1 Lệnh Duy Nhất Với NPX (All-in-One 🚀)
-*Tất cả trong một: **KHÔNG CẦN clone repo Hub**, **KHÔNG CẦN mở Multi-root workspace**, tự động cấu hình dự án **VÀ tự động bơm thẳng vào Antigravity Global Plugin**.*
+### 💡 Synapse Hub là gì? (Hiểu ngay trong 30 giây)
 
-Mở terminal ngay tại thư mục **dự án kiểm thử của bạn** và chạy đúng 1 dòng:
-```bash
-npx synapse-hub setup
-```
-👉 **Đúng 1 lệnh này sẽ tự động hoàn tất toàn bộ trong 5 giây:**
-1. 🧠 **Tự động bơm vào Antigravity Global Plugin:** Triển khai Synapse-Hub vào `~/.gemini/config/plugins/synapse-hub`. Kể từ giây phút này, **mọi dự án** mở trên Google Antigravity đều tự động sở hữu toàn bộ 28 Skills và 6 Subagents mà không cần cấu hình thêm!
-2. 🌐 **Triển Khai Cầu Nối Đa IDE & AI (Universal AI Bridges):** Tự động sinh file cấu hình và quy chuẩn cho mọi trợ lý AI khác nhau ngay trong dự án của bạn:
-   - 🖱️ **Cursor:** `.cursor/rules/synapse-qa.mdc` (Tự động kích hoạt khi mở file trong Cursor)
-   - 🤖 **Claude Code:** `CLAUDE.md` (Hướng dẫn quy chuẩn QA, commands và Clean POM)
-   - 🐙 **GitHub Copilot:** `.github/copilot-instructions.md` (Chỉ dẫn hệ thống cho VS Code / JetBrains Copilot)
-   - 🏄 **Windsurf (Cascade):** `.windsurfrules` (Nguyên tắc kiểm thử bắt buộc)
-   *(Mọi thành viên dù dùng Antigravity, Cursor, Claude Code, Copilot hay Windsurf đều chung 1 chuẩn Clean POM, 1 nguyên tắc Truth Anchor chống pass ảo, và 9 Cổng Kiểm Định DoD (Gate 0–8)!)*
-3. 🔍 **Nhận diện Framework:** Tự động phát hiện Playwright TypeScript/JS, Katalon Studio Groovy, Cypress, hoặc Pytest.
-4. 📋 **Sinh Hướng Dẫn Nghiệp Vụ:** Tạo file `PROJECT_AI_GUIDE.md` ngay trong dự án của bạn để AI hiểu sâu kiến trúc và quy chuẩn code.
-5. 🛡️ **Cài Đặt Cổng Gác Git (Pre-Push Hook):** Tự cài `.git/hooks/pre-push` gọi `npx synapse-hub verify` để chặn đứng mã lỗi và lộ mật khẩu trước khi push.
-6. 💾 **Khởi Tạo Bộ Nhớ Kinh Nghiệm (SQLite Cache):** Khởi tạo và nạp giải pháp sửa lỗi UI vào `~/.agent_memory/global_cache.db` (chi phí 0 token).
-7. 🗺️ **Quét AST & Xuất Bản Đồ Hàm:** Tự động phân tích codebase và trích xuất `repo_map.txt` cô đọng.
-
-Sau đó, bạn có thể thực thi kiểm định bất cứ lúc nào:
-```bash
-# Kiểm định 9 Cổng Chất Lượng (DoD Quality Gates Gate 0–8)
-npx synapse-hub verify
+Bạn có thể sử dụng Synapse Hub theo **2 cách cực kỳ linh hoạt**:
+1. 🛠️ **Dùng như CLI độc lập (Không cần AI):** Bạn chỉ cần gõ `npx synapse-hub lint` để kiểm tra test, nén log CI hoặc xuất kịch bản sang Excel mà không cần cài đặt phức tạp.
+2. 🧠 **Dùng như "Bộ Não Bảo Vệ" cho AI Coding:** Khi bạn dùng Cursor, Google Antigravity hay Claude Code, Synapse Hub đóng vai trò làm cẩm nang hướng dẫn ngầm — ngăn AI sinh ra test "pass ảo", bỏ qua ngoại lệ ngầm hay chèn sleep cố định.
 
-# Đánh giá sức khỏe toàn diện dự án (5-in-1 Project Health Report)
-npx synapse-hub analyze
+> 🛡️ **Yên tâm:** Bạn **không cần học hay ghi nhớ** 38 kỹ năng hay 60 công cụ! Hệ thống hoạt động theo nguyên tắc tự kích hoạt khi cần (*On-Demand*), giúp bạn rảnh tay tập trung vào công việc chính.
 
-# Quét phát hiện mã giả, assertion rỗng (Fake-Pass AST Sentinel)
-npx synapse-hub lint
-```
+#### ⚖️ Trước & Sau khi có Synapse Hub bảo vệ:
+
+| Khi để AI tự viết test (Chưa có Synapse) | Khi có Synapse Hub gác cổng 🛡️ |
+| :--- | :--- |
+| ❌ **Test "pass ảo":** Chạy xanh lè nhưng thực tế có **0 câu lệnh assert**, không kiểm tra gì cả. | ✅ **Phát hiện ngay trong 0.1s:** Báo lỗi test rỗng, yêu cầu bổ sung assertion kiểm tra logic thực tế. |
+| ❌ **Dùng sleep cứng:** Chèn `sleep(5000)` vô tội vạ làm test chậm và thường xuyên tạch trên CI. | ✅ **Ép dùng Smart Wait:** Tự động phát hiện và hướng dẫn thay thế bằng smart wait ổn định 100%. |
+| ❌ **Tràn context AI:** Log CI dài 20.000 dòng làm AI "loạn", tốn token mà không tìm ra lỗi. | ✅ **Nén sạch 95% log thừa:** Cô đọng lại đúng ~30 dòng stacktrace nguyên nhân gốc rễ. |
+| ❌ **Thủng bảo mật:** AI vô tình commit lộ mật khẩu hoặc API token dạng plaintext. | ✅ **Chốt chặn Gate 6:** Quét và chặn đứng các chuỗi nhạy cảm trước khi đẩy lên Git. |
 
 ---
 
-### 🥈 Cách 2: Tối Ưu Cho Antigravity — Cài Đặt 1 Lần Thành "Global Plugin"
-*Cài đặt 1 lần duy nhất: Kể từ đó **BẤT KỲ DỰ ÁN NÀO** mở trên Google Antigravity cũng tự động có sẵn toàn bộ 28 Skills và 6 Subagents mà không cần cấu hình thêm.*
+## ⚡ 1. Trải Nghiệm Nhanh Trong 60 Giây (3 Tính Năng Cốt Lõi 🚀)
 
-#### Bước cài đặt 1-Click:
-```powershell
-# Trên Windows PowerShell:
-./scripts/install_global_plugin.ps1
+Không cần đọc hàng chục tài liệu hay cấu hình phức tạp. Bạn có thể sử dụng ngay 3 tính năng cốt lõi sau để giải quyết trực tiếp nỗi đau kiểm thử hàng ngày:
 
-# Trên macOS / Linux:
-./scripts/install_global_plugin.sh
+### 🔍 1. Phát Hiện Test "Pass Ảo", Sleep Cố Định & Bỏ Qua Lỗi Ngầm
+```bash
+npx synapse-hub lint ./tests
 ```
+* **Vấn đề:** AI viết test thường tạo ra các bài test chạy pass bề ngoài nhưng không kiểm tra gì (0 assert), dùng `Thread.sleep` làm test chậm và flaky, hoặc dùng `try-catch` rỗng bỏ qua ngoại lệ ngầm.
+* **Giải pháp:** Phân tích tĩnh heuristic & AST đa ngôn ngữ (Playwright TypeScript/JavaScript, Pytest Python, Cypress, Groovy/Katalon), phát hiện và báo lỗi ngay lập tức mà không tốn token gọi API LLM.
 
-*(Hoặc nếu chưa clone repo, chỉ cần clone thẳng vào thư mục plugin của Antigravity):*
+### 📊 2. Chuyển Kịch Bản Sang Bảng Excel Doanh Nghiệp Chuẩn 12 Cột
 ```bash
-git clone https://github.com/TeeVee998/Synapse-Hub.git "$HOME/.gemini/config/plugins/synapse-hub"
+npx synapse-hub export-excel
 ```
+* **Vấn đề:** Tester tốn nhiều giờ định dạng bảng tính Excel thủ công từ User Story hoặc kịch bản Markdown.
+* **Giải pháp:** Chuyển đổi tự động kịch bản thành file Excel `.xlsx` chuẩn 12 cột, có sẵn ma trận rủi ro P × I, định dạng màu sắc chuyên nghiệp sẵn sàng gửi cho khách hàng và PM.
 
-**Sau khi cài đặt:**
-- Mở Google Antigravity lên, bạn sẽ thấy `synapse-hub` xuất hiện trong danh mục Plugins toàn cục.
-- Mở bất kỳ thư mục dự án nào, AI Agent cũng tự động nắm bắt toàn bộ năng lực kiểm thử của Synapse-Hub!
-
----
-
-### 🥉 Cách 3: Truyền Thống — Mở Multi-Root Workspace trong IDE
-*Dành cho Core Developers muốn chỉnh sửa, mở rộng hoặc đóng góp phát triển thêm Skills/Tools cho Synapse-Hub.*
-
-1. Mở IDE (Google Antigravity / Cursor / VS Code).
-2. Mở thư mục dự án mục tiêu của bạn (`File -> Open Folder`).
-3. Thêm thư mục `Synapse-Hub` vào Workspace (`File -> Add Folder to Workspace...`).
-4. Chạy script bootstrap môi trường nội bộ:
-```powershell
-# Windows PowerShell
-./scripts/install.ps1
-
-# Linux / macOS
-./scripts/setup.sh
+### 🧹 3. Nén 95% Log CI Thừa — Lấy Đúng Root Cause
+```bash
+npx synapse-hub distill path/to/ci.log
 ```
+* **Vấn đề:** Log build CI/CD dài hàng chục ngàn dòng làm tràn context của AI hoặc khiến kỹ sư mỏi mắt tìm dòng lỗi.
+* **Giải pháp:** Lọc bỏ 95% nhiễu thông tin, cô đọng lại ~30 dòng chứa đúng stacktrace, mã lỗi và kịch bản thất bại.
 
----
-
-## 👥 3. Hệ Thống Multi-Agent Swarm (6 Vai Trò Chuyên Biệt)
-
-Hub phân chia năng lực rõ ràng cho 6 vai trò Agent, mỗi Agent được gán sẵn các Skills và Tools tương ứng:
-
-| Vai Trò Agent | Trách Nhiệm Cốt Lõi | Skills Được Gán | Tools Đi Kèm |
-| :--- | :--- | :--- | :--- |
-| **`orchestrator`** | Trưởng nhóm điều phối, bootstrap dự án, audit sức khỏe, neo state. | `agent-orchestration-multi-agent-optimize`, `graphify-impact-analyzer`, `architecture-decision-records` | `tools/setup_project.py`, `tools/analyze_project.py`, `tools/project_state.py`, `tools/repo_map.py`, `tools/test_impact.py`, `tools/mcp_server.py` |
-| **`live-explorer`** | Thám sát live DOM/AOM qua Playwright, chặn click phá hoại. | `playwright-live-interaction`, `self-healing-locator`, `visual-regression-sentinel`, `auth-session-and-cookie-manager` | `tools/safety_firewall.py`, `tools/lookup_xpath.py`, `tools/visual_diff_canvas.py`, `tools/browser_helpers.js` |
-| **`pom-crafter`** | Kỹ sư Clean POM, kiểm tra API drift, sinh test từ User Story. | `clean-pom-crafter`, `lam-script-generator`, `synthetic-test-data-generator`, `api-spec-to-e2e-matrix`, `file-and-report-validator`, `db-state-verifier-and-seeder` | `tools/generate_tc_from_story.py`, `tools/generate_api_matrix.py`, `tools/api_drift_sentinel.py`, `tools/repo_map.py` |
-| **`test-runner`** | Quản lý chạy test headless CLI, chia tải thời gian chạy trên CI. | `katalon-cli-runner`, `e2e-testing-patterns`, `bats-testing-patterns`, `auth-session-and-cookie-manager`, `flaky-test-sentinel-and-quarantine` | `tools/matrix_sharder.py`, `tools/distill_log.py`, `tools/pinpoint_failure.py`, `tools/flaky_detector.py` |
-| **`failure-analyst`**| Tự động chẩn đoán lỗi, tính điểm tin cậy & tự tạo PR đối soát. | `failure-autopsy-and-healing`, `self-healing-locator`, `file-and-report-validator` | `tools/auto_heal.py`, `tools/heal_pr_automator.py`, `tools/pinpoint_failure.py`, `tools/cache_resolver.py` |
-| **`quality-gatekeeper`**| Gác cổng chất lượng 9 Gates DoD (Gate 0–8), quét Fake-Pass, bơm mutant. | `antigravity-test-sentinel`, `code-refactoring-refactor-clean`, `wcag-audit-patterns`, `web-vitals-and-performance-profiler`, `db-state-verifier-and-seeder`, `security-dast-sentinel`, `skillspector-security-guard` | `tools/verify_all.py`, `tools/infer_linter.py`, `tools/micro_mutator.py`, `tools/trace_data_flow.py`, `tools/wcag_audit.py`, `tools/lint_ai_docs.py`, `tools/skillspector.py` |
+### 💻 Giao Diện Terminal Thực Tế (Bắt Lỗi Trong 0.1s Không Tốn Token):
+```bash
+$ npx synapse-hub lint ./tests
+
+======================================================================
+    ENTERPRISE STATIC DEFECT & FAKE-PASS SENTINEL
+======================================================================
+  Target Scope       : 6 Test Scripts (Polyglot TS/Python/Groovy)
+  Detected Items:
+    - [CRITICAL] tests/checkout.spec.ts:42 - Fake-pass risk: Test contains 0 assertions!
+    - [CRITICAL] tests/login.spec.ts:14 - Hardcoded sleep (5000ms) detected. Replace with dynamic wait.
+======================================================================
+Result: 2 anti-patterns flagged in 0.12s (Zero LLM tokens used).
+```
 
 ---
 
-## 📦 4. Danh Mục 28 Kỹ Năng Chuẩn Hóa (.agents/skills/)
-
-| STT | Tên Kỹ Năng (Skill) | Phạm Vi Hoạt Động Cốt Lõi |
-|:---:|---|---|
-| 1 | `agent-orchestration-multi-agent-optimize` | Tối ưu hóa điều phối multi-agent, phân bổ tải và giám sát chi phí token. |
-| 2 | `antigravity-test-sentinel` | Gác cổng Verification-First, khóa hoàn thành task nếu test chưa pass exit code 0. |
-| 3 | `api-network-mocking-interception` | Chặn bắt, mock lưu lượng HTTP/GraphQL và kiểm thử độ bền mạng (Chaos/Resilience). |
-| 4 | `api-spec-to-e2e-matrix` | Phân tích OpenAPI/Swagger để sinh ma trận kiểm thử tương đương, biên và lỗi. |
-| 5 | `architecture-decision-records` | Soạn thảo và quản lý hồ sơ quyết định kiến trúc kỹ thuật (ADR). |
-| 6 | `auth-session-and-cookie-manager` | Quản lý phiên đăng nhập, JWT tokens, storageState cho đăng nhập 0-giây. |
-| 7 | `backend-load-and-stress-patterns` | Kiểm thử tải và stress backend với k6 & Locust, giám sát ngưỡng SLA P95/P99. |
-| 8 | `bats-testing-patterns` | Kiểm thử tự động Shell Scripts, CI/CD pipelines, mock binary CLI và exit code. |
-| 9 | `clean-pom-crafter` | Chuẩn hóa Clean Page Object Model, Flat Architecture, Dynamic `uniqueCode`. |
-| 10 | `code-refactoring-refactor-clean` | Tái cấu trúc code chuyên sâu, khử code smells, nợ kỹ thuật và chuẩn SOLID. |
-| 11 | `db-state-verifier-and-seeder` | Kiểm tra trạng thái DB trực tiếp (PostgreSQL, MySQL, MongoDB, Redis) và seed fixture. |
-| 12 | `e2e-testing-patterns` | Kiến trúc E2E đa trình duyệt (Playwright/Cypress), Typed POM, sharding song song. |
-| 13 | `failure-autopsy-and-healing` | Khám nghiệm tử thi lỗi cấp vĩ mô từ JUnit XML, Allure report và ảnh chụp lỗi. |
-| 14 | `file-and-report-validator` | Kiểm định nội dung file tải về/tải lên (Excel .xlsx, CSV stream, PDF text/layout). |
-| 15 | `flaky-test-sentinel-and-quarantine` | Phát hiện, chấm điểm và cô lập kiểm thử chập chờn (flaky test) vào vùng cách ly. |
-| 16 | `github-actions-templates` | Mẫu pipeline CI/CD GitHub Actions chuẩn sản xuất và sharded testing. |
-| 17 | `graphify-impact-analyzer` | Phân tích đồ thị tri thức AST Knowledge Graph và khoanh vùng ảnh hưởng thay đổi. |
-| 18 | `katalon-cli-runner` | Điều phối thực thi headless KRE CLI, Community mode và dọn dẹp zombie driver. |
-| 19 | `lam-script-generator` | Large Action Model, chuyển đổi User Story sang 100% test script không token replay. |
-| 20 | `playwright-live-interaction` | Thám sát trực tiếp live DOM/AOM qua Playwright MCP, kiểm tra hit-rate < 200ms. |
-| 21 | `security-dast-sentinel` | Kiểm thử bảo mật động DAST, rà soát OWASP Top 10, HTTP Headers, BOLA/IDOR. |
-| 22 | `self-healing-locator` | Tự phục hồi locator vi mô bằng cây Semantic Accessibility (AOM), Role > Label > TestId. |
-| 23 | `synthetic-test-data-generator` | Tự động sinh dữ liệu kiểm thử biên (BVT), chống SQLi/XSS, đa ngôn ngữ, tọa độ GIS. |
-| 24 | `token-and-context-optimizer` | Tối ưu token, lọc log rác, chống suy thoái ngữ cảnh (Lost-in-the-Middle) và scratchpad đĩa. |
-| 25 | `visual-regression-sentinel` | So sánh giao diện mức pixel và SSIM, hỗ trợ dynamic masking chống flaky test. |
-| 26 | `wcag-audit-patterns` | Kiểm toán tiếp cận web WCAG 2.2 Level A/AA tự động qua AST và `@axe-core`. |
-| 27 | `web-vitals-and-performance-profiler` | Đo lường Core Web Vitals (LCP, CLS, TTFB) và giám sát API endpoint chậm qua CDP. |
-| 28 | `skillspector-security-guard` | Kiểm toán bảo mật AI Agent skills & MCP configs với 71 vector lỗ hổng (Prompt Injection, Data Exfiltration, Privilege Escalation) theo chuẩn NVIDIA SkillSpector. |
+## 🚀 2. Khởi Động Nhanh & Lựa Chọn Cài Đặt (Onboarding Thân Thiện)
 
----
+Synapse Hub tôn trọng sự riêng tư và cấu hình của bạn. Bạn luôn có toàn quyền kiểm soát những gì được ghi vào hệ thống:
 
-## 📜 5. Danh Mục 8 Quy Tắc Cốt Lõi (.agents/rules/)
-
-1. **`context-engineering.md`**: Giao thức lọc log thừa (Observation Masking), khai báo lười (Lazy Loading) và tối ưu hóa KV-Cache.
-2. **`git-push-protocol.md`**: Giao thức Git Push chuẩn hóa cho dự án mục tiêu (Clean SCM by Architecture, loại bỏ hoàn toàn nhu cầu dual-remote/smart-push nhờ tách repo độc lập).
-3. **`graphify.md`**: Điều hướng đồ thị tri thức mã nguồn AST thay vì đọc toàn văn mã nguồn lớn.
-4. **`lessons-learned.md`**: Danh sách bài học kinh nghiệm và anti-patterns (giới hạn cứng < 40 dòng).
-5. **`mandatory-playwright-live.md`**: Quy chuẩn chạy headless Full HD 1920x1080 và khảo sát live DOM trước khi codify.
-6. **`skill-precedence.md`**: Thứ tự ưu tiên kỹ năng cục bộ, chống xung đột trigger với plugin bên ngoài.
-7. **`systematic-debugging.md`**: Kỷ luật điều tra lỗi có căn cứ, cấm đoán mò và verify-first (9 Quality Gates DoD).
-8. **`author-integrity-guard.md`**: Bảo toàn thông báo bản quyền tác giả theo giấy phép MIT và phòng chống đạo văn.
+```bash
+# 🩺 Chẩn đoán môi trường hệ thống chỉ với 1 lệnh (Kiểm tra Node, Python, Chrome, Git):
+npx synapse-hub doctor
 
----
+# 💡 Mẹo: Cài đặt toàn cục để gõ trực tiếp không cần tiền tố npx (nhanh hơn & tiện hơn):
+npm install -g synapse-hub
+synapse-hub doctor
 
-## 🛠️ 6. Sổ Tay 50+ Công Cụ Tự Động Hóa Chuyên Biệt (tools/ & scripts/)
-
-Chi tiết đầy đủ xem tại [tools/TOOLS_RUNBOOK.md](tools/TOOLS_RUNBOOK.md):
-
-- `tools/verify_all.py`: Cổng thẩm định 9 Gates DoD (Gate 0–8: UTF-8, No XPaths, UniqueCode, Clean POM, AST Mutation).
-- `tools/generate_jmx_plan.py`: Sinh kịch bản Apache JMeter 5.x (.jmx) đa giao thức (HTTP, JDBC, WS, gRPC, Kafka) kèm Traffic Shaping Pareto.
-- `tools/jtl_analyzer.py`: Phân tích kết quả JTL, kiểm soát SLA percentiles ($P_{90}, P_{95}, P_{99}$) và làm Quality Gate CI/CD.
-- `tools/telemetry_correlator.py`: Phân tích tương quan Pearson giữa Client Latency và Server APM (CPU, RAM, DB Pool).
-- `tools/export_postman_collection.py`: Xuất Postman Collection v2.1 với AJV JSON Schema, DDT, và Zero-Input synthesis.
-- `tools/newman_analyzer.py`: Phân tích kết quả Newman, triage lỗi assertion và làm Quality Gate cho API.
-- `tools/api_fuzzer.py`: Autonomous API Fuzzer phát hiện lỗi HTTP 500, rò rỉ stacktrace DB và vi phạm SLA độ trễ.
-- `tools/api_drift_sentinel.py`: Bắt breaking change giữa các phiên bản OpenAPI / Swagger specifications.
-- `tools/auto_heal.py`: Tự phục hồi locator gãy dựa trên AOM diffing mà không cần chạy lại toàn bộ test suite.
-- `tools/flaky_detector.py`: Phát hiện kiểm thử chập chờn (Flaky tests) và quản lý vòng đời cách ly Quarantine.
-- `tools/skillspector.py`: Quét kiểm toán an ninh AI Agent Skills & MCP (71 vectors theo chuẩn NVIDIA SkillSpector).
-- `tools/omni_transpiler.py`: Chuyển đổi mã kiểm thử 0-token đa ngôn ngữ (Playwright TS/Python, Java, Groovy, Cypress).
-- `tools/infer_linter.py`: Phân tích tĩnh AST phát hiện fake-pass (0 assertion) và khối try-catch nuốt lỗi.
-- `tools/test_impact.py`: Phân tích git diff và khoanh vùng chính xác test cases bị ảnh hưởng.
-- `tools/cache_resolver.py`: Quản lý bộ nhớ đệm lỗi SQLite trung tâm (`~/.agent_memory/global_cache.db`).
-- `tools/distill_log.py`: Lọc bỏ 95% log thừa từ CLI/Gradle/KRE, giữ lại stacktrace và file pointer.
-- `tools/agent_canary.py`: Hệ thống tiêm 8 vector lỗi tự động đánh giá sức phục hồi của Agent (MTTR).
-- `tools/repo_map.py`: Trích xuất bản đồ cấu trúc hàm và Page Class siêu nén (~500 tokens).
-- `tools/visual_diff_canvas.py`: So sánh pixel/SSIM cho màn hình GIS/Canvas không có DOM.
-- `tools/wcag_audit.py`: Quét kiểm toán tự động các tiêu chí tiếp cận WCAG 2.2 Level A/AA.
-- `tools/generate_api_matrix.py`: Tự động sinh ma trận kiểm thử Positive/Boundary/Negative từ Swagger.
-- `tools/generate_tc_from_story.py`: Large Action Model parser sinh khung Clean POM từ User Story.
-- `tools/trace_data_flow.py`: Kiểm tra luồng dữ liệu kiểm thử, phát hiện rác dữ liệu DB (Orphan Data).
-- `scripts/install.ps1` & `scripts/setup.sh`: Script cài đặt 1-click tự động khởi tạo môi trường Hub.
-- `scripts/lint_skills.ps1`: Linter kiểm tra tính toàn vẹn 28 skills và metadata manifest.
-- `pyproject.toml` & `tools/cli.py`: Đóng gói chuẩn PEP 621 cho lệnh CLI toàn cầu `agent-qa`.
+# 🔹 Cách 1: Cấu hình chỉ trong dự án hiện tại (An toàn nhất, không can thiệp vào ~/.gemini)
+npx synapse-hub setup --local-only
 
----
+# 🔹 Cách 2: Xem trước các thay đổi giả lập (Dry-Run, không ghi đè bất kỳ file nào)
+npx synapse-hub setup --dry-run
 
-## 📚 7. Tài Liệu Kỹ Thuật Mở Rộng & CLI Package (docs/)
+# 🔹 Cách 3: Cài đặt đầy đủ (Tạo PROJECT_AI_GUIDE.md, AI Bridges và Plugin toàn cục)
+npx synapse-hub setup
 
-1. **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**: Kiến trúc Hub/Spoke, mô hình 4 tầng kỹ năng, và ma trận phối hợp 6 Subagent Swarm.
-2. **[docs/CONTRIBUTING.md](docs/CONTRIBUTING.md)**: Quy chuẩn đóng góp, nguyên tắc sáng tạo skill mới và quy trình kiểm định toàn vẹn.
-3. **[docs/CLI_REFERENCE.md](docs/CLI_REFERENCE.md)**: Cẩm nang tra cứu toàn bộ tham số lệnh của công cụ dòng lệnh `agent-qa`.
+# 🔹 Gỡ cài đặt hoàn toàn bất kỳ lúc nào:
+npx synapse-hub uninstall
+```
 
-### Cài đặt nhanh CLI Package:
+### Chạy kiểm định 9 Cổng Chất Lượng (DoD Gates):
 ```bash
-pip install -e .
-agent-qa --help
-agent-qa verify
-agent-qa lint
+npx synapse-hub verify         # Kiểm tra 9 Cổng Chất Lượng DoD (Gate 0–8)
+npx synapse-hub analyze        # Báo cáo sức khỏe dự án (PROJECT_HEALTH_REPORT.md)
 ```
 
----
-
-## 🤝 8. Nguồn Cảm Hứng & Lời Cảm Ơn (Acknowledgments & Inspirations)
-
-Dự án **Synapse Hub** được tổng hợp, kế thừa và phát triển dựa trên tinh thần mã nguồn mở và những ý tưởng đột phá từ các kho lưu trữ xuất sắc của cộng đồng kỹ nghệ phần mềm & AI:
-
-| Dự án & Tác giả | Nguồn cảm hứng & Đóng góp kiến trúc trong Synapse Hub |
-| :--- | :--- |
-| **[muratcankoylan/Agent-Skills-for-Context-Engineering](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)** | Nguyên lý Context Engineering, Observation Masking và kỹ thuật tối ưu hóa sự chú ý của LLM. |
-| **[alexgreensh/token-optimizer](https://github.com/alexgreensh/token-optimizer)** | Cơ chế cô đọng log CLI/Gradle (95% distillation) và tối ưu hóa KV-Cache. |
-| **[obra/superpowers](https://github.com/obra/superpowers)** *(Jesse Vincent)* | Kỷ luật gỡ lỗi dựa trên bằng chứng (Systematic Debugging), Cognitive Forcing và cơ chế Red-Team vs Blue-Team. |
-| **[Aider-AI/aider](https://github.com/Aider-AI/aider)** *(Paul Gauthier)* | Kỹ thuật trích xuất AST bản đồ mã nguồn thu gọn (`tools/repo_map.py`) dưới 600 tokens. |
-| **[lavague-ai/LaVague](https://github.com/lavague-ai/LaVague)** | Mô hình Large Action Model (LAM), tự động biên dịch User Story thành kịch bản kiểm thử Clean POM. |
-| **[facebook/infer](https://github.com/facebook/infer)** *(Meta Infer)* | Linter phân tích tĩnh AST (`tools/infer_linter.py`) phát hiện test giả lập (Fake-Pass) và try-catch nuốt lỗi. |
-| **[microsoft/playwright](https://github.com/microsoft/playwright)** | Tương tác live DOM/AOM sub-200ms, điều hướng headless và mô phỏng network resilience. |
-| **[dequelabs/axe-core](https://github.com/dequelabs/axe-core)** | Quy chuẩn kiểm toán tự động các tiêu chí khả năng tiếp cận WCAG 2.2 Level A/AA. |
-| **[bats-core/bats-core](https://github.com/bats-core/bats-core)** | Chuẩn kiểm thử tự động Bash Automated Testing System cho kịch bản shell/CLI. |
-| **[npryce/adr-tools](https://github.com/npryce/adr-tools)** | Quy chuẩn ghi nhận và lưu vết quyết định kiến trúc phần mềm (ADRs). |
-
----
-
-## 📄 9. Bản Quyền & Điều Khoản Sử Dụng (License & Attribution)
+### 🔄 Tích hợp CI/CD & Pre-commit Hook trong 3 dòng:
+Tự động chặn test pass ảo và code kém chất lượng trước khi merge PR:
 
-Dự án được phân phối chính thức dưới giấy phép **[MIT License](LICENSE)**.
+```yaml
+# Cách 1: Sử dụng GitHub Action chính thức (action.yml)
+- name: Run Synapse Hub Quality Gates
+  uses: TeeVee998/Synapse-Hub@v2
+  with:
+    mode: 'target'
+    format: 'sarif'
 
-**Quyền sở hữu tác giả & Xuất xứ (Provenance):**
-- **Tác giả & Nhà sáng lập:** Thế Vị ([@TeeVee998](https://github.com/TeeVee998))
-- **Mã nguồn gốc:** [https://github.com/TeeVee998/Synapse-Hub](https://github.com/TeeVee998/Synapse-Hub)
-- **Bản quyền:** Copyright © 2026 Thế Vị (@TeeVee998). Phân phối theo giấy phép MIT.
+# Cách 2: Chạy trực tiếp qua NPX (GitLab CI / Bitbucket Pipelines / Jenkins)
+- name: Run Synapse Hub Quality Gates
+  run: npx synapse-hub verify
+```
 
-> ⚖️ **Điều khoản phân phối theo giấy phép MIT:** Bạn được toàn quyền sử dụng, sao chép, sửa đổi, hợp nhất, xuất bản và phân phối mã nguồn này cho bất kỳ mục đích cá nhân hay thương mại nào, **VỚI ĐIỀU KIỆN** thông báo bản quyền gốc ghi nhận tác giả **Thế Vị (@TeeVee998)** cùng điều khoản cấp phép này phải được giữ nguyên vẹn trong toàn bộ bản sao hoặc các phần quan trọng của phần mềm.
+```yaml
+# Tích hợp Pre-commit hook (.pre-commit-config.yaml):
+repos:
+  - repo: https://github.com/TeeVee998/Synapse-Hub
+    rev: v2.4.0
+    hooks:
+      - id: synapse-lint
+      - id: synapse-verify
+```
+*(Cấu hình linh hoạt qua file `synapse.config.json` ở thư mục gốc. Xem hướng dẫn chi tiết tại [docs/CI_CD_INTEGRATION.md](docs/CI_CD_INTEGRATION.md)).*
+
+| Cổng | Tên cổng kiểm soát | Mục tiêu kiểm định thực tế |
+| :---: | :--- | :--- |
+| **Gate 0** | **Bảo Toàn Tác Quyền & MIT** | Xác thực nguồn gốc tác quyền Thế Vị (@TeeVee998) theo MIT License. |
+| **Gate 1** | **Mã Hóa UTF-8 No BOM** | Quét sạch 100% byte BOM và lỗi vỡ ký tự font chữ trên toàn repository. |
+| **Gate 2** | **Đường Dẫn Linh Hoạt (Portability)** | Không gắn cứng đường dẫn máy cá nhân (`/Users/...`, `C:\...`), đảm bảo chạy mượt trên mọi môi trường. |
+| **Gate 3** | **Kiến Trúc Clean POM Phẳng** | Đóng gói 100% locator vào Page Class, cấm raw XPath/CSS trong kịch bản test. |
+| **Gate 4** | **Chống Lệch Tài Liệu AI (Anti-Drift)** | Đối chiếu AST thực tế với `PROJECT_AI_GUIDE.md`, loại bỏ PageClass ảo. |
+| **Gate 5** | **Danh Sách Đen File Tạm** | Chặn rò rỉ file rác (`*.tmp`, memory dump, cache thừa) làm bẩn workspace. |
+| **Gate 6** | **Bảo Vệ Bí Mật & Mật Khẩu** | Quét chặn plaintext password, private keys hoặc API token lưu cứng trong code. |
+| **Gate 7** | **Quét Lỗi Tĩnh & Bắt Test Pass Ảo** | Tự động phát hiện test 0 assertion, try-catch bỏ qua ngoại lệ ngầm, sleep cố định (≥ 3000ms) và unawaited expect. |
+| **Gate 8** | **Đo Độ Nhạy Assert (Micro-Mutation)** | Đảm bảo các câu lệnh assert bắt được lỗi thật khi code bị biến đổi (Yêu cầu điểm ≥ 80%). |
 
 ---
 
-# 🌐 English Edition
+## 🎯 3. Lộ Trình Theo Trình Độ (Tailored For Every Level)
 
-# 🧠 Synapse Hub — AI Agent Intelligence Core & Skill Network
+| Trình độ | Điều bạn cần | Điểm chạm phù hợp trong Synapse Hub |
+| :--- | :--- | :--- |
+| **Fresher / Junior** | Học nhanh, ra việc ngay, hiểu vì sao test yếu | • `npx synapse-hub export-excel`: Tạo test case chuẩn chỉnh.<br/>• `npx synapse-hub lint ./tests`: Giải thích vì sao assert yếu hoặc pass ảo.<br/>• Tham khảo mẫu Clean POM chuẩn trong `examples/practices/`. |
+| **Mid-Level** | Bớt flaky, giảm chi phí bảo trì locator | • `npx synapse-hub flaky scan ./tests`: Dò tìm test chập chờn và phân nhóm cách ly.<br/>• `npx synapse-hub heal`: Gợi ý thay thế locator hỏng qua phân tích cây AOM.<br/>• Tích hợp linter vào pre-commit hook. |
+| **Senior / Lead** | Đo lường, kiểm soát chất lượng, an toàn CI/CD | • `npx synapse-hub verify`: 9 Cổng chất lượng DoD tự động trong CI.<br/>• `npx synapse-hub mutate ./tests`: Kiểm tra độ nhạy của assertion trước khi merge PR.<br/>• Báo cáo chuẩn Markdown/JSON dễ dàng gắn vào GitHub Actions/GitLab CI. |
 
-> **The shared intelligence core and autonomous skill hub empowering AI coding assistants (Google Antigravity / Cursor / Windsurf / Claude Code) across automated testing suites.**  
-> **Author:** Thế Vị ([@TeeVee998](https://github.com/TeeVee998))  
-> **Hub Version:** `v2.2.4` (Semantic Versioning) | **Integrity Index:** 28 Skills, 6 Agent Swarm Roles, 8 Core Rules, 50+ Specialized Python Tools, 9 Quality Gates.
+> *Mẹo tiện dụng: Nếu bạn đã cài đặt toàn cục (`npm i -g synapse-hub`), bạn có thể gõ ngắn gọn `synapse-hub <lệnh>` hoặc các bí danh `synapse`, `agent-qa`.*
 
 ---
 
-## 🌟 1. Overview & Architectural Purpose
-
-**Synapse Hub** serves as a **Decoupled Shared Intelligence Core**, acting as an external neural brain completely isolated from target projects' codebases. It equips AI agents with specialized swarm roles, self-healing execution protocols, AST-level code intelligence, and strict Quality Gates—enabling zero-leakage, truth-anchored test automation across any polyglot codebase without polluting target repositories.
+## 💎 4. Kiến Trúc & Các Trụ Cột Kỹ Thuật
 
 ```mermaid
 flowchart TD
-    subgraph Hub["🧠 Synapse Hub (Intelligence Core v2.2.4)"]
-        Skills[".agents/skills/ (28 Skills)"]
+    subgraph Hub["🧠 Synapse Hub (Core v2.4.0)"]
+        Skills[".agents/skills/ (38 Skills)"]
         Agents[".agents/agents/ (6 Specialized Roles)"]
-        Rules[".agents/rules/ (8 Core Rules)"]
-        Tools["tools/ (50+ Universal Python Tools)"]
-        Workflows[".agents/workflows/"]
+        Rules[".agents/rules/ (11 Core Rules)"]
+        Tools["tools/ (60+ Universal Python Tools)"]
+        Workflows[".agents/workflows/ (10 Workflows)"]
     end
 
-    subgraph ChatSession["💬 AI Agent Workspace / Chat Session"]
-        Hub -->|Mount/Add Workspace| ChatSession
+    subgraph ChatSession["💬 AI Agent Workspace / IDE"]
+        Hub -->|Mount / Plugins| ChatSession
     end
 
-    subgraph Projects["📁 Target Projects"]
-        ProjectA["Project A<br/>(PROJECT_AI_GUIDE.md + Source Code)"]
-        ProjectB["Project B<br/>(PROJECT_AI_GUIDE.md + Test Code)"]
-        ProjectC["Project C<br/>(PROJECT_AI_GUIDE.md + App Code)"]
-        Other["Other Projects..."]
+    subgraph Projects["📁 Dự Án Kiểm Thử Mục Tiêu"]
+        ProjectA["Playwright (TS/JS)"]
+        ProjectB["Pytest (Python)"]
+        ProjectC["Cypress / Katalon"]
     end
 
-    ProjectA -->|Mount Workspace| ChatSession
-    ProjectB -.->|Mount Workspace| ChatSession
-    ProjectC -.->|Mount Workspace| ChatSession
-    Other -.->|Mount Workspace| ChatSession
+    ProjectA -->|Verify & Lint| ChatSession
+    ProjectB -->|Verify & Lint| ChatSession
+    ProjectC -->|Verify & Lint| ChatSession
 ```
 
-### 💎 Breakthrough Architectural Benefits:
-
-#### 1. 🧠 Deep System-2 Reasoning & Cognitive Forcing
-* **Eliminates "Unconscious Autocomplete":** When diagnosing failures or generating tests, the AI agent is strictly barred from speculative guesswork and **forced through a 4-step System-2 reasoning pipeline**:
-  1. *Boundary & Invariant Extraction:* What must never happen under any circumstance?
-  2. *Popper Falsification Hypotheses:* Formulate 3 distinct code mutation scenarios where a naive test passes while the software is broken (False Negatives).
-  3. *Self-Debate:* Formulate concrete proof showing why the prospective assertion will definitively catch all 3 defect vectors.
-  4. *Defensive Code Synthesis:* Emit code only after passing all 3 analytical gates.
-* **Adversarial Red-Team vs. Blue-Team Self-Play:** Automatically injects AST micro-mutants (`tools/micro_mutator.py`) into test suites to verify fault detection power, requiring **Mutation Score $\ge 80\%$** before task approval.
-
-#### 2. ⚡ Radical Token Optimization (85% – 95% Context Cost Reduction)
-* **Log Distillation (95% Token Savings):** `tools/distill_log.py` automatically purges 95% of verbose CLI/Gradle/Playwright stdout, preserving only ~10 lines of root-cause exceptions and pointers (< 50 tokens) instead of dumping 3,000 noise lines.
-* **AST Repo Mapping (90% Code Reading Savings):** `tools/repo_map.py` compresses 500+ method signatures into a clean AST map (< 600 tokens). Agents discover classes and helpers without ever reading 4,000-line source files (preventing "Context Window Blowouts").
-* **Compact AOM (90% HTML Savings):** Replaces raw 50,000-line HTML DOM dumps with compact Accessible Object Model (AOM) subtrees (< 500 tokens).
-* **Zero-Token Episodic SQLite Memory:** Errors and healing patches are recorded and resolved offline in `~/.agent_memory/global_cache.db` via cosine similarity at **0 context tokens**.
-* **Anti-Degradation ("Context Rot" & "Lost-in-the-Middle"):** Preserves model reasoning sharpness and prevents hallucinations even during long sessions exceeding 100,000 tokens.
-
-#### 3. 📊 Quantitative Performance Benchmark:
-
-| Evaluation Metric | Naive AI Coding Prompting | With Synapse Hub 🧠 |
-| :--- | :---: | :---: |
-| **Tokens Consumed per Bug Fix** | 15,000 – 40,000 tokens *(dumps entire classes & logs)* | **300 – 800 tokens (> 90% Savings)** |
-| **Fake-Pass Rate (0 asserts, false passes)** | 30% – 50% *(LLMs tend to relax asserts)* | **0% (Locked by Truth Anchor & 9 DoD Gates)** |
-| **Cross-Session Fix Memory** | 100% forgotten upon new chat session | **Persistent via SQLite Central Cache (0 token)** |
-| **Context Rot / Lost-in-the-Middle** | High degradation after 40k – 60k tokens | **Immune via 3-Tier Progressive Disclosure** |
-| **Mean Time-to-Heal (MTTR)** | 5 – 15 minutes of trial-and-error | **< 1 second (Direct cache resolution)** |
-
-*(Note: 300–800 tokens represents the dynamic micro-turn execution payload achieved via repo_map and distill_log, excluding the one-time IDE system rules prefix overhead of ~7,000 tokens).*
-
----
-
-## 🚀 2. Getting Started & Integration (3 Approaches)
+### 🧠 Trụ cột 1: Chống Pass Ảo & Kiểm Tra Độ Nhạy Assertion (Heuristic)
+- **Static Defect Sentinel (`tools/infer_linter.py`):** Dò tìm các mẫu phản quy chuẩn (anti-patterns) như test thiếu assertion, catch bỏ qua ngoại lệ ngầm, sleep cố định, unawaited Playwright assertions. Đạt độ chính xác cao trên tập benchmark mẫu.
+- **Assertion Sensitivity Sentinel (`tools/micro_mutator.py`):** Tiêm đột biến cú pháp nhẹ (đảo toán tử so sánh, đảo logic boolean) để kiểm tra xem các assertion bên dưới có bắt được lỗi hay không. Bắt buộc độ nhạy assertion ≥ 80% để pass Gate 8.
 
-[![npm version](https://img.shields.io/npm/v/synapse-hub.svg?style=flat-square&color=blue)](https://www.npmjs.com/package/synapse-hub)
-[![node version](https://img.shields.io/badge/node-%3E%3D16.0.0-brightgreen.svg?style=flat-square)](https://nodejs.org)
-[![license](https://img.shields.io/badge/license-MIT-green.svg?style=flat-square)](https://github.com/TeeVee998/Synapse-Hub/blob/main/LICENSE)
+### ⚡ Trụ cột 2: Tối Ưu Hóa Ngữ Cảnh & Tiết Kiệm Token
+- **Lọc Log Thông Minh (`tools/distill_log.py`):** Rút gọn log CI cồng kềnh, đưa đúng thông tin stacktrace vào context của LLM.
+- **AST Method Mapping (`tools/repo_map.py`):** Quét chữ ký hàm và cấu trúc lớp Page Object vào bản đồ nén < 600 tokens; agent không cần đọc toàn bộ mã nguồn lớn.
+- **Bộ Nhớ Lỗi Cục Bộ (`tools/cache_resolver.py`):** Lưu trữ kinh nghiệm sửa lỗi ngoại tuyến vào SQLite tại `~/.agent_memory/global_cache.db` (truy xuất 0 token).
 
 ---
 
-### ⚡ Instant All-in-One Setup: Single NPX Command (Zero-Clone 🚀)
-*All-in-one execution: **NO git cloning**, **NO multi-root workspace setup**, configures the target project **AND automatically injects into Antigravity Global Plugin**.*
-
-Run directly from your **target automation project root**:
-```bash
-npx synapse-hub setup
-```
-👉 **This single command automatically completes everything in 5 seconds:**
-1. 🧠 **Injects Antigravity Global Plugin:** Deploys Synapse-Hub into `~/.gemini/config/plugins/synapse-hub`. From this moment on, **ALL projects** opened in Google Antigravity automatically inherit all 28 Skills and 6 Subagent profiles!
-2. 🌐 **Universal AI Bridges Deployment:** Automatically generates tailored configuration rules for all leading AI IDEs and assistants:
-   - 🖱️ **Cursor:** `.cursor/rules/synapse-qa.mdc`
-   - 🤖 **Claude Code:** `CLAUDE.md`
-   - 🐙 **GitHub Copilot:** `.github/copilot-instructions.md`
-   - 🏄 **Windsurf (Cascade):** `.windsurfrules`
-   *(Empowers team members across Antigravity, Cursor, Claude Code, Copilot, or Windsurf to enforce the exact same Clean POM architecture, Truth Anchor, and 9 Quality Gates DoD (Gate 0–8)!)*
-3. 🔍 **Tech Stack Detection:** Auto-detects Playwright TypeScript/JS, Katalon Groovy, Cypress, or Pytest.
-4. 📋 **Project AI Guide Synthesis:** Generates `PROJECT_AI_GUIDE.md` so AI assistants strictly adhere to project workflows.
-5. 🛡️ **Zero-Leakage Git Pre-Push Hook:** Installs `.git/hooks/pre-push` invoking `npx synapse-hub verify` before any git push.
-6. 💾 **Central Agent Memory Initialization:** Seeds offline SQLite healing memory at `~/.agent_memory/global_cache.db` (0 token cost).
-7. 🗺️ **AST Architecture Mapping:** Scans project methods and exports condensed context map (`repo_map.txt`).
-
-Run verification anytime:
-```bash
-# Run 9 Quality Gates DoD Verification (Gate 0–8)
-npx synapse-hub verify
-
-# Comprehensive 5-in-1 Project Health Audit
-npx synapse-hub analyze
-
-# Static Defect & Fake-Pass Sentinel scan
-npx synapse-hub lint
-```
+## ⚖️ 5. So Sánh Minh Bạch & Giới Hạn Kỹ Thuật Đã Biết (Comparison & Limitations)
+
+### 📊 Bảng so sánh với các công cụ hiện có trong ngành
+
+| Tiêu chí / Giải pháp | ESLint Plugin (Playwright) | Stryker Mutator | Allure Report | Healenium | Synapse Hub 🧠 |
+| :--- | :---: | :---: | :---: | :---: | :---: |
+| **Phạm vi ngôn ngữ** | Chỉ JS / TS | JS / TS, C#, Scala | Mọi ngôn ngữ (nhận XML) | Java / Python / C# (Selenium) | **Đa ngôn ngữ** (TS/JS, Python, Groovy, Java) |
+| **Tích hợp sâu trong Agent Context** | ❌ (Chỉ chạy CLI/IDE) | ❌ (Chạy độc lập) | ❌ (Viewer sau test) | ❌ (Proxy trung gian) | ✅ **NATIVE** (Rule, MCP, Prompt Context, 6 Subagents) |
+| **Diệt Fake-Pass do AI sinh ra** | ⚠️ Hạn chế (chỉ check lint cú pháp) | ❌ Không (chỉ đột biến code app) | ❌ Không | ❌ Không | ✅ **Chuyên biệt** (AST nhận diện 0 assert, try-catch bỏ qua ngoại lệ ngầm, tautology) |
+| **Thời gian chạy Mutation Check** | N/A | ⏱️ Chậm (vài phút đến hàng giờ) | N/A | N/A | ⚡ **Siêu tốc (~0.1s)** với AST Micro-Mutator trước khi commit |
+| **Tự chữa Locator (Self-Healing)** | ❌ | ❌ | ❌ | ⚠️ Cần Server JVM + Docker proxy | ⚡ **Nhẹ (< 500 tokens)** dựa trên AOM Diffing trong luồng Agent |
+| **Tiết kiệm Token & Lọc Log CI** | ❌ | ❌ | ❌ | ❌ | ✅ **Cắt giảm 95%** log thừa (`distill_log.py`, `repo_map.py`) |
+| **Bảo vệ chuẩn kiến trúc Clean POM** | ❌ | ❌ | ❌ | ❌ | ✅ **Bắt buộc Clean POM**, Flat Architecture, cấm selector trong script |
+
+### ⚠️ Giới hạn kỹ thuật đã biết (Known Limitations)
+
+Để duy trì tính minh bạch kỹ thuật (**Truth Anchor**), Synapse Hub công khai các giới hạn thực tế:
+
+1. **Kiểm tra độ nhạy Assert qua AST tĩnh (Không phải Mutation Testing toàn diện runtime):**  
+   Công cụ `tools/micro_mutator.py` sử dụng phương pháp phân tích cú pháp tĩnh siêu nhanh (~0.1s) để kiểm tra xem câu lệnh assert có bắt được lỗi khi mã bị sửa đổi hay không. Nó giúp bạn phát hiện ngay các assert "vô thưởng vô phạt" mà không làm chậm máy, nhưng **không thay thế** các công cụ kiểm thử đột biến cấp runtime biên dịch (như Stryker cho JS/TS hoặc mutmut cho Python). Khi dự án yêu cầu báo cáo Mutation Testing chuẩn công nghiệp cho toàn bộ runtime, hãy sử dụng các công cụ chuyên dụng tương ứng.
+2. **Số Liệu Kiểm Chứng & Benchmark Thực Nghiệm (`benchmarks/qa_eval`):**  
+   Kết quả đo kiểm trên 25 thử thách thực tế đa ngôn ngữ (Groovy, TypeScript, Python, Java) đạt:
+   - **Tỷ lệ giải quyết tự động:** 25 / 25 thử thách (100.0%).
+   - **Chi phí Token trung bình:** 76.2 tokens / bug (tiết kiệm 95% ngữ cảnh so với quét toàn bộ repo).
+   - **Độ nhạy kiểm thử đột biến (Mutation Score):** 100.0% mutant bị bắt hạ.
+   - **Độ chính xác Fake-Pass Sentinel (`infer_linter.py`):** **100.0% Precision** (0 báo động giả), **95.7% Recall**, **97.8% F1-Score** trên 51 mẫu corpus độc lập.
+3. **Phạm Vi Hỗ Trợ Framework & Công Nghệ:**  
+   Hệ thống cung cấp runner và adapter trực tiếp cho **Playwright, Pytest, Katalon Studio/Groovy, và Cypress**. Đối với **Selenium WebDriver**, hệ thống hỗ trợ chuẩn kiến trúc Clean POM, smart-wait patterns và universal IR transpilation; người dùng có thể áp dụng cấu trúc này vào các dự án Selenium hiện có.
+4. **Môi Trường Runtime Khuyến Nghị:**  
+   - Node.js: `>= 18.0.0` (Khuyến nghị Node.js 20 hoặc 22 LTS).
+   - Python: `>= 3.9` (Khuyến nghị Python 3.10+; hỗ trợ đầy đủ Python 3.10, 3.11, 3.12, 3.13).
+5. **Yêu Cầu Môi Trường Headless Browser:**  
+   Các tính năng khảo sát trực tiếp live DOM/AOM và self-healing locator yêu cầu môi trường có cài đặt trình duyệt headless (như Playwright Chromium) để trích xuất cây khả năng truy cập (Accessibility Object Model).
 
 ---
 
-### 🥈 Method 2: Antigravity-Native — Install Once as Global Plugin
-*Install once: From that moment onward, **ANY project** opened in Google Antigravity automatically inherits all 28 Skills and 6 Subagent Swarm profiles.*
-
-#### 1-Click Plugin Installation:
-```powershell
-# On Windows PowerShell:
-./scripts/install_global_plugin.ps1
+## 👥 6. Hệ Thống Multi-Agent Swarm (6 Vai Trò Chuyên Biệt)
 
-# On macOS / Linux:
-./scripts/install_global_plugin.sh
-```
-
-*(Or clone directly into Antigravity's Global Plugins folder):*
-```bash
-git clone https://github.com/TeeVee998/Synapse-Hub.git "$HOME/.gemini/config/plugins/synapse-hub"
-```
-
-**Result:**
-- Google Antigravity registers `synapse-hub` globally.
-- Every workspace session automatically loads the complete QA intelligence core without manual workspace mounts!
-
----
-
-### 🥉 Method 3: Multi-Root Workspace Mounting
-*For Core Developers looking to extend, customize, or contribute new Skills and Tools directly to Synapse-Hub.*
-
-1. Open your AI IDE (Google Antigravity / Cursor / VS Code).
-2. Open your target test project (`File -> Open Folder`).
-3. Add `Synapse-Hub` to your workspace (`File -> Add Folder to Workspace...`).
-4. Run the local environment bootstrap script:
-```powershell
-# Windows PowerShell
-./scripts/install.ps1
-
-# Linux / macOS
-./scripts/setup.sh
-```
-The bootstrap script automatically configures `.venv`, installs dependencies, lints skills, and seeds initial solutions into the Central SQLite Agent Memory (`~/.agent_memory/global_cache.db`).
-
-> 💡 **Initializing SQLite Memory on Clean CI/CD & Docker:**  
-> In fresh CI runners or Docker containers, initialize zero-token memory cache via:
-> ```bash
-> agent-qa heal init
-> # or run directly:
-> python tools/cache_resolver.py init
-> ```
-
----
-
-## 👥 3. Multi-Agent Swarm System (6 Specialized Roles)
-
-Synapse Hub clearly partitions capabilities across 6 specialized AI roles, pre-configured with dedicated skills and tools:
-
-| Agent Role | Core Responsibility | Assigned Skills | Included Tools |
+| Vai Trò Subagent | Trách Nhiệm Cốt Lõi | Kỹ Năng Tiêu Biểu | Công Cụ Đi Kèm |
 | :--- | :--- | :--- | :--- |
-| **`orchestrator`** | Lead coordinator, project bootstrapping, health auditing, state anchoring. | `agent-orchestration-multi-agent-optimize`, `graphify-impact-analyzer`, `architecture-decision-records` | `tools/setup_project.py`, `tools/analyze_project.py`, `tools/project_state.py`, `tools/repo_map.py`, `tools/test_impact.py`, `tools/mcp_server.py` |
-| **`live-explorer`** | Live DOM/AOM probing via Playwright MCP, destructive click firewall. | `playwright-live-interaction`, `self-healing-locator`, `visual-regression-sentinel`, `auth-session-and-cookie-manager` | `tools/safety_firewall.py`, `tools/lookup_xpath.py`, `tools/visual_diff_canvas.py`, `tools/browser_helpers.js` |
-| **`pom-crafter`** | Clean POM engineer, API drift detection, User Story to test generation. | `clean-pom-crafter`, `lam-script-generator`, `synthetic-test-data-generator`, `api-spec-to-e2e-matrix`, `file-and-report-validator`, `db-state-verifier-and-seeder` | `tools/generate_tc_from_story.py`, `tools/generate_api_matrix.py`, `tools/api_drift_sentinel.py`, `tools/repo_map.py` |
-| **`test-runner`** | Headless CLI suite manager, CI parallel sharding and log distillation. | `katalon-cli-runner`, `e2e-testing-patterns`, `bats-testing-patterns`, `auth-session-and-cookie-manager`, `flaky-test-sentinel-and-quarantine` | `tools/matrix_sharder.py`, `tools/distill_log.py`, `tools/pinpoint_failure.py`, `tools/flaky_detector.py` |
-| **`failure-analyst`**| Automated closed-loop failure triage, MTTR scoring, self-healing PR drafting. | `failure-autopsy-and-healing`, `self-healing-locator`, `file-and-report-validator` | `tools/auto_heal.py`, `tools/heal_pr_automator.py`, `tools/pinpoint_failure.py`, `tools/cache_resolver.py` |
-| **`quality-gatekeeper`**| Enforces 9 Quality Gates DoD (Gate 0–8), scans fake passes, runs AST mutation testing. | `antigravity-test-sentinel`, `code-refactoring-refactor-clean`, `wcag-audit-patterns`, `web-vitals-and-performance-profiler`, `db-state-verifier-and-seeder`, `security-dast-sentinel`, `skillspector-security-guard` | `tools/verify_all.py`, `tools/infer_linter.py`, `tools/micro_mutator.py`, `tools/trace_data_flow.py`, `tools/wcag_audit.py`, `tools/lint_ai_docs.py`, `tools/skillspector.py` |
+| **`orchestrator`** | Trưởng nhóm điều phối: khởi tạo dự án, kiểm tra sức khỏe và lưu giữ trạng thái công việc. | `agent-orchestration`, `graphify`, `architecture-decision-records` | `setup_project.py`, `analyze_project.py`, `repo_map.py` |
+| **`live-explorer`** | Khảo sát trực tiếp DOM/AOM qua Playwright headless, tự động ngăn chặn thao tác phá hỏng hoặc nguy hiểm. | `playwright-live-interaction`, `self-healing-locator`, `visual-regression-sentinel` | `safety_firewall.py`, `browser_helpers.js` |
+| **`pom-crafter`** | Kỹ sư Clean POM, kiểm tra breaking change API, sinh test từ User Story. | `clean-pom-crafter`, `lam-script-generator`, `synthetic-test-data-generator` | `generate_tc_from_story.py`, `api_drift_sentinel.py` |
+| **`test-runner`** | Quản lý chạy test headless CLI, chia tải song song CI, lọc log thông minh. | `katalon-cli-runner`, `e2e-testing-patterns`, `flaky-test-sentinel-and-quarantine` | `matrix_sharder.py`, `distill_log.py`, `pinpoint_failure.py` |
+| **`failure-analyst`** | Phân tích nguyên nhân gốc rễ (RCA) khi test thất bại, tự động đề xuất vá locator. | `failure-autopsy-and-healing`, `token-and-context-optimizer` | `auto_heal.py`, `bug_reporter.py`, `cache_resolver.py` |
+| **`quality-gatekeeper`**| Chốt chặn kiểm soát chất lượng, kiểm định 9 Cổng DoD và độ nhạy assertion. | `antigravity-test-sentinel`, `wcag-audit-patterns`, `security-dast-sentinel` | `verify_all.py`, `micro_mutator.py`, `infer_linter.py` |
 
 ---
 
-## 📦 4. Standardized 28 Skills Catalog (.agents/skills/)
+## 📦 7. Danh Mục 38 Kỹ Năng Chuẩn Hóa (.agents/skills/)
 
-| # | Skill Name | Core Operational Scope |
-|:---:|---|---|
-| 1 | `agent-orchestration-multi-agent-optimize` | Multi-agent coordination profiling, workload distribution, and token cost budgeting. |
-| 2 | `antigravity-test-sentinel` | Verification-First sentinel, locking task completion until exit code 0 is proven. |
-| 3 | `api-network-mocking-interception` | HTTP/GraphQL request interception, route stubbing, and chaos network resilience testing. |
-| 4 | `api-spec-to-e2e-matrix` | Transforms OpenAPI/Swagger specifications into equivalence, boundary, and error test matrices. |
-| 5 | `architecture-decision-records` | Documents and maintains technical Architecture Decision Records (ADR). |
-| 6 | `auth-session-and-cookie-manager` | Manages sessions, JWT tokens, and storageState for zero-second authentications. |
-| 7 | `backend-load-and-stress-patterns` | Backend load/stress testing via k6 & Locust with P95/P99 SLA threshold assertions. |
-| 8 | `bats-testing-patterns` | Automated testing for Shell scripts, CI/CD pipelines, CLI mocks, and exit codes. |
-| 9 | `clean-pom-crafter` | Clean Page Object Model standards, Flat Architecture, and dynamic `uniqueCode` test data. |
-| 10 | `code-refactoring-refactor-clean` | Clean code refactoring, code smells elimination, technical debt remediation, and SOLID. |
-| 11 | `db-state-verifier-and-seeder` | Direct DB state assertions (PostgreSQL, MySQL, MongoDB, Redis) and isolated fixtures. |
-| 12 | `e2e-testing-patterns` | Multi-browser E2E testing architecture (Playwright/Cypress), Typed POM, parallel sharding. |
-| 13 | `failure-autopsy-and-healing` | Automated failure triage from JUnit XML, Allure reports, and visual error screenshots. |
-| 14 | `file-and-report-validator` | Verifies uploaded/downloaded files (Excel .xlsx, streaming CSV, PDF text/layout). |
-| 15 | `flaky-test-sentinel-and-quarantine` | Flaky test detection, flakiness index scoring, and quarantine isolation governance. |
-| 16 | `github-actions-templates` | Production-ready GitHub Actions CI/CD workflows and sharded testing matrix. |
-| 17 | `graphify-impact-analyzer` | AST Knowledge Graph navigation and zero-waste test impact analysis. |
-| 18 | `katalon-cli-runner` | Headless KRE CLI execution coordinator, licensing fallback, and zombie driver cleanup. |
-| 19 | `lam-script-generator` | Large Action Model generator compiling User Stories into 100% test scripts with zero replay. |
-| 20 | `playwright-live-interaction` | Real-time DOM/AOM probing via Playwright MCP with sub-200ms selector verification. |
-| 21 | `security-dast-sentinel` | Dynamic Application Security Testing (DAST), OWASP Top 10, Security Headers, BOLA/IDOR. |
-| 22 | `self-healing-locator` | Micro-locator self-healing via Accessibility Tree (AOM), Role > Label > TestId hierarchy. |
-| 23 | `synthetic-test-data-generator` | Robust synthetic boundary test data generation (BVT, anti-injection, multilingual, GIS). |
-| 24 | `token-and-context-optimizer` | Context engineering, 95% log distillation, anti-degradation, and disk scratchpads. |
-| 25 | `visual-regression-sentinel` | Pixel-level and SSIM visual regression testing with dynamic masking. |
-| 26 | `wcag-audit-patterns` | Automated WCAG 2.2 Level A/AA accessibility auditing via AST and `@axe-core`. |
-| 27 | `web-vitals-and-performance-profiler` | Core Web Vitals (LCP, CLS, TTFB) profiling and slow API endpoint detection via CDP. |
-| 28 | `skillspector-security-guard` | AI agent skill & MCP config security auditing against 71 vulnerability vectors (Prompt Injection, Data Exfiltration, Privilege Escalation) powered by NVIDIA SkillSpector spec. |
+<details>
+<summary><b>📦 Bấm để xem: Danh Mục 38 Kỹ Năng Chuẩn Hóa</b></summary>
 
----
-
-## 📜 5. 8 Core Rules Catalog (.agents/rules/)
-
-1. **`context-engineering.md`**: Observation masking, lazy progressive disclosure, and KV-cache optimization.
-2. **`git-push-protocol.md`**: Clean git push protocol (decoupled architecture guarantees zero AI leakage).
-3. **`graphify.md`**: Navigating the AST knowledge graph over reading entire large source files.
-4. **`lessons-learned.md`**: Episodic anti-pattern blacklist (strictly capped under 40 lines).
-5. **`mandatory-playwright-live.md`**: Mandatory headless Full HD 1920x1080 and live DOM probing before codifying.
-6. **`skill-precedence.md`**: Tier-1 local skill precedence resolving external plugin collisions.
-7. **`systematic-debugging.md`**: Evidence-first debugging discipline; zero guessing; 9 Quality Gates DoD.
-8. **`author-integrity-guard.md`**: Mandatory MIT copyright notice preservation and anti-plagiarism guard.
-
----
-
-## 🛠️ 6. Automated Tools Runbook (50+ Specialized Python Tools)
-
-For full details, refer to [tools/TOOLS_RUNBOOK.md](tools/TOOLS_RUNBOOK.md):
-
-- `tools/verify_all.py`: 9 Quality Gates DoD verification (Gate 0–8: UTF-8, No XPaths, UniqueCode, Clean POM, AST Mutation).
-- `tools/generate_jmx_plan.py`: Multi-protocol Apache JMeter 5.x (.jmx) plan generator (HTTP, JDBC, WS, gRPC, Kafka) with Pareto traffic shaping.
-- `tools/jtl_analyzer.py`: JTL execution metrics analyzer, P95/P99 SLA gatekeeper, and CI/CD Quality Gate enforcer.
-- `tools/telemetry_correlator.py`: Full-stack Pearson correlation analyzer between client-side latency and server APM (CPU, RAM, DB Pool).
-- `tools/export_postman_collection.py`: Exports Postman Collections v2.1 with native AJV JSON Schema, DDT CSV, and Zero-Input domain synthesis.
-- `tools/newman_analyzer.py`: Newman automated test results analyzer, assertion failure triage, and CI/CD Quality Gate.
-- `tools/api_fuzzer.py`: Autonomous API fuzzer detecting HTTP 500 crashes, database stacktrace leaks, and latency SLA breaches.
-- `tools/api_drift_sentinel.py`: Contract drift detector comparing OpenAPI/Swagger specifications for breaking changes.
-- `tools/auto_heal.py`: In-place locator self-healing engine correlating JUnit XML and screenshots via AOM diffing.
-- `tools/flaky_detector.py`: Flaky test detector and automated quarantine lifecycle manager.
-- `tools/skillspector.py`: AI Agent Skill & MCP Security Sentinel (71 detection vectors, Prohibition Context Engine, SARIF/JSON reporting).
-- `tools/omni_transpiler.py`: 0-token polyglot test transpiler (Playwright TS/Python, Java, Groovy, Cypress).
-- `tools/infer_linter.py`: Static AST analysis detecting fake passes (zero asserts) and empty catch blocks.
-- `tools/test_impact.py`: Scopes affected test cases based on git diffs.
-- `tools/cache_resolver.py`: Manages the central SQLite error memory cache (`~/.agent_memory/global_cache.db`).
-- `tools/distill_log.py`: Filters 95% noise from CLI/Gradle/KRE logs, preserving stacktraces and pointers.
-- `tools/agent_canary.py`: Injects 8 failure vectors to benchmark MTTR and autonomous recovery rate.
-- `tools/repo_map.py`: Extracts a compressed method and Page Class map (~500 tokens).
-- `tools/visual_diff_canvas.py`: Pixel/SSIM comparison for canvas/GIS interfaces lacking standard DOM.
-- `tools/wcag_audit.py`: Automated scanning for WCAG 2.2 Level A/AA criteria.
-- `tools/generate_api_matrix.py`: Generates positive, boundary, and negative test matrices from Swagger/OpenAPI.
-- `tools/generate_tc_from_story.py`: Large Action Model parser generating Clean POM skeletons from stories.
-- `tools/trace_data_flow.py`: Taint analysis tracking test data flow and preventing database orphan junk.
-- `scripts/install.ps1` & `scripts/setup.sh`: 1-click bootstrap scripts setting up the hub environment.
-- `scripts/lint_skills.ps1`: Linter verifying skill integrity and metadata manifest.
-- `pyproject.toml` & `tools/cli.py`: PEP 621 packaging for the global `agent-qa` CLI.
+| # | Mã Kỹ Năng | Mô Tả Thực Chiến |
+|:---:|---|---|
+| 1 | `clean-pom-crafter` | Thiết kế Page Classes chuẩn Clean POM & Flat Architecture (zero locator trong test script). |
+| 2 | `playwright-live-interaction` | Khảo sát trực tiếp DOM/AOM, kiểm định selector < 200ms qua Playwright Headless. |
+| 3 | `failure-autopsy-and-healing` | Phân tích nguyên nhân lỗi từ JUnit XML/Screenshot, tự động vá locator hỏng. |
+| 4 | `antigravity-test-sentinel` | Chốt chặn kiểm soát chất lượng, phát hiện pass ảo và bảo đảm tuân thủ 9 cổng DoD. |
+| 5 | `token-and-context-optimizer` | Tối ưu hóa prompt context, cô đọng log và chống suy giảm ngữ cảnh (Context Rot). |
+| 6 | `flaky-test-sentinel-and-quarantine` | Phát hiện test chập chờn, tính điểm flakiness và quản lý vòng đời cách ly. |
+| 7 | `api-spec-to-e2e-matrix` | Chuyển đổi đặc tả OpenAPI/Swagger thành ma trận kiểm thử E2E (Happy, Boundary, Fault). |
+| 8 | `api-network-mocking-interception` | Chặn bắt traffic HTTP/GraphQL, giả lập route và tiêm lỗi mạng hỗn loạn (chaos testing). |
+| 9 | `synthetic-test-data-generator` | Sinh dữ liệu kiểm thử giả lập, chống trùng lặp khóa chính trong cơ sở dữ liệu. |
+| 10 | `db-state-verifier-and-seeder` | Khởi tạo dữ liệu mẫu cô lập và kiểm tra biến đổi DB qua SQL/NoSQL. |
+| 11 | `visual-regression-sentinel` | So sánh ảnh chụp màn hình phát hiện lệch pixel với cơ chế che chắn ảnh động (anti-flake mask). |
+| 12 | `wcag-audit-patterns` | Kiểm toán khả năng tiếp cận theo tiêu chuẩn WCAG 2.2 A/AA và vai trò ARIA. |
+| 13 | `security-dast-sentinel` | Kiểm tra bảo mật động DAST: OWASP Top 10, tiêu đề bảo mật, rò rỉ token và IDOR. |
+| 14 | `web-vitals-and-performance-profiler` | Đo lường Core Web Vitals (LCP, CLS, INP) và thác mạng (network waterfall) qua CDP. |
+| 15 | `backend-load-and-stress-patterns` | Điều phối kịch bản tải k6, Locust và Apache JMeter đo lường SLA chịu tải. |
+| 16 | `auth-session-and-cookie-manager` | Quản lý phiên đăng nhập `storageState`, JWT token và trạng thái đa vai trò. |
+| 17 | `file-and-report-validator` | Kiểm tra tính toàn vẹn của tệp tải về/tải lên (Excel, CSV, PDF) so với schema. |
+| 18 | `e2e-testing-patterns` | Thiết kế kiến trúc kiểm thử E2E đa trình duyệt, chia tải song song và quản trị retry. |
+| 19 | `lam-script-generator` | Chuyển đổi User Story và tiêu chí chấp nhận thành kịch bản kiểm thử tự động. |
+| 20 | `katalon-cli-runner` | Điều phối chạy kiểm thử Katalon/Gradle headless với cơ chế tự dọn driver. |
+| 21 | `bats-testing-patterns` | Kiểm thử shell script, công cụ CLI và pipeline CI/CD bằng Bats. |
+| 22 | `code-refactoring-refactor-clean` | Khử nợ kỹ thuật, tái cấu trúc mã kiểm thử theo nguyên lý SOLID & Clean Code. |
+| 23 | `agent-orchestration-multi-agent-optimize` | Đo lường tải và điều phối đa agent tối ưu hóa lưu lượng token. |
+| 24 | `architecture-decision-records` | Soạn thảo và duy trì hồ sơ quyết định kiến trúc kỹ thuật (ADR). |
+| 25 | `github-actions-templates` | Mẫu pipeline GitHub Actions chuẩn sản xuất cho kiểm thử tự động và CI/CD. |
+| 26 | `graphify-impact-analyzer` | Phân tích phạm vi ảnh hưởng của thay đổi mã nguồn qua đồ thị quan hệ AST. |
+| 27 | `skillspector-security-guard` | Quét lỗ hổng prompt injection và cấu hình MCP theo tiêu chuẩn an toàn bảo mật. |
+| 28 | `gherkin-to-suite` | Biên dịch file `.feature` BDD thành ma trận test, Universal IR và phân tích khoảng trống độ phủ. |
+| 29 | `rbt-manual-testing` | Quy trình AI-RBT sinh kịch bản kiểm thử thủ công dựa trên rủi ro, ma trận 12 cột và checklist input field. |
+| 30 | `self-healing-locator` | Tự động phát hiện và vá lỗi định vị phần tử bằng phân tích sai khác cây Accessibility (AOM). |
+| 31 | `persistent-planning-files` | Lưu kế hoạch, phát hiện và tiến độ xuống 3 file markdown để công việc đa pha sống sót qua reset ngữ cảnh. |
+| 32 | `surgical-coding-principles` | Bốn nguyên tắc chỉnh sửa có kỷ luật: nêu giả định, tối giản diff, mọi dòng đổi đều truy về yêu cầu. |
+| 33 | `lean-code-ladder` | Thang 7 bậc reuse-first: chọn phương án nhỏ nhất hoàn chỉnh trước khi viết code mới. |
+| 34 | `playwright-webapp-testing` | Vòng đời server có kiểm soát (start/ready/teardown) khi chạy Playwright test web app cục bộ. |
+| 35 | `test-driven-development` | Kỷ luật RED-GREEN-REFACTOR: chưa xem test fail đúng lý do thì chưa viết code sản phẩm. |
+| 36 | `systematic-debugging` | Điều tra gốc rễ 4 pha trước mọi bản vá; 3 lần sửa thất bại là dấu hiệu sai kiến trúc. |
+| 37 | `verification-before-completion` | Giao thức bằng chứng: mọi tuyên bố pass/done phải kèm output lệnh chạy tươi trong phiên. |
+| 38 | `meta-prompt-crafter` | Chuyên gia kỹ thuật prompt chuyển hóa ý tưởng thô thành câu lệnh chuẩn xác, tối ưu cho mọi AI. |
+
+> **Nguồn mở & credit:** Kỹ năng 31–37 được kế thừa và phát triển từ các dự án mã nguồn mở (andrej-karpathy-skills, ponytail, planning-with-files, anthropics/skills, superpowers, wshobson/agents) — license và tác giả chi tiết tại file `NOTICE` (mục 16–21); hướng dẫn công cụ ngoài kèm theo tại `docs/adopted-ecosystem-tools.md`.
+
+</details>
 
 ---
 
-## 📚 7. Extended Technical Documentation & CLI Package (docs/)
+## 🛠️ 8. Bộ Công Cụ Dòng Lệnh CLI (tools/)
 
-1. **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**: Hub/Spoke architecture, 4-tier skill model, and 6-agent swarm coordination.
-2. **[docs/CONTRIBUTING.md](docs/CONTRIBUTING.md)**: Contribution standards, new skill authoring principles, and verification pipelines.
-3. **[docs/CLI_REFERENCE.md](docs/CLI_REFERENCE.md)**: Comprehensive command-line reference for the `agent-qa` CLI.
+Dự án đi kèm hơn 60 công cụ tiện ích viết hoàn toàn bằng **thư viện chuẩn Python** (Standard Library), không phụ thuộc package ngoài:
 
-### Quick CLI Installation:
 ```bash
-pip install -e .
-agent-qa --help
-agent-qa verify
-agent-qa lint
-agent-qa skillspector
-```
+# 1. Chẩn đoán môi trường hệ thống (Node, Python, Chrome, Git)
+npx synapse-hub doctor
 
----
+# 2. Kiểm tra 9 Cổng Chất Lượng DoD
+npx synapse-hub verify
 
-## 🤝 8. Acknowledgments & Upstream Inspirations
+# 3. Quét phát hiện test pass ảo và ngoại lệ bị bỏ qua ngầm
+npx synapse-hub lint ./tests
 
-**Synapse Hub** synthesizes, adapts, and builds upon groundbreaking methodologies and architectures from the global open-source and AI engineering community:
+# 4. Nén 95% log CI/CD cồng kềnh
+npx synapse-hub distill path/to/ci.log
 
-| Project & Author | Architectural Inspiration in Synapse Hub |
-| :--- | :--- |
-| **[NVIDIA/SkillSpector](https://github.com/NVIDIA/SkillSpector)** *(NVIDIA AI Security Team)* | AI Agent skill & MCP security vetting engine (`tools/skillspector.py`, Skill #28 `skillspector-security-guard`) featuring 71 vulnerability vectors across 17 categories and the Prohibition Context Engine. |
-| **[muratcankoylan/Agent-Skills-for-Context-Engineering](https://github.com/muratcankoylan/Agent-Skills-for-Context-Engineering)** | Context Engineering foundations, observation masking, and LLM attention budget optimization. |
-| **[alexgreensh/token-optimizer](https://github.com/alexgreensh/token-optimizer)** | Token-efficient reasoning, 95% log distillation, and KV-cache serialization protocols. |
-| **[obra/superpowers](https://github.com/obra/superpowers)** *(Jesse Vincent)* | Systematic evidence-based debugging, cognitive forcing functions, and Red-Team vs Blue-Team verification. |
-| **[Aider-AI/aider](https://github.com/Aider-AI/aider)** *(Paul Gauthier)* | Ultra-compact AST repository mapping algorithm (`tools/repo_map.py`) fitting 500+ signatures in < 600 tokens. |
-| **[lavague-ai/LaVague](https://github.com/lavague-ai/LaVague)** | Large Action Model (LAM) concept compiling natural language stories into deterministic Clean POM scripts. |
-| **[facebook/infer](https://github.com/facebook/infer)** *(Meta Infer)* | Static AST defect sentinel (`tools/infer_linter.py`) catching swallowed exceptions and 0-assertion fake passes. |
-| **[microsoft/playwright](https://github.com/microsoft/playwright)** | Sub-200ms headless live DOM/AOM probing, route stubbing, and anti-flake network shielding. |
-| **[dequelabs/axe-core](https://github.com/dequelabs/axe-core)** | Automated accessibility rule heuristics inspiring WCAG 2.2 Level A/AA AST auditing. |
-| **[bats-core/bats-core](https://github.com/bats-core/bats-core)** | Bash Automated Testing System patterns for CI/CD pipelines and cross-platform CLI verification. |
-| **[npryce/adr-tools](https://github.com/npryce/adr-tools)** | Architecture Decision Record (ADR) conventions and lifecycle workflows. |
+# 5. Xuất test case sang file Excel .xlsx chuẩn 12 cột
+npx synapse-hub export-excel
 
----
+# 6. Kiểm tra độ nhạy của các câu lệnh assert
+npx synapse-hub mutate ./tests
 
-## 📄 9. License & Author Attribution
+# 7. Dò tìm và cách ly test chập chờn (Flaky Tests)
+npx synapse-hub flaky scan ./tests
+```
 
-This project is licensed under the **[MIT License](LICENSE)**.
+*(Xem toàn bộ hướng dẫn tham số chi tiết tại [docs/CLI_REFERENCE.md](docs/CLI_REFERENCE.md) và [tools/TOOLS_RUNBOOK.md](tools/TOOLS_RUNBOOK.md)).*
 
-**Provenance & Copyright Notice:**
-- **Author & Founder:** Thế Vị ([@TeeVee998](https://github.com/TeeVee998))
-- **Original Repository:** [https://github.com/TeeVee998/Synapse-Hub](https://github.com/TeeVee998/Synapse-Hub)
-- **Copyright:** Copyright (c) 2026 Thế Vị (@TeeVee998). Distributed under the MIT License.
+> 💡 **Bí danh dòng lệnh tương đương:** Khi cài đặt toàn cục (`npm i -g synapse-hub`), bạn có thể sử dụng bất kỳ bí danh nào: `synapse-hub`, `synapse`, hoặc `agent-qa` (ví dụ: `synapse verify`, `agent-qa lint ./tests`).
 
-> ⚖️ **MIT License Attribution Requirement:** Under the terms of the MIT License, you are granted permission to use, copy, modify, merge, publish, and distribute this software freely, **PROVIDED** that the original copyright notice crediting **Thế Vị (@TeeVee998)** and this permission notice are included in all copies or substantial portions of the Software.
+---
 
+## 📄 Bản Quyền & Nguồn Gốc (MIT License)
 
+Dự án này được sáng lập và phát triển bởi **Thế Vị ([@TeeVee998](https://github.com/TeeVee998))** dưới giấy phép mã nguồn mở [MIT License](LICENSE).  
+Mọi hình thức sao chép, tích hợp hoặc phân phối lại đều được tự do sử dụng, với điều kiện **bắt buộc phải giữ nguyên thông báo bản quyền và nguồn tác giả ban đầu**.