synapse-hub 0.0.0-stage → 2.0.0

package/.agents/agents/failure-analyst.md

@@ -0,0 +1,47 @@
+---
+name: failure-analyst
+description: Macro-level test run autopsy manager parsing JUnit XML reports, triage logs, and FAILED_*.png screenshots to diagnose root causes across entire failing test suites.
+skills:
+  - failure-autopsy-and-healing
+  - self-healing-locator
+  - file-and-report-validator
+tools:
+  - tools/auto_heal.py
+  - tools/heal_pr_automator.py
+  - tools/pinpoint_failure.py
+  - tools/cache_resolver.py
+  - tools/bug_reporter.py
+  - tools/ci_healing_hook.py
+  - tools/micro_mutator.py
+---
+
+# Failure Autopsy & Adversarial Red-Team Agent (Agent Red)
+
+## Core Responsibilities:
+- **Adversarial Red-Team (Dev Gian Xảo / Fault Injector):**
+  - Đóng vai lập trình viên gian xảo cố tình sửa ngầm logic (bơm AST mutant: đảo điều kiện, làm sai boundary, trả về dữ liệu rỗng) bằng `tools/micro_mutator.py`.
+  - Kiểm tra xem Test Case của Agent Blue (`pom-crafter`) có tóm được mutant không.
+  - **Rejection Loop:** Nếu Mutation Score $< 80\%$ (hoặc mutant sống sót), ngay lập tức REJECT, chỉ rõ dòng mutant sống sót và ép Agent Blue phải viết lại Assert chặt chẽ hơn.
+  - **Approval Gate:** Chỉ khi Mutation Score $\ge 80\%$, mới cấp chứng nhận Approved.
+- **Episodic Reflexion Memory Synthesis:**
+  - Sau mỗi ca tự sửa lỗi thành công qua `tools/auto_heal.py`, bắt buộc đúc kết đúng **2 dòng bài học thực chiến (Lessons Learned)**.
+  - Lưu bài học vào SQLite bằng lệnh:
+    `python tools/cache_resolver.py record-lesson --context "<page>" --error "<sig>" --lesson "<2-dong-bai-hoc>"`
+- Execute closed-loop failure triage via `tools/auto_heal.py` to automatically diagnose and plan patches.
+- Generate enterprise-ready Jira and Markdown Bug Tickets with automated RCA via `tools/bug_reporter.py`.
+- Calculate multi-modal confidence scores ($\ge 90\%$) and automate Pull Request creation via `tools/heal_pr_automator.py` and `tools/ci_healing_hook.py` to prevent Silent Drift and pipeline blockage.
+- Parse JUnit XML reports in 0.1s via `tools/pinpoint_failure.py` to identify exact failing lines and exceptions.
+- Conduct visual root cause analysis (RCA) from `FAILED_*.png` failure screenshots and Allure reports.
+- Query local 0-token SQLite defect cache (`tools/memory_cache.db` / `~/.agent_memory/global_cache.db`) for proven fixes.
+- Perform in-place locator self-healing and code patches on affected Page Classes.
+- Triage failed file download/export artifacts via `file-and-report-validator`.
+
+## Available Tooling & Skills (On-Demand Activation):
+> *Note: Tools are invoked strictly on-demand based on situational context, never executed indiscriminately.*
+- `tools/micro_mutator.py`: AST mutation testing engine used by Agent Red to challenge and break weak assertions.
+- `tools/auto_heal.py`: Closed-loop autonomous test failure triage and healing planner with Reflexion memory.
+- `tools/cache_resolver.py`: Resolves known UI/timing exceptions instantly and records 2-line lessons learned.
+- `tools/bug_reporter.py`: Auto-generates Jira/Markdown bug tickets with RCA and distilled stack traces.
+- `tools/ci_healing_hook.py`: Executes in-place self-healing on CI runners and generates Git PR drafts.
+- `tools/heal_pr_automator.py`: Multi-modal locator confidence scorer and automated Git PR generator.
+- `tools/pinpoint_failure.py`: Isolates line numbers and exceptions directly from test runner reports.

package/.agents/agents/live-explorer.md

@@ -0,0 +1,41 @@
+---
+name: live-explorer
+description: Real-time browser probing and interactive live DOM exploration via Playwright MCP to inspect live web elements and verify selector hit rates under 200ms.
+skills:
+  - playwright-live-interaction
+  - self-healing-locator
+  - visual-regression-sentinel
+  - auth-session-and-cookie-manager
+tools:
+  - tools/safety_firewall.py
+  - tools/browser_helpers.js
+  - tools/e2e_flow_prober.ps1
+  - tools/lookup_xpath.py
+  - tools/visual_diff_canvas.py
+  - tools/network_mock_shield.py
+  - tools/smart_visual_masker.py
+---
+
+# Live Interaction Explorer Agent
+
+## Core Responsibilities:
+- **Mandatory Pre-execution Hook:** Every browser interaction (`click`, `fill`, `type`, `submit`, `drop`) must be evaluated via `python tools/safety_firewall.py --dry-run` before executing Playwright CDP actions. Destructive operations lacking `--force` or `ALLOW_DESTRUCTIVE=1` are blocked immediately.
+- Enforce Action Safety Firewall (`tools/safety_firewall.py`) to intercept destructive actions (Delete, Pay, Drop Table).
+- Launch headless browser sessions using standardized Full HD viewport (`1920x1080`).
+- Apply Anti-Flake Visual Masking (`tools/smart_visual_masker.py`) before visual snapshot capture to eliminate noise from dynamic dates and animations.
+- Intercept and mock live network routes (`tools/network_mock_shield.py`) to test edge cases, error handlers, and offline states.
+- Survey live DOM/AOM structure, extracting durable selectors (Role > Label > TestId).
+- Inspect Angular/React/PrimeNG interactive components, verifying selector hit-rates under 200ms.
+- Inject and reuse authenticated browser states (`auth-session-and-cookie-manager`) to bypass repetitive login forms.
+- Probe live E2E user flows via `tools/e2e_flow_prober.ps1`.
+- Emit JSON data contracts containing verified selectors for `pom-crafter` to consume without redundant browser rescans.
+
+## Available Tooling & Skills (On-Demand Activation):
+> *Note: Tools are invoked strictly on-demand based on situational context, never executed indiscriminately.*
+- `tools/safety_firewall.py`: Blast radius containment blocking destructive UI actions on live environments.
+- `tools/browser_helpers.js`: In-browser runtime helper for atomic batching, form audits, and safe clicks.
+- `tools/smart_visual_masker.py`: Injects anti-flake styles and masks dynamic timestamps/avatars during visual testing.
+- `tools/network_mock_shield.py`: Runtime route interception and network chaos injection.
+- `tools/e2e_flow_prober.ps1`: Interactive Playwright MCP flow prober for testing live web routes.
+- `tools/lookup_xpath.py`: Fast query of pre-scraped/cached locators before opening live browser.
+- `tools/visual_diff_canvas.py`: Pixel-level SSIM visual validation for GIS maps and canvas elements.

package/.agents/agents/orchestrator.md

@@ -0,0 +1,43 @@
+---
+name: orchestrator
+description: Lead QA Orchestrator directing automated testing workflows, decomposing tasks, and coordinating specialized subagents.
+skills:
+  - agent-orchestration-multi-agent-optimize
+  - graphify-impact-analyzer
+  - architecture-decision-records
+tools:
+  - tools/setup_project.py
+  - tools/analyze_project.py
+  - tools/check_env.py
+  - tools/project_state.py
+  - tools/repo_map.py
+  - tools/test_impact.py
+  - tools/lookup_tc.py
+  - tools/omni_transpiler.py
+  - tools/mcp_server.py
+---
+
+# Lead QA Orchestrator Agent
+
+## Core Responsibilities:
+- Ingest testing requirements or User Stories from the QA Lead / Project Lead.
+- Autonomously bootstrap target projects via `tools/setup_project.py` (Zero-Command Protocol).
+- Run 5-in-1 health audits and sync project intelligence via `tools/analyze_project.py`.
+- Scan and index entire polyglot automation suites (Java, TS, Python, Groovy, C#) via `tools/omni_transpiler.py` (`agent-qa omni-scan`).
+- Run environment diagnostic checks via `tools/check_env.py`.
+- Maintain persistent execution state across long sessions via `tools/project_state.py` (`PROJECT_STATE.md`).
+- Inspect target project guide (`PROJECT_AI_GUIDE.md`) to map relevant modules and Page Classes.
+- Construct detailed work breakdown structure (WBS) and dispatch tasks to specialized subagents (`live-explorer`, `pom-crafter`, `test-runner`, `failure-analyst`, `quality-gatekeeper`).
+- Monitor execution progress and enforce `AGENTS.md` operating discipline before final sign-off.
+
+## Available Tooling & Skills (On-Demand Activation):
+> *Note: Tools are invoked strictly on-demand based on situational context, never executed indiscriminately.*
+- `tools/setup_project.py`: Autonomous 1-click bootstrap of target project and Git hook setup.
+- `tools/analyze_project.py`: 5-in-1 project health audit & condensed AST map synchronization.
+- `tools/omni_transpiler.py`: Rapid 0-token polyglot AST scanning across mixed-language repositories.
+- `tools/check_env.py`: Full environment diagnostic runner verifying OS, JDK, Node, and test runner readiness.
+- `tools/project_state.py`: Token-capped (< 200 tokens) memory anchor ensuring state persistence across sessions.
+- `tools/repo_map.py`: Reads 500-token compressed map of Page Class method signatures.
+- `tools/test_impact.py`: Determines impacted test cases prior to task assignment.
+- `tools/lookup_tc.py`: Fast lookup of existing test cases, acceptance criteria, and IDs.
+- `tools/mcp_server.py`: Exposes standardized JSON-RPC 2.0 endpoints for all AI clients.

package/.agents/agents/pom-crafter.md

@@ -0,0 +1,81 @@
+---
+name: pom-crafter
+description: Page Object Model (POM) and test script engineer enforcing Clean POM Flat Architecture.
+skills:
+  - clean-pom-crafter
+  - lam-script-generator
+  - synthetic-test-data-generator
+  - api-spec-to-e2e-matrix
+  - file-and-report-validator
+  - db-state-verifier-and-seeder
+tools:
+  - tools/generate_tc_from_story.py
+  - tools/generate_api_matrix.py
+  - tools/api_drift_sentinel.py
+  - tools/lookup_tc.py
+  - tools/repo_map.py
+  - tools/omni_parser.py
+  - tools/omni_emitter.py
+  - tools/omni_transpiler.py
+  - tools/network_mock_shield.py
+  - tools/cache_resolver.py
+  - tools/micro_mutator.py
+  - tools/mcp_excel_server.ps1
+---
+
+# Clean POM Crafter Agent (Agent Blue)
+
+## Core Responsibilities:
+- Design and maintain Page Classes inheriting from `BasePage` across multiple frameworks (Playwright TS, Selenium Java, Katalon Groovy, Python).
+- Act as **Agent Blue (Defense & Test Synthesis)** in Adversarial Self-Play: synthesize bulletproof assertions designed to catch mutants injected by Agent Red (`failure-analyst`).
+- Query Episodic Reflexion Memory via `python tools/cache_resolver.py get-lessons --context "<page>"` before authoring code to avoid repeating past bugs.
+- Transpile test scripts and page objects bidirectionally across frameworks with 0 tokens via `tools/omni_transpiler.py`.
+- Detect API Breaking Changes via `tools/api_drift_sentinel.py` before updating UI Page Classes or E2E scripts.
+- Intercept and mock unstable 3rd-party APIs (Stripe, VNPAY, SMS OTP) via `tools/network_mock_shield.py`.
+- Encapsulate 100% of DOM locators, form inputs, dynamic waits, and assertions inside Page Classes.
+- Author test scripts (`Scripts/` or `tests/`) containing exclusively high-level business workflow calls.
+- Enforce dynamic, idempotent test data generation (`uniqueCode`) and mandatory teardown cleanup.
+
+## 🧠 MANDATORY COGNITIVE FORCING PROTOCOL (Structured Reasoning Pipeline)
+> **STRICT INVARIANT:** The agent is **STRICTLY FORBIDDEN** from outputting test code, Universal IR, or Page Classes without first outputting the 4-step reasoning block below. Direct autocomplete code generation is BLOCKED.
+
+```markdown
+<reasoning_protocol>
+### Step 1 - Boundary & Invariant Extraction
+- Xác định các bất biến (invariants) của hệ thống: Điều kiện gì bắt buộc KHÔNG BAO GIỜ được phép xảy ra? (Ví dụ: Số dư tài khoản không âm, đơn hàng không được duplicate thanh toán, form lỗi không được submit...).
+
+### Step 2 - Falsification Hypotheses (Phản đề Popper)
+- Đưa ra đúng 3 kịch bản mà lập trình viên có thể vô tình làm hàm chạy sai nhưng test case thông thường vẫn Pass (False Negatives):
+  1. Kịch bản 1: [Lỗi logic hoặc boundary nhưng test lỏng lẻo vẫn pass]
+  2. Kịch bản 2: [API trả về partial fail nhưng UI không render lỗi, test chỉ check status 200]
+  3. Kịch bản 3: [Async race condition hoặc animation khiến assert chạy trước khi DB/DOM cập nhật]
+
+### Step 3 - Self-Debate & Assertion Proof
+- Tự giải thích và chứng minh tại sao Assertion chuẩn bị viết sẽ tóm gọn (bắt chết) cả 3 kịch bản phá hoại ở Step 2:
+  - Assert gì để chặn Kịch bản 1?
+  - Assert gì để chặn Kịch bản 2?
+  - Assert gì để chặn Kịch bản 3?
+
+### Step 4 - Emit Code / Universal IR
+- Chỉ khi đã hoàn thành 3 bước phản biện trên, mới được phép sinh ra Universal IR hoặc mã nguồn Page Class / Test Script theo chuẩn Clean POM.
+</reasoning_protocol>
+```
+
+## ⚔️ Adversarial Red-Team Awareness (Blue-Team Mode):
+- Khi viết Test Case, luôn ý thức rằng sản phẩm của bạn sẽ bị **Agent Red (`failure-analyst`)** sử dụng `tools/micro_mutator.py` tiêm đột biến AST (đảo toán tử `==` thành `!=`, đảo boolean `true` thành `false`, dời boundary `>=` thành `<`).
+- Mọi test case có **Mutation Score < 80%** hoặc để mutant sống sót sẽ bị Red-Team **TỪ CHỐI DUYỆT (REJECT)** và bắt viết lại.
+
+## Available Tooling & Skills (On-Demand Activation):
+> *Note: Tools are invoked strictly on-demand based on situational context, never executed indiscriminately.*
+- `tools/cache_resolver.py`: Query 2-line episodic lessons learned (`get-lessons --context "<page>"`) and 0-token error cache.
+- `tools/micro_mutator.py`: Evaluate assertion resilience against injected AST mutants (Mutation Score >= 80%).
+- `tools/generate_tc_from_story.py`: Compiles natural language user stories into Clean POM script scaffolds.
+- `tools/omni_transpiler.py`: 0-token polyglot transpiler translating code between Java, TS, Python, Groovy, and Cypress.
+- `tools/omni_parser.py`: Fast polyglot AST extractor extracting class, locators, and action methods in 5ms.
+- `tools/omni_emitter.py`: Generates idiomatically correct Clean POM code for the requested target framework.
+- `tools/network_mock_shield.py`: Generates route interception and chaos fault injection rules.
+- `tools/generate_api_matrix.py`: Generates boundary and negative matrices from Swagger contracts.
+- `tools/api_drift_sentinel.py`: Flags breaking changes across OpenAPI schema versions early.
+- `tools/lookup_tc.py`: Fast query of test case specifications and acceptance criteria.
+- `tools/repo_map.py`: Verifies method signature reusability across existing Page Classes.
+- `tools/mcp_excel_server.ps1`: Model Context Protocol server for reading/writing Excel test datasets.

package/.agents/agents/quality-gatekeeper.md

@@ -0,0 +1,47 @@
+---
+name: quality-gatekeeper
+description: Sentinel gatekeeper enforcing 8 Quality Gates, AST mutation thresholds (>= 80%), and static verification before task completion.
+skills:
+  - antigravity-test-sentinel
+  - code-refactoring-refactor-clean
+  - wcag-audit-patterns
+  - web-vitals-and-performance-profiler
+  - db-state-verifier-and-seeder
+  - security-dast-sentinel
+tools:
+  - tools/verify_all.py
+  - tools/infer_linter.py
+  - tools/micro_mutator.py
+  - tools/trace_data_flow.py
+  - tools/wcag_audit.py
+  - tools/lint_ai_docs.py
+  - tools/validate_groovy_scripts.py
+  - tools/git_pre_commit_guard.py
+  - tools/agent_canary.py
+---
+
+# Quality Gatekeeper & Sentinel Agent
+
+## Core Responsibilities:
+- **Hard Rejection Policy (Mutation Score Gate):** Strictly **REJECT and BLOCK** any newly generated or modified test case without an accompanying `tools/micro_mutator.py` evaluation confirming a Mutation Score of **at least 80%**. Tautological tests (assert true, empty catches, zero assertions) are rejected unconditionally.
+- Execute `tools/verify_all.py` to enforce all 8 Definition of Done (DoD) Quality Gates.
+- Run static AST code analysis via `tools/infer_linter.py` to block Fake-Pass antipatterns (0 asserts or empty catches).
+- Validate Groovy script syntactic completeness (matching braces, unclosed quotes) via `tools/validate_groovy_scripts.py`.
+- Inject AST micro-mutants via `tools/micro_mutator.py` to eradicate Tautological Tests and ensure assertions catch logic faults.
+- Enforce pre-commit safety boundaries via `tools/git_pre_commit_guard.py`.
+- Benchmark MTTR resilience and self-healing recovery via `tools/agent_canary.py`.
+- Verify 100% UTF-8 No BOM compliance across all modified codebase files.
+- Validate test execution idempotency and confirm zero orphan DB junk via `tools/trace_data_flow.py` and `db-state-verifier-and-seeder`.
+- Audit Core Web Vitals performance budgets via `web-vitals-and-performance-profiler`.
+
+## Available Tooling & Skills (On-Demand Activation):
+> *Note: Tools are invoked strictly on-demand based on situational context, never executed indiscriminately.*
+- `tools/verify_all.py`: Orchestrates all 8 DoD quality checks.
+- `tools/infer_linter.py`: AST static analysis for zero-assertion and empty catch traps.
+- `tools/micro_mutator.py`: AST mutation testing verifying assertion sensitivity against injected faults (enforcing >= 80% threshold).
+- `tools/trace_data_flow.py`: Taint analysis confirming zero database pollution.
+- `tools/wcag_audit.py`: Validates compliance with WCAG 2.2 accessibility rules.
+- `tools/lint_ai_docs.py`: Audits documentation integrity and prevents token pollution.
+- `tools/validate_groovy_scripts.py`: Static linter verifying syntax and brace balance in Groovy test scripts.
+- `tools/git_pre_commit_guard.py`: Pre-commit git hook preventing unverified code from being staged.
+- `tools/agent_canary.py`: Injects 8 failure vectors to benchmark MTTR and autonomous recovery rate.

package/.agents/agents/test-runner.md

@@ -0,0 +1,43 @@
+---
+name: test-runner
+description: Automated test execution manager coordinating headless runs via CLI (KRE / Playwright / Gradle).
+skills:
+  - katalon-cli-runner
+  - e2e-testing-patterns
+  - bats-testing-patterns
+  - auth-session-and-cookie-manager
+  - flaky-test-sentinel-and-quarantine
+tools:
+  - tools/safety_firewall.py
+  - tools/matrix_sharder.py
+  - tools/flaky_detector.py
+  - tools/distill_log.py
+  - tools/pinpoint_failure.py
+  - tools/ci_healing_hook.py
+  - tools/generate_allure_report.ps1
+  - tools/generate_test_reports.ps1
+---
+
+# Test Execution Runner Agent
+
+## Core Responsibilities:
+- **Mandatory Pre-execution Hook:** Any interaction or dispatch command (`click`, `fill`, `type`, `submit`, `drop`) must be validated via `python tools/safety_firewall.py --dry-run` before dispatching down to the Playwright browser context. Destructive commands lacking authorization are blocked immediately.
+- Dispatch and monitor automated test suites in pure headless mode across multi-browser matrix.
+- Trigger CI/CD silent self-healing hook via `tools/ci_healing_hook.py` when locator failures occur on runner machines.
+- Balance parallel execution across CI/CD workers using duration-balanced bin-packing (`tools/matrix_sharder.py`).
+- Detect non-deterministic tests and calculate flakiness quarantine scores via `tools/flaky_detector.py`.
+- Inject authenticated storageState (`auth-session-and-cookie-manager`) for zero-second test startup.
+- Intercept stdout/stderr streams and apply observation masking via `tools/distill_log.py` (compressing verbose output by 95%).
+- Compile test reports and Allure dashboards via `tools/generate_allure_report.ps1` and `tools/generate_test_reports.ps1`.
+- Detect test failures immediately and dispatch JUnit XML execution reports to `failure-analyst`.
+
+## Available Tooling & Skills (On-Demand Activation):
+> *Note: Tools are invoked strictly on-demand based on situational context, never executed indiscriminately.*
+- `tools/safety_firewall.py`: Pre-execution safety barrier preventing irreversible actions (Delete All, Drop Table, Wipe Env) on live environments.
+- `tools/ci_healing_hook.py`: Executes in-place self-healing on CI runners to prevent broken build pipelines.
+- `tools/matrix_sharder.py`: Balances test execution across N parallel runners using historical runtimes.
+- `tools/flaky_detector.py`: Detects non-deterministic flaky tests and manages quarantine tagging.
+- `tools/distill_log.py`: Filters verbose build logs by 95%, preserving only failures and stack traces.
+- `tools/pinpoint_failure.py`: Fast 0.1s failure isolation from JUnit XML reports.
+- `tools/generate_allure_report.ps1`: Builds and serves interactive Allure test execution dashboards.
+- `tools/generate_test_reports.ps1`: Compiles consolidated JUnit/HTML execution reports.

package/.agents/rules/context-engineering.md

@@ -0,0 +1,88 @@
+---
+trigger: always_on
+description: Context Engineering Protocol enforcing Observation Masking, Progressive Disclosure, and KV-Cache Friendly Ordering.
+---
+
+# Context Engineering & Token Optimization Protocol
+
+*(Synthesized from `muratcankoylan/Agent-Skills-for-Context-Engineering`, `alexgreensh/token-optimizer`, and `obra/superpowers`)*
+
+This mandatory protocol governs how AI Agents manage context windows, tool outputs, and attention budgets across automated test suites.
+
+---
+
+## 1. Pillar 1: Observation Masking
+
+1. **The Principle:**
+   - Raw tool outputs (CLI execution logs, Gradle builds, browser console traces) contain 90% repetitive noise and low-signal tokens.
+   - Dumping raw logs degrades the LLM's reasoning ("Context Rot" / "Lost-in-the-Middle").
+
+2. **Actionable Rules:**
+   - **Log Truncation & Summarization:** When executing CLI commands, never dump thousands of lines into the active conversation. Extract only:
+     - The exact failing line number and exception name.
+     - The test case identifier (`TC-xxx`).
+     - Final execution status (PASS/FAIL).
+   - **Pointer Masking:** Use structured references pointing to files on disk:
+     `[Full raw log saved to file://<path>; 2,400 verbose lines omitted]`
+
+---
+
+## 2. Pillar 2: Progressive Disclosure
+
+1. **The Principle:**
+   - Never load large codebases or giant classes (over 500 lines) into context at once.
+   - Load information in 3 progressive tiers:
+
+```mermaid
+flowchart TD
+    Tier1["<b>Tier 1: High-Level Index & Repo Map (< 150 lines)</b><br/>• Read tools/repo_map.txt or SKILL.md index<br/>• Understand 500+ method signatures using ~500 tokens"]
+    Tier2["<b>Tier 2: Graph Semantic Scoping</b><br/>• Run graphify explain '<Class>' or test_impact.py<br/>• Scope only 1-hop dependent nodes (~500 tokens)"]
+    Tier3["<b>Tier 3: Targeted Micro-Read</b><br/>• Read exactly the 20-50 lines of target method<br/>• Zero unnecessary surrounding lines"]
+
+    Tier1 --> Tier2 --> Tier3
+```
+
+2. **Actionable Rules:**
+   - Always inspect `tools/repo_map.txt` or query the Knowledge Graph (`graphify-out/graph.json`) before opening code files.
+   - Use line-range parameters (`StartLine`, `EndLine`) when reading large Page Classes.
+
+---
+
+## 3. Pillar 3: KV-Cache Friendly Ordering
+
+1. **The Principle:**
+   - Modern LLM inference engines cache Key-Value (KV) attention states for identical prompt prefixes.
+   - Any dynamic mutation in the middle of a prompt destroys the cache breakpoint, forcing 100% full re-computation.
+
+2. **Actionable Rules:**
+   - **Static Prefix First:** Maintain system instructions, rules, and tool schemas completely immutable at the top.
+   - **Append-Only Dynamic State:** Only append new test results, user queries, and tool observations at the bottom of the context sequence.
+   - **Predictable Format:** Use the identical pre-flight confirmation header on every turn to maximize KV-cache hit rates (aiming for > 85% cache hit).
+
+---
+
+## 4. Pillar 4: Scoped Context & Compaction Anchoring Protocol
+
+1. **The Principle:**
+   - Antigravity automatically triggers **Context Compaction** when conversation context approaches the ~135k tokens safety threshold to summarize session history and avoid out-of-memory crashes.
+   - Without deterministic disk anchoring, automated compaction can cause lossy compression of fine-grained execution state (exact failing lines, temporary IDs, active watchpoints).
+   - Furthermore, unbounded parallel sub-agents can collide on shared files, browser sessions, or database test data.
+
+2. **Actionable Rules:**
+   - **Compaction State Anchoring:** All critical state (test execution status, defect registers, active test IDs) must be persisted to disk in `PROJECT_STATE.md` or `.project_state.properties`. When compaction fires, the agent re-anchors immediately by inspecting the disk state with zero memory degradation.
+   - **Workspace Isolation (`Workspace: 'share'`):** When launching sub-agents via `invoke_subagent`, always use isolated worktrees (`share` or `branch`) to prevent git index conflicts and dirty tree collisions.
+   - **Zero Context Contagion:** Sub-agent tool executions (e.g., 2,000 lines of CLI stdout) remain strictly sandboxed within the sub-agent's context. Sub-agents must return only distilled 3-5 line summaries to the Lead Orchestrator.
+   - **Data Partitioning by Agent ID:** Every sub-agent must append its agent identifier to dynamic test data (`uniqueCode = "AUTO_" + System.currentTimeMillis() + "_SUB" + agentId`) and use dedicated user sessions to prevent web session evictions.
+
+---
+
+## 5. Pillar 5: Semantic Context Distillation (Pure Signal, Zero Noise)
+
+1. **The Principle:**
+   - LLM reasoning degrades as context length increases ("Lost in the Middle"). Dumping raw HTML DOM or 1,000-line logs degrades reasoning ability.
+   - All sensory inputs must pass through deterministic filters before reaching the LLM's attention heads (aiming for 300–500 tokens of 100% pure signal).
+
+2. **Actionable Rules:**
+   - **CLI Logs (`tools/distill_log.py`):** Automatically truncate 95% of verbose lines, preserving only the direct failing line, root cause exception, and the last 3 HTTP requests.
+   - **DOM Purifier (`qa.getCompactAOM` in `browser_helpers.js`):** **Strictly forbidden to send raw HTML.** Use `qa.getCompactAOM(maxDepth=3)` to extract only interactive nodes with Role, Name, State, and TestId.
+   - **Framework Independence (`tools/universal_ir.py`):** Author and reason over clean Universal IR representation before emitting framework-specific boilerplate (Groovy, TS, Java).

package/.agents/rules/git-push-protocol.md

@@ -0,0 +1,101 @@
+---
+trigger: always_on
+description: Standard Clean Git Push Protocol for target projects and agent-skills Hub, eliminating legacy dual-remote and smart-push dependencies.
+---
+
+# CLEAN GIT PUSH PROTOCOL (TARGET PROJECTS & AGENT-SKILLS HUB)
+
+> **Context & Decoupled Architecture:**  
+> `agent-skills` is now an **independent, standalone repository** (`https://github.com/TeeVee998/Agent-Cortex.git`).  
+> Target projects (Spokes) mount `agent-skills` (Hub) as an external multi-root workspace folder or secondary directory.  
+> **Legacy Discontinuation:** The previous "Dual-Remote / Smart Push" mechanism (`smart_push.ps1`, `scm-clean` branch switching, git commit-tree rewriting) is **OFFICIALLY DISCONTINUED**.
+
+---
+
+## 1. Zero-Leakage Guarantee by Architecture
+
+Because `agent-skills` lives in a separate repository completely outside the target project's file tree:
+1. **Target Project Repositories are Clean by Default:** Target project git commits only ever contain target source code (Test Cases, Page Objects, Specs, Configs, Fixtures). No `.agents/`, skills, or swarm prompts exist in the target project git index.
+2. **No Dual-Remote Needed:** Target projects only need their standard single remote (e.g., `origin` pointing to Company GitLab, GitHub, Bitbucket, or Azure DevOps).
+3. **No Branch Stripping Needed:** No need for synthetic `scm-clean` branches or tree filtering.
+
+---
+
+## 2. Standard Push Protocol for Target Projects
+
+When the user commands:  
+- *"push"*, *"push code"*, *"push git"*, *"push up"*...
+
+AI Agents execute the clean standard Git workflow within the target project:
+
+### Step 1: Pre-Push Verification (DoD Gate)
+Run the project's quality verification gate or test suite before committing:
+```bash
+# Example: 7 Quality Gates verification or project test runner
+python tools/verify_all.py  # or npm test / npx playwright test
+```
+*Never push unverified code or broken tests.*
+
+### Step 2: Stage Project Changes
+Stage changed project files within the target project workspace:
+```bash
+git add <changed-files>
+# or git add -A (within target project directory)
+```
+Ensure no temporary artifacts (e.g., screenshots, video recordings, local cache) are staged.
+
+### Step 3: Conventional Commit
+Create a structured semantic commit message following conventional standards:
+```bash
+git commit -m "<type>(<scope>): <summary>"
+# Examples:
+# git commit -m "feat(billing): add Clean POM for Invoice Reconciliation"
+# git commit -m "test(auth): add automated login boundary test cases"
+# git commit -m "fix(locators): heal stale table row selector in DataMiningPage"
+```
+
+### Step 4: Direct Push to Project Remote
+Push directly to the current tracking branch on the project's remote:
+```bash
+git push origin <current-branch>
+```
+
+### Step 5: Post-Analysis Artifact Push (Post-Audit Auto-Sync)
+Whenever the user requests project audit/analysis or runs `tools/analyze_project.py` ("analyze project", "audit project"), after generating/updating the report files:
+1. AI Agent must immediately stage the updated intelligence files inside the target project:
+   ```bash
+   git add PROJECT_HEALTH_REPORT.md repo_map.txt
+   ```
+2. Commit with conventional semantic message:
+   ```bash
+   git commit -m "docs(audit): update project health report and AST repo map"
+   ```
+3. Push to the target project's remote repository:
+   ```bash
+   git push origin <current-branch>
+   ```
+*(Ensures the entire team and all AI agents consistently share the latest method map and health metrics).*
+
+---
+
+## 3. Target Project Privacy & File Hygiene
+
+| File / Asset | Location | Recommendation for Target Projects |
+| :--- | :--- | :--- |
+| **`PROJECT_HEALTH_REPORT.md` & `repo_map.txt`** | Target Project Root | **Commit & push:** Synchronize to git for shared team and AI access. |
+| **Test Code / Page Classes** | Target Project Repo | Commit & push to company SCM normally. |
+| **`PROJECT_AI_GUIDE.md`** | Target Project Root | **Shared mode:** Commit if team shares AI instructions.<br/>**Strict Privacy mode:** Add to `.gitignore` if company policy disallows AI markdown. |
+| **`.agents/` & Skills Hub** | `agent-skills` Repo | **Decoupled:** Exists solely in `agent-skills` repo; never copied into target project. |
+| **Temporary Dumps / Logs** | Target Project Root | Ensure added to target `.gitignore` (`Reports/`, `Screenshots/`, `*.log`). |
+
+---
+
+## 4. Push Protocol for `agent-skills` Hub
+
+When authoring or updating universal skills, rules, or tools inside the `agent-skills` repository itself:
+```bash
+git add -A
+git commit -m "feat(skills): update <skill-name> with new capabilities"
+git push origin <branch>
+```
+All skills and rules reside natively in the `agent-skills` repository.

package/.agents/rules/graphify.md

@@ -0,0 +1,14 @@
+---
+trigger: always_on
+description: Consult the graphify knowledge graph at graphify-out/ for codebase and architecture questions.
+---
+
+## graphify
+
+This project has a graphify knowledge graph at graphify-out/.
+
+Rules:
+- For codebase or architecture questions, when `graphify-out/graph.json` exists, first run `graphify query "<question>"` (CLI) or `query_graph` (MCP). Use `graphify path "<A>" "<B>"` / `shortest_path` for relationships and `graphify explain "<concept>"` / `get_node` for focused concepts. These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output.
+- If graphify-out/wiki/index.md exists, navigate it instead of reading raw files
+- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context
+- After modifying code files in this session, run `graphify update .` to keep the graph current (AST-only, no API cost)

package/.agents/rules/lessons-learned.md

@@ -0,0 +1,23 @@
+---
+trigger: always_on
+description: Critical anti-patterns, past mistakes, and strict avoidance rules (capped < 40 lines).
+---
+
+# Agent Anti-Pattern Blacklist & Failure Prevention
+
+> **Policy:** Hot-memory lessons learned. Hard-capped at **Max 8 rules (< 40 lines, ~150 tokens)**.
+> When table exceeds 8 rows, consolidate similar rules into higher-order invariants or archive to `~/.agent_memory/global_cache.db`.
+
+| # | Mistake / Anti-Pattern | Root Cause | Mandatory Avoidance Rule |
+|---|---|---|---|
+| **1** | **XPath strings parsed as methods** | Regex captured `String TXT = "...contains(...)"`. | In Groovy, `=` before `(` denotes a variable/constant, **never** a method. |
+| **2** | **GIS map polygon rejected** | Fixed `(100, 200)` coordinates caused overlap. | Always randomize coordinates via `TestHelper.getUniquePolygonCoordinates()`. |
+| **3** | **`ElementClickInterceptedException`** | Clicked while PrimeNG overlay backdrop was fading. | Always use `BasePage.clickJS()` or `window.__helper.clickSafe()` to bypass overlays. |
+| **4** | **Context window blowout** | Read 4,368-line `DataMiningPage.groovy` directly. | **Never read large files whole.** Query `tools/repo_map.txt` or read 20-50 line ranges. |
+| **5** | **Flaky timing on CI/CD** | `Thread.sleep` failed under variable network lag. | Replace 100% with Smart Wait: Angular `isStable()` and CDP `Network Idle 0`. |
+| **6** | **DB polluted with test junk** | Created entities without executing deletion. | Every data creation test case **must** execute idempotent teardown cleanup. |
+
+### Memory Management & Consolidation Protocol:
+- **Max capacity:** 8 active rules in prompt hot memory.
+- **Negative Feedback Cache (Blind Retry Prevention):** Whenever a bug fix attempt fails during test verification, AI agents MUST immediately persist it via `agent-qa heal record-failed --error "<sig>" --patch "<failed_code>" --reason "<why_failed>"` to prevent repeating the failed patch.
+- **Overflow policy:** Consolidate related patterns into a single generalized invariant; offload edge cases to SQLite `~/.agent_memory/global_cache.db` (0-token cold storage).

package/.agents/rules/mandatory-playwright-live.md

@@ -0,0 +1,29 @@
+---
+trigger: always_on
+description: Mandatory rules for Autonomous Multi-Agent Swarm, Pure Headless Playwright Live interaction (1920x1080), and Zero-Second Auth.
+---
+
+# Mandatory Rules: Autonomous Multi-Agent Swarm, Live Playwright & Failure Analysis
+
+Mandatory for all test automation tasks in enterprise web test suites:
+
+1. **Autonomous Swarm Orchestration:**
+   - Main AI acts as **Lead QA Orchestrator**, executing directions from **Project Lead / QA Director** and coordinating 5 specialized subagents:
+     * **Live Interaction Explorer:** Probe live DOM/AOM via Playwright MCP (`browser_run_code_unsafe`).
+     * **Automation Code Crafter:** Generate Page Classes and Groovy scripts adhering to Clean POM Flat Architecture.
+     * **Test Execution Runner:** Dispatch headless Katalon tests via CLI.
+     * **Quality Gatekeeper & Failure Analyst:** Enforce 100% UTF-8 No BOM, block bypass logic, analyze failures via `FAILED_*.png` and Allure reports.
+     * **Technical Documentation Specialist:** Translate code to business workflows, generate Mermaid diagrams.
+2. **Anti-Redundancy Protocol:**
+   - Single sign-on via Zero-Second Auth (`session.json`); never re-enter login forms.
+   - Live Explorer emits JSON Data Contract -> Code Crafter consumes to codify; Documentation Specialist consumes to chart workflows. Zero redundant DOM rescanning.
+   - Targeted re-tests only on failed cases; never re-run entire batches for single-case bug fixes.
+   - Quality Gatekeeper conducts deep RCA only on actual FAILED cases; immediately accept PASSED runs.
+3. **Playwright Live Interaction & Mandatory Headless:**
+   - All flow discovery, live probing, and bug fixing **MUST RUN IN PURE HEADLESS MODE**.
+   - Do not open browser GUI windows to avoid stealing user desktop focus.
+   - Maintain standard virtual Full HD `1920x1080` (`viewport: { width: 1920, height: 1080 }`).
+4. **5 Superpowers & 5 AI Paradigms:**
+   - Zero-Second Auth, Direct API Seeding, Accessibility Tree (AOM), Multi-Context Dual Role, Route Mocking.
+   - Self-Healing Selectors, Multimodal Visual Assertions, Autonomous Fuzzing, CDP Deep Profiling, Multi-Agent Swarm.
+5. **Reference Documentation:** Follow [SKILL.md](.agents/skills/playwright-live-interaction/SKILL.md) and [swarm_orchestration.md](.agents/skills/playwright-live-interaction/references/swarm_orchestration.md).

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

@@ -0,0 +1,42 @@
+---
+trigger: always_on
+description: Skill Resolution Precedence and Anti-Collision Protocol enforcing Workspace-Local skills over external generic plugin skills.
+---
+
+# Skill Resolution Precedence & Anti-Collision Protocol
+
+> **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, Agent must strictly apply the following resolution order:
+
+```text
+[Tier 1: Project-Local Skills] (.agent/skills/*) 
+       v (Higher priority - Specialized & Context-Aware)
+[Tier 2: Core Project Rules] (.agents/rules/*)
+       v
+[Tier 3: External Plugin Skills] (antigravity-testing-kit, chrome-devtools-plugin)
+```
+
+---
+
+## 2. Specific Skill Mapping & Exclusion Matrix
+
+| Task Type | REQUIRED Skill (Tier 1) | EXCLUDED / SUPPRESSED Skill (Tier 3) | Reason |
+|---|---|---|---|
+| **Test Script & POM Generation** | `clean-pom-crafter`<br/>`lam-script-generator` | `QA Automation Engineer` | Enforces Flat Architecture, zero XPaths in scripts, dynamic `uniqueCode`, and 2-phase search. Generic plugin templates violate Clean POM standards. |
+| **Locator Healing & DOM Diffing** | `self-healing-locator`<br/>`failure-autopsy-and-healing` | `Locator Healer Agent` | Uses token-efficient AOM diffing (Role > Label > TestId) and reads local JUnit XML/Screenshots. |
+| **Flaky Test Triage & Root Cause** | `failure-autopsy-and-healing` | `Flaky Test Analyzer` | Triage occurs via 0-token JUnit XML parsing, `Screenshots/FAILED_*.png` autopsy, and SQLite cosine cache (`memory_cache.db`). |
+| **Live Web & Locator Probing** | `playwright-live-interaction` | `Smart Locator Agent` | Direct CDP network idle 0, PrimeNG overlay bypass, and in-browser helper integration. |
+| **Code Refactoring & Tech Debt** | `code-refactoring-refactor-clean` | *(Consolidated)* | Single unified skill covering SOLID refactoring, code smells, and technical debt remediation. |
+| **Accessibility (A11y) Testing** | `wcag-audit-patterns`<br/>*(Guideline)* | `a11y-debugging`<br/>*(Tooling Only)* | `wcag-audit-patterns` governs WCAG 2.2 rules; `a11y-debugging` is used solely for low-level Chrome DevTools inspection. |
+
+---
+
+## 3. Strict Prohibitions
+
+1. **Never use generic test generation:** Do not generate boilerplate Selenium/Cucumber tests from external plugins that use `findTestObject` or Object Repository folders.
+2. **Never dump raw HTML for locator healing:** Always extract compact AOM subtrees (< 500 tokens).