synapse-hub 3.0.0 → 3.0.1

package/docs/CONTRIBUTING.md

@@ -1,34 +1,34 @@
-# Hướng Dẫn Đóng Góp / Contributing to Synapse-Hub
+# Hướng Dẫn Đóng Góp Vào Synapse-Hub
 
-[🇻🇳 Tiếng Việt](#-hướng-dẫn-đóng-góp-tiếng-việt) | [🇬🇧 English Edition](#-english-edition)
+[🇻🇳 Tiếng Việt](CONTRIBUTING.md) | [🇬🇧 English Edition](CONTRIBUTING.en.md)
 
----
-
-## 🇻🇳 Hướng Dẫn Đóng Góp (Tiếng Việt)
+Chào mừng bạn tham gia đóng góp mở rộng kỹ năng (Skills), công cụ (Tools) và các quy tắc kiểm thử trong hệ sinh thái **Synapse Hub**. Mọi đóng góp đều cần tuân thủ 2 nguyên tắc then chốt: **Truth Anchor** (chống test pass ảo, trung thực kỹ thuật) và **Tiết Kiệm Token Tối Đa**.
 
-Chúng tôi rất hoan nghênh các đóng góp từ cộng đồng nhằm mở rộng kỹ năng (Skills), công cụ (Tools) và các quy chuẩn kiểm thử trong hệ sinh thái **Synapse-Hub**. Mọi đóng góp đều cần tuân thủ triệt để nguyên tắc **Truth Anchor** (chống pass ảo, trung thực kỹ thuật) và **Tiết kiệm Token**.
+---
 
-### 1. Quy Chuẩn Viết Kỹ Năng Mới (Skill Standards)
+## 1. Quy Chuẩn Khi Viết Kỹ Năng Mới (Skill Standards)
 
-Mỗi kỹ năng nằm trong thư mục `.agents/skills/<tên-kỹ-năng>/` và cần đáp ứng:
+Mỗi kỹ năng nằm trong thư mục riêng `.agents/skills/<ten-ky-nang>/` và cần đáp ứng các tiêu chí sau:
 
-1. **Cấu trúc tệp `SKILL.md`:**
+1. **Cấu trúc file `SKILL.md`:**
    - Bắt buộc có phần mở đầu YAML frontmatter chuẩn xác chứa `name` và `description`.
-   - `name` phải trùng khớp 100% với tên thư mục (dạng `kebab-case`).
-   - `description` mô tả rõ ràng phạm vi kích hoạt, phân biệt rành mạch với các kỹ năng lân cận để tránh xung đột prompt.
+   - `name` phải trùng khớp 100% với tên thư mục (định dạng `kebab-case`).
+   - `description` phải nêu rõ phạm vi và ngữ cảnh kích hoạt, phân biệt rõ ràng với các kỹ năng khác để AI không bao giờ gọi nhầm.
 2. **Ngắn Gọn & Tiết Kiệm Token:**
-   - Hướng dẫn kỹ thuật viết bằng tiếng Anh ngắn gọn, chuẩn xác để tối ưu hóa lượng token ngữ cảnh cho AI.
-   - Áp dụng nguyên lý nạp thông tin lũy tiến (Progressive Disclosure): giữ `SKILL.md` trong khoảng 40 đến 150 dòng; các đoạn code mẫu chi tiết đưa vào `examples/` hoặc `references/`.
-3. **Không Ràng Buộc Vào Dự Án Cụ Thể (Decoupled):**
-   - Tuyệt đối không gán cứng tên dự án riêng tư, domain bí mật, mật khẩu hay endpoint nội bộ.
-   - Luôn sử dụng định danh mẫu: `https://staging.example.com`, `auto_user_123`.
+   - Nội dung chỉ dẫn kỹ thuật viết bằng tiếng Anh ngắn gọn, súc tích để tránh làm đầy ngữ cảnh của AI.
+   - Áp dụng nguyên lý tải thông tin lũy tiến (Progressive Disclosure): giữ file `SKILL.md` trong khoảng 40 đến 150 dòng; các đoạn code mẫu dài nên đưa vào thư mục `examples/` hoặc `references/`.
+3. **Tuyệt Đối Không Phụ Thuộc Vào Dự Án Cụ Thể (Decoupled):**
+   - Không được hardcode tên dự án nội bộ, domain riêng tư, mật khẩu hay endpoint bí mật.
+   - Luôn dùng định danh mẫu: `https://staging.example.com`, `auto_user_123`.
 
-### 2. Quy Trình Kiểm Thử Trước Khi Mở Pull Request
+---
+
+## 2. Quy Trình Kiểm Thử Trước Khi Mở Pull Request
 
-Trước khi gửi PR hoặc đẩy code lên nhánh `develop`:
+Trước khi mở PR hoặc đẩy code lên nhánh `develop`:
 
 ```bash
-# 1. Chạy toàn bộ 170+ bài kiểm thử đơn vị
+# 1. Chạy toàn bộ 260+ bài unit test
 python3 -m unittest discover tests
 
 # 2. Kiểm định toàn vẹn 10 Cổng Chất Lượng DoD (Gate 0–9)
@@ -38,54 +38,12 @@ python3 tools/verify_all.py
 python3 tools/lint_ai_docs.py
 ```
 
-### 3. Nguyên Tắc Phát Triển Công Cụ (Tools)
-
-Mọi công cụ tiện ích trong `tools/` cần tuân thủ:
-1. **Ưu Tiên Thư Viện Chuẩn Python (Standard Library):** Hạn chế tối đa thư viện bên ngoài để công cụ chạy được ngay trên máy sạch và CI mà không cần cài đặt phức tạp.
-2. **Tốc Độ Xử Lý Siêu Tốc:** Các phép quét AST và regex phải hoàn tất dưới 500ms.
-3. **Không Ghi Rác Vào Repo:** Khi viết test, bắt buộc sử dụng thư mục tạm `tempfile.TemporaryDirectory()`, không để lại file rác trong repo.
-4. **Thông Báo Lỗi Thân Thiện:** Luôn cung cấp gợi ý sửa lỗi rõ ràng (`Fix Hint`) thay vì chỉ in ra stacktrace thô.
-
 ---
 
-## 🇬🇧 English Edition
-
-We welcome contributions to expand and refine skills, tools, and rules in the **Synapse-Hub** ecosystem. All contributions must adhere to our **Truth Anchor** (no fake passes) and **Token-Efficiency** standards.
-
-### 1. Skill Authoring Standards
-
-Every skill resides in `.agents/skills/<skill-name>/` and must satisfy:
-
-1. **`SKILL.md` Structure:**
-   - Must contain valid YAML frontmatter with `name` and `description`.
-   - `name` must exactly match the directory name in kebab-case.
-   - `description` must clearly articulate the triggering scope and disambiguate itself from adjacent skills.
-2. **Conciseness & Token Budget:**
-   - Write instructions in concise technical English to minimize LLM token consumption.
-   - Use progressive disclosure: keep `SKILL.md` between 40 and 150 lines, and offload deep code patterns to `references/` or `examples/`.
-3. **Zero Project Coupling:**
-   - Never hardcode specific project names, proprietary URLs, test credentials, or internal namespaces.
-   - Always use generic placeholders: `<project_namespace>`, `https://app.example.com`, `APP_PASSWORD`.
-
-### 2. Integrity Verification Workflow
-
-Before submitting a pull request or committing changes:
-
-```bash
-# 1. Run unit test suite (170+ tests)
-python3 -m unittest discover tests
-
-# 2. Verify all 9 DoD Quality Gates
-python3 tools/verify_all.py
-
-# 3. Test documentation and entity references integrity
-python3 tools/lint_ai_docs.py
-```
-
-### 3. Tool Development Guidelines
+## 3. Nguyên Tắc Phát Triển Công Cụ Mới (Tools)
 
-All helper scripts in `tools/` must:
-1. **Rely on Standard Libraries:** Minimize third-party package dependencies so tools execute seamlessly across clean host machines and CI pipelines.
-2. **Be Fast & Non-Blocking:** AST scans and regex lookups must complete in under 500ms.
-3. **Zero Test File Pollution:** Tests must use `tempfile.TemporaryDirectory()` and never write temporary test artifacts to the repository tree.
-4. **Handle Errors Gracefully:** Provide clear remedies and pointers rather than dumping raw stack traces.
+Mọi công cụ tiện ích trong thư mục `tools/` cần tuân thủ:
+1. **Ưu Tiên Thư Viện Chuẩn Python (Standard Library):** Hạn chế tối đa thư viện bên ngoài để công cụ chạy được ngay trên máy sạch và CI mà không cần `pip install` phức tạp.
+2. **Tốc Độ Xử Lý Phải Nhanh:** Các phép quét AST và regex phải hoàn tất dưới 500ms.
+3. **Không Làm Bẩn Repo:** Khi viết test cho công cụ, bắt buộc dùng thư mục tạm `tempfile.TemporaryDirectory()`, không được để lại bất kỳ file rác nào trong repo.
+4. **Báo Lỗi Thân Thiện Kèm Cách Sửa:** Luôn cung cấp gợi ý khắc phục (`Fix Hint`) rõ ràng thay vì chỉ in ra stacktrace thô.

package/docs/QUALITY_GATES.en.md

@@ -0,0 +1,115 @@
+# 🛡️ 10 Quality Gates Definition of Done (DoD) Standard
+
+[🇻🇳 Tiếng Việt](QUALITY_GATES.md) | [🇬🇧 English Edition](QUALITY_GATES.en.md)
+
+> **Scope:** Enterprise automated verification sentinel enforcing 10 non-negotiable Quality Gates across Synapse Hub and target client projects.  
+> **Command:** `python3 tools/verify_all.py` or `npx synapse-hub verify`  
+> **Integrity Guard:** Synapse Hub created by **Thế Vị (@TeeVee998)** (<https://github.com/TeeVee998/Synapse-Hub>) under MIT License.
+
+---
+
+## 📋 Quality Gates Matrix Overview
+
+| Gate | Name | Target Scope | Engine / Tool | Exit Code | Passing Criteria (DoD) |
+| :---: | :--- | :--- | :--- | :---: | :--- |
+| **Gate 0** | **Author Attribution & MIT Integrity** | Repository-wide | `tools/author_integrity.py` | 0 | MIT License notice and author attribution intact across all source files. |
+| **Gate 1** | **UTF-8 No BOM Encoding** | All source & config files | `tools/verify_all.py` | 0 | Zero Byte Order Mark (`0xEF, 0xBB, 0xBF`) bytes across any file. |
+| **Gate 2** | **Path Portability** | All source & test files | `tools/verify_all.py` | 0 | Zero hardcoded personal/machine absolute paths (`/Users/...`, `C:\...`). |
+| **Gate 3** | **Clean POM & Flat Architecture** | Test scripts (`tests/`, `Scripts/`) | `tools/verify_all.py` | 0 | Zero raw XPaths or CSS selectors in test scripts; 100% locators encapsulated in Page Classes. |
+| **Gate 4** | **AI Documentation & Anti-Drift** | `PROJECT_AI_GUIDE.md` & AST | `tools/lint_ai_docs.py` | 0 | 0 hallucinated PageClasses; 100% documented methods exist in codebase AST. |
+| **Gate 5** | **Temporary Files Blacklist** | Repository tree | `tools/verify_all.py` | 0 | Zero scratch files, heap dumps, or temporary artifacts (`*.tmp`, `.ruff_cache`, memory dumps). |
+| **Gate 6** | **Credential & Secret Security** | All files & git index | `tools/verify_all.py` | 0 | Zero plaintext passwords, API keys, private tokens, or AWS/JWT credentials committed. |
+| **Gate 7** | **Static Defect & Fake-Pass Sentinel** | Test scripts & tools | `tools/infer_linter.py` | 0 | Zero empty assertions (0 assert), zero swallowed exceptions (`pass`), zero hardcoded sleeps (>= 3000ms). |
+| **Gate 8** | **Assertion Sensitivity (Mutation Score)** | Test assertions | `tools/micro_mutator.py` | 0 | Mutation kill score >= 80% (heuristic static mutant detection catches >= 80% syntactic modifications). |
+| **Gate 9** | **Skill Routing & Collision Guard** | Skill descriptions | `tools/skill_collision_guard.py` | 0 | Zero overlapping trigger collisions (semantic cosine similarity < 0.75 across all skill pairs). |
+
+---
+
+## 🔍 Detailed Gate Specifications
+
+### Gate 0: Author Attribution & MIT License Integrity
+- **Objective:** Protects open-source attribution provenance under MIT License.
+- **Verification Rule:** Rejects any commit, pull request, or modification that attempts to strip copyright notices, false-claim authorship, or remove provenance headers referencing Thế Vị (@TeeVee998).
+- **Remediation:** Restore license headers and canonical notice in `LICENSE` and `NOTICE`.
+
+### Gate 1: UTF-8 No BOM Encoding Integrity
+- **Objective:** Eliminates cross-platform file encoding corruption between Windows, macOS, and Linux CI/CD runners.
+- **Verification Rule:** Inspects raw bytes of all text files. Any occurrence of BOM bytes (`0xEF, 0xBB, 0xBF`) causes immediate failure.
+- **Remediation:** Run `python3 tools/verify_all.py --fix-bom` to strip BOM bytes automatically.
+
+### Gate 2: Path Portability
+- **Objective:** Guarantees test scripts and tooling execute seamlessly across team developer workstations, Docker containers, and CI pipelines.
+- **Verification Rule:** Regex scans for machine-specific path roots (`/Users/`, `/home/`, `C:\`, `D:\`).
+- **Remediation:** Replace absolute paths with dynamic workspace resolution (`Path(__file__).resolve().parent.parent` or `resolve_target_repo()`).
+
+### Gate 3: Clean POM & Flat Architecture
+- **Objective:** Enforces clean separation of concerns. Test scripts must contain solely business workflow actions, never DOM traversal.
+- **Verification Rule:** Prohibits raw CSS selectors, XPaths, or `findTestObject` inside `tests/` or `Scripts/`. All UI operations must be delegated to methods on Page Classes extending `BasePage`.
+- **Remediation:** Encapsulate locators and interaction logic inside dedicated Page Classes.
+
+### Gate 4: AI Documentation & Anti-Drift Linter
+- **Objective:** Prevents AI context drift where documentation refers to non-existent Page Classes or obsolete method signatures.
+- **Verification Rule:** Extracts all documented Page Classes and methods from `PROJECT_AI_GUIDE.md` and verifies their physical AST existence in the codebase.
+- **Remediation:** Run `python3 tools/lint_ai_docs.py` to identify drifts, then re-index via `python3 tools/repo_map.py`.
+
+### Gate 5: Temporary Files Blacklist
+- **Objective:** Maintains git hygiene and prevents polluting repositories with binary dumps or local IDE caches.
+- **Verification Rule:** Scans for prohibited extensions: `*.tmp`, `*.dump`, `*.log`, `*.orig`, `*.bak`, `.ruff_cache/`, `.mypy_cache/`.
+- **Remediation:** Add unignored patterns to `.gitignore` and delete temporary files.
+
+### Gate 6: Credential Security Sentinel
+- **Objective:** Prevents enterprise credential leaks (API tokens, database connection strings, private keys).
+- **Verification Rule:** High-entropy regex scanner detecting AWS secret keys, Bearer tokens, private RSA keys, and hardcoded passwords.
+- **Remediation:** Move credentials to environment variables or `.env` (ensuring `.env` is listed in `.gitignore`).
+
+### Gate 7: Static Defect & Fake-Pass Sentinel
+- **Objective:** Eliminates "fake passes" created by AI code generation (tests that pass trivially without asserting anything).
+- **Verification Rule:**
+  - Flags tests containing 0 assertions.
+  - Flags empty catch blocks (`except Exception: pass`) swallowing failure exceptions.
+  - Flags hardcoded sleeps (`sleep(5000)`, `Thread.sleep(5000)`).
+  - Flags unawaited Playwright assertions (`expect(el).toBeVisible()` without `await`).
+- **Remediation:** Add meaningful assertions; replace sleeps with smart waits (`waitForLoadState('networkidle')`, element visibility checks).
+
+### Gate 8: Assertion Sensitivity & Syntactic Mutation Sentinel
+- **Objective:** Guarantees assertions are sensitive enough to catch real defects, not tautological (always-true) expressions.
+- **Verification Rule:** Injects syntactic mutations (reversing comparison operators `==` to `!=`, swapping boolean constants, altering return values). Requires Mutation Score >= 80%.
+- **Remediation:** Run `python3 tools/micro_mutator.py --strict` to inspect surviving mutants and tighten test assertions.
+
+### Gate 9: Tier-2 Skill Routing & Collision Guard
+- **Objective:** Prevents AI agent prompt confusion caused by overlapping skill trigger descriptions.
+- **Verification Rule:** Computes pairwise cosine similarity between all skill `SKILL.md` description fields. Similarity must remain strictly < 0.75.
+- **Remediation:** Differentiate skill descriptions using the standardized formula `[Function] + Use when [context]` (<= 350 characters).
+
+---
+
+## 🚀 Execution & CI/CD Integration
+
+### Run Locally:
+```bash
+# Verify all 10 Gates on current repository
+python3 tools/verify_all.py
+
+# Verify target project from Hub
+python3 tools/verify_all.py --target /path/to/project
+
+# Output as JUnit XML for CI/CD reporting
+python3 tools/verify_all.py --format junit --output reports/dod_gates.xml
+```
+
+### GitHub Actions Pipeline (`.github/workflows/verify.yml`):
+```yaml
+name: Synapse Hub 10 DoD Quality Gates
+on: [push, pull_request]
+
+jobs:
+  quality-gates:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Run 10 Quality Gates
+        run: python tools/verify_all.py --mode target
+```

package/docs/QUALITY_GATES.md

@@ -1,101 +1,103 @@
-# 🛡️ 10 Quality Gates Definition of Done (DoD) Standard
+# 🛡️ Tiêu Chuẩn 10 Cổng Chất Lượng DoD (Definition of Done)
 
-> **Scope:** Enterprise automated verification sentinel enforcing 10 non-negotiable Quality Gates across Synapse Hub and target client projects.  
-> **Command:** `python3 tools/verify_all.py` or `npx synapse-hub verify`  
-> **Integrity Guard:** Synapse Hub created by **Thế Vị (@TeeVee998)** (<https://github.com/TeeVee998/Synapse-Hub>) under MIT License.
+[🇻🇳 Tiếng Việt](QUALITY_GATES.md) | [🇬🇧 English Edition](QUALITY_GATES.en.md)
+
+> **Phạm vi:** Hệ thống chốt chặn tự động kiểm tra 10 Cổng Chất Lượng bắt buộc trên Synapse Hub và các dự án kiểm thử con.  
+> **Lệnh thực thi:** `python3 tools/verify_all.py` hoặc `npx synapse-hub verify`  
+> **Bảo toàn tác quyền:** Synapse Hub được sáng lập bởi **Thế Vị (@TeeVee998)** (<https://github.com/TeeVee998/Synapse-Hub>) theo giấy phép MIT.
 
 ---
 
-## 📋 Quality Gates Matrix Overview
-
-| Gate | Name | Target Scope | Engine / Tool | Exit Code | Passing Criteria (DoD) |
-|:---:|:---|:---|:---|:---:|:---|
-| **Gate 0** | **Author Attribution & MIT Integrity** | Repository-wide | `tools/author_integrity.py` | 0 | MIT License notice and author attribution intact across all source files. |
-| **Gate 1** | **UTF-8 No BOM Encoding** | All source & config files | `tools/verify_all.py` | 0 | Zero Byte Order Mark (`0xEF, 0xBB, 0xBF`) bytes across any file. |
-| **Gate 2** | **Path Portability** | All source & test files | `tools/verify_all.py` | 0 | Zero hardcoded personal/machine absolute paths (`/Users/...`, `C:\...`). |
-| **Gate 3** | **Clean POM & Flat Architecture** | Test scripts (`tests/`, `Scripts/`) | `tools/verify_all.py` | 0 | Zero raw XPaths or CSS selectors in test scripts; 100% locators encapsulated in Page Classes. |
-| **Gate 4** | **AI Documentation & Anti-Drift** | `PROJECT_AI_GUIDE.md` & AST | `tools/lint_ai_docs.py` | 0 | 0 hallucinated PageClasses; 100% documented methods exist in codebase AST. |
-| **Gate 5** | **Temporary Files Blacklist** | Repository tree | `tools/verify_all.py` | 0 | Zero scratch files, heap dumps, or temporary artifacts (`*.tmp`, `.ruff_cache`, memory dumps). |
-| **Gate 6** | **Credential & Secret Security** | All files & git index | `tools/verify_all.py` | 0 | Zero plaintext passwords, API keys, private tokens, or AWS/JWT credentials committed. |
-| **Gate 7** | **Static Defect & Fake-Pass Sentinel** | Test scripts & tools | `tools/infer_linter.py` | 0 | Zero empty assertions (0 assert), zero swallowed exceptions (`pass`), zero hardcoded sleeps (>= 3000ms). |
-| **Gate 8** | **Assertion Sensitivity (Mutation Score)** | Test assertions | `tools/micro_mutator.py` | 0 | Mutation kill score >= 80% (heuristic static mutant detection catches >= 80% syntactic modifications). |
-| **Gate 9** | **Skill Routing & Collision Guard** | Skill descriptions | `tools/skill_collision_guard.py` | 0 | Zero overlapping trigger collisions (semantic cosine similarity < 0.75 across all skill pairs). |
+## 📋 Bảng Tổng Quan 10 Cổng Kiểm Định Chất Lượng
+
+| Cổng | Tên Cổng | Phạm Vi Quét | Công Cụ Kiểm Tra | Mã Thoát | Tiêu Chuẩn Đạt (DoD) |
+| :---: | :--- | :--- | :--- | :---: | :--- |
+| **Gate 0** | **Bảo Toàn Tác Quyền & Giấy Phép MIT** | Toàn bộ repo | `tools/author_integrity.py` | 0 | Giữ nguyên thông báo bản quyền MIT và tác giả gốc Thế Vị (@TeeVee998). |
+| **Gate 1** | **Chuẩn Mã Hóa UTF-8 No BOM** | Toàn bộ file code & config | `tools/verify_all.py` | 0 | 100% file không chứa ký tự BOM rác (`0xEF, 0xBB, 0xBF`). |
+| **Gate 2** | **Đường Dẫn Linh Hoạt (Path Portability)** | Code test & script công cụ | `tools/verify_all.py` | 0 | Không hardcode đường dẫn tuyệt đối của máy cá nhân (`/Users/...`, `C:\...`). |
+| **Gate 3** | **Kiến Trúc Clean POM Phẳng** | Thư mục test (`tests/`, `Scripts/`) | `tools/verify_all.py` | 0 | 100% locator nằm trong Page Class; không để XPath/CSS selector trong file test. |
+| **Gate 4** | **Chống Bịa Đặt Tài Liệu AI (Anti-Drift)** | `PROJECT_AI_GUIDE.md` & AST code | `tools/lint_ai_docs.py` | 0 | 0 PageClass ảo; 100% hàm tài liệu hóa phải tồn tại thật trong AST codebase. |
+| **Gate 5** | **Chặn File Rác Lọt Vào Git** | Toàn bộ cây thư mục | `tools/verify_all.py` | 0 | Không để file rác, file tạm lọt vào git (`*.tmp`, `.ruff_cache`, heap dump, log). |
+| **Gate 6** | **Quét Mật Khẩu & Token Bí Mật** | Toàn bộ file & git index | `tools/verify_all.py` | 0 | Không commit mật khẩu dạng plaintext, API key, token JWT hoặc private key. |
+| **Gate 7** | **Bắt Lỗi Tĩnh & Test Pass Ảo** | File test & công cụ | `tools/infer_linter.py` | 0 | Chặn đứng test 0 assert, try-catch nuốt lỗi (`pass`), dùng sleep cứng (>= 3000ms). |
+| **Gate 8** | **Đo Độ Nhạy Của Assert (Mutation Score)** | Toàn bộ câu lệnh assert | `tools/micro_mutator.py` | 0 | Tỷ lệ diệt đột biến $\ge 80\%$ (bắt được ít nhất 80% đột biến cú pháp cố ý). |
+| **Gate 9** | **Điều Phối Kỹ Năng Tránh Trùng Lặp** | File `SKILL.md` của các skill | `tools/skill_collision_guard.py` | 0 | Mô tả kích hoạt kỹ năng không được đè phạm vi của nhau (cosine similarity < 0.75). |
 
 ---
 
-## 🔍 Detailed Gate Specifications
-
-### Gate 0: Author Attribution & MIT License Integrity
-- **Objective:** Protects open-source attribution provenance under MIT License.
-- **Verification Rule:** Rejects any commit, pull request, or modification that attempts to strip copyright notices, false-claim authorship, or remove provenance headers referencing Thế Vị (@TeeVee998).
-- **Remediation:** Restore license headers and canonical notice in `LICENSE` and `NOTICE`.
-
-### Gate 1: UTF-8 No BOM Encoding Integrity
-- **Objective:** Eliminates cross-platform file encoding corruption between Windows, macOS, and Linux CI/CD runners.
-- **Verification Rule:** Inspects raw bytes of all text files. Any occurrence of BOM bytes (`0xEF, 0xBB, 0xBF`) causes immediate failure.
-- **Remediation:** Run `python3 tools/verify_all.py --fix-bom` to strip BOM bytes automatically.
-
-### Gate 2: Path Portability
-- **Objective:** Guarantees test scripts and tooling execute seamlessly across team developer workstations, Docker containers, and CI pipelines.
-- **Verification Rule:** Regex scans for machine-specific path roots (`/Users/`, `/home/`, `C:\`, `D:\`).
-- **Remediation:** Replace absolute paths with dynamic workspace resolution (`Path(__file__).resolve().parent.parent` or `resolve_target_repo()`).
-
-### Gate 3: Clean POM & Flat Architecture
-- **Objective:** Enforces clean separation of concerns. Test scripts must contain solely business workflow actions, never DOM traversal.
-- **Verification Rule:** Prohibits raw CSS selectors, XPaths, or `findTestObject` inside `tests/` or `Scripts/`. All UI operations must be delegated to methods on Page Classes extending `BasePage`.
-- **Remediation:** Encapsulate locators and interaction logic inside dedicated Page Classes.
-
-### Gate 4: AI Documentation & Anti-Drift Linter
-- **Objective:** Prevents AI context drift where documentation refers to non-existent Page Classes or obsolete method signatures.
-- **Verification Rule:** Extracts all documented Page Classes and methods from `PROJECT_AI_GUIDE.md` and verifies their physical AST existence in the codebase.
-- **Remediation:** Run `python3 tools/lint_ai_docs.py` to identify drifts, then re-index via `python3 tools/repo_map.py`.
-
-### Gate 5: Temporary Files Blacklist
-- **Objective:** Maintains git hygiene and prevents polluting repositories with binary dumps or local IDE caches.
-- **Verification Rule:** Scans for prohibited extensions: `*.tmp`, `*.dump`, `*.log`, `*.orig`, `*.bak`, `.ruff_cache/`, `.mypy_cache/`.
-- **Remediation:** Add unignored patterns to `.gitignore` and delete temporary files.
-
-### Gate 6: Credential Security Sentinel
-- **Objective:** Prevents enterprise credential leaks (API tokens, database connection strings, private keys).
-- **Verification Rule:** High-entropy regex scanner detecting AWS secret keys, Bearer tokens, private RSA keys, and hardcoded passwords.
-- **Remediation:** Move credentials to environment variables or `.env` (ensuring `.env` is listed in `.gitignore`).
-
-### Gate 7: Static Defect & Fake-Pass Sentinel
-- **Objective:** Eliminates "fake passes" created by AI code generation (tests that pass trivially without asserting anything).
-- **Verification Rule:**
-  - Flags tests containing 0 assertions.
-  - Flags empty catch blocks (`except Exception: pass`) swallowing failure exceptions.
-  - Flags hardcoded sleeps (`sleep(5000)`, `Thread.sleep(5000)`).
-  - Flags unawaited Playwright assertions (`expect(el).toBeVisible()` without `await`).
-- **Remediation:** Add meaningful assertions; replace sleeps with smart waits (`waitForLoadState('networkidle')`, element visibility checks).
-
-### Gate 8: Assertion Sensitivity & Syntactic Mutation Sentinel
-- **Objective:** Guarantees assertions are sensitive enough to catch real defects, not tautological (always-true) expressions.
-- **Verification Rule:** Injects syntactic mutations (reversing comparison operators `==` to `!=`, swapping boolean constants, altering return values). Requires Mutation Score >= 80%.
-- **Remediation:** Run `python3 tools/micro_mutator.py --strict` to inspect surviving mutants and tighten test assertions.
-
-### Gate 9: Tier-2 Skill Routing & Collision Guard
-- **Objective:** Prevents AI agent prompt confusion caused by overlapping skill trigger descriptions.
-- **Verification Rule:** Computes pairwise cosine similarity between all skill `SKILL.md` description fields. Similarity must remain strictly < 0.75.
-- **Remediation:** Differentiate skill descriptions using the standardized formula `[Chức năng] + Use when [ngữ cảnh]` (<= 350 characters).
+## 🔍 Chi Tiết Tiêu Chuẩn Từng Cổng & Cách Khắc Phục
+
+### Gate 0: Bảo Toàn Tác Quyền & Giấy Phép MIT
+- **Mục tiêu:** Bảo vệ nguồn gốc xuất xứ và tuân thủ điều khoản Attribution bắt buộc của Giấy phép MIT.
+- **Quy tắc kiểm tra:** Chặn đứng mọi hành vi xóa bỏ notice bản quyền, mạo nhận quyền tác giả hoặc gỡ tên tác giả Thế Vị (@TeeVee998).
+- **Cách khắc phục:** Khôi phục lại header bản quyền và thông tin nguồn gốc trong `LICENSE` và `NOTICE`.
+
+### Gate 1: Chuẩn Mã Hóa UTF-8 No BOM
+- **Mục tiêu:** Tránh lỗi vỡ font hoặc xung đột đọc file giữa Windows, macOS và môi trường Linux CI/CD.
+- **Quy tắc kiểm tra:** Quét raw bytes của tất cả file văn bản. Báo lỗi ngay nếu xuất hiện ký tự BOM (`0xEF, 0xBB, 0xBF`).
+- **Cách khắc phục:** Chạy `python3 tools/verify_all.py --fix-bom` để công cụ tự động dọn sạch byte BOM.
+
+### Gate 2: Đường Dẫn Linh Hoạt (Path Portability)
+- **Mục tiêu:** Đảm bảo code test và script công cụ chạy được trên mọi máy dev, Docker container và CI runner.
+- **Quy tắc kiểm tra:** Dùng regex quét tìm các path gắn cứng theo máy cục bộ (`/Users/`, `/home/`, `C:\`, `D:\`).
+- **Cách khắc phục:** Dùng đường dẫn tương đối phân giải từ thư mục gốc (`Path(__file__).resolve().parent.parent` hoặc `resolve_target_repo()`).
+
+### Gate 3: Kiến Trúc Clean POM Phẳng
+- **Mục tiêu:** Phân định ranh giới rõ ràng: file test chỉ chứa các bước nghiệp vụ, tuyệt đối không chọc thẳng vào DOM.
+- **Quy tắc kiểm tra:** Cấm selector thô (CSS selector, XPath, `findTestObject`) trong thư mục `tests/` hoặc `Scripts/`. Thao tác UI phải thông qua hàm của Page Class kế thừa `BasePage`.
+- **Cách khắc phục:** Đưa locator và thao tác click/nhập liệu vào đúng Page Class tương ứng.
+
+### Gate 4: Chống Bịa Đặt Tài Liệu AI (Anti-Drift Linter)
+- **Mục tiêu:** Tránh hiện tượng AI bị "ảo giác" (hallucination), đọc tài liệu cũ rồi gọi các Page Class hoặc hàm không hề tồn tại trong code.
+- **Quy tắc kiểm tra:** Quét toàn bộ Page Class và method được ghi trong `PROJECT_AI_GUIDE.md`, kiểm tra xem chúng có tồn tại thật trong AST codebase hay không.
+- **Cách khắc phục:** Chạy `python3 tools/lint_ai_docs.py` để tìm dòng sai lệch, sau đó chạy `python3 tools/repo_map.py` để đồng bộ lại bản đồ code.
+
+### Gate 5: Chặn File Rác Lọt Vào Git
+- **Mục tiêu:** Giữ git index luôn sạch sẽ, không bị phình dung lượng bởi rác build hoặc cache IDE.
+- **Quy tắc kiểm tra:** Quét các đuôi file cấm: `*.tmp`, `*.dump`, `*.log`, `*.orig`, `*.bak`, `.ruff_cache/`, `.mypy_cache/`.
+- **Cách khắc phục:** Khai báo các mẫu file này vào `.gitignore` và xóa bỏ các file tạm hiện có trong repo.
+
+### Gate 6: Quét Mật Khẩu & Token Bí Mật (Secret Sentinel)
+- **Mục tiêu:** Chống rò rỉ thông tin nhạy cảm của dự án (API token, chuỗi kết nối DB, private key, mật khẩu).
+- **Quy tắc kiểm tra:** Quét regex entropy cao để phát hiện chuỗi khóa bí mật AWS, Bearer token, RSA key và mật khẩu bị gán cứng.
+- **Cách khắc phục:** Chuyển sang dùng biến môi trường hoặc file `.env` (nhớ thêm `.env` vào `.gitignore`).
+
+### Gate 7: Bắt Lỗi Tĩnh & Test Pass Ảo
+- **Mục tiêu:** Loại bỏ triệt để các bài test do AI viết chạy xanh nhưng thực chất là vô dụng:
+- **Quy tắc kiểm tra:**
+  - Bắt các bài test có **0 câu lệnh assert**.
+  - Bắt các khối try-catch rỗng (`except Exception: pass`) nuốt mất lỗi khi test fail.
+  - Bắt các lệnh sleep cứng (`sleep(5000)`, `Thread.sleep(5000)`).
+  - Bắt assertion của Playwright bị quên `await` (`expect(el).toBeVisible()` thiếu `await`).
+- **Cách khắc phục:** Bổ sung assert thực tế; thay toàn bộ `sleep` cố định bằng smart wait (`waitForLoadState('networkidle')`, kiểm tra element hiển thị).
+
+### Gate 8: Đo Độ Nhạy Của Assert (Micro-Mutation Testing)
+- **Mục tiêu:** Đảm bảo các câu lệnh assert có giá trị kiểm thử thật sự, không phải là biểu thức "luôn luôn đúng" (tautology).
+- **Quy tắc kiểm tra:** Tự động tiêm các đột biến cú pháp (đổi `==` thành `!=`, đảo boolean `True` sang `False`, thay giá trị return). Yêu cầu test phải bắt trượt và diệt được ít nhất 80% đột biến (Mutation Score $\ge 80\%$).
+- **Cách khắc phục:** Chạy `python3 tools/micro_mutator.py --strict` để xem mutant nào còn sống sót và siết chặt lại assertion.
+
+### Gate 9: Điều Phối Kỹ Năng Tránh Trùng Lặp
+- **Mục tiêu:** Tránh việc AI kích hoạt nhầm kỹ năng do mô tả trong các file `SKILL.md` bị chồng chéo nhau.
+- **Quy tắc kiểm tra:** Tính độ tương đồng cosine giữa phần mô tả của từng cặp kỹ năng. Yêu cầu chỉ số tương đồng phải $< 0.75$.
+- **Cách khắc phục:** Viết lại mô tả kỹ năng theo công thức chuẩn: `[Tính năng] + Dùng khi [ngữ cảnh cụ thể]` (tối đa 350 ký tự).
 
 ---
 
-## 🚀 Execution & CI/CD Integration
+## 🚀 Cách Chạy & Tích Hợp Vào CI/CD
 
-### Run Locally:
+### Chạy Cục Bộ Trên Máy:
 ```bash
-# Verify all 10 Gates on current repository
+# Kiểm định toàn bộ 10 Cổng trên repo hiện tại
 python3 tools/verify_all.py
 
-# Verify target project from Hub
-python3 tools/verify_all.py --target /path/to/project
+# Kiểm định dự án test mục tiêu từ Hub
+python3 tools/verify_all.py --target /duong-dan/toi/du-an-test
 
-# Output as JUnit XML for CI/CD reporting
+# Xuất kết quả ra file JUnit XML để CI/CD đọc
 python3 tools/verify_all.py --format junit --output reports/dod_gates.xml
 ```
 
-### GitHub Actions Pipeline (`.github/workflows/verify.yml`):
+### Đường Ống GitHub Actions (`.github/workflows/verify.yml`):
 ```yaml
 name: Synapse Hub 10 DoD Quality Gates
 on: [push, pull_request]

package/docs/research/agent_skill_training_analysis.md

@@ -1311,7 +1311,7 @@ sequenceDiagram
 - **Objective**: Deploy lifelong skill libraries, textual gradient optimization, and standardized benchmarks.
 - **Deliverables**:
   1. *SkillVault Lifelong POM Library*: Deploy `.synapse/skill_vault.db` and `tools/skill_vault.py` for indexing verified Page Class methods and interaction primitives.
-  2. *TextGrad Mutation-Loss Optimizer*: Create `tools/optimize_prompt_textgrad.py` to optimize test generation prompts using surviving mutant loss reports.
+  2. *TextGrad Mutation-Loss Optimizer*: Create `tools/textgrad_mutation_optimizer.py` to optimize test generation prompts using surviving mutant loss reports.
   3. *Synapse-QA-Bench (BFCL-Style Benchmark)*: Expand `tools/agent_canary.py` to benchmark all 90 tools on AST argument matching and irrelevance detection.
   4. *Modern Skill Packaging*: Add `agentskills.io` metadata and multi-host adapters to support `npx skills add TeeVee998/Synapse-Hub`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synapse-hub",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Enterprise AI Agent Intelligence Hub & Autonomous Skill Network",
   "publishConfig": {
     "access": "public"

package/skills_manifest.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "name": "Enterprise Agent Skills Hub",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "description": "Unified Catalog of 51 Specialized Skills for Autonomous AI Agents in Enterprise Software Quality Engineering, Performance, and Architecture.",
   "totalSkills": 51,
   "categories": {

package/synapse.config.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://raw.githubusercontent.com/TeeVee998/Synapse-Hub/main/docs/schemas/synapse.config.schema.json",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "quality_gates": {
     "mutation_min_score": 80,
     "gates": {

package/templates/ai_bridges/CLAUDE.md

@@ -46,6 +46,7 @@ In accordance with the MIT License, the original copyright notice crediting **Th
 5. **Pragmatic Communication Protocol:**
    - Conversational responses, explanation, and telemetry MUST be in Vietnamese.
    - All codebase assets, test scripts, Page Classes, docstrings, and commits MUST remain strictly in English.
+   - English-First Document Ingestion: When reading bilingual docs (e.g. ARCHITECTURE.en.md vs ARCHITECTURE.md), always read the English version (*.en.md) to save 50–65% BPE tokens.
 
 6. **Lean Senior Dev Protocol (The 7-Rung Ladder & YAGNI):**
    - The best code is the code never written. Solve the whole problem with the least new code.

package/tools/__init__.py

@@ -14,7 +14,7 @@ Domain Packages:
 - tools.mcp: Model Context Protocol servers (core QA and Excel manipulation).
 """
 
-__version__ = "3.0.0"
+__version__ = "3.0.1"
 __author__ = "Thế Vị (@TeeVee998)"
 
 # Expose domain packages

package/tools/auto_heal_reflexion.py

@@ -67,6 +67,14 @@ class ClosedLoopHealer:
             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 "hydration" in err_lower or "did not match" in err_lower:
+            return "Reflection: React/Next.js hydration mismatch caused DOM element to re-render. Adjustment: Ensure DOM is interactive and wait for loadState('domcontentloaded') before query."
+        elif "shadow" in err_lower or "shadowroot" in err_lower:
+            return "Reflection: Target element encapsulated inside closed Shadow DOM boundary. Adjustment: Pierce Shadow DOM via locator piercing syntax or evaluate via CDP."
+        elif "iframe" in err_lower or "frame" in err_lower:
+            return "Reflection: Target element resides inside cross-origin iframe container. Adjustment: Switch context to frameLocator('iframe#...') before clicking."
+        elif any(auth_err in err_lower for auth_err in ("401", "403", "unauthorized", "forbidden", "token expired")):
+            return "Reflection: Session auth token or cookie expired mid-test. Adjustment: Refresh storageState or trigger silent token re-authentication via API fixture."
         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:

package/tools/browser_helpers.js

@@ -13,7 +13,7 @@
 (function () {
   'use strict';
 
-  if (window.__qa && window.__qa.__version === '3.0.0') {
+  if (window.__qa && window.__qa.__version === '3.0.1') {
     return window.__qa;
   }
 
@@ -47,7 +47,7 @@
   }
 
   const qa = {
-    __version: '3.0.0',
+    __version: '3.0.1',
 
     /**
      * 1. Smart Action Batching

package/tools/bump_version.py

@@ -195,25 +195,25 @@ def git_commit_and_tag(version: str, push: bool = False):
         push: If True, pushes the commit and tag to git remote origin.
     """
     print(f"\n📦 Creating Git commit and tag v{version}...")
-    subprocess.run(["git", "add", "-A"], cwd=REPO_ROOT, check=True)
-    subprocess.run(["git", "commit", "-m", f"chore(release): bump version to v{version}"], cwd=REPO_ROOT, check=True)
-    subprocess.run(["git", "tag", f"v{version}"], cwd=REPO_ROOT, check=True)
+    subprocess.run(["git", "add", "-u"], cwd=REPO_ROOT, check=True, timeout=30.0)
+    subprocess.run(["git", "commit", "-m", f"chore(release): bump version to v{version}"], cwd=REPO_ROOT, check=True, timeout=30.0)
+    subprocess.run(["git", "tag", f"v{version}"], cwd=REPO_ROOT, check=True, timeout=30.0)
     print(f"✅ Git commit and tag v{version} created.")
 
     if push:
         print("🚀 Pushing commit and tags to remote origin...")
-        res = subprocess.run(["git", "branch", "--show-current"], cwd=REPO_ROOT, stdout=subprocess.PIPE, text=True)
+        res = subprocess.run(["git", "branch", "--show-current"], cwd=REPO_ROOT, stdout=subprocess.PIPE, text=True, timeout=30.0)
         cur_branch = res.stdout.strip()
         if cur_branch == "develop":
             try:
-                subprocess.run(["git", "checkout", "main"], cwd=REPO_ROOT, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
-                subprocess.run(["git", "merge", "develop", "--ff-only"], cwd=REPO_ROOT, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
-                subprocess.run(["git", "checkout", "develop"], cwd=REPO_ROOT, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
-                subprocess.run(["git", "push", "origin", "develop", "main", "--tags"], cwd=REPO_ROOT, check=True)
+                subprocess.run(["git", "checkout", "main"], cwd=REPO_ROOT, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=30.0)
+                subprocess.run(["git", "merge", "develop", "--ff-only"], cwd=REPO_ROOT, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=30.0)
+                subprocess.run(["git", "checkout", "develop"], cwd=REPO_ROOT, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=30.0)
+                subprocess.run(["git", "push", "origin", "develop", "main", "--tags"], cwd=REPO_ROOT, check=True, timeout=60.0)
             except Exception:
-                subprocess.run(["git", "push", "origin", "HEAD", "--tags"], cwd=REPO_ROOT, check=True)
+                subprocess.run(["git", "push", "origin", "HEAD", "--tags"], cwd=REPO_ROOT, check=True, timeout=60.0)
         else:
-            subprocess.run(["git", "push", "origin", "HEAD", "--tags"], cwd=REPO_ROOT, check=True)
+            subprocess.run(["git", "push", "origin", "HEAD", "--tags"], cwd=REPO_ROOT, check=True, timeout=60.0)
         print("✅ Remote origin synchronized.")
 
 def main():
@@ -271,16 +271,17 @@ def main():
     update_file("tools/mcp_excel_server.py", r'(SERVER_VERSION\s*=\s*")[^"]+(")', rf"\g<1>{new_ver}\g<2>", args.dry_run)
     update_file("tools/mcp_excel_server.py", r'("serverInfo":\s*\{[^}]*"version":\s*")[^"]+(")', rf"\g<1>{new_ver}\g<2>", args.dry_run)
 
-    # 8. docs/ARCHITECTURE.md
+    # 8. docs/ARCHITECTURE.md & docs/ARCHITECTURE.en.md
     update_file("docs/ARCHITECTURE.md", r'(>\s*\*\*Version:\*\*\s*`)[^`]+(`)', rf"\g<1>{new_ver}\g<2>", args.dry_run)
+    update_file("docs/ARCHITECTURE.en.md", r'(>\s*\*\*Version:\*\*\s*`)[^`]+(`)', rf"\g<1>{new_ver}\g<2>", args.dry_run)
 
     # 9. README.md & README.en.md (Documentation headings and badges)
-    update_file("README.md", r'(Phiên bản Hub:\*\*\s*`v)[^`]+(`)', rf"\g<1>{new_ver}\g<2>", args.dry_run)
-    update_file("README.md", r'(Hub Version:\*\*\s*`v)[^`]+(`)', rf"\g<1>{new_ver}\g<2>", args.dry_run)
+    update_file("README.md", r'(Phiên bản(?: Hub)?:\*\*\s*`v)[^`]+(`)', rf"\g<1>{new_ver}\g<2>", args.dry_run)
+    update_file("README.md", r'((?:Hub )?Version:\*\*\s*`v)[^`]+(`)', rf"\g<1>{new_ver}\g<2>", args.dry_run)
     update_file("README.md", r'(Intelligence Core v)[^")\]]+', rf"\g<1>{new_ver}", args.dry_run)
     update_file("README.md", r'(rev:\s*v)[0-9]+\.[0-9]+\.[0-9]+', rf"\g<1>{new_ver}", args.dry_run)
     update_file("README.md", r'(Synapse Hub \(Core v)[0-9]+\.[0-9]+\.[0-9]+(\))', rf"\g<1>{new_ver}\g<2>", args.dry_run)
-    update_file("README.en.md", r'(Hub Version:\*\*\s*`v)[^`]+(`)', rf"\g<1>{new_ver}\g<2>", args.dry_run)
+    update_file("README.en.md", r'((?:Hub )?Version:\*\*\s*`v)[^`]+(`)', rf"\g<1>{new_ver}\g<2>", args.dry_run)
     update_file("README.en.md", r'(Intelligence Core v)[^")\]]+', rf"\g<1>{new_ver}", args.dry_run)
     update_file("README.en.md", r'(rev:\s*v)[0-9]+\.[0-9]+\.[0-9]+', rf"\g<1>{new_ver}", args.dry_run)
     update_file("README.en.md", r'(Synapse Hub \(Core v)[0-9]+\.[0-9]+\.[0-9]+(\))', rf"\g<1>{new_ver}\g<2>", args.dry_run)