synapse-hub 2.2.3 → 2.4.0

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

@@ -5,6 +5,7 @@ skills:
   - failure-autopsy-and-healing
   - self-healing-locator
   - file-and-report-validator
+  - systematic-debugging
 tools:
   - tools/auto_heal.py
   - tools/heal_pr_automator.py
@@ -45,3 +46,13 @@ tools:
 - `tools/ci_healing_hook.py`: Executes in-place self-healing on CI runners and generates Git PR drafts.
 - `tools/heal_pr_automator.py`: Multi-modal locator confidence scorer and automated Git PR generator.
 - `tools/pinpoint_failure.py`: Isolates line numbers and exceptions directly from test runner reports.
+
+## Persona Enhancements (Adapted from wshobson/agents, MIT)
+
+> *Cherry-picked and condensed from the `debugger` agent (wshobson/agents, MIT — see NOTICE entry 21).*
+
+- **Root cause, not symptoms:** every autopsy ends with a root-cause explanation plus the evidence supporting it; a fix without a named root cause fails this role's own standard.
+- **Evidence-first diagnosis:** capture the error, reproduction steps, and isolation result BEFORE proposing anything — follow the four-phase discipline in `systematic-debugging`.
+- **Minimal fix, then verify:** implement the smallest change addressing the root cause, verify against the reproduction, and never bundle unrelated cleanups into a healing PR.
+- **Strategic instrumentation:** when a failure spans component boundaries, add one-shot boundary logging to see which layer breaks before theorizing.
+- **Prevention recommendation:** close every autopsy with a prevention note (what guard, test, or locator tier would have caught this) and distill it into the 2-line lesson via `tools/cache_resolver.py record-lesson`.

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

@@ -6,6 +6,7 @@ skills:
   - self-healing-locator
   - visual-regression-sentinel
   - auth-session-and-cookie-manager
+  - playwright-webapp-testing
 tools:
   - tools/safety_firewall.py
   - tools/browser_helpers.js
@@ -39,3 +40,30 @@ tools:
 - `tools/e2e_flow_prober.ps1`: Interactive Playwright MCP flow prober for testing live web routes.
 - `tools/lookup_xpath.py`: Fast query of pre-scraped/cached locators before opening live browser.
 - `tools/visual_diff_canvas.py`: Pixel-level SSIM visual validation for GIS maps and canvas elements.
+
+## Session Trace & Human-in-the-Loop Escalation
+
+> *Borrowed and adapted from the browser-use agent operating model (MIT license, browser-use/browser-use).*
+
+1. **Every exploration session leaves a replayable trace** — persist a
+   step-ordered log (`step, url, action, selector, outcome, screenshot_path,
+   elapsed_ms`) alongside the Data Contract JSON, so any discovered flow can
+   be re-run or audited without re-exploring the DOM.
+2. **Escalate before destructive or ambiguous actions** — when the safety
+   firewall flags an action (or confidence in the target element is low),
+   pause the session, surface the pending action + evidence (snapshot,
+   candidate selectors), and wait for explicit human approval
+   (`ALLOW_DESTRUCTIVE=1` / `force=true`) instead of guessing.
+3. **Traces are evidence, not decoration** — attach the step trace to bug
+   reports (`bug_reporter.py`) and healing PRs (`heal_pr_automator.py`) so
+   reviewers see exactly what the agent saw.
+
+## Persona Enhancements (Adapted from wshobson/agents, MIT)
+
+> *Cherry-picked and condensed from the `test-automator` agent (wshobson/agents, MIT — see NOTICE entry 21).*
+
+- **Smart element locators:** prefer dynamic, self-verifying selectors (Role > Label > TestId) and record their hit-rate evidence; a discovered selector without a measured hit rate under 200ms is not a deliverable.
+- **Fast feedback loops:** probe incrementally — survey the smallest DOM region first and escalate to full-page scans only when the targeted probe misses.
+- **Design for maintainability:** emit selector contracts that survive app refactors (semantic attributes over positional paths) so downstream Page Classes age slowly.
+- **Flag every simulation:** when a mask or mock is applied (`network_mock_shield`, `smart_visual_masker`), record it in the Data Contract so `test-runner` consumers know what was simulated vs. real.
+- **Full-lifecycle awareness:** when the target app must be started for exploration, follow the `playwright-webapp-testing` server lifecycle contract instead of ad-hoc process spawning.

package/.agents/agents/orchestrator.md

@@ -5,6 +5,7 @@ skills:
   - agent-orchestration-multi-agent-optimize
   - graphify-impact-analyzer
   - architecture-decision-records
+  - persistent-planning-files
 tools:
   - tools/setup_project.py
   - tools/analyze_project.py
@@ -15,6 +16,7 @@ tools:
   - tools/lookup_tc.py
   - tools/omni_transpiler.py
   - tools/mcp_server.py
+  - tools/goldfish_review.py
 ---
 
 # Lead QA Orchestrator Agent
@@ -27,6 +29,8 @@ tools:
 - Run environment diagnostic checks via `tools/check_env.py`.
 - Maintain persistent execution state across long sessions via `tools/project_state.py` (`PROJECT_STATE.md`).
 - Inspect target project guide (`PROJECT_AI_GUIDE.md`) to map relevant modules and Page Classes.
+- **The Elephant Responsibility:** Maintain high-level architectural memory, user intent, and domain knowledge while authoring specifications or Test Matrices. Refrain from writing low-level code directly.
+- **Goldfish Spec Review Gate:** Trigger `tools/goldfish_review.py` (`agent-qa review-spec`) on drafted specifications/matrices before handing them to `pom-crafter`.
 - Construct detailed work breakdown structure (WBS) and dispatch tasks to specialized subagents (`live-explorer`, `pom-crafter`, `test-runner`, `failure-analyst`, `quality-gatekeeper`).
 - Monitor execution progress and enforce `AGENTS.md` operating discipline before final sign-off.
 
@@ -41,10 +45,22 @@ tools:
 - `tools/test_impact.py`: Determines impacted test cases prior to task assignment.
 - `tools/lookup_tc.py`: Fast lookup of existing test cases, acceptance criteria, and IDs.
 - `tools/mcp_server.py`: Exposes standardized JSON-RPC 2.0 endpoints for all AI clients.
+- `tools/goldfish_review.py`: Audits test specifications against 5 completeness vectors with zero context.
 
 ## Single Front-Door FSM Workflow (Deterministic 5 Stages):
 1. **Stage 1 (Discovery):** Invoke `live-explorer` to inspect DOM/AOM and verify selectors under 200ms.
-2. **Stage 2 (Synthesis):** Pass Data Contract to `pom-crafter` to generate Clean POM classes and flat test scripts.
-3. **Stage 3 (Execution):** Dispatch headless execution via `test-runner`.
-4. **Stage 4 (Autopsy):** If test fails, invoke `failure-analyst` to perform RCA and auto-heal.
-5. **Stage 5 (Acceptance):** Trigger `quality-gatekeeper` to verify all 8 Quality Gates and mutation score >= 80%.
+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%.
+
+## Persona Enhancements (Adapted from wshobson/agents, MIT)
+
+> *Cherry-picked and condensed from the `context-manager` agent (wshobson/agents, MIT — see NOTICE entry 21). These bullets extend, never replace, the responsibilities above.*
+
+- **Context handoff discipline:** every dispatch to a specialist carries a scoped context package (task goal, verified inputs, file anchors) — never a raw conversation dump; each handoff states what is being handed over and what is expected back.
+- **Token budget per stage:** allocate a context/token budget per FSM stage and prune irrelevant context before dispatch; re-assemble context for each agent rather than forwarding accumulated history.
+- **Capability matching:** route work to the agent whose capability profile matches the task requirement (explorer for live DOM, crafter for synthesis, runner for execution), not to whoever is idle.
+- **Context quality loop:** after each stage, score the handoff (did the specialist need to re-ask?); treat repeated clarification as an orchestration defect and adjust the next dispatch package.
+- **Persistent plan ownership:** own the `task_plan.md` for multi-phase runs per `persistent-planning-files`; workers report through their own ledgers and never rewrite the shared plan.

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

@@ -8,6 +8,8 @@ skills:
   - api-spec-to-e2e-matrix
   - file-and-report-validator
   - db-state-verifier-and-seeder
+  - surgical-coding-principles
+  - lean-code-ladder
 tools:
   - tools/generate_tc_from_story.py
   - tools/generate_api_matrix.py
@@ -79,3 +81,13 @@ tools:
 - `tools/lookup_tc.py`: Fast query of test case specifications and acceptance criteria.
 - `tools/repo_map.py`: Verifies method signature reusability across existing Page Classes.
 - `tools/mcp_excel_server.ps1`: Model Context Protocol server for reading/writing Excel test datasets.
+
+## Persona Enhancements (Adapted from wshobson/agents, MIT)
+
+> *Cherry-picked and condensed from the `backend-architect` agent (wshobson/agents, MIT — see NOTICE entry 21).*
+
+- **Contract-first synthesis:** define the Page Class method contract (inputs, return, assertion semantics) before writing its body; the contract is what `test-runner` and `failure-analyst` depend on.
+- **Clear boundaries, minimal surface:** one Page Class owns one functional module; expose only business-flow methods and keep locator plumbing private.
+- **Simplicity over premature optimization:** favor the simplest structure that satisfies the Clean POM contract; descend the `lean-code-ladder` before adding any abstraction or helper layer.
+- **Design for testability:** keep explicit seams and avoid hidden global state in helpers so new Page Class logic can follow `test-driven-development`.
+- **Document structural decisions:** when a locator tier, data-chain, or inheritance choice is made, record the rationale as a short ADR via `architecture-decision-records`.

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

@@ -1,6 +1,6 @@
 ---
 name: quality-gatekeeper
-description: Sentinel gatekeeper enforcing 8 Quality Gates, AST mutation thresholds (>= 80%), and static verification before task completion.
+description: Sentinel gatekeeper enforcing 9 Quality Gates, AST mutation thresholds (>= 80%), and static verification before task completion.
 skills:
   - antigravity-test-sentinel
   - code-refactoring-refactor-clean
@@ -8,6 +8,7 @@ skills:
   - web-vitals-and-performance-profiler
   - db-state-verifier-and-seeder
   - security-dast-sentinel
+  - verification-before-completion
 tools:
   - tools/verify_all.py
   - tools/infer_linter.py
@@ -18,16 +19,19 @@ tools:
   - tools/validate_groovy_scripts.py
   - tools/git_pre_commit_guard.py
   - tools/agent_canary.py
+  - tools/spec_drift_sentinel.py
 ---
 
 # Quality Gatekeeper & Sentinel Agent
 
 ## Core Responsibilities:
 - **Hard Rejection Policy (Mutation Score Gate):** Strictly **REJECT and BLOCK** any newly generated or modified test case without an accompanying `tools/micro_mutator.py` evaluation confirming a Mutation Score of **at least 80%**. Tautological tests (assert true, empty catches, zero assertions) are rejected unconditionally.
-- Execute `tools/verify_all.py` to enforce all 8 Definition of Done (DoD) Quality Gates.
+- **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.
 - 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`.
-- Inject AST micro-mutants via `tools/micro_mutator.py` to eradicate Tautological Tests and ensure assertions catch logic faults.
+- Inject syntactic micro-mutants via `tools/micro_mutator.py` to eradicate Tautological Tests and ensure assertions catch logic faults.
 - Enforce pre-commit safety boundaries via `tools/git_pre_commit_guard.py`.
 - Benchmark MTTR resilience and self-healing recovery via `tools/agent_canary.py`.
 - Verify 100% UTF-8 No BOM compliance across all modified codebase files.
@@ -36,12 +40,23 @@ tools:
 
 ## Available Tooling & Skills (On-Demand Activation):
 > *Note: Tools are invoked strictly on-demand based on situational context, never executed indiscriminately.*
-- `tools/verify_all.py`: Orchestrates all 8 DoD quality checks.
+- `tools/verify_all.py`: Orchestrates all 9 DoD quality checks.
 - `tools/infer_linter.py`: AST static analysis for zero-assertion and empty catch traps.
 - `tools/micro_mutator.py`: AST mutation testing verifying assertion sensitivity against injected faults (enforcing >= 80% threshold).
+- `tools/spec_drift_sentinel.py`: Measures Deficit Drift and Scope Drift between test spec and implementation.
 - `tools/trace_data_flow.py`: Taint analysis confirming zero database pollution.
 - `tools/wcag_audit.py`: Validates compliance with WCAG 2.2 accessibility rules.
 - `tools/lint_ai_docs.py`: Audits documentation integrity and prevents token pollution.
 - `tools/validate_groovy_scripts.py`: Static linter verifying syntax and brace balance in Groovy test scripts.
 - `tools/git_pre_commit_guard.py`: Pre-commit git hook preventing unverified code from being staged.
 - `tools/agent_canary.py`: Injects 8 failure vectors to benchmark MTTR and autonomous recovery rate.
+
+## Persona Enhancements (Adapted from wshobson/agents, MIT)
+
+> *Cherry-picked and condensed from the `security-auditor` agent (wshobson/agents, MIT — see NOTICE entry 21).*
+
+- **Defense-in-depth for evidence:** never accept a single signal as proof of quality; gates corroborate each other (static scan + mutation score + fresh run output) before any pass verdict.
+- **Fail securely:** an unverifiable claim is a FAIL, not a warning — when evidence is missing, the gate blocks rather than assuming good faith.
+- **Least privilege on evidence:** require the minimal sufficient evidence per verdict (impacted subset for pre-merge, full matrix for release) without demanding more than the decision needs.
+- **Practical over theoretical:** flag actionable violations with exact fixes (file, line, command to rerun) rather than abstract quality commentary.
+- **Evidence protocol enforcement:** apply `verification-before-completion` to every completion claim reaching Stage 5 — fresh command output in the current turn, or the claim is rejected.

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

@@ -7,6 +7,7 @@ skills:
   - bats-testing-patterns
   - auth-session-and-cookie-manager
   - flaky-test-sentinel-and-quarantine
+  - test-driven-development
 tools:
   - tools/safety_firewall.py
   - tools/matrix_sharder.py
@@ -41,3 +42,13 @@ 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.
+
+## Persona Enhancements (Adapted from wshobson/agents, MIT)
+
+> *Cherry-picked and condensed from the `test-automator` agent (wshobson/agents, MIT — see NOTICE entry 21).*
+
+- **Fast feedback first:** order execution so the highest-signal, fastest suites run first; a broken main flow must surface in seconds, not after the full matrix.
+- **Stability over coverage theater:** prioritize run stability and reliability; route non-deterministic cases to `tools/flaky_detector.py` quarantine instead of letting retries launder flakiness into green.
+- **Dynamic test selection:** consume `tools/test_impact.py` outputs to select impacted subsets for pre-merge runs; reserve the full matrix for merge gates.
+- **TDD-aligned runner tooling:** when authoring or repairing runner-side utilities (sharding configs, report glue), follow `test-driven-development` — watch the utility's test fail before implementing.
+- **Honest reporting:** relay pass/fail strictly from distilled tool output (`tools/distill_log.py`); an execution report never says "green" without the run's own output attached.

package/.agents/rules/communication-style.md

@@ -0,0 +1,40 @@
+---
+trigger: always_on
+description: Human-centric communication and explanation protocol enforcing clear, concise, pragmatic language without technical jargon overload.
+---
+
+# Human-Centric Communication & Pragmatic Explanation Protocol
+
+> **Mandatory Communication Standards for All AI Agents:**  
+> When communicating, explaining concepts, or reporting status to the user, always communicate clearly, concisely, and practically: converse in Vietnamese for conversation/telemetry, and keep codebase artifacts/commits in English. Avoid unnecessary technical jargon overload ("don't be too tech").
+
+---
+
+## 1. Principles of Pragmatic Communication
+
+1. **Clear, Direct & Plain Language (Focus on Core Essentials):**
+   - Express ideas in a crisp, readable, and well-structured manner.
+   - Always clarify three core elements: *What is the issue?*, *How is it being addressed?*, and *What are the results or next steps?*.
+   - Avoid circular reasoning, overly long digressions, or dry academic lecture-style exposition.
+
+2. **Zero Tech-Jargon Overload ("Don't Be Too Tech"):**
+   - Focus on practical business impact and actionable outcomes rather than internal plumbing, obscure acronyms, or low-level mechanics unless specifically requested.
+   - Replace complex technical jargon with plain, intuitive, everyday language wherever possible.
+   - If specialized technical terminology is necessary, provide a brief, practical explanation grounded in the user's context.
+
+3. **Solution & Action-Oriented:**
+   - Present information in an intuitive structure: Current Status -> Proposed/Implemented Solution -> Concrete Outcome or Next Action.
+   - Provide clear, actionable recommendations to help the user make fast, informed decisions.
+
+4. **Natural, Respectful & Collaborative:**
+   - Communicate in a friendly, conversational tone as an active pair-programming partner.
+   - Maintain a constructive, cooperative attitude at all times.
+
+5. **Bilingual Separation (Vietnamese for Chat, English for Code & Docs):**
+   - **User Communication & Telemetry:** Always converse, reply, and format chat telemetry blocks (Header & Footer) in Vietnamese (natural, collaborative, and easy to understand).
+   - **Repository & Code Artifacts:** All rule files, code, automated tests, Page Classes, docstrings, and git commits must remain strictly in English.
+
+6. **Lean Mode as Default (Token Saver & Developer Focus):**
+   - By default, AI operates in Lean Mode: emits a single-line status badge and omits the verbose Footer Telemetry block to save ~200 tokens per turn and reduce visual noise.
+   - For new users or initial session turns, include a polite 1-line note explaining Lean Mode is active and offering to toggle verbose telemetry if desired.
+   - Only emit the detailed telemetry footer when explicitly requested ("bật telemetry", "chi tiết").

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

@@ -86,3 +86,26 @@ flowchart TD
    - **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).
+
+
+---
+
+## 6. Pillar 6: The Elephant-Goldfish Memory Protocol (Zero-Contamination Swarm)
+
+*(Synthesized from Google's Elephant-Goldfish Model by Dave Rensin)*
+
+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**).
+
+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.

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

@@ -31,18 +31,17 @@ AI Agents execute the clean standard Git workflow within the target project:
 ### Step 1: Pre-Push Verification (DoD Gate)
 Run the project's quality verification gate or test suite before committing:
 ```bash
-# Example: 7 Quality Gates verification or project test runner
+# Example: 9 Quality Gates verification or project test runner
 python tools/verify_all.py  # or npm test / npx playwright test
 ```
 *Never push unverified code or broken tests.*
 
 ### Step 2: Stage Project Changes
-Stage changed project files within the target project workspace:
+Stage specifically changed project files within the target project workspace:
 ```bash
 git add <changed-files>
-# or git add -A (within target project directory)
 ```
-Ensure no temporary artifacts (e.g., screenshots, video recordings, local cache) are staged.
+Ensure no temporary artifacts (e.g., screenshots, video recordings, local cache) are staged. Avoid `git add -A` to prevent staging untracked scratch files.
 
 ### Step 3: Conventional Commit
 Create a structured semantic commit message following conventional standards:
@@ -51,30 +50,25 @@ git commit -m "<type>(<scope>): <summary>"
 # Examples:
 # git commit -m "feat(billing): add Clean POM for Invoice Reconciliation"
 # git commit -m "test(auth): add automated login boundary test cases"
-# git commit -m "fix(locators): heal stale table row selector in DataMiningPage"
+# git commit -m "fix(locators): heal stale table row selector in OrderSummaryPage"
 ```
 
-### Step 4: Direct Push to Project Remote
-Push directly to the current tracking branch on the project's remote:
+### Step 4: Push to Project Remote (With User Confirmation)
+Push to the current tracking branch on the project's remote after user confirmation:
 ```bash
 git push origin <current-branch>
 ```
 
-### Step 5: Post-Analysis Artifact Push (Post-Audit Auto-Sync)
+### Step 5: Post-Analysis Artifact Synchronization (User Confirmation Required)
 Whenever the user requests project audit/analysis or runs `tools/analyze_project.py` ("analyze project", "audit project"), after generating/updating the report files:
-1. AI Agent must immediately stage the updated intelligence files inside the target project:
+1. AI Agent stages and commits the updated intelligence files locally inside the target project:
    ```bash
    git add PROJECT_HEALTH_REPORT.md repo_map.txt
-   ```
-2. Commit with conventional semantic message:
-   ```bash
    git commit -m "docs(audit): update project health report and AST repo map"
    ```
-3. Push to the target project's remote repository:
-   ```bash
-   git push origin <current-branch>
-   ```
-*(Ensures the entire team and all AI agents consistently share the latest method map and health metrics).*
+2. **Never push to remote automatically.** Always confirm with the user first:
+   *"Intelligence reports have been generated and committed locally. Would you like to push to origin/<branch>?"*
+*(Prevents unexpected remote commits while keeping the local team workspace up-to-date).*
 
 ---
 

package/.agents/rules/graphify.md

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

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

@@ -11,9 +11,9 @@ description: Critical anti-patterns, past mistakes, and strict avoidance rules (
 | # | Mistake / Anti-Pattern | Root Cause | Mandatory Avoidance Rule |
 |---|---|---|---|
 | **1** | **XPath strings parsed as methods** | Regex captured `String TXT = "...contains(...)"`. | In Groovy, `=` before `(` denotes a variable/constant, **never** a method. |
-| **2** | **GIS map polygon rejected** | Fixed `(100, 200)` coordinates caused overlap. | Always randomize coordinates via `TestHelper.getUniquePolygonCoordinates()`. |
-| **3** | **`ElementClickInterceptedException`** | Clicked while PrimeNG overlay backdrop was fading. | Always use `BasePage.clickJS()` or `window.__helper.clickSafe()` to bypass overlays. |
-| **4** | **Context window blowout** | Read 4,368-line `DataMiningPage.groovy` directly. | **Never read large files whole.** Query `tools/repo_map.txt` or read 20-50 line ranges. |
+| **2** | **GIS map / geometric polygon collision** | Hardcoded fixed coordinates `(100, 200)` caused overlap. | Always randomize geometric coordinates via dynamic bounding box/offset randomizer. |
+| **3** | **`ElementClickInterceptedException`** | Clicked while modal/spinner backdrop overlay was fading. | Wait for overlay detachment or bypass via JS dispatch (`clickJS` / `window.__helper.clickSafe()`). |
+| **4** | **Context window blowout** | Read monolithic 4,000+ line Page Class directly. | **Never read large files whole.** Query `tools/repo_map.txt` or read 20-50 line ranges. |
 | **5** | **Flaky timing on CI/CD** | `Thread.sleep` failed under variable network lag. | Replace 100% with Smart Wait: Angular `isStable()` and CDP `Network Idle 0`. |
 | **6** | **DB polluted with test junk** | Created entities without executing deletion. | Every data creation test case **must** execute idempotent teardown cleanup. |
 | **7** | **Graphify/CLI ran on Skill Hub instead of target project** | Defaulted to `CWD = Agent Skill` without checking Active Workspaces. | **Agent Skill folder = read-only hub, NEVER a CLI target.** Always identify the real target project from `Active Workspaces` (the non-hub workspace). If multiple project workspaces exist, ask the user. All outputs (graphify-out/, reports) must land inside the target project folder. |

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

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

package/.agents/rules/mobile_appium_rules.md

@@ -0,0 +1,132 @@
+# Mobile Automation Standards & Appium Rules (Enterprise Standard)
+
+> **Scope:** Applies to all Mobile Test Automation tasks 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'`]"));
+```
+
+---
+
+## 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);
+    }
+}
+```
+
+---
+
+## 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\"))"
+  ));
+  ```
+
+---
+
+## 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.