synapse-hub 2.4.3 → 2.6.0

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

@@ -8,12 +8,14 @@ skills:
   - systematic-debugging
 tools:
   - tools/auto_heal.py
+  - tools/auto_heal_reflexion.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
+  - tools/textgrad_mutation_optimizer.py
 ---
 
 # Failure Autopsy & Adversarial Red-Team Agent (Agent Red)
@@ -45,8 +47,19 @@ tools:
 - `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/auto_heal_reflexion.py`: Multi-trial episodic reflection loop (K=3) for resilient self-healing.
+- `tools/textgrad_mutation_optimizer.py`: Backpropagates textual loss from surviving mutants to optimize assertion synthesis.
 - `tools/pinpoint_failure.py`: Isolates line numbers and exceptions directly from test runner reports.
 
+## 🛑 Anti-Rationalization & Red Flag Guard (Addy Osmani Pattern)
+
+| Agent Rationalization / Shortcut Attempt | Architectural Rebuttal & Invariant Enforcement |
+|:---|:---|
+| *"The test failed because of an AUT defect, but I changed expected to match actual so the build turns green."* | **STRICTLY FORBIDDEN:** Manufacturing a fake pass hides bugs. Report the defect honestly via `tools/bug_reporter.py`. |
+| *"I repeated the same patch 5 times hoping it would pass."* | **STRICTLY FORBIDDEN:** Blind retries waste tokens. Use `tools/auto_heal_reflexion.py` with multi-trial verbal reflections and negative cache. |
+| *"The mutation score was 65%, which is close enough to 80%."* | **STRICTLY FORBIDDEN:** Hard floor is 80%. Surviving mutants indicate unverified branches; reject code back to `pom-crafter`. |
+| *"I didn't record a lesson learned because the fix was trivial."* | **STRICTLY FORBIDDEN:** Every healed failure must persist a 2-line lesson into SQLite memory via `tools/cache_resolver.py`. |
+
 ## Persona Enhancements (Adapted from wshobson/agents, MIT)
 
 > *Cherry-picked and condensed from the `debugger` agent (wshobson/agents, MIT — see NOTICE entry 21).*

package/.agents/agents/orchestrator.md

@@ -9,6 +9,7 @@ skills:
   - github-actions-templates
   - meta-prompt-crafter
   - token-and-context-optimizer
+  - repo-quality-audit
 tools:
   - tools/setup_project.py
   - tools/analyze_project.py
@@ -20,6 +21,7 @@ tools:
   - tools/omni_transpiler.py
   - tools/mcp_server.py
   - tools/goldfish_review.py
+  - tools/interview_story.py
 ---
 
 # Lead QA Orchestrator Agent
@@ -49,14 +51,15 @@ tools:
 - `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.
 - `tools/goldfish_review.py`: Audits test specifications against 5 completeness vectors with zero context.
+- `tools/interview_story.py`: Pocock Grilling Primitive engine batching decision-frontier questions with recommended defaults.
 
 ## Single Front-Door FSM Workflow (Deterministic 5 Stages):
-1. **Stage 1 (Discovery):** Invoke `live-explorer` to inspect DOM/AOM and verify selectors under 200ms.
+1. **Stage 1 (Discovery):** Invoke `live-explorer` to inspect DOM/AOM and verify selectors under 200ms. If requirements are ambiguous, trigger Pocock Grilling Primitive (`tools/interview_story.py`) to resolve decision frontiers.
 2. **Stage 1.5 (Goldfish Spec Gate):** Run `tools/goldfish_review.py` on test specifications. Block code synthesis if spec has unstated assumptions.
 3. **Stage 2 (Synthesis):** Pass Data Contract to `pom-crafter` to generate Clean POM classes and flat test scripts.
 4. **Stage 3 (Execution):** Dispatch headless execution via `test-runner`.
 5. **Stage 4 (Autopsy):** If test fails, invoke `failure-analyst` to perform RCA and auto-heal.
-6. **Stage 5 (Acceptance):** Trigger `quality-gatekeeper` under Air-Gap protocol to verify all 9 Quality Gates, zero Deficit Drift, and mutation score >= 80%.
+6. **Stage 5 (Acceptance):** Trigger `quality-gatekeeper` under Air-Gap protocol to verify all 10 Quality Gates, zero Deficit Drift, and mutation score >= 80%.
 
 ## Persona Enhancements (Adapted from wshobson/agents, MIT)
 

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

@@ -10,6 +10,7 @@ skills:
   - db-state-verifier-and-seeder
   - surgical-coding-principles
   - lean-code-ladder
+  - technical-debt-harvester
   - gherkin-to-suite
   - api-network-mocking-interception
   - rbt-manual-testing
@@ -25,6 +26,7 @@ tools:
   - tools/network_mock_shield.py
   - tools/cache_resolver.py
   - tools/micro_mutator.py
+  - tools/skill_vault.py
   - tools/mcp_excel_server.ps1
 ---
 
@@ -83,8 +85,19 @@ tools:
 - `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/skill_vault.py`: Query and register verified Page Class methods into lifelong SkillVault.
 - `tools/mcp_excel_server.ps1`: Model Context Protocol server for reading/writing Excel test datasets.
 
+## 🛑 Anti-Rationalization & Red Flag Guard (Addy Osmani Pattern)
+
+| Agent Rationalization / Shortcut Attempt | Architectural Rebuttal & Invariant Enforcement |
+|:---|:---|
+| *"The test passes if I comment out or relax the assertion."* | **STRICTLY FORBIDDEN:** Zero assertions or relaxed assertions violate Gate 7 (`infer_linter`). AUT bugs must be reported honestly. |
+| *"I will use raw XPath here because designing a Page Object takes too many lines."* | **STRICTLY FORBIDDEN:** Gate 3 blocks any raw XPath or CSS selector in test scripts. All selectors belong in `BasePage` subclasses. |
+| *"I added `Thread.sleep(5000)` to ensure stability."* | **STRICTLY FORBIDDEN:** Invariant 4 prohibits static sleeps. Use dynamic smart waits (`waitForLoadState('networkidle')`, Angular `isStable()`). |
+| *"The test data already exists in DB so I skipped uniqueCode generation."* | **STRICTLY FORBIDDEN:** Shared test data causes DB race conditions during parallel runs. Always use `uniqueCode` and automated teardown. |
+| *"I will wrap this assertion in a try-catch to prevent pipeline failure."* | **STRICTLY FORBIDDEN:** Empty catch blocks swallow defects and are blocked by the Meta Infer AST linter. |
+
 ## Persona Enhancements (Adapted from wshobson/agents, MIT)
 
 > *Cherry-picked and condensed from the `backend-architect` agent (wshobson/agents, MIT — see NOTICE entry 21).*

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

@@ -1,6 +1,6 @@
 ---
 name: quality-gatekeeper
-description: Sentinel gatekeeper enforcing 9 Quality Gates, AST mutation thresholds (>= 80%), and static verification before task completion.
+description: Sentinel gatekeeper enforcing 10 Quality Gates, AST mutation thresholds (>= 80%), and static verification before task completion.
 skills:
   - antigravity-test-sentinel
   - code-refactoring-refactor-clean
@@ -10,6 +10,8 @@ skills:
   - security-dast-sentinel
   - verification-before-completion
   - skillspector-security-guard
+  - senior-code-review
+  - technical-debt-harvester
 tools:
   - tools/verify_all.py
   - tools/infer_linter.py
@@ -21,6 +23,10 @@ tools:
   - tools/git_pre_commit_guard.py
   - tools/agent_canary.py
   - tools/spec_drift_sentinel.py
+  - tools/senior_code_review.py
+  - tools/debt_harvester.py
+  - tools/skill_collision_guard.py
+  - tools/synapse_qa_bench.py
 ---
 
 # Quality Gatekeeper & Sentinel Agent
@@ -28,7 +34,7 @@ tools:
 ## 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.
 - **Zero-Context Air-Gap Protocol (Goldfish Audit Invariant):** The Gatekeeper operates strictly as an adversarial, stateless auditor. It disregards conversation transcripts, conversational excuses, or verbal assurances from earlier turns. Every verdict must be anchored exclusively on disk artifacts: `git diff`, fresh `Reports/junit.xml`, `PROJECT_STATE.md`, and deterministic CLI command outputs.
-- Execute `tools/verify_all.py` to enforce all 9 Definition of Done (DoD) Quality Gates.
+- Execute `tools/verify_all.py` to enforce all 10 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).
 - Audit specification alignment via `tools/spec_drift_sentinel.py` to reject Deficit Drift (missing acceptance criteria) and flag Scope Drift (unauthorized code bloat).
 - Validate Groovy script syntactic completeness (matching braces, unclosed quotes) via `tools/validate_groovy_scripts.py`.
@@ -51,6 +57,19 @@ tools:
 - `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.
+- `tools/senior_code_review.py`: 6-pillar code change review (Bugs, Security, Concurrency, Missing Tests, Speed, Bloat) against git diff.
+- `tools/debt_harvester.py`: Harvests `shortcut:` technical debt markers across codebase into tracked debt ledger.
+- `tools/skill_collision_guard.py`: Tier-2 Skill Routing & Collision Guard enforcing offline cosine similarity < 0.75 across skill descriptions.
+- `tools/synapse_qa_bench.py`: Gorilla BFCL-style benchmark measuring tool-use accuracy, argument validity, and irrelevance detection.
+
+## 🛑 Anti-Rationalization & Red Flag Guard (Addy Osmani Pattern)
+
+| Agent Rationalization / Shortcut Attempt | Architectural Rebuttal & Invariant Enforcement |
+|:---|:---|
+| *"Only 1 of 10 gates failed, so it's practically ready to ship."* | **STRICTLY FORBIDDEN:** All 10 Quality Gates must return PASS. 9/10 is a blocker, not a pass. |
+| *"The mutation score is 78%, which is within rounding distance of 80%."* | **STRICTLY FORBIDDEN:** Mutation Score >= 80% is a non-negotiable hard floor. Surviving mutants must be killed. |
+| *"Skill descriptions have 0.78 similarity, but they do different things."* | **STRICTLY FORBIDDEN:** Cosine similarity >= 0.75 causes LLM routing confusion. Refactor descriptions to differentiate triggers. |
+| *"We can bypass the verification command since the author tested it locally."* | **STRICTLY FORBIDDEN:** Verification-before-completion requires fresh command output run directly in the current session. |
 
 ## Persona Enhancements (Adapted from wshobson/agents, MIT)
 

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

@@ -11,6 +11,7 @@ skills:
   - backend-load-and-stress-patterns
 tools:
   - tools/safety_firewall.py
+  - tools/reversible_sandbox.py
   - tools/matrix_sharder.py
   - tools/flaky_detector.py
   - tools/distill_log.py
@@ -43,6 +44,16 @@ tools:
 - `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.
+- `tools/reversible_sandbox.py`: GoEx reversible teardown stack guaranteeing zero database pollution after test runs.
+
+## 🛑 Anti-Rationalization & Red Flag Guard (Addy Osmani Pattern)
+
+| Agent Rationalization / Shortcut Attempt | Architectural Rebuttal & Invariant Enforcement |
+|:---|:---|
+| *"The test failed on CI due to environment lag, so I'll just re-run until it passes."* | **STRICTLY FORBIDDEN:** Flaky retry laundering hides defects. Quarantine via `tools/flaky_detector.py` or fix timing via smart wait. |
+| *"I bypassed `safety_firewall.py` with `--force` because teardown takes too long."* | **STRICTLY FORBIDDEN:** Bypassing the firewall without approval risks destructive mutations on live/staging databases. |
+| *"The teardown step failed so I skipped it; the data shouldn't hurt."* | **STRICTLY FORBIDDEN:** Orphan data causes subsequent run collisions. Use `tools/reversible_sandbox.py` for guaranteed rollback. |
+| *"Dumping the entire 3000-line CLI log helps diagnose better."* | **STRICTLY FORBIDDEN:** Context bloat degrades agent reasoning. Always use `tools/distill_log.py` to mask raw observation logs. |
 
 ## Persona Enhancements (Adapted from wshobson/agents, MIT)
 

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

@@ -1,111 +1,31 @@
----
-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.
+> **Mandatory Rule:** Governs context windows, tool outputs, and attention budgets across all agent sessions.  
+> Detailed architecture guide: [context_engineering_guide.md](file://.agents/skills/token-and-context-optimizer/references/context_engineering_guide.md).
 
 ---
 
-## 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).
-
-
----
+## 1. Observation Masking & Log Truncation
+- Never dump thousands of lines of raw tool outputs (CLI, build logs, browser traces) into the chat.
+- Extract strictly: failing line number, exception name, test ID (`TC-xxx`), and status.
+- Mask verbose logs with pointer references: `[Full raw log saved to file://<path>; verbose lines omitted]`.
 
-## 6. Pillar 6: The Elephant-Goldfish Memory Protocol (Zero-Contamination Swarm)
+## 2. Progressive Disclosure & Micro-Reads
+- Never read large files (> 150 lines) into context at once.
+- Tier 1: Check `tools/repo_map.txt` for class signatures (~500 tokens).
+- Tier 2: Check dependency blast radius via `tools/test_impact.py`.
+- Tier 3: Micro-read targeted 20–50 lines using `StartLine` and `EndLine`.
 
-*(Synthesized from Google's Elephant-Goldfish Model by Dave Rensin)*
+## 3. KV-Cache Optimization & Static Prefix
+- Keep system instructions and rule headers static and immutable at the top.
+- Append new observations strictly at the bottom. Use identical status badges to maintain > 85% cache hit rates.
 
-1. **The Principle:**
-   - Single-agent long context inevitably breeds **Confirmation Bias** and **Context Contamination**: when the same context window designs an architecture, drafts a spec, and evaluates its own plan, it glosses over unstated assumptions and hallucinates completeness.
-   - True engineering rigor requires decoupling deep-context coordination (**The Elephant**) from stateless, adversarial verification (**The Goldfish**).
+## 4. Compaction Anchoring & Subagent Isolation
+- Persist active test registers, IDs, and state to `PROJECT_STATE.md` so automated context compaction never causes state loss.
+- Always isolate subagents (`Workspace: 'share'`); subagents must return only 3–5 line distilled summaries.
+- Partition test data with dynamic agent IDs (`uniqueCode = "AUTO_" + time + "_SUB" + id`).
 
-2. **Actionable Rules:**
-   - **The Elephant (Stateful Orchestrator):**
-     - Narrows problem boundaries, gathers user intent, and drafts architectural specs / Test Matrices (`docs/specs/*.md`).
-     - Maintains global long-term project context via `PROJECT_STATE.md`.
-     - **Strict Invariant:** The Elephant is prohibited from generating automation test scripts or asserting its own test design validity during the initial design phase.
-   - **The Goldfish (Stateless Subagent Swarm):**
-     - Spun up in a fresh, isolated subagent context (`Workspace: 'share'`) with **ZERO conversation history**.
-     - Evaluates solely the cold Markdown artifact and source code on disk using structured contracts (e.g., `tools/goldfish_review.py`).
-     - If the Goldfish cannot execute or understand the specification without guessing, the specification is rejected back to the Elephant.
-   - **Air-Gap Data Contract:**
-     - Data exchanged between stages must pass via deterministic files on disk (JSON Data Contracts, Test Matrices, JUnit XML), never via raw prompt inheritance.
+## 5. Semantic Signal Distillation
+- **Forbidden Raw HTML:** Never send raw HTML trees into context. Use `qa.getCompactAOM()` (< 500 tokens).
+- **Universal IR First:** Reason over clean Universal IR (`tools/universal_ir.py`) before generating Groovy/TS/Java boilerplate.
+- **Elephant-Goldfish Swarm:** Stateful Orchestrator writes specs to disk; stateless verification subagents audit cold files with zero context contagion.

package/.agents/rules/mobile_appium_rules.md

@@ -1,132 +1,36 @@
 # Mobile Automation Standards & Appium Rules (Enterprise Standard)
 
-> **Scope:** Applies to all Mobile Test Automation tasks using Appium, UIAutomator2 (Android), and XCUITest (iOS).  
+> **Scope:** Applies to Mobile Automation using Appium, UIAutomator2 (Android), and XCUITest (iOS).  
 > **Objective:** Deliver resilient, independent, flake-free mobile suites supporting parallel multi-device execution.
 
 ---
 
 ## 1. Native Locator Priority Hierarchy
-
-When interacting with Native or Hybrid mobile applications, agents **MUST** strictly adhere to the following locator priority order:
-
-```mermaid
-flowchart TD
-    L1["<b>1. Accessibility ID / Content-Desc</b><br/>• Cross-platform (iOS & Android)<br/>• Most stable, independent of layout"]
-    L2["<b>2. Resource-ID (Android Native)</b><br/>• Example: com.app.package:id/btn_login"]
-    L3["<b>3. iOS Predicate String / Class Chain (iOS Native)</b><br/>• Native XCUITest performance"]
-    L4["<b>4. Dynamic XPath (Last Resort)</b><br/>• Relative XPath with text/attributes only<br/>• Absolute structural XPath is FORBIDDEN"]
-
-    L1 --> L2 --> L3 --> L4
-```
-
-### Standard Implementation Examples:
-```java
-// 1. Accessibility ID (Top priority)
-driver.findElement(AppiumBy.accessibilityId("btn_login"));
-
-// 2. Resource-ID Android (Android Native priority)
-driver.findElement(AppiumBy.id("com.enterprise.app:id/input_username"));
-
-// 3. iOS Predicate String (iOS Native priority)
-driver.findElement(AppiumBy.iOSNsPredicateString("label == 'Sign In' AND visible == 1"));
-
-// 4. iOS Class Chain
-driver.findElement(AppiumBy.iOSClassChain("**/XCUIElementTypeButton[`label == 'Submit'`]"));
-```
+1. **Accessibility ID / Content-Desc** (Top priority, cross-platform): `driver.findElement(AppiumBy.accessibilityId("btn_login"))`
+2. **Resource-ID (Android Native):** `driver.findElement(AppiumBy.id("com.app:id/username"))`
+3. **iOS Predicate String (iOS Native):** `driver.findElement(AppiumBy.iOSNsPredicateString("label == 'Sign In' AND visible == 1"))`
+4. **iOS Class Chain:** `driver.findElement(AppiumBy.iOSClassChain("**/XCUIElementTypeButton[`label == 'Submit'`]"))`
+5. **Dynamic XPath (Last Resort):** Relative XPath with attributes only. Absolute structural XPath is **FORBIDDEN**.
 
 ---
 
 ## 2. Strict Anti-Patterns & Prohibitions
-
-- ❌ **FORBIDDEN: Absolute XPath based on DOM tree hierarchy:**
-  ```java
-  // STRICTLY FORBIDDEN:
-  driver.findElement(By.xpath("//android.widget.FrameLayout[1]/android.widget.LinearLayout[2]/android.widget.Button[1]"));
-  ```
-- ❌ **FORBIDDEN: Static sleeps (`Thread.sleep()`):** Introduces pipeline latency and flaky synchronization.
-- ❌ **FORBIDDEN: Interacting with off-screen elements without scrolling:** Always scroll into view first.
-- ❌ **FORBIDDEN: Hardcoded device identifiers:** UDID, Device Name, Platform Version must be dynamic via environment variables or profile configurations.
-
----
-
-## 3. Screen Object Model (SOM) Architecture
-
-Following the Page Object Model design pattern, mobile test code adheres to **Screen Object Model**:
-- Screen class names must end with the `Screen` suffix (e.g., `LoginScreen.java`, `HomeScreen.java`, `CartScreen.java`).
-- Extend `BaseScreen` providing shared AppiumDriver instances and gesture helpers.
-- Encapsulate locators within Screen classes; test scripts call business actions only.
-
-```java
-public class LoginScreen extends BaseScreen {
-    private final By btnLogin = AppiumBy.accessibilityId("btn_submit");
-    private final By txtEmail = AppiumBy.accessibilityId("input_email");
-
-    public LoginScreen(AppiumDriver driver) {
-        super(driver);
-    }
-
-    public HomeScreen loginWithValidCredentials(String email, String password) {
-        waitForElementVisible(txtEmail).sendKeys(email);
-        // ...
-        return new HomeScreen(driver);
-    }
-}
-```
+- ❌ **FORBIDDEN:** Absolute hierarchy XPath (e.g., `//android.widget.FrameLayout[1]/.../Button[1]`).
+- ❌ **FORBIDDEN:** Static delays (`Thread.sleep()`).
+- ❌ **FORBIDDEN:** Interacting with off-screen elements without scrolling into view first.
+- ❌ **FORBIDDEN:** Hardcoded device identifiers (UDID, device name must come from environment/profiles).
 
 ---
 
-## 4. Synchronization & Smart Mobile Waits
-
-- Always use `WebDriverWait` with explicit `Duration`:
-  ```java
-  WebDriverWait wait = new WebDriverWait(driver, Duration.ofSeconds(15));
-  wait.until(ExpectedConditions.visibilityOfElementLocated(AppiumBy.accessibilityId("welcome_banner")));
-  ```
-- Smart scroll into view:
-  ```java
-  // Android UIAutomator Scrollable
-  driver.findElement(AppiumBy.androidUIAutomator(
-      "new UiScrollable(new UiSelector().scrollable(true))" +
-      ".scrollIntoView(new UiSelector().text(\"Confirm\"))"
-  ));
-  ```
+## 3. Screen Object Model (SOM) & Synchronization
+- Screen classes end with `Screen` suffix (e.g., `LoginScreen.java`) extending `BaseScreen`.
+- Encapsulate locators in Screen classes; test scripts call business actions only.
+- **Smart Waits:** Always use `WebDriverWait` with explicit `Duration.ofSeconds(N)`.
+- **Smart Scroll:** Use `UiScrollable(...).scrollIntoView(...)` or native iOS scroll gestures.
 
 ---
 
-## 5. Mobile Lifecycle & Device Gestures
-
-1. **Auto-Grant Permissions:**
-   - Configure capabilities to auto-grant system permissions:
-     `capabilities.setCapability("autoGrantPermissions", true);` (Android) or `"permissions": "{\"com.app\": {\"camera\": \"yes\"}}"` (iOS).
-2. **Screen Orientation:**
-   - Verify layout adaptability in both Portrait and Landscape when supported by the application.
-3. **App Backgrounding:**
-   - Test application resilience across background/foreground transitions:
-     `driver.runAppInBackground(Duration.ofSeconds(5));`
-4. **Virtual Keyboard Handling:**
-   - Always dismiss virtual keyboards (`driver.hideKeyboard()`) after input to prevent occluding action buttons.
-
----
-
-## 6. Driver Architecture & Image-Based Matching
-
-> *Borrowed and adapted from the Appium driver/plugin architecture concepts (Apache-2.0, appium/appium).*
-
-1. **Driver isolation** — each platform driver (UIAutomator2, XCUITest)
-   encapsulates its own locator translation and gesture mapping; Screen Object
-   classes must never branch on driver type outside the driver layer. A
-   `*Screen` class speaks intent ("tap primary action"), the driver layer
-   speaks mechanics.
-2. **Capabilities belong in profiles, not scripts** — device/OS/app
-   capabilities live in versioned capability profiles; test classes receive a
-   ready session. Hardcoding `platformVersion`/`deviceName` inside scripts is a
-   prohibited anti-pattern (see Section 2).
-3. **Image-based matching is a last-resort locator** — for canvas/maps/WebView
-   hybrids where the accessibility tree is empty, an image-reference plugin
-   (template match against a committed reference screenshot with a similarity
-   threshold, e.g. ≥ 0.9) may resolve elements. It is slower and flakier than
-   `AccessibilityID`/`ResourceID` — use only after the locator hierarchy in
-   Section 1 is exhausted, and always commit the reference image next to the
-   Screen class.
-4. **Match the session teardown to the driver lifecycle** — quit sessions
-   explicitly; orphaned driver processes leak devices in the grid.
+## 4. Mobile Lifecycle & Driver Invariants
+- **Permissions:** Auto-grant system permissions via capabilities (`autoGrantPermissions: true`).
+- **Resilience:** Validate backgrounding (`driver.runAppInBackground(...)`) and hide virtual keyboard before actions.
+- **Driver Isolation:** Screen classes speak intent; platform drivers (UIAutomator2/XCUITest) encapsulate mechanics. Capabilities reside in profiles, never in scripts. Always explicitly quit sessions.

package/.agents/rules/performance_testing_rules.md

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