synapse-hub 0.0.0-stage → 2.0.0

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

@@ -0,0 +1,99 @@
+---
+trigger: always_on
+description: Enforce rigorous engineering discipline, systematic debugging without guesswork, and verification before completion.
+---
+
+# Systematic Debugging & Verification Discipline (Superpowers Standard)
+
+*(Inherited from `obra/superpowers`)*
+
+This rule governs all AI Agents operating on the repository. It mandates strict engineering rigor, prohibiting intuitive guesswork and unverified declarations of completion.
+
+---
+
+## 1. Iron Discipline: Zero Guesswork Debugging
+
+1. **Evidence Before Action:**
+   - Never modify code based on a hunch or assumption.
+   - Every bug fix or locator update must be preceded by concrete ground-truth evidence:
+     - Log excerpt showing the exact failing line and exception.
+     - Visual inspection of `Screenshots/FAILED_*.png`.
+     - Live DOM element state verified via Playwright Live Interaction.
+2. **Preserve Working Code:**
+   - When fixing an issue in a Page Class or script, touch only the minimal lines required. Never rewrite working methods speculatively.
+
+---
+
+## 2. Verification-First & Zero False Completion
+
+1. **Never Declare Complete Without Running Verification:**
+   - Any agent claiming a fix or refactoring is finished MUST run:
+     ```bash
+     python3 tools/verify_all.py
+     ```
+   - All 8 Gates must return `PASS`. If any gate fails, the task is NOT complete.
+2. **Targeted Re-Test:**
+   - After modifying Page Classes, check impacted Test Cases with:
+     ```bash
+     python3 tools/test_impact.py --git-diff
+     ```
+   - Verify the affected test cases pass before handoff.
+3. **Synchronize Knowledge Graph & Repo Map:**
+   - Run `graphify update .` to keep the AST knowledge graph updated.
+   - Run `python3 tools/repo_map.py` if any Page Class or Helper was modified.
+
+---
+
+## 3. Situational Tool Dispatch Matrix & Zero-Command Autonomy
+
+> 🚀 **Zero-Command Autonomous Invariant (Zero Manual Commands):**  
+> The user **NEVER** needs to remember syntax or manually type tool commands (`agent-qa setup`, `agent-qa analyze`, `verify_all.py`...).  
+> The AI Agent **MUST AUTONOMOUSLY recognize context and trigger** the corresponding tools below on-demand whenever the situation arises.  
+>  
+> 🎯 **On-Demand Activation Principle (Situation-Specific — Never Run Blindly):**  
+> Tools assigned to AI and Subagents are **situational weapons**, **NEVER executed all at once**. Agents draw the specific tool from the arsenal if and only if a concrete need arises (e.g.: failing test triggers `auto_heal`, new project triggers `setup_project`, API breaking change triggers `api_drift_sentinel`).
+
+| Context / Trigger | Mandatory Tool | Specific Objective |
+| :--- | :--- | :--- |
+| **New project / Missing `PROJECT_AI_GUIDE.md` / Fresh clone** | `python3 tools/setup_project.py [target]` | 100% Autonomous: Detects framework (Playwright/Katalon/Pytest), generates `PROJECT_AI_GUIDE.md`, installs `pre-push` hook, extracts `repo_map.txt`, runs initial audit. |
+| **User requests: "analyze project" / "re-analyze" / "project audit"** | `python3 tools/analyze_project.py [target]` | Execute comprehensive 5-in-1 health audit, sync repo_map, infer_linter, data_flow, verify_all & generate PROJECT_HEALTH_REPORT.md.<br/>**Post-Action:** Stage, commit & push updated project files (`PROJECT_HEALTH_REPORT.md`, `repo_map.txt`) to git. |
+| **Starting task / Querying Page Class methods** | `tools/repo_map.txt`<br/>*(run `python3 tools/repo_map.py` if classes changed)* | Read compressed 500-token map for signatures; avoid reading 4,000-line files. |
+| **Dispatching Browser Actions (Live/CDP)** | `python3 tools/safety_firewall.py --dry-run` | Mandatory Pre-execution Hook: Block irreversible/destructive operations before browser dispatch. |
+| **Creating or updating Test Scripts** | `python3 tools/infer_linter.py` | Run AST scan for Fake-Pass (0 asserts) and empty catch blocks. |
+| **New/Modified Test Case Quality** | `python3 tools/micro_mutator.py --min-score 80` | AST Mutation Testing: Reject test suites with mutation score < 80%. |
+| **Before Git Commit or Completing Task** | `python3 tools/verify_all.py` | Validate all 8 Quality Gates DoD. |
+| **After modifying Page Classes** | `python3 tools/test_impact.py --git-diff` | Scope impacted test cases; avoid re-running entire test suites. |
+| **When Test FAILS in CLI/KRE** | `python3 tools/pinpoint_failure.py` | Parse JUnit XML to identify exact failing line and exception in 0.1s. |
+| **When CLI / Gradle logs are verbose** | `python3 tools/distill_log.py <log>` | Filter 95% noise; preserve only actionable stacktraces and pointers. |
+| **Handling UI exceptions (Overlay, Stale)** | `python3 tools/cache_resolver.py query "<error>"` | Lookup 0-token solution from local SQLite memory cache before improvising. |
+| **Pre-Push / Suite Acceptance** | `python3 tools/trace_data_flow.py` | Run Taint Analysis to verify no orphan database junk remains uncleaned. |
+| **Canary Self-Healing Audit** | `python3 tools/agent_canary.py --run` | Inject 8 failure vectors to benchmark MTTR and autonomous recovery rate. |
+| **Testing GIS Canvas / Chart without DOM** | `python3 tools/visual_diff_canvas.py` | Compare pixel / SSIM to detect visual rendering regression. |
+| **Pulling code / New clone** | `python3 tools/cache_resolver.py init` | Automatically sync Central Agent Memory (`~/.agent_memory/global_cache.db`). |
+| **Before authoring test for Page/Flow** | `python3 tools/cache_resolver.py get-lessons --context "<page>"` | Query top 2 episodic lessons learned to avoid repeating past failure patterns. |
+| **After healing a bug / failure** | `python3 tools/cache_resolver.py record-lesson` | Record a concise 2-line lesson into SQLite memory for cross-session reflexion. |
+
+---
+
+## 4. Cognitive Forcing Functions (Structured Reasoning Pipeline)
+
+> **Core Principle:** Autocomplete mode generates weak, tautological tests. Before outputting any test script, Universal IR, or Page Class, the agent **MUST** pass through a 4-step System-2 reasoning pipeline:
+
+```markdown
+<reasoning_protocol>
+Step 1 - Boundary & Invariant Extraction: Xác định các bất biến (invariants) của hệ thống. Cái gì bắt buộc không bao giờ được phép xảy ra?
+Step 2 - Falsification Hypotheses (Phản đề Popper): Đưa ra 3 kịch bản lập trình viên có thể làm hàm chạy sai mà test thông thường vẫn pass (False Negatives).
+Step 3 - Self-Debate: Tự giải thích tại sao assertion chuẩn bị viết sẽ bắt chết cả 3 kịch bản phá hoại ở Step 2.
+Step 4 - Emit Code / Universal IR: Chỉ sinh code khi đã hoàn thành 3 bước trên.
+</reasoning_protocol>
+```
+
+---
+
+## 5. Adversarial Self-Play: Red-Team vs Blue-Team
+
+- **Agent Blue (`pom-crafter`):** Synthesizes Clean POM code and defensive assertions.
+- **Agent Red (`failure-analyst`):** Acts as the rogue developer, actively injecting AST mutants via `tools/micro_mutator.py` into source/mocks.
+- **Evaluation Loop:**
+  - If Blue's tests let mutants survive (Mutation Score $< 80\%$), Red-Team **REJECTS** the code and commands Blue to strengthen assertions.
+  - Test suites are only Approved when Mutation Score reaches $\ge 80\%$.

package/.agents/skills/agent-orchestration-multi-agent-optimize/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: agent-orchestration-multi-agent-optimize
+description: "Optimize multi-agent systems with coordinated profiling, workload distribution, and cost-aware orchestration. Use when improving agent performance, throughput, or reliability."
+---
+
+# Multi-Agent Optimization Toolkit
+
+## Use this skill when
+
+- Improving multi-agent coordination, throughput, or latency
+- Profiling agent workflows to identify bottlenecks
+- Designing orchestration strategies for complex workflows
+- Optimizing cost, context usage, or tool efficiency
+
+## Do not use this skill when
+
+- You only need to tune a single agent prompt
+- There are no measurable metrics or evaluation data
+- The task is unrelated to multi-agent orchestration
+
+## Instructions
+
+1. Establish baseline metrics and target performance goals.
+2. Profile agent workloads and identify coordination bottlenecks.
+3. Apply orchestration changes and cost controls incrementally.
+4. Validate improvements with repeatable tests and rollbacks.
+
+## Safety
+
+- Avoid deploying orchestration changes without regression testing.
+- Roll out changes gradually to prevent system-wide regressions.
+
+## Role: AI-Powered Multi-Agent Performance Engineering Specialist
+
+### Context
+
+The Multi-Agent Optimization Tool is an advanced AI-driven framework designed to holistically improve system performance through intelligent, coordinated agent-based optimization. Leveraging cutting-edge AI orchestration techniques, this tool provides a comprehensive approach to performance engineering across multiple domains.
+
+### Core Capabilities
+
+- Intelligent multi-agent coordination
+- Performance profiling and bottleneck identification
+- Adaptive optimization strategies
+- Cross-domain performance optimization
+- Cost and efficiency tracking
+
+## Arguments Handling
+
+The tool processes optimization arguments with flexible input parameters:
+
+- `$TARGET`: Primary system/application to optimize
+- `$PERFORMANCE_GOALS`: Specific performance metrics and objectives
+- `$OPTIMIZATION_SCOPE`: Depth of optimization (quick-win, comprehensive)
+- `$BUDGET_CONSTRAINTS`: Cost and resource limitations
+- `$QUALITY_METRICS`: Performance quality thresholds
+
+## 1. Multi-Agent Performance Profiling
+
+### Profiling Strategy
+
+- Distributed performance monitoring across system layers
+- Real-time metrics collection and analysis
+- Continuous performance signature tracking
+
+#### Profiling Agents
+
+1. **Database Performance Agent**
+   - Query execution time analysis
+   - Index utilization tracking
+   - Resource consumption monitoring
+
+2. **Application Performance Agent**
+   - CPU and memory profiling
+   - Algorithmic complexity assessment
+   - Concurrency and async operation analysis
+
+3. **Frontend Performance Agent**
+   - Rendering performance metrics
+   - Network request optimization
+   - Core Web Vitals monitoring
+
+### Profiling Code Example
+
+```python
+def multi_agent_profiler(target_system):
+    agents = [
+        DatabasePerformanceAgent(target_system),
+        ApplicationPerformanceAgent(target_system),
+        FrontendPerformanceAgent(target_system)
+    ]
+
+    performance_profile = {}
+    for agent in agents:
+        performance_profile[agent.__class__.__name__] = agent.profile()
+
+    return aggregate_performance_metrics(performance_profile)
+```
+
+## 2. Context Window Optimization
+
+### Optimization Techniques
+
+- Intelligent context compression
+- Semantic relevance filtering
+- Dynamic context window resizing
+- Token budget management
+
+### Context Compression Algorithm
+
+```python
+def compress_context(context, max_tokens=4000):
+    # Semantic compression using embedding-based truncation
+    compressed_context = semantic_truncate(
+        context,
+        max_tokens=max_tokens,
+        importance_threshold=0.7
+    )
+    return compressed_context
+```
+
+## 3. Agent Coordination Efficiency
+
+### Coordination Principles
+
+- Parallel execution design
+- Minimal inter-agent communication overhead
+- Dynamic workload distribution
+- Fault-tolerant agent interactions
+
+### Orchestration Framework
+
+```python
+class MultiAgentOrchestrator:
+    def __init__(self, agents):
+        self.agents = agents
+        self.execution_queue = PriorityQueue()
+        self.performance_tracker = PerformanceTracker()
+
+    def optimize(self, target_system):
+        # Parallel agent execution with coordinated optimization
+        with concurrent.futures.ThreadPoolExecutor() as executor:
+            futures = {
+                executor.submit(agent.optimize, target_system): agent
+                for agent in self.agents
+            }
+
+            for future in concurrent.futures.as_completed(futures):
+                agent = futures[future]
+                result = future.result()
+                self.performance_tracker.log(agent, result)
+```
+
+## 4. Parallel Execution Optimization
+
+### Key Strategies
+
+- Asynchronous agent processing
+- Workload partitioning
+- Dynamic resource allocation
+- Minimal blocking operations
+
+## 5. Cost Optimization Strategies
+
+### LLM Cost Management
+
+- Token usage tracking
+- Adaptive model selection
+- Caching and result reuse
+- Efficient prompt engineering
+
+### Cost Tracking Example
+
+```python
+class CostOptimizer:
+    def __init__(self):
+        self.token_budget = 100000  # Monthly budget
+        self.token_usage = 0
+        self.model_costs = {  # USD per 1K input tokens
+            'gpt-5': 0.03,
+            'claude-sonnet-4-6': 0.003,
+            'claude-haiku-4-5': 0.001
+        }
+
+    def select_optimal_model(self, complexity):
+        # Dynamic model selection based on task complexity and budget
+        pass
+```
+
+## 6. Latency Reduction Techniques
+
+### Performance Acceleration
+
+- Predictive caching
+- Pre-warming agent contexts
+- Intelligent result memoization
+- Reduced round-trip communication
+
+## 7. Quality vs Speed Tradeoffs
+
+### Optimization Spectrum
+
+- Performance thresholds
+- Acceptable degradation margins
+- Quality-aware optimization
+- Intelligent compromise selection
+
+## 8. Monitoring and Continuous Improvement
+
+### Observability Framework
+
+- Real-time performance dashboards
+- Automated optimization feedback loops
+- Machine learning-driven improvement
+- Adaptive optimization strategies
+
+## Reference Workflows
+
+### Workflow 1: E-Commerce Platform Optimization
+
+1. Initial performance profiling
+2. Agent-based optimization
+3. Cost and performance tracking
+4. Continuous improvement cycle
+
+### Workflow 2: Enterprise API Performance Enhancement
+
+1. Comprehensive system analysis
+2. Multi-layered agent optimization
+3. Iterative performance refinement
+4. Cost-efficient scaling strategy
+
+## Key Considerations
+
+- Always measure before and after optimization
+- Maintain system stability during optimization
+- Balance performance gains with resource consumption
+- Implement gradual, reversible changes
+
+Target Optimization: $ARGUMENTS

package/.agents/skills/antigravity-test-sentinel/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: antigravity-test-sentinel
+description: >-
+  Verification-first sentinel for test automation in Antigravity. Strictly locks task completion until test runner commands (verify_all.py, KRE CLI, Playwright) return exit code 0. Forbids declaring completion on unverified code.
+---
+
+# Antigravity Test Sentinel — Verification-First Gatekeeper
+
+The **Antigravity Test Sentinel** enforces absolute engineering integrity across test creation, script refactoring, and bug fixes. It acts as an autonomous circuit breaker that physically prohibits the AI Agent from concluding a task without verifiable proof of test execution success.
+
+---
+
+## 1. The Sentinel Axiom (Zero-Hallucination Gate)
+
+1. **The Core Rule:**
+   - Writing code is NOT completing the task.
+   - Editing a locator is NOT fixing a failure.
+   - **A task is ONLY complete when the test execution returns Exit Code 0.**
+
+2. **Prohibited Agent Behaviors:**
+   - 🚫 Saying *"I have fixed the issue"* without executing verification.
+   - 🚫 Assuming a locator or script will work based on static text analysis.
+   - 🚫 Ignoring non-zero exit codes from CLI runners or Gradle builds.
+
+---
+
+## 2. Gate-Lock Protocol
+
+Whenever an Agent modifies any test script, Page Class, locator, or helper method:
+
+```mermaid
+flowchart TD
+    Edit["1. Code Edit / Bug Fix Applied"] --> Run["2. Execute Test Runner Command"]
+    Run --> Check{"3. Check Process Exit Code"}
+    Check -- "Exit Code == 0" --> DoD["4. Run verify_all.py (6 Gates)"]
+    DoD -- "All Gates PASS" --> Complete["5. Declare Task Complete ✅"]
+    Check -- "Exit Code != 0" --> Extract["4a. Extract Stack Trace & Failing Line"]
+    Extract --> Heal["4b. In-Place Healing Loop"]
+    Heal --> Run
+```
+
+1. **Step 1: Execute Runner Command:**
+   - Run the targeted test case or test suite via headless CLI runner or verification gate:
+     ```bash
+     python3 tools/verify_all.py
+     ```
+2. **Step 2: Inspect Exit Code:**
+   - If the process terminates with exit code != 0, the task is **LOCKED**.
+   - The Agent must not ask the user for confirmation or declare success.
+3. **Step 3: Self-Diagnosis & Auto-Healing:**
+   - The Agent must parse the exact error exception and stack trace from the failure output.
+   - Apply targeted in-place healing and re-execute.
+4. **Step 4: Definition of Done Verification:**
+   - Run `python3 tools/verify_all.py` to confirm all 6 quality gates pass.
+
+---
+
+## 3. Sentinel Status Header
+
+In accordance with Antigravity operating discipline, include the sentinel verification status in the session summary:
+
+```text
+> 🛡️ SENTINEL STATUS: VERIFIED (Exit Code: 0 | 6/6 Gates PASS)
+```

package/.agents/skills/api-network-mocking-interception/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: api-network-mocking-interception
+description: Runtime HTTP/GraphQL request interception, route stubbing (page.route), and chaos network resilience testing (latency, 502/503/504 faults, offline, circuit breaker) during UI execution.
+---
+
+# API Network Mocking, Interception & Resilience Skill
+
+> **Target:** Eliminate flaky tests caused by backend dependencies, slow microservices, or inconsistent staging data by intercepting browser-level network requests, and verify frontend resilience against network faults and degradations.
+
+---
+
+## 1. Core Principles
+
+1. **Deterministic State over Staging Data:**
+   - UI tests should verify front-end state rendering and user interactions, not whether the backend DB is seeded.
+   - Use route interception (`page.route()`) to return predictable JSON contracts (success, 400 Bad Request, 500 Server Error).
+
+2. **Zero Network Latency:**
+   - Mock external telemetry, 3rd party analytics, fonts, and heavy media assets to speed up execution by 3x-5x.
+
+3. **Fault Injection & Chaos Verification:**
+   - Test UI resiliency against network timeouts, dropped connections, upstream gateway outages (502/503/504), and malformed schemas without altering real server code.
+   - Guard against White Screen of Death (WSOD) when sudden network loss or circuit-breaking events occur.
+
+---
+
+## 2. Playwright Route Interception Standard Patterns
+
+### Pattern A: Static JSON Response Stubbing
+```typescript
+// Stub user profile API
+await page.route('**/api/v1/user/profile', async (route) => {
+  await route.fulfill({
+    status: 200,
+    contentType: 'application/json',
+    body: JSON.stringify({
+      id: 'USR_AUTO_99',
+      username: 'qa_sentinel',
+      roles: ['ADMIN_OPERATOR'],
+      permissions: ['READ', 'WRITE', 'EXECUTE']
+    })
+  });
+});
+```
+
+### Pattern B: Modifying Live Responses (HAR / Passthrough Mutation)
+```typescript
+// Intercept real response and inject edge-case field
+await page.route('**/api/v1/reports', async (route) => {
+  const response = await route.fetch();
+  const json = await response.json();
+  json.totalItems = 999999; // Test UI overflow / pagination edge case
+  await route.fulfill({ response, json });
+});
+```
+
+### Pattern C: Simulating Network Failures & Delays
+```typescript
+// Simulate 500 Internal Server Error
+await page.route('**/api/v1/checkout', async (route) => {
+  await route.fulfill({
+    status: 500,
+    contentType: 'application/json',
+    body: JSON.stringify({ errorCode: 'ERR_PAYMENT_DOWN', message: 'Gateway unreachable' })
+  });
+});
+
+// Simulate High Latency (Slow 3G)
+await page.route('**/api/v1/heavy-list', async (route) => {
+  await new Promise(res => setTimeout(res, 3000));
+  await route.continue();
+});
+```
+
+---
+
+## 3. Chaos & Network Degradation Patterns
+
+### Pattern D: Emulating Extreme Latency & Jitter via CDP
+```typescript
+const client = await page.context().newCDPSession(page);
+await client.send('Network.emulateNetworkConditions', {
+  offline: false,
+  latency: 3500, // 3.5s roundtrip latency
+  downloadThroughput: ((500 * 1024) / 8), // 500 kbps
+  uploadThroughput: ((500 * 1024) / 8),
+  connectionType: 'cellular3g',
+});
+
+await page.goto('/orders');
+// Verify UI displays loading skeleton/spinner and submit button is disabled in-flight
+const submitBtn = page.locator('button[type="submit"]');
+if (await submitBtn.isVisible()) {
+  await expect(submitBtn).toBeDisabled();
+}
+```
+
+### Pattern E: Simulating Gateway Drops (502/503/504) & Circuit Breaker Recovery
+```typescript
+let attemptCount = 0;
+await page.route('**/api/v1/orders/submit', async (route) => {
+  attemptCount++;
+  if (attemptCount <= 2) {
+    await route.fulfill({
+      status: 503,
+      contentType: 'application/json',
+      body: JSON.stringify({ message: 'Upstream gateway overloaded' }),
+    });
+  } else {
+    await route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({ success: true, orderId: 'ORD_HEALED_99' }),
+    });
+  }
+});
+```
+
+### Pattern F: Sudden Offline Disconnection & Reconnection
+```typescript
+// 1. Cut network abruptly
+await context.setOffline(true);
+await page.click('[data-testid="nav-reports"]').catch(() => {});
+
+// 2. Assert Zero White Screen of Death (WSOD) & Offline alert
+const bodyContent = await page.evaluate(() => document.body.innerText.trim());
+expect(bodyContent.length, 'Page must not be blank').toBeGreaterThan(20);
+
+// 3. Restore connectivity
+await context.setOffline(false);
+await page.reload();
+await expect(page.locator('h1')).toBeVisible();
+```
+
+---
+
+## 4. Best Practices Checklist
+- [ ] Always declare routes **before** calling `page.goto()`.
+- [ ] Use regex or glob patterns with caution; avoid intercepting Vite/Webpack bundling scripts.
+- [ ] Critical forms must disable submit buttons during in-flight network transit to prevent duplicate requests.
+- [ ] HTTP 502/503/504 errors must trigger user-friendly notifications, never raw JSON dumps or blank screens.
+- [ ] For teardown, unroute specific patterns or reset context per test.

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

@@ -0,0 +1,70 @@
+---
+name: api-spec-to-e2e-matrix
+description: >-
+  Transforms OpenAPI/Swagger specifications and JSON schemas into automated E2E positive, boundary value, and negative test matrices.
+---
+
+# API Spec to E2E Matrix — Contract-Based Test Generator
+
+This skill converts OpenAPI / Swagger specifications, JSON Schemas, or REST endpoint contracts into a structured, executable End-to-End (E2E) testing matrix covering happy path, boundary values, and negative error scenarios.
+
+---
+
+## 1. Test Generation Matrix Taxonomy
+
+```mermaid
+flowchart TD
+    Spec["OpenAPI / Swagger / JSON Schema"] --> Parse["Extract Endpoint Contracts"]
+    Parse --> Pos["1. Positive Happy Path<br/>• Valid payload<br/>• HTTP 200/201<br/>• Response schema match"]
+    Parse --> Bound["2. Boundary Value Analysis<br/>• Min/Max string length<br/>• Zero, negative numbers<br/>• Unicode & special chars"]
+    Parse --> Neg["3. Negative & Fault Scenarios<br/>• Missing required fields (400)<br/>• Invalid auth token (401/403)<br/>• Malformed payload (422)"]
+
+    Pos & Bound & Neg --> Suite["Executable Test Suite"]
+```
+
+---
+
+## 2. Boundary Value Generation Rules
+
+For every field defined in the endpoint schema, generate targeted edge cases:
+
+| Field Data Type | Schema Constraint | Generated Boundary Test Inputs |
+| :--- | :--- | :--- |
+| **String (Code / ID)** | `minLength: 3, maxLength: 20` | Empty string `""`, 2 chars, exactly 3 chars, 20 chars, 21 chars, special chars `<script>`, SQL `' OR 1=1--` |
+| **Number / Integer** | `minimum: 0, maximum: 1000` | `-1`, `0`, `1`, `999`, `1000`, `1001`, floating point `10.5` |
+| **Date / Timestamp** | `format: date-time` | Past date, today, future date, leap year `2024-02-29`, invalid format `31/12/2026` |
+| **Enum** | `["ACTIVE", "INACTIVE"]` | Exactly `"ACTIVE"`, lowercase `"active"`, null, undefined, unknown enum `"DELETED"` |
+| **Required Properties** | `required: ["code", "name"]` | Omit `code`, omit `name`, send `null` values |
+
+---
+
+## 3. Negative Scenario Validation Checklist
+
+Every negative test case must assert two distinct layers:
+1. **API Layer Assertion:**
+   - Verify HTTP Status Code is appropriately 400, 401, 403, 404, or 422.
+   - Verify error payload contains expected error codes and localization messages.
+2. **UI / Toast Notification Layer Assertion:**
+   - Verify that the web UI displays the appropriate red toast notification (e.g. *"Dữ liệu không hợp lệ"* or *"Mã đã tồn tại"*).
+   - Verify that the form remains open and input fields preserve user state without losing entered data.
+
+---
+
+## 4. Automation Output Standards
+
+- Generated test cases must adhere to the project's **Clean POM** structure.
+- All requests should utilize dynamic test data with unique timestamp prefixes to ensure idempotency.
+
+---
+
+## 5. Automated Execution via Tooling
+
+Agent can automatically invoke 	ools/generate_api_matrix.py to produce matrices from Swagger files:
+
+``bash
+# Generate Markdown matrix
+python tools/generate_api_matrix.py --spec path/to/openapi.json --format md -o docs/api_matrix.md
+
+# Generate JSON matrix for programmatic ingestion
+python tools/generate_api_matrix.py --spec path/to/openapi.json --format json -o tools/api_matrix.json
+``