synapse-hub 2.2.4 → 2.4.0

package/benchmarks/qa_eval/reports/eval_results.json

@@ -0,0 +1,105 @@
+{
+  "timestamp": "2026-10-30T17:09:57.038606",
+  "total_challenges": 5,
+  "passed_challenges": 5,
+  "failed_challenges": 0,
+  "resolution_rate_pct": 100.0,
+  "avg_mttr_sec": 0.0,
+  "avg_token_consumption": 52.4,
+  "avg_mutation_score": 100.0,
+  "zero_side_effect_rate_pct": 100.0,
+  "safety_firewall_clearance_pct": 100.0,
+  "categories": {
+    "locator_drift": {
+      "total": 5,
+      "passed": 5,
+      "tokens": 262,
+      "time": 0.0002,
+      "resolution_rate": 100.0,
+      "avg_tokens": 52.4,
+      "avg_time": 0.0
+    }
+  },
+  "details": [
+    {
+      "id": "QA-CHALLENGE-01",
+      "name": "Dynamic CSS-in-JS Hash Locator Shift",
+      "category": "locator_drift",
+      "difficulty": "MEDIUM",
+      "status": "PASSED",
+      "resolved": true,
+      "safety_cleared": true,
+      "time_to_heal_sec": 0.0001,
+      "max_time_allowed_sec": 2.0,
+      "time_compliant": true,
+      "token_consumption": 50,
+      "mutation_score": 100.0,
+      "zero_side_effect": true,
+      "resolution_notes": "Autonomous cascade healed: 'button.btn-submit' -> '[data-testid='submit-order-btn']' (confidence 0.98)"
+    },
+    {
+      "id": "QA-CHALLENGE-02",
+      "name": "Nested Shadow DOM Component Piercing",
+      "category": "locator_drift",
+      "difficulty": "HARD",
+      "status": "PASSED",
+      "resolved": true,
+      "safety_cleared": true,
+      "time_to_heal_sec": 0.0,
+      "max_time_allowed_sec": 3.0,
+      "time_compliant": true,
+      "token_consumption": 62,
+      "mutation_score": 100.0,
+      "zero_side_effect": true,
+      "resolution_notes": "Autonomous cascade healed: '#customer-email' -> 'template:has-text('<input id='customer-email' type='email' data-testid='user-email'/>')' (confidence 0.94)"
+    },
+    {
+      "id": "QA-CHALLENGE-03",
+      "name": "Semantic Text Label Evolution",
+      "category": "locator_drift",
+      "difficulty": "EASY",
+      "status": "PASSED",
+      "resolved": true,
+      "safety_cleared": true,
+      "time_to_heal_sec": 0.0001,
+      "max_time_allowed_sec": 1.5,
+      "time_compliant": true,
+      "token_consumption": 50,
+      "mutation_score": 100.0,
+      "zero_side_effect": true,
+      "resolution_notes": "Autonomous cascade healed: '//button[text()='Submit Order']' -> '#order-cta' (confidence 0.9)"
+    },
+    {
+      "id": "QA-CHALLENGE-04",
+      "name": "Legacy ID Removed in Favor of data-testid",
+      "category": "locator_drift",
+      "difficulty": "EASY",
+      "status": "PASSED",
+      "resolved": true,
+      "safety_cleared": true,
+      "time_to_heal_sec": 0.0,
+      "max_time_allowed_sec": 1.5,
+      "time_compliant": true,
+      "token_consumption": 50,
+      "mutation_score": 100.0,
+      "zero_side_effect": true,
+      "resolution_notes": "Autonomous cascade healed: '#customer_name' -> '[data-testid='customer-name-field']' (confidence 0.98)"
+    },
+    {
+      "id": "QA-CHALLENGE-05",
+      "name": "HTML Tag Evolution: Anchor to ARIA Button",
+      "category": "locator_drift",
+      "difficulty": "MEDIUM",
+      "status": "PASSED",
+      "resolved": true,
+      "safety_cleared": true,
+      "time_to_heal_sec": 0.0,
+      "max_time_allowed_sec": 2.0,
+      "time_compliant": true,
+      "token_consumption": 50,
+      "mutation_score": 100.0,
+      "zero_side_effect": true,
+      "resolution_notes": "Autonomous cascade healed: 'a.nav-export' -> 'button' (confidence 0.9)"
+    }
+  ]
+}

package/bin/agent-qa.js

@@ -10,7 +10,7 @@
  * Provides cross-platform zero-install execution via `npx synapse-hub <command>`.
  */
 
-const { spawn, execSync } = require('child_process');
+const { spawn, execFileSync } = require('child_process');
 const path = require('path');
 const fs = require('fs');
 
@@ -35,7 +35,7 @@ function resolvePython() {
 
   for (const cmd of candidates) {
     try {
-      const output = execSync(`${cmd} --version`, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+      const output = execFileSync(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);
@@ -55,6 +55,9 @@ function main() {
   const python = resolvePython();
 
   if (!python) {
+    if (process.argv.includes('--first-run')) {
+      process.exit(0);
+    }
     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`);
@@ -91,4 +94,8 @@ function main() {
   process.on('SIGTERM', () => child.kill('SIGTERM'));
 }
 
-main();
+if (require.main === module) {
+  main();
+} else {
+  module.exports = { resolvePython };
+}

package/docs/ARCHITECTURE.md

@@ -0,0 +1,107 @@
+# Agent-Skills Architecture & Design Principles
+
+> **Scope:** Enterprise Multi-Agent QA Hub  
+> **Version:** `2.3.0` | **Status:** Active / Production Standard
+
+---
+
+## 1. Hub & Spoke Operating Model
+
+The `agent-skills` repository functions as a centralized **Intelligence Core (Hub)** decoupled from target test repositories (**Spokes**). 
+
+```mermaid
+flowchart TD
+    subgraph Hub["Agent-Skills Hub (Intelligence Core)"]
+        Catalog["38 Standardized Skills (.agents/skills)"]
+        Rules["Core Architectural Rules (.agents/rules)"]
+        Tools["Zero-Token Python Engine (tools/)"]
+        Swarm["6 Specialized Subagents (.agents/agents)"]
+    end
+
+    subgraph Spokes["Target Repositories (Test Suites)"]
+        Repo1["Project A (Playwright / TS)"]
+        Repo2["Project B (Katalon / Groovy)"]
+        Repo3["Project C (Python / Pytest)"]
+    end
+
+    Hub -->|Mounted as Skill Provider| Repo1
+    Hub -->|Mounted as Skill Provider| Repo2
+    Hub -->|Mounted as Skill Provider| Repo3
+```
+
+### Architectural Benefits:
+1. **Zero Context Contagion:** Target project repositories stay clean and focused strictly on test cases and Page Classes, without polluting git trees with heavy AI agent instructions.
+2. **Instant Upgradability:** Improvements to self-healing algorithms, token compressors, and lint rules propagate globally to all target projects instantly.
+3. **Intellectual Property Isolation by Architecture:** Because `agent-skills` is a decoupled, standalone repository, target projects remain 100% clean without requiring complex dual-remote mirroring or `smart_push` scripts. Developers and agents push directly to company SCM for target projects, and to the central hub for skills.
+
+---
+
+## 2. Four-Tier Skill Stratification
+
+The 37 skills in the hub are structured into four progressive operational tiers:
+
+```mermaid
+flowchart LR
+    T1["Tier 1: Core Automation<br/>POM, Live Probing, Repair"] --> T2["Tier 2: Enterprise Quality<br/>WCAG, Visual, Vitals"]
+    T2 --> T3["Tier 3: Context & AI Performance<br/>Token Optimization, Graphify"]
+    T3 --> T4["Tier 4: Architecture & CI/CD<br/>ADR, Sharding, GitHub Actions"]
+```
+
+1. **Tier 1 — Core Automation & Self-Healing:**
+   - Script generation, Clean POM flat architecture, live DOM probing via Playwright MCP, and in-place locator healing.
+2. **Tier 2 — Enterprise Quality Sentinel:**
+   - Accessibility audits (WCAG 2.2), Core Web Vitals profiling, visual regression comparisons, and synthetic data generation.
+3. **Tier 3 — AI Context Engineering & Diagnostics:**
+   - Attention-pattern protection, context degradation countermeasures, token optimization, and AST knowledge graph navigation.
+4. **Tier 4 — Architecture, CI/CD & Delivery:**
+   - Architecture Decision Records (ADRs), code refactoring and technical debt remediation, and containerized GitHub Actions CI/CD pipelines.
+
+---
+
+## 3. Flat Clean POM Architecture Pattern
+
+Test automation scripts orchestrated through this Hub enforce strict Clean POM boundaries:
+
+- **Rule 1 — Zero Selectors in Scripts:** Test scripts (`Scripts/` or `tests/`) must NEVER contain raw XPaths, CSS selectors, or `findTestObject` calls.
+- **Rule 2 — Single Inheritance:** All Page Classes inherit from `BasePage`, which standardizes smart waits, dynamic identifiers, and synthetic event dispatchers.
+- **Rule 3 — Dynamic Test Data Idempotency:** Every data entity must use dynamic prefixes generated via `BasePage.uniqueCode("PREFIX_")` to eliminate database key collisions during parallel execution.
+- **Rule 4 — In-Place Self-Healing:** If an element changes or breaks, only the affected Page Class is updated; test scripts remain untouched.
+
+---
+
+## 4. The 9 Quality Gates Definition-of-Done (DoD)
+
+All automated test code authored, modified, or refactored by AI agents must pass through the deterministic 9 Quality Gates pipeline (`tools/verify_all.py`) prior to committing or merging:
+
+| Gate | Title | Verifier Tool | Strict Acceptance Criteria |
+| :---: | :--- | :--- | :--- |
+| **Gate 0** | **Author Attribution & MIT Provenance** | `author_integrity.py` | Validates immutable MIT license and attribution to original author Thế Vị (@TeeVee998). |
+| **Gate 1** | **UTF-8 No BOM Clean Encoding** | `verify_all.py` | Scans 100% of repository files; zero BOM bytes (`0xEF, 0xBB, 0xBF`) and zero mojibake errors. |
+| **Gate 2** | **Path Portability** | `verify_all.py` | Rejects workstation-specific absolute paths (`/Users/...`, `C:\...`); mandates root-relative resolution. |
+| **Gate 3** | **Clean POM Flat Architecture** | `verify_all.py` | Enforces 100% locator encapsulation in Page Classes; strictly prohibits raw XPaths in test scripts. |
+| **Gate 4** | **AI Docs Anti-Drift** | `lint_ai_docs.py` | Reconciles real AST classes against `PROJECT_AI_GUIDE.md`; eliminates hallucinated PageClasses. |
+| **Gate 5** | **Temporary File Blacklist** | `verify_all.py` | Ensures zero build debris, memory dumps, or temporary sandbox databases leak into version control. |
+| **Gate 6** | **Credential Security** | `verify_all.py` | AST regex scan blocking hardcoded passwords, private keys, and secret tokens in code. |
+| **Gate 7** | **Static Defect & Fake-Pass Sentinel** | `infer_linter.py` | Detects 0-assertion tests, swallowed exception blocks (`except: pass`), hard sleeps, and unawaited promises. |
+| **Gate 8** | **Assertion Sensitivity Sentinel** | `micro_mutator.py` | Syntactic micro-mutations linked via variable dataflow; requires Sensitivity Score $\ge 80\%$. |
+
+---
+
+## 5. Architectural Boundaries & Non-Goals
+
+To maintain a lightweight, deterministic, and highly portable architecture, Synapse Hub establishes explicit boundaries:
+- **No Proprietary Test Runner:** Does not implement a replacement runner engine. Bridges natively with standard runners (Playwright, Pytest, Katalon/Gradle, Newman, JMeter).
+- **Zero AUT Source Code Modifications:** Operates exclusively within test specifications, Page Object models, mock definitions, and verification gates.
+- **Decoupled Stateless Hub:** Never writes persistent user credentials or proprietary corporate data to git.
+- **Target Language Agnostic:** Leverages Universal Intermediate Representation (Universal IR) to bridge TypeScript, Python, Groovy, and Java seamlessly.
+
+The Hub equips 6 specialized subagents with scoped tool and skill permissions:
+
+| Subagent Role | Primary Focus | Allowed Skills | Execution Tools |
+| :--- | :--- | :--- | :--- |
+| **`orchestrator`** | Task decomposition & governance | `agent-orchestration-multi-agent-optimize`, `graphify-impact-analyzer`, `architecture-decision-records`, `token-and-context-optimizer` | `verify_all.py`, `test_impact.py`, `setup_project.py` |
+| **`pom-crafter`** | Clean POM design & test generation | `clean-pom-crafter`, `lam-script-generator`, `synthetic-test-data-generator`, `api-spec-to-e2e-matrix` | `lookup_xpath.py`, `repo_map.py`, `generate_tc_from_story.py` |
+| **`live-explorer`** | Live DOM & AOM exploration (<200ms) | `playwright-live-interaction`, `self-healing-locator`, `visual-regression-sentinel`, `api-network-mocking-interception` | `browser_helpers.js`, `e2e_flow_prober.ps1`, `safety_firewall.py` |
+| **`test-runner`** | Headless CLI test execution & CI | `katalon-cli-runner`, `e2e-testing-patterns`, `flaky-test-sentinel-and-quarantine`, `backend-load-and-stress-patterns`, `github-actions-templates` | `matrix_sharder.py`, `distill_log.py`, `pinpoint_failure.py`, `flaky_detector.py` |
+| **`failure-analyst`**| Visual & XML error autopsy | `failure-autopsy-and-healing`, `self-healing-locator`, `file-and-report-validator` | `auto_heal.py`, `heal_pr_automator.py`, `pinpoint_failure.py`, `cache_resolver.py` |
+| **`quality-gatekeeper`**| 9 Gates DoD & Fake-Pass Sentinel | `antigravity-test-sentinel`, `code-refactoring-refactor-clean`, `wcag-audit-patterns`, `web-vitals-and-performance-profiler`, `security-dast-sentinel` | `verify_all.py`, `infer_linter.py`, `micro_mutator.py`, `trace_data_flow.py` |

package/docs/CI_CD_INTEGRATION.md

@@ -0,0 +1,94 @@
+# CI/CD Integration Guide — Synapse-Hub Enterprise QA
+
+This guide explains how to integrate Synapse-Hub quality gates (`verify_all.py`, `infer_linter`, AST mutator, Clean POM checks) directly into target project CI/CD pipelines without local filesystem dependencies.
+
+---
+
+## 1. Zero-Install NPX Integration (Recommended)
+
+Since `synapse-hub` is distributed via NPM Registry and GitHub Packages, target CI pipelines do not need to clone the hub repository manually. `npx` dynamically fetches and executes the CLI engine.
+
+### GitHub Actions Workflow (`.github/workflows/synapse_qa.yml`)
+
+```yaml
+name: Synapse QA Quality Gate
+
+on:
+  push:
+    branches: [ main, develop, master ]
+  pull_request:
+    branches: [ main, develop, master ]
+
+jobs:
+  quality-gate:
+    name: 9 Quality Gates DoD Verification
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Project Source
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js & Python
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Verify 9 Quality Gates
+        run: npx synapse-hub verify
+```
+
+### GitLab CI (`.gitlab-ci.yml`)
+
+```yaml
+synapse-qa-gate:
+  stage: test
+  image: node:20-bookworm
+  before_script:
+    - apt-get update && apt-get install -y python3 python3-pip
+  script:
+    - npx synapse-hub verify
+  rules:
+    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
+    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
+```
+
+---
+
+## 2. Git Submodule Integration (For Air-Gapped / Private SCM)
+
+If your enterprise network restricts public NPM registry access, mount `Synapse-Hub` as a Git Submodule inside the target repository:
+
+```bash
+# Add submodule into target project
+git submodule add https://github.com/TeeVee998/Synapse-Hub.git .synapse-hub
+```
+
+In your CI pipeline:
+```bash
+git submodule update --init --recursive
+python .synapse-hub/tools/verify_all.py
+```
+
+---
+
+## 3. Python Git / Pip Package Integration
+
+Target runners with Python 3.9+ can install `synapse-hub` directly from git:
+
+```bash
+pip install git+https://github.com/TeeVee998/Synapse-Hub.git
+agent-qa verify
+```
+
+---
+
+## 4. Available CI Subcommands
+
+| Command | Purpose | SLA / Exit Code |
+| :--- | :--- | :--- |
+| `npx synapse-hub verify` | Executes all 9 Quality Gates DoD | Exits `0` if all PASS; non-zero if any FAIL. |
+| `npx synapse-hub lint` | Meta Infer-style static defect and fake-pass scan | Fails if 0-assert tests or empty catches exist. |
+| `npx synapse-hub mutate --min-score 80` | Syntactic Micro-Mutation verification | Fails if test assertion score < 80%. |
+| `npx synapse-hub analyze` | Comprehensive 5-in-1 health audit | Outputs health score and JSON/Markdown artifacts. |

package/docs/CLI_REFERENCE.md

@@ -0,0 +1,157 @@
+# Agent-QA CLI & Tools Reference Manual
+
+The `agent-skills` Hub provides a unified CLI utility `agent-qa` (and direct python scripts in `tools/`) to execute quality gates, linting, impact analysis, and log distillation.
+
+---
+
+## 1. Unified CLI Entrypoint (`agent-qa`)
+
+When installed via `pip install -e .`, the `agent-qa` command is globally accessible:
+
+```bash
+agent-qa <command> [options]
+```
+
+### Supported Commands (51 Subcommands)
+
+#### A. Core Quality & DoD Gates
+| Command | Subsystem | Description | Example |
+| :--- | :--- | :--- | :--- |
+| `verify` | Quality Sentinel | Executes all 9 Quality Gates DoD validation | `synapse-hub verify` |
+| `lint` | Static Analysis | Polyglot heuristic & static AST defect scanner with baseline & suppression | `synapse-hub lint ./tests` |
+| `mutate` | Mutation Sentinel | Syntactic micro-mutator checking assertion sensitivity | `synapse-hub mutate ./tests --min-score 80` |
+| `watch` | HUD Sentinel | Incremental live file watcher for real-time quality feedback | `synapse-hub watch` |
+| `wcag-audit` | Accessibility | WCAG 2.2 accessibility conformance and contrast auditor | `synapse-hub wcag-audit ./reports/WELCOME.html` |
+| `trace-data-flow` | Data Flow | Taint analysis tracing test data lifecycles to detect DB leaks | `synapse-hub trace-data-flow ./tests` |
+| `verify-author` | Provenance Guard | Validates canonical author attribution watermark | `synapse-hub verify-author` |
+
+#### B. Diagnostics, Onboarding & Visual Landing
+| Command | Subsystem | Description | Example |
+| :--- | :--- | :--- | :--- |
+| `doctor` | Environment Audit | 1-click diagnostic for Node.js, Python, Chrome, Git | `synapse-hub doctor` |
+| `welcome` | Visual Landing | Launches interactive bilingual landing page in browser | `synapse-hub welcome` |
+| `setup` | Project Setup | Bootstraps project, generates AI Guide & AI Bridges | `synapse-hub setup --local-only` |
+| `uninstall` | Clean Removal | Cleanly removes AI Bridges, hooks, and local configurations | `synapse-hub uninstall` |
+| `sync-rules` | AI Bridge Sync | Synchronizes AGENTS.md rules across all IDE assistants | `synapse-hub sync-rules` |
+| `version` | Hub Metadata | Displays installed Hub version and catalog summary | `synapse-hub version` |
+| `update` | Auto-Update | 1-click upgrade engine syncing latest upstream changes | `synapse-hub update` |
+| `clean` | Artifact Janitor | Cleans up temporary artifacts, cache files, and logs | `synapse-hub clean` |
+
+#### C. Self-Healing, Triage & Token Optimization
+| Command | Subsystem | Description | Example |
+| :--- | :--- | :--- | :--- |
+| `heal` | Semantic Memory | Queries zero-token semantic error memory cache | `synapse-hub heal query "StaleElement"` |
+| `auto-heal` | Closed-Loop | Autonomous test healing engine parsing JUnit failures | `synapse-hub auto-heal` |
+| `heal-pr` | PR Automator | Creates automated Git branch and PR with healing patch | `synapse-hub heal-pr --branch heal/fix-login` |
+| `distill` | Token Optimizer | Filters verbose CLI/Gradle/CI logs by 95% | `synapse-hub distill build.log` |
+| `pinpoint-failure` | Failure Autopsy | Parses JUnit XML reports and locates exact failing lines in 0.1s | `synapse-hub pinpoint-failure report.xml` |
+| `flaky` | Quarantine | Detects non-deterministic flaky tests and manages quarantine | `synapse-hub flaky --detect` |
+| `lookup-tc` | TC Index | Searches test cases by ID, tag, priority, or flow name | `synapse-hub lookup-tc TC-101` |
+| `lookup-xpath` | Selector Cache | Queries cached resilient XPath & AOM element locators | `synapse-hub lookup-xpath "Submit"` |
+| `impact` | AST Knowledge | Analyzes blast radius of git code changes | `synapse-hub impact --git-diff` |
+| `canary` | Resilience Arena | Injects failure vectors to test autonomous recovery MTTR | `synapse-hub canary --run` |
+| `report-bug` | Bug Triage | Generates structured Markdown/Jira defect reports from RCA | `synapse-hub report-bug --junit report.xml` |
+| `ci-hook` | CI Integration | CI/CD hook executing automated triage on build failure | `synapse-hub ci-hook --log ci.log` |
+| `tokens` | Token Counter | Measures prompt tokens across files and subagent contexts | `synapse-hub tokens path/to/prompt.md` |
+
+#### D. API, Performance & Security Testing
+| Command | Subsystem | Description | Example |
+| :--- | :--- | :--- | :--- |
+| `fuzz-api` | Security Fuzzer | Non-production API security, boundary, and chaos fuzzer | `synapse-hub fuzz-api --spec openapi.json` |
+| `contract-drift` | Drift Sentinel | Detects breaking changes and schema drift in API specs | `synapse-hub contract-drift --baseline v1.json --current v2.json` |
+| `generate-jmx` | Load Testing | Compiles User Story / API specs into Apache JMeter JMX plan | `synapse-hub generate-jmx --threads 50` |
+| `analyze-jtl` | Load Analysis | Parses JMeter JTL execution logs and asserts SLA thresholds | `synapse-hub analyze-jtl results.jtl` |
+| `analyze-newman` | Postman Audit | Analyzes Newman execution JSON reports for API quality | `synapse-hub analyze-newman newman_run.json` |
+| `export-postman` | Collection Gen | Exports API specification into Postman Collection v2.1 | `synapse-hub export-postman --spec swagger.json` |
+| `mock-shield` | Route Mocking | Generates Playwright network route mocks from API specs | `synapse-hub mock-shield --spec openapi.json` |
+| `skillspector` | AI Security | Audits AI Agent skills and MCP configs for prompt injection | `synapse-hub skillspector --dir .agents/skills` |
+| `safety-check` | Firewall Guard | Dry-run code snippet analysis for destructive UI actions | `synapse-hub safety-check --snippet "btn.click()"` |
+
+#### E. Code Generation, Transpilation & Formatting
+| Command | Subsystem | Description | Example |
+| :--- | :--- | :--- | :--- |
+| `generate-tc` | Story Compiler | Compiles natural language user stories into Clean POM test cases | `synapse-hub generate-tc story.md` |
+| `export-excel` | Excel Reporter | Converts Markdown test cases to standard 12-column Excel | `synapse-hub export-excel` |
+| `gherkin` | BDD Compiler | Compiles Gherkin .feature specs into executable suites | `synapse-hub gherkin specs/checkout.feature` |
+| `transpile` | Omni Transpiler | Transpiles test code between Playwright, Pytest, Katalon | `synapse-hub transpile tests/spec.ts --to pytest` |
+| `omni-scan` | Engine Scanner | Scans polyglot repositories for test framework presence | `synapse-hub omni-scan` |
+| `shard` | Matrix Sharder | Partitions test suites across parallel CI runners | `synapse-hub shard ./tests --runners 4` |
+| `visual-mask` | Visual Sentinel | Computes anti-flake coordinate masks for visual testing | `synapse-hub visual-mask screenshot.png` |
+| `som` | Vision Testing | Visual Set-of-Marks helper for interactive elements | `synapse-hub som screen.png` |
+| `decouple-config`| Config Isolator | Decouples environment variables and credentials from code | `synapse-hub decouple-config config.groovy` |
+| `correlate-telemetry` | Correlator | Correlates browser traces, HTTP logs, and server logs | `synapse-hub correlate-telemetry --trace trace.zip` |
+| `dashboard` | Project HUD | Generates standalone HTML5 executive health dashboard | `synapse-hub dashboard` |
+| `analyze` | Health Audit | Comprehensive 5-in-1 repository health and DoD audit | `synapse-hub analyze` |
+| `mcp-serve` | MCP Server | Launches Model Context Protocol (MCP) server over stdio | `synapse-hub mcp-serve` |
+
+---
+
+## 2. Direct Python Scripts Runbook
+
+If running without global package installation, tools can be executed directly via Python:
+
+### 2.1. Verify 9 Quality Gates (Gate 0 - Gate 8)
+```bash
+# Auto-detect mode (default: detects Hub vs Target Test Project)
+python tools/verify_all.py
+
+# Explicit mode selection
+python tools/verify_all.py --mode hub      # QA Hub integrity validation
+python tools/verify_all.py --mode target   # Target automation suite validation
+```
+- **Operational Modes:**
+  - `--mode hub`: Validates QA Hub assets, skills, tools integrity, zero BOM, path portability, and universal credential security across repository files without requiring target test scripts.
+  - `--mode target`: Enforces target automation suite standards including Clean POM across test scripts and credential encryption.
+- **Gate 0:** Author Attribution & Provenance Guard (preserves MIT author notice).
+- **Gate 1:** 100% UTF-8 No BOM check across all scripts, markdown, and config files.
+- **Gate 2:** Path Portability (zero absolute host/machine directory paths).
+- **Gate 3:** Clean POM & Flat Architecture (zero raw XPaths/CSS in test scripts).
+- **Gate 4:** AI Docs & Artifacts Anti-Drift check (zero hallucinated tools/classes).
+- **Gate 5:** Temporary file and properties artifact cleanup.
+- **Gate 6:** Credential Security & Secret Scanner (zero hardcoded plaintext passwords or API tokens).
+- **Gate 7:** Static Defect & AST Fake-Pass Sentinel.
+- **Gate 8:** Syntactic Micro-Mutation Sentinel (Requires Mutation Score >= 80%).
+
+### 2.2. AST Fake-Pass Sentinel
+```bash
+python tools/infer_linter.py
+```
+
+### 2.3. Semantic Memory Cache & Negative Feedback Blacklist
+```bash
+# Initialize database with seed solutions and forbidden anti-patches
+python tools/cache_resolver.py init
+
+# Query pre-tested patches AND retrieve blacklisted anti-patches (0 tokens)
+python tools/cache_resolver.py query --error "ElementClickInterceptedException"
+
+# Learn a verified working solution (Positive Memory)
+python tools/cache_resolver.py learn --error "Timeout" --cause "Slow API" --patch "waitForNetworkIdle()" --symptom "Spinner"
+
+# Record a failed bug fix attempt into blacklist (Negative Memory)
+python tools/cache_resolver.py record-failed --error "StaleElement" --patch "sleep(5000)" --reason "Still fails under network latency"
+```
+
+### 2.4. Log Distiller
+```bash
+python tools/distill_log.py execution.log
+```
+
+---
+
+## 3. Standard Exit Code Specification & Terminal Environment
+
+Synapse Hub adheres to deterministic, standardized UNIX exit codes across all CLI tools:
+
+| Exit Code | Constant Name | Description | Typical Remediation |
+| :---: | :--- | :--- | :--- |
+| **`0`** | `EXIT_SUCCESS` | Operation passed; all Quality Gates satisfied; 0 critical defects. | Proceed to next pipeline stage or commit. |
+| **`1`** | `EXIT_FAILURE` | Quality Gate rejection; test execution failure; linter defect found. | Review failing check details; fix unasserted or swallowed code. |
+| **`2`** | `EXIT_USAGE_ERROR` | Invalid CLI arguments; unknown subcommand; syntax error. | Check command syntax via `--help`. |
+| **`3`** | `EXIT_SECURITY_BLOCK` | Destructive action blocked by safety firewall; secret token leak; MIT license modified. | Review security violation; set `ALLOW_DESTRUCTIVE=1` if intentional. |
+| **`4`** | `EXIT_ENVIRONMENT_ERROR` | Incompatible runtime; missing required tool (e.g. Python < 3.9). | Install recommended runtime (Python 3.10+, Node 20+). |
+
+### Terminal Environment Standards:
+- **`NO_COLOR` Support:** In accordance with [no-color.org](https://no-color.org), setting the `NO_COLOR` environment variable automatically suppresses all ANSI color escape sequences.
+- **`--quiet` / `-q` Flag:** Pass `-q` or `--quiet` to suppress informational banners and output only critical verdicts or machine-readable results.
+- **Machine-Readable Formats:** Use `--format json`, `--format sarif`, or `--format junit` for clean, parseable pipeline outputs.

package/docs/CONTRIBUTING.md

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