synapse-hub 2.7.0 → 3.0.1

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

@@ -0,0 +1,115 @@
+# 🛡️ Tiêu Chuẩn 10 Cổng Chất Lượng DoD (Definition of Done)
+
+[🇻🇳 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.
+
+---
+
+## 📋 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). |
+
+---
+
+## 🔍 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ự).
+
+---
+
+## 🚀 Cách Chạy & Tích Hợp Vào CI/CD
+
+### Chạy Cục Bộ Trên Máy:
+```bash
+# Kiểm định toàn bộ 10 Cổng trên repo hiện tại
+python3 tools/verify_all.py
+
+# Kiểm định dự án test mục tiêu từ Hub
+python3 tools/verify_all.py --target /duong-dan/toi/du-an-test
+
+# Xuất kết quả ra file JUnit XML để CI/CD đọc
+python3 tools/verify_all.py --format junit --output reports/dod_gates.xml
+```
+
+### Đường Ống GitHub Actions (`.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/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": "2.7.0",
+  "version": "3.0.1",
   "description": "Enterprise AI Agent Intelligence Hub & Autonomous Skill Network",
   "publishConfig": {
     "access": "public"

package/scripts/package_dist.py

@@ -37,6 +37,7 @@ EXCLUDE_DIRS = {
     "__pycache__",
     ".pytest_cache",
     ".mypy_cache",
+    ".ruff_cache",
     ".idea",
     ".vscode",
     "agent_qa.egg-info",
@@ -280,7 +281,7 @@ def create_package(output_zip: str = "agent-skills.zip") -> Path:
                 total_size += full_path.stat().st_size
 
     zip_size_mb = out_path.stat().st_size / (1024 * 1024)
-    print(f"✅ Packaging complete:")
+    print("✅ Packaging complete:")
     print(f"   • Total files packaged : {total_files}")
     print(f"   • Uncompressed size    : {total_size / (1024 * 1024):.2f} MB")
     print(f"   • Archive size (.zip)  : {zip_size_mb:.2f} MB")

package/skills_manifest.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "name": "Enterprise Agent Skills Hub",
-  "version": "2.7.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": {
@@ -492,7 +492,7 @@
       "name": "Senior Code Review",
       "category": "architecture_and_analysis",
       "path": ".agents/skills/senior-code-review/SKILL.md",
-      "summary": "Quality review of a code change: verify logic correctness, security boundaries, real concurrency/load, missing test coverage, execution speed, and eliminate bloat.",
+      "summary": "Review code changes across logic, security, concurrency, and test coverage. Use when conducting pull request reviews, diff inspections, or auditing commit changes before merge.",
       "version": "1.0.0"
     },
     {
@@ -500,7 +500,7 @@
       "name": "Repo Quality Audit",
       "category": "architecture_and_analysis",
       "path": ".agents/skills/repo-quality-audit/SKILL.md",
-      "summary": "Quality audit of a whole codebase: bugs, security risks, concurrency and scale bottlenecks, missing test coverage, and code bloat with 'Fix this first' priority.",
+      "summary": "Comprehensive codebase quality audit covering bugs, security, bottlenecks, and bloat. Use when auditing an entire project, evaluating repository health, or prioritizing technical debt.",
       "version": "1.0.0"
     },
     {
@@ -508,7 +508,7 @@
       "name": "Technical Debt Harvester",
       "category": "architecture_and_analysis",
       "path": ".agents/skills/technical-debt-harvester/SKILL.md",
-      "summary": "Harvest shortcut: comments into a tracked debt ledger so deliberate compromises do not rot into forgotten tech debt.",
+      "summary": "Harvest shortcut: comments into a tracked technical debt ledger. Use when auditing code compromises, tracking deferred refactorings, or scanning for shortcut markers.",
       "version": "1.0.0"
     },
     {
@@ -516,7 +516,7 @@
       "name": "Lean Impact Scoreboard",
       "category": "architecture_and_analysis",
       "path": ".agents/skills/lean-impact-scoreboard/SKILL.md",
-      "summary": "Display the measured impact scoreboard (code reduction %, token optimization %, cost reduction %, test rigor) from lean engineering benchmarks.",
+      "summary": "Display empirical impact scoreboards (code reduction, token savings, mutation rigor). Use when reviewing lean engineering benchmarks, token throughput, or reporting quality metrics.",
       "version": "1.0.0"
     },
     {
@@ -588,7 +588,7 @@
       "name": "Review Spec (Goldfish Protocol)",
       "category": "architecture_and_analysis",
       "path": ".agents/skills/review-spec/SKILL.md",
-      "summary": "Zero-context stress test and quality review of test specifications, user stories, BDD feature files, and acceptance criteria before code generation begins.",
+      "summary": "Stress-test specifications, user stories, and BDD feature files with zero-context rigor. Use when reviewing requirements, user stories, or acceptance criteria before code generation.",
       "version": "1.0.0"
     }
   ]

package/synapse.config.json

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

package/templates/ai_bridges/CLAUDE.md

@@ -1,6 +1,6 @@
 # CLAUDE.md — Synapse-Hub Guidelines for Claude Code
 
-> **Author & Creator:** Thế Vị (@TeeVee998) <https://github.com/TeeVee998/Synapse-Hub>  
+> **Author & Creator:** Thế Vị (@TeeVee998) <https://github.com/TeeVee998/Synapse-Hub>
 > **License:** MIT License (Mandatory Attribution Preservation)
 
 <!-- ============================================================================== -->
@@ -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/templates/ai_bridges/copilot-instructions.md

@@ -6,8 +6,8 @@
 <!-- ============================================================================== -->
 
 
-> **Project:** Synapse-Hub Enterprise QA Automation  
-> **Author:** Thế Vị (@TeeVee998) — MIT License  
+> **Project:** Synapse-Hub Enterprise QA Automation
+> **Author:** Thế Vị (@TeeVee998) — MIT License
 
 ## Coding Invariants
 - Enforce Clean Page Object Model (POM) with Flat Architecture.

package/tools/__init__.py

@@ -4,12 +4,29 @@ Synapse Hub — Enterprise AI Agent Quality Engineering & Automated Testing Tool
 Author: Thế Vị (@TeeVee998)
 Repository: https://github.com/TeeVee998/Synapse-Hub
 License: MIT
+
+Domain Packages:
+- tools.core: Execution engines, 10 DoD Quality Gates, setup, CLI, AST maps.
+- tools.lint: Static code defect, encoding, author integrity, and AI doc sentinels.
+- tools.report: HTML dashboards, spreadsheets, telemetry correlation, and metrics.
+- tools.heal: Locator healing, episodic Reflexion memory, and agentless patching.
+- tools.perf: Flakiness detection, JMeter plans, BFCL benchmarks, and matrix sharding.
+- tools.mcp: Model Context Protocol servers (core QA and Excel manipulation).
 """
 
-__version__ = "2.7.0"
+__version__ = "3.0.1"
 __author__ = "Thế Vị (@TeeVee998)"
 
+# Expose domain packages
+from tools import core, heal, lint, mcp, perf, report  # noqa: F401
+
 __all__ = [
+    "core",
+    "heal",
+    "lint",
+    "mcp",
+    "perf",
+    "report",
     "verify_all",
     "infer_linter",
     "micro_mutator",

package/tools/_openapi_parser.py

@@ -14,7 +14,7 @@ value test scenario synthesis across API testing tools.
 import os
 import sys
 import json
-from typing import Dict, Any, List, Optional, Tuple
+from typing import Dict, Any, List
 
 if hasattr(sys.stdout, 'reconfigure'):
     try:

package/tools/agent_canary.py

@@ -85,15 +85,20 @@ class OverlayInterceptVector(MutationVector):
         healed = False
         patch = None
         if os.path.exists(CACHE_DB):
-            conn = sqlite3.connect(CACHE_DB)
-            cur = conn.cursor()
-            cur.execute("SELECT groovy_patch FROM healing_cache WHERE error_signature LIKE '%ElementClickIntercepted%' LIMIT 1")
-            row = cur.fetchone()
-            conn.close()
-            if row:
-                patch = row[0]
-                if "click" in patch and ("JavascriptExecutor" in patch or "jsClick" in patch or "clickJS" in patch):
-                    healed = True
+            try:
+                conn = sqlite3.connect(CACHE_DB)
+                try:
+                    cur = conn.cursor()
+                    cur.execute("SELECT groovy_patch FROM healing_cache WHERE error_signature LIKE '%ElementClickIntercepted%' LIMIT 1")
+                    row = cur.fetchone()
+                    if row:
+                        patch = row[0]
+                        if "click" in patch and ("JavascriptExecutor" in patch or "jsClick" in patch or "clickJS" in patch):
+                            healed = True
+                finally:
+                    conn.close()
+            except sqlite3.Error:
+                healed = False
 
         elapsed_ms = (time.time() - start) * 1000
         return {
@@ -121,15 +126,20 @@ class LocatorDriftVector(MutationVector):
         healed = False
         patch = None
         if os.path.exists(CACHE_DB):
-            conn = sqlite3.connect(CACHE_DB)
-            cur = conn.cursor()
-            cur.execute("SELECT groovy_patch FROM healing_cache WHERE error_signature LIKE '%StaleElement%' LIMIT 1")
-            row = cur.fetchone()
-            conn.close()
-            if row:
-                patch = row[0]
-                if "retry" in patch.lower() or "for (" in patch or "findElement" in patch:
-                    healed = True
+            try:
+                conn = sqlite3.connect(CACHE_DB)
+                try:
+                    cur = conn.cursor()
+                    cur.execute("SELECT groovy_patch FROM healing_cache WHERE error_signature LIKE '%StaleElement%' LIMIT 1")
+                    row = cur.fetchone()
+                    if row:
+                        patch = row[0]
+                        if "retry" in patch.lower() or "for (" in patch or "findElement" in patch:
+                            healed = True
+                finally:
+                    conn.close()
+            except sqlite3.Error:
+                healed = False
 
         elapsed_ms = (time.time() - start) * 1000
         return {
@@ -201,12 +211,14 @@ class DataCollisionVector(MutationVector):
             if os.path.exists(CACHE_DB):
                 try:
                     conn = sqlite3.connect(CACHE_DB)
-                    cur = conn.cursor()
-                    cur.execute("SELECT groovy_patch FROM healing_cache WHERE error_signature LIKE '%Duplicate_Code%'")
-                    row = cur.fetchone()
-                    conn.close()
-                    if row and ("uniqueCode" in row[0] or "currentTimeMillis" in row[0]):
-                        healed = True
+                    try:
+                        cur = conn.cursor()
+                        cur.execute("SELECT groovy_patch FROM healing_cache WHERE error_signature LIKE '%Duplicate_Code%'")
+                        row = cur.fetchone()
+                        if row and ("uniqueCode" in row[0] or "currentTimeMillis" in row[0]):
+                            healed = True
+                    finally:
+                        conn.close()
                 except sqlite3.Error:
                     healed = False
 
@@ -247,7 +259,7 @@ class BomContaminationVector(MutationVector):
             # 1. Inject BOM
             with open(test_file, "wb") as f:
                 f.write(b"\xef\xbb\xbf// Test BOM contamination\n")
-            
+
             # 2. Detect BOM
             with open(test_file, "rb") as f:
                 header = f.read(3)
@@ -261,7 +273,7 @@ class BomContaminationVector(MutationVector):
                 cleaned = raw[3:]
                 with open(test_file, "wb") as f:
                     f.write(cleaned)
-                
+
                 # Re-verify
                 with open(test_file, "rb") as f:
                     if f.read(3) != b"\xef\xbb\xbf":
@@ -297,7 +309,7 @@ class MachinePathLeakVector(MutationVector):
         sample_path = "C:\\Workspace\\Project\\tools\\verify_all.py"
         detected = "C:\\" in sample_path or sample_path.startswith("/")
         healed = False
-        
+
         # Simulate relative path conversion
         relative_path = os.path.relpath(os.path.join(REPO_ROOT, "tools", "verify_all.py"), REPO_ROOT)
         if not relative_path.startswith("/") and "C:" not in relative_path:
@@ -328,7 +340,7 @@ class RawXPathInScriptVector(MutationVector):
         start = time.time()
         sample_bad_script = 'WebUI.click(findTestObject("Object Repository/button_Save"))'
         detected = "findTestObject" in sample_bad_script or "By.xpath" in sample_bad_script
-        
+
         # Self-healing translation: convert to Clean POM method call
         healed_script = "CommonCategoryPage.saveCareer(careerCode, careerName)"
         healed = "findTestObject" not in healed_script and "CommonCategoryPage" in healed_script
@@ -393,7 +405,7 @@ class CanaryArena:
         print(f"{BOLD}{CYAN}            (Dry-Run Simulation Benchmark - Heuristic Evaluation)                 {RESET}")
         print(f"{BOLD}{CYAN}======================================================================{RESET}")
         print(f"Target Repository : {REPO_ROOT}")
-        print(f"Evaluation Mode   : Isolated Memory Sandbox & Offline Local Resolvers")
+        print("Evaluation Mode   : Isolated Memory Sandbox & Offline Local Resolvers")
         print(f"Total Vectors     : {len(self.vectors)} Failure Vectors")
         print(f"Timestamp         : {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}\n")
 
@@ -442,7 +454,7 @@ class CanaryArena:
         print(f"  Autonomous Healing Rate   : {GREEN if resolution_rate == 100 else RED}{resolution_rate:.1f}% ({healed_count}/{len(self.vectors)}){RESET}")
         print(f"  Mean Time To Repair (MTTR): {GREEN}{avg_mttr:.2f} ms{RESET} per incident")
         print(f"  Total Token Consumption   : {GREEN}{total_tokens} tokens{RESET} (100% Offline Local)")
-        
+
         # Run verify_all gate
         print(f"\n{BOLD}[POST-BENCHMARK DoD INTEGRITY CHECK]{RESET}")
         verify_script = os.path.join(SCRIPT_DIR, "verify_all.py")

package/tools/agentless_patcher.py

@@ -127,8 +127,8 @@ class AgentlessPatcher:
                     if method_name == "unknown_method":
                         # Scan backwards for enclosing def/function
                         for idx in range(line_no - 1, -1, -1):
-                            l = lines[idx]
-                            fn_m = re.search(r'(?:def|async\s+function|function|public\s+def|\b([a-zA-Z0-9_]+)\s*\([^)]*\)\s*\{?)\s*([a-zA-Z0-9_]+)?', l)
+                            line_content = lines[idx]
+                            fn_m = re.search(r'(?:def|async\s+function|function|public\s+def|\b([a-zA-Z0-9_]+)\s*\([^)]*\)\s*\{?)\s*([a-zA-Z0-9_]+)?', line_content)
                             if fn_m:
                                 method_name = fn_m.group(2) or fn_m.group(1) or "enclosing_scope"
                                 break

package/tools/analyze_project.py

@@ -19,10 +19,8 @@ Generates & Updates In-Place inside the Target Project:
 
 import os
 import sys
-import json
 import argparse
 from datetime import datetime
-from pathlib import Path
 
 # Enforce UTF-8 stdout encoding for Windows console compatibility
 if hasattr(sys.stdout, 'reconfigure'):
@@ -232,9 +230,9 @@ def run_full_analysis(target_repo):
     print(f"  In-Project Report Path  : {report_in_root if os.path.abspath(target_repo).lower() != os.path.abspath(HUB_ROOT).lower() else report_in_reports}")
     if os.path.abspath(target_repo).lower() != os.path.abspath(HUB_ROOT).lower():
         print(f"  {YELLOW}💡 Post-Analysis Action: Push updated files to Git:{RESET}")
-        print(f"     git add PROJECT_HEALTH_REPORT.md repo_map.txt")
-        print(f"     git commit -m \"docs(audit): update project health report and AST repo map\"")
-        print(f"     git push origin <branch>")
+        print("     git add PROJECT_HEALTH_REPORT.md repo_map.txt")
+        print("     git commit -m \"docs(audit): update project health report and AST repo map\"")
+        print("     git push origin <branch>")
     print(f"{BOLD}{CYAN}======================================================================{RESET}\n")
 
     return 0 if gates_passed else 1

package/tools/api_drift_sentinel.py

@@ -11,7 +11,7 @@ import os
 import sys
 import json
 import argparse
-from typing import Dict, List, Any, Tuple
+from typing import Dict, List, Any
 
 # Enforce UTF-8 stdout encoding for Windows console compatibility
 if hasattr(sys.stdout, 'reconfigure'):
@@ -91,7 +91,7 @@ def compare_specs(old_spec: Dict[str, Any], new_spec: Dict[str, Any]) -> Dict[st
                             "path": f"{method.upper()} {path}",
                             "detail": f"Parameter '{p_name}' was changed from optional to required"
                         })
-                    
+
                     old_type = old_p.get("type") or old_p.get("schema", {}).get("type")
                     new_type = new_p.get("type") or new_p.get("schema", {}).get("type")
                     if old_type and new_type and old_type != new_type:
@@ -145,8 +145,8 @@ def generate_markdown_report(analysis: Dict[str, Any], old_path: str, new_path:
         f"- **Verdict:** {status_icon} (Health Score: `{analysis['contract_health_score']:.1f}%`)",
         "",
         "## Summary Metrics",
-        f"| Breaking Changes | Warnings | Compatible Additions |",
-        f"| :---: | :---: | :---: |",
+        "| Breaking Changes | Warnings | Compatible Additions |",
+        "| :---: | :---: | :---: |",
         f"| **{analysis['breaking_changes_count']}** | **{analysis['warnings_count']}** | **{analysis['additions_count']}** |",
         ""
     ]