synapse-hub 2.2.4 → 2.4.1

package/docs/PLUGIN_DEVELOPMENT_GUIDE.md

@@ -0,0 +1,126 @@
+# 3rd-Party Plugin Development Guide — Synapse Hub
+
+> **Specification Version:** 2.2.4  
+> **Hub Core Provenance:** Thế Vị (@TeeVee998) — [Synapse Hub](https://github.com/TeeVee998/Synapse-Hub)  
+
+---
+
+## 1. Overview
+
+Synapse Hub provides a decoupled, modular architecture enabling 3rd-party teams and community contributors to extend the Hub with specialized QA skills, runner adapters, or domain-specific security linters.
+
+Every 3rd-party plugin is an independent package registered via `plugin.json` and vetted by the built-in **SkillSpector Security Sentinel** (`tools/skillspector.py`).
+
+---
+
+## 2. Plugin Structure & File Conventions
+
+A standard Synapse Hub plugin adheres to the following directory layout:
+
+```text
+my-custom-plugin/
+├── plugin.json                    # Mandatory plugin manifest
+├── README.md                      # Plugin documentation & quickstart
+├── skills/                        # Packaged AI skills (one folder per skill)
+│   └── custom-security-audit/
+│       ├── SKILL.md               # Standardized YAML frontmatter + prompt
+│       └── examples/
+│           └── audit_sample.json  # Demonstrable example fixture
+└── tools/                         # Executable CLI tools (Python 3.9+)
+    └── custom_auditor.py          # Deterministic, standalone tool
+```
+
+---
+
+## 3. Plugin Manifest Specification (`plugin.json`)
+
+The root `plugin.json` declares identity, capabilities, and dependencies:
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "name": "sample-custom-plugin",
+  "version": "1.0.0",
+  "description": "3rd-party plugin extending Synapse Hub with custom HTTP security header auditing.",
+  "author": "Community Contributor",
+  "license": "MIT",
+  "repository": "https://github.com/example/sample-custom-plugin",
+  "skills": [
+    "custom-security-headers-audit"
+  ],
+  "tools": [
+    "tools/custom_security_headers.py"
+  ],
+  "minHubVersion": "2.2.0"
+}
+```
+
+### Manifest Fields:
+- `name` *(string, required)*: Unique kebab-case identifier.
+- `version` *(string, required)*: Semantic versioning (`x.y.z`).
+- `description` *(string, required)*: Concise summary of provided capabilities.
+- `skills` *(array of strings)*: List of skill folder names inside `skills/`.
+- `tools` *(array of strings)*: Relative file paths to executable scripts in `tools/`.
+- `minHubVersion` *(string)*: Minimum compatible Synapse Hub core version.
+
+---
+
+## 4. Skill Authoring Standard (`SKILL.md`)
+
+Each skill must contain valid YAML frontmatter followed by clear, token-optimized instructions:
+
+```markdown
+---
+name: custom-security-headers-audit
+description: Audits web applications for missing or misconfigured HTTP security headers (CSP, HSTS, X-Frame-Options).
+version: 1.0.0
+category: security_and_compliance
+---
+
+# Custom Security Headers Audit Skill
+
+## Purpose
+Inspects target endpoint response headers and reports compliance against OWASP ASVS Section 14.
+
+## Quick CLI Execution
+```bash
+python tools/custom_security_headers.py https://staging.example.com --json report.json
+```
+```
+
+### Skill Invariants:
+1. **Token Ceiling:** Every `SKILL.md` must be $\le 1.500$ tokens (enforced by `scripts/lint_skills.ps1`).
+2. **100% UTF-8 No BOM:** Zero BOM bytes (`0xEF, 0xBB, 0xBF`).
+3. **Evidence-First:** Must reference deterministic tools rather than guessing.
+
+---
+
+## 5. Security & Safety Invariants (DoD Compliance)
+
+All 3rd-party tools and scripts must adhere to Synapse Hub's safety rules:
+
+1. **Zero `shell=True` Policy:** Never invoke `subprocess.Popen` or `subprocess.run` with `shell=True`. Always pass structured lists:
+   ```python
+   # Correct:
+   subprocess.run(["curl", "-I", url], capture_output=True, check=True)
+   # FORBIDDEN (will be rejected by Gatekeeper):
+   subprocess.run(f"curl -I {url}", shell=True)
+   ```
+2. **Environment Allowlist Guard:** Any tool performing destructive modifications or fuzzing must verify staging allowlists (`SYNAPSE_ALLOW_PROD_FUZZ=1`).
+3. **No Hardcoded Credentials:** Never store plaintext secrets or passwords.
+
+---
+
+## 6. Vetting & Verification Pipeline
+
+Before distributing or publishing a plugin, run the Hub's verification sentinels:
+
+```bash
+# 1. Run SkillSpector Security Scan (Must report 0 High/Critical warnings)
+python tools/skillspector.py --target path/to/my-custom-plugin
+
+# 2. Run Quality Gates Linting
+python tools/verify_all.py --target path/to/my-custom-plugin
+```
+
+Once passed, the plugin can be mounted directly into the Antigravity Plugin directory (`~/.gemini/config/plugins/`) or integrated via `skills_manifest.json`.

package/docs/TOKEN_QUOTA_PLAYBOOK.md

@@ -0,0 +1,41 @@
+# Enterprise Token & Context Engineering Playbook (AI QA Hub)
+
+> **Objective:** Maximize AI Agent performance, eliminate context rot, and optimize token quota across the automated test engineering lifecycle.
+
+---
+
+## 1. AI Model Allocation Matrix
+
+Avoid depleting high-tier model quotas by applying the **"Right Task - Right Model"** strategy:
+
+| AI Model Tier | Capability & Relative Cost | Recommended QA Workloads | Token Consumption |
+| :--- | :--- | :--- | :--- |
+| **Claude Sonnet / Opus / GPT-4o** | ⭐⭐⭐ High | • Complex logic, nested Shadow DOM / iFrames<br>• Race conditions & complex async synchronization<br>• Flaky test root-cause autopsy & Clean POM refactoring | 🔴 Expensive (Use selectively) |
+| **Gemini Pro / Claude 3.5 Sonnet** | ⭐⭐ Balanced | • Everyday POM code generation, assertions, locator updates<br>• User Story to automated test transpilation<br>• Unit tests, REST API stubs & mock routes | 🟡 Moderate |
+| **Gemini Flash / Claude Haiku** | ⭐ High-Speed & Low-Cost | • Parsing multi-thousand-line CI/CD logs (`distill_log.py`)<br>• Generating synthetic test data (JSON/CSV rows)<br>• Compact AOM extraction & DOM structure filtering<br>• Summaries, documentation, commit messages | 🟢 Ultra-economical |
+
+---
+
+## 2. Operational Mode Strategy
+
+- **Planning Mode:**
+  - Bootstrap new test automation frameworks from scratch.
+  - Architect multi-tier Page Object Model hierarchies for large modules.
+  - Analyze complex End-to-End user journeys traversing multiple microservices.
+- **Fast / Chat Mode:**
+  - Add individual test cases to existing Page Classes.
+  - Heal single selectors after UI builds.
+  - Debug and re-run isolated test scripts.
+
+---
+
+## 3. Context Window Invariants (Zero Context Rot)
+
+1. **Progressive Disclosure (Never Load Large Files Whole):**
+   - Never load classes over 500 lines into the active conversation prompt.
+   - Query `tools/repo_map.txt` for method signatures first (~500 tokens). Micro-read targeted 20-50 line slices (`StartLine`, `EndLine`).
+2. **Log Distillation (`distill_log.py`):**
+   - Never dump thousands of lines of raw build/runner output.
+   - Run `python3 tools/distill_log.py <path_to_log>` to filter out 95% noise, extracting only the exact failure line and last 3 HTTP requests.
+3. **Compaction State Anchoring (`project_state.py`):**
+   - Antigravity automatically triggers Context Compaction near the ~135k token threshold. Ensure active test run statuses and defect IDs are persisted to `PROJECT_STATE.md` on disk to avoid lossy state compression.

package/docs/adopted-ecosystem-tools.md

@@ -0,0 +1,87 @@
+# Adopted Ecosystem Tools Guide
+
+Companion guide to the seven skills adopted from the open-source Claude ecosystem (see `NOTICE`, entries 16-21). The items below are **external tools that are recommended but NOT copied into this repository** — they run outside the hub, so this page records only vetted install/config snippets and the token-discipline rules that apply when using them.
+
+> **Rule:** any tool here is activated on-demand only (Zero-Command Autoproactivity, `AGENTS.md` Section 3). Never install or run one blindly, and never paste API keys into committed files (Gate 6).
+
+## 1. github-mcp (github/github-mcp-server) — MIT
+
+Official MCP server exposing GitHub (issues, PRs, Actions, security) to agents. Primary hub use: `orchestrator` / `failure-analyst` filing bug tickets and reading CI failures.
+
+```bash
+# Local via Docker, read-only, minimal toolsets (token discipline)
+claude mcp add github \
+  -e GITHUB_PERSONAL_ACCESS_TOKEN \
+  -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN \
+  ghcr.io/github/github-mcp-server \
+  --read-only --toolsets "repos,issues,pull_requests,actions"
+```
+
+- Use a minimum-scope PAT; prefer the `--read-only` flag for agent sessions.
+- Enable only the toolsets a task needs — every loaded toolset costs context.
+
+## 2. playwright-mcp (microsoft/playwright-mcp) — Apache-2.0
+
+Browser control over the accessibility tree (~78 tools). Primary hub use: `live-explorer` fallback when scripted helpers are not enough.
+
+```bash
+claude mcp add playwright -- npx @playwright/mcp@latest \
+  --headless --caps "testing,network"
+```
+
+- Enable capability flags selectively (`--caps`); the full surface is a context hog.
+- Snapshot mode is the main token cost: prefer `browser_find`/targeted probes over full-page snapshots, and disable snapshots for pure action sequences.
+- The hub's `playwright-live-interaction` skill and `tools/browser_helpers.js` remain the default; MCP is the agentic-loop complement (long stateful browser sessions).
+
+## 3. cc-switch (farion1231/cc-switch) — MIT
+
+Desktop app managing provider/API configs for many AI coding tools at once.
+
+- Relevant hub fit: its Skills-sync panel targets `~/.agents/skills`, matching this hub's layout; its usage dashboard tracks quota/token consumption per provider — useful against the manual telemetry footer.
+- Install from the project releases; run fully local. Cloud sync (WebDAV/S3) is optional and off by default.
+
+## 4. claude-hud (jarrodwatts/claude-hud) — MIT
+
+Statusline HUD showing context usage, 5h/7-day quota, cache hit rate, and cost.
+
+```bash
+/plugin marketplace add jarrodwatts/claude-hud
+/claude-hud:setup
+```
+
+- Automates the observation half of the hub's telemetry footer (quota, cache hit, token totals) without touching prompts or model behavior.
+
+## 5. repomix (yamadashy/repomix) — MIT
+
+Packs a repository into one AI-friendly file with per-file token counts.
+
+```bash
+npx repomix --compress        # tree-sitter skeleton pack, fewer tokens
+```
+
+- Hub use: onboarding artifacts for subagents, external audits. Secretlint integration aligns with Gate 6 (credential security).
+- Run from the target project root; output is generated locally (`repomix-output.xml`), and `tools/repo_map.*` remains the hub's own compressed alternative.
+
+## 6. graphify (Graphify-Labs/graphify) — Apache-2.0
+
+Builds a queryable knowledge graph of a directory (tree-sitter AST, ~40 languages including Groovy).
+
+- Hub use: maps Katalon `.groovy` suites and `tools/*.py` the hub's own AST tooling does not cover end-to-end; `graph.json` feeds blast-radius analysis alongside `tools/test_impact.py` and the `graphify-impact-analyzer` skill.
+- Fully local for code (no LLM calls); run `graphify install` to register the skill with your agent host.
+
+## 7. firecrawl (firecrawl/firecrawl) — AGPL-3.0
+
+Web scraping/search API returning LLM-ready markdown. Recommended via **cloud tier + API key**, not self-host (the AGPL monorepo stack is heavy and license-incompatible to embed in this MIT repo — same policy as NOTICE entry 3).
+
+```bash
+npx firecrawl-mcp   # with FIRECRAWL_API_KEY set in the environment
+```
+
+- Hub use: Stage 1 Discovery data gathering for `live-explorer` when the target data lives outside the browser under test.
+
+## 8. claude-code-router (musistudio/claude-code-router) — MIT
+
+Local model gateway (default `127.0.0.1:3456`) with routing, retry, failover, and per-request token/cost logs.
+
+- **Security note:** it is a man-in-the-middle for API keys — run strictly local, never expose the port, and audit its config before pointing production credentials at it.
+- Hub use: route mechanical subagent work to cheaper models while keeping strong models for synthesis/review; its request logs match the hub telemetry fields (token in/out, cost).

package/docs/schemas/synapse.config.schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "SynapseHubConfig",
+  "description": "Configuration schema for Synapse Hub Enterprise QA Sentinel",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "URI of the JSON schema specification"
+    },
+    "version": {
+      "type": "string",
+      "description": "Synapse Hub release semver"
+    },
+    "quality_gates": {
+      "type": "object",
+      "description": "Definition-of-Done Quality Gate configuration",
+      "properties": {
+        "mutation_min_score": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 100,
+          "default": 80,
+          "description": "Minimum acceptable assertion sensitivity score"
+        },
+        "gates": {
+          "type": "object",
+          "properties": {
+            "gate_0_author_integrity": { "type": "boolean" },
+            "gate_1_bom_check": { "type": "boolean" },
+            "gate_2_path_portability": { "type": "boolean" },
+            "gate_3_clean_pom": { "type": "boolean" },
+            "gate_4_ai_docs_lint": { "type": "boolean" },
+            "gate_5_cleanup_blacklist": { "type": "boolean" },
+            "gate_6_credential_security": { "type": "boolean" },
+            "gate_7_infer_linter": { "type": "boolean" },
+            "gate_8_micro_mutator": { "type": "boolean" }
+          },
+          "additionalProperties": false
+        }
+      },
+      "required": ["mutation_min_score", "gates"]
+    },
+    "infer_linter": {
+      "type": "object",
+      "description": "Static defect and fake-pass AST linter configuration",
+      "properties": {
+        "enabled": { "type": "boolean", "default": true },
+        "strict": { "type": "boolean", "default": true },
+        "format": { "type": "string", "enum": ["text", "json", "junit"], "default": "text" },
+        "exclude_paths": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "disabled_rules": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      },
+      "required": ["enabled"]
+    }
+  },
+  "required": ["version", "quality_gates"]
+}

package/examples/cypress-ecommerce-suite/README.md

@@ -0,0 +1,45 @@
+# 🌲 Cypress JavaScript Reference Suite (Clean POM & Synapse Guardrails)
+
+This directory provides a production-grade **Cypress (JavaScript)** reference suite demonstrating the Clean Page Object Model (POM) and Flat Architecture standards enforced by **Synapse Hub**.
+
+---
+
+## 🌟 End-to-End Testing Lifecycle (Story ➔ Test Cases ➔ Script ➔ Report)
+
+```mermaid
+flowchart LR
+    Story["1. User Story<br/>(E-Commerce Checkout)"] --> Matrix["2. Test Case Matrix<br/>(Equivalence & Boundary)"]
+    Matrix --> POM["3. Clean POM Pages<br/>(CartPage, CheckoutPage)"]
+    POM --> Spec["4. Cypress Spec<br/>(checkout.cy.js)"]
+    Spec --> Report["5. JUnit / Mochawesome<br/>(DoD Verified)"]
+```
+
+### 1. User Story & Acceptance Criteria
+- **Story:** *As a customer, I want to review my shopping cart and apply a valid discount coupon so that my total price updates before placing an order.*
+- **Acceptance Criteria (AC):**
+  - AC1: Cart must show items, quantities, and price breakdown.
+  - AC2: Valid coupon code (e.g. `SAVE20`) deducts 20% from subtotal.
+  - AC3: Invalid coupon code displays red error toast: *"Mã giảm giá không hợp lệ"*.
+  - AC4: Empty cart checkout button must remain disabled.
+
+### 2. Key Architectural Patterns Enforced
+- **Zero Raw Selectors in Specs:** `cypress/e2e/checkout.cy.js` calls only semantic methods on `CartPage` and `CheckoutPage`.
+- **Resilient ARIA Locators:** Page objects use `cy.findByRole`, `cy.findByLabel`, or scoped semantic CSS.
+- **Dynamic Idempotency:** Uses `BasePage.uniqueCode('ORDER_')` for order identifiers.
+- **Smart Synchronization:** Replaces static `cy.wait(5000)` with network route assertions and spinner detachment.
+
+---
+
+## 🚀 How to Run & Verify
+
+```bash
+# 1. Run Synapse AST Test Linter (Zero-token verification)
+npx synapse-hub lint ./cypress/e2e
+
+# 2. Verify 9 Quality Gates DoD
+npx synapse-hub verify
+
+# 3. Run Headless Cypress
+npm install
+npx cypress run --spec "cypress/e2e/checkout.cy.js"
+```

package/examples/cypress-ecommerce-suite/cypress/e2e/checkout.cy.js

@@ -0,0 +1,17 @@
+const cartPage = require('../pages/CartPage');
+
+describe('E-Commerce Cart & Discount Coupon Validation', () => {
+  beforeEach(() => {
+    cartPage.openCart();
+  });
+
+  it('TC-ECOM-01: Successfully apply 20% discount coupon to cart', () => {
+    cartPage.applyCoupon('SAVE20');
+    cartPage.verifyDiscountApplied('-20%');
+  });
+
+  it('TC-ECOM-02: Display error when applying invalid or expired coupon', () => {
+    cartPage.applyCoupon('EXPIRED_COUPON_999');
+    cartPage.verifyCouponError('Mã giảm giá không hợp lệ');
+  });
+});

package/examples/cypress-ecommerce-suite/cypress/pages/BasePage.js

@@ -0,0 +1,29 @@
+/**
+ * BasePage — Universal Cypress Base Page Object
+ * Enforces dynamic idempotency, smart waiting, and common interactions.
+ */
+class BasePage {
+  /**
+   * Generates dynamic unique identifier for test data isolation.
+   */
+  static uniqueCode(prefix = 'AUTO_') {
+    return `${prefix}${Date.now()}_${Math.floor(Math.random() * 1000)}`;
+  }
+
+  /**
+   * Waits for loading spinner/overlay detachment.
+   */
+  waitForSpinnerDetached() {
+    cy.get('.spinner-overlay, .loading-backdrop', { timeout: 10000 }).should('not.exist');
+  }
+
+  /**
+   * Navigates to a relative path.
+   */
+  navigate(path = '/') {
+    cy.visit(path);
+    this.waitForSpinnerDetached();
+  }
+}
+
+module.exports = BasePage;

package/examples/cypress-ecommerce-suite/cypress/pages/CartPage.js

@@ -0,0 +1,51 @@
+const BasePage = require('./BasePage');
+
+class CartPage extends BasePage {
+  // Encapsulated locators
+  get couponInput() {
+    return cy.get('input[name="couponCode"]');
+  }
+
+  get applyCouponButton() {
+    return cy.contains('button', 'Áp dụng');
+  }
+
+  get discountBadge() {
+    return cy.get('[data-testid="discount-amount"]');
+  }
+
+  get errorMessageToast() {
+    return cy.get('.toast-error, .notification-error');
+  }
+
+  get checkoutButton() {
+    return cy.contains('button', 'Tiến hành đặt hàng');
+  }
+
+  // Business Action Methods
+  openCart() {
+    this.navigate('/cart');
+  }
+
+  applyCoupon(couponCode) {
+    this.couponInput.clear().type(couponCode);
+    this.applyCouponButton.click();
+    this.waitForSpinnerDetached();
+  }
+
+  proceedToCheckout() {
+    this.checkoutButton.click();
+    this.waitForSpinnerDetached();
+  }
+
+  // Verification Methods
+  verifyDiscountApplied(expectedDiscount) {
+    this.discountBadge.should('be.visible').and('contain.text', expectedDiscount);
+  }
+
+  verifyCouponError(expectedError) {
+    this.errorMessageToast.should('be.visible').and('contain.text', expectedError);
+  }
+}
+
+module.exports = new CartPage();

package/examples/cypress-ecommerce-suite/cypress.config.js

@@ -0,0 +1,13 @@
+const { defineConfig } = require('cypress');
+
+module.exports = defineConfig({
+  e2e: {
+    baseUrl: 'https://staging-shop.example.com',
+    specPattern: 'cypress/e2e/**/*.cy.js',
+    supportFile: false,
+    viewportWidth: 1920,
+    viewportHeight: 1080,
+    video: false,
+    screenshotOnRunFailure: true,
+  },
+});

package/examples/cypress-ecommerce-suite/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "cypress-ecommerce-suite",
+  "version": "1.0.0",
+  "description": "Production Cypress Clean POM Reference Suite for Synapse-Hub",
+  "scripts": {
+    "test": "cypress run",
+    "test:open": "cypress open",
+    "lint:synapse": "npx synapse-hub lint ./cypress/e2e"
+  },
+  "devDependencies": {
+    "cypress": "^13.6.0"
+  }
+}

package/examples/katalon-suite/Keywords/pages/BasePage.groovy

@@ -0,0 +1,19 @@
+package pages
+
+import com.kms.katalon.core.webui.keyword.WebUiBuiltInKeywords as WebUI
+import com.kms.katalon.core.model.FailureHandling
+
+/**
+ * BasePage encapsulating reusable Clean POM operations and smart synchronization.
+ */
+public class BasePage {
+
+    public static String uniqueCode(String prefix = "AUTO_") {
+        return prefix + System.currentTimeMillis()
+    }
+
+    public void waitForReady(int timeoutSec = 10) {
+        // Smart wait: wait for page document state without static Thread.sleep
+        WebUI.waitForPageLoad(timeoutSec, FailureHandling.OPTIONAL)
+    }
+}

package/examples/katalon-suite/Keywords/pages/DashboardPage.groovy

@@ -0,0 +1,29 @@
+package pages
+
+import com.kms.katalon.core.testobject.TestObject
+import com.kms.katalon.core.testobject.ConditionType
+import com.kms.katalon.core.webui.keyword.WebUiBuiltInKeywords as WebUI
+
+/**
+ * DashboardPage displaying business KPIs and metrics.
+ */
+public class DashboardPage extends BasePage {
+
+    private TestObject headerDashboard = makeTestObject("//h1[contains(text(), 'Dashboard')]")
+    private TestObject cardActiveUsers = makeTestObject("//div[@data-testid='card-active-users']")
+
+    private static TestObject makeTestObject(String xpath) {
+        TestObject to = new TestObject()
+        to.addProperty("xpath", ConditionType.EQUALS, xpath)
+        return to
+    }
+
+    public boolean isDashboardLoaded() {
+        waitForReady()
+        return WebUI.verifyElementPresent(headerDashboard, 10)
+    }
+
+    public String getActiveUsersCount() {
+        return WebUI.getText(cardActiveUsers)
+    }
+}

package/examples/katalon-suite/Keywords/pages/LoginPage.groovy

@@ -0,0 +1,45 @@
+package pages
+
+import com.kms.katalon.core.testobject.TestObject
+import com.kms.katalon.core.testobject.ConditionType
+import com.kms.katalon.core.webui.keyword.WebUiBuiltInKeywords as WebUI
+
+/**
+ * LoginPage adhering strictly to Clean POM Flat Architecture.
+ * Encapsulates all DOM selectors and interaction methods.
+ */
+public class LoginPage extends BasePage {
+
+    private TestObject txtUsername = makeTestObject("//input[@id='username']")
+    private TestObject txtPassword = makeTestObject("//input[@id='password']")
+    private TestObject btnLogin = makeTestObject("//button[@id='btn-login']")
+    private TestObject msgSuccess = makeTestObject("//div[contains(@class, 'alert-success')]")
+
+    private static TestObject makeTestObject(String xpath) {
+        TestObject to = new TestObject()
+        to.addProperty("xpath", ConditionType.EQUALS, xpath)
+        return to
+    }
+
+    public LoginPage navigate(String url) {
+        WebUI.openBrowser("")
+        WebUI.navigateToUrl(url)
+        waitForReady()
+        return this
+    }
+
+    public LoginPage enterCredentials(String username, String password) {
+        WebUI.setText(txtUsername, username)
+        WebUI.setText(txtPassword, password)
+        return this
+    }
+
+    public void submitLogin() {
+        WebUI.click(btnLogin)
+        waitForReady()
+    }
+
+    public boolean isLoginSuccessful() {
+        return WebUI.verifyElementPresent(msgSuccess, 10)
+    }
+}

package/examples/katalon-suite/Profiles/default.glbl

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<GlobalVariableEntities>
+   <description></description>
+   <name>default</name>
+   <tag></tag>
+   <defaultProfile>true</defaultProfile>
+   <GlobalVariableEntity>
+      <description>Base application URL</description>
+      <initValue>'https://app.enterprise-demo.com'</initValue>
+      <name>BASE_URL</name>
+   </GlobalVariableEntity>
+</GlobalVariableEntities>

package/examples/katalon-suite/README.md

@@ -0,0 +1,18 @@
+# Katalon Studio Clean POM Reference Suite
+
+Enterprise Katalon Studio web automation project adhering to Synapse Hub Clean POM & Flat Architecture standards.
+
+## Architecture Guidelines Enforced:
+1. **Flat Architecture:** All Page Classes reside in `Keywords/pages/` extending `BasePage`.
+2. **Zero-Locator Scripts:** Test scripts in `Scripts/` contain only business method calls. Zero raw XPaths or CSS selectors.
+3. **Smart Wait:** Prohibits static `Thread.sleep`. Uses dynamic smart waits.
+4. **Idempotent Data:** Dynamic `BasePage.uniqueCode("AUTO_")` with timestamps.
+
+## Validation via Synapse Hub:
+```bash
+# Validate Clean POM and 9 Quality Gates DoD:
+npx synapse-hub verify --mode target
+
+# Run AST Linter:
+npx synapse-hub lint
+```

package/examples/katalon-suite/Scripts/Auth/TC_LoginSuccess/Script1234567890.groovy

@@ -0,0 +1,12 @@
+import pages.LoginPage
+import com.kms.katalon.core.webui.keyword.WebUiBuiltInKeywords as WebUI
+
+// Clean POM Test Script: Zero raw XPaths/CSS selectors
+LoginPage loginPage = new LoginPage()
+
+loginPage.navigate("https://app.enterprise-demo.com/login")
+         .enterCredentials("qa_automation_user", "SecurePass123!")
+         .submitLogin()
+
+assert loginPage.isLoginSuccessful() == true
+WebUI.closeBrowser()

package/examples/katalon-suite/Scripts/Dashboard/TC_ViewSummary/Script1234567891.groovy

@@ -0,0 +1,15 @@
+import pages.LoginPage
+import pages.DashboardPage
+import com.kms.katalon.core.webui.keyword.WebUiBuiltInKeywords as WebUI
+
+LoginPage loginPage = new LoginPage()
+DashboardPage dashboardPage = new DashboardPage()
+
+loginPage.navigate("https://app.enterprise-demo.com/login")
+         .enterCredentials("qa_lead", "LeadSecret2026!")
+         .submitLogin()
+
+assert dashboardPage.isDashboardLoaded() == true
+String userCount = dashboardPage.getActiveUsersCount()
+assert userCount != null
+WebUI.closeBrowser()