synapse-hub 0.0.0-stage → 2.0.0

package/.agents/skills/security-dast-sentinel/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: security-dast-sentinel
+description: Dynamic Application Security Testing (DAST) and OWASP Top 10 automated verification for web apps and APIs. Audits security response headers (CSP, HSTS, X-Frame-Options), detects sensitive data leaks (PII, tokens, internal stacktraces), asserts BOLA/IDOR authorization boundaries via role token swapping, and validates CORS configurations.
+---
+
+# Security DAST Sentinel (Dynamic Application Security & OWASP Top 10)
+
+> **Purpose:** Automated Dynamic Application Security Testing (DAST) and defensive runtime verification across enterprise web applications and REST/GraphQL APIs. Bridges functional automated testing with OWASP Top 10 defensive compliance gates.
+
+---
+
+## 1. Core Defensive Scope & OWASP Top 10 Coverage
+
+```mermaid
+flowchart TD
+    A["<b>Security DAST Sentinel</b><br/>Runtime Defensive Verification"] --> B["<b>1. HTTP Security Headers</b><br/>CSP, HSTS, X-Frame-Options, MIME Sniff"]
+    A --> C["<b>2. Sensitive Data Exposure</b><br/>PII, Secrets, Tokens, Stacktrace Leakage"]
+    A --> D["<b>3. Broken Object Auth (BOLA/IDOR)</b><br/>Horizontal/Vertical Role Token Swapping"]
+    A --> E["<b>4. CORS & Origin Misconfig</b><br/>Origin Reflection, Credentials Wildcard"]
+```
+
+| OWASP Category | Threat Vector | Automated Defensive Check | Assertion Target |
+| :--- | :--- | :--- | :--- |
+| **A01: Broken Access Control** | BOLA / IDOR | Swapping User A's Bearer token into User B's resource URI | HTTP `403 Forbidden` or `404 Not Found` (Never `200 OK`) |
+| **A01: Broken Access Control** | CORS Misconfiguration | Sending unauthorized `Origin` header with `Credentials: include` | Must NOT reflect origin with `Access-Control-Allow-Credentials: true` |
+| **A02: Cryptographic Failures** | Insecure Transport & Missing HSTS | Inspecting headers on HTTPS endpoints | `Strict-Transport-Security: max-age=31536000; includeSubDomains` |
+| **A05: Security Misconfiguration** | Missing Security Headers | Passive audit on all page navigations & API responses | CSP, X-Frame-Options, X-Content-Type-Options: nosniff |
+| **A05: Security Misconfiguration** | Verbose Error Disclosure | Injecting invalid payload to trigger 4xx/5xx | Response must NOT contain `SQLException`, `Traceback`, or internal paths |
+| **A09: Security Logging & Monitoring** | Sensitive Data Leakage | Regex scan on API responses and local storage | Zero plaintext passwords, credit cards, or private keys |
+
+---
+
+## 2. HTTP Security Response Headers Audit
+
+All production and staging responses must enforce strict defensive headers to prevent Clickjacking, Cross-Site Scripting (XSS), and MIME-sniffing attacks.
+
+### Mandatory Security Header Policy
+1. `Content-Security-Policy`: Must define `default-src 'self'` or restrictive directive; must avoid `'unsafe-eval'` or open wildcards `*` in script sources.
+2. `Strict-Transport-Security`: `max-age=31536000; includeSubDomains` on HTTPS.
+3. `X-Frame-Options`: `DENY` or `SAMEORIGIN` (prevents UI clickjacking in external iframes).
+4. `X-Content-Type-Options`: `nosniff` (prevents browser MIME-type confusion).
+5. `Referrer-Policy`: `strict-origin-when-cross-origin` or `no-referrer`.
+6. `Permissions-Policy`: Restricts camera, microphone, and geolocation APIs.
+
+### Playwright Automated Headers Fixture (TypeScript)
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('DAST Security Headers Audit', () => {
+  test('verify mandatory security headers on target application', async ({ page }) => {
+    const response = await page.goto('/dashboard');
+    expect(response).not.toBeNull();
+    const headers = response!.headers();
+
+    // 1. Clickjacking Protection
+    const xFrame = headers['x-frame-options']?.toUpperCase();
+    expect(['DENY', 'SAMEORIGIN'], 'X-Frame-Options must be DENY or SAMEORIGIN').toContain(xFrame);
+
+    // 2. MIME Sniffing Protection
+    expect(headers['x-content-type-options'], 'Must prevent MIME sniffing').toBe('nosniff');
+
+    // 3. Strict Transport Security
+    if (page.url().startsWith('https://')) {
+      expect(headers['strict-transport-security'], 'HSTS must be enabled on HTTPS').toContain('max-age=');
+    }
+
+    // 4. Content Security Policy
+    const csp = headers['content-security-policy'];
+    expect(csp, 'Content-Security-Policy must be declared').toBeTruthy();
+    expect(csp).not.toContain("default-src *");
+  });
+});
+```
+
+---
+
+## 3. Sensitive Data Exposure (PII, Secrets & Error Leakage)
+
+API responses and client-side storage must never leak internal stack traces, system paths, unmasked PII, or authorization credentials.
+
+### Automated Response Interceptor Linter (Python / Playwright)
+```python
+import re
+from typing import Dict, List
+
+# Patterns matching accidental secret or stacktrace leakage
+SENSITIVE_LEAK_PATTERNS = [
+    (re.compile(r'-----BEGIN (?:RSA )?PRIVATE KEY-----'), "Exposed Private Key"),
+    (re.compile(r'(?i)\b(?:password|passwd|pwd)\b\s*[:=]\s*["\'][^"\']{4,}["\']'), "Exposed Plaintext Password"),
+    (re.compile(r'\b(?:4[0-9]{12}(?:[0-9]{3})?|5[1-5][0-9]{14})\b'), "Raw Credit Card Number (Visa/MC)"),
+    (re.compile(r'(?i)(?:SQLException|HibernateException|org\.postgresql\.util|java\.lang\.NullPointerException)'), "Database Stacktrace Leak"),
+    (re.compile(r'(?i)(?:Traceback \(most recent call last\)|File "[a-zA-Z0-9_\-\\/]+\.py", line \d+)'), "Python Stacktrace Leak"),
+    (re.compile(r'\b[a-zA-Z]:\\[a-zA-Z0-9_.\-\\]+\b'), "Internal Windows File Path Leak"),
+]
+
+def scan_response_for_leaks(body_text: str) -> List[str]:
+    """Inspects API response text for prohibited sensitive data leaks."""
+    violations = []
+    for pattern, description in SENSITIVE_LEAK_PATTERNS:
+        if pattern.search(body_text):
+            violations.append(description)
+    return violations
+```
+
+---
+
+## 4. Broken Object-Level Authorization (BOLA / IDOR) Testing
+
+BOLA occurs when an API endpoint uses user-supplied IDs to retrieve object instances without validating user ownership.
+
+### Automated Dual-Role Permutation Protocol
+1. **User A (Victim):** Log in and create Entity `X` (ID: `10042`).
+2. **User B (Attacker):** Log in as an unrelated user or tenant, acquire Token `B`.
+3. **Execute Cross-Tenant Query:** Dispatch `GET /api/v1/entities/10042` with `Authorization: Bearer <Token_B>`.
+4. **Assert Access Barrier:**
+   - `HTTP 403 Forbidden` or `HTTP 404 Not Found` => **PASS** (Zero BOLA).
+   - `HTTP 200 OK` with Entity `X` payload => **CRITICAL DEFECT: BOLA / IDOR VULNERABILITY**.
+
+```typescript
+test('BOLA Defense: Tenant B cannot access Tenant A entity', async ({ request }) => {
+  // Tenant A creates resource
+  const createRes = await request.post('/api/v1/invoices', {
+    headers: { 'Authorization': `Bearer ${tokenTenantA}` },
+    data: { amount: 5000, description: 'Confidential Invoice A' }
+  });
+  const invoiceId = (await createRes.json()).id;
+
+  // Tenant B attempts to read Tenant A's invoice
+  const readAttempt = await request.get(`/api/v1/invoices/${invoiceId}`, {
+    headers: { 'Authorization': `Bearer ${tokenTenantB}` }
+  });
+
+  // Assertion: System must block cross-tenant read
+  expect([403, 404], 'Tenant B must not access Tenant A invoice').toContain(readAttempt.status());
+});
+```
+
+---
+
+## 5. CORS Misconfiguration Audit
+
+CORS policies must never reflect arbitrary untrusted origins when credentials (cookies/tokens) are supported.
+
+```typescript
+test('CORS Defense: Server must not reflect arbitrary untrusted Origin with credentials', async ({ request }) => {
+  const untrustedOrigin = 'https://untrusted-attacker.com';
+  const response = await request.get('/api/v1/user/profile', {
+    headers: {
+      'Origin': untrustedOrigin,
+      'Authorization': `Bearer ${validUserToken}`
+    }
+  });
+
+  const allowOrigin = response.headers()['access-control-allow-origin'];
+  const allowCredentials = response.headers()['access-control-allow-credentials'];
+
+  // Critical CORS Flaw: Reflecting untrusted origin while allowing credentials
+  if (allowOrigin === untrustedOrigin && allowCredentials === 'true') {
+    throw new Error('CRITICAL CORS VULNERABILITY: Arbitrary origin reflection with credentials enabled');
+  }
+
+  // Critical CORS Flaw: Wildcard with credentials
+  if (allowOrigin === '*' && allowCredentials === 'true') {
+    throw new Error('CRITICAL CORS VULNERABILITY: Wildcard origin with credentials enabled');
+  }
+});
+```
+
+---
+
+## 6. Security DoD Verification Checklist
+- [ ] Mandatory security headers verified on root and core dashboard routes.
+- [ ] No `500 Server Error` response contains raw SQL exceptions or language stacktraces.
+- [ ] All ID-based mutation and query endpoints verified against BOLA/IDOR permutations.
+- [ ] CORS policies enforce whitelist or block `Credentials: true` with arbitrary origins.
+- [ ] All security testing conducted non-destructively in defensive QA test suites.

package/.agents/skills/self-healing-locator/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: self-healing-locator
+description: >-
+  Token-efficient self-healing locator skill using Accessibility Tree (AOM) and semantic DOM diffing with Role > Label > TestId hierarchy, avoiding raw HTML bloat.
+---
+
+# Self-Healing Locator Skill — Token-Efficient AOM Diffing
+
+This skill provides an automated, token-conservative mechanism to diagnose, diff, and repair broken web element locators across web applications without overwhelming the LLM context window with raw HTML dumps.
+
+---
+
+## 1. The Token Conservation Principle
+
+- **Raw HTML DOM Problem:** Dumping a complete HTML webpage into the prompt can consume 50,000 to 150,000 tokens, degrading AI reasoning and triggering context rot.
+- **AOM Subtree Solution:** Extract exclusively the **Accessibility Object Model (AOM)** tree or a 2-hop semantic DOM subtree surrounding the target element, consuming under **500 tokens**.
+
+```mermaid
+flowchart LR
+    Broken["Broken Locator Encountered"] --> Probe["Extract Compact AOM Tree (500 tokens)"]
+    Probe --> Rank["Apply Hierarchy: Role > Label > TestId"]
+    Rank --> Test["Verify Uniqueness on Live DOM"]
+    Test --> Patch["Patch Page Class Method"]
+```
+
+---
+
+## 2. Master Locator Ranking Hierarchy
+
+When searching for a replacement locator, evaluate candidates in this strict priority order:
+
+1. **Tier 1 — ARIA Role & Accessible Name:**
+   - Playwright: `page.getByRole('button', { name: 'Thêm mới' })`
+   - CSS: `[role="button"][aria-label="Thêm mới"]`
+2. **Tier 2 — Form Control & Business Semantics:**
+   - `input[formcontrolname="code"]`
+   - `p-dropdown[formcontrolname="categoryId"]`
+3. **Tier 3 — Dedicated Test Identifiers:**
+   - `[data-testid="btn-create"]`
+   - `[data-test="submit"]`
+4. **Tier 4 — Stable Visual Text:**
+   - `button:has-text("Xác nhận")`
+5. **Tier 5 — Scoped Resilient Relative CSS:**
+   - `.card.popup-data input.p-inputtext`
+
+---
+
+## 3. In-Browser AOM Probing Snippet
+
+Execute this compact JavaScript probe via Playwright or Chrome DevTools to locate the target node without dumping HTML:
+
+```javascript
+// Extract interactive elements tree scoped to active modal or container
+() => {
+  const container = document.querySelector('.p-dialog, .modal-content, form') || document.body;
+  const elements = container.querySelectorAll('button, input, select, textarea, p-dropdown, [role="button"]');
+  return Array.from(elements).map(el => ({
+    tag: el.tagName.toLowerCase(),
+    role: el.getAttribute('role') || el.type,
+    name: el.getAttribute('name') || el.getAttribute('formcontrolname') || el.id,
+    label: el.innerText?.trim() || el.getAttribute('aria-label') || el.placeholder,
+    testId: el.getAttribute('data-testid')
+  }));
+}
+```
+
+---
+
+## 4. Healing Execution Checklist
+
+1. **Verify Uniqueness:** Ensure the candidate locator matches exactly 1 element on the live DOM.
+2. **Encapsulate in Page Class:** Update the locator constant or private selector inside the relevant Page Class (e.g. `BasePage` or domain Page Class).
+3. **Never Leak to Test Scripts:** Test scripts must remain 100% clean of raw selectors.

package/.agents/skills/synthetic-test-data-generator/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: synthetic-test-data-generator
+description: Generate robust, idempotent, and boundary-value synthetic test data (strings, numbers, emails, addresses, enterprise contracts, GIS coordinates) for automated test suites.
+---
+
+# Synthetic Test Data Generator & Edge-Case Fuzzing Skill
+
+> **Target:** Eliminate database collisions, race conditions in parallel testing, and stale fixture dependencies by dynamically generating valid, boundary-value, and edge-case fuzzing datasets.
+
+---
+
+## 1. Core Principles
+
+1. **Idempotence & Unique Prefixing:**
+   - Every generated string or identifier must contain an execution timestamp or UUID prefix (`AUTO_1719500000_...`) to allow parallel test executions without unique-key database collisions.
+2. **Boundary Value Testing (BVT):**
+   - Automatically cover equivalence partitions:
+     - Null / Empty / Whitespace-only strings.
+     - Max length limits (e.g. 255 chars, 1,024 chars, 10,000 chars text blocks).
+     - Special characters, emojis, SQL injection probe strings (`' OR '1'='1' -- `), XSS polyglots (`<img src=x onerror=console.warn('qa_xss')>`).
+     - Negative numbers, extreme floats, zero, boundary integer limits (`2^31 - 1`, `2^63 - 1`, `Number.MAX_SAFE_INTEGER`).
+3. **Domain-Specific Constraints:**
+   - Tax IDs, phone numbers, email RFC formats, and GIS coordinates (e.g., non-overlapping closed polygons).
+
+---
+
+## 2. Standard Generation Recipes
+
+### Recipe A: Dynamic Unique Entity Names
+```typescript
+export class TestDataFactory {
+  static uniqueName(prefix: string = 'AUTO'): string {
+    const timestamp = Date.now().toString(36).toUpperCase();
+    const randomSuffix = Math.random().toString(36).substring(2, 6).toUpperCase();
+    return `${prefix}_${timestamp}_${randomSuffix}`;
+  }
+
+  static validEmail(prefix: string = 'tester'): string {
+    return `${prefix}.${Date.now()}@example-testing.com`;
+  }
+}
+```
+
+### Recipe B: Boundary Value String Suite
+```json
+{
+  "boundaryStrings": [
+    "",
+    "   ",
+    "A",
+    "A".repeat(255),
+    "A".repeat(1024),
+    "Tiếng Việt có dấu: Cà phê sữa đá & Trắc nghiệm chất lượng",
+    "Special chars: !@#$%^&*()_+{}|:\"<>?~`-=[]\\;',./",
+    "Unicode emojis: 🚀🔥⚡🧪✨",
+    "XSS probe: <img src=x onerror=alert('qa')>",
+    "SQLi probe: ' OR '1'='1' -- "
+  ]
+}
+```
+
+### Recipe C: GeoJSON / GIS Valid Non-Overlapping Polygons
+```typescript
+export function generateValidPolygon(centerLat = 21.0285, centerLng = 105.8542, offset = 0.005) {
+  // Generates closed 5-point polygon bounding box
+  return [
+    [centerLng - offset, centerLat - offset],
+    [centerLng + offset, centerLat - offset],
+    [centerLng + offset, centerLat + offset],
+    [centerLng - offset, centerLat + offset],
+    [centerLng - offset, centerLat - offset] // Close ring
+  ];
+}
+```
+
+---
+
+## 3. Edge-Case Fuzzing & Input Sanitization Suite (`tools/fuzz_payloads.py`)
+
+Transform functional tests into input sanitization and robustness validation by executing edge-case fuzzing vectors:
+
+```bash
+# Query CLI catalog for specific field vectors
+python tools/fuzz_payloads.py --field username --type string
+python tools/fuzz_payloads.py --category sqli --json
+```
+
+### Recipe D: Harmless SQLi Polyglot Sanity
+```typescript
+export const SQLI_FUZZ_PROBES = [
+  "' OR '1'='1' -- ",
+  "SLEEP(0)/*'/*\"/*--",
+  "1' UNION SELECT NULL, NULL, NULL -- ",
+  "admin' -- ",
+  "'; WAITFOR DELAY '0:0:0'--"
+];
+// Assertion: Application must return HTTP 400 or sanitize safely; MUST NEVER throw 500 SQLException.
+```
+
+### Recipe E: Unicode BiDi & RTL Trojan Source Vectors
+```typescript
+export const BIDI_FUZZ_PROBES = [
+  "\u202E\u0041\u0042\u0043_AUTO_TX", // Right-to-Left Override (RLO)
+  "AUTO\u200B\u200C\u200D_DATA",       // Zero-Width Space & Joiner
+  "\uFEFFAUTO_USER",                   // In-string Byte Order Mark (BOM)
+  "USER_مرحبا_بالعالم_2026"            // Mixed Latin/Arabic BiDi text
+];
+// Assertion: Database persistence and frontend display must not corrupt visual hierarchy or inject Trojan Source spoofing.
+```
+
+### Recipe F: Multi-Byte Emoji Surrogate Pairs & ZWJ Sequences
+```typescript
+export const EMOJI_FUZZ_PROBES = [
+  "👨‍👩‍👧‍👦_QA_RECORD",      // Complex Zero-Width Joiner family sequence
+  "🏳️‍🌈_FLAG_TAG",          // Multi-code point flag sequence
+  "\uD83D\uDE00\uD83D",     // Unpaired surrogate boundary test
+  "🔥🚀⚡🧪✨"               // 4-byte high-plane UTF-8 characters
+];
+// Assertion: Backend UTF-8 MB4 column encoding must persist without truncation or 1366 Incorrect string value error.
+```
+
+### Recipe G: Extreme Length Buffer Stress ($10^4$ Characters)
+```typescript
+export const BUFFER_STRESS_PAYLOADS = [
+  "A".repeat(10000),         // 10,000 chars text block
+  "X".repeat(1024),          // Standard 1KB boundary
+  '{"test": [' + Array(500).fill('1').join(',') + ']}' // Repetitive JSON nesting
+];
+// Assertion: API must reject with 400/413 Payload Too Large; frontend form controls must enforce max-length clipping.
+```
+
+---
+
+## 4. Teardown & Lifecycle Integration
+- Every test generating persistent records with `synthetic-test-data-generator` **MUST** register the generated ID into a teardown queue to clean up after test execution completes.

package/.agents/skills/token-and-context-optimizer/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: token-and-context-optimizer
+description: Context engineering and token optimization skill for Antigravity, enforcing sparse context retrieval, log distillation, prevention of context degradation (Lost-in-the-Middle, attention sinks), and off-context memory scratchpad protocol.
+---
+
+# Token & Context Optimizer — Antigravity Engineering Standard
+
+> **Purpose:** Master context engineering and token efficiency. Directs AI Agents to prevent context rot, mitigate Lost-in-the-Middle attention drops, offload large state to filesystem scratchpads, and maintain clean KV-cache alignment across long test automation sessions.
+
+---
+
+## 1. The Core Context Architecture
+
+```mermaid
+flowchart TD
+    P1["<b>1. Sparse Context Retrieval</b><br/>• Forbid cat on large files<br/>• Grep / Line-range only"] --> P2["<b>2. Terminal Log Distillation</b><br/>• Strip PASSED steps via tools/distill_log.py<br/>• Forward only FAILED stack trace"]
+    P2 --> P3["<b>3. File-Backed Memory Layer</b><br/>• Persist state to PROJECT_STATE.md<br/>• Zero conversational bloat"]
+    P3 --> P4["<b>4. Context Degradation Prevention</b><br/>• Attention U-Curve placement<br/>• Circuit break on hallucination poisoning"]
+```
+
+---
+
+## 2. Protocol 1: Sparse Context Retrieval
+
+- **Rule:** Never read entire source files exceeding 150 lines into active context.
+- **Enforcement:**
+  - Prohibit commands like `cat`, `type`, or unbounded `read_file` on large Page Classes (e.g. `DataMiningPage.groovy`).
+  - Use regex search (`grep -n`, `ripgrep`) or compressed maps (`tools/repo_map.txt`) to pinpoint signatures.
+  - Read strictly the targeted 20–50 lines using `StartLine` and `EndLine` parameters.
+
+---
+
+## 3. Protocol 2: Terminal Log Distiller (`tools/distill_log.py`)
+
+- **Rule:** Never dump unparsed execution logs (KRE CLI, Playwright stdout, Gradle) into the active conversation.
+- **Enforcement:**
+  - Automatically filter out passing step messages, INFO logs, and JVM loading notices.
+  - Forward strictly the distilled failure block:
+    ```text
+    [FAILED] TC-xxx at Line <LineNumber>
+    Exception: <ExceptionName> (<Message>)
+    [Full raw log saved to file://<path>; verbose lines omitted]
+    ```
+
+---
+
+## 4. Protocol 3: Task Scratchpad & File-Backed Context
+
+- **Rule:** Do not accumulate large session state, test case inventories, or defect logs inside conversational prompt turns.
+- **Enforcement:**
+  - Use the filesystem as the primary overflow memory layer.
+  - Persist ephemeral task tracking and defect registers to disk in structured markdown files (e.g. `PROJECT_STATE.md`, `KNOWN_ISSUES.md`, or `<appDataDir>/brain/<id>/scratch/`).
+  - Prefer dynamic context discovery (pulling context on demand via search tools) over static bulk inclusion.
+
+---
+
+## 5. Protocol 4: Mitigating Context Degradation & Lost-in-the-Middle
+
+- **Attention U-Curve Principle:** Models recall information at the beginning (BOS / System Prompt) and end (latest turn) far better than information buried in the middle of long sessions (> 4,000 tokens).
+- **Enforcement:**
+  - Place critical instructions and current objective anchors at the beginning and end of prompts.
+  - Segment multi-module tasks into discrete sub-agent scopes to prevent cross-task confusion.
+  - **Context Poisoning Circuit Breaker:** If a tool output or test run produces an invalid assumption or hallucination, truncate reasoning immediately and re-anchor against verified disk state rather than compounding false premises.
+
+---
+
+## 6. Protocol 5: KV-Cache Friendly Ordering
+- Maintain immutable static instruction prefixes at the top.
+- Append new dynamic observations strictly at the bottom.
+- Use uniform pre-flight header formats to achieve > 85% inference KV-cache hit rate.

package/.agents/skills/visual-regression-sentinel/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: visual-regression-sentinel
+description: Pixel-level and perceptual visual regression testing with dynamic masking, layout shift detection, and threshold-based visual assertions.
+---
+
+# Visual Regression Sentinel Skill
+
+> **Target:** Catch unintended UI rendering defects, CSS breakages, alignment shifts, and missing visual assets across viewports without manual visual inspection.
+
+---
+
+## 1. Core Principles
+
+1. **Anti-Flakiness Masking:**
+   - Always mask dynamic elements (timers, timestamps, random avatars, ads, blinking carets) before capturing baselines.
+2. **Perceptual Diffing over Strict Pixel Match:**
+   - Use SSIM (Structural Similarity Index) or perceptual threshold (`threshold: 0.2`) to tolerate minor antialiasing discrepancies between GPU rendering pipelines.
+3. **Deterministic Viewports:**
+   - Standardize viewport dimensions (`1920x1080` for Desktop, `390x844` for Mobile) and disable animations (`animations: 'disabled'`).
+
+---
+
+## 2. Standard Playwright Visual Assertion Patterns
+
+### Pattern A: Full-Page Screenshot with Dynamic Masking
+```typescript
+await expect(page).toHaveScreenshot('landing-page.png', {
+  fullPage: true,
+  animations: 'disabled',
+  mask: [
+    page.locator('.dynamic-timestamp'),
+    page.locator('.live-ticker-banner'),
+    page.locator('[data-testid="unique-id-badge"]')
+  ],
+  maxDiffPixelRatio: 0.02 // Allow 2% tolerance
+});
+```
+
+### Pattern B: Component-Level Snapshot
+```typescript
+// Isolate critical component to avoid cascade failures from header/footer changes
+const dataTable = page.locator('.custom-data-table');
+await expect(dataTable).toHaveScreenshot('table-component-default.png', {
+  threshold: 0.1
+});
+```
+
+### Pattern C: Color Mode / Responsive Variations
+```typescript
+// Test Dark Mode
+await page.emulateMedia({ colorScheme: 'dark' });
+await expect(page).toHaveScreenshot('dashboard-dark.png');
+```
+
+---
+
+## 3. Visual Failure Autopsy Protocol
+When visual regression fails:
+1. Review generated diff image: `*-diff.png`.
+2. Determine if it is a **Real Regression** (CSS bug, broken layout) or **Intentional Redesign**.
+3. If intentional redesign: update baseline snapshots via `npx playwright test --update-snapshots`.
+4. If bug: file bug report with side-by-side artifact comparison.

package/.agents/skills/wcag-audit-patterns/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: wcag-audit-patterns
+description: Conduct WCAG 2.2 accessibility audits (Level A/AA) with automated AST analysis, keyboard trap verification, ARIA role assertions, and tools/wcag_audit.py.
+---
+
+# WCAG 2.2 Accessibility Audit Patterns
+
+Engineering standards for automated, continuous Web Content Accessibility Guidelines (WCAG 2.2 Level A and AA) auditing across enterprise web applications.
+
+---
+
+## 1. Core WCAG 2.2 Success Criteria Matrix
+
+| Criterion | Rule Code | Requirement & Automated Assertion |
+| :--- | :--- | :--- |
+| **Non-text Content** | WCAG 1.1.1 | All `<img>` tags must possess non-empty `alt` attributes or `aria-hidden="true"` if decorative. |
+| **Info and Relationships**| WCAG 1.3.1 | Form controls `<input>`, `<select>` must link to `<label>` via `id/for` or `aria-label`. |
+| **Heading Structure** | WCAG 1.3.1 | Headings must not skip levels (e.g. `<h1>` followed immediately by `<h3>`). |
+| **Contrast (Minimum)** | WCAG 1.4.3 | Normal text contrast ratio $\ge 4.5:1$; Large text ($\ge 18\text{pt}$ or bold $14\text{pt}$) $\ge 3:1$. |
+| **Keyboard Navigable** | WCAG 2.1.1 | All interactive elements must be focusable via `Tab` with visible focus indicators. |
+| **No Keyboard Trap** | WCAG 2.1.2 | Focus must not become permanently trapped in modal dialogs; `Esc` key must exit. |
+| **Target Size (Minimum)**| WCAG 2.5.8 | Interactive targets must meet $24 \times 24\text{px}$ minimum clickable area (WCAG 2.2 new). |
+
+---
+
+## 2. Playwright Automated Accessibility Testing Patterns
+
+### Pattern A: Integrating `@axe-core/playwright` for Comprehensive Audits
+```typescript
+import { test, expect } from '@playwright/test';
+import AxeBuilder from '@axe-core/playwright';
+
+test('verify WCAG 2.2 Level AA compliance on dashboard', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.waitForLoadState('networkidle');
+
+  const accessibilityScanResults = await new AxeBuilder({ page })
+    .withTags(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa'])
+    .exclude('.legacy-third-party-widget') // Explicitly scoped exclusion
+    .analyze();
+
+  expect(accessibilityScanResults.violations).toEqual([]);
+});
+```
+
+### Pattern B: Modal Keyboard Focus Trap and Escape Verification
+```typescript
+test('modal dialog traps keyboard focus and closes on Escape', async ({ page }) => {
+  await page.goto('/settings');
+  await page.getByRole('button', { name: 'Edit Profile' }).click();
+
+  const modal = page.getByRole('dialog', { name: 'Edit Profile' });
+  await expect(modal).toBeVisible();
+
+  // Verify focus shifts into modal
+  await expect(modal.getByRole('textbox', { name: 'Username' })).toBeFocused();
+
+  // Press Escape and verify focus returns to trigger
+  await page.keyboard.press('Escape');
+  await expect(modal).toBeHidden();
+  await expect(page.getByRole('button', { name: 'Edit Profile' })).toBeFocused();
+});
+```
+
+---
+
+## 3. Automated CLI Auditing via Tooling
+
+Agent can automatically audit accessibility for any HTML file or live page URL via `tools/wcag_audit.py`:
+
+```bash
+# Audit a local HTML snapshot
+python tools/wcag_audit.py path/to/page.html -o docs/wcag_audit_report.md
+
+# Audit a live application URL directly
+python tools/wcag_audit.py https://staging.example.com --url -o docs/wcag_audit_report.md
+```