synapse-hub 2.2.3 → 2.4.0

package/CLAUDE.md

@@ -3,7 +3,11 @@
 > **Author & Creator:** Thế Vị (@TeeVee998) <https://github.com/TeeVee998/Synapse-Hub>  
 > **License:** MIT License (Mandatory Attribution Preservation)
 
----
+<!-- ============================================================================== -->
+<!-- AUTO-GENERATED FROM AGENTS.md — DO NOT EDIT DIRECTLY.                          -->
+<!-- Run: python3 tools/sync_agent_rules.py                                          -->
+<!-- ============================================================================== -->
+
 
 ## 🛡️ MANDATORY AI ETHICAL INVARIANT: AUTHOR ATTRIBUTION GUARD
 
@@ -12,14 +16,33 @@ In accordance with the MIT License, the original copyright notice crediting **Th
 
 ---
 
-## Quick Commands
-- Verify 9 Quality Gates: `python tools/verify_all.py` (or `agent-qa verify`)
-- Verify Author Attribution: `python tools/author_integrity.py` (or `agent-qa verify-author`)
-- Skill & MCP Security Audit: `python tools/skillspector.py` (or `agent-qa skillspector`)
-- Project Health Audit: `python tools/analyze_project.py` (or `agent-qa analyze`)
-
-## Core Architecture & Standards
-1. **Clean Page Object Model (POM):** 100% locators and UI actions belong in Page Classes. Never inline XPaths or CSS in test scripts.
-2. **Truth Anchor (Zero Fake Passes):** Always verify real DOM/API state. Never relax assertions to manufacture false passes.
-3. **100% UTF-8 No BOM:** All files must be UTF-8 without BOM.
-4. **Idempotent Data:** Always use randomized timestamps (`AUTO_` + millis) with automated teardown.
+## ⚡ Quick Commands
+- Verify 9 Quality Gates: `npx synapse-hub verify` (or `python tools/verify_all.py`)
+- Project Health Audit: `npx synapse-hub analyze` (or `python tools/analyze_project.py`)
+- Code Linter & Fake-Pass Sentinel: `npx synapse-hub lint` (or `python tools/infer_linter.py`)
+- Verify Author Attribution: `python tools/author_integrity.py`
+- Skill Security Audit: `python tools/skillspector.py .agents/skills`
+
+---
+
+## 🏛️ Core QA Automation Invariants (From AGENTS.md)
+1. **Clean Page Object Model (POM):**
+   - Test scripts (`tests/`, `Scripts/`) must contain ONLY business workflow method calls on Page Classes.
+   - Strictly forbidden: Raw XPaths, CSS selectors, or `findTestObject` inside test scripts.
+   - All locators and DOM operations must be encapsulated in Page Classes extending `BasePage`.
+
+2. **Truth Anchor (Zero Fake Passes):**
+   - Never write empty assertions or tautological tests (0 asserts).
+   - If a test fails due to an AUT defect, report it honestly. Never soften assertions or skip validation steps to fake a pass.
+
+3. **Dynamic & Idempotent Test Data:**
+   - Always randomize test entity codes with timestamps/prefixes (`AUTO_` + timestamp) to avoid DB unique constraint collisions.
+   - Every creation test case MUST be paired with automated Teardown / Cleanup.
+
+4. **Synchronization & Smart Waits:**
+   - Static sleeps (`Thread.sleep`, `time.sleep`) are strictly prohibited in test scripts.
+   - Use dynamic smart waits: element visibility checks or Playwright `waitForLoadState('networkidle')`.
+
+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.

package/LICENSE

@@ -1,3 +1,33 @@
+# Giấy Phép Bản Quyền MIT / MIT License
+
+[🇻🇳 Phiên Bản Tiếng Việt](#-phiên-bản-tiếng-việt-tham-khảo--giải-thích-pháp-lý) | [🇬🇧 English Legal Text](#-official-mit-license-english-legal-text)
+
+---
+
+## 🇻🇳 Phiên Bản Tiếng Việt (Tham Khảo & Giải Thích Pháp Lý)
+
+Bản quyền (c) 2026 Thế Vị (@TeeVee998). Toàn quyền bảo lưu.  
+Kho mã nguồn gốc: https://github.com/TeeVee998/Synapse-Hub
+
+*(Lưu ý: Phần tiếng Việt dưới đây là bản giải thích tham khảo nhằm giúp cộng đồng nắm bắt rõ quyền và nghĩa vụ; văn bản tiếng Anh phía dưới là văn bản pháp lý chính thức có hiệu lực của Giấy phép MIT).*
+
+### 1. Quyền của bạn (Được phép làm gì?)
+Theo Giấy phép MIT, bạn được cấp quyền miễn phí, không giới hạn để:
+- **Sử dụng:** Tự do chạy phần mềm cho bất kỳ mục đích cá nhân, đào tạo hoặc thương mại nào trong doanh nghiệp.
+- **Sao chép & Chỉnh sửa:** Tự do tạo bản sao, tùy biến, bổ sung thêm kỹ năng (Skills), quy tắc (Rules) hoặc công cụ (Tools) mới.
+- **Hợp nhất & Đóng gói:** Tích hợp Synapse Hub vào các bộ kiểm thử nội bộ hoặc giải pháp của bạn.
+
+### 2. Nghĩa vụ bắt buộc (Điều kiện tiên quyết)
+- **Ghi nhận nguồn tác giả gốc:** Bạn **BẮT BUỘC** phải giữ nguyên thông báo bản quyền ghi nhận tác giả **Thế Vị (@TeeVee998)** cùng liên kết mã nguồn gốc `https://github.com/TeeVee998/Synapse-Hub` trong toàn bộ các bản sao hoặc các phần quan trọng của phần mềm.
+- Nghiêm cấm hành vi xóa bỏ bản quyền hoặc mạo danh quyền tác giả.
+
+### 3. Tuyên bố miễn trừ trách nhiệm
+Phần mềm được cung cấp theo nguyên trạng ("AS IS"), không có bất kỳ bảo đảm nào (rõ ràng hay ngụ ý). Tác giả hoặc người nắm giữ bản quyền không chịu trách nhiệm đối với bất kỳ khiếu nại, tổn thất hay rủi ro nào phát sinh từ việc sử dụng phần mềm.
+
+---
+
+## 🇬🇧 Official MIT License (English Legal Text)
+
 MIT License
 
 Copyright (c) 2026 Thế Vị (@TeeVee998). All rights reserved.

package/NOTICE

@@ -0,0 +1,180 @@
+Synapse Hub
+Copyright (c) 2026 Thế Vị (@TeeVee998). Distributed under the MIT License.
+
+This software includes threat vector taxonomy, static rule categories, and security concepts
+inspired by:
+
+NVIDIA SkillSpector (https://github.com/NVIDIA/SkillSpector)
+Copyright (c) 2024-2025 NVIDIA CORPORATION & AFFILIATES.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+--------------------------------------------------------------------------------
+Third-Party Borrowings (idea- and text-level)
+--------------------------------------------------------------------------------
+
+1. Midscene.js (https://github.com/web-infra-dev/midscene) - MIT License.
+   The "Instant Action vs Auto-Planning Dispatch" guidance in
+   .agents/skills/playwright-live-interaction/SKILL.md and the
+   assert-on-extracted-data guidance in
+   .agents/skills/visual-regression-sentinel/SKILL.md are adapted from the
+   Midscene.js prompting model. Copyright (c) ByteDance / web-infra-dev.
+
+2. Kane CLI (https://github.com/lambdatest/kane-cli) - Apache License 2.0.
+   The "proven vs owed" coverage traceability concept used in
+   .agents/skills/lam-script-generator/SKILL.md and in tools/gherkin_suite.py
+   is adapted from the Kane CLI generate -> execute -> prove workflow.
+
+3. TestZeus Hercules (https://github.com/test-zeus-ai/testzeus-hercules) -
+   GNU Affero General Public License v3.0. tools/gherkin_suite.py is an
+   independent, from-scratch implementation of the Gherkin-driven E2E test
+   ingestion concept. NO upstream code or text is used; AGPL content is
+   incompatible with this MIT repository. Idea-level inspiration only.
+
+4. Anthropic Agent Skills (https://github.com/anthropics/skills) - no license
+   file (all rights reserved). SKILL.md structural conventions only were
+   observed as reference; no upstream text is copied.
+
+5. Agent Skills open standard (https://agentskills.io, governed by the
+   Agentic AI Foundation) - SKILL.md frontmatter and description-trigger
+   conventions followed for all hub skills.
+
+6. Playwright MCP (https://github.com/microsoft/playwright-mcp) - Apache
+   License 2.0. The ARIA snapshot serialization format in
+   tools/browser_helpers.js (ariaSnapshot) and the MCP tool-surface expansion
+   are adapted from the Playwright MCP contract.
+
+7. Stagehand (https://github.com/browserbase/stagehand) - MIT License.
+   The observe -> act -> extract interaction triad in
+   .agents/skills/playwright-live-interaction/SKILL.md and the action-result
+   caching guidance are adapted from the Stagehand primitives.
+
+8. OWASP ZAP (https://github.com/zaproxy/zaproxy) - Apache License 2.0.
+   The passive/active scan taxonomy and severity ladder in
+   .agents/skills/security-dast-sentinel/SKILL.md and tools/api_fuzzer.py
+   are adapted from ZAP's alert risk model.
+
+9. Selenium (https://github.com/SeleniumHQ/selenium) - Apache License 2.0.
+   Geometric relative-locator semantics (above/below/near/left-of/right-of)
+   in tools/heuristic_locator_matcher.py are adapted from Selenium relative
+   locators.
+
+10. Locust (https://github.com/locustio/locust) - MIT License. The
+    code-as-code load model (--emit-locust) in tools/generate_jmx_plan.py and
+    the Locust section in .agents/skills/backend-load-and-stress-patterns/
+    SKILL.md are adapted from the Locust user/task/weight model.
+
+11. Testcontainers (https://github.com/testcontainers/testcontainers-python)
+    - Apache License 2.0. The wait-ready readiness probe strategies
+    (port/http/sqlite) in tools/db_sandbox.py are adapted from the
+    Testcontainers WaitStrategy taxonomy.
+
+12. crewAI (https://github.com/crewAIInc/crewAI) - MIT License. The
+    hierarchical process / manager delegation guidance in
+    .agents/skills/agent-orchestration-multi-agent-optimize/SKILL.md is
+    adapted from the crewAI process model.
+
+13. browser-use (https://github.com/browser-use/browser-use) - MIT License.
+    Session-trace and human-in-the-loop escalation guidance in
+    .agents/agents/live-explorer.md is adapted from the browser-use agent
+    operating model.
+
+14. Appium (https://github.com/appium/appium) - Apache License 2.0. The
+    driver-architecture and image-based-matching rules in
+    .agents/rules/mobile_appium_rules.md are adapted from Appium's driver
+    and plugin concepts.
+
+15. LangChain (https://github.com/langchain-ai/langchain) - MIT License.
+    Consciously NOT adopted at framework level: the hub remains 0-LLM-
+    dependent by design. Recorded here as a documented decision, no content used.
+
+16. andrej-karpathy-skills (https://github.com/multica-ai/andrej-karpathy-skills)
+    - MIT License (declared in the repository's plugin.json), by forrestchang,
+    derived from Andrej Karpathy's published observations on LLM coding
+    pitfalls. The four behavioral principles (Think Before Coding, Simplicity
+    First, Surgical Changes, Goal-Driven Execution) in
+    .agents/skills/surgical-coding-principles/SKILL.md are adapted and
+    re-scoped for enterprise QA automation; wording, structure, and examples
+    modified.
+
+17. ponytail (https://github.com/DietrichGebert/ponytail) - MIT License,
+    Copyright (c) 2026 DietrichGebert. The 7-rung reuse-first ladder, the
+    completeness rules, and the never-cut floor in
+    .agents/skills/lean-code-ladder/SKILL.md are adapted from the ponytail
+    lazy-senior model; wording, structure, and examples modified.
+
+18. planning-with-files (https://github.com/OthmanAdi/planning-with-files)
+    - MIT License, Copyright (c) 2026 Ahmad Adi. The 3-file planning pattern
+    (task_plan.md / findings.md / progress.md), the 2-Action Rule, the
+    3-Strike Error Protocol, and the completion-gate concept in
+    .agents/skills/persistent-planning-files/SKILL.md are adapted as a
+    conventions-only skill; NO hooks or scripts from the upstream are used.
+
+19. anthropics/skills - skill "webapp-testing"
+    (https://github.com/anthropics/skills) - Apache License 2.0,
+    Copyright 2026 Anthropic, PBC. The server-lifecycle contract, the
+    static-vs-dynamic decision tree, and the reconnaissance-then-action
+    pattern in .agents/skills/playwright-webapp-testing/SKILL.md are adapted
+    per Apache-2.0 with prominent modification notices; rewritten derivative,
+    not a verbatim copy. No upstream scripts are bundled.
+
+20. superpowers (https://github.com/obra/superpowers) - MIT License,
+    Copyright (c) 2025 Jesse Vincent. The Iron Laws, the RED-GREEN-REFACTOR
+    cycle, the four-phase debugging process, the 3-fix architecture rule,
+    the verification gate function, and the claim-evidence matrix adapted
+    into .agents/skills/test-driven-development/SKILL.md,
+    .agents/skills/systematic-debugging/SKILL.md, and
+    .agents/skills/verification-before-completion/SKILL.md; wording,
+    structure, and hub tooling modified.
+
+21. wshobson/agents (https://github.com/wshobson/agents) - MIT License,
+    Copyright (c) 2024 Seth Hobson. Persona guidance in the "Persona
+    Enhancements (Adapted from wshobson/agents, MIT)" sections of the six
+    .agents/agents/*.md profiles is cherry-picked and condensed from the
+    test-automator, debugger, security-auditor, backend-architect,
+    context-manager, and qa agent definitions; heavily edited for the Synapse
+    Hub swarm context.
+
+22. bats-core (https://github.com/bats-core/bats-core) - CC0 1.0 Universal /
+    MIT License. Test structure, exit status assertions, and sandbox
+    isolation conventions in .agents/skills/bats-testing-patterns/SKILL.md
+    are adapted from bats-core community best practices.
+
+23. W3C WCAG 2.2 Recommendation & axe-core (https://github.com/dequelabs/axe-core)
+    - MPL 2.0. Accessibility rule heuristics, ARIA conformance checklists,
+    and contrast validation principles in .agents/skills/wcag-audit-patterns/
+    SKILL.md are structured per W3C WCAG 2.2 guidelines and axe-core rule taxonomies.
+
+24. End-to-End Test Architecture & Multi-Browser Sharding Patterns
+    - Adapted from enterprise Playwright and modern browser automation
+    standards in .agents/skills/e2e-testing-patterns/SKILL.md.
+
+25. Clean Architecture & Refactoring (Martin Fowler & Robert C. Martin)
+    - Refactoring catalog, code smell heuristics, and SOLID design patterns in
+    .agents/skills/code-refactoring-refactor-clean/SKILL.md are synthesized
+    from established Clean Code software engineering literature.
+
+26. GitHub Actions Starter Workflows (https://github.com/actions/starter-workflows)
+    - MIT License. CI/CD test automation pipelines, matrix sharding, and caching
+    patterns in .agents/skills/github-actions-templates/SKILL.md are adapted
+    from standard GitHub Actions workflow conventions.
+
+27. Architecture Decision Records (Michael Nygard & MADR)
+    - CC-BY-4.0 / MIT. The architectural decision record schema and governance
+    structure in .agents/skills/architecture-decision-records/SKILL.md are
+    adapted from Michael Nygard's ADR format and the Markdown ADR project.
+
+28. Multi-Agent Swarm Orchestration & Optimization
+    - Multi-agent coordination topologies, subagent communication protocols,
+    and token throughput optimization in
+    .agents/skills/agent-orchestration-multi-agent-optimize/SKILL.md are
+    synthesized from autonomous multi-agent design patterns (crewAI, AutoGen).

package/README.en.md

@@ -0,0 +1,325 @@
+# 🧠 Synapse Hub — AI Test Quality Linter & Guardrails for Automated Testing
+### *Zero-Dependency Quality Linter, Fake-Pass Sentinel & Guardrails for AI-Generated Tests*
+
+[🇻🇳 Tiếng Việt](README.md) | [🇬🇧 English Edition](README.en.md)
+
+> **Core Mission:** A standalone, zero-dependency Linter & Guardrail engine (zero external dependencies for core engine & DoD gates) protecting test suite integrity in the era of AI code generation — Catching tautological "fake-pass" tests, eliminating hard sleeps, distilling 95% CI log noise, and enforcing Clean POM architecture. Specialized tools (Excel export, Canvas visual diff) leverage standard optional extras (`openpyxl`, `Pillow`).  
+> **Extended Ecosystem:** Bundled with 38 production QA skills, 6 specialized AI roles, and 9 DoD Quality Gates supporting Playwright, Cypress, Pytest, and Katalon.  
+> **Author:** Thế Vị ([@TeeVee998](https://github.com/TeeVee998))  
+> **Hub Version:** `v2.4.0` | **Scope:** 38 Standardized Skills, 6 Specialized AI Agents, 51 CLI Commands & 60+ Test Engineering Tools, 9 DoD Quality Gates.
+
+[![npm version](https://img.shields.io/npm/v/synapse-hub.svg?style=flat-square&color=blue)](https://www.npmjs.com/package/synapse-hub)
+[![node version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg?style=flat-square)](https://nodejs.org)
+[![python version](https://img.shields.io/badge/python-%3E%3D3.10-blue.svg?style=flat-square)](https://python.org)
+[![license](https://img.shields.io/badge/license-MIT-green.svg?style=flat-square)](https://github.com/TeeVee998/Synapse-Hub/blob/main/LICENSE)
+[![Ecosystem](https://img.shields.io/badge/AI%20Ecosystem-Antigravity%20%7C%20Cursor%20%7C%20Claude%20%7C%20Copilot%20%7C%20Windsurf-orange.svg?style=flat-square)](#)
+
+---
+
+### 💡 What is Synapse Hub? (In 30 Seconds)
+
+Think of Synapse Hub as a versatile, dual-mode engine:
+1. 🛠️ **Standalone CLI Tool (Zero AI needed):** Simply run `npx synapse-hub lint` to scan your test suite, distill bloated CI logs, or export test cases to standard Excel spreadsheets without any complex setup.
+2. 🧠 **Guardrail "Brain" for AI Coding Assistants:** When using Google Antigravity, Cursor, or Claude Code, Synapse Hub acts as an automated quality guardrail — preventing AI assistants from generating tautological fake-passes, swallowing exceptions, or inserting flaky hard sleeps.
+
+> 🛡️ **Zero Overhead:** You **never need to memorize** all 38 skills or 60+ tools! The system operates strictly *On-Demand*, activating tools only when a specific situation arises.
+
+#### ⚖️ Before vs. After Synapse Hub:
+
+| Raw AI-Generated Tests (Without Synapse) | Protected by Synapse Hub 🛡️ |
+| :--- | :--- |
+| ❌ **"Fake-Pass" tests:** Tests pass unconditionally with **0 assertions**, giving false confidence. | ✅ **Caught in 0.1s:** Flags zero-assertion tautologies and enforces genuine validation. |
+| ❌ **Hardcoded sleeps:** Injects random `sleep(5000)` calls, making suites slow and flaky in CI. | ✅ **Smart Wait Enforcement:** Flags static delays and guides dynamic element synchronization. |
+| ❌ **Context overflow:** CI logs with 20,000+ lines blow up LLM token windows without root cause. | ✅ **95% Noise Distillation:** Compresses logs down to ~30 lines containing the exact failing trace. |
+| ❌ **Security leaks:** AI inadvertently commits hardcoded plaintext passwords or secret tokens. | ✅ **Gate 6 Sentinel:** Scans and blocks credentials before commits ever reach remote SCM. |
+
+---
+
+## ⚡ 1. The 60-Second "Wow" (3 Hero Features 🦸‍♂️)
+
+No need to read dozens of documents or configure complex frameworks. You can immediately solve three daily QA pain points:
+
+### 🔍 1. Catch "Fake-Pass", Static Sleeps & Swallowed Exceptions
+```bash
+npx synapse-hub lint ./tests
+```
+* **The Problem:** AI-generated tests frequently pass unconditionally without testing anything (zero assertions), rely on flaky hardcoded sleeps (`Thread.sleep`), or hide exceptions in empty `try-catch` blocks.
+* **The Solution:** Polyglot heuristic & static AST linter (Playwright TypeScript/JavaScript, Pytest Python, Cypress, Groovy/Katalon) flags defects in 0.1s without LLM tokens.
+
+### 📊 2. Convert Requirements Into Standard 12-Column Excel
+```bash
+npx synapse-hub export-excel
+```
+* **The Problem:** QA engineers spend tedious hours manually formatting Excel sheets from user stories or Markdown scenarios.
+* **The Solution:** Compiles test scenarios directly into formatted 12-column `.xlsx` spreadsheets with calculated P × I risk scoring, ready for PMs and stakeholders.
+
+### 🧹 3. Distill 95% CI Log Bloat Down to Root Cause
+```bash
+npx synapse-hub distill path/to/ci.log
+```
+* **The Problem:** CI/CD build logs containing 20,000+ lines overwhelm LLM context windows and human eyes.
+* **The Solution:** Filters out 95% repetitive noise and extracts ~30 lines containing the exact failing line, exception stacktrace, and HTTP status.
+
+### 💻 Real-World Terminal Output (Catching Defects in 0.1s Zero-Token):
+```bash
+$ npx synapse-hub lint ./tests
+
+======================================================================
+    ENTERPRISE STATIC DEFECT & FAKE-PASS SENTINEL
+======================================================================
+  Target Scope       : 6 Test Scripts (Polyglot TS/Python/Groovy)
+  Detected Items:
+    - [CRITICAL] tests/checkout.spec.ts:42 - Fake-pass risk: Test contains 0 assertions!
+    - [CRITICAL] tests/login.spec.ts:14 - Hardcoded sleep (5000ms) detected. Replace with dynamic wait.
+======================================================================
+Result: 2 anti-patterns flagged in 0.12s (Zero LLM tokens used).
+```
+
+---
+
+## 🚀 2. Fast & Non-Intrusive Onboarding
+
+Synapse Hub respects your workspace privacy and system boundaries. You have complete control over disk writes:
+
+```bash
+# 🩺 Diagnose your local environment in 1 second (Node, Python, Chrome, Git):
+npx synapse-hub doctor
+
+# 💡 Pro Tip: Install globally to run commands directly without npx:
+npm install -g synapse-hub
+synapse-hub doctor
+
+# 🔹 Option 1: Project-local configuration only (Safest, does not touch ~/.gemini)
+npx synapse-hub setup --local-only
+
+# 🔹 Option 2: Dry-run simulation (Preview actions without writing any file to disk)
+npx synapse-hub setup --dry-run
+
+# 🔹 Option 3: Full setup (Generates PROJECT_AI_GUIDE.md, AI bridges and Antigravity plugin)
+npx synapse-hub setup
+
+# 🔹 Completely revert and uninstall at any time:
+npx synapse-hub uninstall
+```
+
+### Run Quality DoD Gates:
+```bash
+npx synapse-hub verify         # Execute 9 Quality Gates DoD (Gate 0–8)
+npx synapse-hub analyze        # Comprehensive 5-in-1 project health audit
+```
+
+### 🔄 3-Line CI/CD & Pre-commit Integration:
+Automatically block fake-pass tests and substandard code before merging:
+
+```yaml
+# Method 1: Official Composite GitHub Action (action.yml)
+- name: Run Synapse Hub Quality Gates
+  uses: TeeVee998/Synapse-Hub@v2
+  with:
+    mode: 'target'
+    format: 'sarif'
+
+# Method 2: Direct NPX execution (GitLab CI / Bitbucket / Jenkins)
+- name: Run Synapse Hub Quality Gates
+  run: npx synapse-hub verify
+```
+
+```yaml
+# Pre-commit Hook Integration (.pre-commit-config.yaml):
+repos:
+  - repo: https://github.com/TeeVee998/Synapse-Hub
+    rev: v2.4.0
+    hooks:
+      - id: synapse-lint
+      - id: synapse-verify
+```
+*(Configurable via root `synapse.config.json`. See comprehensive documentation at [docs/CI_CD_INTEGRATION.md](docs/CI_CD_INTEGRATION.md)).*
+
+| Gate | Gate Name | Practical Verification Objective |
+| :---: | :--- | :--- |
+| **Gate 0** | **Author Attribution & MIT** | Canonical author attribution invariant preserving author Thế Vị (@TeeVee998) MIT notice. |
+| **Gate 1** | **UTF-8 No BOM Clean Encoding** | Scans 100% of repository files for illegal BOM bytes and mojibake corruption. |
+| **Gate 2** | **Path Portability** | Prohibits local workstation paths (`/Users/...`, `C:\...`) in source code. |
+| **Gate 3** | **Clean POM Flat Architecture** | Enforces 100% locator encapsulation in Page Classes; zero raw XPaths in test scripts. |
+| **Gate 4** | **AI Docs Anti-Drift** | Verifies AST truth against `PROJECT_AI_GUIDE.md`, eliminating hallucinated PageClasses. |
+| **Gate 5** | **Temp File Blacklist** | Prevents temporary build debris (`*.tmp`, memory dumps, stale artifacts) from leaking. |
+| **Gate 6** | **Credential Security** | Blocks hardcoded plaintext passwords, private keys, and secret tokens in code. |
+| **Gate 7** | **Static Defect & Fake-Pass Sentinel** | Static heuristic analysis catching 0-assertion tests, empty catch blocks, hardcoded/variable sleeps (≥ 3000ms), and unawaited promises. |
+| **Gate 8** | **Assertion Sensitivity Sentinel** | Injects syntactic micro-mutations linked via dataflow (requires Score ≥ 80%). |
+
+---
+
+## 🎯 3. Level-Based Roadmap
+
+| Level | What You Want | Synapse Hub Entry Point |
+| :--- | :--- | :--- |
+| **Fresher / Junior** | Learn fast, deliver immediately, understand weak asserts | • `npx synapse-hub export-excel`: Generate standard test cases.<br/>• `npx synapse-hub lint ./tests`: Understand why assertions are tautological.<br/>• Inspect Clean POM examples in `examples/practices/`. |
+| **Mid-Level** | Reduce flakiness, cut locator maintenance | • `npx synapse-hub flaky scan ./tests`: Detect flaky tests and quarantine them.<br/>• `npx synapse-hub heal`: Semantic locator healing via AOM diffing.<br/>• Add linter to pre-commit git hooks. |
+| **Senior / Lead** | Control, measurement, CI/CD safety gates | • `npx synapse-hub verify`: 9 Automated DoD Gates in CI.<br/>• `npx synapse-hub mutate ./tests`: Heuristic assertion sensitivity analysis before merge.<br/>• Standard Markdown/JSON telemetry for PR review bots. |
+
+> *Pro Tip: If installed globally (`npm i -g synapse-hub`), you can use the shorter syntax `synapse-hub <cmd>` or equivalent aliases `synapse`, `agent-qa`.*
+
+---
+
+## 💎 4. Core Architecture & Engineering Pillars
+
+```mermaid
+flowchart TD
+    subgraph Hub["🧠 Synapse Hub (Core v2.4.0)"]
+        Skills[".agents/skills/ (38 Skills)"]
+        Agents[".agents/agents/ (6 Specialized Roles)"]
+        Rules[".agents/rules/ (11 Core Rules)"]
+        Tools["tools/ (60+ Universal Python Tools)"]
+        Workflows[".agents/workflows/ (10 Workflows)"]
+    end
+
+    subgraph ChatSession["💬 AI Agent Workspace / IDE"]
+        Hub -->|Mount / Plugins| ChatSession
+    end
+
+    subgraph Projects["📁 Target Test Projects"]
+        ProjectA["Playwright (TS/JS)"]
+        ProjectB["Pytest (Python)"]
+        ProjectC["Cypress / Katalon"]
+    end
+
+    ProjectA -->|Verify & Lint| ChatSession
+    ProjectB -->|Verify & Lint| ChatSession
+    ProjectC -->|Verify & Lint| ChatSession
+```
+
+### 🧠 Pillar 1: Fake-Pass Prevention & Assertion Sensitivity (Heuristic)
+- **Static Defect Sentinel (`tools/infer_linter.py`):** Scans for anti-patterns: unasserted tests, swallowed catch blocks, hardcoded sleeps, and unawaited Playwright assertions.
+- **Assertion Sensitivity Sentinel (`tools/micro_mutator.py`):** Injects lightweight syntactic micro-mutations (equality, relational, boundary inversions) to verify whether downstream assertions catch logic flaws. Enforces Sensitivity Score ≥ 80% to pass Gate 8.
+
+### ⚡ Pillar 2: Context Optimization & Token Conservation
+- **Log Distillation (`tools/distill_log.py`):** Truncates verbose terminal output to keep AI prompts concise.
+- **AST Method Mapping (`tools/repo_map.py`):** Maps class methods into a compressed < 600 token index; no reading large monolithic files whole.
+- **Episodic SQLite Memory (`tools/cache_resolver.py`):** Offline solution store at `~/.agent_memory/global_cache.db` (zero token queries).
+
+---
+
+## ⚖️ 5. Transparent Engineering & Known Limitations
+
+To uphold our strict **Truth Anchor** standard, we openly disclose known system boundaries:
+
+1. **Assertion Sensitivity is a Syntactic Heuristic, not Compiler-Grade Mutation Testing:**  
+   `tools/micro_mutator.py` uses lexical AST pattern evaluation to test downstream assertion coverage in sub-second speed. It **does not replace** full dynamic runtime mutation testing frameworks (such as Stryker for JS/TS or mutmut for Python) when bytecode-level mutant kill-rate is mandated.
+2. **Empirical Benchmark & Evaluation Metrics (`benchmarks/qa_eval`):**  
+   Evaluated across 25 polyglot testing challenges (Groovy, TypeScript, Python, Java):
+   - **Autonomous Resolution Rate:** 25 / 25 challenges (100.0%).
+   - **Average Token Consumption:** 76.2 tokens / bug (saving 95% prompt context vs full repo dump).
+   - **Assertion Sensitivity (Mutation Score):** 100.0% mutants killed.
+   - **Fake-Pass Sentinel Accuracy (`infer_linter.py`):** **100.0% Precision** (0 false positives), **95.7% Recall**, **97.8% F1-Score** on 51 independent samples.
+3. **Framework Support Scope:**  
+   Synapse Hub provides native runners and direct adapters for **Playwright, Pytest, Katalon Studio/Groovy, and Cypress**. For **Selenium WebDriver**, the hub supports Clean POM design patterns, smart waits, and universal IR transpilation, which can be readily adapted into standard Selenium WebDriver test suites.
+4. **Recommended Runtime Baseline:**  
+   - Node.js: `>= 18.0.0` (Node 20 or 22 LTS recommended).
+   - Python: `>= 3.9` (Python 3.10+ recommended; full testing matrix on Python 3.10, 3.11, 3.12, 3.13).
+5. **Headless Browser Requirement:**  
+   Live DOM inspection and locator self-healing require a headless browser environment (e.g., Playwright Chromium) to extract the Accessibility Object Model (AOM).
+
+---
+
+## 👥 6. Multi-Agent Swarm System (6 Specialized Roles)
+
+| Subagent Role | Core Responsibilities | Key Skills | Included Tools |
+| :--- | :--- | :--- | :--- |
+| **`orchestrator`** | Workflow director, project bootstrapper, health auditor, state anchor. | `agent-orchestration`, `graphify`, `architecture-decision-records` | `setup_project.py`, `analyze_project.py`, `repo_map.py` |
+| **`live-explorer`** | Live DOM/AOM probing via headless Playwright, destructive action firewall. | `playwright-live-interaction`, `self-healing-locator`, `visual-regression-sentinel` | `safety_firewall.py`, `browser_helpers.js` |
+| **`pom-crafter`** | Clean POM engineer, API breaking change sentinel, story-to-script generator. | `clean-pom-crafter`, `lam-script-generator`, `synthetic-test-data-generator` | `generate_tc_from_story.py`, `api_drift_sentinel.py` |
+| **`test-runner`** | Headless CLI suite dispatcher, parallel matrix sharder, log distiller. | `katalon-cli-runner`, `e2e-testing-patterns`, `flaky-test-sentinel-and-quarantine` | `matrix_sharder.py`, `distill_log.py`, `pinpoint_failure.py` |
+| **`failure-analyst`** | Root cause autopsy, failing line isolation, automated bug ticket synthesis. | `failure-autopsy-and-healing`, `token-and-context-optimizer` | `auto_heal.py`, `bug_reporter.py`, `cache_resolver.py` |
+| **`quality-gatekeeper`**| Sentinel guardian enforcing 9 DoD Quality Gates and assertion sensitivity. | `antigravity-test-sentinel`, `wcag-audit-patterns`, `security-dast-sentinel` | `verify_all.py`, `micro_mutator.py`, `infer_linter.py` |
+
+---
+
+## 📦 7. Standardized Skill Catalog (38 Skills in .agents/skills/)
+
+<details>
+<summary><b>📦 Click to expand: 38 Standardized Skills</b></summary>
+
+| # | Skill ID | Practical Capability |
+|:---:|---|---|
+| 1 | `clean-pom-crafter` | Clean POM & Flat Architecture page class design (zero raw selectors in test scripts). |
+| 2 | `playwright-live-interaction` | Live DOM/AOM exploration and < 200ms selector verification via headless Playwright. |
+| 3 | `failure-autopsy-and-healing` | Failure triage from JUnit XML/screenshots and automated broken locator repair. |
+| 4 | `infer_linter` / `antigravity-test-sentinel` | Quality gatekeeper enforcing zero fake-passes and 9 DoD quality gates. |
+| 5 | `token-and-context-optimizer` | Prompt context optimization, log distillation, and Context Rot prevention. |
+| 6 | `flaky-test-sentinel-and-quarantine` | Non-deterministic test detection, flakiness scoring, and quarantine management. |
+| 7 | `api-spec-to-e2e-matrix` | Convert OpenAPI/Swagger specifications into E2E testing matrices. |
+| 8 | `api-network-mocking-interception` | HTTP/GraphQL traffic stubbing, route mocking, and chaos network failure simulation. |
+| 9 | `synthetic-test-data-generator` | Generate idempotent, collision-free synthetic test data with timestamps. |
+| 10 | `db-state-verifier-and-seeder` | Seed isolated test fixtures and assert database state across SQL and NoSQL. |
+| 11 | `visual-regression-sentinel` | Screenshot layout comparison with dynamic anti-flake element masking. |
+| 12 | `wcag-audit-patterns` | Accessibility auditing against WCAG 2.2 A/AA and semantic ARIA roles. |
+| 13 | `security-dast-sentinel` | Dynamic security analysis: OWASP Top 10, security headers, token leaks, and IDOR. |
+| 14 | `web-vitals-and-performance-profiler` | Core Web Vitals (LCP, CLS, INP) measurement and network waterfalls via CDP. |
+| 15 | `backend-load-and-stress-patterns` | Orchestrate k6, Locust, and Apache JMeter backend load and SLA endurance test suites. |
+| 16 | `auth-session-and-cookie-manager` | Browser session `storageState`, JWT token management, and multi-role states. |
+| 17 | `file-and-report-validator` | Tabular integrity and schema validation for downloaded/uploaded files (Excel, CSV, PDF). |
+| 18 | `e2e-testing-patterns` | Multi-browser E2E test architectures, parallel sharding, and retry governance. |
+| 19 | `lam-script-generator` | Transform user stories and acceptance criteria into runnable Clean POM test scripts. |
+| 20 | `katalon-cli-runner` | Headless test execution for Katalon and Gradle suites with automatic driver cleanup. |
+| 21 | `bats-testing-patterns` | Automated testing for bash/sh scripts, CLI tools, and CI/CD pipelines with Bats. |
+| 22 | `code-refactoring-refactor-clean` | Technical debt remediation and test refactoring using SOLID and Clean Code patterns. |
+| 23 | `agent-orchestration-multi-agent-optimize` | Profile and optimize multi-agent swarm workloads and token throughput. |
+| 24 | `architecture-decision-records` | Author and maintain technical Architecture Decision Records (ADRs). |
+| 25 | `github-actions-templates` | Production-ready GitHub Actions workflow templates for automated test pipelines. |
+| 26 | `graphify-impact-analyzer` | Code change blast radius analysis and impacted test scoping via AST graphs. |
+| 27 | `skillspector-security-guard` | Audit AI agent skills and MCP configurations against prompt injection vectors. |
+| 28 | `gherkin-to-suite` | Compile Gherkin `.feature` BDD files into an expanded test matrix, Universal IR, and coverage-gap report. |
+| 29 | `rbt-manual-testing` | 6-stage Risk-Based Testing (AI-RBT) manual test case synthesis, 12-column matrix, and input checklist. |
+| 30 | `agy-customizations` | Antigravity Customization System guide for skills, rules, hooks, and MCP servers. |
+| 31 | `persistent-planning-files` | Persist plans, findings, and progress to three markdown files so multi-phase work survives context resets. |
+| 32 | `surgical-coding-principles` | Four disciplined-change principles: state assumptions, minimal diffs, every line traces to the request. |
+| 33 | `lean-code-ladder` | 7-rung reuse-first ladder: pick the smallest complete solution before writing new code. |
+| 34 | `playwright-webapp-testing` | Managed server lifecycle (start/ready/teardown) for local Playwright webapp test runs. |
+| 35 | `test-driven-development` | RED-GREEN-REFACTOR discipline: no production code before a watched failing test. |
+| 36 | `systematic-debugging` | Four-phase root-cause investigation before any fix; 3 failed fixes signal an architecture question. |
+| 37 | `verification-before-completion` | Evidence protocol: every pass/done claim requires fresh command output from the current session. |
+| 38 | `meta-prompt-crafter` | Meta-prompt engineer: Transforms rough requests into high-fidelity prompts for any target AI. |
+
+> **Open source & credits:** Skills 31-37 are adapted from open-source projects (andrej-karpathy-skills, ponytail, planning-with-files, anthropics/skills, superpowers, wshobson/agents) — full license and author details in `NOTICE` (entries 16-21); companion external-tool guide in `docs/adopted-ecosystem-tools.md`.
+
+</details>
+
+---
+
+## 🛠️ 8. CLI Tooling Arsenal (tools/)
+
+Synapse Hub includes over 60 utility tools implemented entirely in the **Python Standard Library** (zero external dependencies):
+
+```bash
+# 1. Diagnose local environment (Node, Python, Chrome, Git)
+npx synapse-hub doctor
+
+# 2. Run 9 Quality Gates DoD Verification
+npx synapse-hub verify
+
+# 3. Scan for fake-passes, tautologies, and empty catch blocks
+npx synapse-hub lint ./tests
+
+# 4. Distill verbose CI/CD logs down to root causes
+npx synapse-hub distill path/to/ci.log
+
+# 5. Export test cases to formatted Excel .xlsx
+npx synapse-hub export-excel
+
+# 6. Verify assertion sensitivity via syntactic micro-mutations
+npx synapse-hub mutate ./tests
+
+# 7. Detect and quarantine flaky tests
+npx synapse-hub flaky scan ./tests
+```
+
+*(See [docs/CLI_REFERENCE.md](docs/CLI_REFERENCE.md) and [tools/TOOLS_RUNBOOK.md](tools/TOOLS_RUNBOOK.md) for parameter details).*
+
+> 💡 **Equivalent Command Aliases:** When installed globally (`npm i -g synapse-hub`), you can interchangeably use `synapse-hub`, `synapse`, or `agent-qa` (e.g., `synapse verify`, `agent-qa lint ./tests`).
+
+---
+
+## 📄 Provenance & Attribution (MIT License)
+
+This software was created and designed by **Thế Vị ([@TeeVee998](https://github.com/TeeVee998))** under the open-source [MIT License](LICENSE).  
+You are free to use, modify, and distribute this software, provided that the **original author attribution and copyright notice are preserved**.