synapse-hub 2.5.0 → 2.7.0

package/.agents/rules/performance_testing_rules.md

@@ -1,74 +1,30 @@
 # Performance & Load Testing Invariants (k6 · JMeter · Locust)
 
 > **Scope:** Applies whenever designing, executing, or analyzing performance, load, stress, spike, or soak test workloads.  
-> These invariants complement `AGENTS.md` and enforce enterprise safety, workload realism, and zero-hallucination analysis.
+> Complement to `AGENTS.md` enforcing enterprise safety, workload realism, and zero-hallucination analysis.
 
 ---
 
-## 1. Safety Gate & Approval Invariants (Mandatory Pre-Flight)
-
-1. **Explicit Authorization:**
-   - Execute load tests **only** against pre-approved, dedicated environments (performance test environment or isolated sandbox).
-   - **Strictly forbidden:** Running load tests against production, shared staging, public demo sites, or third-party APIs without formal written sign-off.
-2. **Pre-Run Declaration:**
-   - Prior to any execution above Smoke test, the agent must declare the run profile and wait for explicit confirmation:
-     - Target host and environment owner
-     - Test archetype (Smoke, Average Load, Stress, Spike, Soak)
-     - Load profile (max VUs, target iterations/sec or requests/sec, duration, ramp-up/down phases)
-     - Data volume created and teardown strategy
-     - Kill-switch threshold (`abortOnFail`)
-3. **Progressive Stepped Escalation:**
-   - Always adhere to progressive ramp-up: **Smoke (1–5 VUs) → Baseline Average Load → Stress / Spike / Soak**.
-   - Never initiate Stress, Spike, Soak, or Breakpoint runs autonomously.
-4. **Hard Caps & Kill-Switch:**
-   - Every script must enforce hard upper bounds on rate and VUs, finite duration, and an automatic abort condition (`abortOnFail` when error rate breaches acceptable thresholds, e.g., > 10%).
-   - Unbounded loops or infinite duration scripts are strictly prohibited.
-5. **Third-Party Isolation:**
-   - Mock or stub third-party external dependencies (Payment Gateways, SMS providers, email senders, CAPTCHA, web analytics). Never send synthetic load to unisolated external partners.
-6. **Data Safety & Idempotent Cleanup:**
-   - Write traffic must use isolated, synthetic test data with recognizable prefixes (e.g., `PERF_AUTO_`, `PERF-`). Real customer credentials or PII must never be used.
-   - Every creation run must be paired with an automated teardown or ephemeral DB rollback.
+## 1. Safety Gate & Pre-Flight Invariants
+1. **Dedicated Environments Only:** Never run load tests against production, shared staging, or third-party APIs without written approval.
+2. **Pre-Run Declaration:** Declare target host, archetype (Smoke, Average Load, Stress, Spike, Soak), VU/arrival profile, duration, and kill-switch threshold (`abortOnFail`).
+3. **Progressive Escalation:** Smoke (1–5 VUs) -> Baseline Average Load -> Stress / Spike / Soak. Never start high-VU runs autonomously.
+4. **Hard Caps & Kill-Switch:** Scripts must enforce finite durations, rate caps, and automated abort (`abortOnFail` when error rate > 10%). Unbounded loops are strictly forbidden.
+5. **Isolation & Cleanup:** Mock third-party providers (Payment, SMS, Captcha). Use synthetic test data (`PERF_AUTO_`); teardown after runs.
 
 ---
 
-## 2. Workload Modeling Invariants
-
-1. **Open vs. Closed Model:**
-   - **Open Model (Arrival Rate):** Use arrival-rate executors for public web traffic or SLA requirements stated in rate (e.g., `N req/sec`). Real users arrive independently of system slowdown.
-   - **Closed Model (Virtual Users):** Use VU-based executors only when modeling fixed concurrent sessions (e.g., internal enterprise portals).
-2. **Realistic Think Time:**
-   - Model user think time between journey steps using realistic distributions (e.g., Gaussian or uniform 1s–5s). Zero-think-time "hammer" testing is forbidden unless specifically requested for denial-of-service resilience audits.
-3. **Data Realism & Cache Skew Prevention:**
-   - Parameterize query parameters, identifiers, and payloads across realistic key spaces. Repeatedly querying identical records measures database cache hit rates rather than true backend capability.
-4. **Phase-Based Evaluation:**
-   - Structure tests into `Ramp-Up`, `Steady State`, and `Ramp-Down` phases.
-   - Compute SLA thresholds and verdicts **strictly against the Steady State**, never against warm-up or cool-down transients.
+## 2. Workload Modeling & k6 Script Standards
+1. **Arrival Rate vs VU:** Use open arrival-rate executors for public traffic; use closed VU-based executors only for fixed employee portals.
+2. **Realistic Think Time & Cache Skew:** Parameterize queries across realistic key spaces. Model user think time (1s–5s); zero think time is forbidden.
+3. **Steady-State Evaluation:** Evaluate SLA thresholds strictly against Steady State, excluding warm-up/cool-down transients.
+4. **k6 Script Structure:** `options` -> `setup()` -> default VU function (`check()`) -> `teardown()`.
+   - Valid threshold syntax: `'http_req_duration{expected_response:true}': ['p(95)<500']`.
+   - Always pair `check()` with `'checks': ['rate>0.99']`.
+   - Set `discardResponseBodies: true` when responses are unparsed. Pass secrets via `__ENV`.
 
 ---
 
-## 3. k6 Script Engineering Standards
-
-1. **Script Structure:**
-   - `options` (profile, stages, thresholds) → `setup()` (one-time auth and shared state) → default function (user journey with `check()` calls) → `teardown()` (cleanup).
-2. **Valid Threshold Syntax:**
-   - Use standard k6 threshold syntax: `metric{tag:value}: ['p(95)<500']`. Braces contain tag filters only.
-   - Latency thresholds must evaluate successful responses: `'http_req_duration{expected_response:true}': ['p(95)<500', 'p(99)<1000']`.
-   - Always pair `check()` with a `checks` threshold (e.g., `'checks': ['rate>0.99']`), as unasserted check failures do not alter k6 exit codes.
-3. **Generator Efficiency:**
-   - Set `discardResponseBodies: true` when response bodies are not required for subsequent extractions, minimizing memory overhead on the load generator.
-4. **Strict Credential Hygiene:**
-   - Pass tokens, usernames, and base URLs via environment variables (`__ENV.BASE_URL`). Never hardcode secrets in test plans or committed repository scripts.
-
----
-
-## 4. Truth Anchor & Performance Autopsy Protocol
-
-1. **No Lowering Thresholds (Truth Anchor):**
-   - If an SLA threshold is breached, report the failure with root causes. **Never loosen thresholds, truncate steady states, or drop samples to manufacture a false pass.**
-2. **Structured Analysis Sequence:**
-   - Analyze results in strict sequence:
-     1. **Run Validity:** Confirm `dropped_iterations == 0` and generator CPU remained < 80%. If the generator was saturated, mark the run INVALID.
-     2. **Error Rate:** Categorize HTTP 4xx, 5xx, timeouts, connection resets.
-     3. **Latency Percentiles:** Report P50, P90, P95, P99, and Max. Never headline average latency.
-     4. **Throughput:** Compare target requests/sec vs. achieved requests/sec.
-     5. **Correlation:** Correlate breaches with backend APM traces (database slow queries, GC pauses, connection pool exhaustion) before attributing root causes.
+## 3. Truth Anchor & Autopsy Sequence
+1. **Truth Anchor:** If an SLA is breached, report root cause honestly. Never loosen thresholds or drop samples to manufacture a fake pass.
+2. **Analysis Sequence:** 1. Run Validity (`dropped_iterations == 0`, generator CPU < 80%) -> 2. Error Rate (4xx, 5xx, timeouts) -> 3. Latency Percentiles (P50, P90, P95, P99; never headline average) -> 4. Throughput -> 5. APM Correlation (DB slow queries, connection pool exhaustion).

package/.agents/rules/skill-precedence.md

@@ -5,58 +5,38 @@ description: Skill Resolution Precedence, Inter-Skill Coordination, and Anti-Col
 
 # Skill Resolution Precedence & Anti-Collision Protocol
 
-> **Purpose:** Resolve overlapping trigger scopes between Project-Local Skills and External Plugins, as well as distinct operational boundaries among internal skills — eliminating context contagion, token bloat, and conflicting instructions.
+> **Purpose:** Resolve overlapping trigger scopes between Project-Local Skills and External Plugins, eliminating context contagion, token bloat, and conflicting instructions.
 
 ---
 
-## 1. Non-Negotiable Precedence Order
-
-When executing tasks within automated testing repositories, all AI Agents must strictly apply the following 3-tier hierarchy:
-
-```text
-[Tier 1: Project-Local Skills] (.agents/skills/*) 
-       v (Highest priority — Specialized, Context-Aware & Clean POM Enforced)
-[Tier 2: Core Project Rules] (.agents/rules/*)
-       v (Mandatory operating invariants & behavioral guardrails)
-[Tier 3: External Plugin Skills] (antigravity-testing-kit, chrome-devtools-plugin, generic plugins)
-       v (Suppressed whenever a Tier 1 skill exists)
-```
+## 1. Non-Negotiable 3-Tier Precedence Order
+`[Tier 1: Project-Local Skills] (.agents/skills/*)` > `[Tier 2: Core Rules] (.agents/rules/*)` > `[Tier 3: External Plugins] (generic plugins)`.
+Whenever a Tier 1 local skill exists, the external plugin skill is **strictly suppressed**.
 
 ---
 
-## 2. External Plugin Suppression Matrix (Tier 1 vs Tier 3)
-
-When an external plugin offers a capability that overlaps with a specialized Synapse Hub skill, the external skill is **strictly suppressed**:
-
-| Task Domain | REQUIRED Skill (Tier 1) | SUPPRESSED Skill (Tier 3) | Architectural Reason |
-|---|---|---|---|
-| **POM & Test Authoring** | `clean-pom-crafter`<br/>`lam-script-generator` | `QA Automation Engineer`, `Test Generator` | Generic plugins generate raw XPaths and Selenium boilerplate; Hub strictly enforces Flat Architecture and zero raw locators in scripts. |
-| **Code Change Review** | `senior-code-review` | `Generic PR Reviewer`, `Code Reviewer` | Evaluates 6 pillars (Bugs, Security, Concurrency, Missing Tests, Speed, Bloat) specifically against Git Diff. |
-| **Locator Healing & Diffing** | `self-healing-locator`<br/>`failure-autopsy-and-healing` | `Locator Healer Agent` | Uses token-efficient semantic AOM diffing (Role > Label > TestId) instead of dumping thousands of raw HTML lines. |
-| **Flaky Test Triage & RCA** | `failure-autopsy-and-healing`<br/>`flaky-test-sentinel-and-quarantine` | `Flaky Test Analyzer` | Triage occurs via 0-token JUnit XML parsing, screenshot autopsy, and SQLite episodic memory cache (`global_cache.db`). |
-| **Live Probing & Inspection** | `playwright-live-interaction` | `Smart Locator Agent` | Direct CDP network idle 0, dynamic overlay detachment, and in-browser helper integration under 200ms. |
-| **Accessibility (WCAG)** | `wcag-audit-patterns` *(Guideline)* | `a11y-debugging` *(Tooling Only)* | `wcag-audit-patterns` enforces WCAG 2.2 A/AA criteria; Chrome DevTools MCP is used strictly for low-level node inspection. |
+## 2. External Plugin Suppression Rules (Tier 1 overrides Tier 3)
+- **POM & Test Authoring:** Use `clean-pom-crafter` / `lam-script-generator`. Suppress generic QA/test plugins. Flat Clean POM only; no raw XPaths in test scripts.
+- **Code Review:** Use `senior-code-review` (6 pillars against git diff). Suppress generic PR reviewers.
+- **Locator Healing:** Use `self-healing-locator` / `failure-autopsy-and-healing` (AOM diffing). Suppress generic locator healers.
+- **Flaky Test Triage:** Use `flaky-test-sentinel-and-quarantine` (episodic SQLite memory + JUnit parsing).
+- **Live Probing:** Use `playwright-live-interaction` (CDP idle 0 under 200ms). Suppress generic smart locators.
+- **Accessibility:** Use `wcag-audit-patterns` for WCAG 2.2 A/AA criteria; use Chrome DevTools MCP strictly for low-level node inspection.
 
 ---
 
-## 3. Internal Inter-Skill Coordination & Boundary Separation
-
-To prevent decision paralysis among internal skills in `.agents/skills/`, agents must strictly adhere to the following boundary matrix:
-
-| Functional Area | Primary Skill | Sibling Skill | Distinct Responsibility & Hand-Off |
-|---|---|---|---|
-| **Code Creation** | `lean-code-ladder` | `surgical-coding-principles` | • `lean-code-ladder` governs **what to build** (descends 7-rung ladder, selects smallest working solution).<br/>• `surgical-coding-principles` governs **where to touch** (keeps git diff surgical, no unrelated file edits). |
-| **Technical Debt** | `technical-debt-harvester` | `code-refactoring-refactor-clean` | • `technical-debt-harvester` is the **accountant** (scans and tracks `shortcut:` comments in Markdown ledgers).<br/>• `code-refactoring-refactor-clean` is the **surgeon** (executes SOLID refactoring and code smell remediation). |
-| **Quality Review** | `senior-code-review` | `review-spec` (`goldfish_review`) | • `senior-code-review` audits **Source Code Diffs** (uncommitted / staged git changes).<br/>• `review-spec` audits **Requirements & User Stories** in a 0-context stress-test (Elephant-Goldfish model). |
-| **System Audit** | `repo-quality-audit` | `analyze_project` (`tools/`) | • `analyze_project.py` produces **deterministic facts** (AST map, env check, data flow, 9 gates DoD).<br/>• `repo-quality-audit` applies **senior engineering judgment** (evaluates real load, ranks *"Fix #1 first"*). |
-| **API Testing** | `api-spec-to-e2e-matrix` | `api-network-mocking-interception` | • `api-spec-to-e2e-matrix` compiles **test matrices** from OpenAPI specs.<br/>• `api-network-mocking-interception` stubs routes and injects **chaos network faults** during UI/API test runs. |
-| **Failure Analysis** | `self-healing-locator` | `failure-autopsy-and-healing` | • `self-healing-locator` fixes **individual broken Page Class selectors**.<br/>• `failure-autopsy-and-healing` triages **suite-wide run crashes**, JUnit XML reports, and logs. |
-| **DoD Verification** | `verification-before-completion` | `antigravity-test-sentinel` | • `verification-before-completion` enforces the **evidence protocol** (fresh command output required in session).<br/>• `antigravity-test-sentinel` is the **hard gatekeeper** (blocks task completion until all 9 Quality Gates pass). |
+## 3. Internal Inter-Skill Coordination & Boundaries
+- **Code Authoring:** `lean-code-ladder` decides *what* to build (7-rung ladder); `surgical-coding-principles` restricts *where* to touch (surgical git diff).
+- **Technical Debt:** `technical-debt-harvester` tracks `shortcut:` markers; `code-refactoring-refactor-clean` executes refactoring.
+- **Quality Review:** `senior-code-review` audits source diffs; `review-spec` audits requirements/stories (0-context stress test).
+- **System Audit:** `tools/analyze_project.py` gathers facts (AST, env, gates); `repo-quality-audit` prioritizes "Fix #1 first".
+- **API Testing:** `api-spec-to-e2e-matrix` compiles test matrices; `api-network-mocking-interception` stubs routes and chaos faults.
+- **Failure Analysis:** `self-healing-locator` heals individual locators; `failure-autopsy-and-healing` triages suite-wide crashes.
+- **DoD Gatekeeper:** `verification-before-completion` checks fresh command evidence; `antigravity-test-sentinel` enforces all 10 gates.
 
 ---
 
 ## 4. Strict Prohibitions
-
-1. **Zero Generic Test Boilerplate:** Never generate legacy Selenium, Cucumber, or Object Repository (`findTestObject`) code from external plugins.
-2. **Zero Raw HTML Dumps:** Never dump full HTML trees into context for locator healing; always extract compact AOM subtrees (< 500 tokens).
-3. **Zero Unverified Assertions:** Never complete a code or test task without executing fresh verification via `tools/verify_all.py`.
+1. **Zero Generic Boilerplate:** Never generate legacy Selenium, Cucumber, or `findTestObject` code.
+2. **Zero Raw HTML Dumps:** Extract compact AOM subtrees (< 500 tokens); never dump raw HTML trees.
+3. **Zero Unverified Assertions:** Never complete tasks without running fresh verification via `tools/verify_all.py`.

package/.agents/rules/systematic-debugging.md

@@ -31,7 +31,7 @@ This rule governs all AI Agents operating on the repository. It mandates strict
      ```bash
      python3 tools/verify_all.py
      ```
-   - All 9 Gates must return `PASS`. If any gate fails, the task is NOT complete.
+   - All 10 Gates must return `PASS`. If any gate fails, the task is NOT complete.
 2. **Targeted Re-Test:**
    - After modifying Page Classes, check impacted Test Cases with:
      ```bash
@@ -46,34 +46,15 @@ This rule governs all AI Agents operating on the repository. It mandates strict
 
 ## 3. Situational Tool Dispatch Matrix & Zero-Command Autonomy
 
-> 🚀 **Zero-Command Autonomous Invariant (Zero Manual Commands):**  
-> The user **NEVER** needs to remember syntax or manually type tool commands (`agent-qa setup`, `agent-qa analyze`, `verify_all.py`...).  
-> The AI Agent **MUST AUTONOMOUSLY recognize context and trigger** the corresponding tools below on-demand whenever the situation arises.  
->  
-> 🎯 **On-Demand Activation Principle (Situation-Specific — Never Run Blindly):**  
-> Tools assigned to AI and Subagents are **situational weapons**, **NEVER executed all at once**. Agents draw the specific tool from the arsenal if and only if a concrete need arises (e.g.: failing test triggers `auto_heal`, new project triggers `setup_project`, API breaking change triggers `api_drift_sentinel`).
-
-| Context / Trigger | Mandatory Tool | Specific Objective |
-| :--- | :--- | :--- |
-| **New project / Missing `PROJECT_AI_GUIDE.md` / Fresh clone** | `python3 tools/setup_project.py [target]` | 100% Autonomous: Detects framework (Playwright/Katalon/Pytest), generates `PROJECT_AI_GUIDE.md`, installs `pre-push` hook, extracts `repo_map.txt`, runs initial audit. |
-| **User requests: "analyze project" / "re-analyze" / "project audit"** | `python3 tools/analyze_project.py [target]` | Execute comprehensive 5-in-1 health audit, sync repo_map, infer_linter, data_flow, verify_all & generate PROJECT_HEALTH_REPORT.md.<br/>**Post-Action:** Stage, commit & push updated project files (`PROJECT_HEALTH_REPORT.md`, `repo_map.txt`) to git. |
-| **User requests: "review code" / "review diff" / "senior review"** | `python3 tools/senior_code_review.py` | 6-pillar code change review (Bugs, Security, Concurrency, Missing Tests, Speed, Bloat). |
-| **User requests: "scan debt" / "list shortcuts" / "harvest debt"** | `python3 tools/debt_harvester.py` | Harvest `shortcut:` technical debt markers across repo into tracked markdown ledger. |
-| **Starting task / Querying Page Class methods** | `tools/repo_map.txt`<br/>*(run `python3 tools/repo_map.py` if classes changed)* | Read compressed 500-token map for signatures; avoid reading 4,000-line files. |
-| **Dispatching Browser Actions (Live/CDP)** | `python3 tools/safety_firewall.py --dry-run` | Mandatory Pre-execution Hook: Block irreversible/destructive operations before browser dispatch. |
-| **Creating or updating Test Scripts** | `python3 tools/infer_linter.py` | Run AST scan for Fake-Pass (0 asserts) and empty catch blocks. |
-| **New/Modified Test Case Quality** | `python3 tools/micro_mutator.py --min-score 80` | AST Mutation Testing: Reject test suites with mutation score < 80%. |
-| **Before Git Commit or Completing Task** | `python3 tools/verify_all.py` | Validate all 9 Quality Gates DoD. |
-| **After modifying Page Classes** | `python3 tools/test_impact.py --git-diff` | Scope impacted test cases; avoid re-running entire test suites. |
-| **When Test FAILS in CLI/KRE** | `python3 tools/pinpoint_failure.py` | Parse JUnit XML to identify exact failing line and exception in 0.1s. |
-| **When CLI / Gradle logs are verbose** | `python3 tools/distill_log.py <log>` | Filter 95% noise; preserve only actionable stacktraces and pointers. |
-| **Handling UI exceptions (Overlay, Stale)** | `python3 tools/cache_resolver.py query "<error>"` | Lookup 0-token solution from local SQLite memory cache before improvising. |
-| **Pre-Push / Suite Acceptance** | `python3 tools/trace_data_flow.py` | Run Taint Analysis to verify no orphan database junk remains uncleaned. |
-| **Canary Self-Healing Audit** | `python3 tools/agent_canary.py --run` | Inject 8 failure vectors to benchmark MTTR and autonomous recovery rate. |
-| **Testing GIS Canvas / Chart without DOM** | `python3 tools/visual_diff_canvas.py` | Compare pixel / SSIM to detect visual rendering regression. |
-| **Pulling code / New clone** | `python3 tools/cache_resolver.py init` | Automatically sync Central Agent Memory (`~/.agent_memory/global_cache.db`). |
-| **Before authoring test for Page/Flow** | `python3 tools/cache_resolver.py get-lessons --context "<page>"` | Query top 2 episodic lessons learned to avoid repeating past failure patterns. |
-| **After healing a bug / failure** | `python3 tools/cache_resolver.py record-lesson` | Record a concise 2-line lesson into SQLite memory for cross-session reflexion. |
+> 🚀 **Zero-Command Autonomous Invariant:** The user **NEVER** needs to manually type tool commands. The AI Agent **MUST AUTONOMOUSLY recognize context and trigger** the corresponding tools on-demand. Never run tools blindly; invoke only when the concrete situation arises.
+
+- **Setup & Audit:** New project -> `tools/setup_project.py`; Project audit -> `tools/analyze_project.py`; Code review -> `tools/senior_code_review.py`; Debt scan -> `tools/debt_harvester.py`.
+- **Quality Gates & DoD:** Pre-commit/Handoff -> `tools/verify_all.py` (10 Gates DoD); Script lint -> `tools/infer_linter.py`; Mutation testing -> `tools/micro_mutator.py --min-score 80`.
+- **Failure Autopsy & Healing:** Test failure -> `tools/pinpoint_failure.py` (parse JUnit XML in 0.1s); Iterative repair -> `tools/auto_heal_reflexion.py`; Reversible rollback -> `tools/reversible_sandbox.py`.
+- **Context & Safety:** Verbose logs -> `tools/distill_log.py`; Destructive browser actions -> `tools/safety_firewall.py`; Method signatures -> `tools/repo_map.txt`.
+- **Memory & Reflexion:** UI exceptions -> `tools/cache_resolver.py query "<error>"`; Query/Save proven patterns -> `tools/skill_vault.py`.
+
+*(For the complete CLI parameters and full tools catalog, refer to [tools/TOOLS_RUNBOOK.md](file://tools/TOOLS_RUNBOOK.md)).*
 
 ---
 

package/.agents/skills/actor-qa-swarm/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: actor-qa-swarm
+description: "Asynchronous Actor Model message broker and matrix sharding coordinator for multi-agent test execution. Use when distributing parallel test workloads or wiring decoupled subagent event pub/sub."
+---
+
+# Actor QA Swarm Skill — Asynchronous Actor Messaging & Matrix Sharding
+
+> **Paradigm Attribution:** Inspired by **Microsoft AutoGen v0.4+ (AG2 Actor Framework)**.  
+> **Core Principle:** Transition from synchronous lock-step file coordination to an asynchronous Actor Model. Subagents exchange messages via non-blocking mailboxes and subscribe to test failure events in real time.
+
+---
+
+## 1. The Actor Swarm Architecture
+
+```mermaid
+flowchart TD
+    Orchestrator["Orchestrator Actor"] -->|dispatch-shards| Broker["Actor QA Message Broker (tools/autogen_qa_broker.py)"]
+    Broker -->|ASSIGN_SHARD| W1["test-runner:worker_1 (Playwright Shard 1)"]
+    Broker -->|ASSIGN_SHARD| W2["test-runner:worker_2 (Playwright Shard 2)"]
+    Broker -->|ASSIGN_SHARD| W3["test-runner:worker_3 (Playwright Shard 3)"]
+    
+    W1 -.->|publish(TEST_FAILED)| Broker
+    Broker -.->|notify| Analyst["failure-analyst Actor (Triage in Parallel)"]
+```
+
+1. **Decoupled Actor Mailboxes (`send-message` / `fetch-messages`):**
+   - Each QA subagent operates as an autonomous Actor with its own private mailbox.
+   - Eliminates monolithic conversational logs and prevents context contamination across subagents.
+
+2. **Parallel Matrix Sharding (`dispatch-shards`):**
+   - Automatically splits regression test suites into $N$ balanced shards.
+   - Dispatches shards to headless Playwright worker actors running in parallel.
+
+3. **Event-Driven Triage (`subscribe` / `publish`):**
+   - When a test runner encounters a failure, it immediately publishes `TEST_FAILED`.
+   - `failure-analyst` diagnoses the failure concurrently while other test runners continue uninterrupted.
+
+---
+
+## 2. CLI Tool Usage
+
+Autonomous commands via `tools/autogen_qa_broker.py`:
+
+```bash
+# 1. Dispatch regression suite across 4 parallel shards
+python tools/autogen_qa_broker.py dispatch-shards \
+  --suite-manifest tests/regression_manifest.json \
+  --shard-count 4 \
+  --worker-role "test-runner"
+
+# 2. Subscribe failure-analyst to test failure events
+python tools/autogen_qa_broker.py subscribe \
+  --actor "failure-analyst" \
+  --event "TEST_FAILED"
+
+# 3. Send direct message between subagents
+python tools/autogen_qa_broker.py send-message \
+  --from-actor "test-runner:worker_1" \
+  --to-actor "failure-analyst" \
+  --topic "TEST_FAILED" \
+  --payload '{"test_case": "TC-102", "error": "TimeoutError"}'
+
+# 4. Fetch messages from actor mailbox
+python tools/autogen_qa_broker.py fetch-messages \
+  --actor "failure-analyst"
+
+# 5. Check broker health and verify zero deadlocks
+python tools/autogen_qa_broker.py check-health
+```
+
+---
+
+## 3. Strict Operating Invariants
+
+- **Deadlock Prevention:** Enforce 300s timeout ceilings on actor response waits.
+- **Asynchronous Execution:** No subagent shall block the main thread waiting for another subagent's response.
+- **Zero Raw Selectors:** Messages instructing code synthesis must strictly enforce Clean POM standards.

package/.agents/skills/actor-qa-swarm/examples/broker_sharding_sample.json

@@ -0,0 +1,12 @@
+{
+  "status": "PASS",
+  "total_tests": 12,
+  "shard_count": 4,
+  "shards": {
+    "worker_1": 3,
+    "worker_2": 3,
+    "worker_3": 3,
+    "worker_4": 3
+  },
+  "dispatched_to_role": "test-runner"
+}

package/.agents/skills/agentless-qa-repair/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: agentless-qa-repair
+description: "Repair broken test scripts and Page Classes using an Agentless 3-phase flow: localization, candidate synthesis, and minimal diff validation. Use when repairing test failures without multi-agent chat bloat."
+---
+
+# Agentless QA Repair Skill — Ultra-Low-Token 3-Phase Failure Healing
+
+> **Paradigm Attribution:** Inspired by **UIUC OpenAutoCoder Agentless**.  
+> **Core Principle:** The best fix is the smallest working diff without round-trip chat loops. Solve 80% of daily test automation defects with a single-pass 3-stage pipeline under 2,500 tokens.
+
+---
+
+## 1. The 3-Phase Deterministic Pipeline
+
+Rather than spawning multi-turn swarm conversations that cost 40,000–80,000 tokens per failure, `agentless-qa-repair` executes in three deterministic stages:
+
+```mermaid
+flowchart LR
+    Fail["Test Failure (Stacktrace)"] --> P1["Phase 1: Localization<br/>Pinpoint file & line span"]
+    P1 --> P2["Phase 2: Candidate Gen<br/>Synthesize 3 minimal patches"]
+    P2 --> P3["Phase 3: Validation & Gate<br/>Syntax + Clean POM + Diff"]
+    P3 --> Winner["Apply Shortest Winning Diff (<10s)"]
+```
+
+1. **Phase 1 (Localization):**
+   - Parses the stacktrace (Playwright, Jest, JUnit XML, or Python Traceback).
+   - Cross-references `tools/repo_map.txt` or repository structure.
+   - Restricts focus strictly to the enclosing method and 5–10 line span.
+
+2. **Phase 2 (Parallel Candidate Synthesis):**
+   - Candidate 1: Semantic ARIA role locator (`getByRole('button', { name: '...' })`).
+   - Candidate 2: Resilient test identifier (`getByTestId('...')`).
+   - Candidate 3: Smart wait / network idle synchronization wrapper (`waitForLoadState('networkidle')`).
+
+3. **Phase 3 (Validation & Selection):**
+   - Checks AST syntax validity (Python `ast.parse` or JS/TS/Groovy bracket balance).
+   - Enforces **Clean POM**: strictly rejects raw XPath / CSS injected into test script files.
+   - Selects the shortest valid diff that clears all checks.
+
+---
+
+## 2. CLI Tool Usage
+
+Autonomous trigger via `tools/agentless_patcher.py`:
+
+```bash
+# End-to-end 3-stage healing
+python tools/agentless_patcher.py heal-failure \
+  --error-log reports/failed_run.log \
+  --repo-map tools/repo_map.txt \
+  --max-candidates 3
+
+# Localize failing line only
+python tools/agentless_patcher.py localize-error \
+  --error-log reports/failed_run.log
+
+# Generate patch candidates for a specific line
+python tools/agentless_patcher.py generate-candidates \
+  --file src/pages/CustomerDirectoryPage.ts \
+  --line 48
+```
+
+---
+
+## 3. Strict Operating Invariants
+
+- **Token Budget Ceiling:** Must stay under **2,500 tokens** per repair cycle.
+- **Zero Raw Selectors in Test Scripts:** If the failing file is located in `tests/`, `Scripts/`, or matches `*.spec.ts`, the fix must redirect selector adjustments into the corresponding Page Class extending `BasePage`.
+- **Minimal Working Diff:** Always choose the patch with the fewest altered lines that passes verification.

package/.agents/skills/agentless-qa-repair/examples/healing_report_sample.json

@@ -0,0 +1,17 @@
+{
+  "status": "PASS",
+  "localization": {
+    "file": "src/pages/CustomerDirectoryPage.ts",
+    "method": "selectCustomerRow",
+    "line_span": [48, 52]
+  },
+  "candidates_evaluated": 3,
+  "validation_results": {
+    "candidate_1": "FAIL (Syntax error: unbalanced bracket)",
+    "candidate_2": "PASS (All DoD Gates cleared, diff: 2 lines)",
+    "candidate_3": "PASS (All DoD Gates cleared, diff: 6 lines)"
+  },
+  "selected_winner": "candidate_2",
+  "tokens_consumed": 1780,
+  "elapsed_seconds": 7.8
+}

package/.agents/skills/api-spec-to-e2e-matrix/SKILL.md

@@ -65,7 +65,7 @@ Agent can automatically invoke `tools/generate_api_matrix.py` and `tools/export_
 python3 tools/generate_api_matrix.py --spec path/to/openapi.json --format md -o docs/api_matrix.md
 
 # 2. Generate JSON matrix for programmatic ingestion
-python3 tools/generate_api_matrix.py --spec path/to/openapi.json --format json -o tools/api_matrix.json
+python3 tools/generate_api_matrix.py --spec path/to/openapi.json --format json -o reports/api_matrix.json
 
 # 3. Export directly to Postman Collection v2.1.0 with AJV JSON Schema & DDT
 synapse export-postman --spec path/to/openapi.json -o postman_collection.json --env-output postman_env.json --ddt-output test_data.csv

package/.agents/skills/clean-pom-crafter/SKILL.md

@@ -22,7 +22,7 @@ Specialized skill for creating, refactoring, and standardizing test automation s
    - All `.groovy`, `.java`, `.ts`, `.tc` files must NEVER contain UTF-8 BOM bytes (`0xEF, 0xBB, 0xBF`).
 5. **Context Window Protection (Zero-Token Economy):**
    - 🚫 **NEVER read entire monolithic Page Class files (> 100KB) into LLM context.**
-   - Always use `python3 ~/.zcode/synapse-hub/tools/lookup_xpath.py <keyword>` or line-range targeted reads (`read_file` with `StartLine`/`EndLine`) to find selectors and methods on demand.
+   - Always use `python tools/lookup_xpath.py <keyword>` or line-range targeted reads (`read_file` with `StartLine`/`EndLine`) to find selectors and methods on demand.
 
 ---
 
@@ -68,7 +68,7 @@ All Page Classes **MUST** follow this strict locator hierarchy:
 
 - [**Standard Clean POM Methods (`pom_patterns.groovy`)**](references/pom_patterns.groovy): Full implementation of `searchRecord`, `editRecord`, `deleteRecord`, `setCalendarDate`, `selectMultiOptions`, `verifyRecordExists`, `verifyRecordNotExists`, `jsSetInput`.
 - [**Standard Test Script Template (`standard_test_case.groovy`)**](examples/standard_test_case.groovy): 7-step complete script template from Login -> Create -> Search -> Edit -> Delete.
-- [**Zero-Token XPath Lookup (`~/.zcode/synapse-hub/tools/lookup_xpath.py`)**](~/.zcode/synapse-hub/tools/lookup_xpath.py): Command `python3 ~/.zcode/synapse-hub/tools/lookup_xpath.py <PageClass>` returns exact locators in <200 tokens without parsing full files.
+- [**Zero-Token XPath Lookup (`tools/lookup_xpath.py`)**](tools/lookup_xpath.py): Command `python tools/lookup_xpath.py <PageClass>` returns exact locators in <200 tokens without parsing full files.
 - [**Browser Runtime Helper (`tools/browser_helpers.js`)**](tools/browser_helpers.js): In-browser validation engine for form audits, safe clicks, and batch verification.
 
 ---

package/.agents/skills/db-state-verifier-and-seeder/SKILL.md

@@ -102,22 +102,22 @@ To eliminate cascading flakiness and orphan test junk in parallel CI runs, agent
 ### 1. Transaction Savepoint Rollback Context
 Wrap E2E test data creation inside transactional savepoints:
 ```bash
-python3 ~/.zcode/synapse-hub/tools/db_sandbox.py rollback-test --db-path "path/to/db.sqlite"
+python tools/db_sandbox.py rollback-test --db-path "path/to/db.sqlite"
 ```
 *Guarantees zero leftover records: state is automatically rolled back to pristine baseline upon test completion.*
 
 ### 2. Ephemeral Snapshot & Instant Restore (< 0.5s)
 ```bash
 # Before test suite runs: capture pristine database baseline
-python3 ~/.zcode/synapse-hub/tools/db_sandbox.py snapshot --id pristine_baseline
+python tools/db_sandbox.py snapshot --id pristine_baseline
 
 # After suite execution: instantly restore clean database
-python3 ~/.zcode/synapse-hub/tools/db_sandbox.py restore --id pristine_baseline
+python tools/db_sandbox.py restore --id pristine_baseline
 ```
 
 ### 3. Taint Pollution Audit & Cascading Purge
 Scan all tables for orphan records carrying test prefixes (`AUTO_`, `TEST_`) and purge them cleanly:
 ```bash
-python3 ~/.zcode/synapse-hub/tools/db_sandbox.py audit
+python tools/db_sandbox.py audit
 ```
 

package/.agents/skills/event-stream-qa-orchestrator/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: event-stream-qa-orchestrator
+description: "Immutable EventStream orchestrator recording deterministic action/observation timelines with SHA-256 hash chains and reversible checkpoint rollbacks. Use when tracing test executions and managing replayable state."
+---
+
+# QA Event Stream Orchestrator Skill — Immutable Audit & Replay Timeline
+
+> **Paradigm Attribution:** Inspired by **All-Hands-AI OpenHands (EventStream & CodeAct Runtime)**.  
+> **Core Principle:** Treat automated testing sessions as an append-only, immutable stream of events. Prevent state corruption and lost context by chaining each event with cryptographic SHA-256 hashes and enabling deterministic check-pointed rollbacks.
+
+---
+
+## 1. The EventStream Pipeline
+
+```mermaid
+flowchart LR
+    Init["init-stream<br/>Genesis Hash (000...0)"] --> Act["record-event<br/>ACTION_NAVIGATE / ACTION_CLICK"]
+    Act --> Obs["record-event<br/>OBSERVATION_DOM / ASSERTION"]
+    Obs --> Check["Checkpoint Anchor<br/>CHECKPOINT_PRE_SUBMIT"]
+    Check --> Verify["verify-stream<br/>Cryptographic Audit"]
+    Verify --> Rollback["rollback<br/>Rewind to Checkpoint"]
+```
+
+1. **Immutable Event Logging (`record-event`):**
+   - Each event records: `index`, `session_id`, `event_type`, `actor`, `payload`, `timestamp`, `prev_hash`, and `event_hash`.
+   - Continuous SHA-256 hash chaining prevents unobserved event injection or tampering.
+
+2. **Reversible Checkpointing (`rollback`):**
+   - In conjunction with GoEx LIFO undo stack (`tools/reversible_sandbox.py`), enables restoring the browser or data state when an unexpected crash occurs.
+   - Appends a `ROLLBACK_EXECUTED` event to the stream without destroying the audit trail.
+
+3. **Cryptographic Verification (`verify-stream`):**
+   - Verifies hash continuity from genesis to latest event.
+   - Ensures zero missing or out-of-order events before certifying run results.
+
+---
+
+## 2. CLI Tool Usage
+
+Autonomous commands via `tools/qa_event_stream.py`:
+
+```bash
+# 1. Initialize stream
+python tools/qa_event_stream.py init-stream \
+  --session-id "CHECKOUT_E2E_001" \
+  --out-file .agent_memory/timeline.jsonl
+
+# 2. Record an action event
+python tools/qa_event_stream.py record-event \
+  --stream .agent_memory/timeline.jsonl \
+  --event-type ACTION_CLICK \
+  --actor live-explorer \
+  --payload '{"page":"CartPage","element":"checkout_button"}'
+
+# 3. Create a state checkpoint
+python tools/qa_event_stream.py record-event \
+  --stream .agent_memory/timeline.jsonl \
+  --event-type CHECKPOINT \
+  --actor test-runner \
+  --payload '{"cart_total": 99.99}' \
+  --checkpoint-id "PRE_CHECKOUT_FORM"
+
+# 4. Verify stream integrity
+python tools/qa_event_stream.py verify-stream \
+  --stream .agent_memory/timeline.jsonl
+
+# 5. Rollback to checkpoint on test failure
+python tools/qa_event_stream.py rollback \
+  --stream .agent_memory/timeline.jsonl \
+  --to-checkpoint "PRE_CHECKOUT_FORM"
+```
+
+---
+
+## 3. Strict Operating Invariants
+
+- **Hash Chain Integrity:** All events must compute `SHA-256(prev_hash | session_id | event_type | actor | payload | timestamp)`.
+- **Zero Log Tampering:** Never edit `timeline.jsonl` lines manually; always append via the CLI tool.
+- **UTF-8 No BOM:** Timeline files must remain clean UTF-8 without byte-order marks.

package/.agents/skills/event-stream-qa-orchestrator/examples/timeline_sample.jsonl

@@ -0,0 +1,2 @@
+{"index": 0, "session_id": "SESSION_DEMO_001", "event_type": "STREAM_INIT", "actor": "system", "payload": {"initialized_at": "2026-11-04T12:00:00Z"}, "timestamp": "2026-11-04T12:00:00Z", "prev_hash": "0000000000000000000000000000000000000000000000000000000000000000", "event_hash": "1a2b3c4d5e6f"}
+{"index": 1, "session_id": "SESSION_DEMO_001", "event_type": "ACTION_NAVIGATE", "actor": "live-explorer", "payload": {"url": "https://app.local/login"}, "timestamp": "2026-11-04T12:00:01Z", "prev_hash": "1a2b3c4d5e6f", "event_hash": "2b3c4d5e6f7a"}

package/.agents/skills/failure-autopsy-and-healing/SKILL.md

@@ -21,7 +21,7 @@ flowchart LR
 
 1. **Zero-Token Triage:** Pinpoint failed line and cause instantly (<50 tokens):
    ```bash
-   python3 ~/.zcode/synapse-hub/tools/pinpoint_failure.py
+   python tools/pinpoint_failure.py
    # or bash .agents/skills/failure-autopsy-and-healing/scripts/triage_failures.sh
    ```
 2. **Visual Autopsy:** Inspect the latest error screenshot to immediately detect: disabled buttons, missing required fields, UI overlaps, or obscuring modal backdrops.
@@ -49,7 +49,7 @@ flowchart LR
 
 - [**Diagnostic & Healing Matrix (`healing_matrix.md`)**](references/healing_matrix.md): Concrete code prescriptions for disabled buttons, boundary overlaps, `ElementClickInterceptedException`, `StaleElementReferenceException`, and 4 flaky test root causes.
 - [**Fast-Fix Triad & Runtime Helper (`tools/browser_helpers.js`)**](tools/browser_helpers.js): In-browser diagnosis engine via `window.__qa` (`audit`, `heal`, `clickSafe`, `hud`).
-- **Automated Triage Script:** `python3 ~/.zcode/synapse-hub/tools/pinpoint_failure.py` and `scripts/triage_failures.sh`.
+- **Automated Triage Script:** `python tools/pinpoint_failure.py` and `scripts/triage_failures.sh`.
 
 ---
 

package/.agents/skills/failure-autopsy-and-healing/scripts/triage_failures.sh

@@ -64,28 +64,13 @@ list_recent_screenshots() {
 list_recent_screenshots | while read -r epoch date time filepath; do
     filename=$(basename "$filepath")
     
-    # Ánh xạ Page Class gợi ý dựa trên mã Test Case (Dynamic Pattern Matching)
+    # Dynamic Page Class mapping via repo_map lookup or fallback to BasePage
     suggested_page="BasePage.groovy"
-    if [[ "$filename" =~ TC-([0-9]+) ]]; then
-        tc_num="${BASH_REMATCH[1]}"
-        if [ "$tc_num" -ge 1 ] && [ "$tc_num" -le 7 ]; then
-            suggested_page="TargetPlanPage.groovy"
-        elif [ "$tc_num" -ge 8 ] && [ "$tc_num" -le 12 ]; then
-            suggested_page="LoginPage.groovy"
-        elif [ "$tc_num" -ge 13 ] && [ "$tc_num" -le 16 ]; then
-            suggested_page="UserAdminPage.groovy"
-        elif [ "$tc_num" -ge 17 ] && [ "$tc_num" -le 28 ]; then
-            suggested_page="CommonCategoryPage.groovy"
-        elif [ "$tc_num" -ge 29 ] && [ "$tc_num" -le 92 ]; then
-            suggested_page="IndustryCategoryPage.groovy"
-        elif [ "$tc_num" -ge 93 ] && [ "$tc_num" -le 122 ]; then
-            suggested_page="PlanningPage.groovy"
-        elif [ "$tc_num" -ge 123 ] && [ "$tc_num" -le 247 ]; then
-            suggested_page="DataMiningPage.groovy"
-        elif [ "$tc_num" -ge 248 ] && [ "$tc_num" -le 249 ]; then
-            suggested_page="ReportPage.groovy"
-        elif [ "$tc_num" -ge 250 ] && [ "$tc_num" -le 259 ]; then
-            suggested_page="TokenMgmtPage.groovy"
+    if [ -f "tools/repo_map.txt" ] && [[ "$filename" =~ TC-([0-9]+) ]]; then
+        tc_pattern="TC-${BASH_REMATCH[1]}"
+        found_page=$(grep -m 1 -i "$tc_pattern" tools/repo_map.txt | awk '{print $1}' 2>/dev/null)
+        if [ -n "$found_page" ]; then
+            suggested_page="$found_page"
         fi
     fi