synapse-hub 0.0.0-stage → 2.0.0

package/.agents/workflows/verify.md

@@ -0,0 +1,34 @@
+---
+name: verify
+description: Execute 8 Quality Gates to verify complete codebase integrity and enforce deterministic safety boundaries before handoff.
+trigger: /verify
+---
+
+# Workflow: verify
+
+## 1. Pre-execution Safety Hook (Mandatory Action Firewall)
+Before dispatching any UI interaction (`click`, `fill`, `submit`, `drop`) down to a live Playwright or CDP browser context, the command or code must be piped through `tools/safety_firewall.py --dry-run`:
+
+```bash
+# Verify single action safety clearance
+python tools/safety_firewall.py --action click --selector "<selector>" --text "<text>" --dry-run
+
+# Or pipe code snippet directly
+python tools/safety_firewall.py --code "page.click('<selector>')" --dry-run
+```
+*If safety firewall reports BLOCKED, execution halts immediately unless explicitly forced via `--force` or `ALLOW_DESTRUCTIVE=1`.*
+
+---
+
+## 2. Hard Quality Gates Verification (8 DoD Gates)
+Execute all 8 Quality Gates (UTF-8 No BOM, Path Portability, Clean POM, AI Docs Linter, Cleanup Blacklist, Credential Security, Infer Linter, and AST Micro-Mutation Testing):
+
+```bash
+python tools/verify_all.py
+```
+
+### Gate 8 Hard Rejection Rule:
+- Any new or updated test case must achieve an AST Mutation Score of **$\ge 80\%$** via `tools/micro_mutator.py`.
+- If `mutation_score < 80%`, the Gatekeeper strictly rejects the test suite (anti-tautology and anti-fake-pass policy).
+
+If any gate returns `FAIL`, pause execution and resolve defects completely before proceeding.

package/AGENTS.md

@@ -0,0 +1,115 @@
+# AGENTS.md — AI Agent Operating Standards & Protocols (Enterprise QA Hub)
+
+> **Scope:** Google Antigravity, Cursor, Claude Code, GitHub Copilot, Codex, Windsurf, and all AI/QA engineers working with automated testing suites.  
+> All rules below are **MANDATORY** and must be consistently enforced across all projects linking to this Hub.
+
+---
+
+## 0. CONTEXT-AWARE PRE-FLIGHT CONFIRMATION BLOCK (CODE & TEST ACTIONS ONLY)
+
+> **Trigger Condition:** This confirmation block is **MANDATORY ONLY** when executing technical tasks: generating code, editing test scripts, refactoring Page Classes, or executing runner tools.  
+> **Conversational Exemption:** For general discussions, architecture questions, planning, and Q&A, **DO NOT emit this block** — respond directly and concisely.  
+> **Dynamic Context:** The architecture and technique fields must adapt dynamically to the target project's `PROJECT_AI_GUIDE.md` (e.g., Playwright/TS, Clean POM/Groovy, Pytest/Python, REST API).
+
+```markdown
+> ✅ **[OK] Skill Hub Loaded:** `agent-skills` & Project Guide (`PROJECT_AI_GUIDE.md`)  
+> 🏛️ **[OK] Architecture:** <Target Architecture, e.g.: Clean POM / Flat Architecture>  
+> ⚡ **[OK] Target Tech:** <Actual Project Tech, e.g.: Playwright Live / API Mocking / Pytest>  
+> 🛡️ **[OK] Discipline:** Truth Anchor (No Fake Pass) + Zero-Token Error Blacklist  
+> 🎯 **[OK] Execution Plan:**  
+> • <Immediate Action Item 1>  
+> • <Immediate Action Item 2>  
+```
+
+---
+
+## 1. CORE ARCHITECTURE & CODE STANDARDS
+
+1. **Clean Page Object Model (POM):**
+   - Test scripts (`Scripts/` or `tests/`) must contain only business workflow method calls from Page Classes.
+   - **Strictly forbidden:** Raw XPaths, CSS selectors, or `findTestObject` calls inside test scripts.
+   - All locators and DOM operations must be encapsulated in Page Classes extending `BasePage`.
+
+2. **100% UTF-8 No BOM:**
+   - All files (`.groovy`, `.java`, `.ts`, `.py`, `.json`, `.md`, `.ps1`, `.sh`) **must not** contain UTF-8 BOM (`0xEF, 0xBB, 0xBF`).
+
+3. **Dynamic & Idempotent Test Data:**
+   - Always use randomized identifiers with timestamps/prefixes (e.g., `BasePage.uniqueCode("AUTO_")` or `DataGenerator`) to eliminate DB unique key collisions during parallel runs.
+   - Every creation test case must be paired with automated Teardown Cleanup.
+
+4. **Synchronization & Smart Wait:**
+   - Static sleeps (`Thread.sleep`) are strictly prohibited to prevent pipeline flakiness.
+   - Use dynamic smart waits: element visibility checks, Angular `zone.isStable()`, or Playwright `waitForLoadState('networkidle')`.
+
+---
+
+## 2. PLAYWRIGHT LIVE INTERACTION PROTOCOL
+
+1. **Mandatory 3-Stage Lifecycle:**
+   - **Stage 1 (Discovery):** Survey live DOM/AOM using headless browser. Never guess URLs or selector attributes.
+   - **Stage 2 (Script Creation):** Verify selectors on the live browser (100% hit rate under 200ms) before committing to Page Classes.
+   - **Stage 3 (In-Place Self-Healing):** When a test fails, pause the browser at the failure point to inspect and heal the locator; do not re-run from scratch.
+2. **Standard Configuration:** Pure headless mode, Full HD resolution `1920x1080`.
+
+---
+
+## 3. TRUTH ANCHOR & ZERO-HALLUCINATION DISCIPLINE
+
+1. **Truth Anchor (No Fake Pass):**
+   - If a test fails due to an application bug (AUT Bug), report the defect honestly. **Never relax assertion conditions, skip validation steps, or alter expected results to manufacture a fake pass.**
+2. **No Lazy Truncation:**
+   - Always output complete, directly executable code. Never use `// ... existing code ...` or `// TODO` in scripts.
+3. **Strict Credential Security:**
+   - Never commit raw plaintext passwords, secret tokens, or private keys to git. Always use environment variables or encrypted profiles.
+4. **Zero-Command Autonomous Proactivity & On-Demand Activation (Situation-Specific — Never Run Blindly):**
+   - The user must never be expected to remember or type CLI tool commands (`agent-qa setup`, `agent-qa analyze`, `verify_all.py`...).
+   - **On-Demand Principle:** Tools assigned to AI and Subagents are **NOT executed blindly or all at once**. They are activated **strictly on-demand** when the specific situation arises to save tokens and avoid execution overhead:
+     * New project / missing `PROJECT_AI_GUIDE.md` -> Autonomously run `tools/setup_project.py`.
+     * User asks to analyze / audit project -> Autonomously run `tools/analyze_project.py` and push to git.
+     * Test failure occurs in runner -> Autonomously run `tools/pinpoint_failure.py` / `auto_heal.py`.
+     * Breaking API change suspected -> Run `tools/api_drift_sentinel.py`.
+     * Parallel CI/CD runner setup needed -> Run `tools/matrix_sharder.py`.
+     * Verifying test assertion quality -> Run `tools/micro_mutator.py` (reject if Mutation Score < 80%).
+     * Before completing code tasks -> Autonomously run `tools/verify_all.py` (8 Quality Gates DoD).
+
+---
+
+## 4. MULTI-AGENT SWARM SYSTEM (AGENT ROLES)
+
+This repository defines specialized multi-agent profiles (configured in `.agents/agents/*.md`):
+
+1. **Lead QA Orchestrator (`orchestrator`):**
+   - Ingests requirements, bootstraps projects (`setup_project.py`), audits health (`analyze_project.py`), scans polyglot test suites (`omni_transpiler.py`), manages state (`project_state.py`), scopes tasks (`test_impact.py`), and serves MCP (`mcp_server.py`).
+2. **Live Interaction Explorer (`live-explorer`):**
+   - Utilizes Playwright live DOM/AOM probing, applies Anti-Flake Visual Masking (`smart_visual_masker.py`), injects network mocks (`network_mock_shield.py`), enforces Action Safety Firewall (`safety_firewall.py`), queries cached XPaths (`lookup_xpath.py`), and validates canvas (`visual_diff_canvas.py`).
+3. **Clean POM Crafter (`pom-crafter`):**
+   - Designs multi-language Page Classes, transpiles test frameworks (`omni_transpiler.py`, `universal_ir.py`), generates API mocks (`network_mock_shield.py`), checks API breaking changes (`api_drift_sentinel.py`), compiles stories to test suites (`generate_tc_from_story.py`), and maps methods (`repo_map.py`).
+4. **Test Execution Runner (`test-runner`):**
+   - Dispatches headless suites, balances parallel CI runners (`matrix_sharder.py`), triggers CI auto-recovery (`ci_healing_hook.py`), filters verbose logs (`distill_log.py`), and isolates failing lines (`pinpoint_failure.py`).
+5. **Failure Autopsy Analyst (`failure-analyst`):**
+   - Performs closed-loop diagnosis (`auto_heal.py`), auto-generates Jira/Markdown bug tickets with RCA (`bug_reporter.py`), executes CI self-healing & PR drafting (`ci_healing_hook.py`, `heal_pr_automator.py`), and resolves fixes from SQLite memory (`cache_resolver.py`).
+6. **Quality Gatekeeper & Sentinel (`quality-gatekeeper`):**
+   - Enforces 8 Quality Gates (`verify_all.py`), scans fake passes (`infer_linter.py`), injects AST micro-mutants (`micro_mutator.py` requiring >= 80% mutation score), audits visual regression masks (`smart_visual_masker.py`), and checks DB leaks (`trace_data_flow.py`).
+
+---
+
+## 5. CENTRALIZED TOOLS RUNBOOK
+
+All quality control and audit tasks are dispatched via scripts in `tools/` (Refer to `tools/TOOLS_RUNBOOK.md`):
+
+```bash
+# 1. Run 8 Quality Gates Verification
+python tools/verify_all.py
+
+# 2. Run AST linter for fake passes and empty catches
+python tools/infer_linter.py
+
+# 3. Analyze code change impact
+python tools/test_impact.py --git-diff
+
+# 4. Filter and distill verbose CLI logs by 95%
+python tools/distill_log.py <path_to_log>
+
+# 5. Query zero-token error memory cache
+python tools/cache_resolver.py query "<error_message>"
+```

package/README.md

@@ -1,3 +1,395 @@
-# Temporary Holding Version
+# 🧠 Synapse Hub — AI Agent Intelligence Core & Skill Network
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **The shared intelligence core and autonomous skill hub empowering AI coding assistants (Google Antigravity / Cursor / Windsurf / Claude Code) across automated testing suites.**  
+> **Tác giả / Author:** Thế Vị ([@TeeVee998](https://github.com/TeeVee998))  
+> **Phiên bản Hub:** `v2.0.0` (Semantic Versioning) | **Chỉ số toàn vẹn:** 27 Skills, 6 Agent Swarm Roles, 7 Core Rules, 20+ Python Tools.
+
+---
+
+## 🌟 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 các vai trò bầy đàn 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.0.0)"]
+        Skills[".agents/skills/ (27 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 cốt lõi:
+1. **Dùng chung đa dự án (Cross-Project Reusability):** Một lần phát triển skill hay tối ưu tool có thể áp dụng ngay cho bất kỳ dự án Web/API nào (React, Angular, Vue, Next.js, Java, Python).
+2. **Bảo mật mã nguồn công ty (Privacy & Clean SCM):** Repository dự án hoàn toàn sạch sẽ, không chứa prompt hay AI skill cá nhân.
+3. **Quản lý tập trung (Single Source of Truth):** Dễ dàng nâng cấp, thêm skill mới, đồng bộ Global Memory Cache tại một nơi duy nhất.
+4. **Nhẹ & Tinh gọn:** Dự án mục tiêu chỉ cần đúng **1 file duy nhất** hướng dẫn AI (`PROJECT_AI_GUIDE.md`).
+
+---
+
+## 🚀 2. Cách Sử Dụng (NPM / npx & Workspace Mount)
+
+### Cách A: Sử dụng tức thì qua NPM / npx (Khuyên dùng cho Web, Node & Playwright)
+Tại thư mục bất kỳ của dự án đích, bạn có thể thực thi ngay mà không cần clone hay cài đặt trước:
+```bash
+# 1-Click Bootstrap dự án (tự động sinh PROJECT_AI_GUIDE.md, cài pre-push hook, trích xuất AST map)
+npx synapse-hub setup
+
+# Chạy kiểm tra 8 Quality Gates DoD
+npx synapse-hub verify
+
+# Đánh giá sức khỏe dự án toàn diện (5-in-1 Project Health Report)
+npx synapse-hub analyze
+
+# Cài đặt cố định vào devDependencies của dự án mục tiêu
+npm install -D synapse-hub
+```
+
+### Cách B: Mở phiên làm việc đa thư mục (Multi-Root Workspace)
+Trong IDE (Google Antigravity / VS Code / Cursor):
+1. Mở thư mục dự án mục tiêu của bạn.
+2. Thêm thư mục `agent-skills` vào Workspace (`File` -> `Add Folder to Workspace...`).
+
+### Bước 2: Khởi tạo hướng dẫn dự án (`PROJECT_AI_GUIDE.md`)
+Copy file mẫu từ `templates/PROJECT_AI_GUIDE_TEMPLATE.md` vào thư mục gốc của dự án mục tiêu, đổi tên thành `PROJECT_AI_GUIDE.md` và điền thông tin cụ thể:
+- URL môi trường test/staging.
+- Tài khoản và cơ chế đăng nhập.
+- Cấu trúc thư mục mã nguồn.
+- Lệnh chạy test headless và công nghệ sử dụng.
+- **Dữ liệu tra cứu nhanh:** Khai báo đường dẫn `testcases.json` và `selectors.json` (hoặc đặt biến môi trường `TC_DATA_FILE` / `XPATH_DATA_FILE`) để công cụ `tools/lookup_tc.py` và `tools/lookup_xpath.py` nạp đúng dữ liệu của dự án.
+
+### Bước 3: Cài đặt tự động (One-Click Bootstrap)
+Chạy script cài đặt môi trường và phụ thuộc:
+```powershell
+# Windows PowerShell
+./scripts/install.ps1
+
+# Linux / macOS
+./scripts/setup.sh
+```
+Script bootstrap sẽ tự động thiết lập `.venv`, cài dependencies, chạy lint kiểm tra 30 skills, và **khởi tạo nạp seed giải pháp ban đầu** cho SQLite Central Agent Memory (`~/.agent_memory/global_cache.db`).
+
+> 💡 **Khởi tạo SQLite Memory trên CI/CD & Docker sạch:**  
+> Trên agent runner CI hoặc container Docker mới tinh, chạy lệnh sau để cấp quyền và khởi tạo bộ nhớ 0-token:
+> ```bash
+> agent-qa heal init
+> # hoặc chạy trực tiếp:
+> python tools/cache_resolver.py init
+> ```
+
+---
+
+## 👥 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 7 Gates DoD, 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` | `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` |
+
+---
+
+## 📦 4. Danh Mục 27 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. |
+
+---
+
+## 📜 5. Danh Mục 7 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 (7 Quality Gates).
+
+---
+
+## 🛠️ 6. Sổ Tay Công Cụ Tự Động Hóa (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 7 Gates DoD (UTF-8, No XPaths, UniqueCode, Clean POM).
+- `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 30 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`.
+
+---
+
+## 📚 7. Tài Liệu Kỹ Thuật Mở Rộng & CLI Package (docs/)
+
+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`.
+
+### Cài đặt nhanh CLI Package:
+```bash
+pip install -e .
+agent-qa --help
+agent-qa verify
+agent-qa lint
+```
+
+---
+
+# 🌐 English Edition
+
+# 🧠 Synapse Hub — AI Agent Intelligence Core & Skill Network
+
+> **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.0.0` (Semantic Versioning) | **Integrity Index:** 27 Skills, 6 Agent Swarm Roles, 7 Core Rules, 20+ Python Tools.
+
+---
+
+## 🌟 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.
+
+```mermaid
+flowchart TD
+    subgraph Hub["🧠 Synapse Hub (Intelligence Core v2.0.0)"]
+        Skills[".agents/skills/ (27 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["📁 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..."]
+    end
+
+    ProjectA -->|Mount Workspace| ChatSession
+    ProjectB -.->|Mount Workspace| ChatSession
+    ProjectC -.->|Mount Workspace| ChatSession
+    Other -.->|Mount Workspace| ChatSession
+```
+
+### Core Architectural Benefits:
+1. **Cross-Project Reusability:** Develop skills and tools once; reuse universally across any Web/API stack (React, Angular, Vue, Next.js, Java, Python).
+2. **Target Repository Privacy & Clean SCM:** Target project repos remain 100% clean—zero personal AI prompts or agent skills polluting production Git history.
+3. **Single Source of Truth:** Manage, upgrade, add new skills, and synchronize Global Memory Cache in one centralized hub.
+4. **Lean & Lightweight Integration:** Target projects require only **a single markdown guide** (`PROJECT_AI_GUIDE.md`).
+
+---
+
+## 🚀 2. Getting Started & Usage (NPM / npx & Workspace Mount)
+
+### Method A: Instant Execution via NPM / npx (Recommended for Web, Node & Playwright)
+Run commands directly from any target project directory without cloning or prior installation:
+```bash
+# 1-Click Project Bootstrap (generates PROJECT_AI_GUIDE.md, installs pre-push hook, extracts AST repo map)
+npx synapse-hub setup
+
+# Run 8 Quality Gates DoD Verification
+npx synapse-hub verify
+
+# Comprehensive 5-in-1 Project Health Audit
+npx synapse-hub analyze
+
+# Install permanently as a devDependency in target project
+npm install -D synapse-hub
+```
+
+### Method B: Multi-Root Workspace Mounting
+Within your AI IDE (Google Antigravity / VS Code / Cursor):
+1. Open your target project folder.
+2. Add the `synapse-hub` directory to your workspace (`File` -> `Add Folder to Workspace...`).
+
+### Step 2: Initialize Project AI Guide (`PROJECT_AI_GUIDE.md`)
+Copy `templates/PROJECT_AI_GUIDE_TEMPLATE.md` to target project root, rename to `PROJECT_AI_GUIDE.md`, and configure:
+- Test/staging environment URLs.
+- Credentials and authentication strategies.
+- Source code directory structure.
+- Headless execution commands and technology stack.
+- **Fast-Lookup Registers:** Point `testcases.json` and `selectors.json` (or set `TC_DATA_FILE` / `XPATH_DATA_FILE` env vars) for instant zero-token query via `tools/lookup_tc.py` and `tools/lookup_xpath.py`.
+
+### Step 3: One-Click Environment Bootstrap
+Execute the automated 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 |
+| :--- | :--- | :--- | :--- |
+| **`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 8 Quality Gates DoD, 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` | `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` |
+
+---
+
+## 📦 4. Standardized 27 Skills Catalog (.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. |
+
+---
+
+## 📜 5. 7 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; 8 Quality Gates DoD.
+
+---
+
+## 🛠️ 6. Automated Tools Runbook (tools/ & scripts/)
+
+For full details, refer to [tools/TOOLS_RUNBOOK.md](tools/TOOLS_RUNBOOK.md):
+
+- `tools/verify_all.py`: 8 Quality Gates DoD verification (UTF-8, No XPaths, UniqueCode, Clean POM).
+- `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.
+
+---
+
+## 📚 7. Extended Technical Documentation & CLI Package (docs/)
+
+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.
+
+### Quick CLI Installation:
+```bash
+pip install -e .
+agent-qa --help
+agent-qa verify
+agent-qa lint
+```

package/bin/agent-qa.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * Enterprise Synapse-Hub NPM Launcher
+ * ====================================
+ * Dispatches CLI subcommands to the underlying Python Standard Library engine (tools/cli.py).
+ * Provides cross-platform zero-install execution via `npx synapse-hub <command>`.
+ */
+
+const { spawn, execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const CLI_PATH = path.join(REPO_ROOT, 'tools', 'cli.py');
+
+// ANSI Color Helpers
+const RED = '\x1b[91m';
+const GREEN = '\x1b[92m';
+const YELLOW = '\x1b[93m';
+const CYAN = '\x1b[96m';
+const BOLD = '\x1b[1m';
+const RESET = '\x1b[0m';
+
+/**
+ * Resolves the available Python 3 executable across Windows, macOS, and Linux.
+ */
+function resolvePython() {
+  const candidates = process.platform === 'win32'
+    ? ['python', 'py', 'python3']
+    : ['python3', 'python'];
+
+  for (const cmd of candidates) {
+    try {
+      const output = execSync(`${cmd} --version`, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+      const match = output.match(/Python\s+(\d+)\.(\d+)/i);
+      if (match) {
+        const major = parseInt(match[1], 10);
+        const minor = parseInt(match[2], 10);
+        if (major > 3 || (major === 3 && minor >= 9)) {
+          return { command: cmd, version: output };
+        }
+      }
+    } catch (e) {
+      // Continue checking next candidate
+    }
+  }
+  return null;
+}
+
+function main() {
+  const python = resolvePython();
+
+  if (!python) {
+    console.error(`\n${BOLD}${RED}[ERROR] Python 3.9+ is required to execute synapse-hub tools.${RESET}`);
+    console.error(`Neither ${CYAN}python3${RESET} nor ${CYAN}python${RESET} (>= 3.9) was found on your PATH.`);
+    console.error(`👉 Please install Python from: ${BOLD}https://www.python.org/downloads/${RESET}\n`);
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(CLI_PATH)) {
+    console.error(`\n${BOLD}${RED}[ERROR] Core CLI engine not found at: ${CLI_PATH}${RESET}\n`);
+    process.exit(1);
+  }
+
+  const args = [CLI_PATH, ...process.argv.slice(2)];
+
+  // Spawn child Python process inheriting standard IO
+  const child = spawn(python.command, args, {
+    stdio: 'inherit',
+    env: { ...process.env, AGENT_QA_INVOKER: 'npm' }
+  });
+
+  child.on('error', (err) => {
+    console.error(`\n${BOLD}${RED}[ERROR] Failed to start synapse-hub CLI:${RESET}`, err.message);
+    process.exit(1);
+  });
+
+  child.on('exit', (code, signal) => {
+    if (signal) {
+      process.kill(process.pid, signal);
+    } else {
+      process.exit(code ?? 0);
+    }
+  });
+
+  process.on('SIGINT', () => child.kill('SIGINT'));
+  process.on('SIGTERM', () => child.kill('SIGTERM'));
+}
+
+main();